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  ///
255  /// Note for an input representing a nested SdrShaderProperty, its expected
256  /// to have the scope delimited by a ":".
257  /// \sa UsdProperty::SetDisplayGroup(), UsdProperty::SetNestedDisplayGroup()
258  /// \sa SdrShaderProperty::GetPage()
260  bool SetDisplayGroup(const std::string& displayGroup) const;
261 
262  /// Get the displayGroup metadata for this Input, i.e. hint for the location
263  /// and nesting of the attribute.
264  /// \sa UsdProperty::GetDisplayGroup(), UsdProperty::GetNestedDisplayGroup()
267 
268  /// @}
269 
270  /// Return true if this Input is valid for querying and authoring
271  /// values and metadata, which is identically equivalent to IsDefined().
272  explicit operator bool() const {
273  return IsDefined();
274  }
275 
276  /// Equality comparison. Returns true if \a lhs and \a rhs represent the
277  /// same UsdShadeInput, false otherwise.
278  friend bool operator==(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
279  return lhs.GetAttr() == rhs.GetAttr();
280  }
281 
282  /// Inequality comparison. Return false if \a lhs and \a rhs represent the
283  /// same UsdShadeInput, true otherwise.
284  friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs) {
285  return !(lhs == rhs);
286  }
287 
288  // -------------------------------------------------------------------------
289  /// \name Connections API
290  // -------------------------------------------------------------------------
291  /// @{
292 
293  /// Determines whether this Input can be connected to the given
294  /// source attribute, which can be an input or an output.
295  ///
296  /// \sa UsdShadeConnectableAPI::CanConnect
298  bool CanConnect(const UsdAttribute &source) const;
299 
300  /// \overload
302  bool CanConnect(const UsdShadeInput &sourceInput) const;
303 
304  /// \overload
306  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
307 
309 
310  /// Authors a connection for this Input
311  ///
312  /// \p source is a struct that describes the upstream source attribute
313  /// with all the information necessary to make a connection. See the
314  /// documentation for UsdShadeConnectionSourceInfo.
315  /// \p mod describes the operation that should be applied to the list of
316  /// connections. By default the new connection will replace any existing
317  /// connections, but it can add to the list of connections to represent
318  /// multiple input connections.
319  ///
320  /// \return
321  /// \c true if a connection was created successfully.
322  /// \c false if this input or \p source is invalid.
323  ///
324  /// \note This method does not verify the connectability of the shading
325  /// attribute to the source. Clients must invoke CanConnect() themselves
326  /// to ensure compatibility.
327  /// \note The source shading attribute is created if it doesn't exist
328  /// already.
329  ///
330  /// \sa UsdShadeConnectableAPI::ConnectToSource
331  ///
333  bool ConnectToSource(
335  ConnectionModification const mod =
337 
338  /// \deprecated
339  /// \overload
341  bool ConnectToSource(
343  TfToken const &sourceName,
345  SdfValueTypeName typeName=SdfValueTypeName()) const;
346 
347  /// Authors a connection for this Input to the source at the given path.
348  ///
349  /// \sa UsdShadeConnectableAPI::ConnectToSource
350  ///
352  bool ConnectToSource(SdfPath const &sourcePath) const;
353 
354  /// Connects this Input to the given input, \p sourceInput.
355  ///
356  /// \sa UsdShadeConnectableAPI::ConnectToSource
357  ///
359  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
360 
361  /// Connects this Input to the given output, \p sourceOutput.
362  ///
363  /// \sa UsdShadeConnectableAPI::ConnectToSource
364  ///
366  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
367 
368  /// Connects this Input to the given sources, \p sourceInfos
369  ///
370  /// \sa UsdShadeConnectableAPI::SetConnectedSources
371  ///
373  bool SetConnectedSources(
374  std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
375 
377 
378  /// Finds the valid sources of connections for the Input.
379  ///
380  /// \p invalidSourcePaths is an optional output parameter to collect the
381  /// invalid source paths that have not been reported in the returned vector.
382  ///
383  /// Returns a vector of \p UsdShadeConnectionSourceInfo structs with
384  /// information about each upsteam attribute. If the vector is empty, there
385  /// have been no valid connections.
386  ///
387  /// \note A valid connection requires the existence of the source attribute
388  /// and also requires that the source prim is UsdShadeConnectableAPI
389  /// compatible.
390  /// \note The python wrapping returns a tuple with the valid connections
391  /// first, followed by the invalid source paths.
392  ///
393  /// \sa UsdShadeConnectableAPI::GetConnectedSources
394  ///
397  SdfPathVector *invalidSourcePaths = nullptr) const;
398 
399  /// \deprecated
402  TfToken *sourceName,
403  UsdShadeAttributeType *sourceType) const;
404 
405  /// \deprecated
406  /// Returns the "raw" (authored) connected source paths for this Input.
407  ///
408  /// \sa UsdShadeConnectableAPI::GetRawConnectedSourcePaths
409  ///
411  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
412 
413  /// Returns true if and only if this Input is currently connected to a
414  /// valid (defined) source.
415  ///
416  /// \sa UsdShadeConnectableAPI::HasConnectedSource
417  ///
419  bool HasConnectedSource() const;
420 
421  /// Returns true if the connection to this Input's source, as returned by
422  /// GetConnectedSource(), is authored across a specializes arc, which is
423  /// used to denote a base material.
424  ///
425  /// \sa UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
426  ///
429 
430  /// Disconnect source for this Input. If \p sourceAttr is valid, only a
431  /// connection to the specified attribute is disconnected, otherwise all
432  /// connections are removed.
433  ///
434  /// \sa UsdShadeConnectableAPI::DisconnectSource
435  ///
437  bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
438 
439  /// Clears sources for this Input in the current UsdEditTarget.
440  ///
441  /// Most of the time, what you probably want is DisconnectSource()
442  /// rather than this function.
443  ///
444  /// \sa UsdShadeConnectableAPI::ClearSources
445  ///
447  bool ClearSources() const;
448 
449  /// \deprecated
451  bool ClearSource() const;
452 
453  /// @}
454 
455  // -------------------------------------------------------------------------
456  /// \name Connectability API
457  // -------------------------------------------------------------------------
458  /// @{
459 
460  /// \brief Set the connectability of the Input.
461  ///
462  /// In certain shading data models, there is a need to distinguish which
463  /// inputs <b>can</b> vary over a surface from those that must be
464  /// <b>uniform</b>. This is accomplished in UsdShade by limiting the
465  /// connectability of the input. This is done by setting the
466  /// "connectability" metadata on the associated attribute.
467  ///
468  /// Connectability of an Input can be set to UsdShadeTokens->full or
469  /// UsdShadeTokens->interfaceOnly.
470  ///
471  /// \li <b>full</b> implies that the Input can be connected to any other
472  /// Input or Output.
473  /// \li <b>interfaceOnly</b> implies that the Input can only be connected to
474  /// a NodeGraph Input (which represents an interface override, not a
475  /// render-time dataflow connection), or another Input whose connectability
476  /// is also "interfaceOnly".
477  ///
478  /// The default connectability of an input is UsdShadeTokens->full.
479  ///
480  /// \sa SetConnectability()
482  bool SetConnectability(const TfToken &connectability) const;
483 
484  /// \brief Returns the connectability of the Input.
485  ///
486  /// \sa SetConnectability()
488  TfToken GetConnectability() const;
489 
490  /// \brief Clears any authored connectability on the Input.
491  ///
493  bool ClearConnectability() const;
494 
495  /// @}
496 
497  // -------------------------------------------------------------------------
498  /// \name Connected Value API
499  // -------------------------------------------------------------------------
500  /// @{
501 
502  /// \brief Find what is connected to this Input recursively
503  ///
504  /// \sa UsdShadeUtils::GetValueProducingAttributes
507  bool shaderOutputsOnly = false) const;
508 
509  /// \deprecated in favor of calling GetValueProducingAttributes
512  UsdShadeAttributeType* attrType) const;
513 
514  /// @}
515 
516 private:
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 
530 
531 #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:112
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:436
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
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDSHADE_API bool ClearSource() const
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
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:278
friend bool operator!=(const UsdShadeInput &lhs, const UsdShadeInput &rhs)
Definition: input.h:284
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
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:135
USDSHADE_API TfToken GetBaseName() const
GLuint const GLchar * name
Definition: glcorearb.h:786
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: attribute.h:477
Definition: path.h:291
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:238
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:212
USDSHADE_API TfToken GetConnectability() const
Returns the connectability of the Input.
UsdShadeInput()
Definition: input.h:53
UsdPrim GetPrim() const
Definition: prim.h:2610
USDSHADE_API TfToken GetRenderType() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
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:167
USDSHADE_API bool SetDocumentation(const std::string &docs) const
UsdShadeAttributeType
Definition: types.h:39
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const