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.1.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). Only the static loader (ovstage-static) consumes any keys today — OVSTAGE_CONFIG_BINARY_PACKAGE_ROOT_PATH, which tells it where to load the ovstage shared library from and MUST be supplied here, before any other ovstage_* call, when a non-default root is needed. The path may include OVX_CONFIG_EXECUTABLE_DIR_TOKEN (“${executable_dir}”), which the loader substitutes with the absolute directory of the running executable. The ovstage shared library’s own ovstage_initialize ignores config, so pass NULL (or entry_count == 0) when linking it directly. Passing loader keys is harmless in either build.

Returns:

OVSTAGE_OK on success.

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.

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.

Relationship targets are cloned: relationship attributes (e.g. material:binding, skel:skeleton) are copied verbatim alongside value attributes, so a clone’s relationships resolve correctly when their targets are outside the cloned subtree (the common case — bindings to a shared materials scope). Targets that point inside the cloned subtree are copied verbatim and not retargeted to the clone’s own copies (matches ovrtx_clone_usd). Only value attributes are change-tracked, so relationship changes — and connectivity changes such as the source/target parents’ child lists — are not ordinal-change-tracked.

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 enum values 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, typically one of the OVSTAGE_HIERARCHY_COMPUTATION_MODEL_DEFAULT_* aliases or a concrete model returned by ovstage_get_hierarchy_computation_models.
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.1.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. (None defined yet.)

Values:

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 models 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_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)#

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.

typedef struct ovstage_population_enqueue_result_t ovstage_population_enqueue_result_t#

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.

typedef struct ovstage_population_op_wait_result_t ovstage_population_op_wait_result_t#

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.

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 the stage units (metersPerUnit, kilogramsPerUnit, upAxis) only — those are authored regardless of domains — and nothing else. Pass OVSTAGE_POPULATION_DOMAIN_ALL to populate everything.

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_stage_info_path(void)#

The reserved prim path that population authors stage units onto (metersPerUnit, kilogramsPerUnit, upAxis, etc.) — see “Stage info” above — regardless of domains.

Consumers read those units off this prim.

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

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.

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#

Instancing #

High-level instancing queries.

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>

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.
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 struct ovstage_vtable_t ovstage_vtable_t: Vtable defined in ovstage_api.h.

typedef enum ovstage_api_status_t 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.

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.

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.

typedef struct ovstage_instance_t ovstage_instance_t#

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#: Ordinal <= write floor.

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_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, TEXTURE_COORDINATE) record a geometric role on the column. Storage stays in the requested numeric dtype.
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)
- 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)
Byte-string semantics (ASSET_STRING, PATH_EXPRESSION_STRING) keep ragged kDLUInt,8,1 byte-row storage with NUL-separated, authored sub-values.
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_STRING#

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#

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: 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, consumers use tensor_count directly.
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 for this attribute, snapshot at read-submit time. 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 value at or before N: has_start_ordinal = false, end_ordinal = N. Returns the most recent value with ordinal <= end_ordinal.
Range query [start, end]: has_start_ordinal = true, start_ordinal <= end_ordinal. Returns all changes in the interval [start_ordinal, end_ordinal].

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, but returns the latest retained payload or tombstone for each selected key. Callers must query the frontier rather than assume a fixed retention depth. Its ordinal ranges are therefore not a historical-payload event log.

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 <= end_ordinal; 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.
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.
Invariant: index_map and mask are mutually exclusive.
Invariant: count is set (non-zero) when index_map or mask is non-NULL.
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 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.

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,

)#

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.

Typedefs

typedef struct path_dictionary_vtable_t path_dictionary_vtable_t#

struct path_dictionary_vtable_t

#include <path_dictionary.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#

typedef struct path_dictionary_vtable_t path_dictionary_vtable_t

typedef struct path_dictionary_instance_t path_dictionary_instance_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, )#

C API Reference#

Data Plane#

Types#

Population (USD → ovstage)#

Instancing#

API Types and Utilities#

Alignment Helpers#

Path Dictionary (OVX)#

Data Plane #

Types #

Instancing #

API Types and Utilities #

Alignment Helpers #