usdrt::UsdShadeMaterialBindingAPI

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

Functions

Variables

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:<i>purpose</i></b>. A direct binding relationship

    must have a single target path that points to a <b>UsdShadeMaterial</b>.</li>

    <li>

    In the case of a collection-based binding, the <i>allPurpose</i> binding is

    represented by a relationship named

    ”material:binding:collection:

    ”, where

    <b>bindingName</b> 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

    <b>UsdShadeMaterial</b>. 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>

    <b>Note:</b> Both <b>bindingName</b> and <b>purpose</b> 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><b>Two tokens</b>: the fallback, “all purpose”, direct binding,

    <i>material:binding</i></li>

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

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

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

    material:binding:collection:metalBits</li>

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

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

    </ul>

    A <b>binding-strength</b> 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 <b>’bindMaterialAs’</b> for future flexibility, even though for

    now, there are only two possible values:

    <i>UsdShadeTokens->weakerThanDescendants</i> and

    <i>UsdShadeTokens->strongerThanDescendants</i>. 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 operator bool() const

Boolean operator.

Returns

Return true if the contained prim is has this api schema applied using HasAPI, and false otherwise.

UsdPrim GetPrim() const

Return this schema object’s held prim.

SdfPath GetPath() const

Return the SdfPath to this schema object’s 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.