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

#include <connectableAPI.h>

+ Inheritance diagram for UsdShadeConnectableAPI:

Public Member Functions

 UsdShadeConnectableAPI (const UsdPrim &prim=UsdPrim())
 
 UsdShadeConnectableAPI (const UsdSchemaBase &schemaObj)
 
virtual USDSHADE_API ~UsdShadeConnectableAPI ()
 Destructor. More...
 
USDSHADE_API bool IsContainer () const
 
USDSHADE_API bool RequiresEncapsulation () const
 
Outputs
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 (bool onlyAuthored=true) const
 
Inputs
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 (bool onlyAuthored=true) const
 
- Public Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
 
virtual USD_API ~UsdAPISchemaBase ()=0
 Destructor. More...
 
- 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
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is. More...
 
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
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDSHADE_API
UsdShadeConnectableAPI 
Get (const UsdStagePtr &stage, const SdfPath &path)
 
- Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::NonAppliedAPI
 
- Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 

Protected Member Functions

USDSHADE_API UsdSchemaKind _GetSchemaKind () const override
 
USDSHADE_API bool _IsCompatible () const override
 
- Protected Member Functions inherited from UsdAPISchemaBase
 UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
 
 UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
 
const TfToken_GetInstanceName () const
 
- 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
 

Connections

Inputs and outputs on shaders and node-graphs are connectable. This section provides API for authoring and managing these connections in a shading network.

using ConnectionModification = UsdShadeConnectionModification
 
static USDSHADE_API bool CanConnect (const UsdShadeInput &input, const UsdAttribute &source)
 
static USDSHADE_API bool CanConnect (const UsdShadeInput &input, const UsdShadeInput &sourceInput)
 
static USDSHADE_API bool CanConnect (const UsdShadeInput &input, const UsdShadeOutput &sourceOutput)
 
static USDSHADE_API bool CanConnect (const UsdShadeOutput &output, const UsdAttribute &source=UsdAttribute())
 
static USDSHADE_API bool CanConnect (const UsdShadeOutput &output, const UsdShadeInput &sourceInput)
 
static USDSHADE_API bool CanConnect (const UsdShadeOutput &output, const UsdShadeOutput &sourceOutput)
 
static USDSHADE_API bool ConnectToSource (UsdAttribute const &shadingAttr, UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace)
 
static USDSHADE_API bool ConnectToSource (UsdShadeInput const &input, UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace)
 
static USDSHADE_API bool ConnectToSource (UsdShadeOutput const &output, UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace)
 
static USDSHADE_API bool ConnectToSource (UsdAttribute const &shadingAttr, UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName())
 
static USDSHADE_API bool ConnectToSource (UsdShadeInput const &input, UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName())
 
static USDSHADE_API bool ConnectToSource (UsdShadeOutput const &output, UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName())
 
static USDSHADE_API bool ConnectToSource (UsdAttribute const &shadingAttr, SdfPath const &sourcePath)
 
static USDSHADE_API bool ConnectToSource (UsdShadeInput const &input, SdfPath const &sourcePath)
 
static USDSHADE_API bool ConnectToSource (UsdShadeOutput const &output, SdfPath const &sourcePath)
 
static USDSHADE_API bool ConnectToSource (UsdAttribute const &shadingAttr, UsdShadeInput const &sourceInput)
 
static USDSHADE_API bool ConnectToSource (UsdShadeInput const &input, UsdShadeInput const &sourceInput)
 
static USDSHADE_API bool ConnectToSource (UsdShadeOutput const &output, UsdShadeInput const &sourceInput)
 
static USDSHADE_API bool ConnectToSource (UsdAttribute const &shadingAttr, UsdShadeOutput const &sourceOutput)
 
static USDSHADE_API bool ConnectToSource (UsdShadeInput const &input, UsdShadeOutput const &sourceOutput)
 
static USDSHADE_API bool ConnectToSource (UsdShadeOutput const &output, UsdShadeOutput const &sourceOutput)
 
static USDSHADE_API bool SetConnectedSources (UsdAttribute const &shadingAttr, std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos)
 
static USDSHADE_API bool GetConnectedSource (UsdAttribute const &shadingAttr, UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType)
 
static USDSHADE_API bool GetConnectedSource (UsdShadeInput const &input, UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType)
 
static USDSHADE_API bool GetConnectedSource (UsdShadeOutput const &output, UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType)
 
