HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
plugin.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 PLUG_PLUGIN_H
25 #define PLUG_PLUGIN_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/base/plug/api.h"
29 
30 #include "pxr/base/js/types.h"
32 #include "pxr/base/tf/refPtr.h"
33 #include "pxr/base/tf/weakPtr.h"
34 
35 #include <hboost/noncopyable.hpp>
36 #include <atomic>
37 #include <string>
38 #include <utility>
39 #include <vector>
40 
42 
44 
45 class Plug_RegistrationMetadata;
46 class TfType;
47 
48 /// \class PlugPlugin
49 ///
50 /// Defines an interface to registered plugins.
51 ///
52 /// Plugins are registered using the interfaces in \c PlugRegistry.
53 ///
54 /// For each registered plugin, there is an instance of
55 /// \c PlugPlugin which can be used to load and unload
56 /// the plugin and to retrieve information about the
57 /// classes implemented by the plugin.
58 ///
59 class PlugPlugin : public TfRefBase, public TfWeakBase {
60 public:
61  PLUG_API virtual ~PlugPlugin();
62 
63  /// Loads the plugin.
64  /// This is a noop if the plugin is already loaded.
65  PLUG_API bool Load();
66 
67  /// Returns \c true if the plugin is currently loaded. Resource
68  /// plugins always report as loaded.
69  PLUG_API bool IsLoaded() const;
70 
71 #ifdef PXR_PYTHON_SUPPORT_ENABLED
72  /// Returns \c true if the plugin is a python module.
73  PLUG_API bool IsPythonModule() const;
74 #endif // PXR_PYTHON_SUPPORT_ENABLED
75 
76  /// Returns \c true if the plugin is resource-only.
77  PLUG_API bool IsResource() const;
78 
79  /// Returns the dictionary containing meta-data for the plugin.
81 
82  /// Returns the metadata sub-dictionary for a particular type.
84 
85  /// Returns the dictionary containing the dependencies for the plugin.
87 
88  /// Returns true if \p type is declared by this plugin.
89  /// If \p includeSubclasses is specified, also returns true if any
90  /// subclasses of \p type have been declared.
91  PLUG_API bool DeclaresType(const TfType& type, bool includeSubclasses = false) const;
92 
93  /// Returns the plugin's name.
94  std::string const &GetName() const {
95  return _name;
96  }
97 
98  /// Returns the plugin's filesystem path.
99  std::string const &GetPath() const {
100  return _path;
101  }
102 
103  /// Returns the plugin's resources filesystem path.
104  std::string const &GetResourcePath() const {
105  return _resourcePath;
106  }
107 
108  /// Build a plugin resource path by returning a given absolute path or
109  /// combining the plugin's resource path with a given relative path.
111 
112  /// Find a plugin resource by absolute or relative path optionally
113  /// verifying that file exists. If verification fails an empty path
114  /// is returned. Relative paths are relative to the plugin's resource
115  /// path.
116  PLUG_API std::string FindPluginResource(const std::string& path, bool verify = true) const;
117 
118 private:
119  enum _Type {
120  LibraryType,
121 #ifdef PXR_PYTHON_SUPPORT_ENABLED
122  PythonType,
123 #endif // PXR_PYTHON_SUPPORT_ENABLED
124  ResourceType
125  };
126 
127  // Private ctor, plugins are constructed only by PlugRegistry.
128  PLUG_LOCAL
129  PlugPlugin(const std::string & path,
130  const std::string & name,
131  const std::string & resourcePath,
132  const JsObject & plugInfo,
133  _Type type);
134 
135  PLUG_LOCAL
136  static PlugPluginPtr _GetPluginForType(const TfType & type);
137 
138  PLUG_LOCAL
139  static void _RegisterAllPlugins();
140  PLUG_LOCAL
141  static PlugPluginPtr _GetPluginWithName(const std::string& name);
142  PLUG_LOCAL
143  static PlugPluginPtrVector _GetAllPlugins();
144 
145  template <class PluginMap>
146  PLUG_LOCAL
147  static std::pair<PlugPluginPtr, bool>
148  _NewPlugin(const Plug_RegistrationMetadata &metadata,
149  _Type pluginType,
150  const std::string& pluginCreationPath,
151  PluginMap *allPluginsByNamePtr);
152 
153  PLUG_LOCAL
154  static std::pair<PlugPluginPtr, bool>
155  _NewDynamicLibraryPlugin(const Plug_RegistrationMetadata& metadata);
156 
157 #ifdef PXR_PYTHON_SUPPORT_ENABLED
158  PLUG_LOCAL
159  static std::pair<PlugPluginPtr, bool>
160  _NewPythonModulePlugin(const Plug_RegistrationMetadata& metadata);
161 #endif // PXR_PYTHON_SUPPORT_ENABLED
162 
163  PLUG_LOCAL
164  static std::pair<PlugPluginPtr, bool>
165  _NewResourcePlugin(const Plug_RegistrationMetadata& metadata);
166 
167  PLUG_LOCAL
168  bool _Load();
169 
170  PLUG_LOCAL
171  void _DeclareAliases( TfType t, const JsObject & metadata );
172  PLUG_LOCAL
173  void _DeclareTypes();
174  PLUG_LOCAL
175  void _DeclareType(const std::string &name, const JsObject &dict);
176  PLUG_LOCAL
177  static void _DefineType( TfType t );
178 
179  struct _SeenPlugins;
180  PLUG_LOCAL
181  bool _LoadWithDependents(_SeenPlugins * seenPlugins);
182 
183  PLUG_LOCAL
184  static void _UpdatePluginMaps( const TfType & baseType );
185 
186  PLUG_LOCAL
187  static constexpr char const *_GetPluginTypeDisplayName(_Type type);
188 
189 private:
190  std::string _name;
191  std::string _path;
192  std::string _resourcePath;
193  JsObject _dict;
194  void *_handle; // the handle returned by ArchLibraryOpen() is a void*
195  std::atomic<bool> _isLoaded;
196  _Type _type;
197 
198  friend class PlugRegistry;
199 };
200 
201 /// Find a plugin's resource by absolute or relative path optionally
202 /// verifying that file exists. If \c plugin is \c NULL or verification
203 /// fails an empty path is returned. Relative paths are relative to the
204 /// plugin's resource path.
205 PLUG_API
207 PlugFindPluginResource(const PlugPluginPtr& plugin,
208  const std::string& path, bool verify = true);
209 
211 
212 #endif // PLUG_PLUGIN_H
PLUG_API JsObject GetMetadataForType(const TfType &type)
Returns the metadata sub-dictionary for a particular type.
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_AND_REF_PTRS(PlugPlugin)
GLuint const GLchar * name
Definition: glew.h:1814
std::string const & GetPath() const
Returns the plugin's filesystem path.
Definition: plugin.h:99
std::string const & GetName() const
Returns the plugin's name.
Definition: plugin.h:94
#define PLUG_LOCAL
Definition: api.h:44
PLUG_API bool IsResource() const
Returns true if the plugin is resource-only.
virtual PLUG_API ~PlugPlugin()
std::map< std::string, JsValue > JsObject
Definition: types.h:37
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
PLUG_API JsObject GetDependencies()
Returns the dictionary containing the dependencies for the plugin.
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
PLUG_API std::string FindPluginResource(const std::string &path, bool verify=true) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
PLUG_API std::string PlugFindPluginResource(const PlugPluginPtr &plugin, const std::string &path, bool verify=true)
#define PLUG_API
Definition: api.h:40
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
Definition: type.h:70
PLUG_API JsObject GetMetadata()
Returns the dictionary containing meta-data for the plugin.
PLUG_API bool IsLoaded() const
PLUG_API bool Load()
PLUG_API std::string MakeResourcePath(const std::string &path) const
PLUG_API bool DeclaresType(const TfType &type, bool includeSubclasses=false) const
GLdouble GLdouble t
Definition: glew.h:1398
std::string const & GetResourcePath() const
Returns the plugin's resources filesystem path.
Definition: plugin.h:104