UsdShadeInput Class Reference

#include <input.h>

Classes
struct	Hash
	Hash functor. More...

Public Member Functions
	UsdShadeInput ()
TfToken const &	GetFullName () const
USDSHADE_API TfToken	GetBaseName () const
USDSHADE_API SdfValueTypeName	GetTypeName () const
UsdPrim	GetPrim () const
	Get the prim that the input belongs to. More...
template<typename T >
bool	Get (T *value, UsdTimeCode time=UsdTimeCode::Default()) const
	Convenience wrapper for the templated UsdAttribute::Get(). More...
USDSHADE_API bool	Get (VtValue *value, UsdTimeCode time=UsdTimeCode::Default()) const
	Convenience wrapper for VtValue version of UsdAttribute::Get(). More...
USDSHADE_API bool	Set (const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
template<typename T >
bool	Set (const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
	operator bool () const
Configuring the Input's Type
USDSHADE_API bool	SetRenderType (TfToken const &renderType) const
USDSHADE_API TfToken	GetRenderType () const
USDSHADE_API bool	HasRenderType () const
API to author and query an Input's sdrMetadata
This section provides API for authoring and querying shader registry metadata on an Input. When the owning shader prim is providing a shader definition, the authored "sdrMetadata" dictionary value provides metadata needed to populate the Input correctly in the shader registry. We expect the keys in sdrMetadata to correspond to the keys in SdrPropertyMetadata. However, this is not strictly enforced by the API. The only allowed value type in the "sdrMetadata" dictionary is a std::string since it needs to be converted into a NdrTokenMap, which Sdr will parse using the utilities available in SdrMetadataHelpers.
USDSHADE_API NdrTokenMap	GetSdrMetadata () const
USDSHADE_API std::string	GetSdrMetadataByKey (const TfToken &key) const
USDSHADE_API void	SetSdrMetadata (const NdrTokenMap &sdrMetadata) const
USDSHADE_API void	SetSdrMetadataByKey (const TfToken &key, const std::string &value) const
USDSHADE_API bool	HasSdrMetadata () const
USDSHADE_API bool	HasSdrMetadataByKey (const TfToken &key) const
USDSHADE_API void	ClearSdrMetadata () const
USDSHADE_API void	ClearSdrMetadataByKey (const TfToken &key) const
Connectability API
USDSHADE_API bool	SetConnectability (const TfToken &connectability) const
	Set the connectability of the Input. More...
USDSHADE_API TfToken	GetConnectability () const
	Returns the connectability of the Input. More...
USDSHADE_API bool	ClearConnectability () const
	Clears any authored connectability on the Input. More...
Connected Value API
USDSHADE_API UsdShadeAttributeVector	GetValueProducingAttributes (bool shaderOutputsOnly=false) const
	Find what is connected to this Input recursively. More...
USDSHADE_API UsdAttribute	GetValueProducingAttribute (UsdShadeAttributeType *attrType) const

Friends
class	UsdShadeConnectableAPI
bool	operator== (const UsdShadeInput &lhs, const UsdShadeInput &rhs)
bool	operator!= (const UsdShadeInput &lhs, const UsdShadeInput &rhs)

UsdAttribute API
USDSHADE_API	UsdShadeInput (const UsdAttribute &attr)
const UsdAttribute &	GetAttr () const
	Explicit UsdAttribute extractor. More...
	operator const UsdAttribute & () const
bool	IsDefined () const
USDSHADE_API bool	SetDocumentation (const std::string &docs) const
USDSHADE_API std::string	GetDocumentation () const
USDSHADE_API bool	SetDisplayGroup (const std::string &displayGroup) const
USDSHADE_API std::string	GetDisplayGroup () const
static USDSHADE_API bool	IsInput (const UsdAttribute &attr)
static USDSHADE_API bool	IsInterfaceInputName (const std::string &name)

Connections API
using	ConnectionModification = UsdShadeConnectionModification
using	SourceInfoVector = TfSmallVector< UsdShadeConnectionSourceInfo, 1 >
USDSHADE_API bool	CanConnect (const UsdAttribute &source) const
USDSHADE_API bool	CanConnect (const UsdShadeInput &sourceInput) const
USDSHADE_API bool	CanConnect (const UsdShadeOutput &sourceOutput) const
USDSHADE_API bool	ConnectToSource (UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
USDSHADE_API bool	ConnectToSource (UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
USDSHADE_API bool	ConnectToSource (SdfPath const &sourcePath) const
USDSHADE_API bool	ConnectToSource (UsdShadeInput const &sourceInput) const
USDSHADE_API bool	ConnectToSource (UsdShadeOutput const &sourceOutput) const
USDSHADE_API bool	SetConnectedSources (std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
USDSHADE_API SourceInfoVector	GetConnectedSources (SdfPathVector *invalidSourcePaths=nullptr) const
USDSHADE_API bool	GetConnectedSource (UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
USDSHADE_API bool	GetRawConnectedSourcePaths (SdfPathVector *sourcePaths) const
USDSHADE_API bool	HasConnectedSource () const
USDSHADE_API bool	IsSourceConnectionFromBaseMaterial () const
USDSHADE_API bool	DisconnectSource (UsdAttribute const &sourceAttr=UsdAttribute()) const
USDSHADE_API bool	ClearSources () const
USDSHADE_API bool	ClearSource () const

Detailed Description

This class encapsulates a shader or node-graph input, which is a connectable attribute representing a typed value.

Definition at line 48 of file input.h.

Member Typedef Documentation

using UsdShadeInput::ConnectionModification = UsdShadeConnectionModification

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

See Also

UsdShadeConnectableAPI::CanConnect

Definition at line 308 of file input.h.

using UsdShadeInput::SourceInfoVector = TfSmallVector<UsdShadeConnectionSourceInfo, 1>

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

See Also

UsdShadeConnectableAPI::CanConnect

Definition at line 376 of file input.h.

Constructor & Destructor Documentation

UsdShadeInput::UsdShadeInput ( )

inline

Default constructor returns an invalid Input. Exists for the sake of container classes

Definition at line 53 of file input.h.

USDSHADE_API UsdShadeInput::UsdShadeInput ( const UsdAttribute &  attr )

explicit

Speculative constructor that will produce a valid UsdShadeInput when attr already represents a shade Input, and produces an invalid UsdShadeInput otherwise (i.e. the explicit bool conversion operator will return false).

Member Function Documentation

USDSHADE_API bool UsdShadeInput::CanConnect

(

const UsdAttribute &

source

)

const

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

See Also

UsdShadeConnectableAPI::CanConnect

USDSHADE_API bool UsdShadeInput::CanConnect

(

const UsdShadeInput &

sourceInput

)

const

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

USDSHADE_API bool UsdShadeInput::CanConnect

(

const UsdShadeOutput &

sourceOutput

)

const

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

USDSHADE_API bool UsdShadeInput::ClearConnectability

(

)

const

Clears any authored connectability on the Input.

USDSHADE_API void UsdShadeInput::ClearSdrMetadata

(

)

const

Clears any "sdrMetadata" value authored on the Input in the current EditTarget.

USDSHADE_API void UsdShadeInput::ClearSdrMetadataByKey

(

const TfToken &

key

)

const

Clears the entry corresponding to the given key in the "sdrMetadata" dictionary authored in the current EditTarget.

USDSHADE_API bool UsdShadeInput::ClearSource

(

)

const

Deprecated:

USDSHADE_API bool UsdShadeInput::ClearSources

(

)

const

Clears sources for this Input in the current UsdEditTarget.

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

See Also

UsdShadeConnectableAPI::ClearSources

USDSHADE_API bool UsdShadeInput::ConnectToSource	(	UsdShadeConnectionSourceInfo const &	source,
		ConnectionModification const	mod = ConnectionModification::Replace
	)		const

Authors a connection for this Input

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 this input 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.

See Also

UsdShadeConnectableAPI::ConnectToSource

USDSHADE_API bool UsdShadeInput::ConnectToSource	(	UsdShadeConnectableAPI const &	source,
		TfToken const &	sourceName,
		UsdShadeAttributeType const	sourceType = UsdShadeAttributeType::Output,
		SdfValueTypeName	typeName = SdfValueTypeName()
	)		const

Deprecated:

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

USDSHADE_API bool UsdShadeInput::ConnectToSource

(

SdfPath const &

sourcePath

)

const

Authors a connection for this Input to the source at the given path.

See Also

UsdShadeConnectableAPI::ConnectToSource

USDSHADE_API bool UsdShadeInput::ConnectToSource

(

UsdShadeInput const &

sourceInput

)

const

Connects this Input to the given input, sourceInput.

See Also

UsdShadeConnectableAPI::ConnectToSource

USDSHADE_API bool UsdShadeInput::ConnectToSource

(

UsdShadeOutput const &

sourceOutput

)

const

Connects this Input to the given output, sourceOutput.

See Also

UsdShadeConnectableAPI::ConnectToSource

USDSHADE_API bool UsdShadeInput::DisconnectSource

(

UsdAttribute const &

sourceAttr = UsdAttribute()

)

const

Disconnect source for this Input. If sourceAttr is valid, only a connection to the specified attribute is disconnected, otherwise all connections are removed.

See Also

UsdShadeConnectableAPI::DisconnectSource

template<typename T >

bool UsdShadeInput::Get ( T *  value, UsdTimeCode  time = UsdTimeCode::Default()  ) const

inline

Convenience wrapper for the templated UsdAttribute::Get().

Definition at line 85 of file input.h.

USDSHADE_API bool UsdShadeInput::Get	(	VtValue *	value,
		UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Convenience wrapper for VtValue version of UsdAttribute::Get().

const UsdAttribute& UsdShadeInput::GetAttr ( ) const

inline

Explicit UsdAttribute extractor.

Definition at line 229 of file input.h.

USDSHADE_API TfToken UsdShadeInput::GetBaseName

(

)

const

Returns the name of the input.

We call this the base name since it strips off the "inputs:" namespace prefix from the attribute name, and returns it.

USDSHADE_API TfToken UsdShadeInput::GetConnectability

(

)

const

Returns the connectability of the Input.

See Also

SetConnectability()

USDSHADE_API bool UsdShadeInput::GetConnectedSource	(	UsdShadeConnectableAPI *	source,
		TfToken *	sourceName,
		UsdShadeAttributeType *	sourceType
	)		const

Deprecated:

USDSHADE_API SourceInfoVector UsdShadeInput::GetConnectedSources

(

SdfPathVector *

invalidSourcePaths = nullptr

)

const

Finds the valid sources of connections for the Input.

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

See Also

UsdShadeConnectableAPI::GetConnectedSources

USDSHADE_API std::string UsdShadeInput::GetDisplayGroup

(

)

const

Get the displayGroup metadata for this Input, i.e. hint for the location and nesting of the attribute.

See Also

UsdProperty::GetDisplayGroup(), UsdProperty::GetNestedDisplayGroup()

USDSHADE_API std::string UsdShadeInput::GetDocumentation

(

)

const

Get documentation string for this Input.

See Also

UsdObject::GetDocumentation()

TfToken const& UsdShadeInput::GetFullName ( ) const

inline

Get the name of the attribute associated with the Input.

Definition at line 60 of file input.h.

UsdPrim UsdShadeInput::GetPrim ( ) const

inline

Get the prim that the input belongs to.

Definition at line 79 of file input.h.

USDSHADE_API bool UsdShadeInput::GetRawConnectedSourcePaths

(

SdfPathVector *

sourcePaths

)

const

Deprecated:

Returns the "raw" (authored) connected source paths for this Input.

See Also

UsdShadeConnectableAPI::GetRawConnectedSourcePaths

USDSHADE_API TfToken UsdShadeInput::GetRenderType

(

)

const

Return this Input's specialized renderType, or an empty token if none was authored.

See Also

SetRenderType()

USDSHADE_API NdrTokenMap UsdShadeInput::GetSdrMetadata

(

)

const

Returns this Input's composed "sdrMetadata" dictionary as a NdrTokenMap.

USDSHADE_API std::string UsdShadeInput::GetSdrMetadataByKey

(

const TfToken &

key

)

const

Returns the value corresponding to key in the composed sdrMetadata dictionary.

USDSHADE_API SdfValueTypeName UsdShadeInput::GetTypeName

(

)

const

Get the "scene description" value type name of the attribute associated with the Input.

USDSHADE_API UsdAttribute UsdShadeInput::GetValueProducingAttribute

(

UsdShadeAttributeType *

attrType

)

const

Deprecated:

in favor of calling GetValueProducingAttributes

USDSHADE_API UsdShadeAttributeVector UsdShadeInput::GetValueProducingAttributes

(

bool

shaderOutputsOnly = false

)

const

Find what is connected to this Input recursively.

See Also

UsdShadeUtils::GetValueProducingAttributes

USDSHADE_API bool UsdShadeInput::HasConnectedSource

(

)

const

Returns true if and only if this Input is currently connected to a valid (defined) source.

See Also

UsdShadeConnectableAPI::HasConnectedSource

USDSHADE_API bool UsdShadeInput::HasRenderType

(

)

const

Return true if a renderType has been specified for this Input.

See Also

SetRenderType()

USDSHADE_API bool UsdShadeInput::HasSdrMetadata

(

)

const

Returns true if the Input has a non-empty composed "sdrMetadata" dictionary value.

USDSHADE_API bool UsdShadeInput::HasSdrMetadataByKey

(

const TfToken &

key

)

const

Returns true if there is a value corresponding to the given key in the composed "sdrMetadata" dictionary.

bool UsdShadeInput::IsDefined ( ) const

inline

Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an input.

Definition at line 238 of file input.h.

static USDSHADE_API bool UsdShadeInput::IsInput ( const UsdAttribute &  attr )

static

Test whether a given UsdAttribute represents a valid Input, which implies that creating a UsdShadeInput from the attribute will succeed.

Success implies that attr.IsDefined() is true.

static USDSHADE_API bool UsdShadeInput::IsInterfaceInputName ( const std::string &  name )

static

Test if this name has a namespace that indicates it could be an input.

USDSHADE_API bool UsdShadeInput::IsSourceConnectionFromBaseMaterial

(

)

const

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

See Also

UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial

UsdShadeInput::operator bool ( ) const

inlineexplicit

Return true if this Input is valid for querying and authoring values and metadata, which is identically equivalent to IsDefined().

Definition at line 272 of file input.h.

UsdShadeInput::operator const UsdAttribute & ( ) const

inline

Allow UsdShadeInput to auto-convert to UsdAttribute, so you can pass a UsdShadeInput to any function that accepts a UsdAttribute or const-ref thereto.

Definition at line 234 of file input.h.

USDSHADE_API bool UsdShadeInput::Set	(	const VtValue &	value,
		UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Set a value for the Input at time.

template<typename T >

bool UsdShadeInput::Set ( const T &  value, UsdTimeCode  time = UsdTimeCode::Default()  ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Set a value of the Input at time.

Definition at line 103 of file input.h.

USDSHADE_API bool UsdShadeInput::SetConnectability

(

const TfToken &

connectability

)

const

Set the connectability of the Input.

In certain shading data models, there is a need to distinguish which inputs can vary over a surface from those that must be uniform. This is accomplished in UsdShade by limiting the connectability of the input. This is done by setting the "connectability" metadata on the associated attribute.

Connectability of an Input can be set to UsdShadeTokens->full or UsdShadeTokens->interfaceOnly.

• full implies that the Input can be connected to any other Input or Output.
• interfaceOnly implies that the Input can only be connected to a NodeGraph Input (which represents an interface override, not a render-time dataflow connection), or another Input whose connectability is also "interfaceOnly".

The default connectability of an input is UsdShadeTokens->full.

See Also

SetConnectability()

USDSHADE_API bool UsdShadeInput::SetConnectedSources

(

std::vector< UsdShadeConnectionSourceInfo > const &

sourceInfos

)

const

Connects this Input to the given sources, sourceInfos

See Also

UsdShadeConnectableAPI::SetConnectedSources

USDSHADE_API bool UsdShadeInput::SetDisplayGroup

(

const std::string &

displayGroup

)

const

Set the displayGroup metadata for this Input, i.e. hinting for the location and nesting of the attribute.

Note for an input representing a nested SdrShaderProperty, its expected to have the scope delimited by a ":".

See Also

UsdProperty::SetDisplayGroup(), UsdProperty::SetNestedDisplayGroup()

SdrShaderProperty::GetPage()

USDSHADE_API bool UsdShadeInput::SetDocumentation

(

const std::string &

docs

)

const

Set documentation string for this Input.

See Also

UsdObject::SetDocumentation()

USDSHADE_API bool UsdShadeInput::SetRenderType

(

TfToken const &

renderType

)

const

Specify an alternative, renderer-specific type to use when emitting/translating this Input, rather than translating based on its GetTypeName()

For example, we set the renderType to "struct" for Inputs that are of renderman custom struct types.

Returns

true on success.

USDSHADE_API void UsdShadeInput::SetSdrMetadata

(

const NdrTokenMap &

sdrMetadata

)

const

Authors the given sdrMetadata value on this Input at the current EditTarget.

USDSHADE_API void UsdShadeInput::SetSdrMetadataByKey	(	const TfToken &	key,
		const std::string &	value
	)		const

Sets the value corresponding to key to the given string value, in the Input's "sdrMetadata" dictionary at the current EditTarget.

Friends And Related Function Documentation

bool operator!= ( const UsdShadeInput &  lhs, const UsdShadeInput &  rhs  )

friend

Inequality comparison. Return false if lhs and rhs represent the same UsdShadeInput, true otherwise.

Definition at line 284 of file input.h.

bool operator== ( const UsdShadeInput &  lhs, const UsdShadeInput &  rhs  )

friend

Equality comparison. Returns true if lhs and rhs represent the same UsdShadeInput, false otherwise.

Definition at line 278 of file input.h.

friend class UsdShadeConnectableAPI

friend

Definition at line 517 of file input.h.

---

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

• pxr/usd/usdShade/input.h