UsdShade module#

Summary: The UsdShade module provides schemas and behaviors for creating and binding materials, which encapsulate shading networks.

Classes:

`AttributeType`
`ConnectableAPI`	UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and making connections between shading parameters and outputs.
`ConnectionModification`
`ConnectionSourceInfo`	A compact struct to represent a bundle of information about an upstream source attribute.
`CoordSysAPI`	UsdShadeCoordSysAPI provides a way to designate, name, and discover coordinate systems.
`Input`	This class encapsulates a shader or node-graph input, which is a connectable attribute representing a typed value.
`Material`	A Material provides a container into which multiple"render targets"can add data that defines a"shading material"for a renderer.
`MaterialBindingAPI`	UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims or collections of prims (represented by UsdCollectionAPI objects).
`NodeDefAPI`	UsdShadeNodeDefAPI is an API schema that provides attributes for a prim to select a corresponding Shader Node Definition ("Sdr Node"), as well as to look up a runtime entry for that shader node in the form of an SdrShaderNode.
`NodeGraph`	A node-graph is a container for shading nodes, as well as other node- graphs.
`Output`	This class encapsulates a shader or node-graph output, which is a connectable attribute representing a typed, externally computed value.
`Shader`	Base class for all USD shaders.
`ShaderDefParserPlugin`	Parses shader definitions represented using USD scene description using the schemas provided by UsdShade.
`ShaderDefUtils`	This class contains a set of utility functions used for populating the shader registry with shaders definitions specified using UsdShade schemas.
`Tokens`
`Utils`	This class contains a set of utility functions used when authoring and querying shading networks.

class pxr.UsdShade.AttributeType#

Attributes:

`Input`
`Invalid`
`Output`
`names`
`values`

Input = pxr.UsdShade.AttributeType.Input#

Invalid = pxr.UsdShade.AttributeType.Invalid#

Output = pxr.UsdShade.AttributeType.Output#

names = {'Input': pxr.UsdShade.AttributeType.Input, 'Invalid': pxr.UsdShade.AttributeType.Invalid, 'Output': pxr.UsdShade.AttributeType.Output}#

values = {0: pxr.UsdShade.AttributeType.Invalid, 1: pxr.UsdShade.AttributeType.Input, 2: pxr.UsdShade.AttributeType.Output}#

class pxr.UsdShade.ConnectableAPI#

UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and making connections between shading parameters and outputs. The interface is common to all UsdShade schemas that support Inputs and Outputs, which currently includes UsdShadeShader, UsdShadeNodeGraph, and UsdShadeMaterial.

One can construct a UsdShadeConnectableAPI directly from a UsdPrim, or from objects of any of the schema classes listed above. If it seems onerous to need to construct a secondary schema object to interact with Inputs and Outputs, keep in mind that any function whose purpose is either to walk material/shader networks via their connections, or to create such networks, can typically be written entirely in terms of UsdShadeConnectableAPI objects, without needing to care what the underlying prim type is.

Additionally, the most common UsdShadeConnectableAPI behaviors (creating Inputs and Outputs, and making connections) are wrapped as convenience methods on the prim schema classes (creation) and UsdShadeInput and UsdShadeOutput.

Methods:

