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