HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
shader.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 USDSHADE_GENERATED_SHADER_H
25 #define USDSHADE_GENERATED_SHADER_H
26 
27 /// \file usdShade/shader.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdShade/api.h"
31 #include "pxr/usd/usd/typed.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 
35 #include "pxr/usd/usdShade/input.h"
38 #include "pxr/usd/ndr/declare.h"
39 #include "pxr/usd/sdr/shaderNode.h"
40 
41 #include "pxr/base/vt/value.h"
42 
43 #include "pxr/base/gf/vec3d.h"
44 #include "pxr/base/gf/vec3f.h"
45 #include "pxr/base/gf/matrix4d.h"
46 
47 #include "pxr/base/tf/token.h"
48 #include "pxr/base/tf/type.h"
49 
51 
52 class SdfAssetPath;
53 
54 // -------------------------------------------------------------------------- //
55 // SHADER //
56 // -------------------------------------------------------------------------- //
57 
58 /// \class UsdShadeShader
59 ///
60 /// Base class for all USD shaders. Shaders are the building blocks
61 /// of shading networks. While UsdShadeShader objects are not target specific,
62 /// each renderer or application target may derive its own renderer-specific
63 /// shader object types from this base, if needed.
64 ///
65 /// Objects of this class generally represent a single shading object, whether
66 /// it exists in the target renderer or not. For example, a texture, a fractal,
67 /// or a mix node.
68 ///
69 /// The UsdShadeNodeDefAPI provides attributes to uniquely identify the
70 /// type of this node. The id resolution into a renderable shader target
71 /// type of this node. The id resolution into a renderable shader target
72 /// is deferred to the consuming application.
73 ///
74 /// The purpose of representing them in Usd is two-fold:
75 /// \li To represent, via "connections" the topology of the shading network
76 /// that must be reconstructed in the renderer. Facilities for authoring and
77 /// manipulating connections are encapsulated in the API schema
78 /// UsdShadeConnectableAPI.
79 /// \li To present a (partial or full) interface of typed input parameters
80 /// whose values can be set and overridden in Usd, to be provided later at
81 /// render-time as parameter values to the actual render shader objects. Shader
82 /// input parameters are encapsulated in the property schema UsdShadeInput.
83 ///
84 ///
85 class UsdShadeShader : public UsdTyped
86 {
87 public:
88  /// Compile time constant representing what kind of schema this class is.
89  ///
90  /// \sa UsdSchemaKind
92 
93  /// Construct a UsdShadeShader on UsdPrim \p prim .
94  /// Equivalent to UsdShadeShader::Get(prim.GetStage(), prim.GetPath())
95  /// for a \em valid \p prim, but will not immediately throw an error for
96  /// an invalid \p prim
97  explicit UsdShadeShader(const UsdPrim& prim=UsdPrim())
98  : UsdTyped(prim)
99  {
100  }
101 
102  /// Construct a UsdShadeShader on the prim held by \p schemaObj .
103  /// Should be preferred over UsdShadeShader(schemaObj.GetPrim()),
104  /// as it preserves SchemaBase state.
105  explicit UsdShadeShader(const UsdSchemaBase& schemaObj)
106  : UsdTyped(schemaObj)
107  {
108  }
109 
110  /// Destructor.
112  virtual ~UsdShadeShader();
113 
114  /// Return a vector of names of all pre-declared attributes for this schema
115  /// class and all its ancestor classes. Does not include attributes that
116  /// may be authored by custom/extended methods of the schemas involved.
118  static const TfTokenVector &
119  GetSchemaAttributeNames(bool includeInherited=true);
120 
121  /// Return a UsdShadeShader holding the prim adhering to this
122  /// schema at \p path on \p stage. If no prim exists at \p path on
123  /// \p stage, or if the prim at that path does not adhere to this schema,
124  /// return an invalid schema object. This is shorthand for the following:
125  ///
126  /// \code
127  /// UsdShadeShader(stage->GetPrimAtPath(path));
128  /// \endcode
129  ///
131  static UsdShadeShader
132  Get(const UsdStagePtr &stage, const SdfPath &path);
133 
134  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
135  /// is defined (according to UsdPrim::IsDefined()) on this stage.
136  ///
137  /// If a prim adhering to this schema at \p path is already defined on this
138  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
139  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
140  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
141  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
142  /// current EditTarget for any nonexistent, or existing but not \a Defined
143  /// ancestors.
144  ///
145  /// The given \a path must be an absolute prim path that does not contain
146  /// any variant selections.
147  ///
148  /// If it is impossible to author any of the necessary PrimSpecs, (for
149  /// example, in case \a path cannot map to the current UsdEditTarget's
150  /// namespace) issue an error and return an invalid \a UsdPrim.
151  ///
152  /// Note that this method may return a defined prim whose typeName does not
153  /// specify this schema class, in case a stronger typeName opinion overrides
154  /// the opinion at the current EditTarget.
155  ///
157  static UsdShadeShader
158  Define(const UsdStagePtr &stage, const SdfPath &path);
159 
160 protected:
161  /// Returns the kind of schema this class belongs to.
162  ///
163  /// \sa UsdSchemaKind
165  UsdSchemaKind _GetSchemaKind() const override;
166 
167 private:
168  // needs to invoke _GetStaticTfType.
169  friend class UsdSchemaRegistry;
171  static const TfType &_GetStaticTfType();
172 
173  static bool _IsTypedSchema();
174 
175  // override SchemaBase virtuals.
177  const TfType &_GetTfType() const override;
178 
179 public:
180  // ===================================================================== //
181  // Feel free to add custom code below this line, it will be preserved by
182  // the code generator.
183  //
184  // Just remember to:
185  // - Close the class declaration with };
186  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
187  // - Close the include guard with #endif
188  // ===================================================================== //
189  // --(BEGIN CUSTOM CODE)--
190 
191  // -------------------------------------------------------------------------
192  /// \name Conversion to and from UsdShadeConnectableAPI
193  ///
194  /// @{
195 
196  /// Constructor that takes a ConnectableAPI object.
197  /// Allow implicit (auto) conversion of UsdShadeConnectableAPI to
198  /// UsdShadeShader, so that a ConnectableAPI can be passed into any function
199  /// that accepts a Shader.
200  ///
201  /// \note that the conversion may produce an invalid Shader object, because
202  /// not all UsdShadeConnectableAPI%s are Shader%s
204  UsdShadeShader(const UsdShadeConnectableAPI &connectable);
205 
206  /// Contructs and returns a UsdShadeConnectableAPI object with this shader.
207  ///
208  /// Note that most tasks can be accomplished without explicitly constructing
209  /// a UsdShadeConnectable API, since connection-related API such as
210  /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and
211  /// UsdShadeShader will auto-convert to a UsdShadeConnectableAPI when
212  /// passed to functions that want to act generically on a connectable
213  /// UsdShadeConnectableAPI object.
216 
217  /// @}
218 
219  // -------------------------------------------------------------------------
220  /// \name Outputs API
221  ///
222  /// Outputs represent a typed attribute on a shader or node-graph whose value
223  /// is computed externally.
224  ///
225  /// When they exist on a node-graph, they are connectable and are typically
226  /// connected to the output of a shader within the node-graph.
227  ///
228  /// @{
229 
230  /// Create an output which can either have a value or can be connected.
231  /// The attribute representing the output is created in the "outputs:"
232  /// namespace. Outputs on a shader cannot be connected, as their
233  /// value is assumed to be computed externally.
234  ///
237  const SdfValueTypeName& typeName);
238 
239  /// Return the requested output if it exists.
240  ///
242  UsdShadeOutput GetOutput(const TfToken &name) const;
243 
244  /// Outputs are represented by attributes in the "outputs:" namespace.
245  /// If \p onlyAuthored is true (the default), then only return authored
246  /// attributes; otherwise, this also returns un-authored builtins.
247  ///
249  std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored=true) const;
250 
251  /// @}
252 
253  // -------------------------------------------------------------------------
254 
255  /// \name Inputs API
256  ///
257  /// Inputs are connectable attribute with a typed value.
258  ///
259  /// On shaders, the shader parameters are encoded as inputs. On node-graphs,
260  /// interface attributes are represented as inputs.
261  ///
262  /// @{
263 
264  /// Create an input which can either have a value or can be connected.
265  /// The attribute representing the input is created in the "inputs:"
266  /// namespace. Inputs on both shaders and node-graphs are connectable.
267  ///
270  const SdfValueTypeName& typeName);
271 
272  /// Return the requested input if it exists.
273  ///
275  UsdShadeInput GetInput(const TfToken &name) const;
276 
277  /// Inputs are represented by attributes in the "inputs:" namespace.
278  /// If \p onlyAuthored is true (the default), then only return authored
279  /// attributes; otherwise, this also returns un-authored builtins.
280  ///
282  std::vector<UsdShadeInput> GetInputs(bool onlyAuthored=true) const;
283 
284  /// @}
285 
286  // -------------------------------------------------------------------------
287  /// \name UsdShadeNodeDefAPI forwarding
288  ///
289  /// @{
290 
291  /// Forwards to UsdShadeNodeDefAPI(prim).
294 
295  /// Forwards to UsdShadeNodeDefAPI(prim).
297  UsdAttribute CreateImplementationSourceAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
298 
299  /// Forwards to UsdShadeNodeDefAPI(prim).
301  UsdAttribute GetIdAttr() const;
302 
303  /// Forwards to UsdShadeNodeDefAPI(prim).
305  UsdAttribute CreateIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
306 
307  /// Forwards to UsdShadeNodeDefAPI(prim).
310 
311  /// Forwards to UsdShadeNodeDefAPI(prim).
313  bool SetShaderId(const TfToken &id) const;
314 
315  /// Forwards to UsdShadeNodeDefAPI(prim).
317  bool GetShaderId(TfToken *id) const;
318 
319  /// Forwards to UsdShadeNodeDefAPI(prim).
321  bool SetSourceAsset(
322  const SdfAssetPath &sourceAsset,
323  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
324 
325  /// Forwards to UsdShadeNodeDefAPI(prim).
327  bool GetSourceAsset(
328  SdfAssetPath *sourceAsset,
329  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
330 
331  /// Forwards to UsdShadeNodeDefAPI(prim).
334  const TfToken &subIdentifier,
335  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
336 
337  /// Forwards to UsdShadeNodeDefAPI(prim).
340  TfToken *subIdentifier,
341  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
342 
343  /// Forwards to UsdShadeNodeDefAPI(prim).
344  USDSHADE_API
345  bool SetSourceCode(
346  const std::string &sourceCode,
347  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
348 
349  /// Forwards to UsdShadeNodeDefAPI(prim).
351  bool GetSourceCode(
352  std::string *sourceCode,
353  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
354 
355  /// Forwards to UsdShadeNodeDefAPI(prim).
358  const;
359 
360  /// @}
361 
362  // -------------------------------------------------------------------------
363 
364  /// \anchor UsdShadeShader_SdrMetadata_API
365  /// \name Shader Sdr Metadata API
366  ///
367  /// This section provides API for authoring and querying shader registry
368  /// metadata. When the shader's implementationSource is <b>sourceAsset</b>
369  /// or <b>sourceCode</b>, the authored "sdrMetadata" dictionary value
370  /// provides additional metadata needed to process the shader source
371  /// correctly. It is used in combination with the sourceAsset or sourceCode
372  /// value to fetch the appropriate node from the shader registry.
373  ///
374  /// We expect the keys in sdrMetadata to correspond to the keys
375  /// in \ref SdrNodeMetadata. However, this is not strictly enforced in the
376  /// API. The only allowed value type in the "sdrMetadata" dictionary is a
377  /// std::string since it needs to be converted into a NdrTokenMap, which Sdr
378  /// will parse using the utilities available in \ref SdrMetadataHelpers.
379  ///
380  /// @{
381 
382  /// Returns this shader's composed "sdrMetadata" dictionary as a
383  /// NdrTokenMap.
385  NdrTokenMap GetSdrMetadata() const;
386 
387  /// Returns the value corresponding to \p key in the composed
388  /// <b>sdrMetadata</b> dictionary.
390  std::string GetSdrMetadataByKey(const TfToken &key) const;
391 
392  /// Authors the given \p sdrMetadata on this shader at the current
393  /// EditTarget.
395  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
396 
397  /// Sets the value corresponding to \p key to the given string \p value, in
398  /// the shader's "sdrMetadata" dictionary at the current EditTarget.
400  void SetSdrMetadataByKey(
401  const TfToken &key,
402  const std::string &value) const;
403 
404  /// Returns true if the shader has a non-empty composed "sdrMetadata"
405  /// dictionary value.
407  bool HasSdrMetadata() const;
408 
409  /// Returns true if there is a value corresponding to the given \p key in
410  /// the composed "sdrMetadata" dictionary.
412  bool HasSdrMetadataByKey(const TfToken &key) const;
413 
414  /// Clears any "sdrMetadata" value authored on the shader in the current
415  /// EditTarget.
417  void ClearSdrMetadata() const;
418 
419  /// Clears the entry corresponding to the given \p key in the
420  /// "sdrMetadata" dictionary authored in the current EditTarget.
422  void ClearSdrMetadataByKey(const TfToken &key) const;
423 
424  /// @}
425 };
426 
428 
429 #endif
#define USDSHADE_API
Definition: api.h:40
static USDSHADE_API UsdShadeShader Get(const UsdStagePtr &stage, const SdfPath &path)
USDSHADE_API SdrShaderNodeConstPtr GetShaderNodeForSourceType(const TfToken &sourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API TfStaticData< UsdShadeTokensType > UsdShadeTokens
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
static USDSHADE_API UsdShadeShader Define(const UsdStagePtr &stage, const SdfPath &path)
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
GLuint const GLchar * name
Definition: glcorearb.h:786
USDSHADE_API TfToken GetImplementationSource() const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
SdrShaderNode const * SdrShaderNodeConstPtr
Definition: declare.h:44
virtual USDSHADE_API ~UsdShadeShader()
Destructor.
USDSHADE_API NdrTokenMap GetSdrMetadata() const
USDSHADE_API UsdShadeOutput GetOutput(const TfToken &name) const
USDSHADE_API void ClearSdrMetadata() const
UsdSchemaKind
Definition: common.h:127
USDSHADE_API bool SetShaderId(const TfToken &id) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API bool GetSourceAsset(SdfAssetPath *sourceAsset, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API UsdShadeOutput CreateOutput(const TfToken &name, const SdfValueTypeName &typeName)
Definition: token.h:87
static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
USDSHADE_API UsdAttribute GetIdAttr() const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API bool GetShaderId(TfToken *id) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API bool SetSourceAsset(const SdfAssetPath &sourceAsset, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDSHADE_API UsdAttribute GetImplementationSourceAttr() const
Forwards to UsdShadeNodeDefAPI(prim).
Represents a concrete typed schema.
USDSHADE_API UsdAttribute CreateImplementationSourceAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Forwards to UsdShadeNodeDefAPI(prim).
Definition: prim.h:132
Definition: typed.h:47
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
Definition: path.h:290
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
USDSHADE_API bool GetSourceAssetSubIdentifier(TfToken *subIdentifier, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API UsdSchemaKind _GetSchemaKind() const override
USDSHADE_API bool GetSourceCode(std::string *sourceCode, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
USDSHADE_API UsdAttribute CreateIdAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Forwards to UsdShadeNodeDefAPI(prim).
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
USDSHADE_API void SetSdrMetadataByKey(const TfToken &key, const std::string &value) const
USDSHADE_API bool SetSourceCode(const std::string &sourceCode, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
UsdShadeShader(const UsdSchemaBase &schemaObj)
Definition: shader.h:105
USDSHADE_API std::vector< UsdShadeInput > GetInputs(bool onlyAuthored=true) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
USDSHADE_API UsdShadeInput CreateInput(const TfToken &name, const SdfValueTypeName &typeName)
Definition: core.h:1131
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
USDSHADE_API std::vector< UsdShadeOutput > GetOutputs(bool onlyAuthored=true) const
UsdShadeShader(const UsdPrim &prim=UsdPrim())
Definition: shader.h:97
USDSHADE_API bool SetSourceAssetSubIdentifier(const TfToken &subIdentifier, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Forwards to UsdShadeNodeDefAPI(prim).
static const UsdSchemaKind schemaKind
Definition: shader.h:91
USDSHADE_API bool HasSdrMetadata() const
USDSHADE_API UsdShadeConnectableAPI ConnectableAPI() const
Definition: value.h:166
USDSHADE_API UsdShadeInput GetInput(const TfToken &name) const