usdrt::UsdShadeShader

Defined in usdrt/scenegraph/usd/usdShade/shader.h

class UsdShadeShader : public usdrt::UsdTyped 

Base class for all USD shaders. Shaders are the building blocks of shading networks. While UsdShadeShader objects are not target specific, each renderer or application target may derive its own renderer-specific shader object types from this base, if needed.

Objects of this class generally represent a single shading object, whether it exists in the target renderer or not. For example, a texture, a fractal, or a mix node.

The UsdShadeNodeDefAPI provides attributes to uniquely identify the type of this node. The id resolution into a renderable shader target type of this node. The id resolution into a renderable shader target is deferred to the consuming application.

The purpose of representing them in Usd is two-fold:

To represent, via “connections” the topology of the shading network that must be reconstructed in the renderer. Facilities for authoring and manipulating connections are encapsulated in the API schema UsdShadeConnectableAPI.
To present a (partial or full) interface of typed input parameters whose values can be set and overridden in Usd, to be provided later at render-time as parameter values to the actual render shader objects. Shader input parameters are encapsulated in the property schema UsdShadeInput.

Conversion to and from UsdShadeConnectableAPI

inline UsdShadeShader(const UsdShadeConnectableAPI &connectable): Constructor that takes a ConnectableAPI object. Allow implicit (auto) conversion of UsdShadeConnectableAPI to UsdShadeShader, so that a ConnectableAPI can be passed into any function that accepts a Shader.

Note

that the conversion may produce an invalid Shader object, because not all UsdShadeConnectableAPIs are Shaders

inline UsdShadeConnectableAPI ConnectableAPI() const

Contructs and returns a UsdShadeConnectableAPI object with this shader.

Note that most tasks can be accomplished without explicitly constructing a UsdShadeConnectable API, since connection-related API such as UsdShadeConnectableAPI::ConnectToSource() are static methods, and UsdShadeShader will auto-convert to a UsdShadeConnectableAPI when passed to functions that want to act generically on a connectable UsdShadeConnectableAPI object.

Outputs API

Outputs represent a typed attribute on a shader or node-graph whose value is computed externally.

When they exist on a node-graph, they are connectable and are typically connected to the output of a shader within the node-graph.

inline UsdShadeOutput CreateOutput(const TfToken &name, const SdfValueTypeName &typeName): Create an output which can either have a value or can be connected. The attribute representing the output is created in the “outputs:” namespace. Outputs on a shader cannot be connected, as their value is assumed to be computed externally.

inline UsdShadeOutput GetOutput(const TfToken &name) const: Return the requested output if it exists.

inline std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored = true) const: Outputs are represented by attributes in the “outputs:” namespace. If onlyAuthored is true (the default), then only return authored attributes; otherwise, this also returns un-authored builtins.

Inputs API

Inputs are connectable attribute with a typed value.

On shaders, the shader parameters are encoded as inputs. On node-graphs, interface attributes are represented as inputs.

inline UsdShadeInput CreateInput(const TfToken &name, const SdfValueTypeName &typeName): Create an input which can either have a value or can be connected. The attribute representing the input is created in the “inputs:” namespace. Inputs on both shaders and node-graphs are connectable.

inline UsdShadeInput GetInput(const TfToken &name) const: Return the requested input if it exists.

inline std::vector<UsdShadeInput> GetInputs(bool onlyAuthored = true) const: 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.

UsdShadeNodeDefAPI forwarding

inline UsdAttribute GetImplementationSourceAttr() const: Forwards to UsdShadeNodeDefAPI(prim).

inline UsdAttribute CreateImplementationSourceAttr() const: Forwards to UsdShadeNodeDefAPI(prim).

inline UsdAttribute GetIdAttr() const: Forwards to UsdShadeNodeDefAPI(prim).

inline UsdAttribute CreateIdAttr() const: Forwards to UsdShadeNodeDefAPI(prim).

inline TfToken GetImplementationSource() const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool SetShaderId(const TfToken &id) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool GetShaderId(TfToken *id) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool SetSourceAsset(const SdfAssetPath &sourceAsset, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool GetSourceAsset(SdfAssetPath *sourceAsset, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool SetSourceAssetSubIdentifier(const TfToken &subIdentifier, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool GetSourceAssetSubIdentifier(TfToken *subIdentifier, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool SetSourceCode(const std::string &sourceCode, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

inline bool GetSourceCode(std::string *sourceCode, const TfToken &sourceType = UsdShadeTokens->universalSourceType) const: Forwards to UsdShadeNodeDefAPI(prim).

Public Functions

inline explicit UsdShadeShader(const UsdPrim &prim = UsdPrim()): Construct a UsdShadeShader on UsdPrim prim. Equivalent to UsdShadeShader::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdShadeShader(const UsdSchemaBase &schemaObj): Construct a UsdShadeShader on the prim held by schemaObj . Should be preferred over UsdShadeShader(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdShadeShader(): Destructor.

UsdPrim GetPrim() const: Return this schema object’s held prim.

SdfPath GetPath() const: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.