UsdStage

Fully qualified name: usdrt::UsdStage

class UsdStage

The outermost container for the scene description.

Contains a fabric stage, and offers most familiar Usd methods, and some additional methods to query fabric and export to USD.

Public Types

enum InitialLoadSet

Specifies the initial set of prims to load when opening a UsdStage.

Values:

enumerator LoadAll

Load all loadable prims.

enumerator LoadNone

Load no loadable prims.

Public Functions

~UsdStage(void)

UsdPrim GetPrimAtPath(

const SdfPath &path,

bool prefetchFromUsd = true,

) const

Get the UsdPrim on this stage at the specified path and optionally prefetch the data in fabric from USD.

Parameters:

• path – The prim path to find.

• prefetchFromUsd – Is prefetching from USD necessary.

Returns:

Return the UsdPrim at the given path, or an invalid prim if not found.

UsdPrim GetDefaultPrim(bool prefetchFromUsd = true) const

Get the root UsdPrim on this stage whose name is the root layer’s defaultPrim metadata’s value and optionally prefetch in fabric from USD.

Note

For a Fabric only stage, this will always return the absolute root path.

Parameters:

prefetchFromUsd – Is prefetching from USD necessary.

Returns:

Return the root UsdPrim.

UsdPrim DefinePrim(

const SdfPath &path,

const TfToken &typeName = TfToken(),

)

Gets or Creates a prim on this stage. If the prim already exists on the Usd stage, prefetch to fabric and return it. If the prim already exists in fabric, return it. Otherwise a new prim is created on the fabric stage.

Note

Current implementation does not yet automatically create any schema attributes defined by the prim type.

Parameters:

• path – The path to the prim.

• typeName – type of prim to create. Default is empty token.

Returns:

Return the prim at the given path.

UsdPrim GetPseudoRoot() const

Get the psuedo root “/” and prefetch in fabric.

Returns:

Return the pseudo root defined by Usd.

bool RemovePrim(const SdfPath &path) const

Remove prim at path from the fabric stage only.

Parameters:

path – The path to the prim to remove.

Returns:

true if the prim has successly been removed from fabric and false otherwise.

UsdAttribute GetAttributeAtPath(

const SdfPath &path,

bool prefetchFromUsd = true,

) const

Get the attribute at the given path if it is a valid prim by optionally prefetching it from USD.. Loads the prim in fabric if it is not already.

Parameters:

• path – The path to the prim.

• prefetchFromUsd – Is prefetching from USD necessary.

Returns:

The attribute at the given path, or an invalid attribute object if not found.

UsdRelationship GetRelationshipAtPath(

const SdfPath &path,

bool prefetchFromUsd = true,

) const

Get the relationship at the given path if it is a valid prim by optionally prefetching it from USD..

Parameters:

• path – The path to the prim.

• prefetchFromUsd – Is prefetching from USD necessary.

Returns:

The relationship at the given path, or an invalid relationship object if not found.

UsdPrimRange Traverse()

Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.

Returns:

Return a UsdPrimRange, which allows for iteratable depth-first traversal of the stage.

omni::fabric::UsdStageId GetStageId() const

Get the the Usd stage id for this stage. This id is consistent across USD and USDRT stages.

Note

For Fabric only stages, this will return omni::fabric::kUninitializedStage.

Returns:

Usd stage id

omni::fabric::StageReaderWriterId GetStageReaderWriterId() const

Get the fabric stage reader writer id associated with this usdrt stage.

Returns:

Return the stage reader writer id.

omni::fabric::StageReaderWriterId GetStageInProgressId() const

Get the fabric stage reader writer id associated with this usdrt stage.

Warning

Deprecated, use GetStageReaderWriterId instead

Returns:

Return the stage reader writer id.

omni::fabric::FabricId GetFabricId() const

Get the specific id for the fabric cache.

Returns:

Return the fabric Id.

bool IsFabricOnlyStage() const

Check if this is a fabric only stage.

Returns:

Returns true if this stage does not have an underlying USD stage.

void WriteToStage(

bool includePrivateFabricProperties = true,

bool convertFabricXforms = false,

) const

Write Fabric data that has been modified since fetching from USD to the underlying USD Stage’s current EditTarget and save it. If no underlying USD stage, do nothing.

Note

Note that WriteToStage will not export new prims created in Fabric.

Parameters:

• includePrivateFabricProperties – Include _* and omni:fabric:* properties when writing USD. Default is true.

• convertFabricXforms – Convert Fabric transforms to XformOps in USD. Default is false.

void WriteToLayer(

const std::string &filePath,

bool includePrivateFabricProperties = true,

bool convertFabricXforms = false,

) const

Write fabric data to a new temp stage with the layer filepath, and save it.

Parameters:

• filePath – Path to the new temp stage.

• includePrivateFabricProperties – Include _* and omni:fabric:* properties when writing USD. Default is true.

• convertFabricXforms – Convert Fabric transforms to XformOps in USD. Default is false.

bool HasPrimAtPath(const SdfPath &path, bool excludeTags = true) const

Check if prim at path exists in fabric, optionally including minimally populated prims.

Parameters:

• path – The path to look for.

• excludeTags – Exclude any prims in fabric that only have minimal population tags. Default is true.

Returns:

Return true if the prim exists in fabric, false otherwise.

std::vector<SdfPath> GetPrimsWithTypeName(

const TfToken &typeName,

) const

Find all prims on the fabric stage with type typename.

Parameters:

typeName – Prim type to find

Returns:

Return a vector of prim paths with the given typename.

std::vector<SdfPath> GetPrimsWithAppliedAPIName(

const TfToken &apiName,

) const

Find all prims on the fabric stage with applied API apiName.

