UsdShadeConnectableAPI

Fully qualified name: usdrt::UsdShadeConnectableAPI

class UsdShadeConnectableAPI : public usdrt::UsdAPISchemaBase

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.

Outputs

inline UsdShadeOutput CreateOutput(

const TfToken &name,

const SdfValueTypeName &typeName,

) const

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.

inline UsdShadeOutput GetOutput(const TfToken &name) const

Return the requested output if it exists.

name is the unnamespaced base name.

inline std::vector<UsdShadeOutput> GetOutputs(

bool onlyAuthored = true,

) const

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.

Inputs

inline UsdShadeInput CreateInput(

const TfToken &name,

const SdfValueTypeName &typeName,

) const

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

inline UsdShadeInput GetInput(const TfToken &name) const

Return the requested input if it exists.

name is the unnamespaced base name.

inline std::vector<UsdShadeInput> GetInputs(

bool onlyAuthored = true,

) const

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.

Public Types

using ConnectionModification = UsdShadeConnectionModification

Public Functions

inline explicit UsdShadeConnectableAPI(

const UsdPrim &prim = UsdPrim(),

)

Construct a UsdShadeConnectableAPI on UsdPrim prim. Equivalent to UsdShadeConnectableAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdShadeConnectableAPI(

const UsdSchemaBase &schemaObj,

)

Construct a UsdShadeConnectableAPI on the prim held by schemaObj . Should be preferred over UsdShadeConnectableAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdShadeConnectableAPI()

Destructor.

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 bool ConnectToSource(

const UsdAttribute &shadingAttr,

const UsdShadeConnectionSourceInfo &source,

const ConnectionModification mod = ConnectionModification::Replace,

)

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.

Note

This method does not verify the connectability of the shading attribute to the source. Clients must invoke CanConnect() themselves to ensure compatibility.

Note

The source shading attribute is created if it doesn’t exist already.

Returns:

true if a connection was created successfully. false if shadingAttr or source is invalid.

static inline bool ConnectToSource(

const UsdShadeInput &input,

const UsdShadeConnectionSourceInfo &source,

const ConnectionModification mod = ConnectionModification::Replace,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static inline bool ConnectToSource(

const UsdShadeOutput &output,

const UsdShadeConnectionSourceInfo &source,

const ConnectionModification mod = ConnectionModification::Replace,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static inline bool ConnectToSource(

const UsdAttribute &shadingAttr,

const UsdShadeConnectableAPI &source,

const TfToken &sourceName,

const UsdShadeAttributeType sourceType = UsdShadeAttributeType::Output,

SdfValueTypeName typeName = SdfValueTypeName(),

)

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.

static inline bool ConnectToSource(

const UsdAttribute &shadingAttr,

const UsdShadeInput &sourceInput,

)

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.

static inline bool ConnectToSource(

const UsdShadeInput &input,

const UsdShadeInput &sourceInput,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static inline bool ConnectToSource(

const UsdShadeOutput &output,

const UsdShadeInput &sourceInput,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static inline bool ConnectToSource(

const UsdAttribute &shadingAttr,

const UsdShadeOutput &sourceOutput,

)

static inline bool ConnectToSource(

const UsdShadeInput &input,

const UsdShadeOutput &sourceOutput,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static inline bool ConnectToSource(

const UsdShadeOutput &output,

const UsdShadeOutput &sourceOutput,

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::NonAppliedAPI

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

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

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.