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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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