UsdStagePopulationMask Class Reference

This class represents a mask that may be applied to a UsdStage to limit the set of UsdPrim s it populates. More...

Public Member Functions

 UsdStagePopulationMask ()=default
 Construct an empty mask that includes no paths. More...
 
 UsdStagePopulationMask (UsdStagePopulationMask const &)=default
 
 UsdStagePopulationMask (UsdStagePopulationMask &&)=default
 
UsdStagePopulationMaskoperator= (UsdStagePopulationMask const &)=default
 
UsdStagePopulationMaskoperator= (UsdStagePopulationMask &&)=default
 
template<class Iter >
 UsdStagePopulationMask (Iter f, Iter l)
 Construct a mask from the range of paths [f, l). More...
 
 UsdStagePopulationMask (std::vector< SdfPath > const &paths)
 Construct a mask from paths. More...
 
USD_API UsdStagePopulationMask (std::vector< SdfPath > &&paths)
 Construct a mask from paths. More...
 
USD_API UsdStagePopulationMask GetUnion (UsdStagePopulationMask const &other) const
 Return a mask that is the union of this and other. More...
 
USD_API UsdStagePopulationMask GetUnion (SdfPath const &path) const
 Return a mask that is the union of this and a mask containing the single path. More...
 
USD_API UsdStagePopulationMask GetIntersection (UsdStagePopulationMask const &other) const
 Return a mask that is the intersection of this and other. More...
 
USD_API bool Includes (UsdStagePopulationMask const &other) const
 Return true if this mask is a superset of other. More...
 
USD_API bool Includes (SdfPath const &path) const
 Return true if this mask includes path. More...
 
USD_API bool IncludesSubtree (SdfPath const &path) const
 Return true if this mask includes path and all paths descendant to path. More...
 
bool IsEmpty () const
 Return true if this mask contains no paths. More...
 
USD_API bool GetIncludedChildNames (SdfPath const &path, std::vector< TfToken > *childNames) const
 Return true if this mask includes any child prims beneath path, false otherwise. More...
 
USD_API std::vector< SdfPathGetPaths () const
 Return the set of paths that define this mask. More...
 
UsdStagePopulationMaskAdd (UsdStagePopulationMask const &other)
 Assign this mask to be its union with other and return a reference to this mask. More...
 
UsdStagePopulationMaskAdd (SdfPath const &path)
 Assign this mask to be its union with path and return a reference to this mask. More...
 
bool operator== (UsdStagePopulationMask const &other) const
 Return true if this mask is equivalent to other. More...
 
bool operator!= (UsdStagePopulationMask const &other) const
 Return true if this mask is not equivalent to other. More...
 
void swap (UsdStagePopulationMask &other)
 Swap the content of this mask with other. More...
 

Static Public Member Functions

static UsdStagePopulationMask All ()
 Return a mask that includes all paths. More...
 
static USD_API UsdStagePopulationMask Union (UsdStagePopulationMask const &l, UsdStagePopulationMask const &r)
 Return a mask that is the union of l and r. More...
 
static USD_API UsdStagePopulationMask Intersection (UsdStagePopulationMask const &l, UsdStagePopulationMask const &r)
 Return a mask that is the intersection of l and r. More...
 

Friends

USD_API size_t hash_value (UsdStagePopulationMask const &)
 

Detailed Description

This class represents a mask that may be applied to a UsdStage to limit the set of UsdPrim s it populates.

This is useful in cases where clients have a large scene but only wish to view or query a single or a handful of objects. For example, suppose we have a city block with buildings, cars, crowds of people, and a couple of main characters. Some tasks might only require looking at a single main character and perhaps a few props. We can create a population mask with the paths to the character and props of interest and open a UsdStage with that mask. Usd will avoid populating the other objects in the scene, saving time and memory. See UsdStage::OpenMasked() for more.

A mask is defined by a set of SdfPath s with the following qualities: they are absolute prim paths (or the absolute root path), and no path in the set is an ancestor path of any other path in the set other than itself. For example, the set of paths ['/a/b', '/a/c', '/x/y'] is a valid mask, but the set of paths ['/a/b', '/a/b/c', '/x/y'] is redundant, since '/a/b' is an ancestor of '/a/b/c'. The path '/a/b/c' may be removed. The GetUnion() and Add() methods ensure that no redundant paths are added.

Default-constructed UsdStagePopulationMask s are considered empty (IsEmpty()) and include no paths. A population mask containing SdfPath::AbsoluteRootPath() includes all paths.

Definition at line 60 of file stagePopulationMask.h.

Constructor & Destructor Documentation

◆ UsdStagePopulationMask() [1/4]

Construct an empty mask that includes no paths.

◆ UsdStagePopulationMask() [2/4]

