output.h
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 
36 PXR_NAMESPACE_OPEN_SCOPE
37 
40 class UsdShadeInput;
41 
48 {
49 public:
53  {
54  // nothing
55  }
56 
59  TfToken const &GetFullName() const {
60  return _attr.GetName();
61  }
62 
68  USDSHADE_API
69  TfToken GetBaseName() const;
70 
72  UsdPrim GetPrim() const {
73  return _attr.GetPrim();
74  }
75 
79  USDSHADE_API
81 
88  USDSHADE_API
89  bool Set(const VtValue& value,
90  UsdTimeCode time = UsdTimeCode::Default()) const;
91 
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 
105 
114  USDSHADE_API
115  bool SetRenderType(TfToken const& renderType) const;
116 
121  USDSHADE_API
122  TfToken GetRenderType() const;
123 
128  USDSHADE_API
129  bool HasRenderType() const;
130 
132 
147 
150  USDSHADE_API
151  NdrTokenMap GetSdrMetadata() const;
152 
155  USDSHADE_API
156  std::string GetSdrMetadataByKey(const TfToken &key) const;
157 
160  USDSHADE_API
161  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
162 
165  USDSHADE_API
166  void SetSdrMetadataByKey(
167  const TfToken &key,
168  const std::string &value) const;
169 
172  USDSHADE_API
173  bool HasSdrMetadata() const;
174 
177  USDSHADE_API
178  bool HasSdrMetadataByKey(const TfToken &key) const;
179 
182  USDSHADE_API
183  void ClearSdrMetadata() const;
184 
187  USDSHADE_API
188  void ClearSdrMetadataByKey(const TfToken &key) const;
189 
191 
192  // ---------------------------------------------------------------
194  // ---------------------------------------------------------------
195 
197 
202  USDSHADE_API
203  explicit UsdShadeOutput(const UsdAttribute &attr);
204 
209  USDSHADE_API
210  static bool IsOutput(const UsdAttribute &attr);
211 
213  UsdAttribute GetAttr() const { return _attr; }
214 
218  operator UsdAttribute () const { return GetAttr(); }
219 
223  bool IsDefined() const {
224  return IsOutput(_attr);
225  }
226 
228 
229  // -------------------------------------------------------------------------
231  // -------------------------------------------------------------------------
233 
241  USDSHADE_API
242  bool CanConnect(const UsdAttribute &source) const;
243 
245  USDSHADE_API
246  bool CanConnect(const UsdShadeInput &sourceInput) const;
247 
249  USDSHADE_API
250  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
251 
252  using ConnectionModification = UsdShadeConnectionModification;
253 
276  USDSHADE_API
277  bool ConnectToSource(
278  UsdShadeConnectionSourceInfo const &source,
279  ConnectionModification const mod =
280  ConnectionModification::Replace) const;
281 
284  USDSHADE_API
285  bool ConnectToSource(
286  UsdShadeConnectableAPI const &source,
287  TfToken const &sourceName,
288  UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output,
289  SdfValueTypeName typeName=SdfValueTypeName()) const;
290 
295  USDSHADE_API
296  bool ConnectToSource(SdfPath const &sourcePath) const;
297 
302  USDSHADE_API
303  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
304 
309  USDSHADE_API
310  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
311 
316  USDSHADE_API
317  bool SetConnectedSources(
318  std::vector<UsdShadeConnectionSourceInfo> const &sourceInfos) const;
319 
320  // XXX move to new header
321  using SourceInfoVector = TfSmallVector<UsdShadeConnectionSourceInfo, 1>;
322 
340  USDSHADE_API
341  SourceInfoVector GetConnectedSources(
342  SdfPathVector *invalidSourcePaths = nullptr) const;
343 
345  USDSHADE_API
347  TfToken *sourceName,
348  UsdShadeAttributeType *sourceType) const;
349 
355  USDSHADE_API
356  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
357 
363  USDSHADE_API
364  bool HasConnectedSource() const;
365 
372  USDSHADE_API
374 
381  USDSHADE_API
382  bool DisconnectSource(UsdAttribute const &sourceAttr = UsdAttribute()) const;
383 
391  USDSHADE_API
392  bool ClearSources() const;
393 
395  USDSHADE_API
396  bool ClearSource() const;
397 
399 
400  // -------------------------------------------------------------------------
402  // -------------------------------------------------------------------------
404 
408  USDSHADE_API
410  bool shaderOutputsOnly = false) const;
411 
413 
416  explicit operator bool() const {
417  return IsDefined();
418  }
419 
422  friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
423  return lhs.GetAttr() == rhs.GetAttr();
424  }
425 
428  friend bool operator!=(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
429  return !(lhs == rhs);
430  }
431 
432 private:
433  friend class UsdShadeConnectableAPI;
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 
446 PXR_NAMESPACE_CLOSE_SCOPE
447 
448 #endif // PXR_USD_USD_SHADE_OUTPUT_H
UsdAttribute GetAttr() const
Explicit UsdAttribute extractor.
Definition: output.h:213
USDSHADE_API SdfValueTypeName GetTypeName() const
Get the "scene description" value type name of the attribute associated with the output.
USDSHADE_API bool ClearSources() const
Clears sources for this Output in the current UsdEditTarget.
This is a small-vector class with local storage optimization, the local storage can be specified via ...
Definition: smallVector.h:177
UsdShadeOutput()
Default constructor returns an invalid Output.
Definition: output.h:52
USDSHADE_API bool CanConnect(const UsdAttribute &source) const
Determines whether this Output can be connected to the given source attribute, which can be an input ...
USDSHADE_API bool HasConnectedSource() const
Returns true if and only if this Output is currently connected to a valid (defined) source.
Represents a value type name, i.e.
Definition: valueTypeName.h:87
USDSHADE_API bool SetConnectedSources(std::vector< UsdShadeConnectionSourceInfo > const &sourceInfos) const
Connects this Output to the given sources, sourceInfos.
friend bool operator!=(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Inequality comparison.
Definition: output.h:428
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:176
static USDSHADE_API bool IsOutput(const UsdAttribute &attr)
Test whether a given UsdAttribute represents a valid Output, which implies that creating a UsdShadeOu...
USDSHADE_API void ClearSdrMetadata() const
Clears any "sdrMetadata" value authored on the Output in the current EditTarget.
This class encapsulates a shader or node-graph input, which is a connectable attribute representing a...
Definition: input.h:48
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
TfToken const & GetFullName() const
Get the name of the attribute associated with the output.
Definition: output.h:59
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
Specify an alternative, renderer-specific type to use when emitting/translating this output,...
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
Returns the value corresponding to key in the composed sdrMetadata dictionary.
bool IsDefined() const
Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an...
Definition: output.h:223
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and mak...
USDSHADE_API bool ClearSource() const
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
USDSHADE_API NdrTokenMap GetSdrMetadata() const
Returns this Output's composed "sdrMetadata" dictionary as a NdrTokenMap.
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set a value for the output.
USDSHADE_API void SetSdrMetadataByKey(const TfToken &key, const std::string &value) const
Sets the value corresponding to key to the given string value, in the Output's "sdrMetadata" dictiona...
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
Authors the given sdrMetadata value on this Output at the current EditTarget.
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
USDSHADE_API bool HasSdrMetadata() const
Returns true if the Output has a non-empty composed "sdrMetadata" dictionary value.
USDSHADE_API bool HasRenderType() const
Return true if a renderType has been specified for this output.
UsdPrim GetPrim() const
Get the prim that the output belongs to.
Definition: output.h:72
USDSHADE_API TfToken GetRenderType() const
Return this output's specialized renderType, or an empty token if none was authored.
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: output.h:96
USDSHADE_API SourceInfoVector GetConnectedSources(SdfPathVector *invalidSourcePaths=nullptr) const
Finds the valid sources of connections for the Output.
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:113
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:229
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
Returns true if there is a value corresponding to the given key in the composed "sdrMetadata" diction...
USDSHADE_API UsdShadeAttributeVector GetValueProducingAttributes(bool shaderOutputsOnly=false) const
Find what is connected to this Output recursively.
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
A compact struct to represent a bundle of information about an upstream source attribute.
This class encapsulates a shader or node-graph output, which is a connectable attribute representing ...
Definition: output.h:47
USDSHADE_API TfToken GetBaseName() const
Returns the name of the output.
USDSHADE_API bool DisconnectSource(UsdAttribute const &sourceAttr=UsdAttribute()) const
Disconnect source for this Output.
friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Equality comparison.
Definition: output.h:422
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
Clears the entry corresponding to the given key in the "sdrMetadata" dictionary authored in the curre...
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object's nearest owning prim.
Definition: prim.h:2180
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
Returns true if the connection to this Output's source, as returned by GetConnectedSource(),...
USDSHADE_API bool ConnectToSource(UsdShadeConnectionSourceInfo const &source, ConnectionModification const mod=ConnectionModification::Replace) const
Authors a connection for this Output.