static USDSHADE_API
UsdShadeSourceInfoVector 
GetConnectedSources (UsdAttribute const &shadingAttr, SdfPathVector *invalidSourcePaths=nullptr)
 
static USDSHADE_API
UsdShadeSourceInfoVector 
GetConnectedSources (UsdShadeInput const &input, SdfPathVector *invalidSourcePaths=nullptr)
 
static USDSHADE_API
UsdShadeSourceInfoVector 
GetConnectedSources (UsdShadeOutput const &output, SdfPathVector *invalidSourcePaths=nullptr)
 
static USDSHADE_API bool GetRawConnectedSourcePaths (UsdAttribute const &shadingAttr, SdfPathVector *sourcePaths)
 
static USDSHADE_API bool GetRawConnectedSourcePaths (UsdShadeInput const &input, SdfPathVector *sourcePaths)
 
static USDSHADE_API bool GetRawConnectedSourcePaths (UsdShadeOutput const &output, SdfPathVector *sourcePaths)
 
static USDSHADE_API bool HasConnectedSource (const UsdAttribute &shadingAttr)
 
static USDSHADE_API bool HasConnectedSource (const UsdShadeInput &input)
 
static USDSHADE_API bool HasConnectedSource (const UsdShadeOutput &output)
 
static USDSHADE_API bool IsSourceConnectionFromBaseMaterial (const UsdAttribute &shadingAttr)
 
static USDSHADE_API bool IsSourceConnectionFromBaseMaterial (const UsdShadeInput &input)
 
static USDSHADE_API bool IsSourceConnectionFromBaseMaterial (const UsdShadeOutput &output)
 
static USDSHADE_API bool DisconnectSource (UsdAttribute const &shadingAttr, UsdAttribute const &sourceAttr=UsdAttribute())
 
static USDSHADE_API bool DisconnectSource (UsdShadeInput const &input, UsdAttribute const &sourceAttr=UsdAttribute())
 
static USDSHADE_API bool DisconnectSource (UsdShadeOutput const &output, UsdAttribute const &sourceAttr=UsdAttribute())
 
static USDSHADE_API bool ClearSources (UsdAttribute const &shadingAttr)
 
static USDSHADE_API bool ClearSources (UsdShadeInput const &input)
 
static USDSHADE_API bool ClearSources (UsdShadeOutput const &output)
 
static USDSHADE_API bool ClearSource (UsdAttribute const &shadingAttr)
 
static USDSHADE_API bool ClearSource (UsdShadeInput const &input)
 
static USDSHADE_API bool ClearSource (UsdShadeOutput const &output)
 
static USDSHADE_API bool HasConnectableAPI (const TfType &schemaType)
 
template<typename T >
static bool HasConnectableAPI ()
 

Additional Inherited Members

- Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector _GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)
 

Detailed Description

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.

Definition at line 81 of file connectableAPI.h.

Member Typedef Documentation

Determines whether the given input can be connected to the given source attribute, which can be an input or an output.

The result depends on the "connectability" of the input and the source attributes. Depending on the prim type, this may require the plugin that defines connectability behavior for that prim type be loaded.

See Also
UsdShadeInput::SetConnectability
UsdShadeInput::GetConnectability

Definition at line 249 of file connectableAPI.h.

Constructor & Destructor Documentation

UsdShadeConnectableAPI::UsdShadeConnectableAPI ( const UsdPrim prim = UsdPrim())
inlineexplicit

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

Definition at line 93 of file connectableAPI.h.

UsdShadeConnectableAPI::UsdShadeConnectableAPI ( const UsdSchemaBase schemaObj)
inlineexplicit

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

Definition at line 101 of file connectableAPI.h.

virtual USDSHADE_API UsdShadeConnectableAPI::~UsdShadeConnectableAPI ( )
virtual

Destructor.

Member Function Documentation

USDSHADE_API UsdSchemaKind UsdShadeConnectableAPI::_GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also
UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

USDSHADE_API bool UsdShadeConnectableAPI::_IsCompatible ( ) const
overrideprotectedvirtual

Returns true if the given prim is compatible with this API schema, i.e. if it is a valid shader or a node-graph. A prim has a compatible connectableAPI if a valid behavior is registered for it.

Reimplemented from UsdAPISchemaBase.

static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeInput input,
const UsdAttribute source 
)
static

Determines whether the given input can be connected to the given source attribute, which can be an input or an output.

The result depends on the "connectability" of the input and the source attributes. Depending on the prim type, this may require the plugin that defines connectability behavior for that prim type be loaded.

