This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdShadeMaterialBindingAPI Class Reference

UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims or collections of prims (represented by UsdCollectionAPI objects). More...

#include <materialBindingAPI.h>

+ Inheritance diagram for UsdShadeMaterialBindingAPI:

Classes

class  CollectionBinding
 This struct is used to represent a collection-based material binding, which contains two objects - a collection and a bound material. More...
 
class  DirectBinding
 This class represents a direct material binding. More...
 

Public Member Functions

 UsdShadeMaterialBindingAPI (const UsdPrim &prim=UsdPrim())
 Construct a UsdShadeMaterialBindingAPI on UsdPrim prim .
 
 UsdShadeMaterialBindingAPI (const UsdSchemaBase &schemaObj)
 Construct a UsdShadeMaterialBindingAPI on the prim held by schemaObj .
 
virtual USDSHADE_API ~UsdShadeMaterialBindingAPI ()
 Destructor.
 
Binding authoring and clearing API

This section provides API for authoring and clearing both direct and collection-based material bindings on a prim.

USDSHADE_API bool Bind (const UsdShadeMaterial &material, const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Authors a direct binding to the given material on this prim.
 
USDSHADE_API bool Bind (const UsdCollectionAPI &collection, const UsdShadeMaterial &material, const TfToken &bindingName=TfToken(), const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Authors a collection-based binding, which binds the given material to the given collection on this prim.
 
USDSHADE_API bool UnbindDirectBinding (const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Unbinds the direct binding for the given material purpose (materialPurpose) on this prim.
 
USDSHADE_API bool UnbindCollectionBinding (const TfToken &bindingName, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Unbinds the collection-based binding with the given bindingName, for the given materialPurpose on this prim.
 
USDSHADE_API bool UnbindAllBindings () const
 Unbinds all direct and collection-based bindings on this prim.
 
USDSHADE_API bool RemovePrimFromBindingCollection (const UsdPrim &prim, const TfToken &bindingName, const TfToken &materialPurpose) const
 Removes the specified prim from the collection targeted by the binding relationship corresponding to given bindingName and materialPurpose.
 
USDSHADE_API bool AddPrimToBindingCollection (const UsdPrim &prim, const TfToken &bindingName, const TfToken &materialPurpose) const
 Adds the specified prim to the collection targeted by the binding relationship corresponding to given bindingName and materialPurpose.
 
- Public Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
 Construct a UsdAPISchemaBase on UsdPrim prim .
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
 Construct a UsdAPISchemaBase on the prim held by schemaObj .
 
virtual USD_API ~UsdAPISchemaBase ()=0
 Destructor.
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped.
 
bool IsAPISchema () const
 Returns whether this is an API schema or not.
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not.
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not.
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is.
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim.
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema.
 
virtual USD_API ~UsdSchemaBase ()
 Destructor.
 
UsdPrim GetPrim () const
 Return this schema object's held prim.
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath().
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null.
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise.
 

Static Public Member Functions

static USDSHADE_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDSHADE_API UsdShadeMaterialBindingAPI Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdShadeMaterialBindingAPI holding the prim adhering to this schema at path on stage.
 
static USDSHADE_API bool CanApply (const UsdPrim &prim, std::string *whyNot=nullptr)
 Returns true if this single-apply API schema can be applied to the given prim.
 
static USDSHADE_API UsdShadeMaterialBindingAPI Apply (const UsdPrim &prim)
 Applies this single-apply API schema to the given prim.
 
- Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 

Protected Member Functions

USDSHADE_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdAPISchemaBase
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
 UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on UsdPrim prim with the specified instanceName.
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
 Construct a multiple-apply UsdAPISchemaBase on the prim held by schemaObj with the given instanceName.
 
const TfToken_GetInstanceName () const
 Returns the instance name of the API schema object belonging to a multiple-apply API schema.
 
USD_API bool _IsCompatible () const override
 Check whether this APISchema object is valid for the currently held
prim.
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Schema property and associated data retrieval API

This section contains API for fetching the two kinds of binding relationships and for computing the corresponding bindings.

using CollectionBindingVector = std::vector< CollectionBinding >
 
USDSHADE_API UsdRelationship GetDirectBindingRel (const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Returns the direct material-binding relationship on this prim for the given material purpose.
 
USDSHADE_API UsdRelationship GetCollectionBindingRel (const TfToken &bindingName, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Returns the collection-based material-binding relationship with the given bindingName and materialPurpose on this prim.
 
USDSHADE_API std::vector< UsdRelationshipGetCollectionBindingRels (const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Returns the list of collection-based material binding relationships on this prim for the given material purpose, materialPurpose.
 
USDSHADE_API DirectBinding GetDirectBinding (const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Computes and returns the direct binding for the given material purpose on this prim.
 
USDSHADE_API CollectionBindingVector GetCollectionBindings (const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
 Returns all the collection-based bindings on this prim for the given material purpose.
 
static USDSHADE_API TfToken GetMaterialBindingStrength (const UsdRelationship &bindingRel)
 Resolves the 'bindMaterialAs' token-valued metadata on the given binding relationship and returns it.
 
static USDSHADE_API bool SetMaterialBindingStrength (const UsdRelationship &bindingRel, const TfToken &bindingStrength)
 Sets the 'bindMaterialAs' token-valued metadata on the given binding relationship.
 

Bound Material Resolution

Material resolution is the process of determining the final bound material for a given gprim (or UsdGeomSubset), for a given value of material purpose. It involves examining all the bindings on the prim and its ancestors, until a matching binding is found. The following set of rules are applied in the process:

  • [1] Material bindings are inherited down the namespace chain. Bindings lower in namespace (closer to leaf gprims) are stronger than bindings on ancestors, unless they have their binding-strength set to UsdShadeTokens->strongerThanDescendants.
  • [2] A collection binding only applies to members of the collection that are at or beneath the prim owning the binding relationship.
  • [3] The purpose of the resolved material binding must either match the requested special (i.e. restricted) purpose or be an all-purpose binding. The restricted purpose binding, if available is preferred over an all-purpose binding.
  • [4] At any given prim, the collection-based bindings are considered to be stronger than the direct bindings. This reflects our belief that the combination would appear primarily to define a "fallback" material to be used by any child prims that are not targeted by a more specific assignment
  • [5] Collection-based binding relationships are applied in native property order, with the earlier ordered binding relationships being stronger.
  • [6] The "namespace specificity" with which a prim is included in a collection is irrelevant to the binding strength of the collection. For example, if a prim contains the ordered collection bindings material:binding:collection:metalBits and material:binding:collection:plasticBits, each of which targets a collection of the same name, then if metalBits includes </Chair/Back>, while plasticBits includes </Chair/Back/Brace/Rivet>, the binding for </Chair/Back/Brace/Rivet> will be metalBits, because the metalBits collection is bound more strongly than the plasticBits, and includes an ancestor of </Chair/Back/Brace/Rivet>.
Note
If a material binding relationship is a built-in property defined as part of a typed prim schema, a fallback value should not be provided for it. This is because the "material resolution" algorithm only conisders authored properties.
using CollectionQueryCache = tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< UsdCollectionAPI::MembershipQuery >, SdfPath::Hash >
 An unordered list of collection paths mapped to the associated collection's MembershipQuery object.
 
using DirectBindingPtr = std::unique_ptr< DirectBinding >
 Alias for a unique_ptr to a DirectBinding object.
 
using BindingsCache = tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< BindingsAtPrim >, SdfPath::Hash >
 An unordered list of prim-paths mapped to the corresponding set of bindings at the associated prim.
 
struct BindingsAtPrim
 BindingsAtPrim needs to invoke private _GetCollectionBindings().
 
USDSHADE_API UsdShadeMaterial ComputeBoundMaterial (BindingsCache *bindingsCache, CollectionQueryCache *collectionQueryCache, const TfToken &materialPurpose=UsdShadeTokens->allPurpose, UsdRelationship *bindingRel=nullptr, bool supportLegacyBindings=true) const
 Computes the resolved bound material for this prim, for the given material purpose.
 
USDSHADE_API UsdShadeMaterial ComputeBoundMaterial (const TfToken &materialPurpose=UsdShadeTokens->allPurpose, UsdRelationship *bindingRel=nullptr, bool supportLegacyBindings=true) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the resolved bound material for this prim, for the given material purpose.
 
static USDSHADE_API TfTokenVector GetMaterialPurposes ()
 Returns a vector of the possible values for the 'material purpose'.
 
static USDSHADE_API const SdfPath GetResolvedTargetPathFromBindingRel (const UsdRelationship &bindingRel)
 returns the path of the resolved target identified by bindingRel.
 
static USDSHADE_API std::vector< UsdShadeMaterialComputeBoundMaterials (const std::vector< UsdPrim > &prims, const TfToken &materialPurpose=UsdShadeTokens->allPurpose, std::vector< UsdRelationship > *bindingRels=nullptr, bool supportLegacyBindings=true)
 Static API for efficiently and concurrently computing the resolved material bindings for a vector of UsdPrims, prims for the given materialPurpose.
 

Binding materials to subsets

API to create, access and query the presence of GeomSubsets that are created for the purpose of binding materials.

Note
GeomSubsets can only be created on valid UsdGeomImageable prims. Hence, this API only works when the prim held by the MaterialBindingAPI schema object is an imageable prim.
Material bindings authored on GeomSubsets are honored by renderers only if their familyName is UsdShadeTokens->materialBind. This allows robust interchange of subset bindings between multiple DCC apps.
The family type of the materialBind family of subsets defaults to UsdGeomTokens->nonOverlapping. It can be set to UsdGeomTokens->partition, using the API SetMaterialBindFaceSubsetsFamilyType(). It should never be set to UsdGeomTokens->unrestricted, since it is invalid for a piece of geometry to be bound to multiple materials.

Here's some sample code that shows how to create "face" subsets and and bind materials to them.

// Get the imageable prim under which subsets must be created and
// bound.
SdfPath("/path/to/meshPrim");
// Get the materials to bind to.
SdfPath("/path/to/PlasticMaterial");
SdfPath("/path/to/MetalMaterial");
VtIntArray plasticFaces, metalFaces;
//.. populate faceIndices here.
//..
UsdShadeMaterialBindingAPI meshBindingAPI(mesh.GetPrim());
UsdGeomSubset plasticSubset = meshBindingAPI.CreateMaterialBindSubset(
"plasticSubset", plasticFaces);
UsdGeomSubset metalSubset = meshBindingAPI.CreateMaterialBindSubset(
"metalSubset", metalFaces);
// Bind materials to the created geom-subsets.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Base class for all prims that may require rendering or visualization of some sort.
Definition: imageable.h:58
static USDGEOM_API UsdGeomImageable Get(const UsdStagePtr &stage, const SdfPath &path)
Return a UsdGeomImageable holding the prim adhering to this schema at path on stage.
Encodes a subset of a piece of geometry (i.e.
Definition: subset.h:71
UsdPrim GetPrim() const
Return this schema object's held prim.
Definition: schemaBase.h:103
UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims...
static USDSHADE_API UsdShadeMaterialBindingAPI Apply(const UsdPrim &prim)
Applies this single-apply API schema to the given prim.
USDSHADE_API bool Bind(const UsdShadeMaterial &material, const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Authors a direct binding to the given material on this prim.
A Material provides a container into which multiple "render contexts" can add data that defines a "sh...
Definition: material.h:96
static USDSHADE_API UsdShadeMaterial Get(const UsdStagePtr &stage, const SdfPath &path)
Return a UsdShadeMaterial holding the prim adhering to this schema at path on stage.
USDSHADE_API UsdGeomSubset CreateMaterialBindSubset (const TfToken &subsetName, const VtIntArray &indices, const TfToken &elementType=UsdGeomTokens->face)
 Creates a GeomSubset named subsetName with element type, elementType and familyName materialBind below this prim.
 
USDSHADE_API std::vector< UsdGeomSubsetGetMaterialBindSubsets ()
 Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.
 
USDSHADE_API bool SetMaterialBindSubsetsFamilyType (const TfToken &familyType)
 Author the familyType of the "materialBind" family of GeomSubsets on this prim.
 
USDSHADE_API TfToken GetMaterialBindSubsetsFamilyType ()
 Returns the familyType of the family of "materialBind" GeomSubsets on this prim.
 
static USDSHADE_API bool CanContainPropertyName (const TfToken &name)
 Test whether a given name contains the "material:binding:" prefix.
 

Additional Inherited Members

- Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector _GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)
 Returns a vector of names of API schema objects belonging to a multiple-apply API schema applied to a given prim.
 

Detailed Description

UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims or collections of prims (represented by UsdCollectionAPI objects).

In the USD shading model, each renderable gprim computes a single resolved Material that will be used to shade the gprim (exceptions, of course, for gprims that possess UsdGeomSubsets, as each subset can be shaded by a different Material). A gprim and each of its ancestor prims can possess, through the MaterialBindingAPI, both a direct binding to a Material, and any number of collection-based bindings to Materials; each binding can be generic or declared for a particular purpose, and given a specific binding strength. It is the process of "material resolution" (see UsdShadeMaterialBindingAPI_MaterialResolution) that examines all of these bindings, and selects the one Material that best matches the client's needs.

The intent of purpose is that each gprim should be able to resolve a Material for any given purpose, which implies it can have differently bound materials for different purposes. There are two special values of purpose defined in UsdShade, although the API fully supports specifying arbitrary values for it, for the sake of extensibility:

  • UsdShadeTokens->full: to be used when the purpose of the render is entirely to visualize the truest representation of a scene, considering all lighting and material information, at highest fidelity.
  • UsdShadeTokens->preview: to be used when the render is in service of a goal other than a high fidelity "full" render (such as scene manipulation, modeling, or realtime playback). Latency and speed are generally of greater concern for preview renders, therefore preview materials are generally designed to be "lighterweight" compared to full materials.

A binding can also have no specific purpose at all, in which case, it is considered to be the fallback or all-purpose binding (denoted by the empty-valued token UsdShadeTokens->allPurpose).

The purpose of a material binding is encoded in the name of the binding relationship.

  • In the case of a direct binding, the allPurpose binding is represented by the relationship named material:binding. Special-purpose direct bindings are represented by relationships named material:binding:purpose. A direct binding relationship must have a single target path that points to a UsdShadeMaterial.
  • In the case of a collection-based binding, the allPurpose binding is represented by a relationship named material:binding:collection:bindingName, where bindingName establishes an identity for the binding that is unique on the prim. Attempting to establish two collection bindings of the same name on the same prim will result in the first binding simply being overridden. A special-purpose collection-based binding is represented by a relationship named material:binding:collection:purpose:bindingName. A collection-based binding relationship must have exacly two targets, one of which should be a collection-path (see ef UsdCollectionAPI::GetCollectionPath()) and the other should point to a UsdShadeMaterial. In the future, we may allow a single collection binding to target multiple collections, if we can establish a reasonable round-tripping pattern for applications that only allow a single collection to be associated with each Material.

Note: Both bindingName and purpose must be non-namespaced tokens. This allows us to know the role of a binding relationship simply from the number of tokens in it.

  • Two tokens: the fallback, "all purpose", direct binding, material:binding
  • Three tokens: a purpose-restricted, direct, fallback binding, e.g. material:binding:preview
  • Four tokens: an all-purpose, collection-based binding, e.g. material:binding:collection:metalBits
  • Five tokens: a purpose-restricted, collection-based binding, e.g. material:binding:collection:full:metalBits

A binding-strength value is used to specify whether a binding authored on a prim should be weaker or stronger than bindings that appear lower in namespace. We encode the binding strength with as token-valued metadata 'bindMaterialAs' for future flexibility, even though for now, there are only two possible values: UsdShadeTokens->weakerThanDescendants and UsdShadeTokens->strongerThanDescendants. When binding-strength is not authored (i.e. empty) on a binding-relationship, the default behavior matches UsdShadeTokens->weakerThanDescendants.

Note
If a material binding relationship is a built-in property defined as part of a typed prim's schema, a fallback value should not be provided for it. This is because the "material resolution" algorithm only conisders authored properties.

Definition at line 134 of file materialBindingAPI.h.

Member Typedef Documentation

◆ BindingsCache

using BindingsCache = tbb::concurrent_unordered_map<SdfPath, std::unique_ptr<BindingsAtPrim>, SdfPath::Hash>

An unordered list of prim-paths mapped to the corresponding set of bindings at the associated prim.

This is used when computing resolved bindings to avoid redundant computations for the shared ancestor prims and to re-use the computed results for leaf prims.

Definition at line 718 of file materialBindingAPI.h.

◆ CollectionBindingVector

using CollectionBindingVector = std::vector<CollectionBinding>

Definition at line 414 of file materialBindingAPI.h.

◆ CollectionQueryCache

using CollectionQueryCache = tbb::concurrent_unordered_map<SdfPath, std::unique_ptr<UsdCollectionAPI::MembershipQuery>, SdfPath::Hash>

An unordered list of collection paths mapped to the associated collection's MembershipQuery object.

This is used to cache the MembershipQuery objects for collections that are encountered during binding resolution for a tree of prims.

Definition at line 677 of file materialBindingAPI.h.

◆ DirectBindingPtr

using DirectBindingPtr = std::unique_ptr<DirectBinding>

Alias for a unique_ptr to a DirectBinding object.

Definition at line 682 of file materialBindingAPI.h.

Constructor & Destructor Documentation

◆ UsdShadeMaterialBindingAPI() [1/2]

UsdShadeMaterialBindingAPI ( const UsdPrim prim = UsdPrim())
inlineexplicit

Construct a UsdShadeMaterialBindingAPI on UsdPrim prim .

Equivalent to UsdShadeMaterialBindingAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 146 of file materialBindingAPI.h.

◆ UsdShadeMaterialBindingAPI() [2/2]

UsdShadeMaterialBindingAPI ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdShadeMaterialBindingAPI on the prim held by schemaObj .

Should be preferred over UsdShadeMaterialBindingAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 154 of file materialBindingAPI.h.

◆ ~UsdShadeMaterialBindingAPI()

virtual USDSHADE_API ~UsdShadeMaterialBindingAPI ( )
virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDSHADE_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

◆ AddPrimToBindingCollection()

USDSHADE_API bool AddPrimToBindingCollection ( const UsdPrim prim,
const TfToken bindingName,
const TfToken materialPurpose 
) const

Adds the specified prim to the collection targeted by the binding relationship corresponding to given bindingName and materialPurpose.

If the collection-binding relationship doesn't exist or if the targeted collection already includes the prim, then this does nothing and returns true.

If the targeted collection does not include prim (or excludes it explicitly), then this modifies the collection by adding the prim to it (by invoking UsdCollectionAPI::AddPrim()).

◆ Apply()

static USDSHADE_API UsdShadeMaterialBindingAPI Apply ( const UsdPrim prim)
static

Applies this single-apply API schema to the given prim.

This information is stored by adding "MaterialBindingAPI" to the token-valued, listOp metadata apiSchemas on the prim.

Returns
A valid UsdShadeMaterialBindingAPI object is returned upon success. An invalid (or empty) UsdShadeMaterialBindingAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.
See also
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()

◆ Bind() [1/2]

USDSHADE_API bool Bind ( const UsdCollectionAPI collection,
const UsdShadeMaterial material,
const TfToken bindingName = TfToken(),
const TfToken bindingStrength = UsdShadeTokens->fallbackStrength,
const TfToken materialPurpose = UsdShadeTokens->allPurpose 
) const

Authors a collection-based binding, which binds the given material to the given collection on this prim.

bindingName establishes an identity for the binding that is unique on the prim. Attempting to establish two collection bindings of the same name on the same prim will result in the first binding simply being overridden. If bindingName is empty, it is set to the base-name of the collection being bound (which is the collection-name with any namespaces stripped out). If there are multiple collections with the same base-name being bound at the same prim, clients should pass in a unique binding name per binding, in order to preserve all bindings. The binding name used in constructing the collection-binding relationship name shoud not contain namespaces. Hence, a coding error is issued and no binding is authored if the provided value of bindingName is non-empty and contains namespaces.

If bindingStrength is UsdShadeTokens->fallbackStrength, the value UsdShadeTokens->weakerThanDescendants is authored sparsely, i.e. only when there is an existing binding with a different bindingStrength. To stamp out the bindingStrength value explicitly, clients can pass in UsdShadeTokens->weakerThanDescendants or UsdShadeTokens->strongerThanDescendants directly.

If materialPurpose is specified and isn't equal to UsdShadeTokens->allPurpose, the binding only applies to the specified material purpose.

Note that UsdShadeMaterialBindingAPI is a SingleAppliedAPI schema which when applied updates the prim definition accordingly. This information on the prim definition is helpful in multiple queries and more performant. Hence its recommended to call UsdShadeMaterialBindingAPI::Apply() when Binding a material.

Returns true on success, false otherwise.

◆ Bind() [2/2]

USDSHADE_API bool Bind ( const UsdShadeMaterial material,
const TfToken bindingStrength = UsdShadeTokens->fallbackStrength,
const TfToken materialPurpose = UsdShadeTokens->allPurpose 
) const

Authors a direct binding to the given material on this prim.

If bindingStrength is UsdShadeTokens->fallbackStrength, the value UsdShadeTokens->weakerThanDescendants is authored sparsely. To stamp out the bindingStrength value explicitly, clients can pass in UsdShadeTokens->weakerThanDescendants or UsdShadeTokens->strongerThanDescendants directly.

If materialPurpose is specified and isn't equal to UsdShadeTokens->allPurpose, the binding only applies to the specified material purpose.

Note that UsdShadeMaterialBindingAPI is a SingleAppliedAPI schema which when applied updates the prim definition accordingly. This information on the prim definition is helpful in multiple queries and more performant. Hence its recommended to call UsdShadeMaterialBindingAPI::Apply() when Binding a material.

Returns true on success, false otherwise.

◆ CanApply()

static USDSHADE_API bool CanApply ( const UsdPrim prim,
std::string *  whyNot = nullptr 
)
static

Returns true if this single-apply API schema can be applied to the given prim.

If this schema can not be a applied to the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

See also
UsdPrim::GetAppliedSchemas()
UsdPrim::HasAPI()
UsdPrim::CanApplyAPI()
UsdPrim::ApplyAPI()
UsdPrim::RemoveAPI()

◆ CanContainPropertyName()

static USDSHADE_API bool CanContainPropertyName ( const TfToken name)
static

Test whether a given name contains the "material:binding:" prefix.

◆ ComputeBoundMaterial() [1/2]

USDSHADE_API UsdShadeMaterial ComputeBoundMaterial ( BindingsCache bindingsCache,
CollectionQueryCache collectionQueryCache,
const TfToken materialPurpose = UsdShadeTokens->allPurpose,
UsdRelationship bindingRel = nullptr,
bool  supportLegacyBindings = true 
) const

Computes the resolved bound material for this prim, for the given material purpose.

This overload of ComputeBoundMaterial makes use of the BindingsCache (bindingsCache) and CollectionQueryCache (collectionQueryCache) that are passed in, to avoid redundant binding computations and computations of MembershipQuery objects for collections. It would be beneficial to make use of these when resolving bindings for a tree of prims. These caches are populated lazily as more and more bindings are resolved.

When the goal is to compute the bound material for a range (or list) of prims, it is recommended to use this version of ComputeBoundMaterial(). Here's how you could compute the bindings of a range of prims efficiently in C++:

std::vector<std::pair<UsdPrim, UsdShadeMaterial> primBindings;
for (auto prim : UsdPrimRange(rootPrim)) {
UsdShadeMaterial boundMaterial =
&bindingsCache, &collQueryCache);
if (boundMaterial) {
primBindings.emplace_back({prim, boundMaterial});
}
}
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first ord...
Definition: primRange.h:102
tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< UsdCollectionAPI::MembershipQuery >, SdfPath::Hash > CollectionQueryCache
An unordered list of collection paths mapped to the associated collection's MembershipQuery object.
tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< BindingsAtPrim >, SdfPath::Hash > BindingsCache
An unordered list of prim-paths mapped to the corresponding set of bindings at the associated prim.
USDSHADE_API UsdShadeMaterial ComputeBoundMaterial(BindingsCache *bindingsCache, CollectionQueryCache *collectionQueryCache, const TfToken &materialPurpose=UsdShadeTokens->allPurpose, UsdRelationship *bindingRel=nullptr, bool supportLegacyBindings=true) const
Computes the resolved bound material for this prim, for the given material purpose.

If bindingRel is not null, then it is set to the "winning" binding relationship.

Note the resolved bound material is considered valid if the target path of the binding relationship is a valid non-empty prim path. This makes sure winning binding relationship and the bound material remain consistent consistent irrespective of the presence/absence of prim at material path. For ascenario where ComputeBoundMaterial returns a invalid UsdShadeMaterial with a valid winning bindingRel, clients can use the
static method UsdShadeMaterialBindingAPI::GetResolvedTargetPathFromBindingRel to get the path of the resolved target identified by the winning bindingRel.

In order for backward compatibility with old assets not having MaterialBindingAPI applied, supportLegacyBindings defaults to true. Though its recommended for clients to update the assets to have MaterialBindingAPI applied for optimized computation of bound material.

Note: In a future release the default for supportLegacyBindings will be updated to "false".

See Bound Material Resolution for details on the material resolution process.

The python version of this method returns a tuple containing the bound material and the "winning" binding relationship.

◆ ComputeBoundMaterial() [2/2]

USDSHADE_API UsdShadeMaterial ComputeBoundMaterial ( const TfToken materialPurpose = UsdShadeTokens->allPurpose,
UsdRelationship bindingRel = nullptr,
bool  supportLegacyBindings = true 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the resolved bound material for this prim, for the given material purpose.

This overload does not utilize cached MembershipQuery object. However, it only computes the MembershipQuery of every collection that bound in the ancestor chain at most once.

If bindingRel is not null, then it is set to the winning binding relationship.

In order for backward compatibility with old assets not having MaterialBindingAPI applied, supportLegacyBindings defaults to true. Though its recommended for clients to update the assets to have MaterialBindingAPI applied for optimized computation of bound material.

Note: In a future release the default for supportLegacyBindings will be updated to "false".

See Bound Material Resolution for details on the material resolution process.

The python version of this method returns a tuple containing the bound material and the "winning" binding relationship.

◆ ComputeBoundMaterials()

static USDSHADE_API std::vector< UsdShadeMaterial > ComputeBoundMaterials ( const std::vector< UsdPrim > &  prims,
const TfToken materialPurpose = UsdShadeTokens->allPurpose,
std::vector< UsdRelationship > *  bindingRels = nullptr,
bool  supportLegacyBindings = true 
)
static

Static API for efficiently and concurrently computing the resolved material bindings for a vector of UsdPrims, prims for the given materialPurpose.

The size of the returned vector always matches the size of the input vector, prims. If a prim is not bound to any material, an invalid or empty UsdShadeMaterial is returned at the index corresponding to it.

If the pointer bindingRels points to a valid vector, then it is populated with the set of all "winning" binding relationships.

In order for backward compatibility with old assets not having MaterialBindingAPI applied, supportLegacyBindings defaults to true. Though its recommended for clients to update the assets to have MaterialBindingAPI applied for optimized computation of bound material.

Note: In a future release the default for supportLegacyBindings will be updated to "false".

The python version of this method returns a tuple containing two lists - the bound materials and the corresponding "winning" binding relationships.

◆ CreateMaterialBindSubset()

USDSHADE_API UsdGeomSubset CreateMaterialBindSubset ( const TfToken subsetName,
const VtIntArray &  indices,
const TfToken elementType = UsdGeomTokens->face 
)

Creates a GeomSubset named subsetName with element type, elementType and familyName materialBind below this prim.

If a GeomSubset named subsetName already exists, then its "familyName" is updated to be UsdShadeTokens->materialBind and its indices (at default timeCode) are updated with the provided indices value before returning.

This method forces the familyType of the "materialBind" family of subsets to UsdGeomTokens->nonOverlapping if it's unset or explicitly set to UsdGeomTokens->unrestricted.

The default value elementType is UsdGeomTokens->face, as we expect materials to be bound most often to subsets of faces on meshes.

◆ Get()

static USDSHADE_API UsdShadeMaterialBindingAPI Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdShadeMaterialBindingAPI holding the prim adhering to this schema at path on stage.

If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdShadeMaterialBindingAPI(stage->GetPrimAtPath(path));

◆ GetCollectionBindingRel()

USDSHADE_API UsdRelationship GetCollectionBindingRel ( const TfToken bindingName,
const TfToken materialPurpose = UsdShadeTokens->allPurpose 
) const

Returns the collection-based material-binding relationship with the given bindingName and materialPurpose on this prim.

For info on bindingName, see UsdShadeMaterialBindingAPI::Bind(). The material purpose of the relationship that's returned will match the specified materialPurpose.

◆ GetCollectionBindingRels()

USDSHADE_API std::vector< UsdRelationship > GetCollectionBindingRels ( const TfToken materialPurpose = UsdShadeTokens->allPurpose) const

Returns the list of collection-based material binding relationships on this prim for the given material purpose, materialPurpose.

The returned list of binding relationships will be in native property order. See UsdPrim::GetPropertyOrder(), UsdPrim::SetPropertyOrder(). Bindings that appear earlier in the property order are considered to be stronger than the ones that come later. See rule #6 in UsdShadeMaterialBindingAPI_MaterialResolution.

◆ GetCollectionBindings()

USDSHADE_API CollectionBindingVector GetCollectionBindings ( const TfToken materialPurpose = UsdShadeTokens->allPurpose) const

Returns all the collection-based bindings on this prim for the given material purpose.

The returned CollectionBinding objects always have the specified materialPurpose (i.e. the all-purpose binding is not returned if a special purpose binding is requested).

If one or more collection based bindings are to prims that are not Materials, this does not generate an error, but the corresponding Material(s) will be invalid (i.e. evaluate to false).

The python version of this API returns a tuple containing the vector of CollectionBinding objects and the corresponding vector of binding relationships.

The returned list of collection-bindings will be in native property order of the associated binding relationships. See UsdPrim::GetPropertyOrder(), UsdPrim::SetPropertyOrder(). Binding relationships that come earlier in the list are considered to be stronger than the ones that come later. See rule #6 in UsdShadeMaterialBindingAPI_MaterialResolution.

◆ GetDirectBinding()

USDSHADE_API DirectBinding GetDirectBinding ( const TfToken materialPurpose = UsdShadeTokens->allPurpose) const

Computes and returns the direct binding for the given material purpose on this prim.

The returned binding always has the specified materialPurpose (i.e. the all-purpose binding is not returned if a special purpose binding is requested).

If the direct binding is to a prim that is not a Material, this does not generate an error, but the returned Material will be invalid (i.e. evaluate to false).

◆ GetDirectBindingRel()

USDSHADE_API UsdRelationship GetDirectBindingRel ( const TfToken materialPurpose = UsdShadeTokens->allPurpose) const

Returns the direct material-binding relationship on this prim for the given material purpose.

The material purpose of the relationship that's returned will match the specified materialPurpose.

◆ GetMaterialBindingStrength()

static USDSHADE_API TfToken GetMaterialBindingStrength ( const UsdRelationship bindingRel)
static

Resolves the 'bindMaterialAs' token-valued metadata on the given binding relationship and returns it.

If the resolved value is empty, this returns the fallback value UsdShadeTokens->weakerThanDescendants.

See also
UsdShadeMaterialBindingAPI::SetMaterialBindingStrength()

◆ GetMaterialBindSubsets()

USDSHADE_API std::vector< UsdGeomSubset > GetMaterialBindSubsets ( )

Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.

◆ GetMaterialBindSubsetsFamilyType()

USDSHADE_API TfToken GetMaterialBindSubsetsFamilyType ( )

Returns the familyType of the family of "materialBind" GeomSubsets on this prim.

By default, materialBind subsets have familyType="nonOverlapping", but they can also be tagged as a "partition", using SetMaterialBindFaceSubsetsFamilyType().

See also
UsdGeomSubset::GetFamilyNameAttr

◆ GetMaterialPurposes()

static USDSHADE_API TfTokenVector GetMaterialPurposes ( )
static

Returns a vector of the possible values for the 'material purpose'.

◆ GetResolvedTargetPathFromBindingRel()

static USDSHADE_API const SdfPath GetResolvedTargetPathFromBindingRel ( const UsdRelationship bindingRel)
static

returns the path of the resolved target identified by bindingRel.

◆ GetSchemaAttributeNames()

static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames ( bool  includeInherited = true)
static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

◆ RemovePrimFromBindingCollection()

USDSHADE_API bool RemovePrimFromBindingCollection ( const UsdPrim prim,
const TfToken bindingName,
const TfToken materialPurpose 
) const

Removes the specified prim from the collection targeted by the binding relationship corresponding to given bindingName and materialPurpose.

If the collection-binding relationship doesn't exist or if the targeted collection does not include the prim, then this does nothing and returns true.

If the targeted collection includes prim, then this modifies the collection by removing the prim from it (by invoking UsdCollectionAPI::RemovePrim()). This method can be used in conjunction with the Unbind*() methods (if desired) to guarantee that a prim has no resolved material binding.

◆ SetMaterialBindingStrength()

static USDSHADE_API bool SetMaterialBindingStrength ( const UsdRelationship bindingRel,
const TfToken bindingStrength 
)
static

Sets the 'bindMaterialAs' token-valued metadata on the given binding relationship.

If bindingStrength is UsdShadeTokens->fallbackStrength, the value UsdShadeTokens->weakerThanDescendants is authored sparsely, i.e. only when there is a different existing bindingStrength value. To stamp out the bindingStrength value explicitly, clients can pass in UsdShadeTokens->weakerThanDescendants or UsdShadeTokens->strongerThanDescendants directly. Returns true on success, false otherwise.

See also
UsdShadeMaterialBindingAPI::GetMaterialBindingStrength()

◆ SetMaterialBindSubsetsFamilyType()

USDSHADE_API bool SetMaterialBindSubsetsFamilyType ( const TfToken familyType)

Author the familyType of the "materialBind" family of GeomSubsets on this prim.

The default familyType is UsdGeomTokens->nonOverlapping. It can be set to UsdGeomTokens->partition to indicate that the entire imageable prim is included in the union of all the "materialBind" subsets. The family type should never be set to UsdGeomTokens->unrestricted, since it is invalid for a single piece of geometry (in this case, a subset) to be bound to more than one material. Hence, a coding error is issued if familyType is UsdGeomTokens->unrestricted.

See also
UsdGeomSubset::SetFamilyType

◆ UnbindAllBindings()

USDSHADE_API bool UnbindAllBindings ( ) const

Unbinds all direct and collection-based bindings on this prim.

◆ UnbindCollectionBinding()

USDSHADE_API bool UnbindCollectionBinding ( const TfToken bindingName,
const TfToken materialPurpose = UsdShadeTokens->allPurpose 
) const

Unbinds the collection-based binding with the given bindingName, for the given materialPurpose on this prim.

It accomplishes this by blocking the targets of the associated binding relationship in the current edit target.

If a binding was created without specifying a bindingName, then the correct bindingName to use for unbinding is the instance name of the targetted collection.

This does not remove the UsdShadeMaterialBindingAPI schema application.

◆ UnbindDirectBinding()

USDSHADE_API bool UnbindDirectBinding ( const TfToken materialPurpose = UsdShadeTokens->allPurpose) const

Unbinds the direct binding for the given material purpose (materialPurpose) on this prim.

It accomplishes this by blocking the targets of the binding relationship in the current edit target.

This does not remove the UsdShadeMaterialBindingAPI schema application.

Friends And Related Function Documentation

◆ BindingsAtPrim

friend struct BindingsAtPrim
friend

BindingsAtPrim needs to invoke private _GetCollectionBindings().

Definition at line 712 of file materialBindingAPI.h.

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 232 of file materialBindingAPI.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI
static

Compile time constant representing what kind of schema this class is.

See also
UsdSchemaKind

Definition at line 140 of file materialBindingAPI.h.


The documentation for this class was generated from the following file: