|
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>
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 | |
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 UsdPrimDefinition * | GetSchemaClassPrimDefinition () 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 TfTokenVector & | GetSchemaAttributeNames (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 TfTokenVector & | GetSchemaAttributeNames (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 TfTokenVector & | GetSchemaAttributeNames (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< 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 . | |
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:
| |
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< UsdShadeMaterial > | ComputeBoundMaterials (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.
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.
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. UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims... Definition: materialBindingAPI.h:135 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< UsdGeomSubset > | GetMaterialBindSubsets () |
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. | |
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:
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.
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.
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.
Definition at line 134 of file materialBindingAPI.h.
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.
using CollectionBindingVector = std::vector<CollectionBinding> |
Definition at line 414 of file materialBindingAPI.h.
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.
using DirectBindingPtr = std::unique_ptr<DirectBinding> |
Alias for a unique_ptr to a DirectBinding object.
Definition at line 682 of file materialBindingAPI.h.
|
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.
|
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.
|
virtual |
Destructor.
|
overrideprotectedvirtual |
Returns the kind of schema this class belongs to.
Reimplemented from UsdAPISchemaBase.
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()).
|
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.
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.
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.
|
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.
|
static |
Test whether a given name
contains the "material:binding:" prefix.
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++:
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 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 |
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 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 |
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:
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
.
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.
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.
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).
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
.
|
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.
USDSHADE_API std::vector< UsdGeomSubset > GetMaterialBindSubsets | ( | ) |
Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.
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().
|
static |
Returns a vector of the possible values for the 'material purpose'.
|
static |
returns the path of the resolved target identified by bindingRel
.
|
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 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 |
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.
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.
USDSHADE_API bool UnbindAllBindings | ( | ) | const |
Unbinds all direct and collection-based bindings 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.
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.
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.
|
friend |
BindingsAtPrim needs to invoke private _GetCollectionBindings().
Definition at line 712 of file materialBindingAPI.h.
|
friend |
Definition at line 232 of file materialBindingAPI.h.
|
static |
Compile time constant representing what kind of schema this class is.
Definition at line 140 of file materialBindingAPI.h.