|
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first order. More...
#include <primRange.h>
Classes | |
class | EndSentinel |
This class lets us represent past-the-end without the full weight of an iterator. More... | |
class | iterator |
A forward iterator into a UsdPrimRange. More... | |
Public Types | |
using | const_iterator = iterator |
Public Member Functions | |
UsdPrimRange (const UsdPrim &start) | |
Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate). | |
UsdPrimRange (const UsdPrim &start, const Usd_PrimFlagsPredicate &predicate) | |
Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate . | |
iterator | begin () const |
Return an iterator to the start of this range. | |
const_iterator | cbegin () const |
Return a const_iterator to the start of this range. | |
UsdPrim | front () const |
Return the first element of this range. The range must not be empty(). | |
iterator | end () const |
Return the past-the-end iterator for this range. | |
const_iterator | cend () const |
Return the past-the-end const_iterator for this range. | |
void | increment_begin () |
Modify this range by advancing the beginning by one. | |
void | set_begin (iterator const &newBegin) |
Set the start of this range to newBegin . | |
bool | empty () const |
Return true if this range contains no prims, false otherwise. | |
operator bool () const | |
Return true if this range contains one or more prims, false otherwise. | |
bool | operator== (UsdPrimRange const &other) const |
Return true if this range is equivalent to other . | |
bool | operator!= (UsdPrimRange const &other) const |
Return true if this range is not equivalent to other . | |
Static Public Member Functions | |
static UsdPrimRange | PreAndPostVisit (const UsdPrim &start) |
Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate) with pre- and post-order visitation. | |
static UsdPrimRange | PreAndPostVisit (const UsdPrim &start, const Usd_PrimFlagsPredicate &predicate) |
Create a PrimRange that traverses the subtree rooted at start in depth-first order, visiting prims that pass predicate with pre- and post-order visitation. | |
static UsdPrimRange | AllPrims (const UsdPrim &start) |
Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims). | |
static UsdPrimRange | AllPrimsPreAndPostVisit (const UsdPrim &start) |
Construct a PrimRange that traverses the subtree rooted at start in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims) with pre- and post-order visitation. | |
static USD_API UsdPrimRange | Stage (const UsdStagePtr &stage, const Usd_PrimFlagsPredicate &predicate=UsdPrimDefaultPredicate) |
Create a PrimRange that traverses all the prims on stage , and visits those that pass the default predicate (as defined by UsdPrimDefaultPredicate). | |
An forward-iterable range that traverses a subtree of prims rooted at a given prim in depth-first order.
In addition to depth-first order, UsdPrimRange provides the optional ability to traverse in depth-first pre- and post-order wher prims appear twice in the range; first before all descendants and then again immediately after all descendants. This is useful for maintaining state associated with subtrees, in a stack-like fashion. See UsdPrimRange::iterator::IsPostVisit() to detect when an iterator is visiting a prim for the second time.
There are several constructors providing different levels of configurability; ultimately, one can provide a prim predicate for a custom iteration, just as one would use UsdPrim::GetFilteredChildren() in a custom recursion.
Why would one want to use a UsdPrimRange rather than just iterating over the results of UsdPrim::GetFilteredDescendants() ? Primarily, if one of the following applies:
Using UsdPrimRange in C++
UsdPrimRange provides standard container-like semantics. For example:
Using Usd.PrimRange in python
The python wrapping for PrimRange is python-iterable, so it can used directly as the object of a "for x in..." clause; however in that usage one loses access to PrimRange methods such as PruneChildren() and IsPostVisit(). Simply create the iterator outside the loop to overcome this limitation. Finally, in python, prim predicates must be combined with bit-wise operators rather than logical operators because the latter are not overridable.
Finally, since iterators in python are not directly dereferencable, we provide the python only methods GetCurrentPrim() and IsValid(), documented in the python help system.
Definition at line 101 of file primRange.h.
using const_iterator = iterator |
Definition at line 227 of file primRange.h.
|
inline |
Definition at line 229 of file primRange.h.
|
inlineexplicit |
Construct a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate).
Definition at line 238 of file primRange.h.
|
inline |
Construct a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting prims that pass predicate
.
Definition at line 245 of file primRange.h.
|
inlinestatic |
Construct a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims).
Definition at line 290 of file primRange.h.
|
inlinestatic |
Construct a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting all prims (including deactivated, undefined, and abstract prims) with pre- and post-order visitation.
Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().
Definition at line 304 of file primRange.h.
|
inline |
Return an iterator to the start of this range.
Definition at line 317 of file primRange.h.
|
inline |
Return a const_iterator to the start of this range.
Definition at line 321 of file primRange.h.
|
inline |
Return the past-the-end const_iterator for this range.
Definition at line 335 of file primRange.h.
|
inline |
Return true if this range contains no prims, false otherwise.
Definition at line 354 of file primRange.h.
|
inline |
Return the past-the-end iterator for this range.
Definition at line 333 of file primRange.h.
|
inline |
Return the first element of this range. The range must not be empty().
Definition at line 326 of file primRange.h.
|
inline |
Modify this range by advancing the beginning by one.
The range must not be empty, and the range must not be a pre- and post-order range.
Definition at line 339 of file primRange.h.
|
inlineexplicit |
Return true if this range contains one or more prims, false otherwise.
Definition at line 357 of file primRange.h.
|
inline |
Return true if this range is not equivalent to other
.
Definition at line 371 of file primRange.h.
|
inline |
Return true if this range is equivalent to other
.
Definition at line 360 of file primRange.h.
|
inlinestatic |
Create a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting prims that pass the default predicate (as defined by UsdPrimDefaultPredicate) with pre- and post-order visitation.
Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().
Definition at line 263 of file primRange.h.
|
inlinestatic |
Create a PrimRange that traverses the subtree rooted at start
in depth-first order, visiting prims that pass predicate
with pre- and post-order visitation.
Pre- and post-order visitation means that each prim appears twice in the range; not only prior to all its descendants as with an ordinary traversal but also immediately following its descendants. This lets client code maintain state for subtrees. See UsdPrimRange::iterator::IsPostVisit().
Definition at line 279 of file primRange.h.
|
inline |
Set the start of this range to newBegin
.
The newBegin
iterator must be within this range's begin() and end(), and must not have UsdPrimRange::iterator::IsPostVisit() be true.
Definition at line 346 of file primRange.h.
|
static |
Create a PrimRange that traverses all the prims on stage
, and visits those that pass the default predicate (as defined by UsdPrimDefaultPredicate).