This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdShadeNodeGraph Class Reference

A node-graph is a container for shading nodes, as well as other node-graphs. More...

#include <nodeGraph.h>

+ Inheritance diagram for UsdShadeNodeGraph:

Classes

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

Public Member Functions

 UsdShadeNodeGraph (const UsdPrim &prim=UsdPrim())
 Construct a UsdShadeNodeGraph on UsdPrim prim .
 
 UsdShadeNodeGraph (const UsdSchemaBase &schemaObj)
 Construct a UsdShadeNodeGraph on the prim held by schemaObj .
 
virtual USDSHADE_API ~UsdShadeNodeGraph ()
 Destructor.
 
USDSHADE_API UsdShadeNodeGraph (const UsdShadeConnectableAPI &connectable)
 Constructor that takes a ConnectableAPI object.
 
USDSHADE_API UsdShadeConnectableAPI ConnectableAPI () const
 Contructs and returns a UsdShadeConnectableAPI object with this node-graph.
 
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
 Create an output which can either have a value or can be connected.
 
USDSHADE_API UsdShadeOutput GetOutput (const TfToken &name) const
 Return the requested output if it exists.
 
USDSHADE_API std::vector< UsdShadeOutputGetOutputs (bool onlyAuthored=true) const
 Outputs are represented by attributes in the "outputs:" namespace.
 
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

USDSHADE_API UsdShadeInput CreateInput (const TfToken &name, const SdfValueTypeName &typeName) const
 Create an Input which can either have a value or can be connected.
 
USDSHADE_API UsdShadeInput GetInput (const TfToken &name) const
 Return the requested input if it exists.
 
USDSHADE_API std::vector< UsdShadeInputGetInputs (bool onlyAuthored=true) const
 Returns all inputs present on the node-graph.
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 Construct a UsdTyped on UsdPrim prim .
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 Construct a UsdTyped on the prim held by schemaObj .
 
virtual USD_API ~UsdTyped ()
 Destructor.
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped.
 
bool IsAPISchema () const
 Returns whether this is an API schema or not.
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not.
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not.
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is.
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim.
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema.
 
virtual USD_API ~UsdSchemaBase ()
 Destructor.
 
UsdPrim GetPrim () const
 Return this schema object's held prim.
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath().
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null.
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise.
 

Static Public Member Functions

static USDSHADE_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDSHADE_API UsdShadeNodeGraph Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdShadeNodeGraph holding the prim adhering to this schema at path on stage.
 
static USDSHADE_API 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.
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdTyped holding the prim adhering to this schema at path on stage.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 

Protected Member Functions

USDSHADE_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdTyped
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USD_API bool _IsCompatible () const override
 Subclasses may override _IsCompatible to do specific compatibility checking with the given prim, such as type compatibility or value compatibility.
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

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::HashInterfaceInputConsumersMap
 Map of interface inputs to corresponding vectors of inputs that consume their values.
 
typedef std::unordered_map< UsdShadeNodeGraph, InterfaceInputConsumersMap, NodeGraphHasher, NodeGraphEqualFnNodeGraphInputConsumersMap
 Map of node-graphs to their associated input-consumers map.
 
USDSHADE_API std::vector< UsdShadeInputGetInterfaceInputs () const
 Returns all the "Interface Inputs" of the node-graph.
 
USDSHADE_API InterfaceInputConsumersMap 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.
 

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 63 of file nodeGraph.h.

Member Typedef Documentation

◆ InterfaceInputConsumersMap

typedef std::unordered_map<UsdShadeInput, std::vector<UsdShadeInput>, UsdShadeInput::Hash> InterfaceInputConsumersMap

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

Definition at line 338 of file nodeGraph.h.

◆ NodeGraphInputConsumersMap

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

Definition at line 345 of file nodeGraph.h.

Constructor & Destructor Documentation

◆ UsdShadeNodeGraph() [1/3]

UsdShadeNodeGraph ( const UsdPrim prim = UsdPrim())
inlineexplicit

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 75 of file nodeGraph.h.

◆ UsdShadeNodeGraph() [2/3]

UsdShadeNodeGraph ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdShadeNodeGraph on the prim held by schemaObj .

Should be preferred over UsdShadeNodeGraph(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 83 of file nodeGraph.h.

◆ ~UsdShadeNodeGraph()

virtual USDSHADE_API ~UsdShadeNodeGraph ( )
virtual

Destructor.

◆ UsdShadeNodeGraph() [3/3]

USDSHADE_API 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

Member Function Documentation

◆ _GetSchemaKind()

USDSHADE_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdTyped.

◆ ComputeInterfaceInputConsumersMap()

USDSHADE_API InterfaceInputConsumersMap 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.

◆ ComputeOutputSource()

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

◆ ConnectableAPI()

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

◆ CreateInput()

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

◆ CreateOutput()

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

◆ Define()

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

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.

◆ Get()

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

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));
A node-graph is a container for shading nodes, as well as other node-graphs.
Definition: nodeGraph.h:64

◆ GetInput()

USDSHADE_API UsdShadeInput GetInput ( const TfToken name) const

Return the requested input if it exists.

◆ GetInputs()

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

◆ GetInterfaceInputs()

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

◆ GetOutput()

USDSHADE_API UsdShadeOutput GetOutput ( const TfToken name) const

Return the requested output if it exists.

◆ GetOutputs()

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

◆ GetSchemaAttributeNames()

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

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

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 147 of file nodeGraph.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
static

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

See also
UsdSchemaKind

Definition at line 69 of file nodeGraph.h.


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