See Also
UsdShadeInput::SetConnectability
UsdShadeInput::GetConnectability
static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeInput input,
const UsdShadeInput sourceInput 
)
inlinestatic

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

Definition at line 209 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeInput input,
const UsdShadeOutput sourceOutput 
)
inlinestatic

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

Definition at line 216 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeOutput output,
const UsdAttribute source = UsdAttribute() 
)
static

Determines whether the given output can be connected to the given source attribute, which can be an input or an output.

An output is considered to be connectable only if it belongs to a node-graph. Shader outputs are not connectable.

source is an optional argument. If a valid UsdAttribute is supplied for it, this method will return true only if the source attribute is owned by a descendant of the node-graph owning the output.

static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeOutput output,
const UsdShadeInput sourceInput 
)
inlinestatic

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

Definition at line 237 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::CanConnect ( const UsdShadeOutput output,
const UsdShadeOutput sourceOutput 
)
inlinestatic

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

Definition at line 244 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ClearSource ( UsdAttribute const &  shadingAttr)
inlinestatic
Deprecated:
This is the older version that only referenced a single source. Please use ClearSources instead.

Definition at line 652 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ClearSource ( UsdShadeInput const &  input)
inlinestatic
Deprecated:

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

Definition at line 659 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ClearSource ( UsdShadeOutput const &  output)
inlinestatic
Deprecated:

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

Definition at line 666 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ClearSources ( UsdAttribute const &  shadingAttr)
static

Clears sources for this shading attribute in the current UsdEditTarget.

Most of the time, what you probably want is DisconnectSource() rather than this function.

See Also
DisconnectSource()
static USDSHADE_API bool UsdShadeConnectableAPI::ClearSources ( UsdShadeInput const &  input)
inlinestatic

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

Definition at line 639 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ClearSources ( UsdShadeOutput const &  output)
inlinestatic

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

Definition at line 645 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdAttribute const &  shadingAttr,
UsdShadeConnectionSourceInfo const &  source,
ConnectionModification const  mod = ConnectionModification::Replace 
)
static

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.

Returns
true if a connection was created successfully. false if shadingAttr or source is invalid.
Note
This method does not verify the connectability of the shading attribute to the source. Clients must invoke CanConnect() themselves to ensure compatibility.
The source shading attribute is created if it doesn't exist already.
static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeInput const &  input,
UsdShadeConnectionSourceInfo const &  source,
ConnectionModification const  mod = ConnectionModification::Replace 
)
inlinestatic

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

Definition at line 280 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeOutput const &  output,
UsdShadeConnectionSourceInfo const &  source,
ConnectionModification const  mod = ConnectionModification::Replace 
)
inlinestatic

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

Definition at line 290 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdAttribute const &  shadingAttr,
UsdShadeConnectableAPI const &  source,
TfToken const &  sourceName,
UsdShadeAttributeType const  sourceType = UsdShadeAttributeType::Output,
SdfValueTypeName  typeName = SdfValueTypeName() 
)
static
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 USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeInput const &  input,
UsdShadeConnectableAPI const &  source,
TfToken const &  sourceName,
UsdShadeAttributeType const  sourceType = UsdShadeAttributeType::Output,
SdfValueTypeName  typeName = SdfValueTypeName() 
)
inlinestatic
Deprecated:

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

Definition at line 312 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeOutput const &  output,
UsdShadeConnectableAPI const &  source,
TfToken const &  sourceName,
UsdShadeAttributeType const  sourceType = UsdShadeAttributeType::Output,
SdfValueTypeName  typeName = SdfValueTypeName() 
)
inlinestatic
Deprecated:

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

Definition at line 326 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdAttribute const &  shadingAttr,
SdfPath const &  sourcePath 
)
static

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 source at path, sourcePath.

sourcePath should be the fully namespaced property path.

This overload is provided for convenience, for use in contexts where the prim types are unknown or unavailable.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeInput const &  input,
SdfPath const &  sourcePath 
)
inlinestatic

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

Definition at line 352 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeOutput const &  output,
SdfPath const &  sourcePath 
)
inlinestatic

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

Definition at line 359 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdAttribute const &  shadingAttr,
UsdShadeInput const &  sourceInput 
)
static

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 USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeInput const &  input,
UsdShadeInput const &  sourceInput 
)
inlinestatic

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

Definition at line 374 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeOutput const &  output,
UsdShadeInput const &  sourceInput 
)
inlinestatic

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

