HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
discoveryPlugin.h
Go to the documentation of this file.
1 //
2 // Copyright 2018 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 
25 #ifndef PXR_USD_NDR_DISCOVERY_PLUGIN_H
26 #define PXR_USD_NDR_DISCOVERY_PLUGIN_H
27 
28 /// \file ndr/registry.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/ndr/api.h"
33 #include "pxr/base/tf/type.h"
34 #include "pxr/base/tf/weakBase.h"
35 #include "pxr/usd/ndr/declare.h"
37 
39 
40 /// Register a discovery plugin (`DiscoveryPluginClass`) with the plugin system.
41 /// If registered, the discovery plugin will execute its discovery process when
42 /// the registry is instantiated.
43 #define NDR_REGISTER_DISCOVERY_PLUGIN(DiscoveryPluginClass) \
44 TF_REGISTRY_FUNCTION(TfType) \
45 { \
46  TfType::Define<DiscoveryPluginClass, TfType::Bases<NdrDiscoveryPlugin>>() \
47  .SetFactory<NdrDiscoveryPluginFactory<DiscoveryPluginClass>>(); \
48 }
49 
51 
52 /// A context for discovery. Discovery plugins can use this to get
53 /// a limited set of non-local information without direct coupling
54 /// between plugins.
56 {
57 public:
58  NDR_API
59  virtual ~NdrDiscoveryPluginContext() = default;
60 
61  /// Returns the source type associated with the discovery type.
62  /// This may return an empty token if there is no such association.
63  NDR_API
64  virtual TfToken GetSourceType(const TfToken& discoveryType) const = 0;
65 };
66 
68 
69 /// \class NdrDiscoveryPlugin
70 ///
71 /// Interface for discovery plugins.
72 ///
73 /// Discovery plugins, like the name implies, find nodes. Where the plugin
74 /// searches is up to the plugin that implements this interface. Examples
75 /// of discovery plugins could include plugins that look for nodes on the
76 /// filesystem, another that finds nodes in a cloud service, and another that
77 /// searches a local database. Multiple discovery plugins that search the
78 /// filesystem in specific locations/ways could also be created. All discovery
79 /// plugins are executed as soon as the registry is instantiated.
80 ///
81 /// These plugins simply report back to the registry what nodes they found in
82 /// a generic way. The registry doesn't know much about the innards of the
83 /// nodes yet, just that the nodes exist. Understanding the nodes is the
84 /// responsibility of another set of plugins defined by the `NdrParserPlugin`
85 /// interface.
86 ///
87 /// Discovery plugins report back to the registry via `NdrNodeDiscoveryResult`s.
88 /// These are small, lightweight classes that contain the information for a
89 /// single node that was found during discovery. The discovery result only
90 /// includes node information that can be gleaned pre-parse, so the data is
91 /// fairly limited; to see exactly what's included, and what is expected to
92 /// be populated, see the documentation for `NdrNodeDiscoveryResult`.
93 ///
94 /// \section create How to Create a Discovery Plugin
95 /// There are three steps to creating a discovery plugin:
96 /// <ul>
97 /// <li>
98 /// Implement the discovery plugin interface, `NdrDiscoveryPlugin`
99 /// </li>
100 /// <li>
101 /// Register your new plugin with the registry. The registration macro
102 /// must be called in your plugin's implementation file:
103 /// \code{.cpp}
104 /// NDR_REGISTER_DISCOVERY_PLUGIN(YOUR_DISCOVERY_PLUGIN_CLASS_NAME)
105 /// \endcode
106 /// This macro is available in discoveryPlugin.h.
107 /// </li>
108 /// <li>
109 /// In the same folder as your plugin, create a `plugInfo.json` file.
110 /// This file must be formatted like so, substituting
111 /// `YOUR_LIBRARY_NAME`, `YOUR_CLASS_NAME`, and `YOUR_DISPLAY_NAME`:
112 /// \code{.json}
113 /// {
114 /// "Plugins": [{
115 /// "Type": "library",
116 /// "Name": "YOUR_LIBRARY_NAME",
117 /// "Root": "@PLUG_INFO_ROOT@",
118 /// "LibraryPath": "@PLUG_INFO_LIBRARY_PATH@",
119 /// "ResourcePath": "@PLUG_INFO_RESOURCE_PATH@",
120 /// "Info": {
121 /// "Types": {
122 /// "YOUR_CLASS_NAME" : {
123 /// "bases": ["NdrDiscoveryPlugin"],
124 /// "displayName": "YOUR_DISPLAY_NAME"
125 /// }
126 /// }
127 /// }
128 /// }]
129 /// }
130 /// \endcode
131 ///
132 /// The NDR ships with one discovery plugin, the
133 /// `_NdrFilesystemDiscoveryPlugin`. Take a look at NDR's plugInfo.json
134 /// file for example values for `YOUR_LIBRARY_NAME`, `YOUR_CLASS_NAME`,
135 /// and `YOUR_DISPLAY_NAME`. If multiple discovery plugins exist in the
136 /// same folder, you can continue adding additional plugins under the
137 /// `Types` key in the JSON. More detailed information about the
138 /// plugInfo.json format can be found in the documentation for the
139 /// `plug` library (in pxr/base).
140 /// </li>
141 /// </ul>
142 ///
144 {
145 public:
147 
148  NDR_API
150  NDR_API
151  virtual ~NdrDiscoveryPlugin();
152 
153  /// Finds and returns all nodes that the implementing plugin should be
154  /// aware of.
155  NDR_API
156  virtual NdrNodeDiscoveryResultVec DiscoverNodes(const Context&) = 0;
157 
158  /// Gets the URIs that this plugin is searching for nodes in.
159  NDR_API
160  virtual const NdrStringVec& GetSearchURIs() const = 0;
161 };
162 
163 
164 /// \cond
165 /// Factory classes should be hidden from the documentation.
166 
167 class NdrDiscoveryPluginFactoryBase : public TfType::FactoryBase
168 {
169 public:
170  NDR_API
171  virtual NdrDiscoveryPluginRefPtr New() const = 0;
172 };
173 
174 template <class T>
175 class NdrDiscoveryPluginFactory : public NdrDiscoveryPluginFactoryBase
176 {
177 public:
178  NdrDiscoveryPluginRefPtr New() const override
179  {
180  return TfCreateRefPtr(new T);
181  }
182 };
183 
184 /// \endcond
185 
187 
188 #endif // PXR_USD_NDR_DISCOVERY_PLUGIN_H
TfRefPtr< T > TfCreateRefPtr(T *ptr)
Definition: refPtr.h:1248
virtual NDR_API ~NdrDiscoveryPluginContext()=default
std::vector< NdrNodeDiscoveryResult > NdrNodeDiscoveryResultVec
NDR_API NdrDiscoveryPlugin()
Base class of all factory types.
Definition: type.h:73
Definition: token.h:87
virtual NDR_API NdrNodeDiscoveryResultVec DiscoverNodes(const Context &)=0
std::vector< std::string > NdrStringVec
Definition: declare.h:79
TF_DECLARE_WEAK_AND_REF_PTRS(NdrDiscoveryPluginContext)
virtual NDR_API const NdrStringVec & GetSearchURIs() const =0
Gets the URIs that this plugin is searching for nodes in.
#define NDR_API
Definition: api.h:40
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
virtual NDR_API ~NdrDiscoveryPlugin()
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
virtual NDR_API TfToken GetSourceType(const TfToken &discoveryType) const =0