HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pluginRegistry.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 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 #ifndef PXR_IMAGING_HF_PLUGIN_REGISTRY_H
25 #define PXR_IMAGING_HF_PLUGIN_REGISTRY_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hf/api.h"
29 #include "pxr/imaging/hf/perfLog.h"
31 #include "pxr/base/plug/registry.h"
32 #include "pxr/base/tf/type.h"
33 
34 #include <map>
35 
37 
38 
39 class HfPluginBase;
40 class Hf_PluginEntry;
41 
42 
43 ///
44 /// \class HfPluginRegistry
45 ///
46 /// Base class for registering Hydra plugins using the plug mechanism.
47 /// It is expected that each plugin has a pluginfo.json file that contains
48 /// a list of types, where each type provides a list of base classes,
49 /// displayName and priority.
50 ///
51 /// The priority is used to order plugins, with the plugin with the highest
52 /// priority being at the front of the order. priority is a signed integer.
53 /// In the event of two plugins having the same priority, the plugins are sorted
54 /// alphabetically on the type name.
55 ///
56 /// The plugin sorted to the front is used as the default plugin, when not
57 /// specified.
58 ///
59 /// Example:
60 ///
61 ///{
62 /// "Types": {
63 /// "CPPTypeName": {
64 /// "bases": ["BaseTypeName"],
65 /// "displayName": "Human Readable Name",
66 /// "priority" : 0
67 /// }
68 /// }
69 ///}
70 ///
72 {
73 
74 public:
75  ///
76  /// Returns an ordered list of all registered plugins.
77  /// The plugins are ordered by priority then alphabetically
78  ///
79  HF_API
80  void GetPluginDescs(HfPluginDescVector *plugins);
81 
82  ///
83  /// Returns the description for the given plugin id.
84  /// The plugin may not be loaded or been actually created yet.
85  ///
86  HF_API
87  bool GetPluginDesc(const TfToken &pluginId, HfPluginDesc *desc);
88 
89  ///
90  /// Increment the reference count on an existing plugin.
91  ///
92  HF_API
93  void AddPluginReference(HfPluginBase *plugin);
94 
95  ///
96  /// Decrement the reference count on the plugin. If the
97  /// reference count get to 0, the plugin is freed.
98  ///
99  HF_API
100  void ReleasePlugin(HfPluginBase *plugin);
101 
102  ///
103  /// Returns true if a plugin has been registered for the given id.
104  /// The plugin may not be loaded or been actually created yet.
105  ///
106  HF_API
107  bool IsRegisteredPlugin(const TfToken &pluginId);
108 
109  HF_API
110  TfToken GetPluginId(const HfPluginBase *plugin) const;
111 
112 protected:
113  // Must be derived.
114 
115  ///
116  /// Constructs a Plugin Registry.
117  /// pluginBaseType is the TfType of the class derived from
118  /// HfPluginBase that provides the plugin API.
119  ///
120  HF_API
121  HfPluginRegistry(const TfType &pluginBaseType);
122  HF_API
123  virtual ~HfPluginRegistry();
124 
125  ///
126  /// Returns the plugin from the given pluginId.
127  /// The reference count on the plugin is automatically increased.
128  ///
129  HF_API
130  HfPluginBase *GetPlugin(const TfToken &pluginId);
131 
132  ///
133  /// Entry point for registering a types implementation.
134  /// T is the plugin being registered.
135  /// PluginBaseType is the HfPluginBase derived class
136  /// that specifies the API (the same one the TfType is for in
137  /// the constructor).
138  ///
139  /// Bases optionally specifies other classes that T is derived from.
140  ///
141  template<typename T, typename PluginBaseType, typename... Bases>
142  static void Define();
143 
144  /// Gives subclasses an opportunity to inspect plugInfo-based metadata
145  /// at the time of discovery.
146  HF_API
147  virtual void _CollectAdditionalMetadata(
148  const PlugRegistry &plugRegistry, const TfType &pluginType);
149 
150 private:
151  typedef std::vector<Hf_PluginEntry> _PluginEntryVector;
152  typedef std::map<TfToken, size_t> _TokenMap;
153 
154  //
155  // The purpose of this group of functions is to provide a factory
156  // to create the registered plugin with the type system
157  // without exposing the internal class _PluginEntry
158  ///
159  typedef std::function<HfPluginBase *()> _FactoryFn;
160 
161  template<typename T>
162  static HfPluginBase *_CreatePlugin();
163 
164  HF_API
165  static void _SetFactory(TfType &type, _FactoryFn &func);
166 
167  TfType _pluginBaseType;
168 
169  //
170  // Plugins are stored in a ordered list (as a vector). The token
171  // map converts from plugin id into an index in the list.
172  //
173  _PluginEntryVector _pluginEntries;
174  _TokenMap _pluginIndex;
175 
176  // Plugin discovery is deferred until first use.
177  bool _pluginCachePopulated;
178 
179  // Use the Plug system to discover plugins from the meta data.
180  void _DiscoverPlugins();
181 
182  // Find the plugin entry for the given plugin object.
183  Hf_PluginEntry *_GetEntryForPlugin(HfPluginBase *plugin);
184 
185  ///
186  /// This class is not intended to be copied.
187  ///
188  HfPluginRegistry() = delete;
189  HfPluginRegistry(const HfPluginRegistry &) = delete;
190  HfPluginRegistry &operator=(const HfPluginRegistry &) = delete;
191 };
192 
193 template<typename T>
194 HfPluginBase *
195 HfPluginRegistry::_CreatePlugin()
196 {
198  return new T;
199 }
200 
201 
202 template<typename T, typename PluginBaseType, typename... Bases>
203 void
205 {
207  TfType::Bases<PluginBaseType, Bases...> >();
208 
209  _FactoryFn func = &_CreatePlugin<T>;
210  _SetFactory(type, func);
211 }
212 
213 
214 
216 
217 #endif //PXR_IMAGING_HF_PLUGIN_REGISTRY_H
218 
#define HF_API
Definition: api.h:40
HF_API TfToken GetPluginId(const HfPluginBase *plugin) const
#define HF_MALLOC_TAG_FUNCTION()
Definition: perfLog.h:37
virtual HF_API void _CollectAdditionalMetadata(const PlugRegistry &plugRegistry, const TfType &pluginType)
HF_API void ReleasePlugin(HfPluginBase *plugin)
HF_API bool IsRegisteredPlugin(const TfToken &pluginId)
Definition: token.h:87
static TfType const & Define()
Definition: type_Impl.h:77
HF_API bool GetPluginDesc(const TfToken &pluginId, HfPluginDesc *desc)
HF_API void GetPluginDescs(HfPluginDescVector *plugins)
GLenum func
Definition: glcorearb.h:783
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
static void Define()
HF_API HfPluginBase * GetPlugin(const TfToken &pluginId)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
std::vector< HfPluginDesc > HfPluginDescVector
Definition: pluginDesc.h:53
type
Definition: core.h:1059
HF_API void AddPluginReference(HfPluginBase *plugin)
virtual HF_API ~HfPluginRegistry()