Definition at line 381 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdAttribute const &  shadingAttr,
UsdShadeOutput const &  sourceOutput 
)
static

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

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeInput const &  input,
UsdShadeOutput const &  sourceOutput 
)
inlinestatic

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

Definition at line 396 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::ConnectToSource ( UsdShadeOutput const &  output,
UsdShadeOutput const &  sourceOutput 
)
inlinestatic

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

Definition at line 403 of file connectableAPI.h.

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

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

static USDSHADE_API bool UsdShadeConnectableAPI::DisconnectSource ( UsdAttribute const &  shadingAttr,
UsdAttribute const &  sourceAttr = UsdAttribute() 
)
static

Disconnect source for this shading attribute.

If sourceAttr is valid it will disconnect the connection to this upstream attribute. Otherwise it will disconnect all connections by authoring an empty list of connections for the attribute shadingAttr.

This may author more scene description than you might expect - we define the behavior of disconnect to be that, even if a shading attribute becomes connected in a weaker layer than the current UsdEditTarget, the attribute will still be disconnected in the composition, therefore we must "block" it in the current UsdEditTarget.

See Also
ConnectToSource().
static USDSHADE_API bool UsdShadeConnectableAPI::DisconnectSource ( UsdShadeInput const &  input,
UsdAttribute const &  sourceAttr = UsdAttribute() 
)
inlinestatic

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

Definition at line 614 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::DisconnectSource ( UsdShadeOutput const &  output,
UsdAttribute const &  sourceAttr = UsdAttribute() 
)
inlinestatic

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

Definition at line 622 of file connectableAPI.h.

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

Return a UsdShadeConnectableAPI 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:

UsdShadeConnectableAPI(stage->GetPrimAtPath(path));
static USDSHADE_API bool UsdShadeConnectableAPI::GetConnectedSource ( UsdAttribute const &  shadingAttr,
UsdShadeConnectableAPI source,
TfToken sourceName,
UsdShadeAttributeType sourceType 
)
static
Deprecated:
Shading attributes can have multiple connections and so using GetConnectedSources is needed in general

Finds the source of a connection for the given shading attribute.

shadingAttr is the shading attribute whose connection we want to interrogate. source is an output parameter which will be set to the source connectable prim. sourceName will be set to the name of the source shading attribute, which may be an input or an output, as specified by sourceType sourceType will have the type of the source shading attribute, i.e. whether it is an Input or Output

Returns
true if the shading attribute is connected to a valid, defined source attribute. false if the shading attribute is not connected to a single, defined source attribute.
Note
Previously this method would silently return false for multiple connections. We are changing the behavior of this method to return the result for the first connection and issue a TfWarn about it. We want to encourage clients to use GetConnectedSources going forward.
The python wrapping for this method returns a (source, sourceName, sourceType) tuple if the parameter is connected, else None
static USDSHADE_API bool UsdShadeConnectableAPI::GetConnectedSource ( UsdShadeInput const &  input,
UsdShadeConnectableAPI source,
TfToken sourceName,
UsdShadeAttributeType sourceType 
)
inlinestatic
Deprecated:

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

Definition at line 466 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::GetConnectedSource ( UsdShadeOutput const &  output,
UsdShadeConnectableAPI source,
TfToken sourceName,
UsdShadeAttributeType sourceType 
)
inlinestatic
Deprecated:

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

Definition at line 477 of file connectableAPI.h.

static USDSHADE_API UsdShadeSourceInfoVector UsdShadeConnectableAPI::GetConnectedSources ( UsdAttribute const &  shadingAttr,
SdfPathVector invalidSourcePaths = nullptr 
)
static

Finds the valid sources of connections for the given shading attribute.

shadingAttr is the shading attribute whose connections we want to interrogate. invalidSourcePaths is an optional output parameter to collect the invalid source paths that have not been reported in the returned vector.

Returns a vector of UsdShadeConnectionSourceInfo structs with information about each upsteam attribute. If the vector is empty, there have been no connections.

Note
A valid connection requires the existence of the source attribute and also requires that the source prim is UsdShadeConnectableAPI compatible.
The python wrapping returns a tuple with the valid connections first, followed by the invalid source paths.
static USDSHADE_API UsdShadeSourceInfoVector UsdShadeConnectableAPI::GetConnectedSources ( UsdShadeInput const &  input,
SdfPathVector invalidSourcePaths = nullptr 
)
static

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

