input.h
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_SHADE_INPUT_H
25 #define PXR_USD_USD_SHADE_INPUT_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usdShade/api.h"
29 #include "pxr/usd/usdShade/types.h"
30 #include "pxr/usd/usdShade/utils.h"
31 #include "pxr/usd/usd/attribute.h"
32 
33 #include "pxr/usd/ndr/declare.h"
34 
35 #include <vector>
36 
37 PXR_NAMESPACE_OPEN_SCOPE
38 
41 class UsdShadeOutput;
42 
49 {
50 public:
54  {
55  // nothing
56  }
57 
60  TfToken const &GetFullName() const {
61  return _attr.GetName();
62  }
63 
69  USDSHADE_API
70  TfToken GetBaseName() const;
71 
75  USDSHADE_API
77 
79  UsdPrim GetPrim() const {
80  return _attr.GetPrim();
81  }
82 
84  template <typename T>
85  bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
86  return GetAttr().Get(value, time);
87  }
88 
90  USDSHADE_API
91  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
92 
95  USDSHADE_API
96  bool Set(const VtValue& value,
97  UsdTimeCode time = UsdTimeCode::Default()) const;
98 
102  template <typename T>
103  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
104  return _attr.Set(value, time);
105  }
106 
108  struct Hash {
109  inline size_t operator()(const UsdShadeInput &input) const {
110  return hash_value(input._attr);
111  }
112  };
113 
116 
126  USDSHADE_API
127  bool SetRenderType(TfToken const& renderType) const;
128 
133  USDSHADE_API
134  TfToken GetRenderType() const;
135 
139  USDSHADE_API
140  bool HasRenderType() const;
141 
143 
158 
161  USDSHADE_API
162  NdrTokenMap GetSdrMetadata() const;
163 
166  USDSHADE_API
167  std::string GetSdrMetadataByKey(const TfToken &key) const;
168 
171  USDSHADE_API
172  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
173 
176  USDSHADE_API
177  void SetSdrMetadataByKey(
178  const TfToken &key,
179  const std::string &value) const;
180 
183  USDSHADE_API
184  bool HasSdrMetadata() const;
185 
188  USDSHADE_API
189  bool HasSdrMetadataByKey(const TfToken &key) const;
190 
193  USDSHADE_API
194  void ClearSdrMetadata() const;
195 
198  USDSHADE_API
199  void ClearSdrMetadataByKey(const TfToken &key) const;
200 
202 
203  // ---------------------------------------------------------------
205  // ---------------------------------------------------------------
206 
208 
213  USDSHADE_API
214  explicit UsdShadeInput(const UsdAttribute &attr);
215 
220  USDSHADE_API
221  static bool IsInput(const UsdAttribute &attr);
222 
225  USDSHADE_API
226  static bool IsInterfaceInputName(const std::string & name);
227 
229  const UsdAttribute &GetAttr() const { return _attr; }
230 
234  operator const UsdAttribute & () const { return GetAttr(); }
235 
238  bool IsDefined() const {
239  return _attr && IsInput(_attr);
240  }
241 
244  USDSHADE_API
245  bool SetDocumentation(const std::string& docs) const;
246 
249  USDSHADE_API
250  std::string GetDocumentation() const;
251 
259  USDSHADE_API
260  bool SetDisplayGroup(const std::string& displayGroup) const;
261 
265  USDSHADE_API
266  std::string GetDisplayGroup() const;
267 
269 
272  explicit operator bool() const {
273  return IsDefined();
274  }
275 
278  friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
279  return lhs.GetAttr() == rhs.GetAttr();
280  }
281 
284  friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
285  return !(lhs == rhs);
286  }
287 
288  // -------------------------------------------------------------------------
290  // -------------------------------------------------------------------------
292 
297  USDSHADE_API
298  bool CanConnect(const UsdAttribute &source) const;
299 
301  USDSHADE_API
302  bool CanConnect(const UsdShadeInput &sourceInput) const;
303 
305  USDSHADE_API
306  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
307 
308  using ConnectionModification = UsdShadeConnectionModification;
309 
332  USDSHADE_API
333  bool ConnectToSource(
334  UsdShadeConnectionSourceInfo const &source,
335  ConnectionModification const mod =
336  ConnectionModification::Replace) const;
337 
340  USDSHADE_API
341  bool ConnectToSource(
342  UsdShadeConnectableAPI const &source,
343  TfToken const &sourceName,
344  UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output,
345  SdfValueTypeName typeName=SdfValueTypeName()) const;
346 
351  USDSHADE_API
352  bool ConnectToSource(SdfPath const &sourcePath) const;
353 
358  USDSHADE_API
359  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
360 
365  USDSHADE_API
366  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
367 
372  USDSHADE_API
373  bool SetConnectedSources(
374  std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
375 
376  using SourceInfoVector = TfSmallVector<UsdShadeConnectionSourceInfo, 1>;
377 
395  USDSHADE_API
396  SourceInfoVector GetConnectedSources(
397  SdfPathVector *invalidSourcePaths = nullptr) const;
398 
400  USDSHADE_API
402  TfToken *sourceName,
403  UsdShadeAttributeType *sourceType) const;
404 
410  USDSHADE_API
411  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
412 
418  USDSHADE_API
419  bool HasConnectedSource() const;
420 
427  USDSHADE_API
429 
436  USDSHADE_API
437  bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
438 
446  USDSHADE_API
447  bool ClearSources() const;
448 
450  USDSHADE_API
451  bool ClearSource() const;
452 
454 
455  // -------------------------------------------------------------------------
457  // -------------------------------------------------------------------------
459 
481  USDSHADE_API
482  bool SetConnectability(const TfToken &connectability) const;
483 
487  USDSHADE_API
488  TfToken GetConnectability() const;
489 
492  USDSHADE_API
493  bool ClearConnectability() const;
494 
496 
497  // -------------------------------------------------------------------------
499  // -------------------------------------------------------------------------
501 
505  USDSHADE_API
507  bool shaderOutputsOnly = false) const;
508 
510  USDSHADE_API
512  UsdShadeAttributeType* attrType) const;
513 
515 
516 private:
517  friend class UsdShadeConnectableAPI;
518 
519  // Constructor that creates a UsdShadeInput with the given name on the
520  // given prim.
521  // \p name here is the unnamespaced name of the input.
522  UsdShadeInput(UsdPrim prim,
523  TfToken const &name,
524  SdfValueTypeName const &typeName);
525 
526  UsdAttribute _attr;
527 };
528 
529 PXR_NAMESPACE_CLOSE_SCOPE
530 
531 #endif // PXR_USD_USD_SHADE_INPUT_H
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
Specify an alternative, renderer-specific type to use when emitting/translating this Input,...
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 bool ClearSource() const
Hash functor.
Definition: input.h:108
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:431
USDSHADE_API bool ClearSources() const
Clears sources for this Input in the current UsdEditTarget.
USDSHADE_API TfToken GetRenderType() const
Return this Input's specialized renderType, or an empty token if none was authored.
USDSHADE_API bool ClearConnectability() const
Clears any authored connectability on the Input.
This is a small-vector class with local storage optimization, the local storage can be specified via ...
Definition: smallVector.h:177
USDSHADE_API bool ConnectToSource(UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
Authors a connection for this Input.
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 bool HasSdrMetadata() const
Returns true if the Input has a non-empty composed "sdrMetadata" dictionary value.
USDSHADE_API bool DisconnectSource(UsdAttribute const &sourceAttr=UsdAttribute()) const
Disconnect source for this Input.
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
Represents a value type name, i.e.
Definition: valueTypeName.h:87
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
USDSHADE_API bool SetConnectability(const TfToken &connectability) const
Set the connectability of the Input.
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
USDSHADE_API UsdAttribute GetValueProducingAttribute(UsdShadeAttributeType *attrType) const
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Convenience wrapper for the templated UsdAttribute::Get().
Definition: input.h:85
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set a value for the Input at time.
USDSHADE_API bool SetConnectedSources(std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
Connects this Input to the given sources, sourceInfos.
This class encapsulates a shader or node-graph input, which is a connectable attribute representing a...
Definition: input.h:48
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...
USDSHADE_API SdfValueTypeName GetTypeName() const
Get the "scene description" value type name of the attribute associated with the Input.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const
Finds the valid sources of connections for the Input.
friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Equality comparison.
Definition: input.h:278
bool IsDefined() const
Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an...
Definition: input.h:238
friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Inequality comparison.
Definition: input.h:284
USDSHADE_API NdrTokenMap GetSdrMetadata() const
Returns this Input's composed "sdrMetadata" dictionary as a NdrTokenMap.
static USDSHADE_API bool IsInterfaceInputName(const std::string &name)
Test if this name has a namespace that indicates it could be an input.
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
USDSHADE_API TfToken GetConnectability() const
Returns the connectability of the Input.
UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and mak...
USDSHADE_API bool SetDisplayGroup(const std::string &displayGroup) const
Set the displayGroup metadata for this Input, i.e.
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 std::string GetSdrMetadataByKey(const TfToken &key) const
Returns the value corresponding to key in the composed sdrMetadata dictionary.
USDSHADE_API std::string GetDisplayGroup() const
Get the displayGroup metadata for this Input, i.e.
const UsdAttribute & GetAttr() const
Explicit UsdAttribute extractor.
Definition: input.h:229
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
USDSHADE_API bool SetDocumentation(const std::string &docs) const
Set documentation string for this Input.
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:472
UsdShadeInput()
Default constructor returns an invalid Input.
Definition: input.h:53
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
Returns true if the connection to this Input's source, as returned by GetConnectedSource(),...
USDSHADE_API TfToken GetBaseName() const
Returns the name of the input.
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 void ClearSdrMetadata() const
Clears any "sdrMetadata" value authored on the Input in the current EditTarget.
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:113
USDSHADE_API bool HasRenderType() const
Return true if a renderType has been specified for this Input.
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
Authors the given sdrMetadata value on this Input at the current EditTarget.
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:229
USDSHADE_API UsdShadeAttributeVector GetValueProducingAttributes(bool shaderOutputsOnly=false) const
Find what is connected to this Input recursively.
UsdPrim GetPrim() const
Get the prim that the input belongs to.
Definition: input.h:79
A compact struct to represent a bundle of information about an upstream source attribute.
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:103
This class encapsulates a shader or node-graph output, which is a connectable attribute representing ...
Definition: output.h:47
USDSHADE_API std::string GetDocumentation() const
Get documentation string for this Input.
TfToken const & GetFullName() const
Get the name of the attribute associated with the Input.
Definition: input.h:60
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object's nearest owning prim.
Definition: prim.h:2180
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
USDSHADE_API bool HasConnectedSource() const
Returns true if and only if this Input is currently connected to a valid (defined) source.