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/usdShade/types.h"
30 #include "pxr/usd/usdShade/utils.h"
31 #include "pxr/usd/usd/attribute.h"
32 #include "pxr/usd/ndr/declare.h"
33 
34 #include <vector>
35 
37 
40 class UsdShadeInput;
41 
42 /// \class UsdShadeOutput
43 ///
44 /// This class encapsulates a shader or node-graph output, which is a
45 /// connectable attribute representing a typed, externally computed value.
46 ///
48 {
49 public:
50  /// Default constructor returns an invalid Output. Exists for
51  /// container classes
53  {
54  // nothing
55  }
56 
57  /// Get the name of the attribute associated with the output.
58  ///
59  TfToken const &GetFullName() const {
60  return _attr.GetName();
61  }
62 
63  /// Returns the name of the output.
64  ///
65  /// We call this the base name since it strips off the "outputs:" namespace
66  /// prefix from the attribute name, and returns it.
67  ///
69  TfToken GetBaseName() const;
70 
71  /// Get the prim that the output belongs to.
72  UsdPrim GetPrim() const {
73  return _attr.GetPrim();
74  }
75 
76  /// Get the "scene description" value type name of the attribute associated
77  /// with the output.
78  ///
81 
82  /// Set a value for the output.
83  ///
84  /// It's unusual to be setting a value on an output since it represents
85  /// an externally computed value. The Set API is provided here just for the
86  /// sake of completeness and uniformity with other property schema.
87  ///
89  bool Set(const VtValue& value,
91 
92  /// \overload
93  /// Set the attribute value of the Output at \p time
94  ///
95  template <typename T>
96  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
97  if (UsdAttribute attr = GetAttr()) {
98  return attr.Set(value, time);
99  }
100  return false;
101  }
102 
103  /// \name Configuring the Output's Type
104  /// @{
105 
106  /// Specify an alternative, renderer-specific type to use when
107  /// emitting/translating this output, rather than translating based
108  /// on its GetTypeName()
109  ///
110  /// For example, we set the renderType to "struct" for outputs that
111  /// are of renderman custom struct types.
112  ///
113  /// \return true on success
115  bool SetRenderType(TfToken const& renderType) const;
116 
117  /// Return this output's specialized renderType, or an empty
118  /// token if none was authored.
119  ///
120  /// \sa SetRenderType()
122  TfToken GetRenderType() const;
123 
124  /// Return true if a renderType has been specified for this
125  /// output.
126  ///
127  /// \sa SetRenderType()
129  bool HasRenderType() const;
130 
131  /// @}
132 
133  /// \name API to author and query an Output's sdrMetadata
134  ///
135  /// This section provides API for authoring and querying shader registry
136  /// metadata on an Output. When the owning shader prim is providing a shader
137  /// definition, the authored "sdrMetadata" dictionary value provides
138  /// metadata needed to populate the Output correctly in the shader registry.
139  ///
140  /// We expect the keys in sdrMetadata to correspond to the keys
141  /// in \ref SdrPropertyMetadata. However, this is not strictly enforced by
142  /// the API. The only allowed value type in the "sdrMetadata" dictionary is
143  /// a std::string since it needs to be converted into a NdrTokenMap, which
144  /// Sdr will parse using the utilities available in \ref SdrMetadataHelpers.
145  ///
146  /// @{
147 
148  /// Returns this Output's composed "sdrMetadata" dictionary as a
149  /// NdrTokenMap.
151  NdrTokenMap GetSdrMetadata() const;
152 
153  /// Returns the value corresponding to \p key in the composed
154  /// <b>sdrMetadata</b> dictionary.
156  std::string GetSdrMetadataByKey(const TfToken &key) const;
157 
158  /// Authors the given \p sdrMetadata value on this Output at the current
159  /// EditTarget.
161  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
162 
163  /// Sets the value corresponding to \p key to the given string \p value, in
164  /// the Output's "sdrMetadata" dictionary at the current EditTarget.
166  void SetSdrMetadataByKey(
167  const TfToken &key,
168  const std::string &value) const;
169 
170  /// Returns true if the Output has a non-empty composed "sdrMetadata"
171  /// dictionary value.
173  bool HasSdrMetadata() const;
174 
175  /// Returns true if there is a value corresponding to the given \p key in
176  /// the composed "sdrMetadata" dictionary.
178  bool HasSdrMetadataByKey(const TfToken &key) const;
179 
180  /// Clears any "sdrMetadata" value authored on the Output in the current
181  /// EditTarget.
183  void ClearSdrMetadata() const;
184 
185  /// Clears the entry corresponding to the given \p key in the
186  /// "sdrMetadata" dictionary authored in the current EditTarget.
188  void ClearSdrMetadataByKey(const TfToken &key) const;
189 
190  /// @}
191 
192  // ---------------------------------------------------------------
193  /// \name UsdAttribute API
194  // ---------------------------------------------------------------
195 
196  /// @{
197 
198  /// Speculative constructor that will produce a valid UsdShadeOutput when
199  /// \p attr already represents a shade Output, and produces an \em invalid
200  /// UsdShadeOutput otherwise (i.e. the explicit bool conversion operator
201  /// will return false).
203  explicit UsdShadeOutput(const UsdAttribute &attr);
204 
205  /// Test whether a given UsdAttribute represents a valid Output, which
206  /// implies that creating a UsdShadeOutput from the attribute will succeed.
207  ///
208  /// Success implies that \c attr.IsDefined() is true.
210  static bool IsOutput(const UsdAttribute &attr);
211 
212  /// Explicit UsdAttribute extractor.
213  const UsdAttribute &GetAttr() const { return _attr; }
214 
215  /// Allow UsdShadeOutput to auto-convert to UsdAttribute, so you can
216  /// pass a UsdShadeOutput to any function that accepts a UsdAttribute or
217  /// const-ref thereto.
218  operator UsdAttribute () const { return GetAttr(); }
219 
220  /// Return true if the wrapped UsdAttribute is defined, and in
221  /// addition the attribute is identified as an output.
222  ///
223  bool IsDefined() const {
224  return IsOutput(_attr);
225  }
226 
227  /// @}
228 
229  // -------------------------------------------------------------------------
230  /// \name Connections API
231  // -------------------------------------------------------------------------
232  /// @{
233 
234  /// Determines whether this Output can be connected to the given
235  /// source attribute, which can be an input or an output.
236  ///
237  /// An output is considered to be connectable only if it belongs to a
238  /// node-graph. Shader outputs are not connectable.
239  ///
240  /// \sa UsdShadeConnectableAPI::CanConnect
242  bool CanConnect(const UsdAttribute &source) const;
243 
244  /// \overload
246  bool CanConnect(const UsdShadeInput &sourceInput) const;
247 
248  /// \overload
250  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
251 
253 
254  /// Authors a connection for this Output
255  ///
256  /// \p source is a struct that describes the upstream source attribute
257  /// with all the information necessary to make a connection. See the
258  /// documentation for UsdShadeConnectionSourceInfo.
259  /// \p mod describes the operation that should be applied to the list of
260  /// connections. By default the new connection will replace any existing
261  /// connections, but it can add to the list of connections to represent
262  /// multiple input connections.
263  ///
264  /// \return
265  /// \c true if a connection was created successfully.
266  /// \c false if \p shadingAttr or \p source is invalid.
267  ///
268  /// \note This method does not verify the connectability of the shading
269  /// attribute to the source. Clients must invoke CanConnect() themselves
270  /// to ensure compatibility.
271  /// \note The source shading attribute is created if it doesn't exist
272  /// already.
273  ///
274  /// \sa UsdShadeConnectableAPI::ConnectToSource
275  ///
277  bool ConnectToSource(
279  ConnectionModification const mod =
281 
282  /// \deprecated
283  /// \overload
285  bool ConnectToSource(
287  TfToken const &sourceName,
289  SdfValueTypeName typeName=SdfValueTypeName()) const;
290 
291  /// Authors a connection for this Output to the source at the given path.
292  ///
293  /// \sa UsdShadeConnectableAPI::ConnectToSource
294  ///
296  bool ConnectToSource(SdfPath const &sourcePath) const;
297 
298  /// Connects this Output to the given input, \p sourceInput.
299  ///
300  /// \sa UsdShadeConnectableAPI::ConnectToSource
301  ///
303  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
304 
305  /// Connects this Output to the given output, \p sourceOutput.
306  ///
307  /// \sa UsdShadeConnectableAPI::ConnectToSource
308  ///
310  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
311 
312  /// Connects this Output to the given sources, \p sourceInfos
313  ///
314  /// \sa UsdShadeConnectableAPI::SetConnectedSources
315  ///
317  bool SetConnectedSources(
318  std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
319 
320  // XXX move to new header
322 
323  /// Finds the valid sources of connections for the Output.
324  ///
325  /// \p invalidSourcePaths is an optional output parameter to collect the
326  /// invalid source paths that have not been reported in the returned vector.
327  ///
328  /// Returns a vector of \p UsdShadeConnectionSourceInfo structs with
329  /// information about each upsteam attribute. If the vector is empty, there
330  /// have been no valid connections.
331  ///
332  /// \note A valid connection requires the existence of the source attribute
333  /// and also requires that the source prim is UsdShadeConnectableAPI
334  /// compatible.
335  /// \note The python wrapping returns a tuple with the valid connections
336  /// first, followed by the invalid source paths.
337  ///
338  /// \sa UsdShadeConnectableAPI::GetConnectedSources
339  ///
342  SdfPathVector *invalidSourcePaths = nullptr) const;
343 
344  /// \deprecated Please use GetConnectedSources instead
347  TfToken *sourceName,
348  UsdShadeAttributeType *sourceType) const;
349 
350  /// \deprecated
351  /// Returns the "raw" (authored) connected source paths for this Output.
352  ///
353  /// \sa UsdShadeConnectableAPI::GetRawConnectedSourcePaths
354  ///
356  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
357 
358  /// Returns true if and only if this Output is currently connected to a
359  /// valid (defined) source.
360  ///
361  /// \sa UsdShadeConnectableAPI::HasConnectedSource
362  ///
364  bool HasConnectedSource() const;
365 
366  /// Returns true if the connection to this Output's source, as returned by
367  /// GetConnectedSource(), is authored across a specializes arc, which is
368  /// used to denote a base material.
369  ///
370  /// \sa UsdShadeConnectableAPI::IsSourceConnectionFromBaseMaterial
371  ///
374 
375  /// Disconnect source for this Output. If \p sourceAttr is valid, only a
376  /// connection to the specified attribute is disconnected, otherwise all
377  /// connections are removed.
378  ///
379  /// \sa UsdShadeConnectableAPI::DisconnectSource
380  ///
382  bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
383 
384  /// Clears sources for this Output in the current UsdEditTarget.
385  ///
386  /// Most of the time, what you probably want is DisconnectSource()
387  /// rather than this function.
388  ///
389  /// \sa UsdShadeConnectableAPI::ClearSources
390  ///
392  bool ClearSources() const;
393 
394  /// \deprecated
396  bool ClearSource() const;
397 
398  /// @}
399 
400  // -------------------------------------------------------------------------
401  /// \name Connected Value API
402  // -------------------------------------------------------------------------
403  /// @{
404 
405  /// \brief Find what is connected to this Output recursively
406  ///
407  /// \sa UsdShadeUtils::GetValueProducingAttributes
410  bool shaderOutputsOnly = false) const;
411 
412  /// @}
413 
414  /// Return true if this Output is valid for querying and authoring
415  /// values and metadata, which is identically equivalent to IsDefined().
416  explicit operator bool() const {
417  return IsDefined();
418  }
419 
420  /// Equality comparison. Returns true if \a lhs and \a rhs represent the
421  /// same UsdShadeOutput, false otherwise.
422  friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
423  return lhs.GetAttr() == rhs.GetAttr();
424  }
425 
426  /// Inequality comparison. Return false if \a lhs and \a rhs represent the
427  /// same UsdShadeOutput, true otherwise.
428  friend bool operator!=(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
429  return !(lhs == rhs);
430  }
431 
432 private:
434 
435  // Constructor that creates a UsdShadeOutput with the given name on the
436  // given prim.
437  // \p name here is the unnamespaced name of the output.
438  UsdShadeOutput(UsdPrim prim,
439  TfToken const &name,
440  SdfValueTypeName const &typeName);
441 
442  UsdAttribute _attr;
443 };
444 
445 
447 
448 #endif // PXR_USD_USD_SHADE_OUTPUT_H
UsdShadeOutput()
Definition: output.h:52
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
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
GT_API const UT_StringHolder time
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
UsdShadeConnectionModification
Definition: types.h:53
USDSHADE_API bool HasRenderType() const
USDSHADE_API bool ClearSources() const
USDSHADE_API TfToken GetRenderType() const
friend bool operator!=(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Definition: output.h:428
USDSHADE_API bool CanConnect(const UsdAttribute &source) const
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
const UsdAttribute & GetAttr() const
Explicit UsdAttribute extractor.
Definition: output.h:213
bool IsDefined() const
Definition: output.h:223
Definition: token.h:87
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
USDSHADE_API bool ConnectToSource(UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
GLsizei GLsizei GLchar * source
Definition: glcorearb.h:803
Definition: prim.h:133
USDSHADE_API UsdShadeAttributeVector GetValueProducingAttributes(bool shaderOutputsOnly=false) const
Find what is connected to this Output recursively.
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:290
const TfToken & GetName() const
Definition: object.h:238
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
USDSHADE_API bool HasSdrMetadata() const
USDSHADE_API void ClearSdrMetadata() const
USDSHADE_API TfToken GetBaseName() const
UsdPrim GetPrim() const
Definition: prim.h:2804
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Definition: output.h:96
USDSHADE_API bool SetConnectedSources(std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
USDSHADE_API void SetSdrMetadataByKey(const TfToken &key, const std::string &value) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const
UsdPrim GetPrim() const
Get the prim that the output belongs to.
Definition: output.h:72
USDSHADE_API NdrTokenMap GetSdrMetadata() const
Definition: core.h:1131
TfToken const & GetFullName() const
Definition: output.h:59
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
friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Definition: output.h:422
USDSHADE_API bool DisconnectSource(UsdAttribute const &sourceAttr=UsdAttribute()) const
USDSHADE_API bool ClearSource() const
Definition: value.h:164
UsdShadeAttributeType
Definition: types.h:39