#include <materialBindingAPI.h>

Inheritance diagram for UsdShadeMaterialBindingAPI:

Classes
struct	BindingsAtPrim

class	CollectionBinding

class	DirectBinding

Public Member Functions
	UsdShadeMaterialBindingAPI (const UsdPrim &prim=UsdPrim())

	UsdShadeMaterialBindingAPI (const UsdSchemaBase &schemaObj)

virtual USDSHADE_API	~UsdShadeMaterialBindingAPI ()
	Destructor. More...

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

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

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

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

USDSHADE_API bool	UnbindAllBindings () const
	Unbinds all direct and collection-based bindings on this prim. More...

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

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

Public Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj)

virtual USD_API	~UsdAPISchemaBase ()=0
	Destructor. More...

Public Member Functions inherited from UsdSchemaBase
bool	IsConcrete () const

bool	IsTyped () const

bool	IsAPISchema () const
	Returns whether this is an API schema or not. More...

bool	IsAppliedAPISchema () const

bool	IsMultipleApplyAPISchema () const

UsdSchemaKind	GetSchemaKind () const
	Returns the kind of schema this class is. More...

USD_API	UsdSchemaBase (const UsdPrim &prim=UsdPrim())
	Construct and store `prim` as the held prim. More...

USD_API	UsdSchemaBase (const UsdSchemaBase &otherSchema)
	Construct and store for the same prim held by `otherSchema`. More...

virtual USD_API	~UsdSchemaBase ()
	Destructor. More...

USD_API	operator bool () const

UsdPrim	GetPrim () const
	Return this schema object's held prim. More...

SdfPath	GetPath () const
	Shorthand for GetPrim()->GetPath(). More...

USD_API const UsdPrimDefinition *	GetSchemaClassPrimDefinition () const

Static Public Member Functions
static USDSHADE_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

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

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

static USDSHADE_API UsdShadeMaterialBindingAPI	Apply (const UsdPrim &prim)

Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

Static Public Attributes
static const UsdSchemaKind	schemaKind = UsdSchemaKind::SingleApplyAPI

Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase

Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase

Protected Member Functions
USDSHADE_API UsdSchemaKind	_GetSchemaKind () const override

Protected Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)

const TfToken &	_GetInstanceName () const

USD_API bool	_IsCompatible () const override

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

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

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

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

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

static USDSHADE_API TfToken	GetMaterialBindingStrength (const UsdRelationship &bindingRel)

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

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 >

using	DirectBindingPtr = std::unique_ptr< DirectBinding >
	Alias for a unique_ptr to a DirectBinding object. More...

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

struct	BindingsAtPrim
	BindingsAtPrim needs to invoke private _GetCollectionBindings(). More...

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

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

static USDSHADE_API TfTokenVector	GetMaterialPurposes ()
	Returns a vector of the possible values for the 'material purpose'. More...

static USDSHADE_API const SdfPath	GetResolvedTargetPathFromBindingRel (const UsdRelationship &bindingRel)
	returns the path of the resolved target identified by `bindingRel`. More...

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)

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. UsdGeomImageable mesh = UsdGeomImageable::Get(stage, SdfPath("/path/to/meshPrim"); // Get the materials to bind to. UsdShadeMaterial plastic = UsdShadeMaterial::Get(stage, SdfPath("/path/to/PlasticMaterial"); UsdShadeMaterial metal = UsdShadeMaterial::Get(stage, 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. UsdShadeMaterialBindingAPI::Apply(plasticSubset.GetPrim()).Bind(plastic) UsdShadeMaterialBindingAPI::Apply(metalSubset.GetPrim()).Bind(metal)
USDSHADE_API UsdGeomSubset	CreateMaterialBindSubset (const TfToken &subsetName, const VtIntArray &indices, const TfToken &elementType=UsdGeomTokens->face)

USDSHADE_API std::vector < UsdGeomSubset >	GetMaterialBindSubsets ()

USDSHADE_API bool	SetMaterialBindSubsetsFamilyType (const TfToken &familyType)

USDSHADE_API TfToken	GetMaterialBindSubsetsFamilyType ()

static USDSHADE_API bool	CanContainPropertyName (const TfToken &name)

Additional Inherited Members
Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector	_GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)

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 151 of file materialBindingAPI.h.

Member Typedef Documentation

using UsdShadeMaterialBindingAPI::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 736 of file materialBindingAPI.h.

using UsdShadeMaterialBindingAPI::CollectionBindingVector = std::vector<CollectionBinding>

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.

