Struct PopulationMask 

pub struct PopulationMask { /* private fields */ }

Population mask limiting which prim paths a Stage exposes (C++ UsdStagePopulationMask).

A mask path includes that prim’s subtree. Ancestors of masked paths are also included, so traversal can reach the requested working set.

The stored paths are a sorted antichain of absolute prim paths (C++ _ValidateAndNormalize): sorted so equal masks compare and hash equal — required by InstanceKey — and free of redundant descendants so membership is one binary search rather than a scan.

Implementations

impl PopulationMask

pub fn all() -> Self

Creates a mask that includes the full stage.

pub fn empty() -> Self

Creates an empty mask, which includes nothing.

pub fn new( paths: impl IntoIterator<Item: IntoPath>, ) -> Result<Self, PopulationMaskError>

Creates a mask from prim paths, normalizing once: sort, then drop every path an earlier one already covers. Sorting puts each path’s descendants directly after it, which is exactly the neighbour dedup_by compares against (C++ SdfPath::RemoveDescendentPaths).

pub fn with_path(self, path: impl IntoPath) -> Result<Self, PopulationMaskError>

Returns a copy of this mask with path added.

pub fn add_path( &mut self, path: impl IntoPath, ) -> Result<&mut Self, PopulationMaskError>

Adds a prim path to the mask, keeping it a sorted antichain: the path is inserted at its ordered position, and the descendants it subsumes are removed as one contiguous range. A path an existing entry already covers is dropped.

pub fn paths(&self) -> &[Path]

Returns the mask paths, sorted and with redundant descendants removed.

pub fn is_empty(&self) -> bool

Returns true if the mask contains no paths, and so includes nothing.

pub fn is_all(&self) -> bool

Returns true if the mask includes the full stage.

The absolute root covers every path, so normalization reduces a mask containing it to exactly [/].

pub fn includes(&self, path: &Path) -> bool

Returns true if path is inside the population mask — it lies at or below a mask path, or is an ancestor of one so traversal can reach the working set (C++ UsdStagePopulationMask::Includes).

Variant selection segments in path are stripped before matching so a mask of /Prim/Child still includes opinions authored under /Prim{set=sel}Child.

pub fn includes_subtree(&self, path: &Path) -> bool

Returns true if the mask includes path and its entire subtree — that is, path is at or below a mask path (C++ UsdStagePopulationMask::IncludesSubtree). Being a mere ancestor of a mask path is not enough, since the rest of the subtree stays excluded.

Child filtering short-circuits on this: once a subtree is wholly included, no descendant needs testing.

pub fn make_relative_to(&self, instance: &Path) -> Self

Re-expresses this mask relative to instance, for use as an instancing key ingredient (C++ Usd_InstanceKey’s _MakeMaskRelativeTo). Mask paths below instance are re-rooted onto the absolute root; those outside its subtree describe nothing about it and are dropped.

An instance whose whole subtree the mask includes keys as all. C++ derives the empty mask for that case and gets away with it only because it never keys an instance the mask excluded, which would derive the same empty mask; naming the two apart keeps the distinction available here.

Trait Implementations

impl Clone for PopulationMask

fn clone(&self) -> PopulationMask

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PopulationMask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PopulationMask

fn default() -> Self

Returns the “default value” for a type.

impl Eq for PopulationMask

impl Hash for PopulationMask

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PopulationMask

fn eq(&self, other: &PopulationMask) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PopulationMask