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/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 
38 
41 class UsdShadeOutput;
42 
43 /// \class UsdShadeInput
44 ///
45 /// This class encapsulates a shader or node-graph input, which is a
46 /// connectable attribute representing a typed value.
47 ///
49 {
50 public:
51  /// Default constructor returns an invalid Input. Exists for the sake of
52  /// container classes
54  {
55  // nothing
56  }
57 
58  /// Get the name of the attribute associated with the Input.
59  ///
60  TfToken const &GetFullName() const {
61  return _attr.GetName();
62  }
63 
64  /// Returns the name of the input.
65  ///
66  /// We call this the base name since it strips off the "inputs:" namespace
67  /// prefix from the attribute name, and returns it.
68  ///
70  TfToken GetBaseName() const;
71 
72  /// Get the "scene description" value type name of the attribute associated
73  /// with the Input.
74  ///
77 
78  /// Get the prim that the input belongs to.
79  UsdPrim GetPrim() const {
80  return _attr.GetPrim();
81  }
82 
83  /// Convenience wrapper for the templated UsdAttribute::Get().
84  template <typename T>
86  return GetAttr().Get(value, time);
87  }
88 
89  /// Convenience wrapper for VtValue version of UsdAttribute::Get().
91  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
92 
93  /// Set a value for the Input at \p time.
94  ///
96  bool Set(const VtValue& value,
98 
99  /// \overload
100  /// Set a value of the Input at \p time.
101  ///
102  template <typename T>
103  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
104  return _attr.Set(value, time);
105  }
106 
107  /// Hash functor.
108  struct Hash {
109  inline size_t operator()(const UsdShadeInput &input) const {
110  return hash_value(input._attr);
111  }
112  };
113 
114  /// \name Configuring the Input's Type
115  /// @{
116 
117  /// Specify an alternative, renderer-specific type to use when
118  /// emitting/translating this Input, rather than translating based
119  /// on its GetTypeName()
120  ///
121  /// For example, we set the renderType to "struct" for Inputs that
122  /// are of renderman custom struct types.
123  ///
124  /// \return true on success.
125  ///
127  bool SetRenderType(TfToken const& renderType) const;
128 
129  /// Return this Input's specialized renderType, or an empty
130  /// token if none was authored.
131  ///
132  /// \sa SetRenderType()
134  TfToken GetRenderType() const;
135 
136  /// Return true if a renderType has been specified for this Input.
137  ///
138  /// \sa SetRenderType()
140  bool HasRenderType() const;
141 
142  /// @}
143 
144  /// \name API to author and query an Input's sdrMetadata
145  ///
146  /// This section provides API for authoring and querying shader registry
147  /// metadata on an Input. When the owning shader prim is providing a shader
148  /// definition, the authored "sdrMetadata" dictionary value provides
149  /// metadata needed to populate the Input correctly in the shader registry.
150  ///
151  /// We expect the keys in sdrMetadata to correspond to the keys
152  /// in \ref SdrPropertyMetadata. However, this is not strictly enforced by
153  /// the API. The only allowed value type in the "sdrMetadata" dictionary is
154  /// a std::string since it needs to be converted into a NdrTokenMap, which
155  /// Sdr will parse using the utilities available in \ref SdrMetadataHelpers.
156  ///
157  /// @{
158 
159  /// Returns this Input's composed "sdrMetadata" dictionary as a
160  /// NdrTokenMap.
162  NdrTokenMap GetSdrMetadata() const;
163 
164  /// Returns the value corresponding to \p key in the composed
165  /// <b>sdrMetadata</b> dictionary.
167  std::string GetSdrMetadataByKey(const TfToken &key) const;
168 
169  /// Authors the given \p sdrMetadata value on this Input at the current
170  /// EditTarget.
172  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
173 
174  /// Sets the value corresponding to \p key to the given string \p value, in
175  /// the Input's "sdrMetadata" dictionary at the current EditTarget.
177  void SetSdrMetadataByKey(
178  const TfToken &key,
179  const std::string &value) const;
180 
181  /// Returns true if the Input has a non-empty composed "sdrMetadata"
182  /// dictionary value.
184  bool HasSdrMetadata() const;
185 
186  /// Returns true if there is a value corresponding to the given \p key in
187  /// the composed "sdrMetadata" dictionary.
189  bool HasSdrMetadataByKey(const TfToken &key) const;
190 
191  /// Clears any "sdrMetadata" value authored on the Input in the current
192  /// EditTarget.
194  void ClearSdrMetadata() const;
195 
196  /// Clears the entry corresponding to the given \p key in the
197  /// "sdrMetadata" dictionary authored in the current EditTarget.
199  void ClearSdrMetadataByKey(const TfToken &key) const;
200 
201  /// @}
202 
203  // ---------------------------------------------------------------
204  /// \name UsdAttribute API
205  // ---------------------------------------------------------------
206 
207  /// @{
208 
209  /// Speculative constructor that will produce a valid UsdShadeInput when
210  /// \p attr already represents a shade Input, and produces an \em invalid
211  /// UsdShadeInput otherwise (i.e. the explicit bool conversion operator will
212  /// return false).
214  explicit UsdShadeInput(const UsdAttribute &attr);
215 
216  /// Test whether a given UsdAttribute represents a valid Input, which
217  /// implies that creating a UsdShadeInput from the attribute will succeed.
218  ///
219  /// Success implies that \c attr.IsDefined() is true.
221  static bool IsInput(const UsdAttribute &attr);
222 
223  /// Test if this name has a namespace that indicates it could be an
224  /// input.
226  static bool IsInterfaceInputName(const std::string & name);
227 
228  /// Explicit UsdAttribute extractor.
229  const UsdAttribute &GetAttr() const { return _attr; }
230 
231  /// Allow UsdShadeInput to auto-convert to UsdAttribute, so you can
232  /// pass a UsdShadeInput to any function that accepts a UsdAttribute or
233  /// const-ref thereto.
234  operator const UsdAttribute & () const { return GetAttr(); }
235 
236  /// Return true if the wrapped UsdAttribute is defined, and in addition the
237  /// attribute is identified as an input.
238  bool IsDefined() const {
239  return _attr && IsInput(_attr);
240  }
241 
242  /// Set documentation string for this Input.
243  /// \sa UsdObject::SetDocumentation()
245  bool SetDocumentation(const std::string& docs) const;
246 
247  /// Get documentation string for this Input.
248  /// \sa UsdObject::GetDocumentation()
251 
252  /// Set the displayGroup metadata for this Input, i.e. hinting for the
253  /// location and nesting of the attribute.
254  /// \sa UsdProperty::SetDisplayGroup(), UsdProperty::SetNestedDisplayGroup()
256  bool SetDisplayGroup(const std::string& displayGroup) const;
257 
258  /// Get the displayGroup metadata for this Input, i.e. hint for the location
259  /// and nesting of the attribute.
260  /// \sa UsdProperty::GetDisplayGroup(), UsdProperty::GetNestedDisplayGroup()
263 
264  /// @}
265 
266  /// Return true if this Input is valid for querying and authoring
267  /// values and metadata, which is identically equivalent to IsDefined().
268  explicit operator bool() const {
269  return IsDefined();
270  }
271 
272  /// Equality comparison. Returns true if \a lhs and \a rhs represent the
273  /// same UsdShadeInput, false otherwise.
274  friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
275  return lhs.GetAttr() == rhs.GetAttr();
276  }
277 
278  /// Inequality comparison. Return false if \a lhs and \a rhs represent the
279  /// same UsdShadeInput, true otherwise.
280  friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
281  return !(lhs == rhs);
282  }
283 
284  // -------------------------------------------------------------------------
285  /// \name Connections API
286  // -------------------------------------------------------------------------
287  /// @{
288 
289  /// Determines whether this Input can be connected to the given
290  /// source attribute, which can be an input or an output.
291  ///
292  /// \sa UsdShadeConnectableAPI::CanConnect
294  bool CanConnect(const UsdAttribute &source) const;
295 
296  /// \overload
298  bool CanConnect(const UsdShadeInput &sourceInput) const;
299 
300  /// \overload
302  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
303 
305 
306  /// Authors a connection for this Input
307  ///
308  /// \p source is a struct that describes the upstream source attribute
309  /// with all the information necessary to make a connection. See the
310  /// documentation for UsdShadeConnectionSourceInfo.
311  /// \p mod describes the operation that should be applied to the list of
312  /// connections. By default the new connection will replace any existing
313  /// connections, but it can add to the list of connections to represent
314  /// multiple input connections.
315  ///
316  /// \return
317  /// \c true if a connection was created successfully.
318  /// \c false if this input or \p source is invalid.
319  ///
320  /// \note This method does not verify the connectability of the shading
321  /// attribute to the source. Clients must invoke CanConnect() themselves
322  /// to ensure compatibility.
323  /// \note The source shading attribute is created if it doesn't exist
324  /// already.
325  ///
326  /// \sa UsdShadeConnectableAPI::ConnectToSource
327  ///
329  bool ConnectToSource(
331  ConnectionModification const mod =
333 
334  /// \deprecated
335  /// \overload
337  bool ConnectToSource(
339  TfToken const &sourceName,
341  SdfValueTypeName typeName=SdfValueTypeName()) const;
342 
343  /// Authors a connection for this Input to the source at the given path.
344  ///
345  /// \sa UsdShadeConnectableAPI::ConnectToSource
346  ///
348  bool ConnectToSource(SdfPath const &sourcePath) const;
349 
350  /// Connects this Input to the given input, \p sourceInput.
351  ///
352  /// \sa UsdShadeConnectableAPI::ConnectToSource
353  ///
355  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
356 
357  /// Connects this Input to the given output, \p sourceOutput.
358  ///
359  /// \sa UsdShadeConnectableAPI::ConnectToSource
360  ///
362  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
363 
364  /// Connects this Input to the given sources, \p sourceInfos
365  ///
366  /// \sa UsdShadeConnectableAPI::SetConnectedSources
367  ///
369  bool SetConnectedSources(
370  std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
371 
373 
374  /// Finds the valid sources of connections for the Input.
375  ///
376  /// \p invalidSourcePaths is an optional output parameter to collect the
377  /// invalid source paths that have not been reported in the returned vector.
378  ///
379  /// Returns a vector of \p UsdShadeConnectionSourceInfo structs with
380  /// information about each upsteam attribute. If the vector is empty, there
381  /// have been no valid connections.
382  ///
383  /// \note A valid connection requires the existence of the source attribute
384  /// and also requires that the source prim is UsdShadeConnectableAPI
385  /// compatible.
386  /// \note The python wrapping returns a tuple with the valid connections
387  /// first, followed by the invalid source paths.
388  ///
389  /// \sa UsdShadeConnectableAPI::GetConnectedSources
390  ///
393  SdfPathVector *invalidSourcePaths = nullptr) const;
394 
395  /// \deprecated
398  TfToken *sourceName,
399  UsdShadeAttributeType *sourceType) const;
400 
401  /// \deprecated
402  /// Returns the "raw" (authored) connected source paths for this Input.
403  ///
404  /// \sa UsdShadeConnectableAPI::GetRawConnectedSourcePaths
405  ///
407  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
408 
409  /// Returns true if and only if this Input is currently connected to a
410  /// valid (defined) source.
411  ///
412  /// \sa UsdShadeConnectableAPI::HasConnectedSource
413  ///
415  bool HasConnectedSource() const;
416 
417  /// Returns true if the connection to this Input's source, as returned by
418  /// GetConnectedSource(), is authored across a specializes arc, which is
419  /// used to denote a base material.
420  ///
421  /// \sa UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
422  ///
425 
426  /// Disconnect source for this Input. If \p sourceAttr is valid, only a
427  /// connection to the specified attribute is disconnected, otherwise all
428  /// connections are removed.
429  ///
430  /// \sa UsdShadeConnectableAPI::DisconnectSource
431  ///
433  bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
434 
435  /// Clears sources for this Input in the current UsdEditTarget.
436  ///
437  /// Most of the time, what you probably want is DisconnectSource()
438  /// rather than this function.
439  ///
440  /// \sa UsdShadeConnectableAPI::ClearSources
441  ///
443  bool ClearSources() const;
444 
445  /// \deprecated
447  bool ClearSource() const;
448 
449  /// @}
450 
451  // -------------------------------------------------------------------------
452  /// \name Connectability API
453  // -------------------------------------------------------------------------
454  /// @{
455 
456  /// \brief Set the connectability of the Input.
457  ///
458  /// In certain shading data models, there is a need to distinguish which
459  /// inputs <b>can</b> vary over a surface from those that must be
460  /// <b>uniform</b>. This is accomplished in UsdShade by limiting the
461  /// connectability of the input. This is done by setting the
462  /// "connectability" metadata on the associated attribute.
463  ///
464  /// Connectability of an Input can be set to UsdShadeTokens->full or
465  /// UsdShadeTokens->interfaceOnly.
466  ///
467  /// \li <b>full</b> implies that the Input can be connected to any other
468  /// Input or Output.
469  /// \li <b>interfaceOnly</b> implies that the Input can only be connected to
470  /// a NodeGraph Input (which represents an interface override, not a
471  /// render-time dataflow connection), or another Input whose connectability
472  /// is also "interfaceOnly".
473  ///
474  /// The default connectability of an input is UsdShadeTokens->full.
475  ///
476  /// \sa SetConnectability()
478  bool SetConnectability(const TfToken &connectability) const;
479 
480  /// \brief Returns the connectability of the Input.
481  ///
482  /// \sa SetConnectability()
484  TfToken GetConnectability() const;
485 
486  /// \brief Clears any authored connectability on the Input.
487  ///
489  bool ClearConnectability() const;
490 
491  /// @}
492 
493  // -------------------------------------------------------------------------
494  /// \name Connected Value API
495  // -------------------------------------------------------------------------
496  /// @{
497 
498  /// \brief Find what is connected to this Input recursively
499  ///
500  /// \sa UsdShadeUtils::GetValueProducingAttributes
503  bool shaderOutputsOnly = false) const;
504 
505  /// \deprecated in favor of calling GetValueProducingAttributes
508  UsdShadeAttributeType* attrType) const;
509 
510  /// @}
511 
512 private:
514 
515  // Constructor that creates a UsdShadeInput with the given name on the
516  // given prim.
517  // \p name here is the unnamespaced name of the input.
518  UsdShadeInput(UsdPrim prim,
519  TfToken const &name,
520  SdfValueTypeName const &typeName);
521 
522  UsdAttribute _attr;
523 };
524 
526 
527 #endif // PXR_USD_USD_SHADE_INPUT_H
bool IsDefined() const
Definition: input.h:238
#define USDSHADE_API
Definition: api.h:40
Hash functor.
Definition: input.h:108
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
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 ClearSource() const
GLenum GLenum GLenum input
Definition: glew.h:14162
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
UsdShadeConnectionModification
Definition: types.h:53
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
GLuint const GLchar * name
Definition: glcorearb.h:786
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:274
friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Definition: input.h:280
USDSHADE_API bool HasRenderType() const
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Convenience wrapper for the templated UsdAttribute::Get().
Definition: input.h:85
UsdPrim GetPrim() const
Get the prim that the input belongs to.
Definition: input.h:79
USDSHADE_API bool HasSdrMetadata() const
GLsizei GLsizei GLchar * source
Definition: glcorearb.h:803
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: input.h:103
TfToken const & GetFullName() const
Definition: input.h:60
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:290
USDSHADE_API bool ClearConnectability() const
Clears any authored connectability on the Input.
USDSHADE_API bool HasConnectedSource() const
USDSHADE_API bool SetConnectedSources(std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
const TfToken & GetName() const
Definition: object.h:229
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
USDSHADE_API TfToken GetConnectability() const
Returns the connectability of the Input.
UsdShadeInput()
Definition: input.h:53
UsdPrim GetPrim() const
Definition: prim.h:2124
USDSHADE_API TfToken GetRenderType() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
USDSHADE_API bool DisconnectSource(UsdAttribute const &sourceAttr=UsdAttribute()) const
USDSHADE_API bool ClearSources() const
size_t operator()(const UsdShadeInput &input) const
Definition: input.h:109
USDSHADE_API UsdShadeAttributeVector GetValueProducingAttributes(bool shaderOutputsOnly=false) const
Find what is connected to this Input recursively.
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:229
USDSHADE_API std::string GetDocumentation() const
USDSHADE_API bool SetDisplayGroup(const std::string &displayGroup) const
USDSHADE_API UsdAttribute GetValueProducingAttribute(UsdShadeAttributeType *attrType) const
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
Definition: core.h:1131
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
USDSHADE_API bool ConnectToSource(UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
size_t hash_value(const CH_ChannelRef &ref)
USDSHADE_API bool SetConnectability(const TfToken &connectability) const
Set the connectability of the Input.
Definition: value.h:166
USDSHADE_API bool SetDocumentation(const std::string &docs) const
UsdShadeAttributeType
Definition: types.h:39
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const