Instancing Queries#

ovstage_instancing.h provides high-level scene-graph instancing queries over populated content.

Note

Draft — API in flux. Instancing queries run over populated content (see Population (USD → ovstage)). This surface is provisional and can change.

C API#

The C header exposes three functions:

Function

Takes

Returns

ovstage_instancing_get_instance_roots

A prototype-root prim path

The instance roots that reference that prototype — a caller-owned ovx_primpath_list_t.

ovstage_instancing_get_prototype_root

An instance-root prim path

The prototype root for that instance — a single ovx_primpath_t.

ovstage_instancing_get_prototype_roots

(the stage)

All prototype roots — a caller-owned ovx_primpath_list_t.

The two *_roots functions return an ovx_primpath_list_t owned by the caller: release it through the path dictionary when you are done (the same refcount rule as any ovx_primpath_list_t you obtain). ovstage_instancing_get_prototype_root instead returns a single ovx_primpath_t, a dictionary-lifetime handle that does not require per-result release.

Python API#

The ovstage.instancing module exposes the same three synchronous queries as get_prototype_roots, get_prototype_root, and get_instance_roots. It accepts and returns path strings; returned native path lists are converted and released before each function returns, so Python callers do not manage path-list references.

# Prototype-root names are synthesized by the runtime
# (/__Prototype_<id>), so enumerate them instead of hardcoding a name.
# The wrapper returns ordinary strings and releases the native
# refcounted path lists before returning.
prototype_roots = instancing.get_prototype_roots(stage)
if not prototype_roots:
    print("expected at least one prototype root")
    return 1
all_prefixed = all(path.startswith("/__Prototype_") for path in prototype_roots)
prefix_status = "yes" if all_prefixed else "no"
print(f"prototype roots: {len(prototype_roots)} (all prefixed /__Prototype_: {prefix_status})")

prototype_root = prototype_roots[0]
instance_roots = sorted(instancing.get_instance_roots(stage, prototype_root))
print("instance roots of the prototype:", " ".join(instance_roots))

back_to_prototype = instancing.get_prototype_root(stage, "/World/InstanceA")
print(
    "/World/InstanceA maps back to the same prototype root:",
    "yes" if back_to_prototype == prototype_root else "no",
)

For the full C signatures, see C API Reference; the Python callables are listed in Python API Reference.

Where to Go Next#