UsdStagePopulationMask ( Iter  f,
Iter  l 
)
inlineexplicit

Construct a mask from the range of paths [f, l).

All paths in the range must be absolute prim paths or the absolute root path. (See SdfPath::IsAbsolutePath, SdfPath::IsAbsoluteRootOrPrimPath).

Definition at line 82 of file stagePopulationMask.h.

◆ UsdStagePopulationMask() [3/4]

UsdStagePopulationMask ( std::vector< SdfPath > const &  paths)
inlineexplicit

Construct a mask from paths.

All paths must be absolute prim paths or the absolute root path. (See SdfPath::IsAbsolutePath, SdfPath::IsAbsoluteRootOrPrimPath).

Definition at line 89 of file stagePopulationMask.h.

◆ UsdStagePopulationMask() [4/4]

USD_API UsdStagePopulationMask ( std::vector< SdfPath > &&  paths)
explicit

Construct a mask from paths.

All paths must be absolute prim paths or the absolute root path. (See SdfPath::IsAbsolutePath, SdfPath::IsAbsoluteRootOrPrimPath).

Member Function Documentation

◆ Add() [1/2]

UsdStagePopulationMask& Add ( UsdStagePopulationMask const &  other)
inline

Assign this mask to be its union with other and return a reference to this mask.

Definition at line 168 of file stagePopulationMask.h.

◆ Add() [2/2]

UsdStagePopulationMask& Add ( SdfPath const &  path)
inline

Assign this mask to be its union with path and return a reference to this mask.

Definition at line 175 of file stagePopulationMask.h.

◆ All()

static UsdStagePopulationMask All ( )
inlinestatic

Return a mask that includes all paths.

This is the mask that contains the absolute root path.

Definition at line 66 of file stagePopulationMask.h.

◆ GetIncludedChildNames()

USD_API bool GetIncludedChildNames ( SdfPath const &  path,
std::vector< TfToken > *  childNames 
) const

Return true if this mask includes any child prims beneath path, false otherwise.

If only specific child prims beneath path are included, the names of those children will be returned in childNames. If all child prims beneath path are included, childNames will be empty.

◆ GetIntersection()

USD_API UsdStagePopulationMask GetIntersection ( UsdStagePopulationMask const &  other) const

Return a mask that is the intersection of this and other.

◆ GetPaths()

USD_API std::vector<SdfPath> GetPaths ( ) const

Return the set of paths that define this mask.

◆ GetUnion() [1/2]

USD_API UsdStagePopulationMask GetUnion ( UsdStagePopulationMask const &  other) const

Return a mask that is the union of this and other.

◆ GetUnion() [2/2]

USD_API UsdStagePopulationMask GetUnion ( SdfPath const &  path) const

Return a mask that is the union of this and a mask containing the single path.

◆ Includes() [1/2]

USD_API bool Includes ( UsdStagePopulationMask const &  other) const

Return true if this mask is a superset of other.

That is, if this mask includes at least every path that other includes.

◆ Includes() [2/2]

USD_API bool Includes ( SdfPath const &  path) const

Return true if this mask includes path.

This is true if path is one of the paths in this mask, or if it is either a descendant or an ancestor of one of the paths in this mask.

◆ IncludesSubtree()

USD_API bool IncludesSubtree ( SdfPath const &  path) const

Return true if this mask includes path and all paths descendant to path.

For example, consider a mask containing the path '/a/b'. Then the following holds:

mask.Includes('/a') -> true
mask.Includes('/a/b') -> true
mask.IncludesSubtree('/a') -> false
mask.IncludesSubtree('/a/b') -> true

◆ Intersection()

static USD_API UsdStagePopulationMask Intersection ( UsdStagePopulationMask const &  l,
UsdStagePopulationMask const &  r 
)
static

Return a mask that is the intersection of l and r.

◆ IsEmpty()

bool IsEmpty ( ) const
inline

Return true if this mask contains no paths.

Empty masks include no paths.

Definition at line 149 of file stagePopulationMask.h.

◆ operator!=()

bool operator!= ( UsdStagePopulationMask const &  other) const
inline

Return true if this mask is not equivalent to other.

Definition at line 186 of file stagePopulationMask.h.

◆ operator==()

bool operator== ( UsdStagePopulationMask const &  other) const
inline

Return true if this mask is equivalent to other.

Definition at line 181 of file stagePopulationMask.h.

◆ swap()

void swap ( UsdStagePopulationMask other)
inline

Swap the content of this mask with other.

Definition at line 191 of file stagePopulationMask.h.

◆ Union()

static USD_API UsdStagePopulationMask Union ( UsdStagePopulationMask const &  l,
UsdStagePopulationMask const &  r 
)
static

Return a mask that is the union of l and r.


The documentation for this class was generated from the following file: