UsdShadeMaterial#

Fully qualified name: usdrt::UsdShadeMaterial

class UsdShadeMaterial : public usdrt::UsdShadeNodeGraph #

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

Standard Material Terminal Outputs

A UsdShadeMaterial can have any number of “terminal” outputs. These outputs are generally used to point to outputs of shader prims or NodeGraphs that describe certain properties of the material that a renderer might wish to consume. There are three standard output terminals that are supported by the core API: surface, displacement and volume.

Each terminal output can further be qualified by a token-valued renderContext. When a non-empty renderContext value is specified to the API, the output is considered to have a specific or restricted renderContext. If the renderContext value is empty (i.e. equal to UsdShadeTokens->universalRenderContext), then the output is considered to be a “universal”, meaning it could apply to any render contexts. Render context token values is typically driven by the rendering backend consuming the terminal output (eg, RI or glslfx).

inline UsdShadeOutput CreateSurfaceOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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.

inline UsdShadeOutput GetSurfaceOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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.

See also

UsdShadeMaterial::ComputeSurfaceSource()

inline std::vector<UsdShadeOutput> GetSurfaceOutputs() const#

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.

inline UsdShadeOutput CreateDisplacementOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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

inline UsdShadeOutput GetDisplacementOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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.

See also

UsdShadeMaterial::ComputeDisplacementSource()

inline std::vector<UsdShadeOutput> GetDisplacementOutputs() const#

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.

inline UsdShadeOutput CreateVolumeOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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

inline UsdShadeOutput GetVolumeOutput( const TfToken &renderContext = UsdShadeTokens->universalRenderContext, ) const#

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.

See also

UsdShadeMaterial::ComputeVolumeSource()

inline std::vector<UsdShadeOutput> GetVolumeOutputs() const#

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.

Outputs of a node-graph. These typically connect to outputs of

shaders or nested node-graphs within the node-graph.

inline UsdShadeOutput CreateOutput( const TfToken &name, const SdfValueTypeName &typeName, ) const#: Create an output which can either have a value or can be connected. The attribute representing the output is created in the “outputs:” namespace.

inline UsdShadeOutput GetOutput(const TfToken &name) const#: Return the requested output if it exists.

inline std::vector<UsdShadeOutput> GetOutputs( bool onlyAuthored = true, ) const#: 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.

inline UsdShadeShader ComputeOutputSource( const TfToken &outputName, TfToken *sourceName, UsdShadeAttributeType *sourceType, ) const#

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

Interface inputs of a node-graph.

In addition to serving as the “head” for all of the shading networks that describe each render target’s particular node-graph, the node-graph prim provides a unified “interface” that allows node-graphs to share shading networks while retaining the ability for each to specify its own set of unique values for the interface inputs that users may need to modify.

A “Node-graph Interface” is a combination of:

a flat collection of attributes, of arbitrary names
for each such attribute, a list of UsdShaderInput targets whose attributes on Shader prims should be driven by the interface input.

A single interface input can drive multiple shader inputs and be consumed by multiple render targets. The set of interface inputs itself is intentionally flat, to encourage sharing of the interface between render targets. Clients are always free to create interface inputs with namespacing to segregate “private” attributes exclusive to the render target, but we hope this will be an exception.

To facilitate connecting, qualifying, and interrogating interface attributes, we use the attribute schema UsdShadeInput, which also serves as an abstraction for shader inputs.

Scoped Interfaces

Todo:: describe scoped interfaces and fix bug/108940 to account for them.

inline UsdShadeInput CreateInput( const TfToken &name, const SdfValueTypeName &typeName, ) const#

Create an Input which can either have a value or can be connected. The attribute representing the input is created in the “inputs:” namespace.

Todo:: clarify error behavior if typeName does not match existing, defined attribute - should match UsdPrim::CreateAttribute - bug/108970

inline UsdShadeInput GetInput(const TfToken &name) const#: Return the requested input if it exists.

inline std::vector<UsdShadeInput> GetInputs( bool onlyAuthored = true, ) const#: 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.

Public Functions

inline explicit UsdShadeMaterial(const UsdPrim &prim = UsdPrim())#: Construct a UsdShadeMaterial on UsdPrim prim. Equivalent to UsdShadeMaterial::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

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

inline virtual ~UsdShadeMaterial()#: Destructor.

inline UsdAttribute GetSurfaceAttr() const#

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


Declaration	`token outputs:surface`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token

inline UsdAttribute CreateSurfaceAttr() const#: 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.

inline UsdAttribute GetDisplacementAttr() const#

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


Declaration	`token outputs:displacement`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token

inline UsdAttribute CreateDisplacementAttr() const#: 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.

inline UsdAttribute GetVolumeAttr() const#

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


Declaration	`token outputs:volume`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token

inline UsdAttribute CreateVolumeAttr() const#: 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.

inline UsdShadeConnectableAPI ConnectableAPI() const#

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.

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

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

inline explicit operator bool() const#

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

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

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

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

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

Public Static Functions

static inline UsdShadeMaterial Define( const UsdStageRefPtr &stage, const SdfPath &path, )#: Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::ConcreteTyped #

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

See also

UsdSchemaType

Protected Functions

inline virtual bool _IsCompatible() const#

Helper for subclasses to do specific compatibility checking with the given prim. Subclassess may override _isCompatible to for example check type compatibility or value compatibility on the prim.

Overrides exist for UsdTyped and UsdAPISchemaBase.

This check is called when clients invoke the bool operator.

Returns:: True if the schema object is compatible with its held prim.

inline const TfToken _GetType() const#

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

Note

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

Returns:: The token representing the schema’s TfType.