HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
input.h
Go to the documentation of this file.
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/usd/attribute.h"
30 
31 #include "pxr/usd/ndr/declare.h"
32 #include "pxr/usd/usdShade/utils.h"
33 
34 #include <vector>
35 
37 
39 class UsdShadeOutput;
40 
41 /// \class UsdShadeInput
42 ///
43 /// This class encapsulates a shader or node-graph input, which is a
44 /// connectable attribute representing a typed value.
45 ///
47 {
48 public:
49  /// Default constructor returns an invalid Input. Exists for the sake of
50  /// container classes
52  {
53  // nothing
54  }
55 
56  /// Get the name of the attribute associated with the Input.
57  ///
58  TfToken const &GetFullName() const {
59  return _attr.GetName();
60  }
61 
62  /// Returns the name of the input.
63  ///
64  /// We call this the base name since it strips off the "inputs:" namespace
65  /// prefix from the attribute name, and returns it.
66  ///
68  TfToken GetBaseName() const;
69 
70  /// Get the "scene description" value type name of the attribute associated
71  /// with the Input.
72  ///
75 
76  /// Get the prim that the input belongs to.
77  UsdPrim GetPrim() const {
78  return _attr.GetPrim();
79  }
80 
81  /// Convenience wrapper for the templated UsdAttribute::Get().
82  template <typename T>
84  return GetAttr().Get(value, time);
85  }
86 
87  /// Convenience wrapper for VtValue version of UsdAttribute::Get().
89  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
90 
91  /// Set a value for the Input at \p time.
92  ///
94  bool Set(const VtValue& value,
96 
97  /// \overload
98  /// Set a value of the Input at \p time.
99  ///
100  template <typename T>
101  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
102  return _attr.Set(value, time);
103  }
104 
105  /// Hash functor.
106  struct Hash {
107  inline size_t operator()(const UsdShadeInput &input) const {
108  return hash_value(input._attr);
109  }
110  };
111 
112  /// \name Configuring the Input's Type
113  /// @{
114 
115  /// Specify an alternative, renderer-specific type to use when
116  /// emitting/translating this Input, rather than translating based
117  /// on its GetTypeName()
118  ///
119  /// For example, we set the renderType to "struct" for Inputs that
120  /// are of renderman custom struct types.
121  ///
122  /// \return true on success.
123  ///
125  bool SetRenderType(TfToken const& renderType) const;
126 
127  /// Return this Input's specialized renderType, or an empty
128  /// token if none was authored.
129  ///
130  /// \sa SetRenderType()
132  TfToken GetRenderType() const;
133 
134  /// Return true if a renderType has been specified for this Input.
135  ///
136  /// \sa SetRenderType()
138  bool HasRenderType() const;
139 
140  /// @}
141 
142  /// \name API to author and query an Input's sdrMetadata
143  ///
144  /// This section provides API for authoring and querying shader registry
145  /// metadata on an Input. When the owning shader prim is providing a shader
146  /// definition, the authored "sdrMetadata" dictionary value provides
147  /// metadata needed to populate the Input correctly in the shader registry.
148  ///
149  /// We expect the keys in sdrMetadata to correspond to the keys
150  /// in \ref SdrPropertyMetadata. However, this is not strictly enforced by
151  /// the API. The only allowed value type in the "sdrMetadata" dictionary is
152  /// a std::string since it needs to be converted into a NdrTokenMap, which
153  /// Sdr will parse using the utilities available in \ref SdrMetadataHelpers.
154  ///
155  /// @{
156 
157  /// Returns this Input's composed "sdrMetadata" dictionary as a
158  /// NdrTokenMap.
160  NdrTokenMap GetSdrMetadata() const;
161 
162  /// Returns the value corresponding to \p key in the composed
163  /// <b>sdrMetadata</b> dictionary.
165  std::string GetSdrMetadataByKey(const TfToken &key) const;
166 
167  /// Authors the given \p sdrMetadata value on this Input at the current
168  /// EditTarget.
170  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
171 
172  /// Sets the value corresponding to \p key to the given string \p value, in
173  /// the Input's "sdrMetadata" dictionary at the current EditTarget.
175  void SetSdrMetadataByKey(
176  const TfToken &key,
177  const std::string &value) const;
178 
179  /// Returns true if the Input has a non-empty composed "sdrMetadata"
180  /// dictionary value.
182  bool HasSdrMetadata() const;
183 
184  /// Returns true if there is a value corresponding to the given \p key in
185  /// the composed "sdrMetadata" dictionary.
187  bool HasSdrMetadataByKey(const TfToken &key) const;
188 
189  /// Clears any "sdrMetadata" value authored on the Input in the current
190  /// EditTarget.
192  void ClearSdrMetadata() const;
193 
194  /// Clears the entry corresponding to the given \p key in the
195  /// "sdrMetadata" dictionary authored in the current EditTarget.
197  void ClearSdrMetadataByKey(const TfToken &key) const;
198 
199  /// @}
200 
201  // ---------------------------------------------------------------
202  /// \name UsdAttribute API
203  // ---------------------------------------------------------------
204 
205  /// @{
206 
207  /// Speculative constructor that will produce a valid UsdShadeInput when
208  /// \p attr already represents a shade Input, and produces an \em invalid
209  /// UsdShadeInput otherwise (i.e. the explicit bool conversion operator will
210  /// return false).
212  explicit UsdShadeInput(const UsdAttribute &attr);
213 
214  /// Test whether a given UsdAttribute represents a valid Input, which
215  /// implies that creating a UsdShadeInput from the attribute will succeed.
216  ///
217  /// Success implies that \c attr.IsDefined() is true.
219  static bool IsInput(const UsdAttribute &attr);
220 
221  /// Test if this name has a namespace that indicates it could be an
222  /// input.
224  static bool IsInterfaceInputName(const std::string & name);
225 
226  /// Explicit UsdAttribute extractor.
227  const UsdAttribute &GetAttr() const { return _attr; }
228 
229  /// Allow UsdShadeInput to auto-convert to UsdAttribute, so you can
230  /// pass a UsdShadeInput to any function that accepts a UsdAttribute or
231  /// const-ref thereto.
232  operator const UsdAttribute & () const { return GetAttr(); }
233 
234  /// Return true if the wrapped UsdAttribute is defined, and in addition the
235  /// attribute is identified as an input.
236  bool IsDefined() const {
237  return _attr && IsInput(_attr);
238  }
239 
240  /// Set documentation string for this Input.
241  /// \sa UsdObject::SetDocumentation()
243  bool SetDocumentation(const std::string& docs) const;
244 
245  /// Get documentation string for this Input.
246  /// \sa UsdObject::GetDocumentation()
249 
250  /// Set the displayGroup metadata for this Input, i.e. hinting for the
251  /// location and nesting of the attribute.
252  /// \sa UsdProperty::SetDisplayGroup(), UsdProperty::SetNestedDisplayGroup()
254  bool SetDisplayGroup(const std::string& displayGroup) const;
255 
256  /// Get the displayGroup metadata for this Input, i.e. hint for the location
257  /// and nesting of the attribute.
258  /// \sa UsdProperty::GetDisplayGroup(), UsdProperty::GetNestedDisplayGroup()
261 
262  /// @}
263 
264  /// Return true if this Input is valid for querying and authoring
265  /// values and metadata, which is identically equivalent to IsDefined().
266  explicit operator bool() const {
267  return IsDefined();
268  }
269 
270  /// Equality comparison. Returns true if \a lhs and \a rhs represent the
271  /// same UsdShadeInput, false otherwise.
272  friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
273  return lhs.GetAttr() == rhs.GetAttr();
274  }
275 
276  // -------------------------------------------------------------------------
277  /// \name Connections API
278  // -------------------------------------------------------------------------
279  /// @{
280 
281  /// Determines whether this Input can be connected to the given
282  /// source attribute, which can be an input or an output.
283  ///
284  /// \sa UsdShadeConnectableAPI::CanConnect
286  bool CanConnect(const UsdAttribute &source) const;
287 
288  /// \overload
290  bool CanConnect(const UsdShadeInput &sourceInput) const;
291 
292  /// \overload
294  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
295 
296  /// Authors a connection for this Input to the source described by the
297  /// following three elements:
298  /// \p source, the connectable owning the source,
299  /// \p sourceName, the name of the source and
300  /// \p sourceType, the value type of the source shading attribute.
301  ///
302  /// \p typeName if specified, is the typename of the attribute to create
303  /// on the source if it doesn't exist. It is also used to validate whether
304  /// the types of the source and consumer of the connection are compatible.
305  ///
306  /// \sa UsdShadeConnectableAPI::ConnectToSource
307  ///
309  bool ConnectToSource(
311  TfToken const &sourceName,
313  SdfValueTypeName typeName=SdfValueTypeName()) const;
314 
315  /// Authors a connection for this Input to the source at the given path.
316  ///
317  /// \sa UsdShadeConnectableAPI::ConnectToSource
318  ///
320  bool ConnectToSource(SdfPath const &sourcePath) const;
321 
322  /// Connects this Input to the given input, \p sourceInput.
323  ///
324  /// \sa UsdShadeConnectableAPI::ConnectToSource
325  ///
327  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
328 
329  /// Connects this Input to the given output, \p sourceOutput.
330  ///
331  /// \sa UsdShadeConnectableAPI::ConnectToSource
332  ///
334  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
335 
336  /// Finds the source of a connection for this Input.
337  ///
338  /// \p source is an output parameter which will be set to the source
339  /// connectable prim.
340  /// \p sourceName will be set to the name of the source shading attribute,
341  /// which may be an input or an output, as specified by \p sourceType
342  /// \p sourceType will have the type of the source shading attribute, i.e.
343  /// whether it is an \c Input or \c Output
344  ///
345  /// \return
346  /// \c true if the shading attribute is connected to a valid, defined source
347  /// attribute.
348  /// \c false if the shading attribute is not connected to a single, defined
349  /// source attribute.
350  ///
351  /// \note The python wrapping for this method returns a
352  /// (source, sourceName, sourceType) tuple if the parameter is connected,
353  /// else \c None
354  ///
355  /// \sa UsdShadeConnectableAPI::GetConnectedSource
356  ///
359  TfToken *sourceName,
360  UsdShadeAttributeType *sourceType) const;
361 
362  /// Returns the "raw" (authored) connected source paths for this Input.
363  ///
364  /// \sa UsdShadeConnectableAPI::GetRawConnectedSourcePaths
365  ///
367  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
368 
369  /// Returns true if and only if this Input is currently connected to a
370  /// valid (defined) source.
371  ///
372  /// \sa UsdShadeConnectableAPI::HasConnectedSource
373  ///
375  bool HasConnectedSource() const;
376 
377  /// Returns true if the connection to this Input's source, as returned by
378  /// GetConnectedSource(), is authored across a specializes arc, which is
379  /// used to denote a base material.
380  ///
381  /// \sa UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
382  ///
385 
386  /// Disconnect source for this Input.
387  ///
388  /// \sa UsdShadeConnectableAPI::DisconnectSource
389  ///
391  bool DisconnectSource() const;
392 
393  /// Clears source for this shading attribute in the current UsdEditTarget.
394  ///
395  /// Most of the time, what you probably want is DisconnectSource()
396  /// rather than this function.
397  ///
398  /// \sa UsdShadeConnectableAPI::ClearSource
399  ///
401  bool ClearSource() const;
402 
403  /// @}
404 
405  // -------------------------------------------------------------------------
406  /// \name Connectability API
407  // -------------------------------------------------------------------------
408  /// @{
409 
410  /// \brief Set the connectability of the Input.
411  ///
412  /// In certain shading data models, there is a need to distinguish which
413  /// inputs <b>can</b> vary over a surface from those that must be
414  /// <b>uniform</b>. This is accomplished in UsdShade by limiting the
415  /// connectability of the input. This is done by setting the
416  /// "connectability" metadata on the associated attribute.
417  ///
418  /// Connectability of an Input can be set to UsdShadeTokens->full or
419  /// UsdShadeTokens->interfaceOnly.
420  ///
421  /// \li <b>full</b> implies that the Input can be connected to any other
422  /// Input or Output.
423  /// \li <b>interfaceOnly</b> implies that the Input can only be connected to
424  /// a NodeGraph Input (which represents an interface override, not a
425  /// render-time dataflow connection), or another Input whose connectability
426  /// is also "interfaceOnly".
427  ///
428  /// The default connectability of an input is UsdShadeTokens->full.
429  ///
430  /// \sa SetConnectability()
432  bool SetConnectability(const TfToken &connectability) const;
433 
434  /// \brief Returns the connectability of the Input.
435  ///
436  /// \sa SetConnectability()
438  TfToken GetConnectability() const;
439 
440  /// \brief Clears any authored connectability on the Input.
441  ///
443  bool ClearConnectability() const;
444 
445  /// @}
446 
447  // -------------------------------------------------------------------------
448  /// \name Connected Value API
449  // -------------------------------------------------------------------------
450  /// @{
451 
452  /// \brief Find what is connected to an Input recursively
453  ///
454  /// When tracing connections within networks that contain UsdShadeNodeGraph
455  /// nodes, the actual output or value at the end of an input might be
456  /// multiple connections removed. The method below resolves this across
457  /// multiple physical connections.
458  ///
459  /// An UsdInput is getting its value from one of these sources:
460  /// \li If the input is not connected the UsdAttribute for this input is
461  /// returned, but only if it has an authored value. The input attribute
462  /// itself carries the value for this input.
463  /// \li If the input is connected we follow the connection(s) until we reach
464  /// a valid output of a UsdShadeShader node or if we reach a valid
465  /// UsdShadeInput attribute of a UsdShadeNodeGraph or UsdShadeMaterial.
466  /// Note that we return the last attribute along the connection chain that
467  /// has an authored value, which might not be the last attribute in the
468  /// chain itself.
469  ///
470  /// This function returns a valid UsdAttribute if a valid output was
471  /// encountered or an input with an authored value. Otherwise an invalid
472  /// UsdAttribute is returned. If a valid \p attrType pointer is provided,
473  /// the method also returns what type of attribute it found, which is
474  /// <b>Invalid</b>, <b>Input</b> or <b>Output</b>.
477  UsdShadeAttributeType* attrType) const;
478 
479  /// @}
480 
481 private:
483 
484  // Constructor that creates a UsdShadeInput with the given name on the
485  // given prim.
486  // \p name here is the unnamespaced name of the input.
487  UsdShadeInput(UsdPrim prim,
488  TfToken const &name,
489  SdfValueTypeName const &typeName);
490 
491  UsdAttribute _attr;
492 };
493 
495 
496 #endif // PXR_USD_USD_SHADE_INPUT_H
bool IsDefined() const
Definition: input.h:236
#define USDSHADE_API
Definition: api.h:40
Hash functor.
Definition: input.h:106
GLenum GLenum GLenum input
Definition: glew.h:13879
USDSHADE_API std::string GetDisplayGroup() const
USDSHADE_API void ClearSdrMetadata() const
USDSHADE_API void SetSdrMetadataByKey(const TfToken &key, const std::string &value) const
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
GLuint const GLchar * name
Definition: glew.h:1814
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:431
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
static USDSHADE_API bool IsInput(const UsdAttribute &attr)
USDSHADE_API bool CanConnect(const UsdAttribute &source) const
GT_API const UT_StringHolder time
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
USDSHADE_API bool ConnectToSource(UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
USDSHADE_API bool DisconnectSource() const
USDSHADE_API bool ClearSource() const
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
GLsizei GLsizei GLchar * source
Definition: glew.h:1832
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
static USDSHADE_API bool IsInterfaceInputName(const std::string &name)
Definition: token.h:87
friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Definition: input.h:272
USDSHADE_API bool HasRenderType() const
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Convenience wrapper for the templated UsdAttribute::Get().
Definition: input.h:83
UsdPrim GetPrim() const
Get the prim that the input belongs to.
Definition: input.h:77
USDSHADE_API bool HasSdrMetadata() const
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: input.h:101
TfToken const & GetFullName() const
Definition: input.h:58
Definition: prim.h:132
USDSHADE_API TfToken GetBaseName() const
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:462
Definition: path.h:288
USDSHADE_API bool ClearConnectability() const
Clears any authored connectability on the Input.
USDSHADE_API bool HasConnectedSource() const
const TfToken & GetName() const
Definition: object.h:229
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
USDSHADE_API TfToken GetConnectability() const
Returns the connectability of the Input.
UsdShadeInput()
Definition: input.h:51
UsdShadeAttributeType
Definition: utils.h:42
UsdPrim GetPrim() const
Definition: prim.h:1959
USDSHADE_API TfToken GetRenderType() const
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
size_t operator()(const UsdShadeInput &input) const
Definition: input.h:107
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
USDSHADE_API SdfValueTypeName GetTypeName() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
const UsdAttribute & GetAttr() const
Explicit UsdAttribute extractor.
Definition: input.h:227
USDSHADE_API std::string GetDocumentation() const
USDSHADE_API bool SetDisplayGroup(const std::string &displayGroup) const
USDSHADE_API UsdAttribute GetValueProducingAttribute(UsdShadeAttributeType *attrType) const
Find what is connected to an Input recursively.
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
USDSHADE_API NdrTokenMap GetSdrMetadata() const
size_t hash_value(const CH_ChannelRef &ref)
GLsizei const GLfloat * value
Definition: glew.h:1849
USDSHADE_API bool SetConnectability(const TfToken &connectability) const
Set the connectability of the Input.
Definition: value.h:174
USDSHADE_API bool SetDocumentation(const std::string &docs) const