`CanConnect`	classmethod CanConnect(input, source) -> bool
`ClearSource`	classmethod ClearSource(shadingAttr) -> bool
`ClearSources`	classmethod ClearSources(shadingAttr) -> bool
`ConnectToSource`	classmethod ConnectToSource(shadingAttr, source, mod) -> bool
`CreateInput`(name, typeName)	Create an input which can both have a value and be connected.
`CreateOutput`(name, typeName)	Create an output, which represents and externally computed, typed value.
`DisconnectSource`	classmethod DisconnectSource(shadingAttr, sourceAttr) -> bool
`Get`	classmethod Get(stage, path) -> ConnectableAPI
`GetConnectedSource`	classmethod GetConnectedSource(shadingAttr, source, sourceName, sourceType) -> bool
`GetConnectedSources`	classmethod GetConnectedSources(shadingAttr, invalidSourcePaths) -> list[UsdShadeSourceInfo]
`GetInput`(name)	Return the requested input if it exists.
`GetInputs`(onlyAuthored)	Returns all inputs on the connectable prim (i.e.
`GetOutput`(name)	Return the requested output if it exists.
`GetOutputs`(onlyAuthored)	Returns all outputs on the connectable prim (i.e.
`GetRawConnectedSourcePaths`	classmethod GetRawConnectedSourcePaths(shadingAttr, sourcePaths) -> bool
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`HasConnectableAPI`	classmethod HasConnectableAPI(schemaType) -> bool
`HasConnectedSource`	classmethod HasConnectedSource(shadingAttr) -> bool
`IsContainer`()	Returns true if the prim is a container.
`IsSourceConnectionFromBaseMaterial`	classmethod IsSourceConnectionFromBaseMaterial(shadingAttr) -> bool
`RequiresEncapsulation`()	Returns true if container encapsulation rules should be respected when evaluating connectibility behavior, false otherwise.
`SetConnectedSources`	classmethod SetConnectedSources(shadingAttr, sourceInfos) -> bool

static CanConnect()#

classmethod CanConnect(input, source) -> bool

Determines whether the given input can be connected to the given source attribute, which can be an input or an output.

The result depends on the”connectability”of the input and the source attributes. Depending on the prim type, this may require the plugin that defines connectability behavior for that prim type be loaded.

UsdShadeInput::SetConnectability

UsdShadeInput::GetConnectability

Parameters:

input (Input)
source (Attribute)

CanConnect(input, sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourceInput (Input)

CanConnect(input, sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourceOutput (Output)

CanConnect(output, source) -> bool

Determines whether the given output can be connected to the given source attribute, which can be an input or an output.

An output is considered to be connectable only if it belongs to a node-graph. Shader outputs are not connectable.

source is an optional argument. If a valid UsdAttribute is supplied for it, this method will return true only if the source attribute is owned by a descendant of the node-graph owning the output.

Parameters:

output (Output)
source (Attribute)

CanConnect(output, sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourceInput (Input)

CanConnect(output, sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourceOutput (Output)

static ClearSource()#

classmethod ClearSource(shadingAttr) -> bool

Deprecated

This is the older version that only referenced a single source. Please use ClearSources instead.

Parameters:: shadingAttr (Attribute)

ClearSource(input) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: input (Input)

ClearSource(output) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: output (Output)

static ClearSources()#

classmethod ClearSources(shadingAttr) -> bool

Clears sources for this shading attribute in the current UsdEditTarget.

Most of the time, what you probably want is DisconnectSource() rather than this function.

DisconnectSource()

Parameters:: shadingAttr (Attribute)

ClearSources(input) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: input (Input)

ClearSources(output) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: output (Output)

static ConnectToSource()#

classmethod ConnectToSource(shadingAttr, source, mod) -> bool

Authors a connection for a given shading attribute shadingAttr .

shadingAttr can represent a parameter, an input or an output. source is a struct that describes the upstream source attribute with all the information necessary to make a connection. See the documentation for UsdShadeConnectionSourceInfo. mod describes the operation that should be applied to the list of connections. By default the new connection will replace any existing connections, but it can add to the list of connections to represent multiple input connections.

true if a connection was created successfully. false if shadingAttr or source is invalid.

This method does not verify the connectability of the shading attribute to the source. Clients must invoke CanConnect() themselves to ensure compatibility.

The source shading attribute is created if it doesn’t exist already.

Parameters:

shadingAttr (Attribute)
source (ConnectionSourceInfo)
mod (ConnectionModification)

ConnectToSource(input, source, mod) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
source (ConnectionSourceInfo)
mod (ConnectionModification)

ConnectToSource(output, source, mod) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
source (ConnectionSourceInfo)
mod (ConnectionModification)

ConnectToSource(shadingAttr, source, sourceName, sourceType, typeName) -> bool

Deprecated

Please use the versions that take a UsdShadeConnectionSourceInfo to describe the upstream source This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

shadingAttr (Attribute)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)
typeName (ValueTypeName)

ConnectToSource(input, source, sourceName, sourceType, typeName) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)
typeName (ValueTypeName)

ConnectToSource(output, source, sourceName, sourceType, typeName) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)
typeName (ValueTypeName)

ConnectToSource(shadingAttr, sourcePath) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Connect the given shading attribute to the source at path, sourcePath .

sourcePath should be the fully namespaced property path.

This overload is provided for convenience, for use in contexts where the prim types are unknown or unavailable.

Parameters:

shadingAttr (Attribute)
sourcePath (Path)

ConnectToSource(input, sourcePath) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourcePath (Path)

ConnectToSource(output, sourcePath) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourcePath (Path)

ConnectToSource(shadingAttr, sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Connect the given shading attribute to the given source input.

Parameters:

shadingAttr (Attribute)
sourceInput (Input)

ConnectToSource(input, sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourceInput (Input)

ConnectToSource(output, sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourceInput (Input)

ConnectToSource(shadingAttr, sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Connect the given shading attribute to the given source output.

Parameters:

shadingAttr (Attribute)
sourceOutput (Output)

ConnectToSource(input, sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourceOutput (Output)

ConnectToSource(output, sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourceOutput (Output)

CreateInput(name, typeName) → Input#

Create an input which can both have a value and be connected.

The attribute representing the input is created in the”inputs:”namespace.

Parameters:

name (str)
typeName (ValueTypeName)

CreateOutput(name, typeName) → Output#

Create an output, which represents and externally computed, typed value.

Outputs on node-graphs can be connected.

The attribute representing an output is created in the”outputs:”namespace.

Parameters:

name (str)
typeName (ValueTypeName)

static DisconnectSource()#

classmethod DisconnectSource(shadingAttr, sourceAttr) -> bool

Disconnect source for this shading attribute.

If sourceAttr is valid it will disconnect the connection to this upstream attribute. Otherwise it will disconnect all connections by authoring an empty list of connections for the attribute shadingAttr .

This may author more scene description than you might expect - we define the behavior of disconnect to be that, even if a shading attribute becomes connected in a weaker layer than the current UsdEditTarget, the attribute will still be disconnected in the composition, therefore we must”block”it in the current UsdEditTarget.

ConnectToSource() .

Parameters:

shadingAttr (Attribute)
sourceAttr (Attribute)

DisconnectSource(input, sourceAttr) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourceAttr (Attribute)

DisconnectSource(output, sourceAttr) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourceAttr (Attribute)

static Get()#

classmethod Get(stage, path) -> ConnectableAPI

Return a UsdShadeConnectableAPI 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:

UsdShadeConnectableAPI(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

static GetConnectedSource()#

classmethod GetConnectedSource(shadingAttr, source, sourceName, sourceType) -> bool

Deprecated

Shading attributes can have multiple connections and so using GetConnectedSources is needed in general

Finds the source of a connection for the given shading attribute.

shadingAttr is the shading attribute whose connection we want to interrogate. source is an output parameter which will be set to the source connectable prim. sourceName will be set to the name of the source shading attribute, which may be an input or an output, as specified by sourceType sourceType will have the type of the source shading attribute, i.e. whether it is an Input or Output

true if the shading attribute is connected to a valid, defined source attribute. false if the shading attribute is not connected to a single, defined source attribute.

Previously this method would silently return false for multiple connections. We are changing the behavior of this method to return the result for the first connection and issue a TfWarn about it. We want to encourage clients to use GetConnectedSources going forward.

The python wrapping for this method returns a (source, sourceName, sourceType) tuple if the parameter is connected, else None

Parameters:

shadingAttr (Attribute)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)

GetConnectedSource(input, source, sourceName, sourceType) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)

GetConnectedSource(output, source, sourceName, sourceType) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)

static GetConnectedSources()#

classmethod GetConnectedSources(shadingAttr, invalidSourcePaths) -> list[UsdShadeSourceInfo]

Finds the valid sources of connections for the given shading attribute.

shadingAttr is the shading attribute whose connections we want to interrogate. invalidSourcePaths is an optional output parameter to collect the invalid source paths that have not been reported in the returned vector.

Returns a vector of UsdShadeConnectionSourceInfo structs with information about each upsteam attribute. If the vector is empty, there have been no connections.

A valid connection requires the existence of the source attribute and also requires that the source prim is UsdShadeConnectableAPI compatible.

The python wrapping returns a tuple with the valid connections first, followed by the invalid source paths.

Parameters:

shadingAttr (Attribute)
invalidSourcePaths (list[Path])

GetConnectedSources(input, invalidSourcePaths) -> list[UsdShadeSourceInfo]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
invalidSourcePaths (list[Path])

GetConnectedSources(output, invalidSourcePaths) -> list[UsdShadeSourceInfo]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
invalidSourcePaths (list[Path])

GetInput(name) → Input#

Return the requested input if it exists.

name is the unnamespaced base name.

Parameters:: name (str)

GetInputs(onlyAuthored) → list[Input]#

Returns all inputs on the connectable prim (i.e.

shader or node-graph). Inputs are represented by attributes in the”inputs:”namespace. If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un- authored builtins.

Parameters:: onlyAuthored (bool)

GetOutput(name) → Output#

Return the requested output if it exists.

name is the unnamespaced base name.

Parameters:: name (str)

GetOutputs(onlyAuthored) → list[Output]#

Returns all outputs on the connectable prim (i.e.

shader or node-graph). Outputs are represented by attributes in the”outputs:”namespace. If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un- authored builtins.

Parameters:: onlyAuthored (bool)

static GetRawConnectedSourcePaths()#

classmethod GetRawConnectedSourcePaths(shadingAttr, sourcePaths) -> bool

Deprecated

Please us GetConnectedSources to retrieve multiple connections

Returns the”raw”(authored) connected source paths for the given shading attribute.

Parameters:

shadingAttr (Attribute)
sourcePaths (list[Path])

GetRawConnectedSourcePaths(input, sourcePaths) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

input (Input)
sourcePaths (list[Path])

GetRawConnectedSourcePaths(output, sourcePaths) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
sourcePaths (list[Path])

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

static HasConnectableAPI()#

classmethod HasConnectableAPI(schemaType) -> bool

Return true if the schemaType has a valid connectableAPIBehavior registered, false otherwise.

To check if a prim’s connectableAPI has a behavior defined, use UsdSchemaBase::operator bool() .

Parameters:: schemaType (Type)

HasConnectableAPI() -> bool

Return true if the schema type T has a connectableAPIBehavior registered, false otherwise.

static HasConnectedSource()#

classmethod HasConnectedSource(shadingAttr) -> bool

Returns true if and only if the shading attribute is currently connected to at least one valid (defined) source.

If you will be calling GetConnectedSources() afterwards anyways, it will be much faster to instead check if the returned vector is empty:

UsdShadeSourceInfoVector connections =
    UsdShadeConnectableAPI::GetConnectedSources(attribute);
if (!connections.empty()){
     // process connected attribute
} else {
     // process unconnected attribute
}

Parameters:: shadingAttr (Attribute)

HasConnectedSource(input) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: input (Input)

HasConnectedSource(output) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: output (Output)

IsContainer() → bool#

Returns true if the prim is a container.

The underlying prim type may provide runtime behavior that defines whether it is a container.

static IsSourceConnectionFromBaseMaterial()#

classmethod IsSourceConnectionFromBaseMaterial(shadingAttr) -> bool

Returns true if the connection to the given shading attribute’s source, as returned by UsdShadeConnectableAPI::GetConnectedSource() , is authored across a specializes arc, which is used to denote a base material.

Parameters:: shadingAttr (Attribute)

IsSourceConnectionFromBaseMaterial(input) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: input (Input)

IsSourceConnectionFromBaseMaterial(output) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: output (Output)

RequiresEncapsulation() → bool#

Returns true if container encapsulation rules should be respected when evaluating connectibility behavior, false otherwise.

The underlying prim type may provide runtime behavior that defines if encapsulation rules are respected or not.

static SetConnectedSources()#

classmethod SetConnectedSources(shadingAttr, sourceInfos) -> bool

Authors a list of connections for a given shading attribute shadingAttr .

shadingAttr can represent a parameter, an input or an output. sourceInfos is a vector of structs that describes the upstream source attributes with all the information necessary to make all the connections. See the documentation for UsdShadeConnectionSourceInfo.

true if all connection were created successfully. false if the shadingAttr or one of the sources are invalid.

A valid connection is one that has a valid UsdShadeConnectionSourceInfo , which requires the existence of the upstream source prim. It does not require the existence of the source attribute as it will be create if necessary.

Parameters:

shadingAttr (Attribute)
sourceInfos (list[ConnectionSourceInfo])

class pxr.UsdShade.ConnectionModification#

Attributes:

`Append`
`Prepend`
`Replace`
`names`
`values`

Append = pxr.UsdShade.ConnectionModification.Append#

Prepend = pxr.UsdShade.ConnectionModification.Prepend#

Replace = pxr.UsdShade.ConnectionModification.Replace#

names = {'Append': pxr.UsdShade.ConnectionModification.Append, 'Prepend': pxr.UsdShade.ConnectionModification.Prepend, 'Replace': pxr.UsdShade.ConnectionModification.Replace}#

values = {0: pxr.UsdShade.ConnectionModification.Replace, 1: pxr.UsdShade.ConnectionModification.Prepend, 2: pxr.UsdShade.ConnectionModification.Append}#

class pxr.UsdShade.ConnectionSourceInfo#

A compact struct to represent a bundle of information about an upstream source attribute.

Methods:

IsValid()

Return true if this source info is valid for setting up a connection.

Attributes:

`source`
`sourceName`
`sourceType`
`typeName`

IsValid() → bool#: Return true if this source info is valid for setting up a connection.

property source#

property sourceName#

property sourceType#

property typeName#

class pxr.UsdShade.CoordSysAPI#

UsdShadeCoordSysAPI provides a way to designate, name, and discover coordinate systems.

Coordinate systems are implicitly established by UsdGeomXformable prims, using their local space. That coordinate system may be bound (i.e., named) from another prim. The binding is encoded as a single- target relationship in the”coordSys:”namespace. Coordinate system bindings apply to descendants of the prim where the binding is expressed, but names may be re-bound by descendant prims.

Named coordinate systems are useful in shading workflows. An example is projection paint, which projects a texture from a certain view (the paint coordinate system). Using the paint coordinate frame avoids the need to assign a UV set to the object, and can be a concise way to project paint across a collection of objects with a single shared paint coordinate system.

This is a non-applied API schema.

Methods:

`Bind`(name, path)	Bind the name to the given path.
`BlockBinding`(name)	Block the indicated coordinate system binding on this prim by blocking targets on the underlying relationship.
`CanContainPropertyName`	classmethod CanContainPropertyName(name) -> bool
`ClearBinding`(name, removeSpec)	Clear the indicated coordinate system binding on this prim from the current edit target.
`FindBindingsWithInheritance`()	Find the list of coordinate system bindings that apply to this prim, including inherited bindings.
`Get`	classmethod Get(stage, path) -> CoordSysAPI
`GetCoordSysRelationshipName`	classmethod GetCoordSysRelationshipName(coordSysName) -> str
`GetLocalBindings`()	Get the list of coordinate system bindings local to this prim.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`HasLocalBindings`()	Returns true if the prim has local coordinate system binding opinions.

Bind(name, path) → bool#

Bind the name to the given path.

The prim at the given path is expected to be UsdGeomXformable, in order for the binding to be succesfully resolved.

Parameters:

name (str)
path (Path)

BlockBinding(name) → bool#

Block the indicated coordinate system binding on this prim by blocking targets on the underlying relationship.

Parameters:: name (str)

static CanContainPropertyName()#

classmethod CanContainPropertyName(name) -> bool

Test whether a given name contains the”coordSys:”prefix.

Parameters:: name (str)

ClearBinding(name, removeSpec) → bool#

Clear the indicated coordinate system binding on this prim from the current edit target.

Only remove the spec if removeSpec is true (leave the spec to preserve meta-data we may have intentionally authored on the relationship)

Parameters:

name (str)
removeSpec (bool)

FindBindingsWithInheritance() → list[Binding]#

Find the list of coordinate system bindings that apply to this prim, including inherited bindings.

This computation examines this prim and ancestors for the strongest binding for each name. A binding expressed by a child prim supercedes bindings on ancestors.

Note that this API does not validate the prims at the target paths; they may be of incorrect type, or missing entirely.

Binding relationships with no resolved targets are skipped.

static Get()#

classmethod Get(stage, path) -> CoordSysAPI

Return a UsdShadeCoordSysAPI 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:

UsdShadeCoordSysAPI(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

static GetCoordSysRelationshipName()#

classmethod GetCoordSysRelationshipName(coordSysName) -> str

Returns the fully namespaced coordinate system relationship name, given the coordinate system name.

Parameters:: coordSysName (str)

GetLocalBindings() → list[Binding]#

Get the list of coordinate system bindings local to this prim.

This does not process inherited bindings. It does not validate that a prim exists at the indicated path. If the binding relationship has multiple targets, only the first is used.

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

HasLocalBindings() → bool#

Returns true if the prim has local coordinate system binding opinions.

Note that the resulting binding list may still be empty.

class pxr.UsdShade.Input#

This class encapsulates a shader or node-graph input, which is a connectable attribute representing a typed value.

Methods:

`CanConnect`(source)	Determines whether this Input can be connected to the given source attribute, which can be an input or an output.
`ClearConnectability`()	Clears any authored connectability on the Input.
`ClearSdrMetadata`()	Clears any"sdrMetadata"value authored on the Input in the current EditTarget.
`ClearSdrMetadataByKey`(key)	Clears the entry corresponding to the given `key` in the"sdrMetadata"dictionary authored in the current EditTarget.
`ClearSource`()	Deprecated
`ClearSources`()	Clears sources for this Input in the current UsdEditTarget.
`ConnectToSource`(source, mod)	Authors a connection for this Input.
`DisconnectSource`(sourceAttr)	Disconnect source for this Input.
`Get`(value, time)	Convenience wrapper for the templated UsdAttribute::Get() .
`GetAttr`()	Explicit UsdAttribute extractor.
`GetBaseName`()	Returns the name of the input.
`GetConnectability`()	Returns the connectability of the Input.
`GetConnectedSource`(source, sourceName, ...)	Deprecated
`GetConnectedSources`(invalidSourcePaths)	Finds the valid sources of connections for the Input.
`GetDisplayGroup`()	Get the displayGroup metadata for this Input, i.e.
`GetDocumentation`()	Get documentation string for this Input.
`GetFullName`()	Get the name of the attribute associated with the Input.
`GetPrim`()	Get the prim that the input belongs to.
`GetRawConnectedSourcePaths`(sourcePaths)	Deprecated
`GetRenderType`()	Return this Input's specialized renderType, or an empty token if none was authored.
`GetSdrMetadata`()	Returns this Input's composed"sdrMetadata"dictionary as a NdrTokenMap.
`GetSdrMetadataByKey`(key)	Returns the value corresponding to `key` in the composed sdrMetadata dictionary.
`GetTypeName`()	Get the"scene description"value type name of the attribute associated with the Input.
`GetValueProducingAttribute`(attrType)	Deprecated
`GetValueProducingAttributes`(shaderOutputsOnly)	Find what is connected to this Input recursively.
`HasConnectedSource`()	Returns true if and only if this Input is currently connected to a valid (defined) source.
`HasRenderType`()	Return true if a renderType has been specified for this Input.
`HasSdrMetadata`()	Returns true if the Input has a non-empty composed"sdrMetadata"dictionary value.
`HasSdrMetadataByKey`(key)	Returns true if there is a value corresponding to the given `key` in the composed"sdrMetadata"dictionary.
`IsInput`	classmethod IsInput(attr) -> bool
`IsInterfaceInputName`	classmethod IsInterfaceInputName(name) -> bool
`IsSourceConnectionFromBaseMaterial`()	Returns true if the connection to this Input's source, as returned by GetConnectedSource() , is authored across a specializes arc, which is used to denote a base material.
`Set`(value, time)	Set a value for the Input at `time` .
`SetConnectability`(connectability)	Set the connectability of the Input.
`SetConnectedSources`(sourceInfos)	Connects this Input to the given sources, `sourceInfos` .
`SetDisplayGroup`(displayGroup)	Set the displayGroup metadata for this Input, i.e.
`SetDocumentation`(docs)	Set documentation string for this Input.
`SetRenderType`(renderType)	Specify an alternative, renderer-specific type to use when emitting/translating this Input, rather than translating based on its GetTypeName()
`SetSdrMetadata`(sdrMetadata)	Authors the given `sdrMetadata` value on this Input at the current EditTarget.
`SetSdrMetadataByKey`(key, value)	Sets the value corresponding to `key` to the given string `value` , in the Input's"sdrMetadata"dictionary at the current EditTarget.

CanConnect(source) → bool#

Determines whether this Input can be connected to the given source attribute, which can be an input or an output.

UsdShadeConnectableAPI::CanConnect

Parameters:: source (Attribute)

CanConnect(sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: sourceInput (Input)

CanConnect(sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: sourceOutput (Output)

ClearConnectability() → bool#: Clears any authored connectability on the Input.

ClearSdrMetadata() → None#: Clears any”sdrMetadata”value authored on the Input in the current EditTarget.

ClearSdrMetadataByKey(key) → None#

Clears the entry corresponding to the given key in the”sdrMetadata”dictionary authored in the current EditTarget.

Parameters:: key (str)

ClearSource() → bool#: Deprecated

ClearSources() → bool#

Clears sources for this Input in the current UsdEditTarget.

Most of the time, what you probably want is DisconnectSource() rather than this function.

UsdShadeConnectableAPI::ClearSources

ConnectToSource(source, mod) → bool#

Authors a connection for this Input.

source is a struct that describes the upstream source attribute with all the information necessary to make a connection. See the documentation for UsdShadeConnectionSourceInfo. mod describes the operation that should be applied to the list of connections. By default the new connection will replace any existing connections, but it can add to the list of connections to represent multiple input connections.

true if a connection was created successfully. false if this input or source is invalid.

This method does not verify the connectability of the shading attribute to the source. Clients must invoke CanConnect() themselves to ensure compatibility.

The source shading attribute is created if it doesn’t exist already.

UsdShadeConnectableAPI::ConnectToSource

Parameters:

source (ConnectionSourceInfo)
mod (ConnectionModification)

ConnectToSource(source, sourceName, sourceType, typeName) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)
typeName (ValueTypeName)

ConnectToSource(sourcePath) -> bool

Authors a connection for this Input to the source at the given path.

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourcePath (Path)

ConnectToSource(sourceInput) -> bool

Connects this Input to the given input, sourceInput .

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourceInput (Input)

ConnectToSource(sourceOutput) -> bool

Connects this Input to the given output, sourceOutput .

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourceOutput (Output)

DisconnectSource(sourceAttr) → bool#

Disconnect source for this Input.

If sourceAttr is valid, only a connection to the specified attribute is disconnected, otherwise all connections are removed.

UsdShadeConnectableAPI::DisconnectSource

Parameters:: sourceAttr (Attribute)

Get(value, time) → bool#

Convenience wrapper for the templated UsdAttribute::Get() .

Parameters:

value (T)
time (TimeCode)

Get(value, time) -> bool

Convenience wrapper for VtValue version of UsdAttribute::Get() .

Parameters:

value (VtValue)
time (TimeCode)

GetAttr() → Attribute#: Explicit UsdAttribute extractor.

GetBaseName() → str#

Returns the name of the input.

We call this the base name since it strips off the”inputs:”namespace prefix from the attribute name, and returns it.

GetConnectability() → str#

Returns the connectability of the Input.

SetConnectability()

GetConnectedSource(source, sourceName, sourceType) → bool#

Deprecated

Parameters:

source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)

GetConnectedSources(invalidSourcePaths) → list[SourceInfo]#

Finds the valid sources of connections for the Input.

invalidSourcePaths is an optional output parameter to collect the invalid source paths that have not been reported in the returned vector.

Returns a vector of UsdShadeConnectionSourceInfo structs with information about each upsteam attribute. If the vector is empty, there have been no valid connections.

A valid connection requires the existence of the source attribute and also requires that the source prim is UsdShadeConnectableAPI compatible.

The python wrapping returns a tuple with the valid connections first, followed by the invalid source paths.

UsdShadeConnectableAPI::GetConnectedSources

Parameters:: invalidSourcePaths (list[Path])

GetDisplayGroup() → str#

Get the displayGroup metadata for this Input, i.e.

hint for the location and nesting of the attribute.

UsdProperty::GetDisplayGroup() , UsdProperty::GetNestedDisplayGroup()

GetDocumentation() → str#

Get documentation string for this Input.

UsdObject::GetDocumentation()

GetFullName() → str#: Get the name of the attribute associated with the Input.

GetPrim() → Prim#: Get the prim that the input belongs to.

GetRawConnectedSourcePaths(sourcePaths) → bool#

Deprecated

Returns the”raw”(authored) connected source paths for this Input.

UsdShadeConnectableAPI::GetRawConnectedSourcePaths

Parameters:: sourcePaths (list[Path])

GetRenderType() → str#

Return this Input’s specialized renderType, or an empty token if none was authored.

SetRenderType()

GetSdrMetadata() → NdrTokenMap#: Returns this Input’s composed”sdrMetadata”dictionary as a NdrTokenMap.

GetSdrMetadataByKey(key) → str#

Returns the value corresponding to key in the composed sdrMetadata dictionary.

Parameters:: key (str)

GetTypeName() → ValueTypeName#: Get the”scene description”value type name of the attribute associated with the Input.

GetValueProducingAttribute(attrType) → Attribute#

Deprecated

in favor of calling GetValueProducingAttributes

Parameters:: attrType (AttributeType)

GetValueProducingAttributes( shaderOutputsOnly, ) → list[UsdShadeAttribute]#

Find what is connected to this Input recursively.

UsdShadeUtils::GetValueProducingAttributes

Parameters:: shaderOutputsOnly (bool)

HasConnectedSource() → bool#

Returns true if and only if this Input is currently connected to a valid (defined) source.

UsdShadeConnectableAPI::HasConnectedSource

HasRenderType() → bool#

Return true if a renderType has been specified for this Input.

SetRenderType()

HasSdrMetadata() → bool#: Returns true if the Input has a non-empty composed”sdrMetadata”dictionary value.

HasSdrMetadataByKey(key) → bool#

Returns true if there is a value corresponding to the given key in the composed”sdrMetadata”dictionary.

Parameters:: key (str)

static IsInput()#

classmethod IsInput(attr) -> bool

Test whether a given UsdAttribute represents a valid Input, which implies that creating a UsdShadeInput from the attribute will succeed.

Success implies that attr.IsDefined() is true.

Parameters:: attr (Attribute)

static IsInterfaceInputName()#

classmethod IsInterfaceInputName(name) -> bool

Test if this name has a namespace that indicates it could be an input.

Parameters:: name (str)

IsSourceConnectionFromBaseMaterial() → bool#

Returns true if the connection to this Input’s source, as returned by GetConnectedSource() , is authored across a specializes arc, which is used to denote a base material.

UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial

Set(value, time) → bool#

Set a value for the Input at time .

Parameters:

value (VtValue)
time (TimeCode)

Set(value, time) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set a value of the Input at time .

Parameters:

value (T)
time (TimeCode)

SetConnectability(connectability) → bool#

Set the connectability of the Input.

In certain shading data models, there is a need to distinguish which inputs can vary over a surface from those that must be uniform. This is accomplished in UsdShade by limiting the connectability of the input. This is done by setting the”connectability”metadata on the associated attribute.

Connectability of an Input can be set to UsdShadeTokens->full or UsdShadeTokens->interfaceOnly.

full implies that the Input can be connected to any other Input or Output.

interfaceOnly implies that the Input can only be connected to a NodeGraph Input (which represents an interface override, not a render-time dataflow connection), or another Input whose connectability is also”interfaceOnly”. The default connectability of an input is UsdShadeTokens->full.

SetConnectability()

Parameters:: connectability (str)

SetConnectedSources(sourceInfos) → bool#

Connects this Input to the given sources, sourceInfos .

UsdShadeConnectableAPI::SetConnectedSources

Parameters:: sourceInfos (list[ConnectionSourceInfo])

SetDisplayGroup(displayGroup) → bool#

Set the displayGroup metadata for this Input, i.e.

hinting for the location and nesting of the attribute.

Note for an input representing a nested SdrShaderProperty, its expected to have the scope delimited by a”:”.

UsdProperty::SetDisplayGroup() , UsdProperty::SetNestedDisplayGroup()

SdrShaderProperty::GetPage()

Parameters:: displayGroup (str)

SetDocumentation(docs) → bool#

Set documentation string for this Input.

UsdObject::SetDocumentation()

Parameters:: docs (str)

SetRenderType(renderType) → bool#

Specify an alternative, renderer-specific type to use when emitting/translating this Input, rather than translating based on its GetTypeName()

For example, we set the renderType to”struct”for Inputs that are of renderman custom struct types.

true on success.

Parameters:: renderType (str)

SetSdrMetadata(sdrMetadata) → None#

Authors the given sdrMetadata value on this Input at the current EditTarget.

Parameters:: sdrMetadata (NdrTokenMap)

SetSdrMetadataByKey(key, value) → None#

Sets the value corresponding to key to the given string value , in the Input’s”sdrMetadata”dictionary at the current EditTarget.

Parameters:

key (str)
value (str)

class pxr.UsdShade.Material#

A Material provides a container into which multiple”render targets”can add data that defines a”shading material”for a renderer. Typically this consists of one or more UsdRelationship properties that target other prims of type Shader - though a target/client is free to add any data that is suitable. We strongly advise that all targets adopt the convention that all properties be prefixed with a namespace that identifies the target, e.g.”rel ri:surface =</Shaders/mySurf>”.

In the UsdShading model, geometry expresses a binding to a single Material or to a set of Materials partitioned by UsdGeomSubsets defined beneath the geometry; it is legal to bind a Material at the root (or other sub-prim) of a model, and then bind a different Material to individual gprims, but the meaning of inheritance and”ancestral overriding”of Material bindings is left to each render- target to determine. Since UsdGeom has no concept of shading, we provide the API for binding and unbinding geometry on the API schema UsdShadeMaterialBindingAPI.

The entire power of USD VariantSets and all the other composition operators can leveraged when encoding shading variation. UsdShadeMaterial provides facilities for a particular way of building”Material variants”in which neither the identity of the Materials themselves nor the geometry Material-bindings need to change - instead we vary the targeted networks, interface values, and even parameter values within a single variantSet. See Authoring Material Variations for more details.

UsdShade requires that all of the shaders that”belong”to the Material live under the Material in namespace. This supports powerful, easy reuse of Materials, because it allows us to reference a Material from one asset (the asset might be a module of Materials) into another asset: USD references compose all descendant prims of the reference target into the referencer’s namespace, which means that all of the referenced Material’s shader networks will come along with the Material. When referenced in this way, Materials can also be instanced, for ease of deduplication and compactness. Finally, Material encapsulation also allows us to specialize child materials from parent materials.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdShadeTokens. So to set an attribute to the value”rightHanded”, use UsdShadeTokens->rightHanded as the value.

Methods:

`ClearBaseMaterial`()	Clear the base Material of this Material.
`ComputeDisplacementSource`(renderContext, ...)	Deprecated
`ComputeSurfaceSource`(renderContext, ...)	Deprecated
`ComputeVolumeSource`(renderContext, ...)	Deprecated
`CreateDisplacementAttr`(defaultValue, ...)	See GetDisplacementAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateDisplacementOutput`(renderContext)	Creates and returns the"displacement"output on this material for the specified `renderContext` .
`CreateMasterMaterialVariant`	classmethod CreateMasterMaterialVariant(masterPrim, MaterialPrims, masterVariantSetName) -> bool
`CreateSurfaceAttr`(defaultValue, writeSparsely)	See GetSurfaceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateSurfaceOutput`(renderContext)	Creates and returns the"surface"output on this material for the specified `renderContext` .
`CreateVolumeAttr`(defaultValue, writeSparsely)	See GetVolumeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateVolumeOutput`(renderContext)	Creates and returns the"volume"output on this material for the specified `renderContext` .
`Define`	classmethod Define(stage, path) -> Material
`Get`	classmethod Get(stage, path) -> Material
`GetBaseMaterial`()	Get the path to the base Material of this Material.
`GetBaseMaterialPath`()	Get the base Material of this Material.
`GetDisplacementAttr`()	Represents the universal"displacement"output terminal of a material.
`GetDisplacementOutput`(renderContext)	Returns the"displacement"output of this material for the specified renderContext.
`GetDisplacementOutputs`()	Returns the"displacement"outputs of this material for all available renderContexts.
`GetEditContextForVariant`(...)	Helper function for configuring a UsdStage 's UsdEditTarget to author Material variations.
`GetMaterialVariant`()	Return a UsdVariantSet object for interacting with the Material variant variantSet.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetSurfaceAttr`()	Represents the universal"surface"output terminal of a material.
`GetSurfaceOutput`(renderContext)	Returns the"surface"output of this material for the specified `renderContext` .
`GetSurfaceOutputs`()	Returns the"surface"outputs of this material for all available renderContexts.
`GetVolumeAttr`()	Represents the universal"volume"output terminal of a material.
`GetVolumeOutput`(renderContext)	Returns the"volume"output of this material for the specified renderContext.
`GetVolumeOutputs`()	Returns the"volume"outputs of this material for all available renderContexts.
`HasBaseMaterial`()
`SetBaseMaterial`(baseMaterial)	Set the base Material of this Material.
`SetBaseMaterialPath`(baseMaterialPath)	Set the path to the base Material of this Material.

ClearBaseMaterial() → None#: Clear the base Material of this Material.

ComputeDisplacementSource( renderContext, sourceName, sourceType, ) → Shader#

Deprecated

Use the form that takes a TfTokenVector or renderContexts

Parameters:

renderContext (str)
sourceName (str)
sourceType (AttributeType)

ComputeDisplacementSource(contextVector, sourceName, sourceType) -> Shader

Computes the resolved”displacement”output source for the given contextVector .

Using the earliest renderContext in the contextVector that produces a valid Shader object.

If a”displacement”output corresponding to each of the renderContexts does not exist or is not connected to a valid source, then this checks the universal displacement output.

Returns an empty Shader object if there is no valid displacement output source for any of the renderContexts in the contextVector . The python version of this method returns a tuple containing three elements (the source displacement shader, sourceName, sourceType).

Parameters:

contextVector (list[str])
sourceName (str)
sourceType (AttributeType)

ComputeSurfaceSource( renderContext, sourceName, sourceType, ) → Shader#

Deprecated

Use the form that takes a TfTokenVector or renderContexts.

Parameters:

renderContext (str)
sourceName (str)
sourceType (AttributeType)

ComputeSurfaceSource(contextVector, sourceName, sourceType) -> Shader

Computes the resolved”surface”output source for the given contextVector .

Using the earliest renderContext in the contextVector that produces a valid Shader object.

If a”surface”output corresponding to each of the renderContexts does not exist or is not connected to a valid source, then this checks the universal surface output.

Returns an empty Shader object if there is no valid surface output source for any of the renderContexts in the contextVector . The python version of this method returns a tuple containing three elements (the source surface shader, sourceName, sourceType).

Parameters:

contextVector (list[str])
sourceName (str)
sourceType (AttributeType)

ComputeVolumeSource( renderContext, sourceName, sourceType, ) → Shader#

Deprecated

Use the form that takes a TfTokenVector or renderContexts

Parameters:

renderContext (str)
sourceName (str)
sourceType (AttributeType)

ComputeVolumeSource(contextVector, sourceName, sourceType) -> Shader

Computes the resolved”volume”output source for the given contextVector .

Using the earliest renderContext in the contextVector that produces a valid Shader object.

If a”volume”output corresponding to each of the renderContexts does not exist or is not connected to a valid source, then this checks the universal volume output.

Returns an empty Shader object if there is no valid volume output output source for any of the renderContexts in the contextVector . The python version of this method returns a tuple containing three elements (the source volume shader, sourceName, sourceType).

Parameters:

contextVector (list[str])
sourceName (str)
sourceType (AttributeType)

CreateDisplacementAttr( defaultValue, writeSparsely, ) → Attribute#

See GetDisplacementAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateDisplacementOutput(renderContext) → Output#

Creates and returns the”displacement”output on this material for the specified renderContext .

If the output already exists on the material, it is returned and no authoring is performed. The returned output will always have the requested renderContext.

Parameters:: renderContext (str)

static CreateMasterMaterialVariant()#

classmethod CreateMasterMaterialVariant(masterPrim, MaterialPrims, masterVariantSetName) -> bool

Create a variantSet on masterPrim that will set the MaterialVariant on each of the given MaterialPrims.

The variantSet, whose name can be specified with masterVariantSetName and defaults to the same MaterialVariant name created on Materials by GetEditContextForVariant() , will have the same variants as the Materials, and each Master variant will set every MaterialPrims' MaterialVariant selection to the same variant as the master. Thus, it allows all Materials to be switched with a single variant selection, on masterPrim .

If masterPrim is an ancestor of any given member of MaterialPrims , then we will author variant selections directly on the MaterialPrims. However, it is often preferable to create a master MaterialVariant in a separately rooted tree from the MaterialPrims, so that it can be layered more strongly on top of the Materials. Therefore, for any MaterialPrim in a different tree than masterPrim, we will create”overs”as children of masterPrim that recreate the path to the MaterialPrim, substituting masterPrim’s full path for the MaterialPrim’s root path component.

Upon successful completion, the new variantSet we created on masterPrim will have its variant selection authored to the”last”variant (determined lexicographically). It is up to the calling client to either UsdVariantSet::ClearVariantSelection() on masterPrim , or set the selection to the desired default setting.

Return true on success. It is an error if any of Materials have a different set of variants for the MaterialVariant than the others.

Parameters:

masterPrim (Prim)
MaterialPrims (list[Prim])
masterVariantSetName (str)

CreateSurfaceAttr(defaultValue, writeSparsely) → Attribute#

See GetSurfaceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateSurfaceOutput(renderContext) → Output#

Creates and returns the”surface”output on this material for the specified renderContext .

If the output already exists on the material, it is returned and no authoring is performed. The returned output will always have the requested renderContext.

Parameters:: renderContext (str)

CreateVolumeAttr(defaultValue, writeSparsely) → Attribute#

See GetVolumeAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateVolumeOutput(renderContext) → Output#

Creates and returns the”volume”output on this material for the specified renderContext .

If the output already exists on the material, it is returned and no authoring is performed. The returned output will always have the requested renderContext.

Parameters:: renderContext (str)

static Define()#

classmethod Define(stage, path) -> Material

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:

stage (Stage)
path (Path)

static Get()#

classmethod Get(stage, path) -> Material

Return a UsdShadeMaterial 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:

UsdShadeMaterial(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

GetBaseMaterial() → Material#

Get the path to the base Material of this Material.

If there is no base Material, an empty Material is returned

GetBaseMaterialPath() → Path#

Get the base Material of this Material.

If there is no base Material, an empty path is returned

GetDisplacementAttr() → Attribute#

Represents the universal”displacement”output terminal of a material.

Declaration

token outputs:displacement

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

GetDisplacementOutput(renderContext) → Output#

Returns the”displacement”output of this material for the specified renderContext.

The returned output will always have the requested renderContext.

An invalid output is returned if an output corresponding to the requested specific-renderContext does not exist.

UsdShadeMaterial::ComputeDisplacementSource()

Parameters:: renderContext (str)

GetDisplacementOutputs() → list[Output]#

Returns the”displacement”outputs of this material for all available renderContexts.

The returned vector will include all authored”displacement”outputs with the universal renderContext output first, if present. Outputs are returned regardless of whether they are connected to a valid source.

GetEditContextForVariant( MaterialVariantName, layer, ) → tuple[Stage, EditTarget]#

Helper function for configuring a UsdStage ‘s UsdEditTarget to author Material variations.

Takes care of creating the Material variantSet and specified variant, if necessary.

Let’s assume that we are authoring Materials into the Stage’s current UsdEditTarget, and that we are iterating over the variations of a UsdShadeMaterial clothMaterial, and currVariant is the variant we are processing (e.g.”denim”).

In C++, then, we would use the following pattern:

{
    UsdEditContext ctxt(clothMaterial.GetEditContextForVariant(currVariant));

    // All USD mutation of the UsdStage on which clothMaterial sits will
    // now go "inside" the currVariant of the "MaterialVariant" variantSet
}

In python, the pattern is:

with clothMaterial.GetEditContextForVariant(currVariant):
    # Now sending mutations to currVariant

If layer is specified, then we will use it, rather than the stage’s current UsdEditTarget ‘s layer as the destination layer for the edit context we are building. If layer does not actually contribute to the Material prim’s definition, any editing will have no effect on this Material.

Note: As just stated, using this method involves authoring a selection for the MaterialVariant in the stage’s current EditTarget. When client is done authoring variations on this prim, they will likely want to either UsdVariantSet::SetVariantSelection() to the appropriate default selection, or possibly UsdVariantSet::ClearVariantSelection() on the UsdShadeMaterial::GetMaterialVariant() UsdVariantSet.

UsdVariantSet::GetVariantEditContext()

Parameters:

MaterialVariantName (str)
layer (Layer)

GetMaterialVariant() → VariantSet#: Return a UsdVariantSet object for interacting with the Material variant variantSet.

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

GetSurfaceAttr() → Attribute#

Represents the universal”surface”output terminal of a material.

Declaration

token outputs:surface

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

GetSurfaceOutput(renderContext) → Output#

Returns the”surface”output of this material for the specified renderContext .

The returned output will always have the requested renderContext.

An invalid output is returned if an output corresponding to the requested specific-renderContext does not exist.

UsdShadeMaterial::ComputeSurfaceSource()

Parameters:: renderContext (str)

GetSurfaceOutputs() → list[Output]#

Returns the”surface”outputs of this material for all available renderContexts.

The returned vector will include all authored”surface”outputs with the universal renderContext output first, if present. Outputs are returned regardless of whether they are connected to a valid source.

GetVolumeAttr() → Attribute#

Represents the universal”volume”output terminal of a material.

Declaration

token outputs:volume

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

GetVolumeOutput(renderContext) → Output#

Returns the”volume”output of this material for the specified renderContext.

The returned output will always have the requested renderContext.

An invalid output is returned if an output corresponding to the requested specific-renderContext does not exist.

UsdShadeMaterial::ComputeVolumeSource()

Parameters:: renderContext (str)

GetVolumeOutputs() → list[Output]#

Returns the”volume”outputs of this material for all available renderContexts.

The returned vector will include all authored”volume”outputs with the universal renderContext output first, if present. Outputs are returned regardless of whether they are connected to a valid source.

HasBaseMaterial() → bool#

SetBaseMaterial(baseMaterial) → None#

Set the base Material of this Material.

An empty Material is equivalent to clearing the base Material.

Parameters:: baseMaterial (Material)

SetBaseMaterialPath(baseMaterialPath) → None#

Set the path to the base Material of this Material.

An empty path is equivalent to clearing the base Material.

Parameters:: baseMaterialPath (Path)

class pxr.UsdShade.MaterialBindingAPI#

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:<i>bindingName</i>”, 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:<i>purpose:bindingName</i>”. 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.

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.

Classes:

`CollectionBinding`
`DirectBinding`

Methods:

`AddPrimToBindingCollection`(prim, ...)	Adds the specified `prim` to the collection targeted by the binding relationship corresponding to given `bindingName` and `materialPurpose` .
`Apply`	classmethod Apply(prim) -> MaterialBindingAPI
`Bind`(material, bindingStrength, materialPurpose)	Authors a direct binding to the given `material` on this prim.
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`CanContainPropertyName`	classmethod CanContainPropertyName(name) -> bool
`ComputeBoundMaterial`(bindingsCache, ...)	Computes the resolved bound material for this prim, for the given material purpose.
`ComputeBoundMaterials`	classmethod ComputeBoundMaterials(prims, materialPurpose, bindingRels) -> list[Material]
`CreateMaterialBindSubset`(subsetName, ...)	Creates a GeomSubset named `subsetName` with element type, `elementType` and familyName materialBind below this prim.
`Get`	classmethod Get(stage, path) -> MaterialBindingAPI
`GetCollectionBindingRel`(bindingName, ...)	Returns the collection-based material-binding relationship with the given `bindingName` and `materialPurpose` on this prim.
`GetCollectionBindingRels`(materialPurpose)	Returns the list of collection-based material binding relationships on this prim for the given material purpose, `materialPurpose` .
`GetCollectionBindings`(materialPurpose)	Returns all the collection-based bindings on this prim for the given material purpose.
`GetDirectBinding`(materialPurpose)	Computes and returns the direct binding for the given material purpose on this prim.
`GetDirectBindingRel`(materialPurpose)	Returns the direct material-binding relationship on this prim for the given material purpose.
`GetMaterialBindSubsets`()	Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.
`GetMaterialBindSubsetsFamilyType`()	Returns the familyType of the family of"materialBind"GeomSubsets on this prim.
`GetMaterialBindingStrength`	classmethod GetMaterialBindingStrength(bindingRel) -> str
`GetMaterialPurposes`	classmethod GetMaterialPurposes() -> list[str]
`GetResolvedTargetPathFromBindingRel`	classmethod GetResolvedTargetPathFromBindingRel(bindingRel) -> Path
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`RemovePrimFromBindingCollection`(prim, ...)	Removes the specified `prim` from the collection targeted by the binding relationship corresponding to given `bindingName` and `materialPurpose` .
`SetMaterialBindSubsetsFamilyType`(familyType)	Author the familyType of the"materialBind"family of GeomSubsets on this prim.
`SetMaterialBindingStrength`	classmethod SetMaterialBindingStrength(bindingRel, bindingStrength) -> bool
`UnbindAllBindings`()	Unbinds all direct and collection-based bindings on this prim.
`UnbindCollectionBinding`(bindingName, ...)	Unbinds the collection-based binding with the given `bindingName` , for the given `materialPurpose` on this prim.
`UnbindDirectBinding`(materialPurpose)	Unbinds the direct binding for the given material purpose ( `materialPurpose` ) on this prim.

class CollectionBinding#

Methods:

`GetBindingRel`
`GetCollection`
`GetCollectionPath`
`GetMaterial`
`GetMaterialPath`
`IsCollectionBindingRel`
`IsValid`

GetBindingRel()#

GetCollection()#

GetCollectionPath()#

GetMaterial()#

GetMaterialPath()#

static IsCollectionBindingRel()#

IsValid()#

class DirectBinding#

Methods:

`GetBindingRel`
`GetMaterial`
`GetMaterialPath`
`GetMaterialPurpose`

GetBindingRel()#

GetMaterial()#

GetMaterialPath()#

GetMaterialPurpose()#

AddPrimToBindingCollection( prim, bindingName, materialPurpose, ) → bool#

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()).

Parameters:

prim (Prim)
bindingName (str)
materialPurpose (str)

static Apply()#

classmethod Apply(prim) -> MaterialBindingAPI

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.

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:: prim (Prim)

Bind( material, bindingStrength, materialPurpose, ) → bool#

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.

Parameters:

material (Material)
bindingStrength (str)
materialPurpose (str)

Bind(collection, material, bindingName, bindingStrength, materialPurpose) -> bool

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.

Parameters:

collection (CollectionAPI)
material (Material)
bindingName (str)
bindingStrength (str)
materialPurpose (str)

static CanApply()#

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)
whyNot (str)

static CanContainPropertyName()#

classmethod CanContainPropertyName(name) -> bool

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

Parameters:: name (str)

ComputeBoundMaterial( bindingsCache, collectionQueryCache, materialPurpose, bindingRel, ) → Material#

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.

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.

Parameters:

bindingsCache (BindingsCache)
collectionQueryCache (CollectionQueryCache)
materialPurpose (str)
bindingRel (Relationship)

ComputeBoundMaterial(materialPurpose, bindingRel) -> Material

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.

Parameters:

materialPurpose (str)
bindingRel (Relationship)

static ComputeBoundMaterials()#

classmethod ComputeBoundMaterials(prims, materialPurpose, bindingRels) -> list[Material]

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.

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

Parameters:

prims (list[Prim])
materialPurpose (str)
bindingRels (list[Relationship])

CreateMaterialBindSubset( subsetName, indices, elementType, ) → Subset#

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.

Parameters:

subsetName (str)
indices (IntArray)
elementType (str)

static Get()#

classmethod Get(stage, path) -> MaterialBindingAPI

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));

Parameters:

stage (Stage)
path (Path)

GetCollectionBindingRel( bindingName, materialPurpose, ) → Relationship#

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 .

Parameters:

bindingName (str)
materialPurpose (str)

GetCollectionBindingRels( materialPurpose, ) → list[Relationship]#

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.

Parameters:: materialPurpose (str)

GetCollectionBindings( materialPurpose, ) → list[CollectionBinding]#

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.

Parameters:: materialPurpose (str)

GetDirectBinding(materialPurpose) → DirectBinding#

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

Parameters:: materialPurpose (str)

GetDirectBindingRel( materialPurpose, ) → Relationship#

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 .

Parameters:: materialPurpose (str)

GetMaterialBindSubsets() → list[Subset]#: Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.

GetMaterialBindSubsetsFamilyType() → str#

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().

UsdGeomSubset::GetFamilyNameAttr

static GetMaterialBindingStrength()#

classmethod GetMaterialBindingStrength(bindingRel) -> str

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.

UsdShadeMaterialBindingAPI::SetMaterialBindingStrength()

Parameters:: bindingRel (Relationship)

static GetMaterialPurposes()#

classmethod GetMaterialPurposes() -> list[str]

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

static GetResolvedTargetPathFromBindingRel()#

classmethod GetResolvedTargetPathFromBindingRel(bindingRel) -> Path

returns the path of the resolved target identified by bindingRel .

Parameters:: bindingRel (Relationship)

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

RemovePrimFromBindingCollection( prim, bindingName, materialPurpose, ) → bool#

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.

Parameters:

prim (Prim)
bindingName (str)
materialPurpose (str)

SetMaterialBindSubsetsFamilyType( familyType, ) → bool#

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

**

UsdGeomSubset::SetFamilyType**

Parameters:: familyType (str)

static SetMaterialBindingStrength()#

classmethod SetMaterialBindingStrength(bindingRel, bindingStrength) -> bool

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.

UsdShadeMaterialBindingAPI::GetMaterialBindingStrength()

Parameters:

bindingRel (Relationship)
bindingStrength (str)

UnbindAllBindings() → bool#: Unbinds all direct and collection-based bindings on this prim.

UnbindCollectionBinding( bindingName, materialPurpose, ) → bool#

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.

Parameters:

bindingName (str)
materialPurpose (str)

UnbindDirectBinding(materialPurpose) → bool#

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.

Parameters:: materialPurpose (str)

class pxr.UsdShade.NodeDefAPI#

UsdShadeNodeDefAPI is an API schema that provides attributes for a prim to select a corresponding Shader Node Definition (“Sdr Node”), as well as to look up a runtime entry for that shader node in the form of an SdrShaderNode.

UsdShadeNodeDefAPI is intended to be a pre-applied API schema for any prim type that wants to refer to the SdrRegistry for further implementation details about the behavior of that prim. The primary use in UsdShade itself is as UsdShadeShader, which is a basis for material shading networks (UsdShadeMaterial), but this is intended to be used in other domains that also use the Sdr node mechanism.

This schema provides properties that allow a prim to identify an external node definition, either by a direct identifier key into the SdrRegistry (info:id), an asset to be parsed by a suitable NdrParserPlugin (info:sourceAsset), or an inline source code that must also be parsed (info:sourceCode); as well as a selector attribute to determine which specifier is active (info:implementationSource).

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdShadeTokens. So to set an attribute to the value”rightHanded”, use UsdShadeTokens->rightHanded as the value.

Methods:

`Apply`	classmethod Apply(prim) -> NodeDefAPI
`CanApply`	classmethod CanApply(prim, whyNot) -> bool
`CreateIdAttr`(defaultValue, writeSparsely)	See GetIdAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`CreateImplementationSourceAttr`(defaultValue, ...)	See GetImplementationSourceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.
`Get`	classmethod Get(stage, path) -> NodeDefAPI
`GetIdAttr`()	The id is an identifier for the type or purpose of the shader.
`GetImplementationSource`()	Reads the value of info:implementationSource attribute and returns a token identifying the attribute that must be consulted to identify the shader's source program.
`GetImplementationSourceAttr`()	Specifies the attribute that should be consulted to get the shader's implementation or its source code.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetShaderId`(id)	Fetches the shader's ID value from the info:id attribute, if the shader's info:implementationSource is id.
`GetShaderNodeForSourceType`(sourceType)	This method attempts to ensure that there is a ShaderNode in the shader registry (i.e.
`GetSourceAsset`(sourceAsset, sourceType)	Fetches the shader's source asset value for the specified `sourceType` value from the *info: sourceType: sourceAsset* attribute, if the shader's info:implementationSource is sourceAsset.
`GetSourceAssetSubIdentifier`(subIdentifier, ...)	Fetches the shader's sub-identifier for the source asset with the specified `sourceType` value from the *info: sourceType: sourceAsset:subIdentifier* attribute, if the shader's info: implementationSource is sourceAsset.
`GetSourceCode`(sourceCode, sourceType)	Fetches the shader's source code for the specified `sourceType` value by reading the *info: sourceType: sourceCode* attribute, if the shader's info:implementationSource is sourceCode.
`SetShaderId`(id)	Sets the shader's ID value.
`SetSourceAsset`(sourceAsset, sourceType)	Sets the shader's source-asset path value to `sourceAsset` for the given source type, `sourceType` .
`SetSourceAssetSubIdentifier`(subIdentifier, ...)	Set a sub-identifier to be used with a source asset of the given source type.
`SetSourceCode`(sourceCode, sourceType)	Sets the shader's source-code value to `sourceCode` for the given source type, `sourceType` .

static Apply()#

classmethod Apply(prim) -> NodeDefAPI

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

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

A valid UsdShadeNodeDefAPI object is returned upon success. An invalid (or empty) UsdShadeNodeDefAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:: prim (Prim)

static CanApply()#

classmethod CanApply(prim, whyNot) -> bool

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.

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

Parameters:

prim (Prim)
whyNot (str)

CreateIdAttr(defaultValue, writeSparsely) → Attribute#

See GetIdAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateImplementationSourceAttr( defaultValue, writeSparsely, ) → Attribute#

See GetImplementationSourceAttr() , and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false .

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

static Get()#

classmethod Get(stage, path) -> NodeDefAPI

Return a UsdShadeNodeDefAPI 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:

UsdShadeNodeDefAPI(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

GetIdAttr() → Attribute#

The id is an identifier for the type or purpose of the shader.

E.g.: Texture or FractalFloat. The use of this id will depend on the render target: some will turn it into an actual shader path, some will use it to generate shader source code dynamically.

SetShaderId()

Declaration

uniform token info:id

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

GetImplementationSource() → str#

Reads the value of info:implementationSource attribute and returns a token identifying the attribute that must be consulted to identify the shader’s source program.

This returns

id, to indicate that the”info:id”attribute must be consulted.

sourceAsset to indicate that the asset- valued”info:{sourceType}:sourceAsset”attribute associated with the desired sourceType should be consulted to locate the asset with the shader’s source.

sourceCode to indicate that the string- valued”info:{sourceType}:sourceCode”attribute associated with the desired sourceType should be read to get shader’s source.

This issues a warning and returns id if the info:implementationSource attribute has an invalid value.

{sourceType} above is a place holder for a token that identifies the type of shader source or its implementation. For example: osl, glslfx, riCpp etc. This allows a shader to specify different sourceAsset (or sourceCode) values for different sourceTypes. The sourceType tokens usually correspond to the sourceType value of the NdrParserPlugin that’s used to parse the shader source (NdrParserPlugin::SourceType).

When sourceType is empty, the corresponding sourceAsset or sourceCode is considered to be”universal”(or fallback), which is represented by the empty-valued token UsdShadeTokens->universalSourceType. When the sourceAsset (or sourceCode) corresponding to a specific, requested sourceType is unavailable, the universal sourceAsset (or sourceCode) is returned by GetSourceAsset (and GetSourceCode} API, if present.

GetShaderId()

GetSourceAsset()

GetSourceCode()

GetImplementationSourceAttr() → Attribute#

Specifies the attribute that should be consulted to get the shader’s implementation or its source code.

If set to”id”, the”info:id”attribute’s value is used to determine the shader source from the shader registry.

If set to”sourceAsset”, the resolved value of the”info:sourceAsset”attribute corresponding to the desired implementation (or source-type) is used to locate the shader source. A source asset file may also specify multiple shader definitions, so there is an optional attribute”info:sourceAsset:subIdentifier”whose value should be used to indicate a particular shader definition from a source asset file.

If set to”sourceCode”, the value of”info:sourceCode”attribute corresponding to the desired implementation (or source type) is used as the shader source.

Declaration

uniform token info:implementationSource ="id"

C++ Type

TfToken

Usd Type

SdfValueTypeNames->Token

Variability

SdfVariabilityUniform

Allowed Values

id, sourceAsset, sourceCode

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

GetShaderId(id) → bool#

Fetches the shader’s ID value from the info:id attribute, if the shader’s info:implementationSource is id.

Returns true if the shader’s implementation source is id and the value was fetched properly into id . Returns false otherwise.

GetImplementationSource()

Parameters:: id (str)

GetShaderNodeForSourceType(sourceType) → ShaderNode#

This method attempts to ensure that there is a ShaderNode in the shader registry (i.e.

SdrRegistry) representing this shader for the given sourceType . It may return a null pointer if none could be found or created.

Parameters:: sourceType (str)

GetSourceAsset(sourceAsset, sourceType) → bool#

Fetches the shader’s source asset value for the specified sourceType value from the info: *sourceType*: sourceAsset attribute, if the shader’s info:implementationSource is sourceAsset.

If the sourceAsset attribute corresponding to the requested sourceType isn’t present on the shader, then the universal fallback sourceAsset attribute, i.e. info:sourceAsset is consulted, if present, to get the source asset path.

Returns true if the shader’s implementation source is sourceAsset and the source asset path value was fetched successfully into sourceAsset . Returns false otherwise.

GetImplementationSource()

Parameters:

sourceAsset (AssetPath)
sourceType (str)

GetSourceAssetSubIdentifier( subIdentifier, sourceType, ) → bool#

Fetches the shader’s sub-identifier for the source asset with the specified sourceType value from the info: *sourceType*: sourceAsset:subIdentifier attribute, if the shader’s info: implementationSource is sourceAsset.

If the subIdentifier attribute corresponding to the requested sourceType isn’t present on the shader, then the universal fallback sub-identifier attribute, i.e. info:sourceAsset: subIdentifier is consulted, if present, to get the sub-identifier name.

Returns true if the shader’s implementation source is sourceAsset and the sub-identifier for the given source type was fetched successfully into subIdentifier . Returns false otherwise.

Parameters:

subIdentifier (str)
sourceType (str)

GetSourceCode(sourceCode, sourceType) → bool#

Fetches the shader’s source code for the specified sourceType value by reading the info: *sourceType*: sourceCode attribute, if the shader’s info:implementationSource is sourceCode.

If the sourceCode attribute corresponding to the requested sourceType isn’t present on the shader, then the universal or fallback sourceCode attribute (i.e. info:sourceCode) is consulted, if present, to get the source code.

Returns true if the shader’s implementation source is sourceCode and the source code string was fetched successfully into sourceCode . Returns false otherwise.

GetImplementationSource()

Parameters:

sourceCode (str)
sourceType (str)

SetShaderId(id) → bool#

Sets the shader’s ID value.

This also sets the info:implementationSource attribute on the shader to UsdShadeTokens->id, if the existing value is different.

Parameters:: id (str)

SetSourceAsset(sourceAsset, sourceType) → bool#

Sets the shader’s source-asset path value to sourceAsset for the given source type, sourceType .

This also sets the info:implementationSource attribute on the shader to UsdShadeTokens->sourceAsset.

Parameters:

sourceAsset (AssetPath)
sourceType (str)

SetSourceAssetSubIdentifier( subIdentifier, sourceType, ) → bool#

Set a sub-identifier to be used with a source asset of the given source type.

This sets the info: *sourceType*: sourceAsset:subIdentifier.

This also sets the info:implementationSource attribute on the shader to UsdShadeTokens->sourceAsset

Parameters:

subIdentifier (str)
sourceType (str)

SetSourceCode(sourceCode, sourceType) → bool#

Sets the shader’s source-code value to sourceCode for the given source type, sourceType .

This also sets the info:implementationSource attribute on the shader to UsdShadeTokens->sourceCode.

Parameters:

sourceCode (str)
sourceType (str)

class pxr.UsdShade.NodeGraph#

A node-graph is a container for shading nodes, as well as other node- graphs. It has a public input interface and provides a list of public outputs.

Node Graph Interfaces

One of the most important functions of a node-graph is to host the”interface”with which clients of already-built shading networks will interact. Please see Interface Inputs for a detailed explanation of what the interface provides, and how to construct and use it, to effectively share/instance shader networks.

Node Graph Outputs

These behave like outputs on a shader and are typically connected to an output on a shader inside the node-graph.

Methods:

`ComputeInterfaceInputConsumersMap`(...)	Walks the namespace subtree below the node-graph and computes a map containing the list of all inputs on the node-graph and the associated vector of consumers of their values.
`ComputeOutputSource`(outputName, sourceName, ...)	Deprecated
`ConnectableAPI`()	Contructs and returns a UsdShadeConnectableAPI object with this node- graph.
`CreateInput`(name, typeName)	Create an Input which can either have a value or can be connected.
`CreateOutput`(name, typeName)	Create an output which can either have a value or can be connected.
`Define`	classmethod Define(stage, path) -> NodeGraph
`Get`	classmethod Get(stage, path) -> NodeGraph
`GetInput`(name)	Return the requested input if it exists.
`GetInputs`(onlyAuthored)	Returns all inputs present on the node-graph.
`GetInterfaceInputs`()	Returns all the"Interface Inputs"of the node-graph.
`GetOutput`(name)	Return the requested output if it exists.
`GetOutputs`(onlyAuthored)	Outputs are represented by attributes in the"outputs:"namespace.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

ComputeInterfaceInputConsumersMap( computeTransitiveConsumers, ) → InterfaceInputConsumersMap#

Walks the namespace subtree below the node-graph and computes a map containing the list of all inputs on the node-graph and the associated vector of consumers of their values.

The consumers can be inputs on shaders within the node-graph or on nested node-graphs).

If computeTransitiveConsumers is true, then value consumers belonging to node-graphs are resolved transitively to compute the transitive mapping from inputs on the node-graph to inputs on shaders inside the material. Note that inputs on node-graphs that don’t have value consumers will continue to be included in the result.

This API is provided for use by DCC’s that want to present node-graph interface / shader connections in the opposite direction than they are encoded in USD.

Parameters:: computeTransitiveConsumers (bool)

ComputeOutputSource( outputName, sourceName, sourceType, ) → Shader#

Deprecated

in favor of GetValueProducingAttributes on UsdShadeOutput Resolves the connection source of the requested output, identified by outputName to a shader output.

sourceName is an output parameter that is set to the name of the resolved output, if the node-graph output is connected to a valid shader source.

sourceType is an output parameter that is set to the type of the resolved output, if the node-graph output is connected to a valid shader source.

Returns a valid shader object if the specified output exists and is connected to one. Return an empty shader object otherwise. The python version of this method returns a tuple containing three elements (the source shader, sourceName, sourceType).

Parameters:

outputName (str)
sourceName (str)
sourceType (AttributeType)

ConnectableAPI() → ConnectableAPI#

Contructs and returns a UsdShadeConnectableAPI object with this node- graph.

Note that most tasks can be accomplished without explicitly constructing a UsdShadeConnectable API, since connection-related API such as UsdShadeConnectableAPI::ConnectToSource() are static methods, and UsdShadeNodeGraph will auto-convert to a UsdShadeConnectableAPI when passed to functions that want to act generically on a connectable UsdShadeConnectableAPI object.

CreateInput(name, typeName) → Input#

Create an Input which can either have a value or can be connected.

The attribute representing the input is created in the”inputs:”namespace.

Parameters:

name (str)
typeName (ValueTypeName)

CreateOutput(name, typeName) → Output#

Create an output which can either have a value or can be connected.

The attribute representing the output is created in the”outputs:”namespace.

Parameters:

name (str)
typeName (ValueTypeName)

static Define()#

classmethod Define(stage, path) -> NodeGraph

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:

stage (Stage)
path (Path)

static Get()#

classmethod Get(stage, path) -> NodeGraph

Return a UsdShadeNodeGraph 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:

UsdShadeNodeGraph(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

GetInput(name) → Input#

Return the requested input if it exists.

Parameters:: name (str)

GetInputs(onlyAuthored) → list[Input]#

Returns all inputs present on the node-graph.

These are represented by attributes in the”inputs:”namespace. If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

Parameters:: onlyAuthored (bool)

GetInterfaceInputs() → list[Input]#

Returns all the”Interface Inputs”of the node-graph.

This is the same as GetInputs() , but is provided as a convenience, to allow clients to distinguish between inputs on shaders vs. interface- inputs on node-graphs.

GetOutput(name) → Output#

Return the requested output if it exists.

Parameters:: name (str)

GetOutputs(onlyAuthored) → list[Output]#

Outputs are represented by attributes in the”outputs:”namespace.

If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

Parameters:: onlyAuthored (bool)

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

class pxr.UsdShade.Output#

This class encapsulates a shader or node-graph output, which is a connectable attribute representing a typed, externally computed value.

Methods:

`CanConnect`(source)	Determines whether this Output can be connected to the given source attribute, which can be an input or an output.
`ClearSdrMetadata`()	Clears any"sdrMetadata"value authored on the Output in the current EditTarget.
`ClearSdrMetadataByKey`(key)	Clears the entry corresponding to the given `key` in the"sdrMetadata"dictionary authored in the current EditTarget.
`ClearSource`()	Deprecated
`ClearSources`()	Clears sources for this Output in the current UsdEditTarget.
`ConnectToSource`(source, mod)	Authors a connection for this Output.
`DisconnectSource`(sourceAttr)	Disconnect source for this Output.
`GetAttr`()	Explicit UsdAttribute extractor.
`GetBaseName`()	Returns the name of the output.
`GetConnectedSource`(source, sourceName, ...)	Deprecated
`GetConnectedSources`(invalidSourcePaths)	Finds the valid sources of connections for the Output.
`GetFullName`()	Get the name of the attribute associated with the output.
`GetPrim`()	Get the prim that the output belongs to.
`GetRawConnectedSourcePaths`(sourcePaths)	Deprecated
`GetRenderType`()	Return this output's specialized renderType, or an empty token if none was authored.
`GetSdrMetadata`()	Returns this Output's composed"sdrMetadata"dictionary as a NdrTokenMap.
`GetSdrMetadataByKey`(key)	Returns the value corresponding to `key` in the composed sdrMetadata dictionary.
`GetTypeName`()	Get the"scene description"value type name of the attribute associated with the output.
`GetValueProducingAttributes`(shaderOutputsOnly)	Find what is connected to this Output recursively.
`HasConnectedSource`()	Returns true if and only if this Output is currently connected to a valid (defined) source.
`HasRenderType`()	Return true if a renderType has been specified for this output.
`HasSdrMetadata`()	Returns true if the Output has a non-empty composed"sdrMetadata"dictionary value.
`HasSdrMetadataByKey`(key)	Returns true if there is a value corresponding to the given `key` in the composed"sdrMetadata"dictionary.
`IsOutput`	classmethod IsOutput(attr) -> bool
`IsSourceConnectionFromBaseMaterial`()	Returns true if the connection to this Output's source, as returned by GetConnectedSource() , is authored across a specializes arc, which is used to denote a base material.
`Set`(value, time)	Set a value for the output.
`SetConnectedSources`(sourceInfos)	Connects this Output to the given sources, `sourceInfos` .
`SetRenderType`(renderType)	Specify an alternative, renderer-specific type to use when emitting/translating this output, rather than translating based on its GetTypeName()
`SetSdrMetadata`(sdrMetadata)	Authors the given `sdrMetadata` value on this Output at the current EditTarget.
`SetSdrMetadataByKey`(key, value)	Sets the value corresponding to `key` to the given string `value` , in the Output's"sdrMetadata"dictionary at the current EditTarget.

CanConnect(source) → bool#

Determines whether this Output can be connected to the given source attribute, which can be an input or an output.

An output is considered to be connectable only if it belongs to a node-graph. Shader outputs are not connectable.

UsdShadeConnectableAPI::CanConnect

Parameters:: source (Attribute)

CanConnect(sourceInput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: sourceInput (Input)

CanConnect(sourceOutput) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:: sourceOutput (Output)

ClearSdrMetadata() → None#: Clears any”sdrMetadata”value authored on the Output in the current EditTarget.

ClearSdrMetadataByKey(key) → None#

Clears the entry corresponding to the given key in the”sdrMetadata”dictionary authored in the current EditTarget.

Parameters:: key (str)

ClearSource() → bool#: Deprecated

ClearSources() → bool#

Clears sources for this Output in the current UsdEditTarget.

Most of the time, what you probably want is DisconnectSource() rather than this function.

UsdShadeConnectableAPI::ClearSources

ConnectToSource(source, mod) → bool#

Authors a connection for this Output.

source is a struct that describes the upstream source attribute with all the information necessary to make a connection. See the documentation for UsdShadeConnectionSourceInfo. mod describes the operation that should be applied to the list of connections. By default the new connection will replace any existing connections, but it can add to the list of connections to represent multiple input connections.

true if a connection was created successfully. false if shadingAttr or source is invalid.

This method does not verify the connectability of the shading attribute to the source. Clients must invoke CanConnect() themselves to ensure compatibility.

The source shading attribute is created if it doesn’t exist already.

UsdShadeConnectableAPI::ConnectToSource

Parameters:

source (ConnectionSourceInfo)
mod (ConnectionModification)

ConnectToSource(source, sourceName, sourceType, typeName) -> bool

Deprecated

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)
typeName (ValueTypeName)

ConnectToSource(sourcePath) -> bool

Authors a connection for this Output to the source at the given path.

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourcePath (Path)

ConnectToSource(sourceInput) -> bool

Connects this Output to the given input, sourceInput .

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourceInput (Input)

ConnectToSource(sourceOutput) -> bool

Connects this Output to the given output, sourceOutput .

UsdShadeConnectableAPI::ConnectToSource

Parameters:: sourceOutput (Output)

DisconnectSource(sourceAttr) → bool#

Disconnect source for this Output.

If sourceAttr is valid, only a connection to the specified attribute is disconnected, otherwise all connections are removed.

UsdShadeConnectableAPI::DisconnectSource

Parameters:: sourceAttr (Attribute)

GetAttr() → Attribute#: Explicit UsdAttribute extractor.

GetBaseName() → str#

Returns the name of the output.

We call this the base name since it strips off the”outputs:”namespace prefix from the attribute name, and returns it.

GetConnectedSource(source, sourceName, sourceType) → bool#

Deprecated

Please use GetConnectedSources instead

Parameters:

source (ConnectableAPI)
sourceName (str)
sourceType (AttributeType)

GetConnectedSources(invalidSourcePaths) → list[SourceInfo]#

Finds the valid sources of connections for the Output.

invalidSourcePaths is an optional output parameter to collect the invalid source paths that have not been reported in the returned vector.

Returns a vector of UsdShadeConnectionSourceInfo structs with information about each upsteam attribute. If the vector is empty, there have been no valid connections.

A valid connection requires the existence of the source attribute and also requires that the source prim is UsdShadeConnectableAPI compatible.

The python wrapping returns a tuple with the valid connections first, followed by the invalid source paths.

UsdShadeConnectableAPI::GetConnectedSources

Parameters:: invalidSourcePaths (list[Path])

GetFullName() → str#: Get the name of the attribute associated with the output.

GetPrim() → Prim#: Get the prim that the output belongs to.

GetRawConnectedSourcePaths(sourcePaths) → bool#

Deprecated

Returns the”raw”(authored) connected source paths for this Output.

UsdShadeConnectableAPI::GetRawConnectedSourcePaths

Parameters:: sourcePaths (list[Path])

GetRenderType() → str#

Return this output’s specialized renderType, or an empty token if none was authored.

SetRenderType()

GetSdrMetadata() → NdrTokenMap#: Returns this Output’s composed”sdrMetadata”dictionary as a NdrTokenMap.

GetSdrMetadataByKey(key) → str#

Returns the value corresponding to key in the composed sdrMetadata dictionary.

Parameters:: key (str)

GetTypeName() → ValueTypeName#: Get the”scene description”value type name of the attribute associated with the output.

GetValueProducingAttributes( shaderOutputsOnly, ) → list[UsdShadeAttribute]#

Find what is connected to this Output recursively.

UsdShadeUtils::GetValueProducingAttributes

Parameters:: shaderOutputsOnly (bool)

HasConnectedSource() → bool#

Returns true if and only if this Output is currently connected to a valid (defined) source.

UsdShadeConnectableAPI::HasConnectedSource

HasRenderType() → bool#

Return true if a renderType has been specified for this output.

SetRenderType()

HasSdrMetadata() → bool#: Returns true if the Output has a non-empty composed”sdrMetadata”dictionary value.

HasSdrMetadataByKey(key) → bool#

Returns true if there is a value corresponding to the given key in the composed”sdrMetadata”dictionary.

Parameters:: key (str)

static IsOutput()#

classmethod IsOutput(attr) -> bool

Test whether a given UsdAttribute represents a valid Output, which implies that creating a UsdShadeOutput from the attribute will succeed.

Success implies that attr.IsDefined() is true.

Parameters:: attr (Attribute)

IsSourceConnectionFromBaseMaterial() → bool#

Returns true if the connection to this Output’s source, as returned by GetConnectedSource() , is authored across a specializes arc, which is used to denote a base material.

UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial

Set(value, time) → bool#

Set a value for the output.

It’s unusual to be setting a value on an output since it represents an externally computed value. The Set API is provided here just for the sake of completeness and uniformity with other property schema.

Parameters:

value (VtValue)
time (TimeCode)

Set(value, time) -> bool

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set the attribute value of the Output at time .

Parameters:

value (T)
time (TimeCode)

SetConnectedSources(sourceInfos) → bool#

Connects this Output to the given sources, sourceInfos .

UsdShadeConnectableAPI::SetConnectedSources

Parameters:: sourceInfos (list[ConnectionSourceInfo])

SetRenderType(renderType) → bool#

Specify an alternative, renderer-specific type to use when emitting/translating this output, rather than translating based on its GetTypeName()

For example, we set the renderType to”struct”for outputs that are of renderman custom struct types.

true on success

Parameters:: renderType (str)

SetSdrMetadata(sdrMetadata) → None#

Authors the given sdrMetadata value on this Output at the current EditTarget.

Parameters:: sdrMetadata (NdrTokenMap)

SetSdrMetadataByKey(key, value) → None#

Sets the value corresponding to key to the given string value , in the Output’s”sdrMetadata”dictionary at the current EditTarget.

Parameters:

key (str)
value (str)

class pxr.UsdShade.Shader#

Base class for all USD shaders. Shaders are the building blocks of shading networks. While UsdShadeShader objects are not target specific, each renderer or application target may derive its own renderer-specific shader object types from this base, if needed.

Objects of this class generally represent a single shading object, whether it exists in the target renderer or not. For example, a texture, a fractal, or a mix node.

The UsdShadeNodeDefAPI provides attributes to uniquely identify the type of this node. The id resolution into a renderable shader target type of this node. The id resolution into a renderable shader target is deferred to the consuming application.

The purpose of representing them in Usd is two-fold:

To represent, via”connections”the topology of the shading network that must be reconstructed in the renderer. Facilities for authoring and manipulating connections are encapsulated in the API schema UsdShadeConnectableAPI.

To present a (partial or full) interface of typed input parameters whose values can be set and overridden in Usd, to be provided later at render-time as parameter values to the actual render shader objects. Shader input parameters are encapsulated in the property schema UsdShadeInput.

Methods:

`ClearSdrMetadata`()	Clears any"sdrMetadata"value authored on the shader in the current EditTarget.
`ClearSdrMetadataByKey`(key)	Clears the entry corresponding to the given `key` in the"sdrMetadata"dictionary authored in the current EditTarget.
`ConnectableAPI`()	Contructs and returns a UsdShadeConnectableAPI object with this shader.
`CreateIdAttr`(defaultValue, writeSparsely)	Forwards to UsdShadeNodeDefAPI(prim).
`CreateImplementationSourceAttr`(defaultValue, ...)	Forwards to UsdShadeNodeDefAPI(prim).
`CreateInput`(name, typeName)	Create an input which can either have a value or can be connected.
`CreateOutput`(name, typeName)	Create an output which can either have a value or can be connected.
`Define`	classmethod Define(stage, path) -> Shader
`Get`	classmethod Get(stage, path) -> Shader
`GetIdAttr`()	Forwards to UsdShadeNodeDefAPI(prim).
`GetImplementationSource`()	Forwards to UsdShadeNodeDefAPI(prim).
`GetImplementationSourceAttr`()	Forwards to UsdShadeNodeDefAPI(prim).
`GetInput`(name)	Return the requested input if it exists.
`GetInputs`(onlyAuthored)	Inputs are represented by attributes in the"inputs:"namespace.
`GetOutput`(name)	Return the requested output if it exists.
`GetOutputs`(onlyAuthored)	Outputs are represented by attributes in the"outputs:"namespace.
`GetSchemaAttributeNames`	classmethod GetSchemaAttributeNames(includeInherited) -> list[str]
`GetSdrMetadata`()	Returns this shader's composed"sdrMetadata"dictionary as a NdrTokenMap.
`GetSdrMetadataByKey`(key)	Returns the value corresponding to `key` in the composed sdrMetadata dictionary.
`GetShaderId`(id)	Forwards to UsdShadeNodeDefAPI(prim).
`GetShaderNodeForSourceType`(sourceType)	Forwards to UsdShadeNodeDefAPI(prim).
`GetSourceAsset`(sourceAsset, sourceType)	Forwards to UsdShadeNodeDefAPI(prim).
`GetSourceAssetSubIdentifier`(subIdentifier, ...)	Forwards to UsdShadeNodeDefAPI(prim).
`GetSourceCode`(sourceCode, sourceType)	Forwards to UsdShadeNodeDefAPI(prim).
`HasSdrMetadata`()	Returns true if the shader has a non-empty composed"sdrMetadata"dictionary value.
`HasSdrMetadataByKey`(key)	Returns true if there is a value corresponding to the given `key` in the composed"sdrMetadata"dictionary.
`SetSdrMetadata`(sdrMetadata)	Authors the given `sdrMetadata` on this shader at the current EditTarget.
`SetSdrMetadataByKey`(key, value)	Sets the value corresponding to `key` to the given string `value` , in the shader's"sdrMetadata"dictionary at the current EditTarget.
`SetShaderId`(id)	Forwards to UsdShadeNodeDefAPI(prim).
`SetSourceAsset`(sourceAsset, sourceType)	Forwards to UsdShadeNodeDefAPI(prim).
`SetSourceAssetSubIdentifier`(subIdentifier, ...)	Forwards to UsdShadeNodeDefAPI(prim).
`SetSourceCode`(sourceCode, sourceType)	Forwards to UsdShadeNodeDefAPI(prim).

ClearSdrMetadata() → None#: Clears any”sdrMetadata”value authored on the shader in the current EditTarget.

ClearSdrMetadataByKey(key) → None#

Clears the entry corresponding to the given key in the”sdrMetadata”dictionary authored in the current EditTarget.

Parameters:: key (str)

ConnectableAPI() → ConnectableAPI#

Contructs and returns a UsdShadeConnectableAPI object with this shader.

Note that most tasks can be accomplished without explicitly constructing a UsdShadeConnectable API, since connection-related API such as UsdShadeConnectableAPI::ConnectToSource() are static methods, and UsdShadeShader will auto-convert to a UsdShadeConnectableAPI when passed to functions that want to act generically on a connectable UsdShadeConnectableAPI object.

CreateIdAttr(defaultValue, writeSparsely) → Attribute#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateImplementationSourceAttr( defaultValue, writeSparsely, ) → Attribute#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

defaultValue (VtValue)
writeSparsely (bool)

CreateInput(name, typeName) → Input#

Create an input which can either have a value or can be connected.

The attribute representing the input is created in the”inputs:”namespace. Inputs on both shaders and node-graphs are connectable.

Parameters:

name (str)
typeName (ValueTypeName)

CreateOutput(name, typeName) → Output#

Create an output which can either have a value or can be connected.

The attribute representing the output is created in the”outputs:”namespace. Outputs on a shader cannot be connected, as their value is assumed to be computed externally.

Parameters:

name (str)
typeName (ValueTypeName)

static Define()#

classmethod Define(stage, path) -> Shader

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined() ) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema’s prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget ‘s namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

Parameters:

stage (Stage)
path (Path)

static Get()#

classmethod Get(stage, path) -> Shader

Return a UsdShadeShader 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:

UsdShadeShader(stage->GetPrimAtPath(path));

Parameters:

stage (Stage)
path (Path)

GetIdAttr() → Attribute#: Forwards to UsdShadeNodeDefAPI(prim).

GetImplementationSource() → str#: Forwards to UsdShadeNodeDefAPI(prim).

GetImplementationSourceAttr() → Attribute#: Forwards to UsdShadeNodeDefAPI(prim).

GetInput(name) → Input#

Return the requested input if it exists.

Parameters:: name (str)

GetInputs(onlyAuthored) → list[Input]#

Inputs are represented by attributes in the”inputs:”namespace.

If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

Parameters:: onlyAuthored (bool)

GetOutput(name) → Output#

Return the requested output if it exists.

Parameters:: name (str)

GetOutputs(onlyAuthored) → list[Output]#

Outputs are represented by attributes in the”outputs:”namespace.

If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

Parameters:: onlyAuthored (bool)

static GetSchemaAttributeNames()#

classmethod GetSchemaAttributeNames(includeInherited) -> list[str]

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.

Parameters:: includeInherited (bool)

GetSdrMetadata() → NdrTokenMap#: Returns this shader’s composed”sdrMetadata”dictionary as a NdrTokenMap.

GetSdrMetadataByKey(key) → str#

Returns the value corresponding to key in the composed sdrMetadata dictionary.

Parameters:: key (str)

GetShaderId(id) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:: id (str)

GetShaderNodeForSourceType(sourceType) → ShaderNode#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:: sourceType (str)

GetSourceAsset(sourceAsset, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

sourceAsset (AssetPath)
sourceType (str)

GetSourceAssetSubIdentifier(subIdentifier, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

subIdentifier (str)
sourceType (str)

GetSourceCode(sourceCode, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

sourceCode (str)
sourceType (str)

HasSdrMetadata() → bool#: Returns true if the shader has a non-empty composed”sdrMetadata”dictionary value.

HasSdrMetadataByKey(key) → bool#

Returns true if there is a value corresponding to the given key in the composed”sdrMetadata”dictionary.

Parameters:: key (str)

SetSdrMetadata(sdrMetadata) → None#

Authors the given sdrMetadata on this shader at the current EditTarget.

Parameters:: sdrMetadata (NdrTokenMap)

SetSdrMetadataByKey(key, value) → None#

Sets the value corresponding to key to the given string value , in the shader’s”sdrMetadata”dictionary at the current EditTarget.

Parameters:

key (str)
value (str)

SetShaderId(id) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:: id (str)

SetSourceAsset(sourceAsset, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

sourceAsset (AssetPath)
sourceType (str)

SetSourceAssetSubIdentifier(subIdentifier, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

subIdentifier (str)
sourceType (str)

SetSourceCode(sourceCode, sourceType) → bool#

Forwards to UsdShadeNodeDefAPI(prim).

Parameters:

sourceCode (str)
sourceType (str)

class pxr.UsdShade.ShaderDefParserPlugin#

Parses shader definitions represented using USD scene description using the schemas provided by UsdShade.

Methods:

`GetDiscoveryTypes`()	Returns the types of nodes that this plugin can parse.
`GetSourceType`()	Returns the source type that this parser operates on.
`Parse`(discoveryResult)	Takes the specified `NdrNodeDiscoveryResult` instance, which was a result of the discovery process, and generates a new `NdrNode` .

GetDiscoveryTypes() → NdrTokenVec#

Returns the types of nodes that this plugin can parse.

“Type”here is the discovery type (in the case of files, this will probably be the file extension, but in other systems will be data that can be determined during discovery). This type should only be used to match up a NdrNodeDiscoveryResult to its parser plugin; this value is not exposed in the node’s API.

GetSourceType() → str#

Returns the source type that this parser operates on.

A source type is the most general type for a node. The parser plugin is responsible for parsing all discovery results that have the types declared under GetDiscoveryTypes() , and those types are collectively identified as one”source type”.

Parse(discoveryResult) → NdrNodeUnique#

Takes the specified NdrNodeDiscoveryResult instance, which was a result of the discovery process, and generates a new NdrNode .

The node’s name, source type, and family must match.

Parameters:: discoveryResult (NodeDiscoveryResult)

class pxr.UsdShade.ShaderDefUtils#

This class contains a set of utility functions used for populating the shader registry with shaders definitions specified using UsdShade schemas.

Methods:

`GetNodeDiscoveryResults`	classmethod GetNodeDiscoveryResults(shaderDef, sourceUri) -> NdrNodeDiscoveryResultVec
`GetPrimvarNamesMetadataString`	classmethod GetPrimvarNamesMetadataString(metadata, shaderDef) -> str
`GetShaderProperties`	classmethod GetShaderProperties(shaderDef) -> NdrPropertyUniquePtrVec

static GetNodeDiscoveryResults()#

classmethod GetNodeDiscoveryResults(shaderDef, sourceUri) -> NdrNodeDiscoveryResultVec

Returns the list of NdrNodeDiscoveryResult objects that must be added to the shader registry for the given shader shaderDef , assuming it is found in a shader definition file found by an Ndr discovery plugin.

To enable the shaderDef parser to find and parse this shader, sourceUri should have the resolved path to the usd file containing this shader prim.

Parameters:

shaderDef (Shader)
sourceUri (str)

static GetPrimvarNamesMetadataString()#

classmethod GetPrimvarNamesMetadataString(metadata, shaderDef) -> str

Collects all the names of valid primvar inputs of the given metadata and the given shaderDef and returns the string used to represent them in SdrShaderNode metadata.

Parameters:

metadata (NdrTokenMap)
shaderDef (ConnectableAPI)

static GetShaderProperties()#

classmethod GetShaderProperties(shaderDef) -> NdrPropertyUniquePtrVec

Gets all input and output properties of the given shaderDef and translates them into NdrProperties that can be used as the properties for an SdrShaderNode.

Parameters:: shaderDef (ConnectableAPI)

class pxr.UsdShade.Tokens#

Attributes:

allPurpose = ''#

bindMaterialAs = 'bindMaterialAs'#

coordSys = 'coordSys:'#

displacement = 'displacement'#

fallbackStrength = 'fallbackStrength'#

full = 'full'#

id = 'id'#

infoId = 'info:id'#

infoImplementationSource = 'info:implementationSource'#

inputs = 'inputs:'#

interfaceOnly = 'interfaceOnly'#

materialBind = 'materialBind'#

materialBinding = 'material:binding'#

materialBindingCollection = 'material:binding:collection'#

materialVariant = 'materialVariant'#

outputs = 'outputs:'#

outputsDisplacement = 'outputs:displacement'#

outputsSurface = 'outputs:surface'#

outputsVolume = 'outputs:volume'#

preview = 'preview'#

sdrMetadata = 'sdrMetadata'#

sourceAsset = 'sourceAsset'#

sourceCode = 'sourceCode'#

strongerThanDescendants = 'strongerThanDescendants'#

subIdentifier = 'subIdentifier'#

surface = 'surface'#

universalRenderContext = ''#

universalSourceType = ''#

volume = 'volume'#

weakerThanDescendants = 'weakerThanDescendants'#

class pxr.UsdShade.Utils#

This class contains a set of utility functions used when authoring and querying shading networks.

Methods:

`GetBaseNameAndType`	classmethod GetBaseNameAndType(fullName) -> tuple[str, AttributeType]
`GetConnectedSourcePath`	classmethod GetConnectedSourcePath(srcInfo) -> Path
`GetFullName`	classmethod GetFullName(baseName, type) -> str
`GetPrefixForAttributeType`	classmethod GetPrefixForAttributeType(sourceType) -> str
`GetType`	classmethod GetType(fullName) -> AttributeType
`GetValueProducingAttributes`	classmethod GetValueProducingAttributes(input, shaderOutputsOnly) -> list[UsdShadeAttribute]

static GetBaseNameAndType()#

classmethod GetBaseNameAndType(fullName) -> tuple[str, AttributeType]

Given the full name of a shading attribute, returns it’s base name and shading attribute type.

Parameters:: fullName (str)

static GetConnectedSourcePath()#

classmethod GetConnectedSourcePath(srcInfo) -> Path

For a valid UsdShadeConnectionSourceInfo, return the complete path to the source property; otherwise the empty path.

Parameters:: srcInfo (ConnectionSourceInfo)

static GetFullName()#

classmethod GetFullName(baseName, type) -> str

Returns the full shading attribute name given the basename and the shading attribute type.

baseName is the name of the input or output on the shading node. type is the UsdShadeAttributeType of the shading attribute.

Parameters:

baseName (str)
type (AttributeType)

static GetPrefixForAttributeType()#

classmethod GetPrefixForAttributeType(sourceType) -> str

Returns the namespace prefix of the USD attribute associated with the given shading attribute type.

Parameters:: sourceType (AttributeType)

static GetType()#

classmethod GetType(fullName) -> AttributeType

Given the full name of a shading attribute, returns its shading attribute type.

Parameters:: fullName (str)

static GetValueProducingAttributes()#

classmethod GetValueProducingAttributes(input, shaderOutputsOnly) -> list[UsdShadeAttribute]

Find what is connected to an Input or Output recursively.

GetValueProducingAttributes implements the UsdShade connectivity rules described in Connection Resolution Utilities.

When tracing connections within networks that contain containers like UsdShadeNodeGraph nodes, the actual output(s) or value(s) at the end of an input or output might be multiple connections removed. The methods below resolves this across multiple physical connections.

An UsdShadeInput is getting its value from one of these sources:

If the input is not connected the UsdAttribute for this input is returned, but only if it has an authored value. The input attribute itself carries the value for this input.

If the input is connected we follow the connection(s) until we reach a valid output of a UsdShadeShader node or if we reach a valid UsdShadeInput attribute of a UsdShadeNodeGraph or UsdShadeMaterial that has an authored value.

An UsdShadeOutput on a container can get its value from the same type of sources as a UsdShadeInput on either a UsdShadeShader or UsdShadeNodeGraph. Outputs on non-containers (UsdShadeShaders) cannot be connected.

This function returns a vector of UsdAttributes. The vector is empty if no valid attribute was found. The type of each attribute can be determined with the UsdShadeUtils::GetType function.

If shaderOutputsOnly is true, it will only report attributes that are outputs of non-containers (UsdShadeShaders). This is a bit faster and what is need when determining the connections for Material terminals.

This will return the last attribute along the connection chain that has an authored value, which might not be the last attribute in the chain itself.

When the network contains multi-connections, this function can return multiple attributes for a single input or output. The list of attributes is build by a depth-first search, following the underlying connection paths in order. The list can contain both UsdShadeOutput and UsdShadeInput attributes. It is up to the caller to decide how to process such a mixture.

Parameters:

input (Input)
shaderOutputsOnly (bool)

GetValueProducingAttributes(output, shaderOutputsOnly) -> list[UsdShadeAttribute]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

output (Output)
shaderOutputsOnly (bool)

`allPurpose`
`bindMaterialAs`
`coordSys`
`displacement`
`fallbackStrength`
`full`
`id`
`infoId`
`infoImplementationSource`
`inputs`
`interfaceOnly`
`materialBind`
`materialBinding`
`materialBindingCollection`
`materialVariant`
`outputs`
`outputsDisplacement`
`outputsSurface`
`outputsVolume`
`preview`
`sdrMetadata`
`sourceAsset`
`sourceCode`
`strongerThanDescendants`
`subIdentifier`
`surface`
`universalRenderContext`
`universalSourceType`
`volume`
`weakerThanDescendants`