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