definePayload#

Fully qualified name: usdex::core::definePayload

pxr::UsdPrim usdex::core::definePayload(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const std::string &sourceIdentifier,
std::optional<pxr::SdfPath> primPath = std::nullopt,
)#

Define a payload to a prim from a USD file.

This creates a payload prim that targets the prims in the external USD file.

Resolution behavior for sourceIdentifier:

  • Absolute filesystem paths are resolved directly by the configured asset resolver.

  • Relative filesystem paths (including ./, ../, or filenames without a leading root) are anchored to the resolved identifier of the stage’s current edit target layer, so the external file is located relative to that layer’s path.

  • Identifiers containing a URI-like scheme (for example, containing ://) are resolved without anchoring to the stage’s current edit target layer.

Parameters:

  • stage – The stage on which to define the payload

  • path – The absolute prim path at which to define the payload

  • sourceIdentifier – The identifier of the external USD file to payload

  • primPath – Absolute prim path in the external USD file for the root prim of this reference. If not provided, uses the default prim’s path

Returns:

The newly created payload prim. Returns an invalid prim on error.

On this page