This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
input.h
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_USD_USD_SHADE_INPUT_H
8#define PXR_USD_USD_SHADE_INPUT_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/usdShade/api.h"
12#include "pxr/usd/usdShade/types.h"
13#include "pxr/usd/usdShade/utils.h"
14#include "pxr/usd/usd/attribute.h"
15
16#include "pxr/usd/ndr/declare.h"
17
18#include <vector>
19
20PXR_NAMESPACE_OPEN_SCOPE
21
24class UsdShadeOutput;
25
32{
33public:
37 {
38 // nothing
39 }
40
43 TfToken const &GetFullName() const {
44 return _attr.GetName();
45 }
46
52 USDSHADE_API
54
58 USDSHADE_API
60
62 UsdPrim GetPrim() const {
63 return _attr.GetPrim();
64 }
65
67 template <typename T>
68 bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
69 return GetAttr().Get(value, time);
70 }
71
73 USDSHADE_API
74 bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
75
78 USDSHADE_API
79 bool Set(const VtValue& value,
80 UsdTimeCode time = UsdTimeCode::Default()) const;
81
85 template <typename T>
86 bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
87 return _attr.Set(value, time);
88 }
89
91 struct Hash {
92 inline size_t operator()(const UsdShadeInput &input) const {
93 return hash_value(input._attr);
94 }
95 };
96
99
109 USDSHADE_API
110 bool SetRenderType(TfToken const& renderType) const;
111
116 USDSHADE_API
118
122 USDSHADE_API
123 bool HasRenderType() const;
124
126
141
144 USDSHADE_API
145 NdrTokenMap GetSdrMetadata() const;
146
149 USDSHADE_API
150 std::string GetSdrMetadataByKey(const TfToken &key) const;
151
154 USDSHADE_API
155 void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
156
159 USDSHADE_API
161 const TfToken &key,
162 const std::string &value) const;
163
166 USDSHADE_API
167 bool HasSdrMetadata() const;
168
171 USDSHADE_API
172 bool HasSdrMetadataByKey(const TfToken &key) const;
173
176 USDSHADE_API
177 void ClearSdrMetadata() const;
178
181 USDSHADE_API
182 void ClearSdrMetadataByKey(const TfToken &key) const;
183
185
186 // ---------------------------------------------------------------
188 // ---------------------------------------------------------------
189
191
196 USDSHADE_API
197 explicit UsdShadeInput(const UsdAttribute &attr);
198
203 USDSHADE_API
204 static bool IsInput(const UsdAttribute &attr);
205
208 USDSHADE_API
209 static bool IsInterfaceInputName(const std::string & name);
210
212 const UsdAttribute &GetAttr() const { return _attr; }
213
217 operator const UsdAttribute & () const { return GetAttr(); }
218
221 bool IsDefined() const {
222 return _attr && IsInput(_attr);
223 }
224
227 USDSHADE_API
228 bool SetDocumentation(const std::string& docs) const;
229
232 USDSHADE_API
233 std::string GetDocumentation() const;
234
242 USDSHADE_API
243 bool SetDisplayGroup(const std::string& displayGroup) const;
244
248 USDSHADE_API
249 std::string GetDisplayGroup() const;
250
252
255 explicit operator bool() const {
256 return IsDefined();
257 }
258
261 friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
262 return lhs.GetAttr() == rhs.GetAttr();
263 }
264
267 friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
268 return !(lhs == rhs);
269 }
270
271 // -------------------------------------------------------------------------
273 // -------------------------------------------------------------------------
275
280 USDSHADE_API
281 bool CanConnect(const UsdAttribute &source) const;
282
284 USDSHADE_API
285 bool CanConnect(const UsdShadeInput &sourceInput) const;
286
288 USDSHADE_API
289 bool CanConnect(const UsdShadeOutput &sourceOutput) const;
290
291 using ConnectionModification = UsdShadeConnectionModification;
292
315 USDSHADE_API
317 UsdShadeConnectionSourceInfo const &source,
318 ConnectionModification const mod =
319 ConnectionModification::Replace) const;
320
323 USDSHADE_API
325 UsdShadeConnectableAPI const &source,
326 TfToken const &sourceName,
327 UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output,
328 SdfValueTypeName typeName=SdfValueTypeName()) const;
329
334 USDSHADE_API
335 bool ConnectToSource(SdfPath const &sourcePath) const;
336
341 USDSHADE_API
342 bool ConnectToSource(UsdShadeInput const &sourceInput) const;
343
348 USDSHADE_API
349 bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
350
355 USDSHADE_API
357 std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
358
360
378 USDSHADE_API
380 SdfPathVector *invalidSourcePaths = nullptr) const;
381
383 USDSHADE_API
385 TfToken *sourceName,
386 UsdShadeAttributeType *sourceType) const;
387
393 USDSHADE_API
394 bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
395
401 USDSHADE_API
402 bool HasConnectedSource() const;
403
410 USDSHADE_API
412
419 USDSHADE_API
420 bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
421
429 USDSHADE_API
430 bool ClearSources() const;
431
433 USDSHADE_API
434 bool ClearSource() const;
435
437
438 // -------------------------------------------------------------------------
440 // -------------------------------------------------------------------------
442
464 USDSHADE_API
465 bool SetConnectability(const TfToken &connectability) const;
466
470 USDSHADE_API
472
475 USDSHADE_API
477
479
480 // -------------------------------------------------------------------------
482 // -------------------------------------------------------------------------
484
488 USDSHADE_API
490 bool shaderOutputsOnly = false) const;
491
493 USDSHADE_API
495 UsdShadeAttributeType* attrType) const;
496
498
499private:
500 friend class UsdShadeConnectableAPI;
501
502 // Constructor that creates a UsdShadeInput with the given name on the
503 // given prim.
504 // \p name here is the unnamespaced name of the input.
506 TfToken const &name,
507 SdfValueTypeName const &typeName);
508
509 UsdAttribute _attr;
510};
511
512PXR_NAMESPACE_CLOSE_SCOPE
513
514#endif // PXR_USD_USD_SHADE_INPUT_H
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Represents a value type name, i.e.
Definition: valueTypeName.h:71
This is a small-vector class with local storage optimization, the local storage can be specified via ...
Definition: smallVector.h:157
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time,...
Definition: attribute.h:461
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time,...
Definition: attribute.h:420
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object's nearest owning prim.
Definition: prim.h:2787
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:221
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and mak...
This class encapsulates a shader or node-graph input, which is a connectable attribute representing a...
Definition: input.h:32
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 o...
USDSHADE_API std::string GetDisplayGroup() const
Get the displayGroup metadata for this Input, i.e.
USDSHADE_API bool ConnectToSource(SdfPath const &sourcePath) const
Authors a connection for this Input to the source at the given path.
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
Returns the value corresponding to key in the composed sdrMetadata dictionary.
USDSHADE_API UsdShadeAttributeVector GetValueProducingAttributes(bool shaderOutputsOnly=false) const
Find what is connected to this Input recursively.
USDSHADE_API bool SetConnectability(const TfToken &connectability) const
Set the connectability of the Input.
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set a value for the Input at time.
USDSHADE_API bool HasRenderType() const
Return true if a renderType has been specified for this Input.
USDSHADE_API bool Get(VtValue *value, UsdTimeCode time=UsdTimeCode::Default()) const
Convenience wrapper for VtValue version of UsdAttribute::Get().
USDSHADE_API bool CanConnect(const UsdShadeOutput &sourceOutput) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
USDSHADE_API TfToken GetRenderType() const
Return this Input's specialized renderType, or an empty token if none was authored.
USDSHADE_API bool HasConnectedSource() const
Returns true if and only if this Input is currently connected to a valid (defined) source.
UsdPrim GetPrim() const
Get the prim that the input belongs to.
Definition: input.h:62
USDSHADE_API bool ConnectToSource(UsdShadeOutput const &sourceOutput) const
Connects this Input to the given output, sourceOutput.
USDSHADE_API bool ClearConnectability() const
Clears any authored connectability on the Input.
USDSHADE_API bool ConnectToSource(UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
Authors a connection for this Input.
USDSHADE_API UsdShadeInput(const UsdAttribute &attr)
Speculative constructor that will produce a valid UsdShadeInput when attr already represents a shade ...
TfToken const & GetFullName() const
Get the name of the attribute associated with the Input.
Definition: input.h:43
USDSHADE_API TfToken GetBaseName() const
Returns the name of the input.
USDSHADE_API bool ConnectToSource(UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
const UsdAttribute & GetAttr() const
Explicit UsdAttribute extractor.
Definition: input.h:212
USDSHADE_API NdrTokenMap GetSdrMetadata() const
Returns this Input's composed "sdrMetadata" dictionary as a NdrTokenMap.
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 o...
Definition: input.h:86
bool IsDefined() const
Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an...
Definition: input.h:221
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const
Finds the valid sources of connections for the Input.
USDSHADE_API UsdAttribute GetValueProducingAttribute(UsdShadeAttributeType *attrType) const
USDSHADE_API bool SetConnectedSources(std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
Connects this Input to the given sources, sourceInfos.
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Convenience wrapper for the templated UsdAttribute::Get().
Definition: input.h:68
static USDSHADE_API bool IsInterfaceInputName(const std::string &name)
Test if this name has a namespace that indicates it could be an input.
USDSHADE_API std::string GetDocumentation() const
Get documentation string for this Input.
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
Authors the given sdrMetadata value on this Input at the current EditTarget.
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
Returns true if the connection to this Input's source, as returned by GetConnectedSource(),...
USDSHADE_API void ClearSdrMetadata() const
Clears any "sdrMetadata" value authored on the Input in the current EditTarget.
USDSHADE_API bool SetDocumentation(const std::string &docs) const
Set documentation string for this Input.
USDSHADE_API bool CanConnect(const UsdShadeInput &sourceInput) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
USDSHADE_API bool HasSdrMetadata() const
Returns true if the Input has a non-empty composed "sdrMetadata" dictionary value.
USDSHADE_API SdfValueTypeName GetTypeName() const
Get the "scene description" value type name of the attribute associated with the Input.
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
Specify an alternative, renderer-specific type to use when emitting/translating this Input,...
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
Returns true if there is a value corresponding to the given key in the composed "sdrMetadata" diction...
UsdShadeInput()
Default constructor returns an invalid Input.
Definition: input.h:36
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" dictionar...
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
Clears the entry corresponding to the given key in the "sdrMetadata" dictionary authored in the curre...
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
static USDSHADE_API bool IsInput(const UsdAttribute &attr)
Test whether a given UsdAttribute represents a valid Input, which implies that creating a UsdShadeInp...
USDSHADE_API bool DisconnectSource(UsdAttribute const &sourceAttr=UsdAttribute()) const
Disconnect source for this Input.
USDSHADE_API bool ClearSource() const
USDSHADE_API bool ClearSources() const
Clears sources for this Input in the current UsdEditTarget.
USDSHADE_API bool ConnectToSource(UsdShadeInput const &sourceInput) const
Connects this Input to the given input, sourceInput.
friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Equality comparison.
Definition: input.h:261
USDSHADE_API bool SetDisplayGroup(const std::string &displayGroup) const
Set the displayGroup metadata for this Input, i.e.
USDSHADE_API TfToken GetConnectability() const
Returns the connectability of the Input.
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Inequality comparison.
Definition: input.h:267
This class encapsulates a shader or node-graph output, which is a connectable attribute representing ...
Definition: output.h:31
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:67
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:95
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:147
A compact struct to represent a bundle of information about an upstream source attribute.
Hash functor.
Definition: input.h:91
size_t hash_value(const TfToken &x)
Overload hash_value for TfToken.
Definition: token.h:437
Common typedefs that are used throughout the NDR library.