HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
connectableAPIBehavior.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 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_CONNECTABLE_BEHAVIOR_H
25 #define PXR_USD_USD_SHADE_CONNECTABLE_BEHAVIOR_H
26 
27 /// \file usdShade/connectableAPIBehavior.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdShade/api.h"
31 
32 #include "pxr/base/gf/vec3f.h"
33 #include "pxr/base/vt/array.h"
34 
35 #include "pxr/base/tf/type.h"
36 
38 
39 class UsdAttribute;
40 class UsdShadeInput;
41 class UsdShadeOutput;
42 
43 /// UsdShadeConnectableAPIBehavior defines the compatibilty and behavior
44 /// UsdShadeConnectableAPIof when applied to a particular prim type.
45 ///
46 /// This enables schema libraries to enable UsdShadeConnectableAPI for
47 /// their prim types and define its behavior.
49 {
50 public:
51 
52  /// An enum describing the types of connectable nodes which will govern what
53  /// connectibility rule is invoked for these.
55  {
56  BasicNodes, // Shader, NodeGraph
57  DerivedContainerNodes, // Material, etc
58  };
59 
60  // By default we want a connectableBehavior to not exhibit a container like
61  // behavior. And we want encapsulation behavior enabled by default.
64  : _isContainer(false), _requiresEncapsulation(true) {}
65 
67  UsdShadeConnectableAPIBehavior(const bool isContainer,
68  const bool requiresEncapsulation)
69  : _isContainer(isContainer),
70  _requiresEncapsulation(requiresEncapsulation) {}
71 
74 
75  /// The prim owning the input is guaranteed to be of the type this
76  /// behavior was registered with. The function must be thread-safe.
77  ///
78  /// It should return true if the connection is allowed, false
79  /// otherwise. If the connection is prohibited and \p reason is
80  /// non-NULL, it should be set to a user-facing description of the
81  /// reason the connection is prohibited.
82  ///
83  /// The base implementation checks that the input is defined; that
84  /// the source attribute exists; and that the connectability metadata
85  /// on the input allows a connection from the attribute -- see
86  /// UsdShadeInput::GetConnectability().
87  ///
89  virtual bool
91  const UsdAttribute &,
92  std::string *reason) const;
93 
94  /// The prim owning the output is guaranteed to be of the type this
95  /// behavior was registered with. The function must be thread-safe.
96  ///
97  /// It should return true if the connection is allowed, false
98  /// otherwise. If the connection is prohibited and \p reason is
99  /// non-NULL, it should be set to a user-facing description of the
100  /// reason the connection is prohibited.
101  ///
102  /// The base implementation returns false. Outputs of most prim
103  /// types will be defined by the underlying node definition (see
104  /// UsdShadeNodeDefAPI), not a connection.
105  ///
107  virtual bool
109  const UsdAttribute &,
110  std::string *reason) const;
111 
112  /// The function must be thread-safe.
113  ///
114  /// It should return true if the associated prim type is considered
115  /// a "container" for connected nodes.
116  /// Returns the value set for _isContainer.
118  virtual bool
119  IsContainer() const final;
120 
121  /// The function must be thread-safe.
122  ///
123  /// Determines if the behavior should respect container encapsulation rules
124  /// (\ref UsdShadeConnectability), when evaluating CanConnectInputToSource
125  /// or CanConnectOutputToSource. This should return true if the container
126  /// encapsulation rules need to be respected, false otherwise.
127  //
128  /// Returns the value set for _requiresEncapsulation.
129  ///
130  /// \sa IsContainer()
131  ///
133  virtual bool
134  RequiresEncapsulation() const final;
135 
136 protected:
137  /// Helper function to separate and share special connectivity logic for
138  /// specialized, NodeGraph-derived nodes, like Material (and other in other
139  /// domains) that allow their inputs to be connected to an output of a
140  /// source that they directly contain/encapsulate. The default behavior is
141  /// for Shader Nodes or NodeGraphs which allow their input connections to
142  /// output of a sibling source, both encapsulated by the same container
143  /// node.
146  std::string *reason,
147  ConnectableNodeTypes nodeType =
149 
151  bool _CanConnectOutputToSource(const UsdShadeOutput&, const UsdAttribute&,
152  std::string *reason,
153  ConnectableNodeTypes nodeType =
155 private:
156  bool _isContainer;
157  bool _requiresEncapsulation;
158 };
159 
160 /// Registers \p behavior to define connectability of attributes for \p PrimType.
161 ///
162 /// Plugins should call this function in a TF_REGISTRY_FUNCTION. For example:
163 ///
164 /// \code
165 /// class MyBehavior : public UsdShadeConnectableAPIBehavior { ... }
166 ///
167 /// TF_REGISTRY_FUNCTION(UsdShadeConnectableAPI)
168 /// {
169 /// UsdShadeRegisterConnectableAPIBehavior<MyPrim, MyBehavior>();
170 /// }
171 /// \endcode
172 ///
173 /// Plugins must also note that UsdShadeConnectableAPI behavior is implemented
174 /// for a prim type in that type's schema definnition. For example:
175 ///
176 /// \code
177 /// class "MyPrim" (
178 /// ...
179 /// customData = {
180 /// dictionary extraPlugInfo = {
181 /// bool providesUsdShadeConnectableAPIBehavior = true
182 /// }
183 /// }
184 /// ...
185 /// )
186 /// { ... }
187 /// \endcode
188 ///
189 /// This allows the plugin system to discover this behavior dynamically
190 /// and load the plugin if needed.
191 ///
192 /// In addition to Typed schemas, single apply API schemas can also include
193 /// **providesUsdShadeConnectableAPIBehavior** in their **extraPlugInfo** and
194 /// hence impart connectableAPIBehavior to the prim definition in which they
195 /// are participating. Additionally a schema can include metadata in their
196 /// extraPlugInfo fields to override isContainer and requiresEncapsulation
197 /// properties by specifying bool values for **isUsdShadeContainer** and
198 /// **requiresUsdShadeEncapsulation**. This can be especially useful for
199 /// \ref codeless_schema that cannot provide a C++ derivation of
200 /// UsdShadeConnectableAPIBehavior.
201 ///
202 /// \ref UsdShadeConnectableAPIBehavior_ResolutionOrder defines the
203 /// resolution order when multiple types and apiSchemas provide a
204 /// UsdShadeConnectableAPIBehavior.
205 ///
206 template <class PrimType, class BehaviorType = UsdShadeConnectableAPIBehavior>
207 inline void
209 {
211  TfType::Find<PrimType>(),
212  std::shared_ptr<UsdShadeConnectableAPIBehavior>(new BehaviorType));
213 }
214 
215 /// Registers \p behavior to define connectability of attributes for
216 /// \p PrimType.
218 void
220  const TfType& connectablePrimType,
221  const std::shared_ptr<UsdShadeConnectableAPIBehavior>& behavior);
222 
224 
225 #endif // PXR_USD_USD_SHADE_CONNECTABLE_BEHAVIOR_H
void UsdShadeRegisterConnectableAPIBehavior()
#define USDSHADE_API
Definition: api.h:40
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:623
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDSHADE_API bool _CanConnectInputToSource(const UsdShadeInput &, const UsdAttribute &, std::string *reason, ConnectableNodeTypes nodeType=ConnectableNodeTypes::BasicNodes) const
virtual USDSHADE_API bool CanConnectInputToSource(const UsdShadeInput &, const UsdAttribute &, std::string *reason) const
virtual USDSHADE_API bool RequiresEncapsulation() const final
virtual USDSHADE_API bool CanConnectOutputToSource(const UsdShadeOutput &, const UsdAttribute &, std::string *reason) const
virtual USDSHADE_API ~UsdShadeConnectableAPIBehavior()
USDSHADE_API bool _CanConnectOutputToSource(const UsdShadeOutput &, const UsdAttribute &, std::string *reason, ConnectableNodeTypes nodeType=ConnectableNodeTypes::BasicNodes) const
virtual USDSHADE_API bool IsContainer() const final
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
USDSHADE_API UsdShadeConnectableAPIBehavior(const bool isContainer, const bool requiresEncapsulation)