UsdStage Configuration#

Utility functions to provide consistant authoring of UsdStages

When authoring UsdStages it is important to configure certain metrics & metadata on the root SdfLayer of the stage. While this is trivial using various Usd and UsdGeom public methods, it is also easy to forget, and difficult to discover.

These functions assist authoring applications in setting stage metrics and authoring metadata (see SdfLayer Authoring), so that each application can produce consistant metadata on the SdfLayers it exports.

Functions#

bool usdex::core::configureStage(pxr::UsdStagePtr stage, const std::string &defaultPrimName, const pxr::TfToken &upAxis, const double linearUnits, const std::string &authoringMetadata)

Configure a stage so that the defining metadata is explicitly authored.

pxr::UsdStageRefPtr usdex::core::createStage(const std::string &identifier, const std::string &defaultPrimName, const pxr::TfToken &upAxis, const double linearUnits, const std::string &authoringMetadata, const pxr::SdfLayer::FileFormatArguments &fileFormatArgs=pxr::SdfLayer::FileFormatArguments())

Create and configure a UsdStage so that the defining metadata is explicitly authored.

void usdex::core::saveStage(pxr::UsdStagePtr stage, const std::string &authoringMetadata, std::optional< std::string_view > comment=std::nullopt)

Save the given UsdStage with metadata applied to all dirty layers.

Functions#

bool usdex::core::configureStage(
pxr::UsdStagePtr stage,
const std::string &defaultPrimName,
const pxr::TfToken &upAxis,
const double linearUnits,
const std::string &authoringMetadata,
)#

Configure a stage so that the defining metadata is explicitly authored.

The default prim will be used as the target of a Reference or Payload to this layer when no explicit prim path is specified. A root prim with the given defaultPrimName will be defined on the stage if one is not already specified. If a new prim is defined then the prim type will be set to Scope.

The stage metrics of Up Axis and Linear Units will be authored.

The root layer will be annotated with authoring metadata, unless previously annotated. This is to preserve authoring metadata on referenced layers that came from other applications. See SdfLayer Authoring for more details on setLayerAuthoringMetadata.

Parameters:

  • stage – The stage to be configured.

  • defaultPrimName – Name of the default root prim.

  • upAxis – The up axis for all the geometry contained in the stage.

  • linearUnits – The meters per unit for all linear measurements in the stage.

  • authoringMetadata – The provenance information from the host application. See SdfLayer Authoring for details.

Returns:

A bool indicating if the metadata was successfully authored.

pxr::UsdStageRefPtr usdex::core::createStage(
const std::string &identifier,
const std::string &defaultPrimName,
const pxr::TfToken &upAxis,
const double linearUnits,
const std::string &authoringMetadata,
const pxr::SdfLayer::FileFormatArguments &fileFormatArgs = pxr::SdfLayer::FileFormatArguments(),
)#

Create and configure a UsdStage so that the defining metadata is explicitly authored.

See configureStage for more details.

Note

The extension of the identifier must be associated with a file format that supports editing.

Parameters:

  • identifier – The identifier to be used for the root layer of this stage.

  • defaultPrimName – Name of the default root prim.

  • upAxis – The up axis for all the geometry contained in the stage.

  • linearUnits – The meters per unit for all linear measurements in the stage.

  • authoringMetadata – The provenance information from the host application. See SdfLayer Authoring for details. If the “creator” key already exists, it will not be overwritten & this data will be ignored.

  • fileFormatArgs – Additional file format-specific arguments to be supplied during Stage creation.

Returns:

The newly created stage or a null pointer.

void usdex::core::saveStage(
pxr::UsdStagePtr stage,
const std::string &authoringMetadata,
std::optional<std::string_view> comment = std::nullopt,
)#

Save the given UsdStage with metadata applied to all dirty layers.

Save all dirty layers and sublayers contributing to this stage.

All dirty layers will be annotated with authoring metadata, unless previously annotated. This is to preserve authoring metadata on referenced layers that came from other applications. See SdfLayer Authoring for more details on setLayerAuthoringMetadata.

The comment will be authored in all layers as the SdfLayer comment.

Parameters:

  • stage – The stage to be saved.

  • authoringMetadata – The provenance information from the host application. See SdfLayer Authoring for details. If the “creator” key already exists, it will not be overwritten & this data will be ignored.

  • comment – The comment will be authored in all dirty layers as the Sdf.Layer comment.

On this page