HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
material.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_MATERIAL_H
25 #define USDSHADE_GENERATED_MATERIAL_H
26 
27 /// \file usdShade/material.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 
37 #include "pxr/usd/usdGeom/subset.h"
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 // MATERIAL //
55 // -------------------------------------------------------------------------- //
56 
57 /// \class UsdShadeMaterial
58 ///
59 /// A Material provides a container into which multiple "render targets"
60 /// can add data that defines a "shading material" for a renderer. Typically
61 /// this consists of one or more UsdRelationship properties that target
62 /// other prims of type \em Shader - though a target/client is free to add
63 /// any data that is suitable. We <b>strongly advise</b> that all targets
64 /// adopt the convention that all properties be prefixed with a namespace
65 /// that identifies the target, e.g. "rel ri:surface = </Shaders/mySurf>".
66 ///
67 /// ## Binding Materials
68 ///
69 /// In the UsdShading model, geometry expresses a binding to a single Material or
70 /// to a set of Materials partitioned by UsdGeomSubsets defined beneath the
71 /// geometry; it is legal to bind a Material at the root (or other sub-prim) of
72 /// a model, and then bind a different Material to individual gprims, but the
73 /// meaning of inheritance and "ancestral overriding" of Material bindings is
74 /// left to each render-target to determine. Since UsdGeom has no concept of
75 /// shading, we provide the API for binding and unbinding geometry on the API
76 /// schema UsdShadeMaterialBindingAPI.
77 ///
78 /// ## Material Variation
79 ///
80 /// The entire power of USD VariantSets and all the other composition
81 /// operators can leveraged when encoding shading variation.
82 /// UsdShadeMaterial provides facilities for a particular way of building
83 /// "Material variants" in which neither the identity of the Materials themselves
84 /// nor the geometry Material-bindings need to change - instead we vary the
85 /// targeted networks, interface values, and even parameter values within
86 /// a single variantSet.
87 /// See \ref UsdShadeMaterial_Variations "Authoring Material Variations"
88 /// for more details.
89 ///
90 /// ## Materials Encapsulate their Networks in Namespace
91 ///
92 /// UsdShade requires that all of the shaders that "belong" to the Material
93 /// live under the Material in namespace. This supports powerful, easy reuse
94 /// of Materials, because it allows us to *reference* a Material from one
95 /// asset (the asset might be a library of Materials) into another asset: USD
96 /// references compose all descendant prims of the reference target into the
97 /// referencer's namespace, which means that all of the referenced Material's
98 /// shader networks will come along with the Material. When referenced in this
99 /// way, Materials can also be [instanced](http://openusd.org/docs/USD-Glossary.html#USDGlossary-Instancing), for ease of deduplication and compactness.
100 /// Finally, Material encapsulation also allows us to
101 /// \ref UsdShadeMaterial_BaseMaterial "specialize" child materials from
102 /// parent materials.
103 ///
104 ///
105 ///
106 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
107 /// that are text/tokens, the actual token is published and defined in \ref UsdShadeTokens.
108 /// So to set an attribute to the value "rightHanded", use UsdShadeTokens->rightHanded
109 /// as the value.
110 ///
112 {
113 public:
114  /// Compile time constant representing what kind of schema this class is.
115  ///
116  /// \sa UsdSchemaKind
118 
119  /// Construct a UsdShadeMaterial on UsdPrim \p prim .
120  /// Equivalent to UsdShadeMaterial::Get(prim.GetStage(), prim.GetPath())
121  /// for a \em valid \p prim, but will not immediately throw an error for
122  /// an invalid \p prim
123  explicit UsdShadeMaterial(const UsdPrim& prim=UsdPrim())
124  : UsdShadeNodeGraph(prim)
125  {
126  }
127 
128  /// Construct a UsdShadeMaterial on the prim held by \p schemaObj .
129  /// Should be preferred over UsdShadeMaterial(schemaObj.GetPrim()),
130  /// as it preserves SchemaBase state.
131  explicit UsdShadeMaterial(const UsdSchemaBase& schemaObj)
132  : UsdShadeNodeGraph(schemaObj)
133  {
134  }
135 
136  /// Destructor.
138  virtual ~UsdShadeMaterial();
139 
140  /// Return a vector of names of all pre-declared attributes for this schema
141  /// class and all its ancestor classes. Does not include attributes that
142  /// may be authored by custom/extended methods of the schemas involved.
144  static const TfTokenVector &
145  GetSchemaAttributeNames(bool includeInherited=true);
146 
147  /// Return a UsdShadeMaterial holding the prim adhering to this
148  /// schema at \p path on \p stage. If no prim exists at \p path on
149  /// \p stage, or if the prim at that path does not adhere to this schema,
150  /// return an invalid schema object. This is shorthand for the following:
151  ///
152  /// \code
153  /// UsdShadeMaterial(stage->GetPrimAtPath(path));
154  /// \endcode
155  ///
157  static UsdShadeMaterial
158  Get(const UsdStagePtr &stage, const SdfPath &path);
159 
160  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
161  /// is defined (according to UsdPrim::IsDefined()) on this stage.
162  ///
163  /// If a prim adhering to this schema at \p path is already defined on this
164  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
165  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
166  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
167  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
168  /// current EditTarget for any nonexistent, or existing but not \a Defined
169  /// ancestors.
170  ///
171  /// The given \a path must be an absolute prim path that does not contain
172  /// any variant selections.
173  ///
174  /// If it is impossible to author any of the necessary PrimSpecs, (for
175  /// example, in case \a path cannot map to the current UsdEditTarget's
176  /// namespace) issue an error and return an invalid \a UsdPrim.
177  ///
178  /// Note that this method may return a defined prim whose typeName does not
179  /// specify this schema class, in case a stronger typeName opinion overrides
180  /// the opinion at the current EditTarget.
181  ///
183  static UsdShadeMaterial
184  Define(const UsdStagePtr &stage, const SdfPath &path);
185 
186 protected:
187  /// Returns the kind of schema this class belongs to.
188  ///
189  /// \sa UsdSchemaKind
191  UsdSchemaKind _GetSchemaKind() const override;
192 
193 private:
194  // needs to invoke _GetStaticTfType.
195  friend class UsdSchemaRegistry;
197  static const TfType &_GetStaticTfType();
198 
199  static bool _IsTypedSchema();
200 
201  // override SchemaBase virtuals.
203  const TfType &_GetTfType() const override;
204 
205 public:
206  // --------------------------------------------------------------------- //
207  // SURFACE
208  // --------------------------------------------------------------------- //
209  /// Represents the universal "surface" output terminal of a
210  /// material.
211  ///
212  /// | ||
213  /// | -- | -- |
214  /// | Declaration | `token outputs:surface` |
215  /// | C++ Type | TfToken |
216  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
219 
220  /// See GetSurfaceAttr(), and also
221  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
222  /// If specified, author \p defaultValue as the attribute's default,
223  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
224  /// the default for \p writeSparsely is \c false.
226  UsdAttribute CreateSurfaceAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
227 
228 public:
229  // --------------------------------------------------------------------- //
230  // DISPLACEMENT
231  // --------------------------------------------------------------------- //
232  /// Represents the universal "displacement" output terminal of a
233  /// material.
234  ///
235  /// | ||
236  /// | -- | -- |
237  /// | Declaration | `token outputs:displacement` |
238  /// | C++ Type | TfToken |
239  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
242 
243  /// See GetDisplacementAttr(), and also
244  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
245  /// If specified, author \p defaultValue as the attribute's default,
246  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
247  /// the default for \p writeSparsely is \c false.
249  UsdAttribute CreateDisplacementAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
250 
251 public:
252  // --------------------------------------------------------------------- //
253  // VOLUME
254  // --------------------------------------------------------------------- //
255  /// Represents the universal "volume" output terminal of a
256  /// material.
257  ///
258  /// | ||
259  /// | -- | -- |
260  /// | Declaration | `token outputs:volume` |
261  /// | C++ Type | TfToken |
262  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
264  UsdAttribute GetVolumeAttr() const;
265 
266  /// See GetVolumeAttr(), and also
267  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
268  /// If specified, author \p defaultValue as the attribute's default,
269  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
270  /// the default for \p writeSparsely is \c false.
272  UsdAttribute CreateVolumeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
273 
274 public:
275  // ===================================================================== //
276  // Feel free to add custom code below this line, it will be preserved by
277  // the code generator.
278  //
279  // Just remember to:
280  // - Close the class declaration with };
281  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
282  // - Close the include guard with #endif
283  // ===================================================================== //
284  // --(BEGIN CUSTOM CODE)--
285 
286  // --------------------------------------------------------------------- //
287  /// \name Helpful Types
288  /// @{
289  // --------------------------------------------------------------------- //
290 
291  /// A function type that takes a path and returns a bool.
292  typedef std::function<bool (const SdfPath &)> PathPredicate;
293 
294  /// @}
295 
296 
297  // --------------------------------------------------------------------- //
298  /// \anchor UsdShadeMaterial_Outputs
299  /// \name Standard Material Terminal Outputs
300  /// A UsdShadeMaterial can have any number of "terminal" outputs. These
301  /// outputs are generally used to point to outputs of shader prims or
302  /// NodeGraphs that describe certain properties of the material that a
303  /// renderer might wish to consume. There are three standard output
304  /// terminals that are supported by the core API: <b>surface</b>,
305  /// <b>displacement</b> and <b>volume</b>.
306  ///
307  /// Each terminal output can further be qualified by a token-valued
308  /// <b>renderContext</b>. When a non-empty renderContext value is specified
309  /// to the API, the output is considered to have a specific or restricted
310  /// renderContext. If the renderContext value is empty (i.e. equal to
311  /// UsdShadeTokens->universalRenderContext), then the output is considered
312  /// to be a "universal", meaning it could apply to any render contexts.
313  /// Render context token values is typically driven by the rendering backend
314  /// consuming the terminal output (eg, RI or glslfx).
315  /// @{
316 
317  /// Creates and returns the "surface" output on this material for the
318  /// specified \p renderContext.
319  ///
320  /// If the output already exists on the material, it is returned and no
321  /// authoring is performed. The returned output will always have the
322  /// requested renderContext.
323  USDSHADE_API
324  UsdShadeOutput CreateSurfaceOutput(const TfToken &renderContext
325  =UsdShadeTokens->universalRenderContext) const;
326 
327  /// Returns the "surface" output of this material for the specified
328  /// \p renderContext. The returned output will always have the requested
329  /// renderContext.
330  ///
331  /// An invalid output is returned if an output corresponding to the
332  /// requested specific-renderContext does not exist.
333  ///
334  /// \sa UsdShadeMaterial::ComputeSurfaceSource()
336  UsdShadeOutput GetSurfaceOutput(const TfToken &renderContext
337  =UsdShadeTokens->universalRenderContext) const;
338 
339  /// Returns the "surface" outputs of this material for all available
340  /// renderContexts.
341  ///
342  /// The returned vector will include all authored "surface" outputs with
343  /// the <i>universal</i> renderContext output first, if present. Outputs
344  /// are returned regardless of whether they are connected to a valid
345  /// source.
347  std::vector<UsdShadeOutput> GetSurfaceOutputs() const;
348 
349  /// \deprecated Use the form that takes a TfTokenVector or renderContexts.
352  const TfToken &renderContext,
353  TfToken *sourceName=nullptr,
354  UsdShadeAttributeType *sourceType=nullptr) const;
355 
356  /// Computes the resolved "surface" output source for the given
357  /// \p contextVector. Using the earliest renderContext in the contextVector
358  /// that produces a valid Shader object.
359  ///
360  /// If a "surface" output corresponding to each of the renderContexts
361  /// does not exist <b>or</b> is not connected to a valid source, then this
362  /// checks the <i>universal</i> surface output.
363  ///
364  /// Returns an empty Shader object if there is no valid <i>surface</i>
365  /// output source for any of the renderContexts in the \p contextVector.
366  /// The python version of this method returns a tuple containing three
367  /// elements (the source surface shader, sourceName, sourceType).
370  const TfTokenVector &contextVector={UsdShadeTokens->universalRenderContext},
371  TfToken *sourceName=nullptr,
372  UsdShadeAttributeType *sourceType=nullptr) const;
373 
374  /// Creates and returns the "displacement" output on this material for the
375  /// specified \p renderContext.
376  ///
377  /// If the output already exists on the material, it is returned and no
378  /// authoring is performed. The returned output will always have the
379  /// requested renderContext.
380  USDSHADE_API
381  UsdShadeOutput CreateDisplacementOutput(const TfToken &renderContext
382  =UsdShadeTokens->universalRenderContext) const;
383 
384  /// Returns the "displacement" output of this material for the specified
385  /// renderContext. The returned output will always have the requested
386  /// renderContext.
387  ///
388  /// An invalid output is returned if an output corresponding to the
389  /// requested specific-renderContext does not exist.
390  ///
391  /// \sa UsdShadeMaterial::ComputeDisplacementSource()
392  USDSHADE_API
393  UsdShadeOutput GetDisplacementOutput(const TfToken &renderContext
394  =UsdShadeTokens->universalRenderContext) const;
395 
396  /// Returns the "displacement" outputs of this material for all available
397  /// renderContexts.
398  ///
399  /// The returned vector will include all authored "displacement" outputs
400  /// with the <i>universal</i> renderContext output first, if present.
401  /// Outputs are returned regardless of whether they are connected to a
402  /// valid source.
404  std::vector<UsdShadeOutput> GetDisplacementOutputs() const;
405 
406  /// \deprecated Use the form that takes a TfTokenVector or renderContexts
409  const TfToken &renderContext,
410  TfToken *sourceName=nullptr,
411  UsdShadeAttributeType *sourceType=nullptr) const;
412 
413  /// Computes the resolved "displacement" output source for the given
414  /// \p contextVector. Using the earliest renderContext in the contextVector
415  /// that produces a valid Shader object.
416  ///
417  /// If a "displacement" output corresponding to each of the renderContexts
418  /// does not exist <b>or</b> is not connected to a valid source, then this
419  /// checks the <i>universal</i> displacement output.
420  ///
421  /// Returns an empty Shader object if there is no valid <i>displacement</i>
422  /// output source for any of the renderContexts in the \p contextVector.
423  /// The python version of this method returns a tuple containing three
424  /// elements (the source displacement shader, sourceName, sourceType).
427  const TfTokenVector &contextVector={UsdShadeTokens->universalRenderContext},
428  TfToken *sourceName=nullptr,
429  UsdShadeAttributeType *sourceType=nullptr) const;
430 
431  /// Creates and returns the "volume" output on this material for the
432  /// specified \p renderContext.
433  ///
434  /// If the output already exists on the material, it is returned and no
435  /// authoring is performed. The returned output will always have the
436  /// requested renderContext.
437  USDSHADE_API
438  UsdShadeOutput CreateVolumeOutput(const TfToken &renderContext
439  =UsdShadeTokens->universalRenderContext) const;
440 
441  /// Returns the "volume" output of this material for the specified
442  /// renderContext. The returned output will always have the requested
443  /// renderContext.
444  ///
445  /// An invalid output is returned if an output corresponding to the
446  /// requested specific-renderContext does not exist.
447  ///
448  /// \sa UsdShadeMaterial::ComputeVolumeSource()
449  USDSHADE_API
450  UsdShadeOutput GetVolumeOutput(const TfToken &renderContext
451  =UsdShadeTokens->universalRenderContext) const;
452 
453  /// Returns the "volume" outputs of this material for all available
454  /// renderContexts.
455  ///
456  /// The returned vector will include all authored "volume" outputs with the
457  /// <i>universal</i> renderContext output first, if present. Outputs are
458  /// returned regardless of whether they are connected to a valid source.
460  std::vector<UsdShadeOutput> GetVolumeOutputs() const;
461 
462  /// \deprecated Use the form that takes a TfTokenVector or renderContexts
465  const TfToken &renderContext,
466  TfToken *sourceName=nullptr,
467  UsdShadeAttributeType *sourceType=nullptr) const;
468 
469  /// Computes the resolved "volume" output source for the given
470  /// \p contextVector. Using the earliest renderContext in the contextVector
471  /// that produces a valid Shader object.
472  ///
473  /// If a "volume" output corresponding to each of the renderContexts
474  /// does not exist <b>or</b> is not connected to a valid source, then this
475  /// checks the <i>universal</i> volume output.
476  ///
477  /// Returns an empty Shader object if there is no valid <i>volume</i> output
478  /// output source for any of the renderContexts in the \p contextVector.
479  /// The python version of this method returns a tuple containing three
480  /// elements (the source volume shader, sourceName, sourceType).
483  const TfTokenVector &contextVector={UsdShadeTokens->universalRenderContext},
484  TfToken *sourceName=nullptr,
485  UsdShadeAttributeType *sourceType=nullptr) const;
486 
487  /// @}
488 
489 private:
490  // Helper method to compute the sources of a given output, identified by its
491  // baseName, for the renderContexts in the specified contextVector.
492  UsdShadeAttributeVector _ComputeNamedOutputSources(
493  const TfToken &baseName,
494  const TfTokenVector &contextVector) const;
495 
496  // Helper method to compute the source shader of a given output, identified
497  // by its baseName, for the renderContexts in the specified contextVector.
498  UsdShadeShader _ComputeNamedOutputShader(
499  const TfToken &baseName,
500  const TfTokenVector &contextVector,
501  TfToken *sourceName,
502  UsdShadeAttributeType *sourceType) const;
503 
504  // Helper method to retrieve outputs in all renderContexts that match the
505  // given terminalName.
506  std::vector<UsdShadeOutput> _GetOutputsForTerminalName(
507  const TfToken& terminalName) const;
508 
509 public:
510  // --------------------------------------------------------------------- //
511  /// \anchor UsdShadeMaterial_Variations
512  /// \name Authoring Material Variations
513  /// Each UsdShadeMaterial prim can host data for any number of render targets
514  /// (such as Renderman RIS, Arnold, or glslfx).
515  ///
516  /// A single UsdShadeMaterial group can, however, encode variations on
517  /// appearance, varying any data authored on the material and its contents.
518  /// For example, we might have a logo'd baseball cap that
519  /// comes in denim, nylon, and corduroy variations.
520  ///
521  /// We provide methods to aid in authoring such variations on individual
522  /// Material prims, and also a facility for creating a "master" look
523  /// variant on another prim (e.g. a model's root prim, or another common
524  /// ancestor of all Material prims in a model) that will be able to modify
525  /// Materials, bindings, connections and values at once.
526  ///
527  /// <b>Note on variant vs "direct" opinions.</b>
528  /// For any given prim's spec in a layer, opinions expressed inside a
529  /// variant of a variantSet will be /weaker/ than any opinions expressed
530  /// "directly" at the location, outside of any layer.
531  ///
532  /// Therefore, if you intend to author a default variant that is weaker than
533  /// more explicit variants, you will need to have those opinions be weaker
534  /// by setting them across a reference arc such as the following:
535  ///
536  /// \code
537  /// def "MyMaterial" (
538  /// add references = </MyMaterial_defaultShadingVariant>
539  /// variants = {
540  /// string materialVariant = "SomeVariant"
541  /// }
542  /// add variantSets = "materialVariant"
543  /// )
544  /// {
545  /// float strongerThanVariantOpinion
546  ///
547  /// variantSet "materialVariant" = {
548  /// "SomeVariant" {
549  /// float variantOpinion
550  /// }
551  /// }
552  /// }
553  ///
554  /// over "MyMaterial_defaultShadingVariant"
555  /// {
556  /// float weakerThanVariantOpinion
557  /// }
558  /// \endcode
559  ///
560  /// @{
561  ///
562  // --------------------------------------------------------------------- //
563  /// Helper function for configuring a UsdStage's UsdEditTarget to author
564  /// Material variations. Takes care of creating the Material variantSet and
565  /// specified variant, if necessary.
566  ///
567  /// Let's assume that we are authoring Materials into the Stage's current
568  /// UsdEditTarget, and that we are iterating over the variations of a
569  /// UsdShadeMaterial \em clothMaterial, and \em currVariant is the variant we are
570  /// processing (e.g. "denim").
571  ///
572  /// In C++, then, we would use the following pattern:
573  /// \code
574  /// {
575  /// UsdEditContext ctxt(clothMaterial.GetEditContextForVariant(currVariant));
576  ///
577  /// // All USD mutation of the UsdStage on which clothMaterial sits will
578  /// // now go "inside" the currVariant of the "MaterialVariant" variantSet
579  /// }
580  /// \endcode
581  ///
582  /// In python, the pattern is:
583  /// \code{.py}
584  /// with clothMaterial.GetEditContextForVariant(currVariant):
585  /// # Now sending mutations to currVariant
586  /// \endcode
587  ///
588  /// If \p layer is specified, then we will use it, rather than the stage's
589  /// current UsdEditTarget's layer as the destination layer for the
590  /// edit context we are building. If \p layer does not actually contribute
591  /// to the Material prim's definition, any editing will have no effect on this
592  /// Material.
593  ///
594  /// <b>Note:</b> As just stated, using this method involves authoring
595  /// a selection for the MaterialVariant in the stage's current EditTarget.
596  /// When client is done authoring variations on this prim, they will likely
597  /// want to either UsdVariantSet::SetVariantSelection() to the appropriate
598  /// default selection, or possibly UsdVariantSet::ClearVariantSelection()
599  /// on the UsdShadeMaterial::GetMaterialVariant() UsdVariantSet.
600  /// \sa UsdVariantSet::GetVariantEditContext()
602  std::pair<UsdStagePtr, UsdEditTarget>
603  GetEditContextForVariant(const TfToken &MaterialVariantName,
604  const SdfLayerHandle &layer = SdfLayerHandle()) const;
605 
606  /// Return a UsdVariantSet object for interacting with the Material variant
607  /// variantSet
610 
611  /// Create a variantSet on \p masterPrim that will set the MaterialVariant on
612  /// each of the given \em MaterialPrims.
613  ///
614  /// The variantSet, whose name can be specified with \p
615  /// masterVariantSetName and defaults to the same MaterialVariant name
616  /// created on Materials by GetEditContextForVariant(), will have the same
617  /// variants as the Materials, and each Master variant will set every
618  /// \p MaterialPrims' MaterialVariant selection to the same variant as the
619  /// master. Thus, it allows all Materials to be switched with a single
620  /// variant selection, on \p masterPrim.
621  ///
622  /// If \p masterPrim is an ancestor of any given member of \p MaterialPrims,
623  /// then we will author variant selections directly on the MaterialPrims.
624  /// However, it is often preferable to create a master MaterialVariant in
625  /// a separately rooted tree from the MaterialPrims, so that it can be
626  /// layered more strongly on top of the Materials. Therefore, for any MaterialPrim
627  /// in a different tree than masterPrim, we will create "overs" as children
628  /// of masterPrim that recreate the path to the MaterialPrim, substituting
629  /// masterPrim's full path for the MaterialPrim's root path component.
630  ///
631  /// Upon successful completion, the new variantSet we created on
632  /// \p masterPrim will have its variant selection authored to the
633  /// "last" variant (determined lexicographically). It is up to the
634  /// calling client to either UsdVariantSet::ClearVariantSelection()
635  /// on \p masterPrim, or set the selection to the desired default setting.
636  ///
637  /// Return \c true on success. It is an error if any of \p Materials
638  /// have a different set of variants for the MaterialVariant than the others.
640  static bool CreateMasterMaterialVariant(
641  const UsdPrim &masterPrim,
642  const std::vector<UsdPrim> &MaterialPrims,
643  const TfToken &masterVariantSetName = TfToken());
644 
645  /// @}
646 
647  // --------------------------------------------------------------------- //
648  /// \anchor UsdShadeMaterial_BaseMaterial
649  /// \name BaseMaterial
650  /// A specialize arc describes child/parent inheritance.
651  /// A Material that derives from a BaseMaterial will retain a live
652  /// composition relationship to its BaseMaterial
653  ///
654  /// @{
655  // --------------------------------------------------------------------- //
656 
657  /// Get the path to the base Material of this Material.
658  /// If there is no base Material, an empty Material is returned
661 
662  /// Get the base Material of this Material.
663  /// If there is no base Material, an empty path is returned
666 
667  /// Given a PcpPrimIndex, searches it for an arc to a parent material.
668  ///
669  /// This is a public static function to support applications that use
670  /// Pcp but not Usd. Most clients should call \ref GetBaseMaterialPath,
671  /// which uses this function when appropriate.
674  const PcpPrimIndex & primIndex,
675  const PathPredicate & pathIsMaterialPredicate);
676 
677  /// Set the base Material of this Material.
678  /// An empty Material is equivalent to clearing the base Material.
680  void SetBaseMaterial(const UsdShadeMaterial& baseMaterial) const;
681 
682  /// Set the path to the base Material of this Material.
683  /// An empty path is equivalent to clearing the base Material.
685  void SetBaseMaterialPath(const SdfPath& baseMaterialPath) const;
686 
687  /// Clear the base Material of this Material.
689  void ClearBaseMaterial() const;
690 
691  // Check if this Material has a base Material
693  bool HasBaseMaterial() const;
694 
695  /// @}
696 
697 };
698 
700 
701 #endif
USDSHADE_API UsdShadeOutput CreateSurfaceOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
USDSHADE_API UsdShadeOutput GetVolumeOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
#define USDSHADE_API
Definition: api.h:40
static USDSHADE_API SdfPath FindBaseMaterialPathInPrimIndex(const PcpPrimIndex &primIndex, const PathPredicate &pathIsMaterialPredicate)
USDSHADE_API UsdAttribute CreateDisplacementAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDSHADE_API TfStaticData< UsdShadeTokensType > UsdShadeTokens
USDSHADE_API UsdShadeOutput GetDisplacementOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
virtual USDSHADE_API ~UsdShadeMaterial()
Destructor.
USDSHADE_API std::vector< UsdShadeOutput > GetVolumeOutputs() const
static USDSHADE_API UsdShadeMaterial Get(const UsdStagePtr &stage, const SdfPath &path)
USDSHADE_API UsdAttribute CreateSurfaceAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDSHADE_API UsdAttribute GetDisplacementAttr() const
static USDSHADE_API bool CreateMasterMaterialVariant(const UsdPrim &masterPrim, const std::vector< UsdPrim > &MaterialPrims, const TfToken &masterVariantSetName=TfToken())
USDSHADE_API void ClearBaseMaterial() const
Clear the base Material of this Material.
USDSHADE_API UsdShadeMaterial GetBaseMaterial() const
USDSHADE_API UsdShadeOutput CreateDisplacementOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
USDSHADE_API UsdAttribute GetVolumeAttr() const
UsdSchemaKind
Definition: common.h:127
USDSHADE_API UsdAttribute CreateVolumeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: token.h:87
static const UsdSchemaKind schemaKind
Definition: material.h:117
USDSHADE_API SdfPath GetBaseMaterialPath() const
USDSHADE_API void SetBaseMaterialPath(const SdfPath &baseMaterialPath) const
USDSHADE_API UsdShadeShader ComputeVolumeSource(const TfToken &renderContext, TfToken *sourceName=nullptr, UsdShadeAttributeType *sourceType=nullptr) const
USDSHADE_API std::pair< UsdStagePtr, UsdEditTarget > GetEditContextForVariant(const TfToken &MaterialVariantName, const SdfLayerHandle &layer=SdfLayerHandle()) const
UsdShadeMaterial(const UsdPrim &prim=UsdPrim())
Definition: material.h:123
USDSHADE_API bool HasBaseMaterial() const
UsdShadeMaterial(const UsdSchemaBase &schemaObj)
Definition: material.h:131
Represents a concrete typed schema.
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
Definition: path.h:290
USDSHADE_API std::vector< UsdShadeOutput > GetSurfaceOutputs() const
USDSHADE_API UsdShadeOutput CreateVolumeOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
static USDSHADE_API UsdShadeMaterial Define(const UsdStagePtr &stage, const SdfPath &path)
USDSHADE_API std::vector< UsdShadeOutput > GetDisplacementOutputs() const
USDSHADE_API UsdShadeShader ComputeSurfaceSource(const TfToken &renderContext, TfToken *sourceName=nullptr, UsdShadeAttributeType *sourceType=nullptr) const
USDSHADE_API UsdShadeOutput GetSurfaceOutput(const TfToken &renderContext=UsdShadeTokens->universalRenderContext) const
USDSHADE_API void SetBaseMaterial(const UsdShadeMaterial &baseMaterial) const
USDSHADE_API UsdSchemaKind _GetSchemaKind() const override
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
USDSHADE_API UsdVariantSet GetMaterialVariant() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
std::function< bool(const SdfPath &)> PathPredicate
A function type that takes a path and returns a bool.
Definition: material.h:292
USDSHADE_API UsdShadeShader ComputeDisplacementSource(const TfToken &renderContext, TfToken *sourceName=nullptr, UsdShadeAttributeType *sourceType=nullptr) const
static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
USDSHADE_API UsdAttribute GetSurfaceAttr() const
Definition: value.h:166
UsdShadeAttributeType
Definition: types.h:39