UsdShadeNodeGraph#

Fully qualified name: usdrt::UsdShadeNodeGraph

class UsdShadeNodeGraph : public usdrt::UsdTyped #

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.

Subclassed by usdrt::UsdShadeMaterial

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 UsdShadeNodeGraph(const UsdPrim &prim = UsdPrim())#: Construct a UsdShadeNodeGraph on UsdPrim prim. Equivalent to UsdShadeNodeGraph::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

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

inline virtual ~UsdShadeNodeGraph()#: Destructor.

inline UsdShadeNodeGraph(const UsdShadeConnectableAPI &connectable)#: Constructor that takes a ConnectableAPI object. Allow implicit (auto) conversion of UsdShadeConnectableAPI to UsdShadeNodeGraph, so that a ConnectableAPI can be passed into any function that accepts a NodeGraph.

Note

that the conversion may produce an invalid NodeGraph object, because not all UsdShadeConnectableAPIs are UsdShadeNodeGraphs

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.