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