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