All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 USDSHADE_OUTPUT_H
25 #define USDSHADE_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/usd/property.h"
31 #include "pxr/usd/usd/relationship.h"
32 #include "pxr/usd/ndr/declare.h"
33 #include "pxr/usd/usdShade/utils.h"
34 
35 #include <vector>
36 
37 PXR_NAMESPACE_OPEN_SCOPE
38 
40 class UsdShadeInput;
41 
48 {
49 public:
53  {
54  // nothing
55  }
56 
62  TfToken const &GetFullName() const {
63  return _prop.GetName();
64  }
65 
74  USDSHADE_API
75  TfToken GetBaseName() const;
76 
78  UsdPrim GetPrim() const {
79  return _prop.GetPrim();
80  }
81 
88  USDSHADE_API
90 
97  USDSHADE_API
98  bool Set(const VtValue& value,
99  UsdTimeCode time = UsdTimeCode::Default()) const;
100 
104  template <typename T>
105  bool Set(const T& value, UsdTimeCode time = UsdTimeCode::Default()) const {
106  if (UsdAttribute attr = GetAttr()) {
107  return attr.Set(value, time);
108  }
109  return false;
110  }
111 
114 
123  USDSHADE_API
124  bool SetRenderType(TfToken const& renderType) const;
125 
130  USDSHADE_API
131  TfToken GetRenderType() const;
132 
137  USDSHADE_API
138  bool HasRenderType() const;
139 
141 
156 
159  USDSHADE_API
160  NdrTokenMap GetSdrMetadata() const;
161 
164  USDSHADE_API
165  std::string GetSdrMetadataByKey(const TfToken &key) const;
166 
169  USDSHADE_API
170  void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const;
171 
174  USDSHADE_API
175  void SetSdrMetadataByKey(
176  const TfToken &key,
177  const std::string &value) const;
178 
181  USDSHADE_API
182  bool HasSdrMetadata() const;
183 
186  USDSHADE_API
187  bool HasSdrMetadataByKey(const TfToken &key) const;
188 
191  USDSHADE_API
192  void ClearSdrMetadata() const;
193 
196  USDSHADE_API
197  void ClearSdrMetadataByKey(const TfToken &key) const;
198 
200 
201  // ---------------------------------------------------------------
203  // ---------------------------------------------------------------
204 
206 
211  USDSHADE_API
212  explicit UsdShadeOutput(const UsdAttribute &attr);
213 
218  USDSHADE_API
219  static bool IsOutput(const UsdAttribute &attr);
220 
222  UsdAttribute GetAttr() const { return _prop.As<UsdAttribute>(); }
223 
225  const UsdProperty &GetProperty() const { return _prop; }
226 
230  operator UsdAttribute () const { return GetAttr(); }
231 
235  operator const UsdProperty & () const { return GetProperty(); }
236 
238  UsdRelationship GetRel() const { return _prop.As<UsdRelationship>(); }
239 
243  bool IsTerminal() const {
244  return static_cast<bool>(GetRel());
245  }
246 
252  bool IsDefined() const {
253  if (UsdAttribute attr = GetAttr()) {
254  return IsOutput(attr);
255  }
256  return IsTerminal();
257  }
258 
260 
261  // -------------------------------------------------------------------------
263  // -------------------------------------------------------------------------
265 
273  USDSHADE_API
274  bool CanConnect(const UsdAttribute &source) const;
275 
277  USDSHADE_API
278  bool CanConnect(const UsdShadeInput &sourceInput) const;
279 
281  USDSHADE_API
282  bool CanConnect(const UsdShadeOutput &sourceOutput) const;
283 
296  USDSHADE_API
297  bool ConnectToSource(
298  UsdShadeConnectableAPI const &source,
299  TfToken const &sourceName,
300  UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output,
301  SdfValueTypeName typeName=SdfValueTypeName()) const;
302 
307  USDSHADE_API
308  bool ConnectToSource(SdfPath const &sourcePath) const;
309 
314  USDSHADE_API
315  bool ConnectToSource(UsdShadeInput const &sourceInput) const;
316 
321  USDSHADE_API
322  bool ConnectToSource(UsdShadeOutput const &sourceOutput) const;
323 
345  USDSHADE_API
347  TfToken *sourceName,
348  UsdShadeAttributeType *sourceType) const;
349 
354  USDSHADE_API
355  bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const;
356 
362  USDSHADE_API
363  bool HasConnectedSource() const;
364 
371  USDSHADE_API
373 
378  USDSHADE_API
379  bool DisconnectSource() const;
380 
388  USDSHADE_API
389  bool ClearSource() const;
390 
392 
395  explicit operator bool() const {
396  return IsDefined();
397  }
398 
401  friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs) {
402  return lhs.GetProperty() == rhs.GetProperty();
403  }
404 
405 private:
406  friend class UsdShadeConnectableAPI;
407 
408  // Befriend UsdRiMaterialAPI which will provide a backwards compatible
409  // interface for managing terminal relationships, which turn into outputs
410  // in the new encoding of shading networks.
411  // This is temporary to assist in the transition to the new shading
412  // encoding.
413  friend class UsdRiMaterialAPI;
414 
415  // Constructor that creates a UsdShadeOutput with the given name on the
416  // given prim.
417  // \p name here is the unnamespaced name of the output.
418  UsdShadeOutput(UsdPrim prim,
419  TfToken const &name,
420  SdfValueTypeName const &typeName);
421 
422  // Speculative constructor that will produce a valid UsdShadeOutput when
423  // \p rel represents a terminal relationship on a material, a concept that
424  // has been retired in favor of outputs represented as (attribute,
425  // relationship) pair.
426  //
427  // Outputs wrapping a terminal relationship are always considered valid
428  // as long as the relationship is defined and valid.
429  //
430  // This exists only to allow higher level API to be backwards compatible
431  // and treat terminals and outputs uniformly.
432  //
433  USDSHADE_API
434  explicit UsdShadeOutput(const UsdRelationship &rel);
435 
436  // Constructor that wraps the given shading property in a UsdShadeOutput
437  // object.
438  explicit UsdShadeOutput(const UsdProperty &prop);
439 
440  // This is currently a relationship if the output belongs to a node-graph.
441  // In the future, all outputs will have associated attributes and we
442  // can switch this to be a UsdAttribute instead of UsdProperty.
443  UsdProperty _prop;
444 };
445 
446 
447 PXR_NAMESPACE_CLOSE_SCOPE
448 
449 #endif // USDSHADE_OUTPUT_H
USDSHADE_API bool GetRawConnectedSourcePaths(SdfPathVector *sourcePaths) const
Returns the &quot;raw&quot; (authored) connected source paths for this Output.
USDSHADE_API bool HasConnectedSource() const
Returns true if and only if this Output is currently connected to a valid (defined) source...
USDSHADE_API bool HasRenderType() const
Return true if a renderType has been specified for this output.
T As() const
Convert this UsdObject to another object type T if possible.
Definition: object.h:236
USDSHADE_API bool GetConnectedSource(UsdShadeConnectableAPI *source, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
Finds the source of a connection for this Output.
UsdShadeOutput()
Default constructor returns an invalid Output.
Definition: output.h:52
USDSHADE_API bool SetRenderType(TfToken const &renderType) const
Specify an alternative, renderer-specific type to use when emitting/translating this output...
UsdAttribute GetAttr() const
Explicit UsdAttribute extractor.
Definition: output.h:222
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&#39;s &quot;sdrMetadata&quot; dictiona...
Represents a value type name, i.e.
Definition: valueTypeName.h:83
const UsdProperty & GetProperty() const
Explicit UsdProperty extractor.
Definition: output.h:225
bool IsTerminal() const
Returns whether the Output represents a terminal relationship on a material, which is a concept we&#39;d ...
Definition: output.h:243
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
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...
bool IsDefined() const
Return true if the wrapped UsdAttribute is defined, and in addition the attribute is identified as an...
Definition: output.h:252
USDSHADE_API bool IsSourceConnectionFromBaseMaterial() const
Returns true if the connection to this Output&#39;s source, as returned by GetConnectedSource(), is authored across a specializes arc, which is used to denote a base material.
This class encapsulates a shader or node-graph input, which is a connectable property representing a ...
Definition: input.h:46
USDSHADE_API bool Set(const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set a value for the output.
USDSHADE_API void SetSdrMetadata(const NdrTokenMap &sdrMetadata) const
Authors the given sdrMetadata value on this Output at the current EditTarget.
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 ...
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:89
USDSHADE_API bool DisconnectSource() const
Disconnect source for this Output.
USDSHADE_API std::string GetSdrMetadataByKey(const TfToken &key) const
Returns the value corresponding to key in the composed sdrMetadata dictionary.
USDSHADE_API bool ConnectToSource(UsdShadeConnectableAPI const &source, TfToken const &sourceName, UsdShadeAttributeType const sourceType=UsdShadeAttributeType::Output, SdfValueTypeName typeName=SdfValueTypeName()) const
Authors a connection for this Output to the source described by the following three elements: source...
USDSHADE_API TfToken GetRenderType() const
Return this output&#39;s specialized renderType, or an empty token if none was authored.
USDSHADE_API void ClearSdrMetadata() const
Clears any &quot;sdrMetadata&quot; value authored on the Output in the current EditTarget.
USDSHADE_API bool HasSdrMetadata() const
Returns true if the Output has a non-empty composed &quot;sdrMetadata&quot; dictionary value.
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:85
USDSHADE_API SdfValueTypeName GetTypeName() const
Get the &quot;scene description&quot; value type name of the attribute associated with the output.
UsdPrim GetPrim() const
Return this object if it is a prim, otherwise return this object&#39;s nearest owning prim...
Definition: prim.h:1644
UsdShadeConnectableAPI is an API schema that provides a common interface for creating outputs and mak...
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:105
USDSHADE_API bool HasSdrMetadataByKey(const TfToken &key) const
Returns true if there is a value corresponding to the given key in the composed &quot;sdrMetadata&quot; diction...
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a &quot;Prim&quot; as ...
Definition: prim.h:131
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:287
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
USDSHADE_API void ClearSdrMetadataByKey(const TfToken &key) const
Clears the entry corresponding to the given key in the &quot;sdrMetadata&quot; dictionary authored in the curre...
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:55
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for &#39;default&#39;.
Definition: timeCode.h:113
UsdPrim GetPrim() const
Get the prim that the output belongs to.
Definition: output.h:78
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:228
USDSHADE_API NdrTokenMap GetSdrMetadata() const
Returns this Output&#39;s composed &quot;sdrMetadata&quot; dictionary as a NdrTokenMap.
This class encapsulates a shader or node-graph output, which is a connectable property representing a...
Definition: output.h:47
friend bool operator==(const UsdShadeOutput &lhs, const UsdShadeOutput &rhs)
Equality comparison.
Definition: output.h:401
This API provides outputs that connect a material prim to prman shaders and RIS objects.
Definition: materialAPI.h:68
UsdRelationship GetRel() const
Explicit UsdRelationship extractor.
Definition: output.h:238
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:182
TfToken const & GetFullName() const
Get the name of the attribute associated with the output.
Definition: output.h:62
USDSHADE_API bool ClearSource() const
Clears source for this shading property in the current UsdEditTarget.
USDSHADE_API TfToken GetBaseName() const
Returns the name of the output.