HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nodeDefAPI.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_NODEDEFAPI_H
25 #define USDSHADE_GENERATED_NODEDEFAPI_H
26 
27 /// \file usdShade/nodeDefAPI.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdShade/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
35 
36 #include "pxr/usd/ndr/declare.h"
37 #include "pxr/usd/sdr/shaderNode.h"
38 
39 
40 #include "pxr/base/vt/value.h"
41 
42 #include "pxr/base/gf/vec3d.h"
43 #include "pxr/base/gf/vec3f.h"
44 #include "pxr/base/gf/matrix4d.h"
45 
46 #include "pxr/base/tf/token.h"
47 #include "pxr/base/tf/type.h"
48 
50 
51 class SdfAssetPath;
52 
53 // -------------------------------------------------------------------------- //
54 // NODEDEFAPI //
55 // -------------------------------------------------------------------------- //
56 
57 /// \class UsdShadeNodeDefAPI
58 ///
59 /// UsdShadeNodeDefAPI is an API schema that provides attributes
60 /// for a prim to select a corresponding Shader Node Definition ("Sdr Node"),
61 /// as well as to look up a runtime entry for that shader node in the
62 /// form of an SdrShaderNode.
63 ///
64 /// UsdShadeNodeDefAPI is intended to be a pre-applied API schema for any
65 /// prim type that wants to refer to the SdrRegistry for further implementation
66 /// details about the behavior of that prim. The primary use in UsdShade
67 /// itself is as UsdShadeShader, which is a basis for material shading networks
68 /// (UsdShadeMaterial), but this is intended to be used in other domains
69 /// that also use the Sdr node mechanism.
70 ///
71 /// This schema provides properties that allow a prim to identify an external
72 /// node definition, either by a direct identifier key into the SdrRegistry
73 /// (info:id), an asset to be parsed by a suitable NdrParserPlugin
74 /// (info:sourceAsset), or an inline source code that must also be parsed
75 /// (info:sourceCode); as well as a selector attribute to determine which
76 /// specifier is active (info:implementationSource).
77 ///
78 ///
79 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
80 /// that are text/tokens, the actual token is published and defined in \ref UsdShadeTokens.
81 /// So to set an attribute to the value "rightHanded", use UsdShadeTokens->rightHanded
82 /// as the value.
83 ///
85 {
86 public:
87  /// Compile time constant representing what kind of schema this class is.
88  ///
89  /// \sa UsdSchemaKind
91 
92  /// Construct a UsdShadeNodeDefAPI on UsdPrim \p prim .
93  /// Equivalent to UsdShadeNodeDefAPI::Get(prim.GetStage(), prim.GetPath())
94  /// for a \em valid \p prim, but will not immediately throw an error for
95  /// an invalid \p prim
96  explicit UsdShadeNodeDefAPI(const UsdPrim& prim=UsdPrim())
97  : UsdAPISchemaBase(prim)
98  {
99  }
100 
101  /// Construct a UsdShadeNodeDefAPI on the prim held by \p schemaObj .
102  /// Should be preferred over UsdShadeNodeDefAPI(schemaObj.GetPrim()),
103  /// as it preserves SchemaBase state.
104  explicit UsdShadeNodeDefAPI(const UsdSchemaBase& schemaObj)
105  : UsdAPISchemaBase(schemaObj)
106  {
107  }
108 
109  /// Destructor.
111  virtual ~UsdShadeNodeDefAPI();
112 
113  /// Return a vector of names of all pre-declared attributes for this schema
114  /// class and all its ancestor classes. Does not include attributes that
115  /// may be authored by custom/extended methods of the schemas involved.
117  static const TfTokenVector &
118  GetSchemaAttributeNames(bool includeInherited=true);
119 
120  /// Return a UsdShadeNodeDefAPI holding the prim adhering to this
121  /// schema at \p path on \p stage. If no prim exists at \p path on
122  /// \p stage, or if the prim at that path does not adhere to this schema,
123  /// return an invalid schema object. This is shorthand for the following:
124  ///
125  /// \code
126  /// UsdShadeNodeDefAPI(stage->GetPrimAtPath(path));
127  /// \endcode
128  ///
130  static UsdShadeNodeDefAPI
131  Get(const UsdStagePtr &stage, const SdfPath &path);
132 
133 
134  /// Returns true if this <b>single-apply</b> API schema can be applied to
135  /// the given \p prim. If this schema can not be a applied to the prim,
136  /// this returns false and, if provided, populates \p whyNot with the
137  /// reason it can not be applied.
138  ///
139  /// Note that if CanApply returns false, that does not necessarily imply
140  /// that calling Apply will fail. Callers are expected to call CanApply
141  /// before calling Apply if they want to ensure that it is valid to
142  /// apply a schema.
143  ///
144  /// \sa UsdPrim::GetAppliedSchemas()
145  /// \sa UsdPrim::HasAPI()
146  /// \sa UsdPrim::CanApplyAPI()
147  /// \sa UsdPrim::ApplyAPI()
148  /// \sa UsdPrim::RemoveAPI()
149  ///
151  static bool
152  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
153 
154  /// Applies this <b>single-apply</b> API schema to the given \p prim.
155  /// This information is stored by adding "NodeDefAPI" to the
156  /// token-valued, listOp metadata \em apiSchemas on the prim.
157  ///
158  /// \return A valid UsdShadeNodeDefAPI object is returned upon success.
159  /// An invalid (or empty) UsdShadeNodeDefAPI object is returned upon
160  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
161  /// resulting in failure.
162  ///
163  /// \sa UsdPrim::GetAppliedSchemas()
164  /// \sa UsdPrim::HasAPI()
165  /// \sa UsdPrim::CanApplyAPI()
166  /// \sa UsdPrim::ApplyAPI()
167  /// \sa UsdPrim::RemoveAPI()
168  ///
170  static UsdShadeNodeDefAPI
171  Apply(const UsdPrim &prim);
172 
173 protected:
174  /// Returns the kind of schema this class belongs to.
175  ///
176  /// \sa UsdSchemaKind
178  UsdSchemaKind _GetSchemaKind() const override;
179 
180 private:
181  // needs to invoke _GetStaticTfType.
182  friend class UsdSchemaRegistry;
184  static const TfType &_GetStaticTfType();
185 
186  static bool _IsTypedSchema();
187 
188  // override SchemaBase virtuals.
190  const TfType &_GetTfType() const override;
191 
192 public:
193  // --------------------------------------------------------------------- //
194  // IMPLEMENTATIONSOURCE
195  // --------------------------------------------------------------------- //
196  /// Specifies the attribute that should be consulted to get the
197  /// shader's implementation or its source code.
198  ///
199  /// * If set to "id", the "info:id" attribute's value is used to
200  /// determine the shader source from the shader registry.
201  /// * If set to "sourceAsset", the resolved value of the "info:sourceAsset"
202  /// attribute corresponding to the desired implementation (or source-type)
203  /// is used to locate the shader source. A source asset file may also
204  /// specify multiple shader definitions, so there is an optional attribute
205  /// "info:sourceAsset:subIdentifier" whose value should be used to indicate
206  /// a particular shader definition from a source asset file.
207  /// * If set to "sourceCode", the value of "info:sourceCode" attribute
208  /// corresponding to the desired implementation (or source type) is used as
209  /// the shader source.
210  ///
211  ///
212  /// | ||
213  /// | -- | -- |
214  /// | Declaration | `uniform token info:implementationSource = "id"` |
215  /// | C++ Type | TfToken |
216  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
217  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
218  /// | \ref UsdShadeTokens "Allowed Values" | id, sourceAsset, sourceCode |
221 
222  /// See GetImplementationSourceAttr(), and also
223  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
224  /// If specified, author \p defaultValue as the attribute's default,
225  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
226  /// the default for \p writeSparsely is \c false.
228  UsdAttribute CreateImplementationSourceAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
229 
230 public:
231  // --------------------------------------------------------------------- //
232  // ID
233  // --------------------------------------------------------------------- //
234  /// The id is an identifier for the type or purpose of the
235  /// shader. E.g.: Texture or FractalFloat.
236  /// The use of this id will depend on the render context: some will turn it
237  /// into an actual shader path, some will use it to generate shader source
238  /// code dynamically.
239  ///
240  /// \sa SetShaderId()
241  ///
242  ///
243  /// | ||
244  /// | -- | -- |
245  /// | Declaration | `uniform token info:id` |
246  /// | C++ Type | TfToken |
247  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
248  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
250  UsdAttribute GetIdAttr() const;
251 
252  /// See GetIdAttr(), and also
253  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
254  /// If specified, author \p defaultValue as the attribute's default,
255  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
256  /// the default for \p writeSparsely is \c false.
258  UsdAttribute CreateIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
259 
260 public:
261  // ===================================================================== //
262  // Feel free to add custom code below this line, it will be preserved by
263  // the code generator.
264  //
265  // Just remember to:
266  // - Close the class declaration with };
267  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
268  // - Close the include guard with #endif
269  // ===================================================================== //
270  // --(BEGIN CUSTOM CODE)--
271 
272 
273  // -------------------------------------------------------------------------
274  /// \anchor UsdShadeNodeDefAPI_ImplementationSource
275  /// \name Shader Source API
276  ///
277  /// This section provides API for identifying the source of a shader's
278  /// implementation.
279  ///
280  /// @{
281 
282  /// Reads the value of info:implementationSource attribute and returns a
283  /// token identifying the attribute that must be consulted to identify the
284  /// shader's source program.
285  ///
286  /// This returns
287  /// * <b>id</b>, to indicate that the "info:id" attribute must be
288  /// consulted.
289  /// * <b>sourceAsset</b> to indicate that the asset-valued
290  /// "info:{sourceType}:sourceAsset" attribute associated with the desired
291  /// <b>sourceType</b> should be consulted to locate the asset with the
292  /// shader's source.
293  /// * <b>sourceCode</b> to indicate that the string-valued
294  /// "info:{sourceType}:sourceCode" attribute associated with the desired
295  /// <b>sourceType</b> should be read to get shader's source.
296  ///
297  /// This issues a warning and returns <b>id</b> if the
298  /// <i>info:implementationSource</i> attribute has an invalid value.
299  ///
300  /// <i>{sourceType}</i> above is a place holder for a token that identifies
301  /// the type of shader source or its implementation. For example: osl,
302  /// glslfx, riCpp etc. This allows a shader to specify different sourceAsset
303  /// (or sourceCode) values for different sourceTypes. The sourceType tokens
304  /// usually correspond to the sourceType value of the NdrParserPlugin that's
305  /// used to parse the shader source (\ref NdrParserPlugin::SourceType).
306  ///
307  /// When sourceType is empty, the corresponding sourceAsset or sourceCode is
308  /// considered to be "universal" (or fallback), which is represented by the
309  /// empty-valued token UsdShadeTokens->universalSourceType. When the
310  /// sourceAsset (or sourceCode) corresponding to a specific, requested
311  /// sourceType is unavailable, the universal sourceAsset (or sourceCode) is
312  /// returned by GetSourceAsset (and GetSourceCode} API, if present.
313  ///
314  /// \sa GetShaderId()
315  /// \sa GetSourceAsset()
316  /// \sa GetSourceCode()
319 
320  /// Sets the shader's ID value. This also sets the
321  /// <i>info:implementationSource</i> attribute on the shader to
322  /// <b>UsdShadeTokens->id</b>, if the existing value is different.
324  bool SetShaderId(const TfToken &id) const;
325 
326  /// Fetches the shader's ID value from the <i>info:id</i> attribute, if the
327  /// shader's <i>info:implementationSource</i> is <b>id</b>.
328  ///
329  /// Returns <b>true</b> if the shader's implementation source is <b>id</b>
330  /// and the value was fetched properly into \p id. Returns false otherwise.
331  ///
332  /// \sa GetImplementationSource()
334  bool GetShaderId(TfToken *id) const;
335 
336  /// Sets the shader's source-asset path value to \p sourceAsset for the
337  /// given source type, \p sourceType.
338  ///
339  /// This also sets the <i>info:implementationSource</i> attribute on the
340  /// shader to <b>UsdShadeTokens->sourceAsset</b>.
342  bool SetSourceAsset(
343  const SdfAssetPath &sourceAsset,
344  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
345 
346  /// Fetches the shader's source asset value for the specified
347  /// \p sourceType value from the <b>info:<i>sourceType:</i>sourceAsset</b>
348  /// attribute, if the shader's <i>info:implementationSource</i> is
349  /// <b>sourceAsset</b>.
350  ///
351  /// If the <i>sourceAsset</i> attribute corresponding to the requested
352  /// <i>sourceType</i> isn't present on the shader, then the <i>universal</i>
353  /// <i>fallback</i> sourceAsset attribute, i.e. <i>info:sourceAsset</i> is
354  /// consulted, if present, to get the source asset path.
355  ///
356  /// Returns <b>true</b> if the shader's implementation source is
357  /// <b>sourceAsset</b> and the source asset path value was fetched
358  /// successfully into \p sourceAsset. Returns false otherwise.
359  ///
360  /// \sa GetImplementationSource()
362  bool GetSourceAsset(
363  SdfAssetPath *sourceAsset,
364  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
365 
366  /// Set a sub-identifier to be used with a source asset of the given source
367  /// type. This sets the <b>info:<i>sourceType:</i>sourceAsset:subIdentifier
368  /// </b>.
369  ///
370  /// This also sets the <i>info:implementationSource</i> attribute on the
371  /// shader to <b>UsdShadeTokens->sourceAsset</b>
374  const TfToken &subIdentifier,
375  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
376 
377  /// Fetches the shader's sub-identifier for the source asset with the
378  /// specified \p sourceType value from the <b>info:<i>sourceType:</i>
379  /// sourceAsset:subIdentifier</b> attribute, if the shader's <i>info:
380  /// implementationSource</i> is <b>sourceAsset</b>.
381  ///
382  /// If the <i>subIdentifier</i> attribute corresponding to the requested
383  /// <i>sourceType</i> isn't present on the shader, then the <i>universal</i>
384  /// <i>fallback</i> sub-identifier attribute, i.e. <i>info:sourceAsset:
385  /// subIdentifier</i> is consulted, if present, to get the sub-identifier
386  /// name.
387  ///
388  /// Returns <b>true</b> if the shader's implementation source is
389  /// <b>sourceAsset</b> and the sub-identifier for the given source type was
390  /// fetched successfully into \p subIdentifier. Returns false otherwise.
393  TfToken *subIdentifier,
394  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
395 
396  /// Sets the shader's source-code value to \p sourceCode for the given
397  /// source type, \p sourceType.
398  ///
399  /// This also sets the <i>info:implementationSource</i> attribute on the
400  /// shader to <b>UsdShadeTokens->sourceCode</b>.
401  USDSHADE_API
402  bool SetSourceCode(
403  const std::string &sourceCode,
404  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
405 
406  /// Fetches the shader's source code for the specified \p sourceType value
407  /// by reading the <b>info:<i>sourceType:</i>sourceCode</b> attribute, if
408  /// the shader's <i>info:implementationSource</i> is <b>sourceCode</b>.
409  ///
410  /// If the <i>sourceCode</i> attribute corresponding to the
411  /// requested <i>sourceType</i> isn't present on the shader, then the
412  /// <i>universal</i> or <i>fallback</i> sourceCode attribute (i.e.
413  /// <i>info:sourceCode</i>) is consulted, if present, to get the source
414  /// code.
415  ///
416  /// Returns <b>true</b> if the shader's implementation source is
417  /// <b>sourceCode</b> and the source code string was fetched successfully
418  /// into \p sourceCode. Returns false otherwise.
419  ///
420  /// \sa GetImplementationSource()
422  bool GetSourceCode(
423  std::string *sourceCode,
424  const TfToken &sourceType=UsdShadeTokens->universalSourceType) const;
425 
426  /// @}
427  // -------------------------------------------------------------------------
428 
429  /// This method attempts to ensure that there is a ShaderNode in the shader
430  /// registry (i.e. \ref SdrRegistry) representing this shader for the
431  /// given \p sourceType. It may return a null pointer if none could be
432  /// found or created.
435  const;
436 
437 };
438 
440 
441 #endif
USDSHADE_API TfToken GetImplementationSource() const
#define USDSHADE_API
Definition: api.h:40
USDSHADE_API TfStaticData< UsdShadeTokensType > UsdShadeTokens
UsdShadeNodeDefAPI(const UsdPrim &prim=UsdPrim())
Definition: nodeDefAPI.h:96
Single Apply API schema.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDSHADE_API bool SetSourceAsset(const SdfAssetPath &sourceAsset, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
USDSHADE_API UsdAttribute CreateIdAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
SdrShaderNode const * SdrShaderNodeConstPtr
Definition: declare.h:44
virtual USDSHADE_API ~UsdShadeNodeDefAPI()
Destructor.
USDSHADE_API UsdAttribute GetIdAttr() const
USDSHADE_API bool GetSourceAssetSubIdentifier(TfToken *subIdentifier, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
USDSHADE_API bool SetSourceCode(const std::string &sourceCode, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
Definition: token.h:87
USDSHADE_API bool GetSourceAsset(SdfAssetPath *sourceAsset, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
static USDSHADE_API UsdShadeNodeDefAPI Apply(const UsdPrim &prim)
USDSHADE_API bool SetSourceAssetSubIdentifier(const TfToken &subIdentifier, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: prim.h:133
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:457
Definition: path.h:290
USDSHADE_API UsdAttribute GetImplementationSourceAttr() const
UsdSchemaKind
Definition: common.h:129
static const UsdSchemaKind schemaKind
Definition: nodeDefAPI.h:90
USDSHADE_API bool SetShaderId(const TfToken &id) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USDSHADE_API UsdSchemaKind _GetSchemaKind() const override
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDSHADE_API SdrShaderNodeConstPtr GetShaderNodeForSourceType(const TfToken &sourceType) const
Definition: type.h:64
USDSHADE_API bool GetShaderId(TfToken *id) const
USDSHADE_API bool GetSourceCode(std::string *sourceCode, const TfToken &sourceType=UsdShadeTokens->universalSourceType) const
USDSHADE_API UsdAttribute CreateImplementationSourceAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
UsdShadeNodeDefAPI(const UsdSchemaBase &schemaObj)
Definition: nodeDefAPI.h:104
static USDSHADE_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
Definition: value.h:164
static USDSHADE_API UsdShadeNodeDefAPI Get(const UsdStagePtr &stage, const SdfPath &path)