HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
shaderNode.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_SDR_SHADER_NODE_H
26 #define PXR_USD_SDR_SHADER_NODE_H
27 
28 /// \file sdr/shaderNode.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/sdr/api.h"
33 #include "pxr/usd/ndr/node.h"
34 #include "pxr/usd/sdr/declare.h"
35 
37 
38 // Note: Metadata keys that are generated by parsers should start with
39 // "__SDR__" to reduce the risk of collision with metadata actually in the
40 // shader.
41 #define SDR_NODE_METADATA_TOKENS \
42  ((Category, "category")) \
43  ((Role, "role")) \
44  ((Departments, "departments")) \
45  ((Help, "help")) \
46  ((Label, "label")) \
47  ((Pages, "pages")) \
48  ((Primvars, "primvars")) \
49  ((ImplementationName, "__SDR__implementationName"))\
50  ((Target, "__SDR__target")) \
51  ((SdrUsdEncodingVersion, "sdrUsdEncodingVersion")) \
52  ((SdrDefinitionNameFallbackPrefix, "sdrDefinitionNameFallbackPrefix"))
53 
54 // Note: The concept of context is defined on NdrNode and can be queried with
55 // the GetContext() method. Sdr categorizes shaders by the context in which they
56 // are used inside of a renderer. For instance during 'pattern' evaluation to
57 // feed into a surface or volume shader. For BXDFs used in 'surface' and
58 // 'volume' rendering situations.
59 #define SDR_NODE_CONTEXT_TOKENS \
60  ((Pattern, "pattern")) \
61  ((Surface, "surface")) \
62  ((Volume, "volume")) \
63  ((Displacement, "displacement")) \
64  ((Light, "light")) \
65  ((DisplayFilter, "displayFilter")) \
66  ((LightFilter, "lightFilter")) \
67  ((PixelFilter, "pixelFilter")) \
68  ((SampleFilter, "sampleFilter"))
69 
70 #define SDR_NODE_ROLE_TOKENS \
71  ((Primvar, "primvar")) \
72  ((Texture, "texture")) \
73  ((Field, "field")) \
74  ((Math, "math")) \
75 
79 
80 /// \class SdrShaderNode
81 ///
82 /// A specialized version of `NdrNode` which holds shading information.
83 ///
84 class SdrShaderNode : public NdrNode
85 {
86 public:
87  /// Constructor.
88  SDR_API
89  SdrShaderNode(const NdrIdentifier& identifier,
90  const NdrVersion& version,
91  const std::string& name,
92  const TfToken& family,
93  const TfToken& context,
94  const TfToken& sourceType,
95  const std::string& definitionURI,
96  const std::string& implementationURI,
97  NdrPropertyUniquePtrVec&& properties,
98  const NdrTokenMap& metadata = NdrTokenMap(),
99  const std::string &sourceCode = std::string());
100 
101  /// \name Inputs and Outputs
102  /// An input or output is also generically referred to as a "property".
103  /// @{
104 
105  /// Get a shader input property by name. `nullptr` is returned if an input
106  /// with the given name does not exist.
107  SDR_API
108  SdrShaderPropertyConstPtr GetShaderInput(const TfToken& inputName) const;
109 
110  /// Get a shader output property by name. `nullptr` is returned if an output
111  /// with the given name does not exist.
112  SDR_API
113  SdrShaderPropertyConstPtr GetShaderOutput(const TfToken& outputName) const;
114 
115  /// Returns the list of all inputs that are tagged as asset identifier
116  /// inputs.
117  SDR_API
119 
120  /// Returns the first shader input that is tagged as the default input.
121  /// A default input and its value can be used to acquire a fallback value
122  /// for a node when the node is considered 'disabled' or otherwise
123  /// incapable of producing an output value.
124  SDR_API
126 
127  /// @}
128 
129 
130  /// \name Metadata
131  /// The metadata returned here is a direct result of what the parser plugin
132  /// is able to determine about the node. See the documentation for a
133  /// specific parser plugin to get help on what the parser is looking for to
134  /// populate these values.
135  /// @{
136 
137  /// The label assigned to this node, if any. Distinct from the name
138  /// returned from `GetName()`. In the context of a UI, the label value
139  /// might be used as the display name for the node instead of the name.
140  SDR_API
141  const TfToken& GetLabel() const { return _label; }
142 
143  /// The category assigned to this node, if any. Distinct from the family
144  /// returned from `GetFamily()`.
145  SDR_API
146  const TfToken& GetCategory() const { return _category; }
147 
148  /// Returns the role of this node. This is used to annotate the role that
149  /// the shader node plays inside a shader network. We can tag certain
150  /// shaders to indicate their role within a shading network. We currently
151  /// tag primvar reading nodes, texture reading nodes and nodes that access
152  /// volume fields (like extinction or scattering). This is done to identify
153  /// resources used by a shading network.
154  SDR_API
155  std::string GetRole() const;
156 
157  /// The help message assigned to this node, if any.
158  SDR_API
159  std::string GetHelp() const;
160 
161  /// The departments this node is associated with, if any.
162  SDR_API
163  const NdrTokenVec& GetDepartments() const { return _departments; }
164 
165  /// Gets the pages on which the node's properties reside (an aggregate of
166  /// the unique `SdrShaderProperty::GetPage()` values for all of the node's
167  /// properties). Nodes themselves do not reside on pages. In an example
168  /// scenario, properties might be divided into two pages, 'Simple' and
169  /// 'Advanced'.
170  SDR_API
171  const NdrTokenVec& GetPages() const { return _pages; };
172 
173  /// The list of primvars this node knows it requires / uses.
174  /// For example, a shader node may require the 'normals' primvar to function
175  /// correctly. Additional, user specified primvars may have been authored on
176  /// the node. These can be queried via `GetAdditionalPrimvarProperties()`.
177  /// Together, `GetPrimvars()` and `GetAdditionalPrimvarProperties()`,
178  /// provide the complete list of primvar requirements for the node.
179  SDR_API
180  const NdrTokenVec& GetPrimvars() const { return _primvars; }
181 
182  /// The list of string input properties whose values provide the names of
183  /// additional primvars consumed by this node. For example, this may return
184  /// a token named `varname`. This indicates that the client should query the
185  /// value of a (presumed to be string-valued) input attribute named varname
186  /// from its scene description to determine the name of a primvar the
187  /// node will consume. See `GetPrimvars()` for additional information.
188  SDR_API
191  }
192 
193  /// Returns the implementation name of this node. The name of the node
194  /// is how to refer to the node in shader networks. The label is how to
195  /// present this node to users. The implementation name is the name of
196  /// the function (or something) this node represents in the
197  /// implementation. Any client using the implementation \b must call
198  /// this method to get the correct name; using \c getName() is not
199  /// correct.
200  SDR_API
202 
203  /// @}
204 
205 
206  /// \name Aggregate Information
207  /// @{
208 
209  /// Gets the names of the properties on a certain page (one that was
210  /// returned by `GetPages()`). To get properties that are not assigned to a
211  /// page, an empty string can be used for \p pageName.
212  SDR_API
213  NdrTokenVec GetPropertyNamesForPage(const std::string& pageName) const;
214 
215  /// Gets all vstructs that are present in the shader.
216  SDR_API
218 
219  /// @}
220 
221 
222  /// \cond
223  /// Hide from the API.
224 
225  // Performs a post-process on properties to determine information that can
226  // only be determined after parsing or in aggregate. Clients SHOULD NOT
227  // need to call this.
228  void _PostProcessProperties();
229 
230  /// \endcond
231 
232 protected:
233  // Processed primvar metadata. `_primvars` contains the names of primvars
234  // consumed by this node, whereas `_primvarNamingProperties` contains the
235  // names of string input properties whose values provide the names of
236  // additional primvars consumed by this node.
239 
240  // Tokenized metadata
245 
248 
249 private:
250  // Initializes `_primvars` and `_primvarNamingProperties`
251  void _InitializePrimvars();
252 
253  // Determines which pages are present on the node's properties
254  NdrTokenVec _ComputePages() const;
255 };
256 
258 
259 #endif // PXR_USD_SDR_SHADER_NODE_H
SdrPropertyMap _shaderInputs
Definition: shaderNode.h:246
SdrPropertyMap _shaderOutputs
Definition: shaderNode.h:247
NdrTokenVec _pages
Definition: shaderNode.h:244
SDR_API const TfToken & GetCategory() const
Definition: shaderNode.h:146
SDR_API const TfToken & GetLabel() const
Definition: shaderNode.h:141
std::vector< TfToken > NdrTokenVec
Definition: declare.h:59
NdrTokenVec _primvars
Definition: shaderNode.h:237
NdrTokenVec _primvarNamingProperties
Definition: shaderNode.h:238
std::unordered_map< TfToken, SdrShaderPropertyConstPtr, TfToken::HashFunctor > SdrPropertyMap
Definition: declare.h:53
TfToken _category
Definition: shaderNode.h:242
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
SDR_API const NdrTokenVec & GetDepartments() const
The departments this node is associated with, if any.
Definition: shaderNode.h:163
SDR_API SdrShaderPropertyConstPtr GetShaderInput(const TfToken &inputName) const
TfToken _label
Definition: shaderNode.h:241
std::vector< NdrPropertyUniquePtr > NdrPropertyUniquePtrVec
Definition: declare.h:67
SDR_API std::string GetHelp() const
The help message assigned to this node, if any.
SDR_API std::string GetImplementationName() const
Definition: token.h:87
SDR_API SdrShaderPropertyConstPtr GetDefaultInput() const
Definition: node.h:48
NdrTokenVec _departments
Definition: shaderNode.h:243
GLuint const GLchar * name
Definition: glcorearb.h:786
SdrShaderProperty const * SdrShaderPropertyConstPtr
Definition: declare.h:50
GT_API const UT_StringHolder version
SDR_API NdrTokenVec GetPropertyNamesForPage(const std::string &pageName) const
SDR_API NdrTokenVec GetAllVstructNames() const
Gets all vstructs that are present in the shader.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define SDR_NODE_ROLE_TOKENS
Definition: shaderNode.h:70
SDR_API const NdrTokenVec & GetPrimvars() const
Definition: shaderNode.h:180
SDR_API const NdrTokenVec & GetPages() const
Definition: shaderNode.h:171
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDR_API SdrShaderPropertyConstPtr GetShaderOutput(const TfToken &outputName) const
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
SDR_API const NdrTokenVec & GetAdditionalPrimvarProperties() const
Definition: shaderNode.h:189
#define SDR_NODE_CONTEXT_TOKENS
Definition: shaderNode.h:59
#define SDR_API
Definition: api.h:40
#define SDR_NODE_METADATA_TOKENS
Definition: shaderNode.h:41
SDR_API SdrShaderNode(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.
TF_DECLARE_PUBLIC_TOKENS(SdrNodeMetadata, SDR_API, SDR_NODE_METADATA_TOKENS)
SDR_API std::string GetRole() const
SDR_API NdrTokenVec GetAssetIdentifierInputNames() const