All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdShadeNodeGraph Class Reference

#include <nodeGraph.h>

+ Inheritance diagram for UsdShadeNodeGraph:


struct  NodeGraphEqualFn
 Equality comparator for UsdShadeNodeGraph objects. More...
struct  NodeGraphHasher
 Hash functor for UsdShadeNodeGraph objects. More...

Public Member Functions

 UsdShadeNodeGraph (const UsdPrim &prim=UsdPrim())
 UsdShadeNodeGraph (const UsdSchemaBase &schemaObj)
virtual USDSHADE_API ~UsdShadeNodeGraph ()
 Destructor. More...
USDSHADE_API UsdShadeNodeGraph (const UsdShadeConnectableAPI &connectable)
USDSHADE_API UsdShadeConnectableAPI ConnectableAPI () const
Outputs of a node-graph. These typically connect to outputs of

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

USDSHADE_API UsdShadeOutput CreateOutput (const TfToken &name, const SdfValueTypeName &typeName) const
USDSHADE_API UsdShadeOutput GetOutput (const TfToken &name) const
USDSHADE_API std::vector
< UsdShadeOutput
GetOutputs () const
USDSHADE_API UsdShadeShader ComputeOutputSource (const TfToken &outputName, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
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

describe scoped interfaces and fix bug/108940 to account for them.
USDSHADE_API UsdShadeInput CreateInput (const TfToken &name, const SdfValueTypeName &typeName) const
USDSHADE_API UsdShadeInput GetInput (const TfToken &name) const
USDSHADE_API std::vector
< UsdShadeInput
GetInputs () const
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 UsdTyped (const UsdSchemaBase &schemaObj)
virtual USD_API ~UsdTyped ()
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
bool IsTyped () const
bool IsAPISchema () const
 Returns whether this is an API schema or not. More...
bool IsAppliedAPISchema () const
bool IsMultipleApplyAPISchema () const
UsdSchemaType GetSchemaType () const
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim. More...
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema. More...
virtual USD_API ~UsdSchemaBase ()
 Destructor. More...
USD_API operator bool () const
UsdPrim GetPrim () const
 Return this schema object's held prim. More...
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath(). More...
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const

Static Public Member Functions

static USDSHADE_API const
GetSchemaAttributeNames (bool includeInherited=true)
Get (const UsdStagePtr &stage, const SdfPath &path)
Define (const UsdStagePtr &stage, const SdfPath &path)
- Static Public Member Functions inherited from UsdTyped
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)

Static Public Attributes

static const UsdSchemaType schemaType = UsdSchemaType::ConcreteTyped
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaType schemaType = UsdSchemaType::AbstractBase
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaType schemaType = UsdSchemaType::AbstractBase

Protected Member Functions

USDSHADE_API UsdSchemaType _GetSchemaType () const override
- Protected Member Functions inherited from UsdTyped
USD_API bool _IsCompatible () const override
- Protected Member Functions inherited from UsdSchemaBase
const TfType_GetType () const
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const


class UsdSchemaRegistry

Interface Inputs

API to query the inputs that form the interface of the node-graph and their connections.

typedef std::unordered_map
< UsdShadeInput, std::vector
< UsdShadeInput >
, UsdShadeInput::Hash
typedef std::unordered_map
< UsdShadeNodeGraph,
 Map of node-graphs to their associated input-consumers map. More...
USDSHADE_API std::vector
< UsdShadeInput
GetInterfaceInputs () const
ComputeInterfaceInputConsumersMap (bool computeTransitiveConsumers=false) const

Detailed Description

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.

Definition at line 79 of file nodeGraph.h.

Member Typedef Documentation

Map of interface inputs to corresponding vectors of inputs that consume their values.

Definition at line 346 of file nodeGraph.h.

Map of node-graphs to their associated input-consumers map.

Definition at line 353 of file nodeGraph.h.

Constructor & Destructor Documentation

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

Definition at line 91 of file nodeGraph.h.

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

Definition at line 99 of file nodeGraph.h.

virtual USDSHADE_API UsdShadeNodeGraph::~UsdShadeNodeGraph ( )


USDSHADE_API UsdShadeNodeGraph::UsdShadeNodeGraph ( const UsdShadeConnectableAPI connectable)

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

Member Function Documentation

USDSHADE_API UsdSchemaType UsdShadeNodeGraph::_GetSchemaType ( ) const

Returns the type of schema this class belongs to.

See Also

Reimplemented from UsdSchemaBase.

USDSHADE_API InterfaceInputConsumersMap UsdShadeNodeGraph::ComputeInterfaceInputConsumersMap ( bool  computeTransitiveConsumers = false) const

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.

USDSHADE_API UsdShadeShader UsdShadeNodeGraph::ComputeOutputSource ( const TfToken outputName,
TfToken sourceName,
UsdShadeAttributeType sourceType 
) const

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).
USDSHADE_API UsdShadeConnectableAPI UsdShadeNodeGraph::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.

USDSHADE_API UsdShadeInput UsdShadeNodeGraph::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.

clarify error behavior if typeName does not match existing, defined attribute - should match UsdPrim::CreateAttribute - bug/108970
USDSHADE_API UsdShadeOutput UsdShadeNodeGraph::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.

static USDSHADE_API UsdShadeNodeGraph UsdShadeNodeGraph::Define ( const UsdStagePtr &  stage,
const SdfPath path 

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.

static USDSHADE_API UsdShadeNodeGraph UsdShadeNodeGraph::Get ( const UsdStagePtr &  stage,
const SdfPath path 

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:

USDSHADE_API UsdShadeInput UsdShadeNodeGraph::GetInput ( const TfToken name) const

Return the requested input if it exists.

USDSHADE_API std::vector<UsdShadeInput> UsdShadeNodeGraph::GetInputs ( ) const

Returns all inputs present on the node-graph. These are represented by attributes in the "inputs:" namespace.

USDSHADE_API std::vector<UsdShadeInput> UsdShadeNodeGraph::GetInterfaceInputs ( ) const

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.

USDSHADE_API UsdShadeOutput UsdShadeNodeGraph::GetOutput ( const TfToken name) const

Return the requested output if it exists.

USDSHADE_API std::vector<UsdShadeOutput> UsdShadeNodeGraph::GetOutputs ( ) const

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

static USDSHADE_API const TfTokenVector& UsdShadeNodeGraph::GetSchemaAttributeNames ( bool  includeInherited = true)

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.

Friends And Related Function Documentation

friend class UsdSchemaRegistry

Definition at line 163 of file nodeGraph.h.

Member Data Documentation

const UsdSchemaType UsdShadeNodeGraph::schemaType = UsdSchemaType::ConcreteTyped

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

See Also

Definition at line 85 of file nodeGraph.h.

The documentation for this class was generated from the following file: