Cloning Prims#

Note

Python uses ovstage cloning. Renderer.clone_usd* and ovrtx_clone_usd() are deprecated compatibility APIs. Refer to skills/update-0_3-0_4-python/SKILL.md. Ovstage cloning differs from the compatibility API:

  • The caller supplies an ordinal that must satisfy ovstage’s configured admission policy and applicable write floors.

  • The _usd suffix is dropped from clone destination paths.

  • A missing source prim or an already-existing target is rejected with a specific status (OVSTAGE_ERROR_NOT_FOUND / OVSTAGE_ERROR_PRIM_NOT_FOUND) rather than the generic OVRTX_API_ERROR. Both APIs reject before anything is cloned and name the offending path in the operation error.

Refer to ovstage Integration for the attached-stage workflow.

Cloning copies a USD subtree already present on the runtime stage to a new prim path. Use it for making additional copies of loaded geometry, sensors, or other stage content without re-authoring the original USD.

Clone destinations must be new absolute prim paths. If the cloned subtree contains relationships, make sure the copied content still points at the desired targets after cloning.

For attached ovstage clones, customizing a copied attribute under the STRICTLY_INCREASING policy requires a newer ordinal than the clone, even before sealing. See the admission-policy summary for other policy choices.

Wait for the clone to complete successfully before customizing its results. Then wait for all customizations and the write-floor advance before rendering. An accepted async enqueue alone does not establish successful publication.

Clone a Subtree#

These snippets clone at an explicit ordinal and wait for write-floor publication:

stage.clone("/World/Plane", ["/World/PlaneCloneA", "/World/PlaneCloneB"], ordinal=2)
stage.advance_write_floor(2, ovstage.Scope.ALL).wait()

ovx_string_t source = ovx_str("/World/Plane");
ovx_string_t targets[] = {
    ovx_str("/World/PlaneCloneA"),
    ovx_str("/World/PlaneCloneB"),
};

ovstage_enqueue_result_t eq = ovstage_clone(stage_, source, targets, 2, /*ordinal=*/2);
ASSERT_EQ(eq.status, OVSTAGE_OK) << format_ovstage_last_error();
docs_wait_ovstage_no_errors(stage_, eq.op_index);
docs_ovstage_advance_write_floor(stage_, 2);

Async Cloning#

Wait for the async clone before advancing and waiting for the write floor:

op = stage.clone_async("/World/Plane", ["/World/PlaneCloneAsync"], ordinal=2)
op.wait()
stage.advance_write_floor(2, ovstage.Scope.ALL).wait()

Notes#

  • Clone loaded content, then use Writing Transforms to place each copy.

  • Use Stage Queries to discover source paths before cloning generated or externally supplied scenes.

  • Use Loading USD references when the content should remain removable by handle or when it has not yet been loaded onto the stage.