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

This class encapsulates a shader or node-graph output, which is a connectable property representing a typed, externally computed value. More...

Public Member Functions

 UsdShadeOutput ()
 Default constructor returns an invalid Output. More...
 
TfToken const & GetFullName () const
 Get the name of the attribute associated with the output. More...
 
USDSHADE_API TfToken GetBaseName () const
 Returns the name of the output. More...
 
UsdPrim GetPrim () const
 Get the prim that the output belongs to. More...
 
USDSHADE_API SdfValueTypeName GetTypeName () const
 Get the "scene description" value type name of the attribute associated with the output. More...
 
USDSHADE_API bool Set (const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
 Set a value for the output. 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 the attribute value of the Output at time. More...
 
 operator bool () const
 Return true if this Output is valid for querying and authoring values and metadata, which is identically equivalent to IsDefined(). More...
 
Configuring the Output's Type
USDSHADE_API bool SetRenderType (TfToken const &renderType) const
 Specify an alternative, renderer-specific type to use when emitting/translating this output, rather than translating based on its GetTypeName() More...
 
USDSHADE_API TfToken GetRenderType () const
 Return this output'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 output. More...
 
API to author and query an Output's sdrMetadata

This section provides API for authoring and querying shader registry metadata on an Output.

When the owning shader prim is providing a shader definition, the authored "sdrMetadata" dictionary value provides metadata needed to populate the Output 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 Output'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 Output 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 Output's "sdrMetadata" dictionary at the current EditTarget. More...
 
USDSHADE_API bool HasSdrMetadata () const
 Returns true if the Output 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 Output 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 Output 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 Output 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 Output to the source at the given path. More...
 
USDSHADE_API bool ConnectToSource (UsdShadeInput const &sourceInput) const
 Connects this Output to the given input, sourceInput. More...
 
USDSHADE_API bool ConnectToSource (UsdShadeOutput const &sourceOutput) const
 Connects this Output 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 Output. More...
 
USDSHADE_API bool GetRawConnectedSourcePaths (SdfPathVector *sourcePaths) const
 Returns the "raw" (authored) connected source paths for this Output. More...
 
USDSHADE_API bool HasConnectedSource () const
 Returns true if and only if this Output is currently connected to a valid (defined) source. More...
 
USDSHADE_API bool IsSourceConnectionFromBaseMaterial () const
 Returns true if the connection to this Output'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 Output. More...
 
USDSHADE_API bool ClearSource () const
 Clears source for this shading property in the current UsdEditTarget. More...
 

Friends

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

UsdAttribute API

USDSHADE_API UsdShadeOutput (const UsdAttribute &attr)
 Speculative constructor that will produce a valid UsdShadeOutput when attr already represents a shade Output, and produces an invalid UsdShadeOutput otherwise (i.e. More...
 
UsdAttribute GetAttr () const
 Explicit UsdAttribute extractor. More...
 
const UsdPropertyGetProperty () const
 Explicit UsdProperty extractor. More...
 
 operator UsdAttribute () const
 Allow UsdShadeOutput to auto-convert to UsdAttribute, so you can pass a UsdShadeOutput to any function that accepts a UsdAttribute or const-ref thereto. More...
 
 operator const UsdProperty & () const
 Allow UsdShadeOutput to auto-convert to UsdProperty, so you can pass a UsdShadeOutput to any function that accepts a UsdProperty or const-ref thereto. More...
 
UsdRelationship GetRel () const
 Explicit UsdRelationship extractor. More...
 
bool IsTerminal () const
 Returns whether the Output represents a terminal relationship on a material, which is a concept we'd like to retire in favor of outputs. More...
 
bool IsDefined () const
 Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an output. More...
 
static USDSHADE_API bool IsOutput (const UsdAttribute &attr)
 Test whether a given UsdAttribute represents a valid Output, which implies that creating a UsdShadeOutput from the attribute will succeed. More...
 

Detailed Description

This class encapsulates a shader or node-graph output, which is a connectable property representing a typed, externally computed value.

Definition at line 47 of file output.h.

Constructor & Destructor Documentation

UsdShadeOutput ( )
inline

Default constructor returns an invalid Output.

Exists for container classes

Definition at line 52 of file output.h.

USDSHADE_API UsdShadeOutput ( const UsdAttribute attr)
explicit

Speculative constructor that will produce a valid UsdShadeOutput when attr already represents a shade Output, and produces an invalid UsdShadeOutput 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 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.

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

Clears any "sdrMetadata" value authored on the Output 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 property 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 Output 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 Output to the source at the given path.

See Also
UsdShadeConnectableAPI::ConnectToSource
USDSHADE_API bool ConnectToSource ( UsdShadeInput const &  sourceInput) const

Connects this Output to the given input, sourceInput.

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

Connects this Output to the given output, sourceOutput.

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

Disconnect source for this Output.

See Also
UsdShadeConnectableAPI::DisconnectSource
UsdAttribute GetAttr ( ) const
inline

Explicit UsdAttribute extractor.

Definition at line 222 of file output.h.

USDSHADE_API TfToken GetBaseName ( ) const

Returns the name of the output.

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

Note
This simply returns the full property name if the Output represents a terminal on a material.
USDSHADE_API bool GetConnectedSource ( UsdShadeConnectableAPI source,
TfToken sourceName,
UsdShadeAttributeType *  sourceType 
) const

Finds the source of a connection for this Output.

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 property, i.e. whether it is an Input or Output

Returns
true if the shading property is connected to a valid, defined source attribute. false if the shading property 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
TfToken const& GetFullName ( ) const
inline

Get the name of the attribute associated with the output.

Note
Returns the relationship name if it represents a terminal on a material.

Definition at line 62 of file output.h.

UsdPrim GetPrim ( ) const
inline

Get the prim that the output belongs to.

Definition at line 78 of file output.h.

const UsdProperty& GetProperty ( ) const
inline

Explicit UsdProperty extractor.

Definition at line 225 of file output.h.

USDSHADE_API bool GetRawConnectedSourcePaths ( SdfPathVector *  sourcePaths) const

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

See Also
UsdShadeConnectableAPI::GetRawConnectedSourcePaths
UsdRelationship GetRel ( ) const
inline

Explicit UsdRelationship extractor.

Definition at line 238 of file output.h.

USDSHADE_API TfToken GetRenderType ( ) const

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

See Also
SetRenderType()
USDSHADE_API NdrTokenMap GetSdrMetadata ( ) const

Returns this Output'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 output.

Note
If this is an output belonging to a terminal on a material, which does not have an associated attribute, we return 'Token' as the type.
USDSHADE_API bool HasConnectedSource ( ) const

Returns true if and only if this Output 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 output.

See Also
SetRenderType()
USDSHADE_API bool HasSdrMetadata ( ) const

Returns true if the Output 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 output.

For backwards compatibility, also returns true for the case of a valid terminal relationship; see IsTerminal().

Definition at line 252 of file output.h.

static USDSHADE_API bool IsOutput ( const UsdAttribute attr)
static

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

Success implies that prop.IsDefined() is true.

USDSHADE_API bool IsSourceConnectionFromBaseMaterial ( ) const

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

See Also
UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
bool IsTerminal ( ) const
inline

Returns whether the Output represents a terminal relationship on a material, which is a concept we'd like to retire in favor of outputs.

This is temporary convenience API.

Definition at line 243 of file output.h.

operator bool ( ) const
inlineexplicit

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

Definition at line 395 of file output.h.

operator const UsdProperty & ( ) const
inline

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

Definition at line 235 of file output.h.

operator UsdAttribute ( ) const
inline

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

Definition at line 230 of file output.h.

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

Set a value for the output.

It's unusual to be setting a value on an output since it represents an externally computed value. The Set API is provided here just for the sake of completeness and uniformity with other property schema.

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 the attribute value of the Output at time.

Definition at line 105 of file output.h.

USDSHADE_API bool SetRenderType ( TfToken const &  renderType) const

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

For example, we set the renderType to "struct" for outputs 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 Output 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 Output's "sdrMetadata" dictionary at the current EditTarget.

Friends And Related Function Documentation

bool operator== ( const UsdShadeOutput lhs,
const UsdShadeOutput rhs 
)
friend

Equality comparison.

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

Definition at line 401 of file output.h.


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