C API Reference#

The C API provides the primary public interface to the ovstage runtime data plane. The reference below is generated from the shipped public headers under include/ovstage.

Note

These pages are generated by Doxygen + Breathe from the header comments. Building them locally requires Doxygen (refer to docs/README.md); the make html target runs Doxygen first.

Data Plane #

Instance lifecycle, cloning, and hierarchy. Writes, reads, queries, maps, and the write floor are declared in ovstage_api.h (refer to API Types and Utilities below).

OVStage instance lifecycle — creation and destruction of the ovstage data-plane backend.

The OVStage data-plane API (types, handles, operations, diagnostics) is declared in ovstage_api/ovstage_api.h as a vtable contract and exposed to callers through inline wrappers in ovstage_api/ovstage_api_utils.h (transitively included from ovstage_api.h) and sibling extension APIs.

This header adds the pieces specific to the ovstage backend: an instance descriptor, create/destroy entry points, and backend-owned helpers. Once an ovstage_instance_t* has been produced by ovstage_create_instance, call the generic ovstage_* wrappers declared in ovstage_api.h and the backend-specific entry points declared here to drive it.

Version: 0.2.0
Date: 2026-05-27

Functions

ovstage_api_status_t ovstage_initialize( const ovstage_config_t *config )#

Acquire a reference to process-scoped ovstage state.

Reference-counted: each successful call must be balanced by one ovstage_shutdown(). Process-scoped state is set up on the first reference (0 -> 1) and torn down on the last (1 -> 0). Instances created with ovstage_create_instance also hold a reference, so process state stays alive while any instance exists.

Calling ovstage_initialize() is optional when linking the ovstage shared library directly: instance creation acquires process state on demand. Call it explicitly to (1) pin process-scoped state independent of instance lifetime — so process-level resources stay alive when no instance is live or across instance create/destroy churn — and (2) bootstrap the runtime eagerly, so a framework/plugin failure surfaces here instead of at the first create_instance.

Parameters:

config – Optional process configuration (see ovstage_config_t / the entry builders in ovstage_config.h). OVSTAGE_CONFIG_BINARY_PACKAGE_ROOT_PATH is consumed by the static loader and must be supplied before any other ovstage_* call when a non-default root is needed. OVSTAGE_CONFIG_RUNTIME_DEFAULT_HIERARCHY_COMPUTATION_MODEL is consumed by the runtime and controls automatic hierarchy updates and the RUNTIME_DEFAULT selector for new instances. A runtime setting supplied after a process reference already exists must match the active setting.

Returns:

OVSTAGE_OK on success; OVSTAGE_ERROR_INVALID_ARGUMENT for malformed, duplicate, unknown, or conflicting runtime configuration.

Post:

Balance every successful call with one ovstage_shutdown().

ovstage_api_status_t ovstage_shutdown(void)#

Release one reference acquired by ovstage_initialize().

On the last outstanding reference (explicit initializations and live instances both count), process-scoped state is torn down.

Returns:: OVSTAGE_OK on success; OVSTAGE_ERROR_INVALID_ARGUMENT if called without a matching outstanding ovstage_initialize().

ovstage_api_status_t ovstage_set_log_callback( ovstage_log_severity_t severity, const ovx_string_t *channel_filter, ovstage_log_callback_t callback, void *user_data )#

Install a process-global log callback.

Routes ovstage’s log messages (and messages from its USD support layer) to callback. Process-global: one callback for the whole process, replacing any previous one. Pass callback = NULL to disable delivery.

Messages are delivered asynchronously on a dedicated dispatcher thread, so the callback never runs on the logging hot path and invocations are serialized. Use ovstage_flush_log to force pending messages through before a checkpoint.

The dispatcher thread and runtime log hook are created lazily on the first non-null callback and torn down when the callback is cleared, so a client that never installs a callback pays nothing. Passing callback = NULL flushes any pending messages to the current callback and then disables delivery.

When ovstage runs standalone (the shipped package used directly), this callback is the only diagnostics sink: with no callback installed the runtime prints nothing to stdout/stderr — except a final sanitized message when a fatal error aborts the process — and operation failures are reported through status codes and the error string accessors regardless of logging. When ovstage is embedded in a host application that configures its own logging, console behavior follows the host’s configuration. USD-support-layer messages carry the diagnostic text only (statuses at OVSTAGE_LOG_INFO, warnings and USD coding errors at OVSTAGE_LOG_WARNING, other errors at OVSTAGE_LOG_ERROR), never call-site file/line details.

Requires the ovstage runtime to be bootstrapped (an ovstage_initialize() or a live instance); otherwise returns OVSTAGE_ERROR_OP_FAILED. Keep a process reference (or clear the callback) before releasing the last one — the last ovstage_shutdown / instance destroy flushes and tears the bridge down.

Parameters:

severity – Default severity threshold for channels not matched by a rule in channel_filter. Messages below it are dropped. OVSTAGE_LOG_NONE drops all by default.
channel_filter – Optional comma-separated <channel>=<level> list (e.g. “omni.ovstage=verbose”). NULL applies severity uniformly. Levels: verbose|debug|info|warn| warning|error|fatal|none.
callback – Callback to receive messages, or NULL to disable.
user_data – Context passed to each callback invocation.

Returns:

OVSTAGE_OK on success; OVSTAGE_ERROR_INVALID_ARGUMENT if the filter string fails to parse; OVSTAGE_ERROR_OP_FAILED if the runtime is not bootstrapped.

ovstage_api_status_t ovstage_flush_log(ovstage_timeout_ns_t timeout)#

Block until all log messages emitted before this call have been delivered through the callback.

Point-in-time barrier: messages produced concurrently with or after this call are not guaranteed to be included. Returns OVSTAGE_OK immediately if no callback is installed (nothing is buffered).

Parameters:

timeout – Max time to wait. OVSTAGE_TIMEOUT_INFINITE blocks; 0 polls.

Returns:

OVSTAGE_OK if drained (or no callback installed); OVSTAGE_ERROR_TIMEOUT if not drained within timeout.

ovstage_api_status_t ovstage_create_instance(

const ovstage_instance_desc_t *desc,

ovstage_instance_t **out_instance

)#

Create an ovstage instance.

Parameters:

desc – Configuration descriptor.
out_instance – [out] Receives the new instance (vtable + context bundle).

Returns:

OVSTAGE_OK on success.

Post:

Caller owns the instance; destroy via ovstage_destroy_instance.

ovstage_api_status_t ovstage_destroy_instance( ovstage_instance_t *instance )#

Destroy an ovstage instance and release all resources.

Parameters:

instance – Instance to destroy. May be NULL (no-op).

Pre:

All operations, handles, and result payloads from this instance must be released first.

Pre:

No other thread may invoke any ovstage_* wrapper, vtable slot, or internal accessor on this instance while or after destroy runs. The bundle and its context are deallocated before this call returns; any concurrent or post-destroy use is a use-after-free.

ovstage_api_status_t ovstage_get_usd_stage_id( ovstage_instance_t *instance, uint64_t *out_usd_stage_id )#

Get the source USD stage id backing this ovstage instance.

TEMPORARY: this accessor is a stopgap and is expected to be removed. Consumers should read stage data (units, attributes, relationships) through the ovstage query/read API rather than reaching back to the USD stage; do not build a lasting dependency on this entry point.

An ovstage instance with USD population support mirrors a USD stage (populated by ovpopulation or the host). This returns the runtime identifier of that source stage.

Parameters:

instance – The ovstage instance.
out_usd_stage_id – [out] Receives the USD stage id.

Returns:

OVSTAGE_OK on success.

Returns:

OVSTAGE_ERROR_INVALID_ARGUMENT if instance or out_usd_stage_id is NULL.

Returns:

OVSTAGE_ERROR_NOT_SUPPORTED if the instance has no associated USD stage.

ovstage_enqueue_result_t ovstage_clone( ovstage_instance_t *instance, ovx_string_t source_path, const ovx_string_t *target_paths, size_t num_target_paths, ovstage_ordinal_t ordinal )#

Enqueue an asynchronous operation to clone the subtree under the source path to one or more target paths in the runtime stage representation.

The source path must exist in the stage; a missing source is rejected with OVSTAGE_ERROR_NOT_FOUND (surfaced through wait_op). The target paths must not already exist; a target that does is rejected with OVSTAGE_ERROR_PRIM_NOT_FOUND (the create-only convention shared with INSERT-mode writes), before any prim is created, so a batch mixing fresh and existing targets clones nothing.

Data-plane peer of ovrtx’s ovrtx_clone_usd (the _usd postfix is dropped), but — like write_attribute / delete_attributes — clone is an ordinal-keyed write: it carries an ordinal and is rejected with OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION (surfaced through wait_op) when ordinal is at or below the effective seal of any attribute it would touch, so it can never mutate sealed ordinals. The call returns immediately with an ovstage_enqueue_result_t (status + op_index); await completion through the vtable wait_op (and release it with release_op) like any other data-plane operation.

Path-bearing values that target the source subtree are rebased to the corresponding target subtree. This includes relationship targets (e.g. material:binding, skel:skeleton), scalar/array path values, and USD attribute connections. Paths outside the source subtree are copied unchanged, so clones can continue to reference shared materials and other shared resources. Cloned attribute values, including relationship targets, are ordinal-change-tracked. Attribute connections and scene hierarchy changes, such as the source/target parents’ child lists, are not.

Parameters:

instance – The ovstage instance.
source_path – Path to the source subtree to clone.
target_paths – Array of target paths to clone to.
num_target_paths – Number of target paths to clone to.
ordinal – Ordinal for this clone. Must be greater than the effective seal of every attribute the clone reproduces (admission is per-attribute over the source subtree, like write_attribute), evaluated at execution time.

Returns:

Enqueue result with status + op_index.

status == OVSTAGE_OK if the operation was enqueued successfully.
a non-OK status if the enqueue was rejected (e.g. invalid arguments, or the required runtime capability is unavailable). Per-op execution errors — including OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION, OVSTAGE_ERROR_NOT_FOUND (missing source), and OVSTAGE_ERROR_PRIM_NOT_FOUND (a target already exists) — are surfaced through wait_op.

ovstage_enqueue_result_t ovstage_get_hierarchy( ovstage_instance_t *instance, ovx_primpath_list_t prim_paths, ovstage_ordinal_t ordinal, ovstage_hierarchy_relation_t relation, ovstage_hierarchy_handle_t *out_hierarchy_handle )#

Enqueue a backend hierarchy lookup for a batch of prims.

prim_paths is an immutable ordered ovx_primpath_list_t. The list is copied during enqueue; callers may destroy their user-owned list after this call returns OVSTAGE_OK. The ovstage backend answers parent/children/sibling hierarchy lookups from its tracked prim-parent hierarchy. Fetch the per-input results with ovstage_fetch_hierarchy_result.

Hierarchy lookups observe the latest sealed stage state. Returned relation information is resolved from attribute data at the latest sealed ordinal(s).

Parameters:

instance – The ovstage instance.
prim_paths – Ordered prim path list to inspect.
ordinal – Stage ordinal requested by this lookup.
relation – Hierarchy direction to return for each input prim.
out_hierarchy_handle – [out] Receives the lookup handle.

Returns:

Enqueue result with status + op_index. Per-op execution failures are surfaced through ovstage_wait_op + ovstage_get_last_op_error.

ovstage_api_status_t ovstage_fetch_hierarchy_result( ovstage_instance_t *instance, ovstage_hierarchy_handle_t hierarchy_handle, ovstage_hierarchy_result_t *out_result )#

Fetch the result of a completed hierarchy lookup batch.

Use ovstage_wait_op with the op_index returned by ovstage_get_hierarchy to wait for completion before fetching. This function does not block.

Returns:: OVSTAGE_OK on success, OVSTAGE_ERROR_TIMEOUT if the producer op has not completed, OVSTAGE_ERROR_OP_FAILED if the underlying enqueue failed.
Post:: On OVSTAGE_OK, pointers in *out_result remain valid until ovstage_release_hierarchy_result.

ovstage_api_status_t ovstage_release_hierarchy_result( ovstage_instance_t *instance, const ovstage_hierarchy_result_t *result )#

Release a fetched hierarchy result payload.

After this call, pointers in *result are invalid.

ovstage_enqueue_result_t ovstage_release_hierarchy( ovstage_instance_t *instance, ovstage_hierarchy_handle_t handle )#

Enqueue release of a hierarchy handle.

Per-handle ordered: the release waits for any in-flight fetch on the same handle to complete before reclaiming resources.

ovstage_api_status_t ovstage_get_hierarchy_computation_models(

ovstage_instance_t *instance,

const ovstage_hierarchy_computation_model_desc_t **out_models,

size_t *out_model_count

)#

Return the hierarchy computation models supported by this backend.

The descriptor array lists the ovstage_hierarchy_computation_model_id_t concrete values and selectors supported by this instance. Names and descriptions are implementation-owned and valid for the lifetime of the instance.

Parameters:

instance – The ovstage instance.
out_models – [out] Receives the implementation-owned descriptor array.
out_model_count – [out] Receives the number of descriptors.

Returns:

OVSTAGE_OK on success.

ovstage_enqueue_result_t ovstage_compute_hierarchy( ovstage_instance_t *instance, ovstage_hierarchy_computation_model_id_t computation_model_id, ovstage_ordinal_t input_ordinal, ovstage_ordinal_t output_ordinal )#

Enqueue hierarchy computation using a runtime computation model.

This computes hierarchy-derived stage data such as local/world transforms, visibility, and other derived bounds/state managed by the selected runtime model.

The caller supplies the input ordinal to compute from and the output ordinal assigned to hierarchy-derived results.

Parameters:

instance – The ovstage instance.
computation_model_id – Public model enum value: a concrete model, a DEFAULT_* alias, or RUNTIME_DEFAULT to use the process default captured when the instance was created.
input_ordinal – Ordinal of hierarchy inputs to compute from.
output_ordinal – Ordinal assigned to hierarchy-derived outputs.

Returns:

Enqueue result with status + op_index. Per-op execution failures are surfaced through ovstage_wait_op + ovstage_get_last_op_error.

Types #

Backend-owned enums, handles, and result structures.

Backend-owned ovstage data-plane types.

This header contains the type surface that is specific to the ovstage backend. The generic vtable runtime types remain in ovstage_api/ovstage_api_types.h.

Version: 0.2.0
Date: 2026-06-17

Defines

OVSTAGE_INVALID_HIERARCHY_HANDLE#

OVSTAGE_INVALID_HIERARCHY_RESULT_ID#

OVSTAGE_INVALID_HIERARCHY_COMPUTATION_MODEL_ID#

Typedefs

typedef void (*ovstage_log_callback_t)(ovstage_log_severity_t severity, double timestamp, ovx_string_t message, void *user_data)#

Callback for receiving ovstage log messages.

Process-global (see ovstage_set_log_callback) and may be invoked from any thread; the implementation serializes invocations, so the callback body needs no mutex of its own for its own state. message is valid only for the duration of the call — copy it to retain.

Param severity:: Severity of the message.
Param timestamp:: Wall-clock seconds since the epoch.
Param message:: Message text (valid only during the call).
Param user_data:: Context passed to ovstage_set_log_callback.

typedef uint64_t ovstage_hierarchy_handle_t#: Hierarchy handle - identifies an enqueued hierarchy lookup batch.

typedef uint64_t ovstage_hierarchy_result_id_t#: Opaque identity for a fetched hierarchy result payload.

Enums

enum ovstage_config_key_type_t#

Key-type tag for ovstage_config_entry_t; selects the valid key/value union members.

Values:

enumerator OVSTAGE_CONFIG_KEY_TYPE_BOOL#

enumerator OVSTAGE_CONFIG_KEY_TYPE_INT64#

enumerator OVSTAGE_CONFIG_KEY_TYPE_UINT64#

enumerator OVSTAGE_CONFIG_KEY_TYPE_DOUBLE#

enumerator OVSTAGE_CONFIG_KEY_TYPE_STRING#

enumerator OVSTAGE_CONFIG_KEY_TYPE_BLOB#

enumerator OVSTAGE_CONFIG_KEY_TYPE_COUNT#

enum ovstage_config_bool_t#

Boolean config keys.

Value type: bool. (None defined yet.)

Values:

enumerator OVSTAGE_CONFIG_BOOL_COUNT#

enum ovstage_config_int64_t#

Int64 config keys.

Value type: int64_t. (None defined yet.)

Values:

enumerator OVSTAGE_CONFIG_INT64_COUNT#

enum ovstage_config_uint64_t#

Uint64 config keys.

Value type: uint64_t.

Values:

enumerator OVSTAGE_CONFIG_RUNTIME_DEFAULT_HIERARCHY_COMPUTATION_MODEL#

ovstage_hierarchy_computation_model_id_t override used for automatic hierarchy-derived transform updates and by OVSTAGE_HIERARCHY_COMPUTATION_MODEL_RUNTIME_DEFAULT.

Defaults to OVSTAGE_HIERARCHY_COMPUTATION_MODEL_CPU_INCREMENTAL. An entry whose value is RUNTIME_DEFAULT is ignored.

enumerator OVSTAGE_CONFIG_UINT64_COUNT#

enum ovstage_config_double_t#

Double config keys.

Value type: double. (None defined yet.)

Values:

enumerator OVSTAGE_CONFIG_DOUBLE_COUNT#

enum ovstage_config_string_t#

String config keys.

Value type: ovx_string_t.

Values:

enumerator OVSTAGE_CONFIG_BINARY_PACKAGE_ROOT_PATH#

Directory of the ovstage binary package (the package bin/).

The static loader (ovstage-static) loads the ovstage shared library from here and ovstage resolves its bundled plugins/USD schemas relative to it. When absent, the loader defaults to its own module directory. Ignored by the ovstage shared library’s own ovstage_initialize.

enumerator OVSTAGE_CONFIG_STRING_COUNT#

enum ovstage_config_blob_t#

Blob config keys.

Value type: ptr + size. (None defined yet.)

Values:

enumerator OVSTAGE_CONFIG_BLOB_COUNT#

enum ovstage_log_severity_t#

Log severity levels.

Values follow the underlying log-level ordering.

Values:

enumerator OVSTAGE_LOG_VERBOSE#: Most verbose (debug/trace).

enumerator OVSTAGE_LOG_INFO#: Informational.

enumerator OVSTAGE_LOG_WARNING#: Warning; operation continues.

enumerator OVSTAGE_LOG_ERROR#: Error; operation may have failed (fatal is reported here too).

enumerator OVSTAGE_LOG_NONE#

Threshold sentinel: as a filter level, disables all logging.

Never delivered to the callback.

enum ovstage_hierarchy_computation_model_id_t#

Public hierarchy computation model identifiers.

Hierarchy computation models update hierarchy-derived stage data, such as world transforms, visibility, and derived bounds/state owned by the backing runtime. The enum values are stable API inputs for ovstage_compute_hierarchy.

Not every backend, platform, or build necessarily supports every concrete model below. Call ovstage_get_hierarchy_computation_models to discover the concrete models and selectors advertised by the current ovstage instance, along with their display names and descriptions.

The DEFAULT_* aliases are semantic convenience choices for callers that only care about CPU vs GPU placement. They intentionally alias concrete entries instead of introducing extra model IDs, so catalog discovery remains stable and duplicate-free.

Values:

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_INVALID#: Invalid/sentinel value; never accepted by ovstage_compute_hierarchy.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_CPU_INCREMENTAL#: Incrementally update hierarchy-derived stage data on CPU.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_GPU_INCREMENTAL#: Incrementally update hierarchy-derived stage data on GPU.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_GPU_GLOBAL#: Globally recompute hierarchy-derived stage data on GPU.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_RUNTIME_DEFAULT#

Use the runtime default captured when this ovstage instance was created.

The process default is configured through OVSTAGE_CONFIG_RUNTIME_DEFAULT_HIERARCHY_COMPUTATION_MODEL and defaults to CPU_INCREMENTAL.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_DEFAULT_CPU#: Default CPU hierarchy computation model for this API revision.

enumerator OVSTAGE_HIERARCHY_COMPUTATION_MODEL_DEFAULT_GPU#: Default GPU hierarchy computation model for this API revision.

enum ovstage_hierarchy_relation_t#

Backend hierarchy relation to inspect for each input prim.

Values:

enumerator OVSTAGE_HIERARCHY_PARENT#: Parent prim path; result count is 0 or 1.

enumerator OVSTAGE_HIERARCHY_CHILDREN#: Direct child prim paths.

enumerator OVSTAGE_HIERARCHY_SIBLINGS#: Other prims with the same direct parent.

struct ovstage_instance_desc_t#

#include <ovstage_types.h>

Configuration for creating an ovstage instance.

Note

GPU device configuration is intentionally omitted; see “Deferred Design

Items” in

ovstage.h.

Public Members

const char *name#

Optional instance name for debugging.

May be NULL.

struct ovstage_config_entry_t#

#include <ovstage_types.h>

A single config entry.

key_type selects the valid key/value union members.

Public Members

ovstage_config_key_type_t key_type#

ovstage_config_bool_t bool_key#

ovstage_config_int64_t int64_key#

ovstage_config_uint64_t uint64_key#

ovstage_config_double_t double_key#

ovstage_config_string_t string_key#

ovstage_config_blob_t blob_key#

union ovstage_config_entry_t key#

bool bool_value#

int64_t int_value#

uint64_t uint_value#

double double_value#

ovx_string_t string_value#

const void *data#

size_t size#

struct ovstage_config_entry_t blob_value#

union ovstage_config_entry_t value#

struct ovstage_config_t#

#include <ovstage_types.h>

Process configuration passed to ovstage_initialize().

NULL, or a non-NULL struct with entry_count 0, selects defaults.

Public Members

const ovstage_config_entry_t *entries#

size_t entry_count#

struct ovstage_hierarchy_item_t#

#include <ovstage_types.h>

Per-input hierarchy result metadata.

path_offset and path_count select this input’s relation paths from the flattened ovstage_hierarchy_result_t::paths array. Empty relations return OVSTAGE_OK with path_count 0. Missing input prims report OVSTAGE_ERROR_NOT_FOUND in the item status without failing the whole fetched batch.

Public Members

ovstage_api_status_t status#

size_t path_offset#

size_t path_count#

struct ovstage_hierarchy_result_t#

#include <ovstage_types.h>

Result of a fetched hierarchy lookup batch.

items has one entry for each input path in the submitted ovx_primpath_list_t, in the same order. paths is a flattened array of ovstage-owned string-or-token views referenced by item offsets/counts. ordinal is the requested stage ordinal from ovstage_get_hierarchy. Both arrays remain valid until ovstage_release_hierarchy_result.

Public Members

ovstage_hierarchy_result_id_t hierarchy_result_id#

ovstage_ordinal_t ordinal#

const ovstage_hierarchy_item_t *items#

size_t input_count#

const ovx_string_or_token_t *paths#

size_t path_count#

struct ovstage_hierarchy_computation_model_desc_t#

#include <ovstage_types.h>

Description of a runtime-supported hierarchy computation model.

model_id is one of ovstage_hierarchy_computation_model_id_t. name is stable enough for logs/config files owned by the implementation; description is human-readable guidance.

Public Members

ovstage_hierarchy_computation_model_id_t model_id#

ovx_string_t name#

ovx_string_t description#

Population (USD → ovstage)#

Per-stage population state is created lazily on first use of any populate entry point and released automatically when the ovstage instance is destroyed via ovstage_destroy_instance.

Reserved prim attributes.

Every populated prim carries usd-prim-type, whatever put it in scope and whatever its properties are. A prim USD gives no type name gets ovstage_population_untyped_type_name() instead, so it is never absent.

usd-schemas carries the prim’s applied API schema names, and is populated only when it has any — a prim with none does not carry it at all, rather than carrying an empty one.

Neither depends on the selector’s property predicate. A selector that publishes no properties at all still yields these. Populated value types.

What a USD value becomes in ovstage is fixed by its USD value type, and a caller selecting arbitrary properties needs it up front to size and interpret a read. The rules below give the whole mapping; the per-type table is in the population documentation.

Numeric types keep their bytes. The dtype’s element type and bit width come from the USD scalar type and its lane count from the number of components, so float is {float, 32, 1}, double3 is {float, 64, 3}, int4 is {int, 32, 4}, and matrix4d is {float, 64, 16}.
A USD array populates with the same dtype as its element type and is_array = true. Everything else populates flat, one fixed-size value per prim.
String-like types do not populate as text. token, string, pathExpression and the halves of an asset are interned through the path dictionary and populate as {uint, 64, 1} ids, which a consumer resolves back through the dictionary. An asset is the exception in width: it carries the (authored, resolved) pair as {uint, 64, 2}.
An empty token, string, path expression, or asset half populates as id 0. It is a value USD authors and reads back, so it is populated rather than dropped: absence means the property was not authored, not that it was empty.
The semantic records what the bytes mean. It comes from the USD type’s role where it has one (point3f to OVSTAGE_SEMANTIC_POINT, color3f to ..._COLOR, frame4d to ..._FRAME), and otherwise from the type itself (matrix4d to ..._MATRIX, quatf to ..._QUATERNION, timecode to ..._TIME_CODE, token to ..._TOKEN_ID, asset to ..._ASSET_PATH_ID, pathExpression to ..._PATH_EXPRESSION_STRING). A relationship’s targets populate as interned path ids with ..._RELATIONSHIP_PATH_ID.
**opaque** carries no value by definition, so nothing is populated for it and nothing is reported.

A few properties populate in a type their USD type does not predict, because the OVSTAGE_POPULATION_DOMAIN_RENDERING domain publishes them in a fixed one and both domains must agree on a shared stage. These are listed in the documentation; extent is the one whose dtype differs rather than only its semantic. Path predicates.

OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PATH and ..._IS_UNDER_PATH take an absolute prim path, or /. A property, target, or variant-selection path is rejected at enqueue.

Neither matches a prim inside a native instance. Populated ancestors.

A prim that OVSTAGE_POPULATION_DOMAIN_PHYSICS or a desc’s selectors put in scope is published together with every one of its ancestor prims, so a consumer can walk the prim tree down to it however sparse the selection is.

An ancestor that no selector matches on its own merit carries none of the data a selected prim does — no attributes, relationships, or metadata — only the reserved ones above. It does carry the derived local-transform attributes below when it is xformable, which is what lets world-transform composition run the whole chain.

Populated USD metadata attributes.

Besides attribute and relationship values, population can surface USD metadata as attributes, under a reserved usd-metadata: prefix:

Prim metadata -> usd-metadata:<field>
Property (attribute/relationship) metadata -> <property>:usd-metadata:<field>

A metadatum inside a dictionary field (e.g. customData) extends <field> with the :-joined key path — the same separator USD itself uses to address subdictionary elements. Example attribute names:

usd-metadata:inactiveIds
usd-metadata:customData:physics:localSpaceVelocities
points:usd-metadata:interpolation

A path with an empty component — a leading, trailing or doubled : — names neither a field nor a key, and is rejected wherever one is taken.

The value uses the same type mapping as attribute values.

Defines

OVSTAGE_POPULATION_INVALID_OP_ID#

OVSTAGE_POPULATION_INVALID_USD_REFERENCE_HANDLE#

Typedefs

typedef uint64_t ovstage_population_op_id_t#

Opaque id of an enqueued population operation, returned by the async entry points and passed to ovstage_population_wait_op.

Zero is never a live op id.

typedef uint64_t ovstage_population_usd_reference_handle_t#

Opaque handle to a USD reference added by ovstage_population_add_usd_reference_from_file / _from_string, passed to ovstage_population_remove_usd_reference to take it back out.

Reserved synchronously by the add call (so it is valid immediately, before the op runs) and freed by ovstage_population_remove_usd_reference, _reset_usd, or a fresh _open_usd_*. Zero is never a live handle.

Enums

enum ovstage_population_domain_t#

Coarse population domains for the canonical population entry points.

Bitmask — OR values together.

OVSTAGE_POPULATION_DOMAIN_NONE (0) selects no data domain: a domains argument of 0 populates nothing at all. Pass OVSTAGE_POPULATION_DOMAIN_ALL to populate all domains.

Values:

enumerator OVSTAGE_POPULATION_DOMAIN_NONE#

enumerator OVSTAGE_POPULATION_DOMAIN_RENDERING#: Meshes, lights, materials, and cameras.

enumerator OVSTAGE_POPULATION_DOMAIN_PHYSICS#: Colliders, rigid bodies, joints, articulations, and the physics schema attributes/relationships authored on them.

enumerator OVSTAGE_POPULATION_DOMAIN_ALL#

Functions

static inline ovx_string_t ovstage_population_untyped_type_name(void)#

The reserved usd-prim-type value population authors onto prims that have no USD type (typeless def "Foo" containers).

USD allows a defined prim to carry no type name, but ovstage rows are keyed/created through their prim type; authoring this synthetic type makes a typeless prim a first-class, queryable row so prim-tree/hierarchy walks can cross it (e.g. a typeless /World between / and its populated descendants). It is namespaced to never collide with a real USD type, and consumers can filter usd-prim-type against this value to recognize originally-typeless prims.

Returned as an ovx_string_t view over a static, null-terminated literal: .ptr is a valid C string and .length its byte length.

ovstage_api_status_t ovstage_population_register_usd_schemas( const ovx_string_t *paths, size_t path_count )#

Transform attributes.

For every prim that OVSTAGE_POPULATION_DOMAIN_PHYSICS or a desc’s selectors put in scope, and that is USD-xformable, population also derives the prim’s local transform. The attributes and their types are a contract consumers can rely on:

omni:xform — float64, 16 lanes, OVSTAGE_SEMANTIC_MATRIX. The 4x4 row-major local transform: the prim’s USD transform ops composed into a single matrix. This is the input ovstage_compute_hierarchy reads to derive world transforms.
omni:resetXformStack — bool. True when the prim resets the inherited parent transform stack, which world-transform composition honors.
omni:fabric:worldMatrix — float64, 16 lanes, OVSTAGE_SEMANTIC_MATRIX. Created, not maintained, and only when OVSTAGE_POPULATION_DOMAIN_RENDERING is not among the selected domains. ovstage_compute_hierarchy updates this value but does not create it, so population creates it for a qualifying prim that has none and thereafter leaves it alone: the value is written once, at creation, as the local transform, and later derived values come from hierarchy computation. Treat this provisional implementation-named attribute as read-only output; author transforms through omni:xform and omni:resetXformStack instead. A prim that stops being xformable loses it. With ..._RENDERING selected that domain owns it outright and population neither creates nor writes it.

A prim that is not xformable gets none of these. Being xformable does not by itself put a prim in scope: the derivation only ever applies to prims population already publishes. Register USD schema definitions with the USD runtime population reads through.

Population registers only what its USD build provides (the core Usd* schemas). Register any additional family your stages use, so population resolves each prim’s full schema-declared property set rather than only its authored properties.

Registering does not load schema code, so a family that ships a C++ library or Python module is usable for its definitions alone.

Remark

Only the paths themselves are checked here. What a descriptor contains is USD’s to validate: a malformed one, or an Includes pattern matching nothing, raises a USD diagnostic, contributes no plugins, and still returns OVSTAGE_OK — surfacing later as schema properties that never resolve.

Remark

Register before the first ovstage call that reads USD schema definitions — population and export both do. USD assembles its schema definitions once, on first read, and ignores plugins registered after that — a late family registers cleanly and contributes nothing. Such a call reports OVSTAGE_ERROR_OP_FAILED, and the plugins it registered cannot be taken back. If another USD consumer in the process reads schemas first, that cannot be detected and the call still reports success.

Remark

Process-scoped, thread-safe and irreversible: USD offers no counterpart removal. Re-registering a family is a no-op, not an error.

Remark

Callable on its own: it requires no prior ovstage_initialize() and no live ovstage instance.

Remark

Registering a family makes its definitions resolvable. It does not change which prims a population domain claims.

Parameters:

paths – Array of path_count paths, each a USD plugin descriptor (plugInfo.json) or a directory containing one. A descriptor’s Includes are followed. Each ovx_string_t must remain valid until this call returns.
path_count – Number of entries in paths. Zero is a no-op.

Returns:

OVSTAGE_OK on success; OVSTAGE_ERROR_INVALID_ARGUMENT for a NULL paths with a non-zero path_count or an empty entry; OVSTAGE_ERROR_NOT_FOUND if an entry names no readable descriptor; OVSTAGE_ERROR_OP_FAILED if the call came too late (see below). Detail in ovstage_population_get_last_error. Both argument failures are checked before anything registers, so a rejected call leaves the process untouched and can be corrected and retried.

ovstage_population_enqueue_result_t ovstage_population_open_usd_from_file( ovstage_instance_t *stage, ovx_string_t path, ovstage_ordinal_t ordinal, double time, uint32_t domains )#

Enqueue an asynchronous operation to populate an ovstage instance from a USD file.

Replaces any USD content previously loaded into this ovstage with the contents of path. This both loads the USD and populates the ovstage in one operation. Initial population is one-shot; live edits made afterwards are picked up by ovstage_population_apply_usd_changes / ovstage_population_apply_usd_time.

Per-stage population state is created lazily on first use and released automatically when stage is destroyed.

Parameters:

stage – ovstage instance to populate into.
path – Filesystem path to a .usda / .usdc / .usd file, or an Omniverse Nucleus URL (omniverse://server/path.usd), as an ovx_string_t view.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time; a new instance’s floor is 0, so initial population starts at 1.
time – Time in seconds at which to evaluate attributes; converted to a USD time code via the stage’s timeCodesPerSecond.
domains – Bitmask of ovstage_population_domain_t selecting which data domains to populate. 0 (DOMAIN_NONE) populates nothing; pass OVSTAGE_POPULATION_DOMAIN_ALL for everything.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the stage cannot be populated, the file cannot be opened, or population failed — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_open_usd_from_string( ovstage_instance_t *stage, ovx_string_t usda, ovstage_ordinal_t ordinal, double time, uint32_t domains )#

Enqueue an asynchronous operation to populate an ovstage instance from an inline USDA string.

Same semantics as ovstage_population_open_usd_from_file but the USD content is provided directly as text instead of loaded from disk.

Parameters:

stage – ovstage instance to populate into.
usda – USDA content (e.g. “#usda 1.0\n…”) as an ovx_string_t view.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time; a new instance’s floor is 0, so initial population starts at 1.
time – Time in seconds; converted to a USD time code via the stage’s timeCodesPerSecond.
domains – Bitmask of ovstage_population_domain_t selecting which data domains to populate. 0 (DOMAIN_NONE) populates nothing; pass OVSTAGE_POPULATION_DOMAIN_ALL for everything.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the stage cannot be populated, the USDA content fails to parse, or population failed — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_open_usd_from_file_with_desc( ovstage_instance_t *stage, ovx_string_t path, ovstage_ordinal_t ordinal, double time, const ovstage_population_desc_t *descs, size_t desc_count )#

Enqueue an asynchronous operation to populate an ovstage instance from a USD file, with an explicit population description.

Identical to ovstage_population_open_usd_from_file except that what to populate is given as an array of ovstage_population_desc_t rather than a bare domains bitmask. A single desc that carries only domains is exactly the shorter entry point.

Parameters:

stage – ovstage instance to populate into.
path – Filesystem path to a .usda / .usdc / .usd file, or an Omniverse Nucleus URL (omniverse://server/path.usd), as an ovx_string_t view.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time; a new instance’s floor is 0, so initial population starts at 1.
time – Time in seconds at which to evaluate attributes; converted to a USD time code via the stage’s timeCodesPerSecond.
descs – Array of descriptions selecting what to populate; their domains are OR-ed together and their selectors combined. Must stay valid only until this call returns. May be NULL when desc_count is 0.
desc_count – Number of entries in descs. 0 (or a NULL descs) selects nothing, as OVSTAGE_POPULATION_DOMAIN_NONE does.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the stage cannot be populated, the file cannot be opened, or population failed — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_open_usd_from_string_with_desc( ovstage_instance_t *stage, ovx_string_t usda, ovstage_ordinal_t ordinal, double time, const ovstage_population_desc_t *descs, size_t desc_count )#

Enqueue an asynchronous operation to populate an ovstage instance from an inline USDA string, with an explicit population description.

Same semantics as ovstage_population_open_usd_from_file_with_desc but the USD content is provided directly as text instead of loaded from disk.

Parameters:

stage – ovstage instance to populate into.
usda – USDA content (e.g. “#usda 1.0\n…”) as an ovx_string_t view.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time; a new instance’s floor is 0, so initial population starts at 1.
time – Time in seconds; converted to a USD time code via the stage’s timeCodesPerSecond.
descs – Array of descriptions selecting what to populate; their domains are OR-ed together and their selectors combined. Must stay valid only until this call returns. May be NULL when desc_count is 0.
desc_count – Number of entries in descs. 0 (or a NULL descs) selects nothing, as OVSTAGE_POPULATION_DOMAIN_NONE does.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the stage cannot be populated, the USDA content fails to parse, or population failed — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_add_usd_reference_from_file( ovstage_instance_t *stage, ovx_string_t ref_file_path, ovx_string_t target_path, ovstage_population_usd_reference_handle_t *out_handle )#

Enqueue an asynchronous operation to add a USD file as a reference at target_path.

This edits only the USD source, additively — existing USD content is left untouched. The shape of the merge depends on target_path (see below): a new prim is defined and ref_file_path referenced on it, the reference is added onto an existing prim, or — for the root “/” — the content is merged in at the top level. Like ovstage_population_reset_usd, it does not itself touch the ovstage; call ovstage_population_apply_usd_changes afterwards to propagate the added subtree into the ovstage (at the time and domains already in effect from the initial _open_usd_*).

Requires existing population state: call one of the _open_usd_* entry points first. The enqueue is rejected (status) if this stage has never been populated.

Parameters:

stage – ovstage instance.
ref_file_path – Filesystem path to a .usda / .usdc / .usd file, or an Omniverse Nucleus URL (omniverse://server/path.usd), as an ovx_string_t view — the layer to reference.
target_path – Absolute path (starting with ‘/’) selecting how the content is merged, additively in every case:
- the root “/” — the content is merged in at the top level (its top-level prims are added to the stage without clobbering the existing stage’s units/upAxis/defaultPrim);
- an existing prim path — the reference is added onto that prim and the referenced subtree composes in beneath it; the prim and its prior content are left in place;
- a not-yet-existing prim path — a new prim is defined there (any missing ancestors are defined) and the layer referenced on it.
out_handle – [out, optional] Receives a handle for the added reference, reserved synchronously (valid before the op runs) for a later ovstage_population_remove_usd_reference. Set to OVSTAGE_POPULATION_INVALID_USD_REFERENCE_HANDLE if the enqueue is rejected. A non-invalid handle does not by itself mean the reference was added — await the op to confirm.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the file cannot be opened, or the target path is not a valid absolute path — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_add_usd_reference_from_string( ovstage_instance_t *stage, ovx_string_t ref_str, ovx_string_t target_path, ovstage_population_usd_reference_handle_t *out_handle )#

Enqueue an asynchronous operation to add inline USDA content as a reference at target_path.

Same semantics as ovstage_population_add_usd_reference_from_file but the USD content is provided directly as text instead of loaded from disk. The inline layer is held alive for as long as the reference exists (until ovstage_population_remove_usd_reference / _reset_usd / a fresh _open_usd_*).

Parameters:

stage – ovstage instance.
ref_str – USDA content (e.g. “#usda 1.0\n…”) as an ovx_string_t view — the layer to reference.
target_path – Absolute path (starting with ‘/’) selecting how the content is merged, additively in every case — the root “/” merges the content at the top level, an existing prim path adds the reference onto that prim, a not-yet-existing prim path defines a new prim there. See ovstage_population_add_usd_reference_from_file.
out_handle – [out, optional] Receives a handle for the added reference, reserved synchronously, for a later ovstage_population_remove_usd_reference. See ovstage_population_add_usd_reference_from_file.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue is reported in status; failures while the op runs — the USDA content fails to parse, or the target path is not a valid absolute path — are surfaced by ovstage_population_wait_op, with detail in ovstage_population_get_last_error.

ovstage_population_enqueue_result_t ovstage_population_remove_usd_reference( ovstage_instance_t *stage, ovstage_population_usd_reference_handle_t handle )#

Enqueue an asynchronous operation to remove a USD reference previously added by ovstage_population_add_usd_reference_from_file / _from_string.

This edits only the USD source, undoing exactly what the matching add introduced: a prim the add defined is removed whole (with its referenced subtree); a reference the add placed onto a pre-existing prim is removed on its own, leaving that prim and its prior content in place; a root “/” merge removes just the sublayer the add inserted. Like the add, it does not itself touch the ovstage; call ovstage_population_apply_usd_changes afterwards to propagate the removal (the affected prims are tombstoned out of the ovstage). For an inline (_from_string) reference this also releases the held layer. Carries no ordinal.

Parameters:

stage – ovstage instance.
handle – Handle returned by an add-reference call. Removing the same handle twice, or a handle whose add never completed, fails when the op runs.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue (invalid handle, or no population state) is reported in status; a run-time failure (unknown/already-removed handle, or the prim could not be removed) is surfaced by ovstage_population_wait_op.

ovstage_population_enqueue_result_t ovstage_population_reset_usd( ovstage_instance_t *stage )#

Enqueue an asynchronous operation to reset (clear) all USD source content from this stage.

Unlike the open entry points, which load and populate in one step, this edits only the USD source: call ovstage_population_apply_usd_changes afterwards to propagate the cleared state into the ovstage, or repopulate with ovstage_population_open_usd_from_file / _open_usd_from_string. Carries no ordinal.

Parameters:

stage – ovstage instance.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue (no population state) is reported in status; a run-time failure is surfaced by ovstage_population_wait_op.

ovstage_population_enqueue_result_t ovstage_population_apply_usd_time( ovstage_instance_t *stage, ovstage_ordinal_t ordinal, double time )#

Enqueue an asynchronous operation to advance the time and propagate time-sampled attribute changes into the ovstage.

Call once per simulation tick when playing back time-sampled USD content.

Samples time-sampled attributes from the latest USD state at time: their values are re-sampled from the current USD, so edits to an attribute’s time samples are reflected at the new time even if ovstage_population_apply_usd_changes has not been called since they were made.

Re-samples whatever the initial _open_usd_* put in scope, not only the domains it selected: a _with_desc open puts prims in scope through its selectors as well, so a description carrying selectors and domains == 0 is advanced like any other. Nothing outside that scope is written.

RENDERING — additional behavior: for the RENDERING domain this call also reflects pending structural USD edits (prim add/remove, and attribute or relationship changes that are not time samples) at the new time, even if ovstage_population_apply_usd_changes has not been called. Other domains advance time for time-sampled values only and leave such structural edits to be applied by ovstage_population_apply_usd_changes. This RENDERING-specific behavior is expected to converge with the other domains over time.

Parameters:

stage – ovstage instance.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time.
time – New time in seconds; converted to a USD time code via the stage’s timeCodesPerSecond.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue (no population state) is reported in status; a run-time failure is surfaced by ovstage_population_wait_op.

ovstage_population_enqueue_result_t ovstage_population_apply_usd_changes( ovstage_instance_t *stage, ovstage_ordinal_t ordinal )#

Enqueue an asynchronous operation to propagate any USD edits accumulated since the last call (including content emptied by ovstage_population_reset_usd) into the ovstage.

Intended for frame-coordinator pre-commit hooks: call once per tick before consumers read from the ovstage so any pending USD-side edits are visible. A no-op (returns success) when nothing has changed.

Honors the data domains selected by the initial _open_usd_*: only those domains’ edits are propagated.

Parameters:

stage – ovstage instance.
ordinal – Accumulating ordinal owned by the caller. Must be greater than the effective write floor at execution time.

Returns:

Enqueue result (see ovstage_population_enqueue_result_t). A rejected enqueue (no population state) is reported in status; a run-time failure is surfaced by ovstage_population_wait_op. A no-op (nothing changed) returns OVSTAGE_OK.

ovstage_api_status_t ovstage_population_wait_op( ovstage_instance_t *stage, ovstage_population_op_id_t op_id, ovstage_timeout_ns_t timeout_ns, ovstage_population_op_wait_result_t *out_wait_result )#

Wait for completion of all operations up to and including op_id, or until timeout_ns elapses.

Because the wait covers earlier operations too, any of them may be the one that failed — see out_wait_result.

timeout_ns = 0 polls; OVSTAGE_TIMEOUT_INFINITE blocks indefinitely.

Parameters:

stage – ovstage instance.
op_id – Operation id from a population enqueue result.
timeout_ns – Nanoseconds to wait; OVSTAGE_TIMEOUT_INFINITE blocks.
out_wait_result – [out, optional] Receives the ids of every op that failed within the awaited range and, on timeout, the lowest still-pending op id. May be NULL if the caller only needs the return code. See ovstage_population_op_wait_result_t.

Returns:

OVSTAGE_OK if the awaited op (and all ops before it) completed successfully.
OVSTAGE_ERROR_TIMEOUT if the range did not complete within timeout_ns.
OVSTAGE_ERROR_OP_FAILED if any op in the range failed; the failing ids are reported in out_wait_result, with per-op detail available from ovstage_population_get_last_op_error and the primary failure mirrored into ovstage_population_get_last_error.
OVSTAGE_ERROR_INVALID_ARGUMENT for an unknown op id (zero, or never enqueued), or when stage has no population state.

ovx_string_t ovstage_population_get_last_error(void)#

Returns the thread-local error string for the latest population call on this thread, regardless of which ovstage instance produced it.

For an op that failed asynchronously, this holds the primary failure only after ovstage_population_wait_op has observed it on this thread; for a rejected enqueue it is set on return. Valid until the next population call on the same thread. Returns {NULL, 0} when no error has been recorded.

ovx_string_t ovstage_population_get_last_op_error( ovstage_population_op_id_t op_id )#

Returns the human-readable error string for op_id, as reported by the last ovstage_population_wait_op call on this thread (i.e.

an op id listed in that call’s ovstage_population_op_wait_result_t::error_op_ids). Valid until the next ovstage_population_wait_op call on the same thread. Returns {NULL, 0} if op_id is not known to have failed on this thread.

struct ovstage_population_selector_t#

#include <ovstage_population.h>

One population selector: which prims are populated, and which of their properties and metadata.

Public Members

ovstage_population_prim_predicate_t prim_predicate#: Which prims this selector populates.

ovstage_population_property_predicate_t property_predicate#: Which properties of those prims are populated.

const ovx_string_t *prim_metadata_paths#

Metadata to populate for each selected prim, as paths: a metadata field name, extended with a :-joined key path to reach inside a dictionary field.

A path naming a dictionary rather than a single value populates every value beneath it, one attribute each. Populated as usd-metadata:<path>.

size_t prim_metadata_path_count#

const ovx_string_t *property_metadata_paths#

Metadata to populate for each selected property, as paths — same addressing and dictionary flattening as prim_metadata_paths.

Applies to every property property_predicate selects; use a further selector to populate a field for some properties only. Populated as <property>:usd-metadata:<path>.

size_t property_metadata_path_count#

struct ovstage_population_desc_t#

#include <ovstage_population.h>

A complete description of what to populate.

Zero-initialize, then set the fields you need. A desc with no selectors and domains set is exactly equivalent to passing that domains to the entry point without a desc; a desc with neither populates nothing.

Descs are supplied as an array and compose: domains is OR-ed across every desc, and their selectors are combined in array order.

The array, and everything it points at, must stay valid only until the call returns: the description is copied as the operation is enqueued.

Public Members

uint32_t domains#

Bitmask of ovstage_population_domain_t — built-in domains to populate alongside this desc’s selectors.

0 for selectors only.

const ovstage_population_selector_t *selectors#

The selectors that make up this description.

May be NULL when domains alone is wanted.

size_t selector_count#

const ovx_string_t *stage_metadata_paths#

Stage metadata to populate onto the root prim, as paths: a stage metadata field name, extended with a :-joined key path to reach inside a dictionary field — customLayerData:myTool:version.

A path naming a dictionary rather than a single value populates every value beneath it, one attribute each. A path that does not resolve populates nothing.

size_t stage_metadata_path_count#

struct ovstage_population_enqueue_result_t#

#include <ovstage_population.h>

Result of enqueuing a population operation.

Population runs asynchronously: status reports only that the operation was accepted (OVSTAGE_OK) and the work runs on a background worker — call ovstage_population_wait_op(op_id) to await completion and obtain the outcome (with detail via ovstage_population_get_last_error). op_index identifies the operation for ovstage_population_wait_op, or is OVSTAGE_POPULATION_INVALID_OP_ID if nothing was enqueued.

Public Members

ovstage_api_status_t status#

ovstage_population_op_id_t op_index#

struct ovstage_population_op_wait_result_t#

#include <ovstage_population.h>

Output of ovstage_population_wait_op.

Because a single wait covers all operations up to and including the awaited op, more than one op can have failed within that range. error_op_ids lists those failed op ids. Each failure is reported exactly once — by the first ovstage_population_wait_op call (on any thread) whose range covers it — so a later wait does not re-report it. For each id, retrieve the human-readable detail with ovstage_population_get_last_op_error.

The array (and the strings from ovstage_population_get_last_op_error) live in the calling thread’s storage and stay valid only until that same thread’s next ovstage_population_wait_op call, which overwrites them; copy anything you need to keep before calling again. Calls on different threads use independent buffers and do not clobber each other.

lowest_pending_op_id is meaningful only when the wait returns OVSTAGE_ERROR_TIMEOUT: it is the lowest op id in the awaited range that had not completed when the timeout elapsed (useful for partial-progress reporting). It is OVSTAGE_POPULATION_INVALID_OP_ID otherwise.

Public Members

const ovstage_population_op_id_t *error_op_ids#

size_t error_op_id_count#

ovstage_population_op_id_t lowest_pending_op_id#

Enums

enum ovstage_population_prim_predicate_kind_t#

How an ovstage_population_prim_predicate_t matches, and which member of its values union carries the value_count values it matches against.

A kind that takes values matches when any one of them matches: the values of a single predicate are a disjunction, never a conjunction. Requiring more than one condition is what OVSTAGE_POPULATION_PRIM_PREDICATE_AND is for.

Values:

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_NONE#: Matches no prim.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_ALL#

Matches every prim.

Takes no values.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_AND#: values.subpredicates: matches when every subpredicate matches.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_OR#: values.subpredicates: matches when any subpredicate matches.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_NOT#: values.subpredicates, exactly one: matches when it does not.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PARENT#: values.subpredicates, exactly one: matches when the prim’s parent does.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_ANCESTOR#: values.subpredicates, exactly one: matches when any ancestor does.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PROPERTY#: values.property_predicate, exactly one: matches when any property of the prim matches it.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_TYPE#: values.strings: the prim’s type name, matched exactly.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_IS_A_TYPE#: values.strings: the prim’s type name, or any type it derives from.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_SCHEMA#

values.strings: a schema the prim conforms to, matched exactly — its type name or one of its applied API schemas.

The form to use when a list of schema names mixes the two, which a schema family generally does.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_APPLIED_SCHEMA#: values.strings: an API schema applied to the prim, matched exactly — including the :instance suffix a multiple-apply schema carries.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_APPLIED_SCHEMA_IN_NAMESPACE#: values.strings: a namespace an applied API schema name is in, matched at : boundaries — PhysxJointAxisAPI matches every instance of it, such as PhysxJointAxisAPI:linear.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PATH#: values.strings: the prim’s absolute path, matched exactly.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_IS_UNDER_PATH#

values.strings: an absolute prim path the prim’s own path is at or beneath.

Matched at path-component boundaries, so /World/Env does not match /World/Environment. Does not match a prim inside a native instance.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_KIND#: values.strings: the prim’s model kind, matched exactly — a kind’s ancestors in the kind hierarchy are not considered.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PURPOSE#

values.strings: the prim’s purpose, as inherited down the tree — a prim under a guide scope has purpose guide.

A prim that is not imageable has no purpose and matches nothing.

enumerator OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_METADATA#

values.strings: a metadata path the prim resolves, in the same form prim_metadata_paths takes — a field name, extended with a :-joined key path to reach inside a dictionary field.

Presence, not value: a path resolving to false or 0 matches as much as one resolving to true.

Name a key, not a whole dictionary field. A field matches whenever anything resolves beneath it, including what a schema registers rather than the prim authoring it; customData:myTool:export selects the prims that carry that key.

enum ovstage_population_property_predicate_kind_t#

How an ovstage_population_property_predicate_t matches, and which member of its values union carries the value_count values it matches against.

A kind that takes values matches when any one of them matches: the values of a single predicate are a disjunction, never a conjunction. Requiring more than one condition is what OVSTAGE_POPULATION_PROPERTY_PREDICATE_AND is for.

Values:

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_NONE#: Matches no property.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_ALL#

Matches every property of an in-scope prim.

Takes no values.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_AND#: values.subpredicates: matches when every subpredicate matches.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_OR#: values.subpredicates: matches when any subpredicate matches.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_NOT#: values.subpredicates, exactly one: matches when it does not.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_DECLARED_BY_SCHEMA#

values.strings: the property’s name is declared by one of the named schemas.

Whether the prim carrying the property has that schema applied is not considered.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_HAS_NAME#: values.strings: the property’s name, matched exactly.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_IN_NAMESPACE#: values.strings: a namespace the property’s name is in, matched at : boundaries — material:binding matches material:binding:physics but not material:bindingStrength.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_HAS_METADATA#

values.strings: a metadata path the property resolves, in the same form property_metadata_paths takes.

Path form, presence, and the dictionary-field caveat are as for OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_METADATA.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_ATTRIBUTE#

Matches an attribute.

Takes no values.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_RELATIONSHIP#

Matches a relationship.

Takes no values.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_CUSTOM#

Matches a property carrying USD’s custom modifier, which marks ad hoc client data not formalized into a schema.

Takes no values.

enumerator OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_AUTHORED#

Matches a property carrying an authored opinion, as opposed to one resolving to its schema fallback.

Takes no values.

Functions

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_none( void )#

Predicate constructors — one per kind.

Each sets kind, the one values member that kind names, and value_count together, so no combination can be built wrongly. See the kind’s enumerator for what it matches.

A nested predicate is referenced, not copied: the object passed to _and, _or, _not, _has_parent, _has_ancestor, or _has_property must outlive the predicate built from it. OVSTAGE_POPULATION_PRIM_PREDICATE_NONE.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_all( void )#: OVSTAGE_POPULATION_PRIM_PREDICATE_ALL.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_and( const ovstage_population_prim_predicate_t *subpredicates, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_AND over value_count subpredicates.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_or( const ovstage_population_prim_predicate_t *subpredicates, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_OR over value_count subpredicates.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_not( const ovstage_population_prim_predicate_t *subpredicate )#: OVSTAGE_POPULATION_PRIM_PREDICATE_NOT over one subpredicate.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_parent( const ovstage_population_prim_predicate_t *subpredicate )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PARENT over one subpredicate.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_ancestor( const ovstage_population_prim_predicate_t *subpredicate )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_ANCESTOR over one subpredicate.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_property( const ovstage_population_property_predicate_t *property_predicate )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PROPERTY over one property predicate.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_type( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_TYPE over value_count type names.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_is_a_type( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_IS_A_TYPE over value_count type names.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_schema( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_SCHEMA over value_count schema names.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_applied_schema( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_APPLIED_SCHEMA over value_count schema names.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_applied_schema_in_namespace( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_APPLIED_SCHEMA_IN_NAMESPACE over value_count namespaces.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_path( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PATH over value_count paths.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_is_under_path( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_IS_UNDER_PATH over value_count paths.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_kind( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_KIND over value_count kinds.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_purpose( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PURPOSE over value_count purposes.

static inline ovstage_population_prim_predicate_t ovstage_population_prim_predicate_has_metadata( const ovx_string_t *paths, size_t path_count )#: OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_METADATA over value_count metadata paths.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_none( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_NONE.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_all( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_ALL.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_and( const ovstage_population_property_predicate_t *subpredicates, size_t value_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_AND over value_count subpredicates.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_or( const ovstage_population_property_predicate_t *subpredicates, size_t value_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_OR over value_count subpredicates.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_not( const ovstage_population_property_predicate_t *subpredicate )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_NOT over one subpredicate.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_declared_by_schema( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_DECLARED_BY_SCHEMA over value_count schema names.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_has_name( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_HAS_NAME over value_count names.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_in_namespace( const ovx_string_t *values, size_t value_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_IN_NAMESPACE over value_count namespaces.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_has_metadata( const ovx_string_t *paths, size_t path_count )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_HAS_METADATA over value_count metadata paths.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_is_attribute( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_ATTRIBUTE.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_is_relationship( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_RELATIONSHIP.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_is_custom( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_CUSTOM.

static inline ovstage_population_property_predicate_t ovstage_population_property_predicate_is_authored( void )#: OVSTAGE_POPULATION_PROPERTY_PREDICATE_IS_AUTHORED.

struct ovstage_population_prim_predicate_t#

#include <ovstage_population_predicate.h>

Which prims a selector puts in scope.

Zero-initialize, then set kind, the values member that kind names, and value_count. Several values of one kind match if any one of them does, so a list of schema names is a single predicate; combine different kinds with AND / OR / NOT. A property predicate nests here — as OVSTAGE_POPULATION_PRIM_PREDICATE_HAS_PROPERTY — so a prim can be gated on the properties it carries.

Public Members

ovstage_population_prim_predicate_kind_t kind#

const ovx_string_t *strings#

const ovstage_population_prim_predicate_t *subpredicates#

const ovstage_population_property_predicate_t *property_predicate#

union ovstage_population_prim_predicate_t values#

size_t value_count#

struct ovstage_population_property_predicate_t#

#include <ovstage_population_predicate.h>

Which of an in-scope prim’s properties a selector publishes.

Built the same way as ovstage_population_prim_predicate_t: kind names the live values member, and several values of one kind match if any one of them does.

Public Members

ovstage_population_property_predicate_kind_t kind#

const ovx_string_t *strings#

const ovstage_population_property_predicate_t *subpredicates#

union ovstage_population_property_predicate_t values#

size_t value_count#

Population Export (ovstage → USD)#

Selected current runtime state can be authored into a USD destination that ovstage opens and owns, without exposing OpenUSD C++ types through the C ABI. See Exporting ovstage to USD for destination ownership and persistence rules.

Defines

OVSTAGE_POPULATION_EXPORT_UNKNOWN_APPLIED_API_SCHEMAS_CUSTOM_DATA_KEY#: Custom-data key used to preserve an array of unresolved applied API schema names when unknown_metadata_policy is PRESERVE.

OVSTAGE_POPULATION_EXPORT_INVALID_DESTINATION_HANDLE#: Invalid/sentinel reusable export destination handle.

Typedefs

typedef uint64_t ovstage_population_export_destination_handle_t#: ABI-opaque handle for a reusable, source-stage-bound USD export destination.

Enums

enum ovstage_population_export_selection_t#

Selects the source-state class exported by a descriptor.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_SELECTION_EXPLICIT_PREDICATE#: Export the current committed ovstage state constrained by predicates and rules.

enumerator OVSTAGE_POPULATION_EXPORT_SELECTION_CHANGED_PROPERTIES_SINCE_ORDINAL#: Export properties dirtied in the open interval (since_ordinal, ordinal], intersected with the descriptor’s prim and property predicates.

enum ovstage_population_export_layer_mode_t#

Controls the authored USD prim specifier for newly materialized prim specs.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_LAYER_MODE_OVER#: Author sparse overlay opinions with SdfSpecifierOver.

enumerator OVSTAGE_POPULATION_EXPORT_LAYER_MODE_DEF#: Author durable definitions with SdfSpecifierDef.

enum ovstage_population_export_path_match_t#

How rule paths are compared against ovstage/USD prim paths.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_PATH_MATCH_EXACT#: Match one exact absolute prim path.

enumerator OVSTAGE_POPULATION_EXPORT_PATH_MATCH_PREFIX#: Match the path itself and all descendants under it.

enum ovstage_population_export_name_match_t#

How rule attribute-name patterns are compared against ovstage runtime names.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_NAME_MATCH_EXACT#: Match the exact attribute name.

enumerator OVSTAGE_POPULATION_EXPORT_NAME_MATCH_GLOB#: Match with simple glob wildcards accepted by the implementation.

enum ovstage_population_export_transform_policy_t#

How local transform attributes are emitted to USD.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_TRANSFORM_USD_XFORM_OP#: Prefer standard xformOp opinions such as xformOp:transform where possible.

enumerator OVSTAGE_POPULATION_EXPORT_TRANSFORM_NONE#: Do not export recognized transform attributes.

enumerator OVSTAGE_POPULATION_EXPORT_TRANSFORM_USD_MATRIX_OP#: Author local matrices as an explicit USD matrix transform op.

enum ovstage_population_export_unknown_metadata_policy_t#

Policy for selected source metadata whose USD schema or type cannot be resolved.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_UNKNOWN_METADATA_DROP#: Drop unknown metadata and continue.

enumerator OVSTAGE_POPULATION_EXPORT_UNKNOWN_METADATA_PRESERVE#: Preserve supported unknown metadata in a namespaced fallback where available.

enumerator OVSTAGE_POPULATION_EXPORT_UNKNOWN_METADATA_FAIL#: Fail the export when unknown selected metadata is encountered.

enum ovstage_population_export_source_api_schema_policy_t#

Controls whether effective applied API schemas recorded on source prims are authored on destination prims.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_SOURCE_API_SCHEMAS_EXPLICIT_ONLY#: Author only API schemas named by explicit api_schema_rules.

enumerator OVSTAGE_POPULATION_EXPORT_SOURCE_API_SCHEMAS_APPLY_RECORDED#: Also author each selected prim’s effective usd-schemas metadata.

enum ovstage_population_export_projection_t#

Controls automatic projection of source runtime attributes.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_PROJECTION_EXPLICIT_RULES#: Author only attributes named by explicit attribute_rules.

enumerator OVSTAGE_POPULATION_EXPORT_PROJECTION_SCHEMA_DECLARED#: Also author selected attributes declared by each prim’s effective USD schemas.

enum ovstage_population_export_rule_flags_t#

Per-rule behavior flags.

Flags may be ORed together.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_RULE_NONE#: No special behavior.

enumerator OVSTAGE_POPULATION_EXPORT_RULE_EXPORT_DEFAULT_VALUE#: Export a selected attribute even when the value equals the USD default/fallback.

enumerator OVSTAGE_POPULATION_EXPORT_RULE_DERIVED_ALLOWED#: Allow schema-derived type resolution instead of requiring an exact explicit type.

enumerator OVSTAGE_POPULATION_EXPORT_RULE_INFER_CUSTOM_TYPE#: Infer a custom USD value type from the ovstage runtime tensor shape/type.

enumerator OVSTAGE_POPULATION_EXPORT_RULE_REQUIRED#: Treat a missing, unsupported, or non-authoring rule as an export error.

enum ovstage_population_export_property_kind_t#

USD property kind authored by a property-edge rule.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_PROPERTY_INVALID#

Invalid sentinel.

Zero-initialized property rules are rejected; callers must select RELATIONSHIP, CONNECTION, or MATERIAL_BINDING explicitly.

enumerator OVSTAGE_POPULATION_EXPORT_PROPERTY_RELATIONSHIP#: Author a UsdRelationship target list.

enumerator OVSTAGE_POPULATION_EXPORT_PROPERTY_CONNECTION#: Author an attribute connection target list.

enumerator OVSTAGE_POPULATION_EXPORT_PROPERTY_MATERIAL_BINDING#

Author the material:binding relationship.

Other binding names are unsupported.

enum ovstage_population_export_metadata_kind_t#

Destination kind for a metadata rule.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_METADATA_PRIM#: Author metadata on matching prim specs.

enumerator OVSTAGE_POPULATION_EXPORT_METADATA_LAYER_CUSTOM_DATA#: Author entries into layer customData.

enumerator OVSTAGE_POPULATION_EXPORT_METADATA_REFERENCES#: Author selected asset references on matching prim specs.

enumerator OVSTAGE_POPULATION_EXPORT_METADATA_LAYER_STANDARD#: Author known layer-level metadata such as defaultPrim or documentation.

enum ovstage_population_export_destination_mode_t#

Controls the initial contents of a persistent USD export destination.

Values:

enumerator OVSTAGE_POPULATION_EXPORT_DESTINATION_EMPTY#

Start from an empty in-memory USD stage.

Existing stored content is not read and is replaced only when the destination is explicitly saved.

enumerator OVSTAGE_POPULATION_EXPORT_DESTINATION_OPEN_EXISTING#

Open and preserve an existing USD layer stack.

Export opinions are authored into its root layer without flattening composed content.

Functions

ovstage_api_status_t ovstage_population_export_desc_init( ovstage_population_export_desc_t *desc )#

Initialize an export descriptor with conservative defaults.

The descriptor selects explicit-predicate export in OVER mode, authors recognized transforms as USD xform ops, and drops metadata whose USD type is unknown.

Parameters:

desc – [out] Descriptor to initialize.

Returns:

OVSTAGE_OK on success or OVSTAGE_ERROR_INVALID_ARGUMENT when desc is null.

ovstage_api_status_t ovstage_population_export_desc_init_snapshot( ovstage_population_export_desc_t *desc, ovstage_ordinal_t ordinal )#

Initialize a current-snapshot descriptor for an ordinal.

Applies the defaults from ovstage_population_export_desc_init, then records the expected current ordinal. Both predicates retain their ALL defaults.

Parameters:

desc – [out] Descriptor to initialize.
ordinal – Current committed ordinal expected by the caller.

Returns:

OVSTAGE_OK on success or OVSTAGE_ERROR_INVALID_ARGUMENT when desc is null.

static inline ovstage_api_status_t ovstage_population_export_desc_init_typed_hierarchy( ovstage_population_export_desc_t *desc, ovstage_ordinal_t ordinal, const ovx_string_t *root_path )#

Initialize a typed DEF-hierarchy export descriptor rooted at one USD path.

Applies current-snapshot defaults, selects root_path and its descendants, applies recorded API schemas, and projects schema-declared attributes. Callers may refine the returned descriptor before exporting.

The caller-owned ovx_string_t object and the character bytes referenced by that view are retained by the descriptor. They must outlive a synchronous export call or, for asynchronous export, successful enqueue; the enqueue then copies them.

Parameters:

desc – [out] Descriptor to initialize.
ordinal – Current committed ordinal expected by the caller.
root_path – Root USD path to select, retained by the descriptor.

Returns:

OVSTAGE_OK on success or the status from ovstage_population_export_desc_init_snapshot.

ovstage_api_status_t ovstage_population_export_destination_create( ovstage_instance_t *stage, ovx_string_t usd_identifier, ovstage_population_export_destination_mode_t mode, ovstage_population_export_destination_handle_t *out_destination )#

Create a reusable USD export destination and wait for initialization.

The destination is bound to stage, which must outlive it. Exactly one active destination may own a canonical USD identifier in this process. Creation never writes storage. EMPTY starts from an empty private stage; OPEN_EXISTING fails unless the identifier can be opened and preserves its layer stack while selecting the root layer as the edit target.

Parameters:

stage – Source ovstage instance and owner of destination ordering.
usd_identifier – Local path or resolver identifier for later save.
mode – Initial-content policy.
out_destination – [out] Receives the destination handle on success and the invalid handle on failure.

Returns:

OVSTAGE_OK on success or an ovstage_api_status_t error code.

ovstage_population_enqueue_result_t ovstage_population_export_destination_enqueue_create( ovstage_instance_t *stage, ovx_string_t usd_identifier, ovstage_population_export_destination_mode_t mode, ovstage_population_export_destination_handle_t *out_destination )#

Enqueue creation of a reusable USD export destination.

The handle is reserved synchronously and remains usable for later operations enqueued on the same stage. Those operations execute after initialization on the per-instance population FIFO. A non-invalid handle does not mean that opening succeeded; await the returned operation to observe its outcome. The identifier is copied before this function returns.

Parameters:

stage – Source ovstage instance and owner of destination ordering.
usd_identifier – Local path or resolver identifier for later save.
mode – Initial-content policy.
out_destination – [out] Receives the reserved destination handle, or the invalid handle when enqueue is rejected.

Returns:

Enqueue result for ovstage_population_export_wait_op.

ovstage_api_status_t ovstage_population_export_to_destination( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination, const ovstage_population_export_desc_t *desc, ovstage_population_export_report_t *report )#

Export into a reusable destination and wait for completion.

Successful calls accumulate opinions in the destination without saving. Failure leaves the destination at its previously committed in-memory state. The handle must have been created for the same stage.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.
desc – Export descriptor. The caller retains ownership.
report – [out, optional] Receives counters for this export only.

Returns:

OVSTAGE_OK on success or an ovstage_api_status_t error code.

ovstage_population_enqueue_result_t ovstage_population_export_enqueue_to_destination( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination, const ovstage_population_export_desc_t *desc )#

Enqueue export into a reusable destination.

The descriptor graph is copied before return. Work is ordered with create, prior exports, save, and destroy operations on the same source stage. Retrieve the report with ovstage_population_export_wait_op.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.
desc – Export descriptor; the complete graph is copied before return.

Returns:

Enqueue result for ovstage_population_export_wait_op.

ovstage_api_status_t ovstage_population_export_destination_save( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination )#

Persist the complete current destination and wait for completion.

A successful save replaces storage at the captured identifier and leaves the destination open for later export and save calls. .usd, .usda, .usdc, and other resolver/file-format identifiers supported by this OpenUSD build are passed through to OpenUSD. Save is explicit; export and destroy never persist implicitly. OpenUSD does not provide a portable atomic-replacement guarantee, so a failed save may have modified storage.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.

Returns:

OVSTAGE_OK on success or an ovstage_api_status_t error code.

ovstage_population_enqueue_result_t ovstage_population_export_destination_enqueue_save( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination )#

Enqueue explicit persistence of the complete current destination.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.

Returns:

Enqueue result for ovstage_population_export_wait_op.

ovstage_api_status_t ovstage_population_export_destination_destroy( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination )#

Destroy a reusable destination without saving and wait for completion.

Already-enqueued work completes first. No new work is accepted after destroy is submitted, and the handle is invalid after completion.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.

Returns:

OVSTAGE_OK on success or an ovstage_api_status_t error code.

ovstage_population_enqueue_result_t ovstage_population_export_destination_enqueue_destroy( ovstage_instance_t *stage, ovstage_population_export_destination_handle_t destination )#

Enqueue ordered destruction of a reusable destination without saving.

Parameters:

stage – Source ovstage instance that owns the destination.
destination – Reusable destination created for stage.

Returns:

Enqueue result for ovstage_population_export_wait_op.

ovstage_api_status_t ovstage_population_export_to_usd_file( ovstage_instance_t *stage, ovx_string_t usd_identifier, const ovstage_population_export_desc_t *desc, ovstage_population_export_report_t *report )#

Export one snapshot to durable USD storage.

Convenience equivalent to creating an EMPTY destination, exporting once, saving, and destroying it. The destination is replaced on successful save.

Parameters:

stage – Source ovstage instance and owner of operation ordering.
usd_identifier – Local path or resolver identifier to replace.
desc – Export descriptor. The caller retains ownership.
report – [out, optional] Receives counters for this export.

Returns:

OVSTAGE_OK on success or an ovstage_api_status_t error code.

ovstage_population_enqueue_result_t ovstage_population_export_enqueue_to_usd_file( ovstage_instance_t *stage, ovx_string_t usd_identifier, const ovstage_population_export_desc_t *desc )#

Enqueue the one-shot EMPTY export-and-save convenience operation.

The descriptor graph and identifier are copied before return. Retrieve the export report with ovstage_population_export_wait_op.

Parameters:

stage – Source ovstage instance and owner of operation ordering.
usd_identifier – Local path or resolver identifier to replace.
desc – Export descriptor; the complete graph is copied before return.

Returns:

Enqueue result for ovstage_population_export_wait_op.

ovstage_api_status_t ovstage_population_export_wait_op( ovstage_instance_t *stage, ovstage_population_op_id_t op_id, ovstage_timeout_ns_t timeout_ns, ovstage_population_export_report_t *report )#

Wait for an asynchronous export operation and consume its stored result.

The wait fences every ovpopulation operation through op_id. A timeout leaves the result available for a later wait and does not cancel work. This function accepts operations returned by async export, destination create, destination save, and destination destroy functions. A terminal wait consumes the result; a second export wait for the same id is invalid. Generic ovstage_population_wait_op may be used first as a fence without consuming this result. Every accepted operation from this header must eventually receive a terminal call to this function; abandoning it retains its result and any destination keepalive until the ovstage instance is destroyed.

Parameters:

stage – ovstage instance.
op_id – Operation id returned by an async function in this header.
timeout_ns – Maximum wait duration, or OVSTAGE_TIMEOUT_INFINITE.
report – [out, optional] Receives the final export report after terminal completion; lifecycle operations return a zeroed report. Zeroed before waiting and on timeout.

Returns:

OVSTAGE_OK on successful completion, OVSTAGE_ERROR_TIMEOUT while work remains pending, the operation failure status when execution failed, or OVSTAGE_ERROR_INVALID_ARGUMENT for an unknown, consumed, or unrelated operation id.

struct ovstage_population_export_attribute_rule_t#

#include <ovstage_population_export.h>

Attribute export rule.

Use this rule to map one or more ovstage runtime attributes to USD attributes. Empty path means every selected prim. Empty destination_attribute_name reuses source_attribute_name. Empty usd_type_name asks the exporter to use the destination schema/existing USD attribute type, or infer a custom type when OVSTAGE_POPULATION_EXPORT_RULE_INFER_CUSTOM_TYPE is set.

Public Members

ovx_string_t path#: Prim path selector; empty means all selected prims.

ovstage_population_export_path_match_t path_match#: Exact or prefix path matching mode for path.

ovx_string_t source_attribute_name#: ovstage runtime attribute name or glob pattern to read.

ovstage_population_export_name_match_t source_attribute_name_match#: Exact/glob matching mode for source_attribute_name.

ovx_string_t destination_attribute_name#: USD attribute name to author; empty reuses source_attribute_name.

ovx_string_t usd_type_name#: USD value type name to author; empty uses schema/destination/inference.

ovx_string_t required_schema_name#: Optional required schema name used when resolving schema-defined attribute types.

uint32_t flags#: Bitmask of ovstage_population_export_rule_flags_t.

struct ovstage_population_export_prim_rule_t#

#include <ovstage_population_export.h>

Prim export rule.

Use this rule to force creation of USD prim specs and, in DEF mode, to supply or override the authored USD type name. Prefix rules author each selected runtime prim under the prefix.

Public Members

ovx_string_t path#: Prim path selector.

ovstage_population_export_path_match_t path_match#: Exact or prefix path matching mode for path.

ovx_string_t usd_type_name#: USD prim type name to author; empty preserves/infer source type where available.

ovx_string_t unknown_type_metadata_key#: Optional metadata key used to preserve unknown type names when policy permits.

struct ovstage_population_export_api_schema_rule_t#

#include <ovstage_population_export.h>

Applied API schema export rule.

Use this rule to apply a USD API schema to matching prims. Multiple-apply API schemas use instance_name; single-apply schemas leave it empty.

Public Members

ovx_string_t path#: Prim path selector.

ovstage_population_export_path_match_t path_match#: Exact or prefix path matching mode for path.

ovx_string_t schema_name#: API schema type name to apply, such as “PhysicsRigidBodyAPI”.

ovx_string_t instance_name#: Multiple-apply instance name; empty for single-apply schemas.

uint32_t flags#: Bitmask of ovstage_population_export_rule_flags_t.

struct ovstage_population_export_property_edge_rule_t#

#include <ovstage_population_export.h>

Property-target export rule.

Relationship and material-binding rules read target paths from the runtime attribute named by source_property_name. Connection rules read target paths from the companion runtime attribute named “<source_property_name>.connect”. The source attributes must use the corresponding relationship-path or connection-path semantic. Empty path means every selected prim. Empty destination_property_name reuses source_property_name.

Public Members

ovx_string_t path#: Prim path selector; empty means all selected prims.

ovstage_population_export_path_match_t path_match#: Exact or prefix path matching mode for path.

ovx_string_t source_property_name#: Runtime property name whose target-path attribute is read.

ovx_string_t destination_property_name#: USD relationship or attribute name to author; empty reuses source_property_name.

ovx_string_t usd_type_name#: USD value type for connection attributes; ignored for relationships.

ovstage_population_export_property_kind_t property_kind#: Property kind to author.

uint32_t flags#: Bitmask of ovstage_population_export_rule_flags_t.

struct ovstage_population_export_metadata_rule_t#

#include <ovstage_population_export.h>

Metadata export rule.

Use this rule to map ovstage metadata attributes to USD prim metadata, layer metadata/customData, or references. Empty path means every selected prim for prim-scoped metadata; layer-scoped metadata ignores path.

Public Members

ovx_string_t path#: Prim path selector for prim-scoped metadata; empty means all selected prims.

ovstage_population_export_path_match_t path_match#: Exact or prefix path matching mode for path.

ovx_string_t source_metadata_name#: ovstage metadata attribute name to read.

ovx_string_t destination_metadata_name#: USD metadata/customData key to author; empty reuses source_metadata_name.

ovstage_population_export_metadata_kind_t metadata_kind#: Metadata destination kind.

uint32_t flags#: Bitmask of ovstage_population_export_rule_flags_t.

struct ovstage_population_export_desc_t#

#include <ovstage_population_export.h>

USD export descriptor.

Public Members

uint32_t struct_size#

Must be sizeof(ovstage_population_export_desc_t) for this header revision.

This is not an automatic compatibility mode for old layouts.

ovstage_population_export_source_api_schema_policy_t source_api_schema_policy#: Policy for applied API schemas recorded on source prims.

ovstage_population_export_projection_t projection#: Policy for automatic projection of source runtime attributes.

ovstage_ordinal_t ordinal#

Current committed ordinal expected by the caller.

Export queries the current topology and rejects stale or future ordinals instead of silently exporting a different source state.

ovstage_ordinal_t since_ordinal#: Lower bound for CHANGED_PROPERTIES_SINCE_ORDINAL; exports the open interval (since_ordinal, ordinal].

ovstage_population_export_selection_t selection#

ovstage_population_export_layer_mode_t layer_mode#

ovstage_population_export_transform_policy_t transform_policy#

ovstage_population_export_unknown_metadata_policy_t unknown_metadata_policy#

ovstage_population_prim_predicate_t prim_predicate#

Which runtime prims are candidates for export.

Defaults to ALL.

Export supports NONE, ALL, AND, OR, NOT, HAS_TYPE, IS_A_TYPE, HAS_SCHEMA, HAS_APPLIED_SCHEMA, HAS_APPLIED_SCHEMA_IN_NAMESPACE, HAS_PATH, and IS_UNDER_PATH. Other declared kinds require USD semantics not preserved by the public runtime representation and are rejected atomically with OVSTAGE_ERROR_NOT_SUPPORTED.

ovstage_population_property_predicate_t property_predicate#

Which runtime properties are candidates for property-scoped export rules and schema-declared projection.

Defaults to ALL. Prim rules, applied-schema rules, and prim/layer metadata rules are governed only by prim_predicate.

Export supports NONE, ALL, AND, OR, NOT, DECLARED_BY_SCHEMA, HAS_NAME, IN_NAMESPACE, IS_ATTRIBUTE, and IS_RELATIONSHIP. Other declared kinds are rejected atomically with OVSTAGE_ERROR_NOT_SUPPORTED.

const ovstage_population_export_prim_rule_t *prim_rules#

Each descriptor array below is limited to 4096 entries.

Counts above that limit are rejected before an array is read or retained.

size_t prim_rule_count#

const ovstage_population_export_api_schema_rule_t *api_schema_rules#

size_t api_schema_rule_count#

const ovstage_population_export_attribute_rule_t *attribute_rules#

size_t attribute_rule_count#

const ovstage_population_export_property_edge_rule_t *property_rules#

size_t property_rule_count#

const ovstage_population_export_metadata_rule_t *metadata_rules#

size_t metadata_rule_count#

struct ovstage_population_export_report_t#

#include <ovstage_population_export.h>

Export diagnostic counters.

Counters are best-effort progress diagnostics, not a stable ABI for behavioral decisions.

Public Members

size_t prims_examined#

size_t prims_exported#

size_t prims_skipped#

size_t attributes_examined#

size_t attributes_exported#

size_t attributes_skipped#

size_t attributes_unsupported#

size_t api_schemas_examined#

size_t api_schemas_applied#

size_t api_schemas_skipped#

size_t custom_attributes_inferred#

size_t unknown_metadata_preserved#

size_t transforms_examined#

size_t transforms_exported#

size_t property_edges_examined#

size_t property_edges_exported#

size_t property_edges_skipped#

size_t property_edges_unsupported#

size_t metadata_examined#

size_t metadata_exported#

size_t metadata_skipped#

size_t metadata_unsupported#

size_t source_states_unavailable#: Export could not read the requested current source ordinal.

Instancing #

High-level instancing queries.

Functions

ovstage_api_status_t ovstage_instancing_get_instance_roots( ovstage_instance_t *instance, ovx_primpath_t prototype_root, ovx_primpath_list_t *out_instance_roots )#

Return all instance-root prim paths that reference prototype_root.

Parameters:

instance – ovstage instance.
prototype_root – Prototype-root prim path.
out_instance_roots – Receives a path-list handle. The list may be empty when no instance roots reference prototype_root.

Returns:

OVSTAGE_OK on success.

ovstage_api_status_t ovstage_instancing_get_prototype_root( ovstage_instance_t *instance, ovx_primpath_t instance_root, ovx_primpath_t *out_prototype_root )#

Return the prototype root referenced by instance_root.

Parameters:

instance – ovstage instance.
instance_root – Instance-root prim path.
out_prototype_root – Receives the prototype-root prim path.

Returns:

OVSTAGE_OK on success, OVSTAGE_ERROR_NOT_FOUND when the prim is not an instance root.

ovstage_api_status_t ovstage_instancing_get_prototype_roots( ovstage_instance_t *instance, ovx_primpath_list_t *out_prototype_roots )#

Return all prototype-root prim paths.

Parameters:

instance – ovstage instance.
out_prototype_roots – Receives a path-list handle. The list may be empty when the stage contains no scene-graph instancing prototypes.

Returns:

OVSTAGE_OK on success.

API Types and Utilities #

ovstage_api — vtable-based contract for asynchronous, ordinal-keyed zero-copy simulation data access.

ovstage_api provides a unified C API for reading, writing, and managing simulation data (transforms, velocities, materials, metadata) across CPU and GPU memory. It is the abstract contract that various stage implementations can provide.

Consumers receive an ovstage_instance_t* (vtable + context) and invoke functions either directly through the vtable, via the core convenience wrappers in ovstage_api_utils.h, or via sibling extension APIs such as ovstage_instancing.h.

Functions

ovx_string_t ovstage_get_last_error(void)#

Get the error string for the latest synchronous API call on the calling thread.

Free function (no instance), because the error state is thread-local rather than per-instance: each thread observes its own most-recent synchronous error, regardless of which ovstage_instance_t produced it. If two instances are driven from the same thread, the most recent failure wins. Crucially, this can be called when ovstage_create_instance itself failed and no instance exists. Valid until the next API call on the same thread. Returns {NULL, 0} when no error has been recorded.

Mirrors ovstage_population_get_last_error(void).

struct ovstage_vtable_t#

#include <ovstage_api.h>

Vtable defined in ovstage_api.h.

Public Members

ovstage_api_status_t (*wait_op)(ovstage_context_t *instance, ovstage_op_id_t op_id, ovstage_timeout_ns_t timeout, ovstage_op_wait_result_t *out_wait_result)#

Wait for completion of an enqueued operation, with timeout.

Blocks until the operation identified by op_id (and any operations it transitively depends on under the ordinal-keyed ordering rules) has completed, or until timeout elapses. timeout = 0 makes this a non-blocking poll. OVSTAGE_TIMEOUT_INFINITE blocks indefinitely. Operations in unrelated ordinal buckets may still be in flight when this call returns OVSTAGE_OK.

On return, out_wait_result->error_op_ids lists ops observed to have failed since the previous wait_op call on this thread. For each id, the error string can be retrieved via get_last_op_error. The list and strings are transient thread-local data, invalidated by the next wait_op call on the same thread.

ovstage_api_status_t (*release_op)(ovstage_context_t *instance, ovstage_op_id_t op_id)#

Release tracking state associated with an op id (synchronous).

Safe to call once the op is known to have completed. After this call the op id may not be used again with wait_op or get_last_op_error.

ovstage_enqueue_result_t (*advance_write_floor)(ovstage_context_t *instance, const ovstage_write_floor_desc_t *desc)#

Enqueue a write-floor advance with scope control.

desc->scope selects the attributes affected:

SCOPE_ALL: advance the global write floor and every known attribute.
SCOPE_INCLUDE: advance only the listed attributes.
SCOPE_EXCLUDE: advance every known attribute EXCEPT the listed ones. With an empty attribute list, SCOPE_EXCLUDE behaves like SCOPE_ALL.

Advances clamp to the current value (max), so they never regress and a non-monotonic ordinal is a no-op rather than an error.

Param instance:: Implementation context.
Param desc:: Write-floor advance descriptor.
Return:: Enqueue result with status + op_index.

ovstage_enqueue_result_t (*get_oldest_preserved_ordinal)(ovstage_context_t *instance, ovstage_ordinal_query_handle_t *out_handle)#

Enqueue a query for the inclusive retained-history frontier.

Ordinal queries at or above the returned frontier are exact. Older history may have been coalesced or discarded.

Remark

In the current implementation, this is the exact change-membership frontier. Payload reads remain latest-snapshot and return the latest retained payload or tombstone.

ovstage_enqueue_result_t (*get_attribute_write_floor)(ovstage_context_t *instance, ovx_string_or_token_t attribute, ovstage_ordinal_query_handle_t *out_handle)#

Enqueue a query for the write floor of a specific attribute.

Pass an empty attribute ({.token = 0, .string = {NULL, 0}}) to query the global write floor (minimum across all known attributes).

ovstage_api_status_t (*fetch_ordinal)(ovstage_context_t *instance, ovstage_ordinal_query_handle_t handle, ovstage_timeout_ns_t timeout, ovstage_ordinal_t *out_ordinal)#

Fetch the scalar result of any enqueued ordinal query.

Return:: OVSTAGE_OK on success, OVSTAGE_ERROR_TIMEOUT if not ready within timeout, OVSTAGE_ERROR_OP_FAILED if the underlying enqueue failed.

ovstage_enqueue_result_t (*release_ordinal_query)(ovstage_context_t *instance, ovstage_ordinal_query_handle_t handle)#

Enqueue release of an ordinal-query handle.

Per-handle ordered: the release waits for any in-flight fetch on the same handle to complete before reclaiming resources.

ovstage_enqueue_result_t (*query)(ovstage_context_t *instance, const ovstage_filter_t *filter, const ovx_token_t *attrs, size_t attr_count, ovstage_query_handle_t *out_query_handle)#

Enqueue a query of prims matching a filter, optionally discovering attributes for the matched set.

The returned query handle is reserved synchronously. Reading the discovered attribute list and total prim count requires a subsequent fetch_query_result call.

ovstage_api_status_t (*query_from_path_list)(ovstage_context_t *instance, ovx_primpath_list_t path_list, ovstage_query_handle_t *out_handle)#

Create a query handle from an explicit prim path list.

Synchronous.

The returned handle wraps a caller-owned, interned prim path list and does not require evaluation against the stage. It may be used immediately as input to any enqueue.

ovstage_api_status_t (*fetch_query_result)(ovstage_context_t *instance, ovstage_query_handle_t query_handle, ovstage_timeout_ns_t timeout, ovstage_query_result_t *out_result)#

Fetch the result (discovered attributes + summary) of a prior query enqueue.

Pointers in *out_result are valid until release_query_result.

Return:: OVSTAGE_OK on success, OVSTAGE_ERROR_TIMEOUT if not ready within timeout, OVSTAGE_ERROR_OP_FAILED if the underlying enqueue failed.

ovstage_api_status_t (*release_query_result)(ovstage_context_t *instance, const ovstage_query_result_t *result)#

Release a query result payload (synchronous).

After this call, the attributes array in *result is invalid. The query handle itself remains valid and must be released separately via release_query.

ovstage_enqueue_result_t (*release_query)(ovstage_context_t *instance, ovstage_query_handle_t handle)#

Enqueue release of a query handle.

Per-handle ordered: the release waits for any in-flight read/write/ map/delete enqueued against the same handle to complete before reclaiming resources.

ovstage_enqueue_result_t (*read_attributes)(ovstage_context_t *instance, ovstage_query_handle_t handle, const ovx_token_t *attrs, size_t attr_count, ovstage_ordinal_range_t range, ovstage_read_handle_t *out_read_handle)#: Enqueue a multi-attribute read.

ovstage_api_status_t (*fetch_read_next)(ovstage_context_t *instance, ovstage_read_handle_t read_handle, ovstage_timeout_ns_t timeout, ovstage_read_group_t *out_group)#

Fetch the next read result group, with timeout.

Return:: OVSTAGE_OK on success, OVSTAGE_ERROR_END_OF_ITERATION when no more groups, OVSTAGE_ERROR_TIMEOUT if the next group is not ready within timeout, OVSTAGE_ERROR_OP_FAILED if the underlying enqueue failed. When a deferred read is rejected, the producer’s own status (for example OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION or OVSTAGE_ERROR_OUT_OF_RANGE) is reported once that producer has completed; a fetch that is itself waiting on the producer reports OVSTAGE_ERROR_OP_FAILED instead. Ready queries are validated at enqueue and report the typed status from read_attributes.
Post:: On OVSTAGE_OK, the group is independently valid until release_group.

ovstage_api_status_t (*release_group)(ovstage_context_t *instance, const ovstage_read_group_t *group)#

Release a read group’s pinned storage (synchronous).

Thread-safe; groups can be released in any order from any thread.

ovstage_enqueue_result_t (*release_read)(ovstage_context_t *instance, ovstage_read_handle_t read_handle)#

Enqueue release of a read handle.

Per-handle ordered: the release waits for any in-flight fetch_read_next call on the same handle to complete before reclaiming resources.

ovstage_enqueue_result_t (*write_attribute)(ovstage_context_t *instance, ovstage_query_handle_t handle, ovx_string_or_token_t attribute, ovstage_ordinal_t ordinal, ovstage_write_data_t data, ovstage_prim_mode_t prim_mode)#

Enqueue a write of attribute values for prims identified by a query handle.

This is implemented as a one-entry write_attributes call. Write-entry, tensor-layout, and attribute-schema errors that can be proven during common preflight are therefore returned synchronously with an invalid op_index; failures that require pending-query resolution or execution remain observable through wait_op. When multiple inputs are independently invalid, callers must not rely on error precedence; common preflight currently validates prim_mode before query-handle readiness and ordinal admission.

Param instance:: Implementation context.
Param handle:: Query handle identifying target prims.
Param attribute:: Attribute to write.
Param ordinal:: Ordinal for this write (must be > write floor at execution time). Writes sharing this ordinal execute in submission order; writes at other ordinals are independent.
Param data:: Write payload (tensors + cuda_sync + mask/index_map).
Param prim_mode:: UPSERT (default) or INSERT.
Return:: Enqueue result with status + op_index. A synchronous preflight failure has an invalid op_index. After a successful enqueue, failures discovered only during pending-query resolution, state-race revalidation, or backend execution are surfaced through wait_op + get_last_op_error.

ovstage_enqueue_result_t (*map_attribute)(ovstage_context_t *instance, ovstage_query_handle_t handle, const ovstage_map_desc_t *desc, ovstage_ordinal_t ordinal, const size_t *element_sizes, size_t element_count, ovstage_map_handle_t *out_map_handle)#

Enqueue a zero-copy map session for writing an attribute.

The returned map handle is reserved synchronously and may immediately be used with subsequent fetch_map_next / unmap_* calls.

Param instance:: Implementation context.
Param handle:: Query handle identifying target prims.
Param desc:: Map descriptor (attribute, dtype, semantic, prim_mode). See ovstage_map_desc_t.
Param ordinal:: Ordinal for this map session (must be > write floor at execution time). Map commits sharing this ordinal execute in submission order; those at other ordinals are independent.
Param element_sizes:: For array (variable-size) attributes, the per-prim element count: element_sizes[i] is the number of array elements to allocate for the i-th prim in handle’s prim set. This lets the implementation pre-allocate the ragged backing storage before handing back writable groups. Pass NULL for fixed-size (scalar / fixed-tuple) attributes, whose per-element footprint comes from the existing column type, or from desc.dtype when the column is being created.
Param element_count:: Number of entries in element_sizes. When element_sizes is non-NULL it must equal the number of prims in handle’s prim set; pass 0 when element_sizes is NULL.
Param out_map_handle:: Receives the reserved map handle.
Return:: Enqueue result with status + op_index.

ovstage_api_status_t (*fetch_map_next)(ovstage_context_t *instance, ovstage_map_handle_t map_handle, ovstage_timeout_ns_t timeout, ovstage_map_group_t *out_group)#: Fetch the next writable map group, with timeout.

ovstage_enqueue_result_t (*unmap_group)(ovstage_context_t *instance, ovstage_map_handle_t map_handle, const ovstage_map_group_t *group, ovstage_cuda_sync_t write_done_sync)#

Enqueue commit of a single map group (streaming commit).

Executes in the session’s ordinal bucket; ordered relative to other writes/deletes/map commits at the session’s ordinal.

ovstage_enqueue_result_t (*unmap_attribute)(ovstage_context_t *instance, ovstage_map_handle_t map_handle, ovstage_cuda_sync_t write_done_sync)#

Enqueue commit of all remaining groups and release of the map handle.

After the enqueued op executes, the map handle is no longer valid.

ovstage_enqueue_result_t (*delete_attributes)(ovstage_context_t *instance, ovstage_query_handle_t handle, const ovx_string_or_token_t *attributes, size_t attribute_count, ovstage_ordinal_t ordinal)#

Enqueue a delete (tombstone) of attributes on prims at a given ordinal.

Param instance:: Implementation context.
Param handle:: Query handle identifying target prims.
Param attributes:: List of attributes to delete. Empty list = delete entire prims (all attributes).
Param attribute_count:: Number of attributes. 0 = delete entire prims.
Param ordinal:: Ordinal of the deletion.
Return:: Enqueue result with status + op_index.

void (*get_version)(ovstage_context_t *instance, uint32_t *out_major, uint32_t *out_minor, uint32_t *out_patch)#

Get the implementation’s version (SemVer 2.0).

Returns the same values as the compile-time OVSTAGE_VERSION_MAJOR / OVSTAGE_VERSION_MINOR / OVSTAGE_VERSION_PATCH macros, so a runtime query and a compile-time #if check always agree.

const char *(*get_error_string)(ovstage_context_t *instance, ovstage_api_status_t error)#

Get a human-readable string for an error code.

Return:: Static string. Never NULL.

ovx_string_t (*get_last_op_error)(ovstage_context_t *instance, ovstage_op_id_t op_id)#

Get the human-readable error string for a failed op id reported by the last wait_op call on this thread.

The returned string is valid until the next wait_op call on the same thread. Returns {NULL, 0} if the op id is not known or did not fail.

path_dictionary_instance_t *(*get_path_dictionary)(ovstage_context_t *instance)#

Get the path dictionary obtained from this ovstage instance.

Returns a path_dictionary_instance_t* owned by the ovstage subsystem. See <ovx/path_dictionary/path_dictionary.h> for the full vtable contract, handle-lifetime regimes, refcount rules and thread safety; the points below are ovstage-specific.

ovstage_enqueue_result_t (*write_attributes)(ovstage_context_t *instance, ovstage_query_handle_t handle, const ovstage_attribute_write_t *writes, size_t write_count, ovstage_ordinal_t ordinal, ovstage_prim_mode_t prim_mode)#

Enqueue one operation that writes multiple attributes to the prims identified by a query handle.

The entire write array is validated before the operation is queued. Ordinary value columns and the reserved usd-prim-type/usd-schemas entries participate in the same operation and structural precreate. Attribute kind is declared by each entry’s data.is_array with exactly the same rules as write_attribute.

One op_index groups completion and pending-write coverage; it does not make the entries an atomic multi-attribute transaction or establish a global snapshot barrier. Entries may be applied incrementally, descriptor order does not define execution order, and operations that do not overlap the batch may interleave before completion. Pending coverage rejects read_attributes calls overlapping any batch entry until the operation finishes.

Non-reserved entries must name distinct logical attributes and must also map to distinct canonical storage columns. For example, an API alias and its canonical storage name cannot appear together in one batch.

Every DLManagedTensorVersioned pointer across the complete write array must be non-NULL and unique. Ownership of all supplied managed tensors transfers at call entry; every unique pointer is released exactly once, including when synchronous validation rejects the batch.

If the query has no target prims, batch-level names, aliases, ordinal admission, and managed-pointer uniqueness are still validated, but tensor payload shape/device/type validation is skipped because no payload is accessed. Transferred managed tensors are still released exactly once.

A successful enqueue does not promise transactional rollback if a later asynchronous scatter fails after earlier columns were authored. Such an execution failure is reported by wait_op/get_last_op_error and does not publish a successful group completion. Successful structural precreate may leave physical/default column storage for entries whose scatter did not complete. Only successfully authored entries publish value and dirty-membership records.

Param instance:: Implementation context.
Param handle:: Query handle identifying target prims.
Param writes:: Array of named attribute writes.
Param write_count:: Number of entries in writes.
Param ordinal:: Ordinal shared by the operation.
Param prim_mode:: UPSERT (default) or INSERT.
Return:: Enqueue result with status and one op_index for the complete group.

ovstage_api_status_t (*query_extension)(ovstage_context_t *instance, const char *name, const void **out_extension)#

Query an optional implementation-specific extension table.

Extension names are UTF-8, NUL-terminated identifiers. On success, *out_extension receives a pointer to an immutable function table owned by the implementation and valid for the lifetime of the process. The table layout is defined by the extension owner.

Returns OVSTAGE_OK when the extension exists, OVSTAGE_ERROR_NOT_FOUND when it does not, and OVSTAGE_ERROR_INVALID_ARGUMENT for NULL arguments.

ovstage_api — shared types, handles, and instance bundle.

ovstage_api is a vtable-based contract for asynchronous, ordinal-keyed zero-copy simulation data access. It is the abstract API that various stage implementations can provide.

This header defines the data types (handles, error codes, enums, payload structs), the forward declarations for the vtable and context, and the ovstage_instance_t bundle that pairs them.

The vtable itself is defined in ovstage_api.h. Convenience static inline wrappers around the core data-plane slots live in ovstage_api_utils.h; higher-level extension APIs may live in sibling headers.

Defines

OVSTAGE_VERSION_MAJOR#

OVSTAGE_VERSION_MINOR#

OVSTAGE_VERSION_PATCH#

OVSTAGE_DEPRECATED(msg)#

OVSTAGE_ORDINAL_T_DECLARED#

Application/simulation ordinal used as the API’s ordering key.

The ordinal is not necessarily physical simulation time in nanoseconds. It is the scalar key used for write ordering, sealing/write floors, point/range change-membership reads, and retention frontiers. Applications that need physical time should carry an explicit ordinal-to-time mapping outside this scalar or in metadata.

Valid range: any uint64_t value. There is no sentinel; see ovstage_ordinal_range_t for how “latest” reads are expressed.

OVSTAGE_TIMEOUT_INFINITE#

OVSTAGE_INVALID_OP_ID#

OVSTAGE_INVALID_QUERY_HANDLE#

OVSTAGE_INVALID_READ_HANDLE#

OVSTAGE_INVALID_MAP_HANDLE#

OVSTAGE_INVALID_ORDINAL_QUERY_HANDLE#

OVSTAGE_INVALID_READ_GROUP_ID#

OVSTAGE_INVALID_QUERY_RESULT_ID#

OVSTAGE_INSTANCE_T_DECLARED#

Typedefs

typedef struct ovstage_context_t ovstage_context_t#: Opaque per-implementation context, stored in ovstage_instance_t.

typedef uint64_t ovstage_ordinal_t#

typedef const uint64_t *ovstage_mask_t#

Bitmask pointer.

NULL = all valid. Bit i set = element i is valid.

Element i is bit i % 64 of word i / 64, least significant bit first. A non-NULL mask spans at least ceil(count / 64) uint64_t words, where count is the logical element count of the structure carrying it; exactly that many words are read. Any bits above count in the final word are ignored.

typedef uint64_t ovstage_timeout_ns_t#

Timeout for fetch/wait calls, in nanoseconds.

0 : non-blocking poll.
OVSTAGE_TIMEOUT_INFINITE : block until the result is ready.
any other value : block for up to that many nanoseconds before returning OVSTAGE_ERROR_TIMEOUT.

typedef uint64_t ovstage_op_id_t#: Monotonic per-instance operation identifier.

typedef uint64_t ovstage_query_handle_t#: Query handle — identifies a logical set of prims.

typedef uint64_t ovstage_read_handle_t#: Read handle — identifies an enqueued multi-attribute read.

typedef uint64_t ovstage_map_handle_t#: Map handle — identifies an enqueued zero-copy write session.

typedef uint64_t ovstage_ordinal_query_handle_t#: Ordinal-query handle — identifies an enqueued read of an ordinal scalar, such as the global or per-attribute write floor.

typedef uint64_t ovstage_read_group_id_t#: Opaque identity for a fetched read group payload.

typedef uint64_t ovstage_query_result_id_t#: Opaque identity for a fetched query result payload.

Enums

enum ovstage_api_status_t#

API status / error code returned by ovstage calls (synchronous returns and the status field of enqueue results).

A typed enum rather than a bare integer: the fine-grained codes are retained, and a human-readable detail string for the most recent failure is available via ovstage_get_last_error() (or ovstage_get_last_op_error() for a failed op). The numeric values are stable ABI.

Values:

enumerator OVSTAGE_OK#

enumerator OVSTAGE_ERROR_INVALID_ARGUMENT#

enumerator OVSTAGE_ERROR_INVALID_HANDLE#: Stale/invalid handle of any kind.

enumerator OVSTAGE_ERROR_NOT_FOUND#

enumerator OVSTAGE_ERROR_PRIM_NOT_FOUND#: INSERT mode and prim already exists.

enumerator OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION#: Write at/below effective write floor; snapshot read with current state above it; range read with a selected change above it.

enumerator OVSTAGE_ERROR_NOT_SUPPORTED#

enumerator OVSTAGE_ERROR_QUEUE_FULL#: Backpressure: submit queue full.

enumerator OVSTAGE_ERROR_END_OF_ITERATION#: No more groups to iterate.

enumerator OVSTAGE_ERROR_OUT_OF_MEMORY#

enumerator OVSTAGE_ERROR_LAYOUT_CHANGED#: Layout changed during map.

enumerator OVSTAGE_ERROR_TIMEOUT#: Fetch/wait did not complete within timeout.

enumerator OVSTAGE_ERROR_OP_FAILED#: An enqueued op failed; see get_last_op_error.

enumerator OVSTAGE_ERROR_OUT_OF_RANGE#: Requested ordinal range cannot be materialized from retained payloads.

enumerator OVSTAGE_ERROR_INTERNAL#

enum ovstage_filter_op_t#

Filter predicate operators for query matching.

Notes:

CONTAINS tests whether a composite value (array, string) contains at least one of the provided match values. For “contains all”, use multiple CONTAINS predicates (one per required value).
CONTAINS works on string attributes (substring match), array attributes (element membership), and any other composite data types.
Comparison operators (LT, LE, GT, GE) work on numeric and string attributes. String comparison is binary (byte-wise).

Values:

enumerator OVSTAGE_FILTER_OP_HAS#: Attribute exists on prim (no value test).

enumerator OVSTAGE_FILTER_OP_IN#: Attribute value ∈ {values} (single value = equals).

enumerator OVSTAGE_FILTER_OP_CONTAINS#: Composite attribute contains one of {values}.

enumerator OVSTAGE_FILTER_OP_PREFIX#: String attribute starts with one of {values}.

enumerator OVSTAGE_FILTER_OP_LT#: Attribute value < value.

enumerator OVSTAGE_FILTER_OP_LE#: Attribute value <= value.

enumerator OVSTAGE_FILTER_OP_GT#: Attribute value > value.

enumerator OVSTAGE_FILTER_OP_GE#: Attribute value >= value.

enum ovstage_prim_mode_t#

Write prim creation mode.

UPSERT (default): Create prims that don’t exist; update prims that do.
INSERT: Only create new prims; error if prim already exists.

Values:

enumerator OVSTAGE_PRIM_MODE_UPSERT#: Create if absent, update if present (default).

enumerator OVSTAGE_PRIM_MODE_INSERT#: Create only; OVSTAGE_ERROR_PRIM_NOT_FOUND if exists.

enum ovstage_scope_t#

Write-floor advance scope.

Values:

enumerator OVSTAGE_SCOPE_ALL#: Advance all attributes (and the global write floor).

enumerator OVSTAGE_SCOPE_INCLUDE#: Advance only listed attributes.

enumerator OVSTAGE_SCOPE_EXCLUDE#: Advance all EXCEPT listed attributes.

enum ovstage_attribute_semantic_t#

Per-attribute USD semantic — the authored interpretation of a column’s bytes, orthogonal to its DLDataType storage shape.

ovpopulation derives this from the USD SdfValueTypeName (role + scalar type) and carries it through writes; consumers (e.g. runtime→USD export) use it to recover the authored USD type (point3f vs float3, asset vs string, etc.). It is NOT part of the bucket key — float3 and point3f share bytes and a column. Tuple width comes from dtype.lanes, precision from dtype.bits; these roles deliberately do not encode dimensional suffixes such as 3f or 4d.

The semantic round-trips through the attribute column: write records it on the column at creation, read recovers it by decoding the column.

Geometric semantics (POINT, VECTOR, NORMAL, COLOR, QUATERNION, MATRIX, FRAME, TEXTURE_COORDINATE) record a geometric role on the column. Storage stays in the requested numeric dtype.
TIME_CODE marks a time code — a unitless time value — again with storage in the requested numeric dtype. Only the plain numeric value is carried: sentinel time codes have no portable numeric encoding, so they are not representable.
ID semantics select the corresponding ID storage type and require pre-interned id payloads (producers — e.g. ovpopulation — must intern via the path or token dictionary before writing; ovstage does not stringify or resolve):
- TOKEN_ID → dtype = {kDLUInt, 64, 1} (one 64-bit token id per row; id 0 is the empty token)
- RELATIONSHIP_PATH_ID → dtype = {kDLUInt, 64, 1} (one 64-bit path id per row)
- CONNECTION_PATH_ID → dtype = {kDLUInt, 64, 2} (one (path_id, token_id) pair per row, using one 16-byte element per row)
- ASSET_PATH_ID → dtype = {kDLUInt, 64, 2} (one (authored_token, resolved_token) pair per row, using one 16-byte element per row)
An asset has two paths: the path as authored, and the path after resolution. ASSET_PATH_ID carries both as token ids. A token id of 0 means no path, so an unresolved asset has a resolved token id of 0.
PATH_EXPRESSION_STRING carries the expression text as one interned token id, dtype {kDLUInt, 64, 1}. is_array = false is a scalar pathExpression; true is pathExpression[], one id per element. Other layouts return OVSTAGE_ERROR_INVALID_ARGUMENT. A token id of 0 means no expression. ovstage does not evaluate the expression; it stores the id of the authored text.
STRING carries a plain USD string value as raw UTF-8 bytes. The payload is a ragged kDLUInt,8,1 byte array (one string per row, is_array = true) — NOT a pre-interned token id. It stamps the USD-string role on the column, so the resulting column is the canonical USD-string representation. Read recovers the semantic by decoding that role.

Either way, borrow and replicate modes converge on the same authored interpretation because they consult the same attribute column.

Values:

enumerator OVSTAGE_SEMANTIC_NONE#

enumerator OVSTAGE_SEMANTIC_ASSET_PATH_ID#

enumerator OVSTAGE_SEMANTIC_TOKEN_ID#

enumerator OVSTAGE_SEMANTIC_PATH_EXPRESSION_STRING#

enumerator OVSTAGE_SEMANTIC_RELATIONSHIP_PATH_ID#

enumerator OVSTAGE_SEMANTIC_POINT#

enumerator OVSTAGE_SEMANTIC_VECTOR#

enumerator OVSTAGE_SEMANTIC_NORMAL#

enumerator OVSTAGE_SEMANTIC_COLOR#

enumerator OVSTAGE_SEMANTIC_QUATERNION#

enumerator OVSTAGE_SEMANTIC_MATRIX#

enumerator OVSTAGE_SEMANTIC_TEXTURE_COORDINATE#

enumerator OVSTAGE_SEMANTIC_CONNECTION_PATH_ID#

enumerator OVSTAGE_SEMANTIC_STRING#

enumerator OVSTAGE_SEMANTIC_TIME_CODE#

enumerator OVSTAGE_SEMANTIC_FRAME#

struct ovstage_cuda_sync_t#

#include <ovstage_api_types.h>

CUDA synchronization for a GPU data handoff.

The two fields are independent knobs — set either, both, or neither. Each non-zero field adds its own synchronization before the op:

stream — 0 = none; 1 = the default stream; >1 = a specific cudaStream_t. When set, all work currently queued on that stream is drained.
wait_event — 0 = none; otherwise a cudaEvent_t to wait on.

So { 0, event } waits on the event only, { stream, 0 } drains the stream only, { stream, event } does both, and { 0, 0 } is no synchronization (CPU-resident or already-synced data).

Public Members

uintptr_t stream#: CUDA stream to synchronize: 0 = none, 1 = default stream, >1 = a specific cudaStream_t.

uintptr_t wait_event#: CUDA event to wait on: 0 = none, else a cudaEvent_t.

struct ovstage_enqueue_result_t#

#include <ovstage_api_types.h>

Result of an asynchronous enqueue call.

status is the enqueue status. OVSTAGE_OK means the operation was accepted; the operation itself has not necessarily executed. Use the wait_op slot or a corresponding fetch_* call to observe completion/results.
op_index is OVSTAGE_INVALID_OP_ID when status != OVSTAGE_OK.

Public Members

ovstage_api_status_t status#

ovstage_op_id_t op_index#

struct ovstage_op_wait_result_t#

#include <ovstage_api_types.h>

Output of the wait_op slot.

error_op_ids lists op ids observed to have failed since the previous wait_op call on this thread. For each id, call the get_last_op_error slot to retrieve the human-readable error string. The array is transient thread-local memory and is invalidated by the next wait_op call on the same thread.
lowest_pending_op_id is meaningful only on OVSTAGE_ERROR_TIMEOUT: it is the lowest still-pending op id within the dependency chain of the waited op (not a global lowest across the instance). Useful for partial-progress reporting.

Public Members

const ovstage_op_id_t *error_op_ids#

size_t error_op_id_count#

ovstage_op_id_t lowest_pending_op_id#

struct ovstage_data_t#

#include <ovstage_api_types.h>

Data payload — array of tensors plus sparsity and GPU sync metadata.

Used for both read results (caller reads from tensors[i].data) and the map iterator (caller writes into tensors[i].data). The DLTensor metadata is owned by the implementation and treated as read-only by the caller.

Invariant: For value groups, tensor_count >= 1. For fixed-size attributes it is 1; for array attributes it equals the number of logical prim elements.
Invariant: A fixed-size value tensor has ndim == 1; its leading shape is the transported data-row count and dtype.lanes carries the tuple width. Logical element i selects row i when index_map is NULL, or row index_map[i] otherwise.
Invariant: For delete/tombstone read groups (is_delete == true), tensor_count == 0, tensors == NULL, and count == 0.
Invariant: index_map and mask are mutually exclusive.
Invariant: count is set (non-zero) when index_map or mask is non-NULL. When both are NULL, logical elements select data rows by identity.
Invariant: cuda_sync is {0, 0} for CPU-resident or already-synchronized data.

Public Members

const DLTensor *tensors#: Array of tensors (1 for fixed-size attrs; per-prim for array attrs).

uint32_t tensor_count#: Number of tensors in tensors.

uint32_t count#: Logical element count when index_map/mask present.

const uint32_t *index_map#: NULL = identity; non-NULL = gather/reorder/dedup.

ovstage_mask_t mask#: NULL = all valid; non-NULL = bitmask over elements.

ovstage_cuda_sync_t cuda_sync#

GPU sync applied before access; {0,0} = none.

See ovstage_cuda_sync_t.

struct ovstage_prim_group_t#

#include <ovstage_api_types.h>

Prim group — identifies which prims a group covers.

Uses four mutually exclusive representations:

Full match: list == query list, offset=0, count=total, index_map=NULL
Contiguous sub-range: same list, offset/count subset, index_map=NULL
Sparse subset: same list, index_map non-NULL (gather indices into list)
Different set: different list handle (resolve via path dictionary)

Handle comparison (list == other.list) is O(1) pointer equality.

Public Members

ovx_primpath_list_t list#: Comparable prim list handle (== for identity).

uint32_t offset#: Start index within list (0 if full match).

uint32_t count#: Number of prims in this group.

const uint32_t *index_map#: NULL = contiguous from offset; non-NULL = sparse indices.

struct ovstage_attribute_meta_t#

#include <ovstage_api_types.h>

Attribute metadata — write floor and layout generation.

Shared across read groups and map groups.

attribute_write_floor_ordinal: The write floor in effect for this attribute when the group was produced. Data at ordinals <= attribute_write_floor_ordinal is sealed (will never change).
layout_generation: Monotonically increasing counter scoped to the attribute. Bumps on structural changes (prim add/remove, index_map shape change). Stable when only values update. Enables consumers to skip re-setup on hot path.

Public Members

ovstage_ordinal_t attribute_write_floor_ordinal#: Write floor for this attribute.

uint64_t layout_generation#: Structural version (opaque).

struct ovstage_ordinal_range_t#

#include <ovstage_api_types.h>

Ordinal range for read operations.

Latest snapshot request: has_start_ordinal = false, end_ordinal = N. In the current implementation, recorded columns return their latest committed payload, not a historical payload selected at or before N.
Change range [start, end]: has_start_ordinal = true, start_ordinal <= end_ordinal. Selects keys with retained changes in the inclusive interval [start_ordinal, end_ordinal]. As a limitation of the current implementation, this interval selects keys only; it does not select a historical payload version. A selected change above the effective write floor fails with OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION. If a selected public key (attribute and path) also has a retained change after end_ordinal, the read fails with OVSTAGE_ERROR_OUT_OF_RANGE because the payload for the fixed range is no longer available, whether or not the later change is sealed. Otherwise, the selected key returns its latest committed payload or tombstone.

Implementations may coalesce or discard history below their inclusive retention frontier. Query ovstage_get_oldest_preserved_ordinal before relying on an old interval.

0 is a valid ordinal (no sentinel values).

Remark

The current implementation retains bounded exact change membership at or above the frontier reported by ovstage_get_oldest_preserved_ordinal. Callers must query the frontier rather than assume a fixed retention depth. Ordinal ranges are therefore not a historical-payload event log. Historical-payload support must first return a retained in-range payload when one is available before reporting OVSTAGE_ERROR_OUT_OF_RANGE.

Public Members

ovstage_ordinal_t start_ordinal#: Range start (only when has_start_ordinal).

ovstage_ordinal_t end_ordinal#: Upper-bound ordinal.

bool has_start_ordinal#: false = latest snapshot; true = range [start, end].

struct ovstage_read_group_t#

#include <ovstage_api_types.h>

A single read result group.

Public Members

ovstage_read_group_id_t read_group_id#: Opaque payload identity for release_group.

ovx_token_t attribute#: Which attribute this group contains.

ovstage_ordinal_t ordinal#: Data ordinal.

bool is_delete#: true = tombstone group (deletions).

bool is_array#

true = source is a ragged (variable-length / USD-array or byte-string) column; false = fixed scalar.

The data is CSR either way, so this is the only signal that distinguishes e.g. a 1-byte string from a scalar uint8.

ovstage_attribute_semantic_t semantic#

Authored USD interpretation of the column’s bytes (point vs float3, asset vs string, …).

NONE when unspecified. Orthogonal to dtype/is_array; see ovstage_attribute_semantic_t.

ovstage_prim_group_t prims#: Which prims this group covers.

ovstage_data_t data#: Attribute data (array of tensors).

ovstage_attribute_meta_t meta#: Write floor + layout generation.

struct ovstage_map_group_t#

#include <ovstage_api_types.h>

A writable group returned by the map iterator.

Public Members

ovstage_prim_group_t prims#: Which prims this group covers.

ovstage_data_t data#

Writable tensor(s).

Caller writes values here.

ovstage_attribute_meta_t meta#: Layout generation (detect structural changes).

struct ovstage_map_desc_t#

#include <ovstage_api_types.h>

Descriptor for a zero-copy map session (map_attribute).

Public Members

ovx_string_or_token_t attribute#: Attribute to map (name or interned token).

DLDataType dtype#

Requested element type.

Required to create a new mapped attribute. Leave zero-initialized only when the target prims already have one unambiguous schema for this attribute name. dtype.lanes carries the tuple width.

ovstage_attribute_semantic_t semantic#

Authored USD interpretation (point vs float3, asset vs string, …).

NONE = unspecified. Must match an existing prim/name unless the attribute is being created.

ovstage_prim_mode_t prim_mode#: UPSERT (create absent prims, update present) or INSERT (create-only; OVSTAGE_ERROR_PRIM_NOT_FOUND if a prim already exists).

struct ovstage_predicate_t#

#include <ovstage_api_types.h>

Single filter predicate (tests one attribute).

HAS: attribute exists (values/value_count ignored).
IN: attribute value matches one of the provided values.
CONTAINS: composite attribute contains at least one of the values. Works on arrays (element membership), strings (substring), and composites. For “contains ALL”, use multiple CONTAINS predicates.
PREFIX: string attribute starts with one of the values.
LT/LE/GT/GE: numeric or binary (byte-wise) comparison (single value expected).

Public Members

ovx_string_or_token_t attribute#: Which attribute to test.

ovstage_filter_op_t op#: Comparison operator.

const ovx_string_t *values#: Match values (NULL for HAS).

size_t value_count#: Number of values (0 for HAS).

struct ovstage_filter_t#

#include <ovstage_api_types.h>

Query filter — conjunction (AND) of all predicates.

All predicates must match for a prim to be included.

Public Members

const ovstage_predicate_t *predicates#: Array of predicates (AND).

size_t count#: Number of predicates.

struct ovstage_query_result_t#

#include <ovstage_api_types.h>

Result of the fetch_query_result slot — discovered attributes + summary.

all_handle is the same query handle reserved by the query slot (or built by query_from_path_list). It is included for convenience so consumers receiving only this struct still have the handle in hand.

Public Members

ovstage_query_result_id_t query_result_id#: Opaque payload identity for release_query_result.

const ovx_token_t *attributes#: Discovered attribute tokens.

size_t attribute_count#: Number of distinct attributes.

ovstage_query_handle_t all_handle#: Handle covering all matched prims.

size_t total_prim_count#: Total prims matching the filter.

struct ovstage_write_floor_desc_t#

#include <ovstage_api_types.h>

Descriptor for advancing the per-attribute and/or global write floor.

Usage patterns:

SCOPE_ALL: advance the global write floor and every known attribute (end-of-frame signal).
SCOPE_INCLUDE {“transforms”}: advance only transforms after xform writer completes.
SCOPE_EXCLUDE {“points”, “velocities”}: advance all except physics attrs still being written. With an empty attribute list, SCOPE_EXCLUDE behaves like SCOPE_ALL.

To query the global write floor, call the get_attribute_write_floor slot with attribute = {.token = 0, .string = {NULL, 0}}.

To advance the global write floor (all attributes), use SCOPE_ALL.

Public Members

ovstage_ordinal_t ordinal#: New write-floor ordinal.

ovstage_scope_t scope#: ALL, INCLUDE, or EXCLUDE.

const ovx_token_t *attributes#: Attribute list (for INCLUDE/EXCLUDE).

size_t attribute_count#: Number of attributes in list.

struct ovstage_write_data_t#

#include <ovstage_api_types.h>

Write payload — tensor(s) plus sparsity and GPU sync metadata.

Exactly one of tensors and managed_tensors is non-NULL, selecting the lifetime model for the supplied tensors. Both arrays, when present, have length tensor_count.

Every attribute, including reserved metadata, follows this contract. usd-prim-type has the canonical fixed token-id schema (is_array == false); usd-schemas has the canonical token-id-array schema (is_array == true). A conflicting declaration is rejected. Both attributes use the normal row/count/mask/index_map coverage rules; their names do not trigger implicit broadcasting or kind correction.

Invariant: Exactly one of tensors / managed_tensors is non-NULL.
Invariant: tensor_count >= 1.
Invariant: When is_array == false, tensor_count == 1 and the tensor contains the fixed-size rows stacked along its leading dimension. The canonical input is ndim == 1, shape == {source_rows}, with the complete per-row tuple width in dtype.lanes. A compact convenience input may instead place tuple components in trailing shape dimensions (for example (N, 3) with lanes == 1, or (N, 4) with lanes == 4). Those per-row dimensions are folded into dtype.lanes; their rank and shape are not preserved. Reads and maps expose the canonical 1-D form ((N,), lanes 3 or 16 in these examples). Without index_map, shape[0] must equal the logical element count. A flat (N * L,), lanes == 1 tensor is not an encoding of N rows of width L.
Invariant: When is_array == true, tensor_count == 1 selects packed uniform-row transport and tensor_count > 1 selects one tensor per source row. Neither form changes the declared logical kind. Packed transport carries no explicit row capacity — one flat tensor holds every row back to back — so its row count is inferred: the highest index_map entry plus one, or the logical element count when index_map is NULL. The uniform row width is the payload size divided by that inferred count — not by the logical element count — so an index_map declares the partition as well as selecting from it, and may declare more rows than the logical element count. A partition the payload cannot support is rejected: the payload must divide evenly across the inferred count, and the resulting row width must be a whole number of dtype elements. A packed payload cannot carry trailing rows above the highest index_map entry; they would change the inferred width of every row. Use tensor_count > 1 when rows must be described individually.
Invariant: index_map and mask are mutually exclusive.
Invariant: count is set (non-zero) when index_map or mask is non-NULL. Otherwise count == 0 means the write addresses every prim the query covers. A non-zero count addresses the leading count prims in query order and may not exceed the query’s prim count. The logical element count is count, or the query’s prim count when count == 0.
Invariant: index_map has count entries and holds source row indices, not target prim indices: logical element i reads transported row index_map[i]. Where the payload declares a transported row count — shape[0] when is_array == false, tensor_count for per-row array transport — every entry is less than it, and an out-of-range entry is rejected rather than reinterpreted. Rows no entry references are left unused, so the payload may carry more rows than the query has prims. Packed array transport declares no row count; there the map defines one, as described above.
Invariant: mask selects which of the count logical elements are written; unselected prims are left untouched. It does not change how the payload is cut into rows, so the payload still carries a row for every logical element, including the unselected ones. A non-NULL mask addresses at least ceil(count / 64) uint64_t words — the implementation reads that many — with element i at bit i % 64 of word i / 64.
Invariant: cuda_sync is {0, 0} for CPU-resident or already-synchronized data.

Public Members

const DLTensor *tensors#

Client-managed tensors (read-only to the implementation).

Must remain valid until op completes. NULL when managed_tensors is provided.

const DLManagedTensorVersioned *const *managed_tensors#

Storage-managed tensors (read-only to the implementation).

Deleter invoked when storage no longer needs them. NULL when tensors is provided.

uint32_t tensor_count#: Number of tensors in tensors/managed_tensors; selects transport layout, not attribute kind.

uint32_t count#

Logical element count; addresses the leading count prims in query order.

Required (non-zero) when index_map/mask present; 0 = every prim the query covers.

const uint32_t *index_map#

NULL = identity; non-NULL = gather/reorder/dedup.

count source row indices, each below the transported row count.

ovstage_mask_t mask#

NULL = all valid; non-NULL = bitmask over elements, at least ceil(count / 64) words long.

Selects target elements; it does not change how the payload is cut into rows.

ovstage_cuda_sync_t cuda_sync#

GPU sync applied before access; {0,0} = none.

See ovstage_cuda_sync_t.

ovstage_attribute_semantic_t semantic#

Authored USD interpretation for this write (NONE = unspecified).

Must match an existing prim/name unless the attribute is being created. Geometric semantics are recorded at creation and surfaced back on read; see ovstage_attribute_semantic_t.

bool is_array#

Logical attribute kind.

Sole authority for fixed (false) versus array (true) storage. Kept last to minimize padding; it occupies existing tail padding on 64-bit ABIs.

struct ovstage_attribute_write_t#

#include <ovstage_api_types.h>

One named attribute write passed to write_attributes.

Attribute kind is declared by data.is_array with the same contract as write_attribute. Tensor count, tensor shape, payload width, attribute name, semantic, and existing storage never substitute for that declaration.

Public Members

ovx_string_or_token_t attribute#: Attribute to write (name or interned token).

ovstage_write_data_t data#: Write payload for this attribute.

struct ovstage_instance_t#

#include <ovstage_api_types.h>

Public Members

const ovstage_vtable_t *vtable#: Vtable pointer (see ovstage_api.h).

ovstage_context_t *context#: Implementation-specific context.

Convenience static inline wrappers around the core ovstage_api slots.

This header is included by ovstage_api.h after the vtable struct is defined. Callers should #include "ovstage_api.h" and then call the wrappers directly:

ovstage_query_handle_t qh;
ovstage_enqueue_result_t er = ovstage_query(instance, &filter,
                                            NULL, 0, &qh);

The core data-plane slots have wrappers here, including the diagnostics slots (ovstage_get_version, ovstage_get_error_string, ovstage_get_last_op_error) and the resources slot (ovstage_get_path_dictionary). Higher-level extension APIs live in sibling headers such as ovstage_instancing.h.

Functions

static inline ovstage_api_status_t ovstage_wait_op( ovstage_instance_t *instance, ovstage_op_id_t op_id, ovstage_timeout_ns_t timeout, ovstage_op_wait_result_t *out_wait_result )#

static inline ovstage_api_status_t ovstage_release_op( ovstage_instance_t *instance, ovstage_op_id_t op_id )#

static inline ovstage_enqueue_result_t ovstage_advance_write_floor( ovstage_instance_t *instance, const ovstage_write_floor_desc_t *desc )#

static inline ovstage_enqueue_result_t ovstage_get_oldest_preserved_ordinal( ovstage_instance_t *instance, ovstage_ordinal_query_handle_t *out_handle )#

static inline ovstage_enqueue_result_t ovstage_get_attribute_write_floor( ovstage_instance_t *instance, ovx_string_or_token_t attribute, ovstage_ordinal_query_handle_t *out_handle )#

static inline ovstage_api_status_t ovstage_fetch_ordinal( ovstage_instance_t *instance, ovstage_ordinal_query_handle_t handle, ovstage_timeout_ns_t timeout, ovstage_ordinal_t *out_ordinal )#

static inline ovstage_enqueue_result_t ovstage_release_ordinal_query( ovstage_instance_t *instance, ovstage_ordinal_query_handle_t handle )#

static inline ovstage_enqueue_result_t ovstage_query( ovstage_instance_t *instance, const ovstage_filter_t *filter, const ovx_token_t *attrs, size_t attr_count, ovstage_query_handle_t *out_query_handle )#

static inline ovstage_api_status_t ovstage_query_from_path_list( ovstage_instance_t *instance, ovx_primpath_list_t path_list, ovstage_query_handle_t *out_handle )#

static inline ovstage_api_status_t ovstage_fetch_query_result( ovstage_instance_t *instance, ovstage_query_handle_t query_handle, ovstage_timeout_ns_t timeout, ovstage_query_result_t *out_result )#

static inline ovstage_api_status_t ovstage_release_query_result( ovstage_instance_t *instance, const ovstage_query_result_t *result )#

static inline ovstage_enqueue_result_t ovstage_release_query( ovstage_instance_t *instance, ovstage_query_handle_t handle )#

static inline ovstage_enqueue_result_t ovstage_read_attributes( ovstage_instance_t *instance, ovstage_query_handle_t handle, const ovx_token_t *attrs, size_t attr_count, ovstage_ordinal_range_t range, ovstage_read_handle_t *out_read_handle )#

static inline ovstage_api_status_t ovstage_fetch_read_next( ovstage_instance_t *instance, ovstage_read_handle_t read_handle, ovstage_timeout_ns_t timeout, ovstage_read_group_t *out_group )#

static inline ovstage_api_status_t ovstage_release_group( ovstage_instance_t *instance, const ovstage_read_group_t *group )#

static inline ovstage_enqueue_result_t ovstage_release_read( ovstage_instance_t *instance, ovstage_read_handle_t read_handle )#

static inline ovstage_enqueue_result_t ovstage_write_attribute( ovstage_instance_t *instance, ovstage_query_handle_t handle, ovx_string_or_token_t attribute, ovstage_ordinal_t ordinal, ovstage_write_data_t data, ovstage_prim_mode_t prim_mode )#

static inline ovstage_enqueue_result_t ovstage_write_attributes( ovstage_instance_t *instance, ovstage_query_handle_t handle, const ovstage_attribute_write_t *writes, size_t write_count, ovstage_ordinal_t ordinal, ovstage_prim_mode_t prim_mode )#

static inline ovstage_enqueue_result_t ovstage_map_attribute( ovstage_instance_t *instance, ovstage_query_handle_t handle, const ovstage_map_desc_t *desc, ovstage_ordinal_t ordinal, const size_t *element_sizes, size_t element_count, ovstage_map_handle_t *out_map_handle )#

static inline ovstage_api_status_t ovstage_fetch_map_next( ovstage_instance_t *instance, ovstage_map_handle_t map_handle, ovstage_timeout_ns_t timeout, ovstage_map_group_t *out_group )#

static inline ovstage_enqueue_result_t ovstage_unmap_group( ovstage_instance_t *instance, ovstage_map_handle_t map_handle, const ovstage_map_group_t *group, ovstage_cuda_sync_t write_done_sync )#

static inline ovstage_enqueue_result_t ovstage_unmap_attribute( ovstage_instance_t *instance, ovstage_map_handle_t map_handle, ovstage_cuda_sync_t write_done_sync )#

static inline ovstage_enqueue_result_t ovstage_delete_attributes( ovstage_instance_t *instance, ovstage_query_handle_t handle, const ovx_string_or_token_t *attributes, size_t attribute_count, ovstage_ordinal_t ordinal )#

static inline void ovstage_get_version( ovstage_instance_t *instance, uint32_t *out_major, uint32_t *out_minor, uint32_t *out_patch )#

static inline const char *ovstage_get_error_string( ovstage_instance_t *instance, ovstage_api_status_t error )#

static inline ovx_string_t ovstage_get_last_op_error( ovstage_instance_t *instance, ovstage_op_id_t op_id )#

static inline path_dictionary_instance_t *ovstage_get_path_dictionary( ovstage_instance_t *instance )#

static inline ovstage_api_status_t ovstage_query_extension(

ovstage_instance_t *instance,

const char *name,

const void **out_extension

)#

Configuration #

Helpers for building the ovstage_config_t entries passed to ovstage_initialize().

Helpers for building ovstage_config_t entries passed to ovstage_initialize().

Functions

static inline ovstage_config_entry_t ovstage_config_entry_string( ovstage_config_string_t key, ovx_string_t value )#

Build a config entry for a string setting.

Parameters:

key – Config key from ovstage_config_string_t.
value – String value. value.ptr must remain valid until the API call that consumes the config returns.

static inline ovstage_config_entry_t ovstage_config_entry_uint64( ovstage_config_uint64_t key, uint64_t value )#

Build a config entry for an unsigned 64-bit setting.

Parameters:

key – Config key from ovstage_config_uint64_t.
value – Unsigned 64-bit value.

static inline ovstage_config_entry_t ovstage_config_entry_runtime_default_hierarchy_computation_model( ovstage_hierarchy_computation_model_id_t model )#

Configure the hierarchy computation model used by automatic transform updates and by OVSTAGE_HIERARCHY_COMPUTATION_MODEL_RUNTIME_DEFAULT.

To override the default, use CPU_INCREMENTAL, GPU_INCREMENTAL, or GPU_GLOBAL (the DEFAULT_CPU and DEFAULT_GPU aliases are also accepted). RUNTIME_DEFAULT means “no override”; an entry with that value is ignored.

The setting is process-scoped and must be supplied when acquiring the first process reference. Existing instances retain the default captured when they were created.

static inline ovstage_config_entry_t ovstage_config_entry_binary_package_root_path( ovx_string_t path )#

Configure the ovstage “binary package root” directory.

This is used by the static loader (ovstage-static) to locate the ovstage shared library and, transitively, its bundled runtime closure (plugins/), which ovstage resolves relative to the directory the shared library is loaded from. If not provided, the loader defaults to its own module directory.

Pass this entry to ovstage_initialize(). The loader loads the shared library once, from the root supplied on that first load — so static-loader consumers that need a non-default root must call ovstage_initialize() with this entry BEFORE any other ovstage_* call (ovstage_create_instance would otherwise trigger the load from the default module directory). Ignored by the dynamic ovstage shared library, so it is harmless when passed in non-static builds.

Parameters:

path – The package bin/ directory. path.ptr must remain valid until the ovstage_initialize() call that consumes the config returns. The path may contain the OVX_CONFIG_EXECUTABLE_DIR_TOKEN token, which the static loader substitutes with the absolute directory of the running executable (e.g. OVX_CONFIG_EXECUTABLE_DIR_TOKEN “/ovstage/bin”).

ovx_string_t ovstage_executable_dir(void)#

Absolute directory of the running executable, with no trailing separator.

Convenience for static-loader clients building the binary package root, e.g. OVX_CONFIG_EXECUTABLE_DIR_TOKEN “/ovstage”, to pass via ovstage_config_entry_binary_package_root_path() — so callers need not reimplement the platform-specific GetModuleFileName/readlink lookup.

Provided by the ovstage-static loader (link ovstage::ovstage_static); it is not exported by the dynamic ovstage shared library. The returned pointer is backed by a thread-local buffer valid until the next ovstage_executable_dir() call on the same thread. Returns {NULL, 0} if the path cannot be determined. Callable at any time, including before ovstage_initialize().

Alignment Helpers #

OVAlign — composable cross-attribute group alignment library.

OVAlign normalizes the group decomposition across multiple attributes so that consumers can zip-iterate attributes for the same prim in a single loop.

Enums

enum ovalign_device_t#

Target device for alignment computation.

Values:

enumerator OVALIGN_DEVICE_CPU#: Alignment runs on CPU.

enumerator OVALIGN_DEVICE_CUDA#: Alignment runs on GPU (intersection + gather as kernels).

Functions

int ovalign_align( const ovalign_request_t *request, ovalign_result_t *out_result )#

Align groups across attributes into a uniform decomposition.

After alignment, all attributes have matching prim structure per group index, enabling direct zip-iteration without index translation.

Behavior by input state:

Input state	Action	Cost
Same decomposition	No-op, skipped=true	O(groups × attrs) cmp
Different group counts/shapes	Intersect + gather	One alloc + gather/attr
prim_order provided	Reorder into specified order	One alloc + gather/attr
prim_order + already ordered	No-op, skipped=true	O(prims) comparison

Note

No ovstage instance required — operates purely on data structs.

Parameters:

request – Alignment request (input groups + configuration).
out_result – [out] Receives aligned result.

Returns:

0 on success, non-zero on error.

Post:

If already aligned: out_result.skipped=true, group pointers reference original input data (zero-copy).

Post:

If alignment needed: out_result contains newly allocated groups with gathered/intersected data.

Post:

Caller must call ovalign_release(out_result) when done.

void ovalign_release(ovalign_result_t *result)#

Release memory allocated by ovalign_align.

Safe to call on results where skipped=true (no-op in that case). After release, all pointers in the result are invalid.

Parameters:

result – Result to release. May be NULL (no-op).

struct ovalign_request_t#

#include <ovalign.h>

Alignment request — which groups to align, for which attributes.

Input uses ovstage_read_group_t (the same struct ovstage_fetch_read_next produces). Groups may be from multiple attributes, mixed together.

Public Members

const ovstage_read_group_t *groups#: All input groups (mixed attributes).

size_t group_count#: Total input group count.

const ovx_token_t *attributes#: Which attribute tokens to align.

size_t attr_count#: Number of attributes.

ovx_primpath_list_t prim_list#: The query’s prim list (groups index into this).

const uint32_t *prim_order#: NULL = preserve natural order; non-NULL = reorder.

size_t prim_order_count#: Length of prim_order (ignored if NULL).

ovalign_device_t device#: Where to run alignment computation.

struct ovalign_attr_result_t#

#include <ovalign.h>

Per-attribute result after alignment.

Contains an array of ovstage_read_group_t — same type as ovstage produces. Consumer code that processes groups works unchanged.

Public Members

const ovstage_read_group_t *groups#

Aligned groups for this attribute.

[group_count]

size_t group_count#: Same for all attrs in result (uniform).

struct ovalign_result_t#

#include <ovalign.h>

Alignment result — per-attribute group arrays + metadata.

Invariant: All attrs have the same group_count (uniform decomposition).
Invariant: Within each group index g: result.attrs[a].groups[g].prims.offset == result.attrs[b].groups[g].prims.offset result.attrs[a].groups[g].prims.count == result.attrs[b].groups[g].prims.count (prim structure matches; data/mask/index_map are per-attribute)

Public Members

const ovalign_attr_result_t *attrs#

Per-attribute results.

[attr_count]

size_t attr_count#: Number of attributes.

size_t group_count#: Uniform group count across all attrs.

bool skipped#: true = already aligned, zero-copy (no alloc).

Path Dictionary (OVX)#

The shared path dictionary: interning, tokens, and prim-path lists. These headers ship under include/ovx/ and are shared with sibling OV libraries.

struct path_dictionary_vtable_t#

#include <path_dictionary_vtable.h>

Public Members

ovx_api_result_t (*create_tokens_from_strings)(path_dictionary_context_t *instance, const ovx_string_t *strings, size_t num_strings, ovx_token_t *out_tokens)#

ovx_api_result_t (*create_paths_from_tokens)(path_dictionary_context_t *instance, const ovx_token_t *tokens_per_path, const size_t *num_tokens_per_path, size_t num_paths, ovx_primpath_t *out_prim_paths)#

ovx_api_result_t (*create_paths_from_strings)(path_dictionary_context_t *instance, const ovx_string_t *path_strings, size_t num_paths, ovx_primpath_t *out_prim_paths)#

ovx_api_result_t (*create_path_list_from_paths)(path_dictionary_context_t *instance, const ovx_primpath_t *paths, size_t num_paths, ovx_primpath_list_t *out_path_list)#

ovx_api_result_t (*create_path_list_from_strings)(path_dictionary_context_t *instance, const ovx_string_t *path_strings, size_t num_paths, ovx_primpath_list_t *out_path_list)#

ovx_api_result_t (*add_path_list_reference)(path_dictionary_context_t *instance, ovx_primpath_list_t path_list)#

ovx_api_result_t (*release_path_list_reference)(path_dictionary_context_t *instance, ovx_primpath_list_t path_list)#

ovx_api_result_t (*get_strings_from_tokens)(path_dictionary_context_t *instance, const ovx_token_t *tokens, size_t num_tokens, ovx_string_t *out_strings)#

ovx_api_result_t (*get_tokens_from_paths)(path_dictionary_context_t *instance, const ovx_primpath_t *prim_paths, size_t num_paths, ovx_token_t *token_buffer, size_t token_buffer_size, ovx_token_t **out_tokens_per_path, size_t *out_num_tokens_per_path, size_t *out_num_paths_processed)#

ovx_api_result_t (*get_num_paths_from_path_list)(path_dictionary_context_t *instance, ovx_primpath_list_t path_list, size_t *out_num_paths)#

ovx_api_result_t (*get_paths_from_path_list)(path_dictionary_context_t *instance, ovx_primpath_list_t path_list, size_t start_offset, size_t max_paths, ovx_primpath_t *out_paths, size_t *out_num_paths)#

void (*release_error)(path_dictionary_context_t *context, ovx_string_t error)#

Typedefs

typedef struct path_dictionary_context_t path_dictionary_context_t#

struct path_dictionary_instance_t#

#include <path_dictionary_types.h>

Public Members

path_dictionary_vtable_t *vtable#

path_dictionary_context_t *context#: Implementation-specific data.

Functions

static inline ovx_api_result_t path_dictionary_create_tokens_from_strings( path_dictionary_instance_t *instance, const ovx_string_t *strings, size_t num_strings, ovx_token_t *out_tokens )#

static inline ovx_api_result_t path_dictionary_create_paths_from_tokens( path_dictionary_instance_t *instance, const ovx_token_t *tokens_per_path, const size_t *num_tokens_per_path, size_t num_paths, ovx_primpath_t *out_prim_paths )#

static inline ovx_api_result_t path_dictionary_create_paths_from_strings( path_dictionary_instance_t *instance, const ovx_string_t *path_strings, size_t num_paths, ovx_primpath_t *out_prim_paths )#

static inline ovx_api_result_t path_dictionary_create_path_list_from_paths( path_dictionary_instance_t *instance, const ovx_primpath_t *paths, size_t num_paths, ovx_primpath_list_t *out_path_list )#

static inline ovx_api_result_t path_dictionary_create_path_list_from_strings( path_dictionary_instance_t *instance, const ovx_string_t *path_strings, size_t num_paths, ovx_primpath_list_t *out_path_list )#

static inline ovx_api_result_t path_dictionary_add_path_list_reference( path_dictionary_instance_t *instance, ovx_primpath_list_t path_list )#

static inline ovx_api_result_t path_dictionary_release_path_list_reference( path_dictionary_instance_t *instance, ovx_primpath_list_t path_list )#

static inline ovx_api_result_t path_dictionary_get_strings_from_tokens( path_dictionary_instance_t *instance, const ovx_token_t *tokens, size_t num_tokens, ovx_string_t *out_strings )#

static inline ovx_api_result_t path_dictionary_get_tokens_from_paths(

path_dictionary_instance_t *instance,

const ovx_primpath_t *prim_paths,

size_t num_paths,

ovx_token_t *token_buffer,

size_t token_buffer_size,

ovx_token_t **out_tokens_per_path,

size_t *out_num_tokens_per_path,

size_t *out_num_paths_processed

)#

static inline ovx_api_result_t path_dictionary_get_num_paths_from_path_list( path_dictionary_instance_t *instance, ovx_primpath_list_t path_list, size_t *out_num_paths )#

static inline ovx_api_result_t path_dictionary_get_paths_from_path_list( path_dictionary_instance_t *instance, ovx_primpath_list_t path_list, size_t start_offset, size_t max_paths, ovx_primpath_t *out_paths, size_t *out_num_paths )#

static inline void path_dictionary_release_error( path_dictionary_instance_t *instance, ovx_string_t error )#

Functions

static inline bool ovx_string_contains_embedded_nul( const ovx_string_t *string )#

static inline bool ovx_string_has_null_data( const ovx_string_t *string )#