usdrt::UsdShadeMaterialBindingAPI

Defined in usdrt/scenegraph/usd/usdShade/materialBindingAPI.h

class UsdShadeMaterialBindingAPI : public usdrt::UsdAPISchemaBase 

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.</li>

<li>

In the case of a collection-based binding, the allPurpose binding is

represented by a relationship named

”material:binding:collection:

”, 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:

”.

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.

</li>

</ul>

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.

<ul><li>Two tokens: the fallback, “all purpose”, direct binding,

material:binding</li>

<li>Three tokens: a purpose-restricted, direct, fallback binding,

e.g. material:binding:preview</li>

<li>Four tokens: an all-purpose, collection-based binding, e.g.

material:binding:collection:metalBits</li>

<li>Five tokens: a purpose-restricted, collection-based binding,

e.g. material:binding:collection:full:metalBits</li>

</ul>

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
properties.

Public Functions

inline explicit UsdShadeMaterialBindingAPI(const UsdPrim &prim = UsdPrim()): 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.

inline explicit UsdShadeMaterialBindingAPI(const UsdSchemaBase &schemaObj): Construct a UsdShadeMaterialBindingAPI on the prim held by schemaObj . Should be preferred over UsdShadeMaterialBindingAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdShadeMaterialBindingAPI(): Destructor.

inline 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.

At the moment bindingStrength and materialPurpose is not supported.

Returns true on success, false otherwise.

inline bool UnbindAllBindings() const: Unbinds all direct and collection-based bindings on this prim.

inline UsdShadeMaterial ComputeBoundMaterial(const TfToken &materialPurpose = UsdShadeTokens->allPurpose, UsdRelationship *bindingRel = nullptr) 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.

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.

UsdPrim GetPrim() const: Return this schema object’s held prim.

SdfPath GetPath() const: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

Returns: True if the help prim is valid, and the schema object is compatible with its held prim.

Public Static Functions

static inline UsdShadeMaterialBindingAPI Apply(const UsdPrim &prim)

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.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

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.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::SingleApplyAPI 

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

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

inline const TfToken _GetType() const

Helper for subclasses to get this schema’s type token.

Note

This diverges from Usd and returns a TfToken, since we don’t implements TfType.

Returns: The token representing the schema’s TfType.