HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
parserPlugin.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_PARSER_PLUGIN_H
26 #define PXR_USD_NDR_PARSER_PLUGIN_H
27 
28 /// \file ndr/parserPlugin.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/ndr/api.h"
32 #include "pxr/base/tf/type.h"
33 #include "pxr/base/tf/weakBase.h"
34 #include "pxr/base/tf/weakPtr.h"
35 #include "pxr/usd/ndr/declare.h"
36 
38 
39 // Forward declarations
41 
42 /// Register a parser plugin with the plugin system.
43 #define NDR_REGISTER_PARSER_PLUGIN(ParserPluginClass) \
44 TF_REGISTRY_FUNCTION(TfType) \
45 { \
46  TfType::Define<ParserPluginClass, TfType::Bases<NdrParserPlugin>>() \
47  .SetFactory<NdrParserPluginFactory<ParserPluginClass>>(); \
48 }
49 
50 /// \class NdrParserPlugin
51 ///
52 /// Interface for parser plugins.
53 ///
54 /// Parser plugins take a `NdrNodeDiscoveryResult` from the discovery process
55 /// and creates a full `NdrNode` instance (or, in the case of a real-world
56 /// scenario, a specialized node that derives from `NdrNode`). The parser that
57 /// is selected to run is ultimately decided by the registry, and depends on the
58 /// `NdrNodeDiscoveryResult`'s `discoveryType` member. A parser plugin's
59 /// `GetDiscoveryTypes()` method is how this link is made. If a discovery result
60 /// has a `discoveryType` of 'foo', and `SomeParserPlugin` has 'foo' included
61 /// in its `GetDiscoveryTypes()` return value, `SomeParserPlugin` will parse
62 /// that discovery result.
63 ///
64 /// Another kind of 'type' within the parser plugin is the 'source type'. The
65 /// discovery type simply acts as a way to link a discovery result to a parser
66 /// plugin. On the other hand, a 'source type' acts as an umbrella type that
67 /// groups all of the discovery types together. For example, if a plugin handled
68 /// discovery types 'foo', 'bar', and 'baz' (which are all related because they
69 /// are all handled by the same parser), they may all be grouped under one
70 /// unifying source type. This type is available on the node via
71 /// `NdrNode::GetSourceType()`.
72 ///
73 /// \section create How to Create a Parser Plugin
74 /// There are three steps to creating a parser plugin:
75 /// <ul>
76 /// <li>
77 /// Implement the parser plugin interface. An example parser plugin is
78 /// available in the plugin folder under `sdrOsl`. The `Parse()` method
79 /// should return the specialized node that derives from `NdrNode` (and
80 /// this node should also be constructed with its specialized
81 /// properties). Examples of a specialized node and property class are
82 /// `SdrShaderNode` and `SdrShaderProperty`.
83 /// </li>
84 /// <li>
85 /// Register your new plugin with the registry. The registration macro
86 /// must be called in your plugin's implementation file:
87 /// \code{.cpp}
88 /// NDR_REGISTER_PARSER_PLUGIN(<YOUR_PARSER_PLUGIN_CLASS_NAME>)
89 /// \endcode
90 /// This macro is available in parserPlugin.h.
91 /// </li>
92 /// <li>
93 /// In the same folder as your plugin, create a `plugInfo.json` file.
94 /// This file must be formatted like so, substituting
95 /// `YOUR_LIBRARY_NAME`, `YOUR_CLASS_NAME`, and `YOUR_DISPLAY_NAME`:
96 /// \code{.json}
97 /// {
98 /// "Plugins": [{
99 /// "Type": "library",
100 /// "Name": "YOUR_LIBRARY_NAME",
101 /// "Root": "@PLUG_INFO_ROOT@",
102 /// "LibraryPath": "@PLUG_INFO_LIBRARY_PATH@",
103 /// "ResourcePath": "@PLUG_INFO_RESOURCE_PATH@",
104 /// "Info": {
105 /// "Types": {
106 /// "YOUR_CLASS_NAME" : {
107 /// "bases": ["NdrParserPlugin"],
108 /// "displayName": "YOUR_DISPLAY_NAME"
109 /// }
110 /// }
111 /// }
112 /// }]
113 /// }
114 /// \endcode
115 ///
116 /// The SDR ships with one parser plugin, the `SdrOslParserPlugin`. Take
117 /// a look at its plugInfo.json file for example values for
118 /// `YOUR_LIBRARY_NAME`, `YOUR_CLASS_NAME`, and `YOUR_DISPLAY_NAME`. If
119 /// multiple parser plugins exist in the same folder, you can continue
120 /// adding additional plugins under the `Types` key in the JSON. More
121 /// detailed information about the plugInfo.json format can be found in
122 /// the documentation for the `plug` library (in pxr/base).
123 /// </li>
124 /// </ul>
126 {
127 public:
128  NDR_API
129  NdrParserPlugin();
130  NDR_API
131  virtual ~NdrParserPlugin();
132 
133  /// Takes the specified `NdrNodeDiscoveryResult` instance, which was a
134  /// result of the discovery process, and generates a new `NdrNode`.
135  /// The node's name, source type, and family must match.
136  NDR_API
137  virtual NdrNodeUniquePtr Parse(
138  const NdrNodeDiscoveryResult& discoveryResult) = 0;
139 
140  /// Returns the types of nodes that this plugin can parse.
141  ///
142  /// "Type" here is the discovery type (in the case of files, this will
143  /// probably be the file extension, but in other systems will be data that
144  /// can be determined during discovery). This type should only be used to
145  /// match up a `NdrNodeDiscoveryResult` to its parser plugin; this value is
146  /// not exposed in the node's API.
147  NDR_API
148  virtual const NdrTokenVec& GetDiscoveryTypes() const = 0;
149 
150  /// Returns the source type that this parser operates on.
151  ///
152  /// A source type is the most general type for a node. The parser plugin is
153  /// responsible for parsing all discovery results that have the types
154  /// declared under `GetDiscoveryTypes()`, and those types are collectively
155  /// identified as one "source type".
156  NDR_API
157  virtual const TfToken& GetSourceType() const = 0;
158 
159  /// Gets an invalid node based on the discovery result provided. An invalid
160  /// node is a node that has no properties, but may have basic data found
161  /// during discovery.
162  NDR_API
164 };
165 
166 
167 /// \cond
168 /// Factory classes should be hidden from the documentation.
169 
170 class NdrParserPluginFactoryBase : public TfType::FactoryBase
171 {
172 public:
173  virtual NdrParserPlugin* New() const = 0;
174 };
175 
176 template <class T>
177 class NdrParserPluginFactory : public NdrParserPluginFactoryBase
178 {
179 public:
180  virtual NdrParserPlugin* New() const
181  {
182  return new T;
183  }
184 };
185 
186 /// \endcond
187 
189 
190 #endif // PXR_USD_NDR_PARSER_PLUGIN_H
NDR_API NdrParserPlugin()
std::vector< TfToken > NdrTokenVec
Definition: declare.h:59
virtual NDR_API ~NdrParserPlugin()
virtual NDR_API const NdrTokenVec & GetDiscoveryTypes() const =0
static NDR_API NdrNodeUniquePtr GetInvalidNode(const NdrNodeDiscoveryResult &dr)
Base class of all factory types.
Definition: type.h:73
Definition: token.h:87
virtual NDR_API const TfToken & GetSourceType() const =0
#define NDR_API
Definition: api.h:40
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
virtual NDR_API NdrNodeUniquePtr Parse(const NdrNodeDiscoveryResult &discoveryResult)=0
std::unique_ptr< NdrNode > NdrNodeUniquePtr
Definition: declare.h:74
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91