HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
node.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_NODE_H
26 #define PXR_USD_NDR_NODE_H
27 
28 /// \file ndr/node.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/ndr/api.h"
32 #include "pxr/base/tf/token.h"
33 #include "pxr/usd/ndr/declare.h"
35 #include "pxr/usd/ndr/property.h"
36 
38 
39 /// \class NdrNode
40 ///
41 /// Represents an abstract node. Describes information like the name of the
42 /// node, what its inputs and outputs are, and any associated metadata.
43 ///
44 /// In almost all cases, this class will not be used directly. More specialized
45 /// nodes can be created that derive from `NdrNode`; those specialized nodes can
46 /// add their own domain-specific data and methods.
47 ///
48 class NdrNode
49 {
50 public:
51  /// Constructor.
52  NDR_API
53  NdrNode(const NdrIdentifier& identifier,
54  const NdrVersion& version,
55  const std::string& name,
56  const TfToken& family,
57  const TfToken& context,
58  const TfToken& sourceType,
59  const std::string& definitionURI,
60  const std::string& implementationURI,
61  NdrPropertyUniquePtrVec&& properties,
62  const NdrTokenMap& metadata = NdrTokenMap(),
63  const std::string &sourceCode = std::string());
64 
65  /// Destructor.
66  NDR_API
67  virtual ~NdrNode();
68 
69  /// \name The Basics
70  /// @{
71 
72  /// Return the identifier of the node.
73  const NdrIdentifier& GetIdentifier() const { return _identifier; }
74 
75  /// Return the version of the node
76  NdrVersion GetVersion() const { return _version; }
77 
78  /// Gets the name of the node.
79  const std::string& GetName() const { return _name; }
80 
81  /// Gets the name of the family that the node belongs to. An empty token
82  /// will be returned if the node does not belong to a family.
83  const TfToken& GetFamily() const { return _family; }
84 
85  /// Gets the context of the node.
86  ///
87  /// The context is the context that the node declares itself as having (or,
88  /// if a particular node does not declare a context, it will be assigned a
89  /// default context by the parser).
90  ///
91  /// As a concrete example from the `Sdr` library, a shader with a specific
92  /// source type may perform different duties vs. another shader with the
93  /// same source type. For example, one shader with a source type of
94  /// `SdrArgsParser::SourceType` may declare itself as having a context of
95  /// 'pattern', while another shader of the same source type may say it is
96  /// used for lighting, and thus has a context of 'light'.
97  const TfToken& GetContext() const { return _context; }
98 
99  /// Gets the type of source that this node originated from.
100  ///
101  /// Note that this is distinct from `GetContext()`, which is the type that
102  /// the node declares itself as having.
103  ///
104  /// As a concrete example from the `Sdr` library, several shader parsers
105  /// exist and operate on different types of shaders. In this scenario, each
106  /// distinct type of shader (OSL, Args, etc) is considered a different
107  /// _source_, even though they are all shaders. In addition, the shaders
108  /// under each source type may declare themselves as having a specific
109  /// context (shaders can serve different roles). See `GetContext()` for
110  /// more information on this.
111  const TfToken& GetSourceType() const { return _sourceType; }
112 
113  /// Gets the URI to the resource that provided this node's
114  /// definition. Could be a path to a file, or some other resource
115  /// identifier. This URI should be fully resolved.
116  ///
117  /// \sa NdrNode::GetResolvedImplementationURI()
119 
120  /// Gets the URI to the resource that provides this node's
121  /// implementation. Could be a path to a file, or some other resource
122  /// identifier. This URI should be fully resolved.
123  ///
124  /// \sa NdrNode::GetResolvedDefinitionURI()
126 
127  /// Returns the source code for this node. This will be empty for most
128  /// nodes. It will be non-empty only for the nodes that are constructed
129  /// using \ref NdrRegistry::GetNodeFromSourceCode(), in which case, the
130  /// source code has not been parsed (or even compiled) yet.
131  ///
132  /// An unparsed node with non-empty source-code but no properties is
133  /// considered to be invalid. Once the node is parsed and the relevant
134  /// properties and metadata are extracted from the source code, the node
135  /// becomes valid.
136  ///
137  /// \sa NdrNode::IsValid
138  const std::string &GetSourceCode() const { return _sourceCode; }
139 
140  /// Whether or not this node is valid. A node that is valid indicates that
141  /// the parser plugin was able to successfully parse the contents of this
142  /// node.
143  ///
144  /// Note that if a node is not valid, some data like its name, URI, source
145  /// code etc. could still be available (data that was obtained during the
146  /// discovery process). However, other data that must be gathered from the
147  /// parsing process will NOT be available (eg, inputs and outputs).
148  NDR_API
149  virtual bool IsValid() const { return _isValid; }
150 
151  /// Gets a string with basic information about this node. Helpful for
152  /// things like adding this node to a log.
153  NDR_API
154  virtual std::string GetInfoString() const;
155 
156  /// @}
157 
158 
159  /// \name Inputs and Outputs
160  /// An input or output is also generically referred to as a "property".
161  /// @{
162 
163  /// Get an ordered list of all the input names on this node.
164  NDR_API
165  const NdrTokenVec& GetInputNames() const;
166 
167  /// Get an ordered list of all the output names on this node.
168  NDR_API
169  const NdrTokenVec& GetOutputNames() const;
170 
171  /// Get an input property by name. `nullptr` is returned if an input with
172  /// the given name does not exist.
173  NDR_API
174  NdrPropertyConstPtr GetInput(const TfToken& inputName) const;
175 
176  /// Get an output property by name. `nullptr` is returned if an output with
177  /// the given name does not exist.
178  NDR_API
179  NdrPropertyConstPtr GetOutput(const TfToken& outputName) const;
180 
181  /// @}
182 
183 
184  /// \name Metadata
185  /// The metadata returned here is a direct result of what the parser plugin
186  /// is able to determine about the node. See the documentation for a
187  /// specific parser plugin to get help on what the parser is looking for to
188  /// populate these values.
189  /// @{
190 
191  /// All metadata that came from the parse process. Specialized nodes may
192  /// isolate values in the metadata (with possible manipulations and/or
193  /// additional parsing) and expose those values in their API.
194  NDR_API
195  const NdrTokenMap& GetMetadata() const;
196 
197  /// @}
198 
199 protected:
200  NdrNode& operator=(const NdrNode&) = delete;
201 
202  bool _isValid;
214 
219 };
220 
222 
223 #endif // PXR_USD_NDR_NODE_H
NDR_API const NdrTokenVec & GetOutputNames() const
Get an ordered list of all the output names on this node.
const TfToken & GetSourceType() const
Definition: node.h:111
NdrPropertyPtrMap _outputs
Definition: node.h:217
std::vector< TfToken > NdrTokenVec
Definition: declare.h:59
const std::string & GetResolvedImplementationURI() const
Definition: node.h:125
NDR_API NdrPropertyConstPtr GetOutput(const TfToken &outputName) const
NDR_API const NdrTokenMap & GetMetadata() const
NdrPropertyPtrMap _inputs
Definition: node.h:215
const std::string & GetResolvedDefinitionURI() const
Definition: node.h:118
NdrNode & operator=(const NdrNode &)=delete
NdrTokenVec _inputNames
Definition: node.h:216
GLuint const GLchar * name
Definition: glcorearb.h:785
NDR_API NdrNode(const NdrIdentifier &identifier, const NdrVersion &version, const std::string &name, const TfToken &family, const TfToken &context, const TfToken &sourceType, const std::string &definitionURI, const std::string &implementationURI, NdrPropertyUniquePtrVec &&properties, const NdrTokenMap &metadata=NdrTokenMap(), const std::string &sourceCode=std::string())
Constructor.
std::string _name
Definition: node.h:205
const std::string & GetSourceCode() const
Definition: node.h:138
NdrTokenVec _outputNames
Definition: node.h:218
std::vector< NdrPropertyUniquePtr > NdrPropertyUniquePtrVec
Definition: declare.h:67
std::string _definitionURI
Definition: node.h:209
Definition: token.h:87
Definition: node.h:48
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
const TfToken & GetContext() const
Definition: node.h:97
TfToken _family
Definition: node.h:206
NdrTokenMap _metadata
Definition: node.h:212
NdrIdentifier _identifier
Definition: node.h:203
NdrPropertyUniquePtrVec _properties
Definition: node.h:211
virtual NDR_API bool IsValid() const
Definition: node.h:149
#define NDR_API
Definition: api.h:40
GT_API const UT_StringHolder version
const NdrIdentifier & GetIdentifier() const
Return the identifier of the node.
Definition: node.h:73
NDR_API NdrPropertyConstPtr GetInput(const TfToken &inputName) const
bool _isValid
Definition: node.h:202
TfToken _context
Definition: node.h:207
std::string _sourceCode
Definition: node.h:213
NdrVersion GetVersion() const
Return the version of the node.
Definition: node.h:76
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
const TfToken & GetFamily() const
Definition: node.h:83
const std::string & GetName() const
Gets the name of the node.
Definition: node.h:79
virtual NDR_API ~NdrNode()
Destructor.
std::string _implementationURI
Definition: node.h:210
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TfToken _sourceType
Definition: node.h:208
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
std::unordered_map< TfToken, NdrPropertyConstPtr, TfToken::HashFunctor > NdrPropertyPtrMap
Definition: declare.h:69
NdrVersion _version
Definition: node.h:204
NDR_API const NdrTokenVec & GetInputNames() const
Get an ordered list of all the input names on this node.
virtual NDR_API std::string GetInfoString() const
NdrProperty const * NdrPropertyConstPtr
Definition: declare.h:65