Definition at line 431 of file materialBindingAPI.h.

using UsdShadeMaterialBindingAPI::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 696 of file materialBindingAPI.h.

using UsdShadeMaterialBindingAPI::DirectBindingPtr = std::unique_ptr<DirectBinding>

Alias for a unique_ptr to a DirectBinding object.

Definition at line 699 of file materialBindingAPI.h.

Constructor & Destructor Documentation

UsdShadeMaterialBindingAPI::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 163 of file materialBindingAPI.h.

UsdShadeMaterialBindingAPI::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 171 of file materialBindingAPI.h.

virtual USDSHADE_API UsdShadeMaterialBindingAPI::~UsdShadeMaterialBindingAPI ( )

virtual

Destructor.

Member Function Documentation

USDSHADE_API UsdSchemaKind UsdShadeMaterialBindingAPI::_GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also: UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

USDSHADE_API bool UsdShadeMaterialBindingAPI::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()).

static USDSHADE_API UsdShadeMaterialBindingAPI 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()

USDSHADE_API bool UsdShadeMaterialBindingAPI::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.

USDSHADE_API bool UsdShadeMaterialBindingAPI::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.

static USDSHADE_API bool UsdShadeMaterialBindingAPI::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()

static USDSHADE_API bool UsdShadeMaterialBindingAPI::CanContainPropertyName ( const TfToken & name )

static

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

USDSHADE_API UsdShadeMaterial UsdShadeMaterialBindingAPI::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; 
UsdShadeMaterialBindingAPI::BindingsCache bindingsCache;
UsdShadeMaterialBindingAPI::CollectionQueryCache collQueryCache;
for (auto prim : UsdPrimRange(rootPrim)) {
    UsdShadeMaterial boundMaterial = 
          UsdShadeMaterialBindingAPI(prim).ComputeBoundMaterial(
          &bindingsCache, &collQueryCache);
    if (boundMaterial) {
        primBindings.emplace_back({prim, boundMaterial});
    }
}

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.

USDSHADE_API UsdShadeMaterial UsdShadeMaterialBindingAPI::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.

static USDSHADE_API std::vector<UsdShadeMaterial> UsdShadeMaterialBindingAPI::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.

USDSHADE_API UsdGeomSubset UsdShadeMaterialBindingAPI::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.

static USDSHADE_API UsdShadeMaterialBindingAPI 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));

USDSHADE_API UsdRelationship UsdShadeMaterialBindingAPI::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.

USDSHADE_API std::vector<UsdRelationship> UsdShadeMaterialBindingAPI::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.

USDSHADE_API CollectionBindingVector UsdShadeMaterialBindingAPI::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.

USDSHADE_API DirectBinding UsdShadeMaterialBindingAPI::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).

USDSHADE_API UsdRelationship UsdShadeMaterialBindingAPI::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.

static USDSHADE_API TfToken UsdShadeMaterialBindingAPI::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()

USDSHADE_API std::vector<UsdGeomSubset> UsdShadeMaterialBindingAPI::GetMaterialBindSubsets ( )

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

USDSHADE_API TfToken UsdShadeMaterialBindingAPI::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

static USDSHADE_API TfTokenVector UsdShadeMaterialBindingAPI::GetMaterialPurposes ( )

static

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

static USDSHADE_API const SdfPath UsdShadeMaterialBindingAPI::GetResolvedTargetPathFromBindingRel ( const UsdRelationship & bindingRel )

static

returns the path of the resolved target identified by bindingRel.

static USDSHADE_API const TfTokenVector& UsdShadeMaterialBindingAPI::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.

USDSHADE_API bool UsdShadeMaterialBindingAPI::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.

static USDSHADE_API bool UsdShadeMaterialBindingAPI::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()

USDSHADE_API bool UsdShadeMaterialBindingAPI::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.

Friends And Related Function Documentation

friend struct BindingsAtPrim

friend

BindingsAtPrim needs to invoke private _GetCollectionBindings().

Definition at line 729 of file materialBindingAPI.h.

friend class UsdSchemaRegistry

friend

Definition at line 249 of file materialBindingAPI.h.

Member Data Documentation

const UsdSchemaKind UsdShadeMaterialBindingAPI::schemaKind = UsdSchemaKind::SingleApplyAPI

static

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

See Also: UsdSchemaKind

Definition at line 157 of file materialBindingAPI.h.

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

pxr/usd/usdShade/materialBindingAPI.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Schema property and associated data retrieval API

Bound Material Resolution

Binding materials to subsets

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation