HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nodeGraph.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 USDSHADE_GENERATED_NODEGRAPH_H
25 #define USDSHADE_GENERATED_NODEGRAPH_H
26 
27 /// \file usdShade/nodeGraph.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdShade/api.h"
31 #include "pxr/usd/usd/typed.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 
35 #include <utility>
36 #include "pxr/usd/usd/editTarget.h"
38 #include "pxr/usd/usdShade/input.h"
41 
42 #include "pxr/base/vt/value.h"
43 
44 #include "pxr/base/gf/vec3d.h"
45 #include "pxr/base/gf/vec3f.h"
46 #include "pxr/base/gf/matrix4d.h"
47 
48 #include "pxr/base/tf/token.h"
49 #include "pxr/base/tf/type.h"
50 
52 
53 class SdfAssetPath;
54 
55 // -------------------------------------------------------------------------- //
56 // NODEGRAPH //
57 // -------------------------------------------------------------------------- //
58 
59 /// \class UsdShadeNodeGraph
60 ///
61 /// A node-graph is a container for shading nodes, as well as other
62 /// node-graphs. It has a public input interface and provides a list of public
63 /// outputs.
64 ///
65 /// <b>Node Graph Interfaces</b>
66 ///
67 /// One of the most important functions of a node-graph is to host the "interface"
68 /// with which clients of already-built shading networks will interact. Please
69 /// see \ref UsdShadeNodeGraph_Interfaces "Interface Inputs" for a detailed
70 /// explanation of what the interface provides, and how to construct and
71 /// use it, to effectively share/instance shader networks.
72 ///
73 /// <b>Node Graph Outputs</b>
74 ///
75 /// These behave like outputs on a shader and are typically connected to an
76 /// output on a shader inside the node-graph.
77 ///
78 ///
80 {
81 public:
82  /// Compile time constant representing what kind of schema this class is.
83  ///
84  /// \sa UsdSchemaType
86 
87  /// Construct a UsdShadeNodeGraph on UsdPrim \p prim .
88  /// Equivalent to UsdShadeNodeGraph::Get(prim.GetStage(), prim.GetPath())
89  /// for a \em valid \p prim, but will not immediately throw an error for
90  /// an invalid \p prim
91  explicit UsdShadeNodeGraph(const UsdPrim& prim=UsdPrim())
92  : UsdTyped(prim)
93  {
94  }
95 
96  /// Construct a UsdShadeNodeGraph on the prim held by \p schemaObj .
97  /// Should be preferred over UsdShadeNodeGraph(schemaObj.GetPrim()),
98  /// as it preserves SchemaBase state.
99  explicit UsdShadeNodeGraph(const UsdSchemaBase& schemaObj)
100  : UsdTyped(schemaObj)
101  {
102  }
103 
104  /// Destructor.
106  virtual ~UsdShadeNodeGraph();
107 
108  /// Return a vector of names of all pre-declared attributes for this schema
109  /// class and all its ancestor classes. Does not include attributes that
110  /// may be authored by custom/extended methods of the schemas involved.
112  static const TfTokenVector &
113  GetSchemaAttributeNames(bool includeInherited=true);
114 
115  /// Return a UsdShadeNodeGraph holding the prim adhering to this
116  /// schema at \p path on \p stage. If no prim exists at \p path on
117  /// \p stage, or if the prim at that path does not adhere to this schema,
118  /// return an invalid schema object. This is shorthand for the following:
119  ///
120  /// \code
121  /// UsdShadeNodeGraph(stage->GetPrimAtPath(path));
122  /// \endcode
123  ///
125  static UsdShadeNodeGraph
126  Get(const UsdStagePtr &stage, const SdfPath &path);
127 
128  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
129  /// is defined (according to UsdPrim::IsDefined()) on this stage.
130  ///
131  /// If a prim adhering to this schema at \p path is already defined on this
132  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
133  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
134  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
135  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
136  /// current EditTarget for any nonexistent, or existing but not \a Defined
137  /// ancestors.
138  ///
139  /// The given \a path must be an absolute prim path that does not contain
140  /// any variant selections.
141  ///
142  /// If it is impossible to author any of the necessary PrimSpecs, (for
143  /// example, in case \a path cannot map to the current UsdEditTarget's
144  /// namespace) issue an error and return an invalid \a UsdPrim.
145  ///
146  /// Note that this method may return a defined prim whose typeName does not
147  /// specify this schema class, in case a stronger typeName opinion overrides
148  /// the opinion at the current EditTarget.
149  ///
151  static UsdShadeNodeGraph
152  Define(const UsdStagePtr &stage, const SdfPath &path);
153 
154 protected:
155  /// Returns the type of schema this class belongs to.
156  ///
157  /// \sa UsdSchemaType
159  UsdSchemaType _GetSchemaType() const override;
160 
161 private:
162  // needs to invoke _GetStaticTfType.
163  friend class UsdSchemaRegistry;
165  static const TfType &_GetStaticTfType();
166 
167  static bool _IsTypedSchema();
168 
169  // override SchemaBase virtuals.
171  const TfType &_GetTfType() const override;
172 
173 public:
174  // ===================================================================== //
175  // Feel free to add custom code below this line, it will be preserved by
176  // the code generator.
177  //
178  // Just remember to:
179  // - Close the class declaration with };
180  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
181  // - Close the include guard with #endif
182  // ===================================================================== //
183  // --(BEGIN CUSTOM CODE)--
184 
185  /// Constructor that takes a ConnectableAPI object.
186  /// Allow implicit (auto) conversion of UsdShadeNodeGraph to
187  /// UsdShadeConnectableAPI, so that a NodeGraph can be passed into any
188  /// function that accepts a ConnectableAPI.
190  UsdShadeNodeGraph(const UsdShadeConnectableAPI &connectable);
191 
192  /// Contructs and returns a UsdShadeConnectableAPI object with this
193  /// node-graph.
194  ///
195  /// Note that most tasks can be accomplished without explicitly constructing
196  /// a UsdShadeConnectable API, since connection-related API such as
197  /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and
198  /// UsdShadeNodeGraph will auto-convert to a UsdShadeConnectableAPI when
199  /// passed to functions that want to act generically on a connectable
200  /// UsdShadeConnectableAPI object.
203 
204  /// \anchor UsdShadeNodeGraph_Output
205  /// \name Outputs of a node-graph. These typically connect to outputs of
206  /// shaders or nested node-graphs within the node-graph.
207  ///
208  /// @{
209 
210  /// Create an output which can either have a value or can be connected.
211  /// The attribute representing the output is created in the "outputs:"
212  /// namespace.
213  ///
216  const SdfValueTypeName& typeName) const;
217 
218  /// Return the requested output if it exists.
219  ///
221  UsdShadeOutput GetOutput(const TfToken &name) const;
222 
223  /// Outputs are represented by attributes in the "outputs:" namespace.
224  ///
226  std::vector<UsdShadeOutput> GetOutputs() const;
227 
228  /// Resolves the connection source of the requested output, identified by
229  /// \p outputName to a shader output.
230  ///
231  /// \p sourceName is an output parameter that is set to the name of the
232  /// resolved output, if the node-graph output is connected to a valid
233  /// shader source.
234  ///
235  /// \p sourceType is an output parameter that is set to the type of the
236  /// resolved output, if the node-graph output is connected to a valid
237  /// shader source.
238  ///
239  /// \return Returns a valid shader object if the specified output exists and
240  /// is connected to one. Return an empty shader object otherwise.
241  /// The python version of this method returns a tuple containing three
242  /// elements (the source shader, sourceName, sourceType).
245  const TfToken &outputName,
246  TfToken *sourceName,
247  UsdShadeAttributeType *sourceType) const;
248 
249  /// @}
250 
251  /// \anchor UsdShadeNodeGraph_Interfaces
252  /// \name Interface inputs of a node-graph.
253  ///
254  /// In addition to serving as the "head" for all of the shading networks
255  /// that describe each render target's particular node-graph, the node-graph
256  /// prim provides a unified "interface" that allows node-graphs to share
257  /// shading networks while retaining the ability for each to specify its own
258  /// set of unique values for the interface inputs that users may need to
259  /// modify.
260  ///
261  /// A "Node-graph Interface" is a combination of:
262  /// \li a flat collection of attributes, of arbitrary names
263  /// \li for each such attribute, a list of UsdShaderInput targets
264  /// whose attributes on Shader prims should be driven by the interface
265  /// input.
266  ///
267  /// A single interface input can drive multiple shader inputs and be
268  /// consumed by multiple render targets. The set of interface inputs itself
269  /// is intentionally flat, to encourage sharing of the interface between
270  /// render targets. Clients are always free to create interface inputs with
271  /// namespacing to segregate "private" attributes exclusive to the render
272  /// target, but we hope this will be an exception.
273  ///
274  /// To facilitate connecting, qualifying, and interrogating interface
275  /// attributes, we use the attribute schema UsdShadeInput, which also
276  /// serves as an abstraction for shader inputs.
277  ///
278  /// <b>Scoped Interfaces</b>
279  ///
280  /// \todo describe scoped interfaces and fix bug/108940 to account for them.
281  ///
282  /// @{
283 
284  /// Create an Input which can either have a value or can be connected.
285  /// The attribute representing the input is created in the "inputs:"
286  /// namespace.
287  ///
288  /// \todo clarify error behavior if typeName does not match existing,
289  /// defined attribute - should match UsdPrim::CreateAttribute - bug/108970
290  ///
293  const SdfValueTypeName& typeName) const;
294 
295  /// Return the requested input if it exists.
296  ///
298  UsdShadeInput GetInput(const TfToken &name) const;
299 
300  /// Returns all inputs present on the node-graph. These are represented by
301  /// attributes in the "inputs:" namespace.
302  ///
304  std::vector<UsdShadeInput> GetInputs() const;
305 
306  /// @}
307 
308  // Provide custom hash and equality comparison function objects for
309  // UsdShadeNodeGraph until bug 143077 is resolved.
310 
311  /// Hash functor for UsdShadeNodeGraph objects.
313  inline size_t operator()(const UsdShadeNodeGraph &nodeGraph) const {
314  return hash_value(nodeGraph.GetPrim());
315  }
316  };
317  /// Equality comparator for UsdShadeNodeGraph objects.
319  {
320  inline bool operator() (UsdShadeNodeGraph const& s1,
321  UsdShadeNodeGraph const& s2) const
322  {
323  return s1.GetPrim() == s2.GetPrim();
324  }
325  };
326 
327  // ---------------------------------------------------------------------- //
328  /// \anchor UsdShadeNodeGraph_InterfaceInputs
329  /// \name Interface Inputs
330  ///
331  /// API to query the inputs that form the interface of the node-graph and
332  /// their connections.
333  ///
334  /// @{
335 
336  /// Returns all the "Interface Inputs" of the node-graph. This is the same
337  /// as GetInputs(), but is provided as a convenience, to allow clients to
338  /// distinguish between inputs on shaders vs. interface-inputs on
339  /// node-graphs.
341  std::vector<UsdShadeInput> GetInterfaceInputs() const;
342 
343  /// Map of interface inputs to corresponding vectors of inputs that
344  /// consume their values.
345  typedef std::unordered_map<UsdShadeInput, std::vector<UsdShadeInput>,
347 
348  /// Map of node-graphs to their associated input-consumers map.
349  typedef std::unordered_map<UsdShadeNodeGraph,
354 
355  /// Walks the namespace subtree below the node-graph and computes a map
356  /// containing the list of all inputs on the node-graph and the associated
357  /// vector of consumers of their values. The consumers can be inputs on
358  /// shaders within the node-graph or on nested node-graphs).
359  ///
360  /// If \p computeTransitiveConsumers is true, then value consumers
361  /// belonging to <b>node-graphs</b> are resolved transitively to compute the
362  /// transitive mapping from inputs on the node-graph to inputs on shaders
363  /// inside the material. Note that inputs on node-graphs that don't have
364  /// value consumers will continue to be included in the result.
365  ///
366  /// This API is provided for use by DCC's that want to present node-graph
367  /// interface / shader connections in the opposite direction than they are
368  /// encoded in USD.
369  ///
372  bool computeTransitiveConsumers=false) const;
373 
374  /// @}
375 
376 };
377 
379 
380 #endif
#define USDSHADE_API
Definition: api.h:40
Hash functor.
Definition: input.h:106
virtual USDSHADE_API ~UsdShadeNodeGraph()
Destructor.
std::unordered_map< UsdShadeInput, std::vector< UsdShadeInput >, UsdShadeInput::Hash > InterfaceInputConsumersMap
Definition: nodeGraph.h:346
USDSHADE_API UsdShadeShader ComputeOutputSource(const TfToken &outputName, TfToken *sourceName, UsdShadeAttributeType *sourceType) const
GLuint const GLchar * name
Definition: glew.h:1814
std::unordered_map< UsdShadeNodeGraph, InterfaceInputConsumersMap, NodeGraphHasher, NodeGraphEqualFn > NodeGraphInputConsumersMap
Map of node-graphs to their associated input-consumers map.
Definition: nodeGraph.h:353
bool operator()(UsdShadeNodeGraph const &s1, UsdShadeNodeGraph const &s2) const
Definition: nodeGraph.h:320
USDSHADE_API UsdShadeConnectableAPI ConnectableAPI() const
Represents a concrete typed schema.
UsdShadeNodeGraph(const UsdPrim &prim=UsdPrim())
Definition: nodeGraph.h:91
static USDSHADE_API UsdShadeNodeGraph Get(const UsdStagePtr &stage, const SdfPath &path)
Definition: token.h:87
USDSHADE_API std::vector< UsdShadeInput > GetInterfaceInputs() const
UsdShadeNodeGraph(const UsdSchemaBase &schemaObj)
Definition: nodeGraph.h:99
static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
static const UsdSchemaType schemaType
Definition: nodeGraph.h:85
UsdSchemaType
Definition: common.h:127
USDSHADE_API UsdSchemaType _GetSchemaType() const override
Definition: prim.h:132
Definition: typed.h:47
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
USDSHADE_API std::vector< UsdShadeOutput > GetOutputs() const
Definition: path.h:288
USDSHADE_API UsdShadeOutput GetOutput(const TfToken &name) const
size_t operator()(const UsdShadeNodeGraph &nodeGraph) const
Definition: nodeGraph.h:313
GLsizei const GLchar *const * path
Definition: glew.h:6461
Hash functor for UsdShadeNodeGraph objects.
Definition: nodeGraph.h:312
UsdShadeAttributeType
Definition: utils.h:42
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
GLuint GLfloat GLfloat GLfloat GLfloat GLfloat GLfloat GLfloat GLfloat s1
Definition: glew.h:12681
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDSHADE_API UsdShadeOutput CreateOutput(const TfToken &name, const SdfValueTypeName &typeName) const
static USDSHADE_API UsdShadeNodeGraph Define(const UsdStagePtr &stage, const SdfPath &path)
Definition: type.h:64
USDSHADE_API UsdShadeInput CreateInput(const TfToken &name, const SdfValueTypeName &typeName) const
USDSHADE_API UsdShadeInput GetInput(const TfToken &name) const
size_t hash_value(const CH_ChannelRef &ref)
USDSHADE_API InterfaceInputConsumersMap ComputeInterfaceInputConsumersMap(bool computeTransitiveConsumers=false) const
Equality comparator for UsdShadeNodeGraph objects.
Definition: nodeGraph.h:318
UsdPrim GetPrim() const
Return this schema object's held prim.
Definition: schemaBase.h:119
USDSHADE_API std::vector< UsdShadeInput > GetInputs() const