Parameters:

apiName – The schema api name to look for.

Returns:

Return a vector of prim paths with the given apiName.

std::vector<SdfPath> GetPrimsWithTypeAndAppliedAPIName(

const TfToken &typeName,

const std::vector<TfToken> &apiNames,

) const

Find all prims on the fabric stage with type name typeName and applied APIs apiNames.

Parameters:

• typeName – Prim type to find

• apiNames – The list of schema api names to look for.

Returns:

Return a vector of prim paths with the given apiNames and typeName.

GfRange3d GetStageExtent() const

Get the stage extent. Run minimal populate if FSD is not active, and if not yet populated, compute and populate the world extent attributes for all boundable prims. Then compute the global min/max for the stage.

Note

For a Fabric only stage, this does nothing.

Returns:

Return the min/max points range for the stage.

RtPrimSelection SelectPrims(

std::vector<TfToken> requireAppliedSchemas,

std::vector<AttrSpec> requireAttrs,

std::optional<TfToken> requirePrimTypeName = {},

uint32_t device = kDeviceCpu,

bool wantPaths = false,

)

Get an RtPrimSelection, a selection of the stage’s prims accessible on CPU or GPU. For example, you can create an RtPrimSelection that selects all the Meshes on the stage, or all the Meshes with Physics applied, and then efficiently process that selection as a batch. An RtPrimSelection also selects a subset of the attributes of the selected prims, USDRT uses this information to minimize CPU<->GPU transfers.

Parameters:

• device – kDeviceCpu to get the prim selection on CPU, or integer i for CUDA device i.

• requireAppliedSchemas – Only include prims that have all the applied schemas in this list.

• requireAttrs – Provide access to the attributes in this list, only include prims with these attributes.

• requirePrimTypeName – Only include prims that have this prim type (optional).

• wantPaths – Provide access to prim paths within the selection - this has memory overhead and GPU transfer timing implications when enabled (optional)

void SynchronizeToFabric(

TimeChange timeChange = TimeChange::NoUpdate,

const usdrt::UsdTimeCode &time = usdrt::UsdTimeCode::Default(),

)

Synchronizes all pending USD changes to Fabric and makes cached Fabric data (such as transformation caches) up to date. Cached Fabric data is made consistent even if there is no USD stage attached.

For a Fabric only stage with no underlying USD stage, this does nothing.

When is not set to TimeChange::NoUpdate, time-sampled USD data is sampled at the given time before writing it to Fabric, otherwise time-sampled data is ignored.

Known issues:

• Default time code is not supported

• TimeChange::ForceUpdate is not supported

• Time-sampled data is not updated when FSD is off

Parameters:

• timeChange – How to synchronize time-sampled data. NoUpdate: ignore time samples. LazyUpdate: if time is different from the value passed in the previous call, evaluate attribute value at time and write it to Fabric. ForceUpdate: always evaluate attribute value at time and write it to Fabric.

• time – Time in USD time codes at which time-sampled data is evaluated. Ignored when timeChange is NoUpdate.

Public Static Functions

static UsdStageRefPtr CreateNew(

const std::string &identifier,

InitialLoadSet load = LoadAll,

)

Creates a new stage with root layer identifier.

Parameters:

• identifier – Root layer name for the new stage.

• load – The initial set of prims to load on the staged. Default is LoadAll.

Returns:

Return the reference pointer to the new stage.

static UsdStageRefPtr Open(

const std::string &filePath,

InitialLoadSet load = LoadAll,

)

Open a stage rooted at filePath.

Parameters:

• filePath – Path to the stage to open.

• load – The initial set of prims to load on the stage. Default is LoadAll.

Returns:

Return the reference pointer to the opened stage.

static UsdStageRefPtr CreateInMemory(

const std::string &identifier,

InitialLoadSet load = LoadAll,

)

Creates a new stage only in memory with root layer identifier. Note: This also creates an underlying usd stage. To create a stage in Fabric only, see CreateOnlyInFabric.

Parameters:

• identifier – Root layer name for the new stage.

• load – The initial set of prims to load on the stage. Default is LoadAll.

Returns:

Return the reference pointer to the new stage.

static UsdStageRefPtr CreateOnlyInFabric()

Creates a new stage only in fabric.

Returns:

Return the reference pointer to the new stage.

static UsdStageRefPtr Attach(

omni::fabric::UsdStageId stageId,

omni::fabric::StageReaderWriterId stageReaderWriterId = {0},

)

Attempt to find a matching existing fabric stage with Usd stage id stageId.

Parameters:

• stageId – The UsdStageId to look for in the UsdUtils global stage cache.

• stageReaderWriterId – The fabric stage id associated with this usdrt stage.

Returns:

Return the reference pointer to the attached stage.

static UsdStageRefPtr Attach(const omni::fabric::FabricId fabricId)

Attempt to find a matching existing fabric stage with fabric id fabricId.

Parameters:

fabricId – The FabricId to look for.

Returns:

Return the reference pointer to the attached stage.

static bool SimStageWithHistoryExists(

omni::fabric::UsdStageId stageId,

)

Check if a specific sim stage with history exists. SimStageWithHistory is a container for fabric with a StageReaderWriter and read-only StageAtTime instances.

Parameters:

stageId – The Usd stage id to look for.

Returns:

Return true if the sim stage with history exists, false otherwise.

static bool StageWithHistoryExists(omni::fabric::UsdStageId stageId)

This is a default kit container for fabric for the stage reader writer and read-only stage at time instances.

Warning

Deprecated, use SimStageWithHistoryExists instead

Parameters:

stageId – The Usd stage id to look for.

Returns:

Return true if the sim stage with history exists, false otherwise.