static USDSHADE_API UsdShadeSourceInfoVector UsdShadeConnectableAPI::GetConnectedSources ( UsdShadeOutput const &  output,
SdfPathVector invalidSourcePaths = nullptr 
)
static

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

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

Return the requested input if it exists.

name is the unnamespaced base name.

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

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

Return the requested output if it exists.

name is the unnamespaced base name.

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

static USDSHADE_API bool UsdShadeConnectableAPI::GetRawConnectedSourcePaths ( UsdAttribute const &  shadingAttr,
SdfPathVector sourcePaths 
)
static
Deprecated:
Please us GetConnectedSources to retrieve multiple connections

Returns the "raw" (authored) connected source paths for the given shading attribute.

static USDSHADE_API bool UsdShadeConnectableAPI::GetRawConnectedSourcePaths ( UsdShadeInput const &  input,
SdfPathVector sourcePaths 
)
inlinestatic
Deprecated:

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

Definition at line 530 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::GetRawConnectedSourcePaths ( UsdShadeOutput const &  output,
SdfPathVector sourcePaths 
)
inlinestatic
Deprecated:

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

Definition at line 538 of file connectableAPI.h.

static USDSHADE_API const TfTokenVector& UsdShadeConnectableAPI::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.

static USDSHADE_API bool UsdShadeConnectableAPI::HasConnectableAPI ( const TfType schemaType)
static

Return true if the schemaType has a valid connectableAPIBehavior registered, false otherwise. To check if a prim's connectableAPI has a behavior defined, use UsdSchemaBase::operator bool().

template<typename T >
static bool UsdShadeConnectableAPI::HasConnectableAPI ( )
inlinestatic

Return true if the schema type T has a connectableAPIBehavior registered, false otherwise.

Definition at line 680 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::HasConnectedSource ( const UsdAttribute shadingAttr)
static

Returns true if and only if the shading attribute is currently connected to at least one valid (defined) source.

If you will be calling GetConnectedSources() afterwards anyways, it will be much faster to instead check if the returned vector is empty:

if (!connections.empty()){
// process connected attribute
} else {
// process unconnected attribute
}
static USDSHADE_API bool UsdShadeConnectableAPI::HasConnectedSource ( const UsdShadeInput input)
inlinestatic

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

Definition at line 563 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::HasConnectedSource ( const UsdShadeOutput output)
inlinestatic

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

Definition at line 569 of file connectableAPI.h.

USDSHADE_API bool UsdShadeConnectableAPI::IsContainer ( ) const

Returns true if the prim is a container.

The underlying prim type may provide runtime behavior that defines whether it is a container.

static USDSHADE_API bool UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial ( const UsdAttribute shadingAttr)
static

Returns true if the connection to the given shading attribute's source, as returned by UsdShadeConnectableAPI::GetConnectedSource(), is authored across a specializes arc, which is used to denote a base material.

static USDSHADE_API bool UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial ( const UsdShadeInput input)
inlinestatic

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

Definition at line 583 of file connectableAPI.h.

static USDSHADE_API bool UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial ( const UsdShadeOutput output)
inlinestatic

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

Definition at line 589 of file connectableAPI.h.

USDSHADE_API bool UsdShadeConnectableAPI::RequiresEncapsulation ( ) const

Returns true if container encapsulation rules should be respected when evaluating connectibility behavior, false otherwise.

The underlying prim type may provide runtime behavior that defines if encapsulation rules are respected or not.

static USDSHADE_API bool UsdShadeConnectableAPI::SetConnectedSources ( UsdAttribute const &  shadingAttr,
std::vector< UsdShadeConnectionSourceInfo > const &  sourceInfos 
)
static

Authors a list of connections for a given shading attribute shadingAttr.

shadingAttr can represent a parameter, an input or an output. sourceInfos is a vector of structs that describes the upstream source attributes with all the information necessary to make all the connections. See the documentation for UsdShadeConnectionSourceInfo.

Returns
true if all connection were created successfully. false if the shadingAttr or one of the sources are invalid.
Note
A valid connection is one that has a valid UsdShadeConnectionSourceInfo, which requires the existence of the upstream source prim. It does not require the existence of the source attribute as it will be create if necessary.

Friends And Related Function Documentation

friend class UsdSchemaRegistry
friend

Definition at line 140 of file connectableAPI.h.

Member Data Documentation

const UsdSchemaKind UsdShadeConnectableAPI::schemaKind = UsdSchemaKind::NonAppliedAPI
static

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

See Also
UsdSchemaKind

Definition at line 87 of file connectableAPI.h.


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