HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
output.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_OUTPUT_H
25 #define PXR_USD_USD_SHADE_OUTPUT_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usdShade/api.h"
29 #include "pxr/usd/usd/attribute.h"
30 #include "pxr/usd/ndr/declare.h"
31 #include "pxr/usd/usdShade/utils.h"
32 
33 #include <vector>
34 
36 
38 class UsdShadeInput;
39 
40 /// \class UsdShadeOutput
41 ///
42 /// This class encapsulates a shader or node-graph output, which is a
43 /// connectable attribute representing a typed, externally computed value.
44 ///
46 {
47 public:
48  /// Default constructor returns an invalid Output. Exists for
49  /// container classes
51  {
52  // nothing
53  }
54 
55  /// Get the name of the attribute associated with the output.
56  ///
57  TfToken const &GetFullName() const {
58  return _attr.GetName();
59  }
60 
61  /// Returns the name of the output.
62  ///
63  /// We call this the base name since it strips off the "outputs:" namespace
64  /// prefix from the attribute name, and returns it.
65  ///
67  TfToken GetBaseName() const;
68 
69  /// Get the prim that the output belongs to.
70  UsdPrim GetPrim() const {
71  return _attr.GetPrim();
72  }
73 
74  /// Get the "scene description" value type name of the attribute associated
75  /// with the output.
76  ///
79 
80  /// Set a value for the output.
81  ///
82  /// It's unusual to be setting a value on an output since it represents
83  /// an externally computed value. The Set API is provided here just for the
84  /// sake of completeness and uniformity with other property schema.
85  ///
87  bool Set(const VtValue& value,
89 
90  /// \overload
91  /// Set the attribute value of the Output at \p time
92  ///
93  template <typename T>
94  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
95  if (UsdAttribute attr = GetAttr()) {
96  return attr.Set(value, time);
97  }
98  return false;
99  }
100 
101  /// \name Configuring the Output's Type
102  /// @{
103 
104  /// Specify an alternative, renderer-specific type to use when
105  /// emitting/translating this output, rather than translating based
106  /// on its GetTypeName()
107  ///
108  /// For example, we set the renderType to "struct" for outputs that
109  /// are of renderman custom struct types.
110  ///
111  /// \return true on success
113  bool SetRenderType(TfToken const& renderType) const;
114 
115  /// Return this output's specialized renderType, or an empty
116  /// token if none was authored.
117  ///
118  /// \sa SetRenderType()
120  TfToken GetRenderType() const;
121 
122  /// Return true if a renderType has been specified for this
123  /// output.
124  ///
125  /// \sa SetRenderType()
127  bool HasRenderType() const;
128 
129  /// @}
130 
131  /// \name API to author and query an Output's sdrMetadata
132  ///
133  /// This section provides API for authoring and querying shader registry
134  /// metadata on an Output. When the owning shader prim is providing a shader
135  /// definition, the authored "sdrMetadata" dictionary value provides
136  /// metadata needed to populate the Output correctly in the shader registry.
137  ///
138  /// We expect the keys in sdrMetadata to correspond to the keys
139  /// in \ref SdrPropertyMetadata. However, this is not strictly enforced by
140  /// the API. The only allowed value type in the "sdrMetadata" dictionary is
141  /// a std::string since it needs to be converted into a NdrTokenMap, which
142  /// Sdr will parse using the utilities available in \ref SdrMetadataHelpers.
143  ///
144  /// @{
145 
146  /// Returns this Output's composed "sdrMetadata" dictionary as a
147  /// NdrTokenMap.
149  NdrTokenMap GetSdrMetadata() const;
150 
151  /// Returns the value corresponding to \p key in the composed
152  /// <b>sdrMetadata</b> dictionary.
154  std::string GetSdrMetadataByKey(const TfToken &key) const;
155 
156  /// Authors the given \p sdrMetadata value on this Output at the current
157  /// EditTarget.
159  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
160 
161  /// Sets the value corresponding to \p key to the given string \p value, in
162  /// the Output's "sdrMetadata" dictionary at the current EditTarget.
164  void SetSdrMetadataByKey(
165  const TfToken &key,
166  const std::string &value) const;
167 
168  /// Returns true if the Output has a non-empty composed "sdrMetadata"
169  /// dictionary value.
171  bool HasSdrMetadata() const;
172 
173  /// Returns true if there is a value corresponding to the given \p key in
174  /// the composed "sdrMetadata" dictionary.
176  bool HasSdrMetadataByKey(const TfToken &key) const;
177 
178  /// Clears any "sdrMetadata" value authored on the Output in the current
179  /// EditTarget.
181  void ClearSdrMetadata() const;
182 
183  /// Clears the entry corresponding to the given \p key in the
184  /// "sdrMetadata" dictionary authored in the current EditTarget.
186  void ClearSdrMetadataByKey(const TfToken &key) const;
187 
188  /// @}
189 
190  // ---------------------------------------------------------------
191  /// \name UsdAttribute API
192  // ---------------------------------------------------------------
193 
194  /// @{
195 
196  /// Speculative constructor that will produce a valid UsdShadeOutput when
197  /// \p attr already represents a shade Output, and produces an \em invalid
198  /// UsdShadeOutput otherwise (i.e. the explicit bool conversion operator
199  /// will return false).
201  explicit UsdShadeOutput(const UsdAttribute &attr);
202 
203  /// Test whether a given UsdAttribute represents a valid Output, which
204  /// implies that creating a UsdShadeOutput from the attribute will succeed.
205  ///
206  /// Success implies that \c attr.IsDefined() is true.
208  static bool IsOutput(const UsdAttribute &attr);
209 
210  /// Explicit UsdAttribute extractor.
211  UsdAttribute GetAttr() const { return _attr; }
212 
213  /// Allow UsdShadeOutput to auto-convert to UsdAttribute, so you can
214  /// pass a UsdShadeOutput to any function that accepts a UsdAttribute or
215  /// const-ref thereto.
216  operator UsdAttribute () const { return GetAttr(); }
217 
218  /// Return true if the wrapped UsdAttribute is defined, and in
219  /// addition the attribute is identified as an output.
220  ///
221  bool IsDefined() const {
222  return IsOutput(_attr);
223  }
224 
225  /// @}
226 
227  // -------------------------------------------------------------------------
228  /// \name Connections API
229  // -------------------------------------------------------------------------
230  /// @{
231 
232  /// Determines whether this Output can be connected to the given
233  /// source attribute, which can be an input or an output.
234  ///
235  /// An output is considered to be connectable only if it belongs to a
236  /// node-graph. Shader outputs are not connectable.
237  ///
238  /// \sa UsdShadeConnectableAPI::CanConnect
240  bool CanConnect(const UsdAttribute &source) const;
241 
242  /// \overload
244  bool CanConnect(const UsdShadeInput &sourceInput) const;
245 
246  /// \overload
248  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
249 
250  /// Authors a connection for this Output to the source described by the
251  /// following three elements:
252  /// \p source, the connectable owning the source,
253  /// \p sourceName, the name of the source and
254  /// \p sourceType, the value type of the source shading attribute.
255  ///
256  /// \p typeName if specified, is the typename of the attribute to create
257  /// on the source if it doesn't exist. It is also used to validate whether
258  /// the types of the source and consumer of the connection are compatible.
259  ///
260  /// \sa UsdShadeConnectableAPI::ConnectToSource
261  ///
263  bool ConnectToSource(
265  TfToken const &sourceName,
267  SdfValueTypeName typeName=SdfValueTypeName()) const;
268 
269  /// Authors a connection for this Output to the source at the given path.
270  ///
271  /// \sa UsdShadeConnectableAPI::ConnectToSource
272  ///
274  bool ConnectToSource(SdfPath const &sourcePath) const;
275 
276  /// Connects this Output to the given input, \p sourceInput.
277  ///
278  /// \sa UsdShadeConnectableAPI::ConnectToSource
279  ///
281  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
282 
283  /// Connects this Output to the given output, \p sourceOutput.
284  ///
285  /// \sa UsdShadeConnectableAPI::ConnectToSource
286  ///
288  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
289 
290  /// Finds the source of a connection for this Output.
291  ///
292  /// \p source is an output parameter which will be set to the source
293  /// connectable prim.
294  /// \p sourceName will be set to the name of the source shading attribute,
295  /// which may be an input or an output, as specified by \p sourceType
296  /// \p sourceType will have the type of the source shading attribute, i.e.
297  /// whether it is an \c Input or \c Output
298  ///
299  /// \return
300  /// \c true if the shading attribute is connected to a valid, defined source
301  /// attribute.
302  /// \c false if the shading attribute is not connected to a single, defined
303  /// source attribute.
304  ///
305  /// \note The python wrapping for this method returns a
306  /// (source, sourceName, sourceType) tuple if the parameter is connected,
307  /// else \c None
308  ///
309  /// \sa UsdShadeConnectableAPI::GetConnectedSource
310  ///
313  TfToken *sourceName,
314  UsdShadeAttributeType *sourceType) const;
315 
316  /// Returns the "raw" (authored) connected source paths for this Output.
317  ///
318  /// \sa UsdShadeConnectableAPI::GetRawConnectedSourcePaths
319  ///
321  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
322 
323  /// Returns true if and only if this Output is currently connected to a
324  /// valid (defined) source.
325  ///
326  /// \sa UsdShadeConnectableAPI::HasConnectedSource
327  ///
329  bool HasConnectedSource() const;
330 
331  /// Returns true if the connection to this Output's source, as returned by
332  /// GetConnectedSource(), is authored across a specializes arc, which is
333  /// used to denote a base material.
334  ///
335  /// \sa UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
336  ///
339 
340  /// Disconnect source for this Output.
341  ///
342  /// \sa UsdShadeConnectableAPI::DisconnectSource
343  ///
345  bool DisconnectSource() const;
346 
347  /// Clears source for this shading attribute in the current UsdEditTarget.
348  ///
349  /// Most of the time, what you probably want is DisconnectSource()
350  /// rather than this function.
351  ///
352  /// \sa UsdShadeConnectableAPI::ClearSource
353  ///
355  bool ClearSource() const;
356 
357  /// @}
358 
359  /// Return true if this Output is valid for querying and authoring
360  /// values and metadata, which is identically equivalent to IsDefined().
361  explicit operator bool() const {
362  return IsDefined();
363  }
364 
365  /// Equality comparison. Returns true if \a lhs and \a rhs represent the
366  /// same UsdShadeOutput, false otherwise.
367  friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
368  return lhs.GetAttr() == rhs.GetAttr();
369  }
370 
371 private:
373 
374  // Constructor that creates a UsdShadeOutput with the given name on the
375  // given prim.
376  // \p name here is the unnamespaced name of the output.
377  UsdShadeOutput(UsdPrim prim,
378  TfToken const &name,
379  SdfValueTypeName const &typeName);
380 
381  UsdAttribute _attr;
382 };
383 
384 
386 
387 #endif // PXR_USD_USD_SHADE_OUTPUT_H
UsdShadeOutput()
Definition: output.h:50
USDSHADE_API SdfValueTypeName GetTypeName() const
#define USDSHADE_API
Definition: api.h:40
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool HasConnectedSource() const
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
GLuint const GLchar * name
Definition: glew.h:1814
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
GT_API const UT_StringHolder time
GLsizei GLsizei GLchar * source
Definition: glew.h:1832
USDSHADE_API bool HasRenderType() const
USDSHADE_API TfToken GetRenderType() const
USDSHADE_API bool CanConnect(const UsdAttribute &source) const
USDSHADE_API bool DisconnectSource() const
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
bool IsDefined() const
Definition: output.h:221
Definition: token.h:87
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
Definition: prim.h:132
Definition: path.h:288
UsdAttribute GetAttr() const
Explicit UsdAttribute extractor.
Definition: output.h:211
const TfToken & GetName() const
Definition: object.h:229
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
USDSHADE_API bool HasSdrMetadata() const
USDSHADE_API void ClearSdrMetadata() const
USDSHADE_API TfToken GetBaseName() const
UsdShadeAttributeType
Definition: utils.h:42
UsdPrim GetPrim() const
Definition: prim.h:1959
USDSHADE_API bool ConnectToSource(UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
GLsizei const GLchar *const * string
Definition: glew.h:1844
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: output.h:94
USDSHADE_API void SetSdrMetadataByKey(const TfToken &key, const std::string &value) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
UsdPrim GetPrim() const
Get the prim that the output belongs to.
Definition: output.h:70
USDSHADE_API NdrTokenMap GetSdrMetadata() const
TfToken const & GetFullName() const
Definition: output.h:57
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
static USDSHADE_API bool IsOutput(const UsdAttribute &attr)
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
GLsizei const GLfloat * value
Definition: glew.h:1849
friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Definition: output.h:367
USDSHADE_API bool ClearSource() const
Definition: value.h:174