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

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

Classes

struct  Hash
 Hash functor. More...
 

Public Member Functions

 UsdShadeInput ()
 Default constructor returns an invalid Input. More...
 
TfToken const & GetFullName () const
 Get the name of the attribute associated with the Input. More...
 
USDSHADE_API TfToken GetBaseName () const
 Returns the name of the input. More...
 
USDSHADE_API SdfValueTypeName GetTypeName () const
 Get the "scene description" value type name of the attribute associated with the Input. More...
 
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
 Set a value for the Input at time. More...
 
template<typename T >
bool Set (const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
 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. More...
 
 operator bool () const
 Return true if this Input is valid for querying and authoring values and metadata, which is identically equivalent to IsDefined(). More...
 
Configuring the Input's Type
USDSHADE_API bool 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() More...
 
USDSHADE_API TfToken GetRenderType () const
 Return this Input's specialized renderType, or an empty token if none was authored. More...
 
USDSHADE_API bool HasRenderType () const
 Return true if a renderType has been specified for this Input. More...
 
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
 Returns this Input's composed "sdrMetadata" dictionary as a NdrTokenMap. More...
 
USDSHADE_API std::string GetSdrMetadataByKey (const TfToken &key) const
 Returns the value corresponding to key in the composed sdrMetadata dictionary. More...
 
USDSHADE_API void SetSdrMetadata (const NdrTokenMap &sdrMetadata) const
 Authors the given sdrMetadata value on this Input at the current EditTarget. More...
 
USDSHADE_API void 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. More...
 
USDSHADE_API bool HasSdrMetadata () const
 Returns true if the Input has a non-empty composed "sdrMetadata" dictionary value. More...
 
USDSHADE_API bool HasSdrMetadataByKey (const TfToken &key) const
 Returns true if there is a value corresponding to the given key in the composed "sdrMetadata" dictionary. More...
 
USDSHADE_API void ClearSdrMetadata () const
 Clears any "sdrMetadata" value authored on the Input in the current EditTarget. More...
 
USDSHADE_API void ClearSdrMetadataByKey (const TfToken &key) const
 Clears the entry corresponding to the given key in the "sdrMetadata" dictionary authored in the current EditTarget. More...
 
Connections API
USDSHADE_API bool 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. More...
 
USDSHADE_API bool CanConnect (const UsdShadeInput &sourceInput) const
 
USDSHADE_API bool CanConnect (const UsdShadeOutput &sourceOutput) const
 
USDSHADE_API bool ConnectToSource (UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
 Authors a connection for this Input to the source described by the following three elements: source, the connectable owning the source, sourceName, the name of the source and sourceType, the value type of the source shading attribute. More...
 
USDSHADE_API bool ConnectToSource (SdfPath const &sourcePath) const
 Authors a connection for this Input to the source at the given path. More...
 
USDSHADE_API bool ConnectToSource (UsdShadeInput const &sourceInput) const
 Connects this Input to the given input, sourceInput. More...
 
USDSHADE_API bool ConnectToSource (UsdShadeOutput const &sourceOutput) const
 Connects this Input to the given output, sourceOutput. More...
 
USDSHADE_API bool GetConnectedSource (UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
 Finds the source of a connection for this Input. More...
 
USDSHADE_API bool GetRawConnectedSourcePaths (SdfPathVector *sourcePaths) const
 Returns the "raw" (authored) connected source paths for this Input. More...
 
USDSHADE_API bool HasConnectedSource () const
 Returns true if and only if this Input is currently connected to a valid (defined) source. More...
 
USDSHADE_API bool 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. More...
 
USDSHADE_API bool DisconnectSource () const
 Disconnect source for this Input. More...
 
USDSHADE_API bool ClearSource () const
 Clears source for this shading attribute in the current UsdEditTarget. More...
 
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 UsdAttribute GetValueProducingAttribute (UsdShadeAttributeType *attrType) const
 Find what is connected to an Input recursively. More...
 

Friends

class UsdShadeConnectableAPI
 
bool operator== (const UsdShadeInput &lhs, const UsdShadeInput &rhs)
 Equality comparison. More...
 

UsdAttribute API

USDSHADE_API UsdShadeInput (const UsdAttribute &attr)
 Speculative constructor that will produce a valid UsdShadeInput when attr already represents a shade Input, and produces an invalid UsdShadeInput otherwise (i.e. More...
 
const UsdAttributeGetAttr () const
 Explicit UsdAttribute extractor. More...
 
 operator const UsdAttribute & () const
 Allow UsdShadeInput to auto-convert to UsdAttribute, so you can pass a UsdShadeInput to any function that accepts a UsdAttribute or const-ref thereto. More...
 
bool IsDefined () const
 Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an input. More...
 
USDSHADE_API bool SetDocumentation (const std::string &docs) const
 Set documentation string for this Input. More...
 
USDSHADE_API std::string GetDocumentation () const
 Get documentation string for this Input. More...
 
USDSHADE_API bool SetDisplayGroup (const std::string &displayGroup) const
 Set the displayGroup metadata for this Input, i.e. More...
 
USDSHADE_API std::string GetDisplayGroup () const
 Get the displayGroup metadata for this Input, i.e. More...
 
static USDSHADE_API bool IsInput (const UsdAttribute &attr)
 Test whether a given UsdAttribute represents a valid Input, which implies that creating a UsdShadeInput from the attribute will succeed. More...
 
static USDSHADE_API bool IsInterfaceInputName (const std::string &name)
 Test if this name has a namespace that indicates it could be an input. More...
 

Detailed Description

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

Definition at line 46 of file input.h.

Constructor & Destructor Documentation

UsdShadeInput ( )
inline

Default constructor returns an invalid Input.

Exists for the sake of container classes

Definition at line 51 of file input.h.

USDSHADE_API 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 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 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 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 ClearConnectability ( ) const

Clears any authored connectability on the Input.

USDSHADE_API void ClearSdrMetadata ( ) const

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

USDSHADE_API void 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 ClearSource ( ) const

Clears source for this shading attribute in the current UsdEditTarget.

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

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

Authors a connection for this Input to the source described by the following three elements: source, the connectable owning the source, sourceName, the name of the source and sourceType, the value type of the source shading attribute.

typeName if specified, is the typename of the attribute to create on the source if it doesn't exist. It is also used to validate whether the types of the source and consumer of the connection are compatible.

See Also
UsdShadeConnectableAPI::ConnectToSource
USDSHADE_API bool 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 ConnectToSource ( UsdShadeInput const &  sourceInput) const

Connects this Input to the given input, sourceInput.

See Also
UsdShadeConnectableAPI::ConnectToSource
USDSHADE_API bool ConnectToSource ( UsdShadeOutput const &  sourceOutput) const

Connects this Input to the given output, sourceOutput.

See Also
UsdShadeConnectableAPI::ConnectToSource
USDSHADE_API bool DisconnectSource ( ) const

Disconnect source for this Input.

See Also
UsdShadeConnectableAPI::DisconnectSource
bool Get ( T *  value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const
inline

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

Definition at line 83 of file input.h.

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

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

const UsdAttribute& GetAttr ( ) const
inline

Explicit UsdAttribute extractor.

Definition at line 227 of file input.h.

USDSHADE_API TfToken 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 GetConnectability ( ) const

Returns the connectability of the Input.

See Also
SetConnectability()
USDSHADE_API bool GetConnectedSource ( UsdShadeConnectableAPI source,
TfToken sourceName,
UsdShadeAttributeType *  sourceType 
) const

Finds the source of a connection for this Input.

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
The python wrapping for this method returns a (source, sourceName, sourceType) tuple if the parameter is connected, else None
See Also
UsdShadeConnectableAPI::GetConnectedSource
USDSHADE_API std::string 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 GetDocumentation ( ) const

Get documentation string for this Input.

See Also
UsdObject::GetDocumentation()
TfToken const& GetFullName ( ) const
inline

Get the name of the attribute associated with the Input.

Definition at line 58 of file input.h.

UsdPrim GetPrim ( ) const
inline

Get the prim that the input belongs to.

Definition at line 77 of file input.h.

USDSHADE_API bool GetRawConnectedSourcePaths ( SdfPathVector *  sourcePaths) const

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

See Also
UsdShadeConnectableAPI::GetRawConnectedSourcePaths
USDSHADE_API TfToken GetRenderType ( ) const

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

See Also
SetRenderType()
USDSHADE_API NdrTokenMap GetSdrMetadata ( ) const

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

USDSHADE_API std::string GetSdrMetadataByKey ( const TfToken key) const

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

USDSHADE_API SdfValueTypeName GetTypeName ( ) const

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

USDSHADE_API UsdAttribute GetValueProducingAttribute ( UsdShadeAttributeType *  attrType) const

Find what is connected to an Input recursively.

When tracing connections within networks that contain UsdShadeNodeGraph nodes, the actual output or value at the end of an input might be multiple connections removed. The method below resolves this across multiple physical connections.

An UsdInput is getting its value from one of these sources:

  • If the input is not connected the UsdAttribute for this input is returned, but only if it has an authored value. The input attribute itself carries the value for this input.
  • If the input is connected we follow the connection(s) until we reach a valid output of a UsdShadeShader node or if we reach a valid UsdShadeInput attribute of a UsdShadeNodeGraph or UsdShadeMaterial. Note that we return the last attribute along the connection chain that has an authored value, which might not be the last attribute in the chain itself.

This function returns a valid UsdAttribute if a valid output was encountered or an input with an authored value. Otherwise an invalid UsdAttribute is returned. If a valid attrType pointer is provided, the method also returns what type of attribute it found, which is Invalid, Input or Output.

USDSHADE_API bool 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 HasRenderType ( ) const

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

See Also
SetRenderType()
USDSHADE_API bool HasSdrMetadata ( ) const

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

USDSHADE_API bool HasSdrMetadataByKey ( const TfToken key) const

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

bool IsDefined ( ) const
inline

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

Definition at line 236 of file input.h.

static USDSHADE_API bool 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 IsInterfaceInputName ( const std::string &  name)
static

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

USDSHADE_API bool 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
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 266 of file input.h.

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 232 of file input.h.

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

Set a value for the Input at time.

bool 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 101 of file input.h.

USDSHADE_API bool 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 SetDisplayGroup ( const std::string &  displayGroup) const

Set the displayGroup metadata for this Input, i.e.

hinting for the location and nesting of the attribute.

See Also
UsdProperty::SetDisplayGroup(), UsdProperty::SetNestedDisplayGroup()
USDSHADE_API bool SetDocumentation ( const std::string &  docs) const

Set documentation string for this Input.

See Also
UsdObject::SetDocumentation()
USDSHADE_API bool 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 SetSdrMetadata ( const NdrTokenMap &  sdrMetadata) const

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

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

Equality comparison.

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

Definition at line 272 of file input.h.


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