HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
node.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_PCP_NODE_H
25 #define PXR_USD_PCP_NODE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/pcp/api.h"
29 #include "pxr/usd/pcp/types.h"
30 #include "pxr/usd/sdf/types.h"
31 #include "pxr/base/tf/iterator.h"
32 #include "pxr/base/tf/hashset.h"
33 
34 #include <hboost/operators.hpp>
35 #include <hboost/iterator/iterator_facade.hpp>
36 #include <hboost/iterator/reverse_iterator.hpp>
37 
39 
40 class PcpArc;
41 class PcpLayerStackSite;
42 class PcpMapExpression;
43 class PcpNodeRef;
46 
47 TF_DECLARE_WEAK_PTRS(PcpPrimIndex_Graph);
48 
49 /// \class PcpNodeRef
50 ///
51 /// PcpNode represents a node in an expression tree for compositing
52 /// scene description.
53 ///
54 /// A node represents the opinions from a particular site. In addition,
55 /// it may have child nodes, representing nested expressions that are
56 /// composited over/under this node.
57 ///
58 /// Child nodes are stored and composited in strength order.
59 ///
60 /// Each node holds information about the arc to its parent.
61 /// This captures both the relative strength of the sub-expression
62 /// as well as any value-mapping needed, such as to rename opinions
63 /// from a model to use in a particular instance.
64 ///
65 class PcpNodeRef :
66  public hboost::totally_ordered<PcpNodeRef>
67 {
68 public:
71  typedef std::pair<child_const_iterator,
73 
74  PcpNodeRef() : _graph(0), _nodeIdx(PCP_INVALID_INDEX) {}
75 
76  /// \name Operators / Miscellaneous
77  /// @{
78 
79  /// Returns true if this is a valid node reference, false otherwise.
80  typedef size_t PcpNodeRef::*UnspecifiedBoolType;
81  inline operator UnspecifiedBoolType() const {
82  return (_graph && _nodeIdx != PCP_INVALID_INDEX) ? &PcpNodeRef::_nodeIdx : 0;
83  }
84 
85  /// Returns true if this references the same node as \p rhs.
86  inline bool operator==(const PcpNodeRef& rhs) const {
87  return _nodeIdx == rhs._nodeIdx && _graph == rhs._graph;
88  }
89 
90  /// Returns true if this node is 'less' than \p rhs.
91  /// The ordering of nodes is arbitrary and does not indicate the relative
92  /// strength of the nodes.
93  PCP_API
94  bool operator<(const PcpNodeRef& rhs) const;
95 
96  /// Hash functor.
97  struct Hash {
98  size_t operator()(const PcpNodeRef& rhs) const
99  { return (size_t)rhs.GetUniqueIdentifier(); }
100  };
101 
102  /// Returns the graph that this node belongs to.
103  PcpPrimIndex_GraphPtr GetOwningGraph() const;
104 
105  /// Returns a value that uniquely identifies this node.
106  PCP_API
107  void* GetUniqueIdentifier() const;
108 
109  /// @}
110 
111  /// \name Arc information
112  /// Information pertaining to the arcs connecting this node to its
113  /// parent and child nodes.
114  /// @{
115 
116  /// Returns the type of arc connecting this node to its parent node.
117  PCP_API
118  PcpArcType GetArcType() const;
119 
120  /// Returns this node's immediate parent node. Will return NULL if this
121  /// node is a root node.
122  PCP_API
123  PcpNodeRef GetParentNode() const;
124 
125  /// Returns an iterator range over the children nodes in strongest to
126  /// weakest order.
127  PCP_API
129 
130  /// Inserts a new child node for \p site, connected to this node via
131  /// \p arc.
132  PCP_API
133  PcpNodeRef InsertChild(const PcpLayerStackSite& site, const PcpArc& arc);
134 
135  /// Inserts \p subgraph as a child of this node, with the root node of
136  /// \p subtree connected to this node via \p arc.
137  PCP_API
139  const PcpPrimIndex_GraphPtr& subgraph, const PcpArc& arc);
140 
141  /// Returns the immediate origin node for this node. The origin node
142  /// is the node that caused this node to be brought into the prim index.
143  /// In most cases, this is the same as the parent node. For implied
144  /// inherits, the origin is the node from which this node was propagated.
145  PCP_API
146  PcpNodeRef GetOriginNode() const;
147 
148  /// Walk up to the root origin node for this node. This is the very
149  /// first node that caused this node to be added to the graph. For
150  /// instance, the root origin node of an implied inherit is the
151  /// original inherit node.
152  PCP_API
154 
155  /// Walk up to the root node of this expression.
156  PCP_API
157  PcpNodeRef GetRootNode() const;
158 
159  /// Returns mapping function used to translate paths and values from
160  /// this node to its parent node.
161  PCP_API
162  const PcpMapExpression& GetMapToParent() const;
163 
164  /// Returns mapping function used to translate paths and values from
165  /// this node directly to the root node.
166  PCP_API
167  const PcpMapExpression& GetMapToRoot() const;
168 
169  /// Returns this node's index among siblings with the same arc type
170  /// at this node's origin.
171  PCP_API
172  int GetSiblingNumAtOrigin() const;
173 
174  /// Returns the absolute namespace depth of the node that introduced
175  /// this node. Note that this does *not* count any variant selections.
176  PCP_API
177  int GetNamespaceDepth() const;
178 
179  /// Return the number of levels of namespace this node's site is
180  /// below the level at which it was introduced by an arc.
181  PCP_API
182  int GetDepthBelowIntroduction() const;
183 
184  /// Returns the path for this node's site when it was introduced.
185  PCP_API
187 
188  /// Get the path that introduced this node.
189  /// Specifically, this is the path the parent node had at the level
190  /// of namespace where this node was added as a child.
191  /// For a root node, this returns the absolute root path.
192  /// See also GetDepthBelowIntroduction().
193  PCP_API
194  SdfPath GetIntroPath() const;
195 
196  /// @}
197 
198  /// \name Node information
199  /// Information pertaining specifically to this node and the opinions
200  /// that it may or may not provide.
201  /// @{
202 
203  /// Get the site this node represents.
204  PCP_API
205  PcpLayerStackSite GetSite() const;
206 
207  /// Returns the path for the site this node represents.
208  PCP_API
209  const SdfPath& GetPath() const;
210 
211  /// Returns the layer stack for the site this node represents.
212  PCP_API
213  const PcpLayerStackRefPtr& GetLayerStack() const;
214 
215  /// Returns true if this node is the root node of the prim index graph.
216  PCP_API
217  bool IsRootNode() const;
218 
219  /// Returns true if this node is due to an ancestral opinion.
220  PCP_API
221  bool IsDueToAncestor() const;
222 
223  /// Get/set whether this node provides any symmetry opinions, either
224  /// directly or from a namespace ancestor.
225  PCP_API
226  void SetHasSymmetry(bool hasSymmetry);
227  PCP_API
228  bool HasSymmetry() const;
229 
230  /// Get/set the permission for this node. This indicates whether specs
231  /// on this node can be accessed from other nodes.
232  PCP_API
233  void SetPermission(SdfPermission perm);
234  PCP_API
236 
237  /// Get/set whether this node is inert. An inert node never provides
238  /// any opinions to a prim index. Such a node may exist purely as a
239  /// marker to represent certain composition structure, but should never
240  /// contribute opinions.
241  PCP_API
242  void SetInert(bool inert);
243  PCP_API
244  bool IsInert() const;
245 
246  /// Get/set whether this node is culled. If a node is culled, it and
247  /// all descendant nodes provide no opinions to the index. A culled
248  /// node is also considered inert.
249  PCP_API
250  void SetCulled(bool culled);
251  PCP_API
252  bool IsCulled() const;
253 
254  /// Get/set whether this node is restricted. A restricted node is a
255  /// node that cannot contribute opinions to the index due to permissions.
256  PCP_API
257  void SetRestricted(bool restricted);
258  PCP_API
259  bool IsRestricted() const;
260 
261  /// Returns true if this node is allowed to contribute opinions
262  /// for composition, false otherwise.
263  PCP_API
264  bool CanContributeSpecs() const;
265 
266  /// Returns true if this node has opinions authored
267  /// for composition, false otherwise.
268  PCP_API
269  void SetHasSpecs(bool hasSpecs);
270  PCP_API
271  bool HasSpecs() const;
272 
273  /// @}
274 
275  // Returns a compressed Sd site. For internal use only.
276  Pcp_CompressedSdSite GetCompressedSdSite(size_t layerIndex) const
277  {
278  return Pcp_CompressedSdSite(_nodeIdx, layerIndex);
279  }
280 
281 private:
282  friend class PcpPrimIndex_Graph;
283  friend class PcpNodeIterator;
288 
289  // Private constructor for internal use.
290  PcpNodeRef(PcpPrimIndex_Graph* graph, size_t idx)
291  : _graph(graph), _nodeIdx(idx)
292  {}
293 
294  size_t _GetNodeIndex() const { return _nodeIdx; }
295 
296  size_t _GetParentIndex() const;
297  size_t _GetOriginIndex() const;
298 
299 private: // Data
300  PcpPrimIndex_Graph* _graph;
301  size_t _nodeIdx;
302 };
303 
304 /// Typedefs and support functions
305 inline
306 size_t
308 {
309  return (size_t)x.GetUniqueIdentifier();
310 }
311 
313 typedef std::vector<PcpNodeRef> PcpNodeRefVector;
314 
315 /// \class PcpNodeRef_ChildrenIterator
316 ///
317 /// Object used to iterate over child nodes (not all descendant nodes) of a
318 /// node in the prim index graph in strong-to-weak order.
319 ///
321  : public hboost::iterator_facade<
322  /* Derived = */ PcpNodeRef_ChildrenIterator,
323  /* ValueType = */ PcpNodeRef,
324  /* Category = */ hboost::forward_traversal_tag,
325  /* RefType = */ PcpNodeRef
326  >
327 {
328 public:
329  /// Constructs an invalid iterator.
330  PCP_API
332 
333  /// Constructs an iterator pointing to \p node. Passing a NULL value
334  /// for \p node constructs an end iterator.
335  PCP_API
336  PcpNodeRef_ChildrenIterator(const PcpNodeRef& node, bool end = false);
337 
338 private:
340  PCP_API
341  void increment();
342  bool equal(const PcpNodeRef_ChildrenIterator& other) const
343  {
344  // Note: The default constructed iterator is *not* equal to any
345  // other iterator.
346  return (_node == other._node && _index == other._index);
347  }
348  reference dereference() const
349  {
350  return reference(_node._graph, _index);
351  }
352 
353 private:
354  // Current graph node this iterator is pointing at.
355  PcpNodeRef _node;
356 
357  // Index of current child.
358  size_t _index;
359 
361 };
362 
363 /// \class PcpNodeRef_ChildrenReverseIterator
364 ///
365 /// Object used to iterate over nodes in the prim index graph in weak-to-strong
366 /// order.
367 ///
369  : public hboost::iterator_facade<
370  /* Derived = */ PcpNodeRef_ChildrenReverseIterator,
371  /* ValueType = */ PcpNodeRef,
372  /* Category = */ hboost::forward_traversal_tag,
373  /* RefType = */ PcpNodeRef
374  >
375 {
376 public:
377  /// Constructs an invalid iterator.
378  PCP_API
380 
381  /// Constructs a reverse iterator from a forward iterator.
382  PCP_API
383  PcpNodeRef_ChildrenReverseIterator(const PcpNodeRef_ChildrenIterator&);
384 
385  /// Constructs an iterator pointing to \p node. Passing a NULL value
386  /// for \p node constructs an end iterator.
387  PCP_API
388  PcpNodeRef_ChildrenReverseIterator(const PcpNodeRef& node,bool end = false);
389 
390 private:
392  PCP_API
393  void increment();
394  bool equal(const PcpNodeRef_ChildrenReverseIterator& other) const
395  {
396  // Note: The default constructed iterator is *not* equal to any
397  // other iterator.
398  return (_node == other._node && _index == other._index);
399  }
400  reference dereference() const
401  {
402  return reference(_node._graph, _index);
403  }
404 
405 private:
406  // Current graph node this iterator is pointing at.
407  PcpNodeRef _node;
408 
409  // Index of current child.
410  size_t _index;
411 };
412 
413 template <>
414 struct Tf_IteratorInterface<PcpNodeRef::child_const_range, false> {
417  {
418  return c.first;
419  }
421  {
422  return c.second;
423  }
424 };
425 
426 template <>
427 struct Tf_IteratorInterface<PcpNodeRef::child_const_range, true> {
430  {
431  return c.second;
432  }
434  {
435  return c.first;
436  }
437 };
438 
439 template <>
440 struct Tf_ShouldIterateOverCopy<PcpNodeRef::child_const_range> :
441  hboost::true_type {};
442 
443 // Helper to count the non-variant path components of a path; equivalent
444 // to path.StripAllVariantSelections().GetPathElementCount() except
445 // this method avoids constructing a new SdfPath value.
447 
449 
450 #endif // PXR_USD_PCP_NODE_H
Definition: arc.h:44
PcpNodeRef::child_const_iterator IteratorType
Definition: node.h:415
PCP_API SdfPath GetPathAtIntroduction() const
Returns the path for this node's site when it was introduced.
PCP_API SdfPermission GetPermission() const
Get the site this node represents.
TfHashSet< PcpNodeRef, PcpNodeRef::Hash > PcpNodeRefHashSet
Definition: node.h:312
friend class PcpPrimIndex_Graph
Definition: node.h:282
PCP_API bool IsRootNode() const
Returns true if this node is the root node of the prim index graph.
PCP_API PcpNodeRef InsertChildSubgraph(const PcpPrimIndex_GraphPtr &subgraph, const PcpArc &arc)
static IteratorType End(PcpNodeRef::child_const_range const &c)
Definition: node.h:420
friend class PcpNodeRef_PrivateChildrenConstReverseIterator
Definition: node.h:287
PCP_API PcpNodeRef GetOriginRootNode() const
PCP_API void SetRestricted(bool restricted)
static IteratorType End(PcpNodeRef::child_const_range const &c)
Definition: node.h:433
friend class hboost::iterator_core_access
Definition: node.h:339
size_t PcpNodeRef::* UnspecifiedBoolType
Returns true if this is a valid node reference, false otherwise.
Definition: node.h:80
PcpNodeRef_ChildrenIterator child_const_iterator
Definition: node.h:69
static IteratorType Begin(PcpNodeRef::child_const_range const &c)
Definition: node.h:429
PCP_API int GetDepthBelowIntroduction() const
PCP_API bool operator<(const PcpNodeRef &rhs) const
PCP_API PcpNodeRef GetOriginNode() const
int PcpNode_GetNonVariantPathElementCount(const SdfPath &path)
PCP_API int GetSiblingNumAtOrigin() const
PCP_API void SetHasSymmetry(bool hasSymmetry)
TF_DECLARE_WEAK_PTRS(PcpPrimIndex_Graph)
PCP_API const PcpMapExpression & GetMapToRoot() const
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
PcpNodeRef()
Definition: node.h:74
PcpNodeRef_ChildrenReverseIterator child_const_reverse_iterator
Definition: node.h:70
PCP_API child_const_range GetChildrenRange() const
PCP_API PcpNodeRef GetParentNode() const
size_t operator()(const PcpNodeRef &rhs) const
Definition: node.h:98
PCP_API bool IsCulled() const
Get the site this node represents.
GLuint GLuint end
Definition: glew.h:1253
PCP_API bool IsDueToAncestor() const
Returns true if this node is due to an ancestral opinion.
const GLfloat * c
Definition: glew.h:16296
PCP_API const SdfPath & GetPath() const
Returns the path for the site this node represents.
Hash functor.
Definition: node.h:97
PCP_API PcpNodeRef InsertChild(const PcpLayerStackSite &site, const PcpArc &arc)
PCP_API void SetInert(bool inert)
friend class hboost::iterator_core_access
Definition: node.h:391
PCP_API PcpLayerStackSite GetSite() const
Get the site this node represents.
Definition: path.h:288
friend class PcpNodeRef_PrivateChildrenConstIterator
Definition: node.h:286
PCP_API bool IsRestricted() const
Get the site this node represents.
PcpNodeRef::child_const_reverse_iterator IteratorType
Definition: node.h:428
constexpr size_t PCP_INVALID_INDEX
Definition: types.h:199
std::pair< child_const_iterator, child_const_iterator > child_const_range
Definition: node.h:72
GLsizei const GLchar *const * path
Definition: glew.h:6461
PCP_API const PcpLayerStackRefPtr & GetLayerStack() const
Returns the layer stack for the site this node represents.
PCP_API PcpNodeRef GetRootNode() const
Walk up to the root node of this expression.
PCP_API bool CanContributeSpecs() const
Pcp_CompressedSdSite GetCompressedSdSite(size_t layerIndex) const
Definition: node.h:276
PCP_API const PcpMapExpression & GetMapToParent() const
PCP_API int GetNamespaceDepth() const
size_t hash_value(const PcpNodeRef &x)
Typedefs and support functions.
Definition: node.h:307
std::vector< PcpNodeRef > PcpNodeRefVector
Definition: node.h:313
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
bool equal(T1 a, T2 b, T3 t)
Definition: ImathFun.h:143
PCP_API bool HasSpecs() const
Get the site this node represents.
GA_API const UT_StringHolder arc
GLenum const void GLuint GLint reference
Definition: glew.h:13644
PCP_API void * GetUniqueIdentifier() const
Returns a value that uniquely identifies this node.
PCP_API bool IsInert() const
Get the site this node represents.
PCP_API PcpArcType GetArcType() const
Returns the type of arc connecting this node to its parent node.
PCP_API PcpNodeRef_ChildrenReverseIterator()
Constructs an invalid iterator.
static IteratorType Begin(PcpNodeRef::child_const_range const &c)
Definition: node.h:416
PCP_API SdfPath GetIntroPath() const
PCP_API void SetCulled(bool culled)
PCP_API void SetHasSpecs(bool hasSpecs)
PcpPrimIndex_GraphPtr GetOwningGraph() const
Returns the graph that this node belongs to.
bool operator==(const PcpNodeRef &rhs) const
Returns true if this references the same node as rhs.
Definition: node.h:86
PCP_API PcpNodeRef_ChildrenIterator()
Constructs an invalid iterator.
PCP_API void SetPermission(SdfPermission perm)
SdfPermission
Definition: types.h:155
#define PCP_API
Definition: api.h:40
PCP_API bool HasSymmetry() const
Get the site this node represents.
PcpArcType
Definition: types.h:46