C API Reference#

The C API provides low-level access to the ovrtx rendering library.

For lifecycle, error-handling, status-query, logging, and ovx_string_t usage patterns, start with C API Practical Patterns.

Overview #

Functions returning ovrtx_result_t report success or failure through a status code:

OVRTX_API_SUCCESS: The operation completed successfully
OVRTX_API_ERROR: The operation failed (use ovrtx_get_last_error() for details)
OVRTX_API_TIMEOUT: The operation timed out

Many operations are stream-ordered and execute asynchronously. They return handles that can be used in subsequent operations, but the actual effects may not be produced until stream execution completes. For these asynchronous operations, enqueue may still succeed while execution fails later. Check ovrtx_wait_op() and inspect ovrtx_op_wait_result_t.error_op_ids, then retrieve per-op details with ovrtx_get_last_op_error().

Functions #

Version #

void ovrtx_get_version( uint32_t *out_major, uint32_t *out_minor, uint32_t *out_patch )#

Get the ovrtx API version that the library was compiled with.

This function can be called at any time, including before ovrtx_initialize(). It can be used to verify that the loaded library matches the header version at runtime.

The compile-time version is also available via OVRTX_VERSION_MAJOR, OVRTX_VERSION_MINOR, and OVRTX_VERSION_PATCH macros.

Parameters:

out_major – [out] Major version number
out_minor – [out] Minor version number
out_patch – [out] Patch version number

const ovrtx_build_info_t *ovrtx_get_build_info(void)#

Get the complete build identity embedded in the loaded OVRTX loader binary that exports this API.

This function is safe before ovrtx_initialize(). The returned pointer and all strings it references are immutable and remain valid while the OVRTX loader library remains loaded. Callers should use struct_size to interpret future append-only extensions safely.

Returns:: Build information for the loaded OVRTX loader library.

Creation and Destruction #

ovrtx_result_t ovrtx_register_schema_paths( const ovrtx_config_t *config )#

Register ovrtx’s USD schema/plugin discovery paths and lightweight USD/MDL environment, without loading USD or initializing the renderer.

This is intended for applications that share an OpenUSD runtime between multiple subsystems (for example ovrtx and ovphysx). USD’s schema registry and several TfEnvSettings are populated only once for the process, so every subsystem that contributes schema/plugin paths or USD-facing path environment must publish them before OpenUSD is loaded: USD reads its plugin-path variable as its libraries load, and anything published after that is never seen. Each subsystem calls its own equivalent first, after which the order of initialize calls no longer matters.

Binary package root resolution (highest precedence first):

The OMNI_USD_PLUGINS_BASE_PATH environment variable, if set.
OVRTX_CONFIG_BINARY_PACKAGE_ROOT_PATH from config, if config is non-null and contains that entry. The path may include OVX_CONFIG_EXECUTABLE_DIR_TOKEN, which the loader substitutes with the absolute directory of the running executable.
The directory of the loaded ovrtx loader library (default).

Notes:

Safe to call before ovrtx_initialize() and before ovrtx_create_renderer().
Publishes the process-global environment required before OpenUSD initializes: Hydra/USD toggles, MDL and MaterialX search paths, and the resolver’s MDL bypass.
Idempotent for matching roots: the first call performs registration; subsequent calls with the same effective root are no-ops.
First-call wins. Once schema/plugin paths have been registered against an effective binary package root, subsequent calls (here, or via ovrtx_initialize() / ovrtx_create_renderer()) that resolve to a different effective root log a warning to stderr and are no-ops; PXR_PLUGINPATH_NAME stays anchored at the first-registered root (the contract is one-shot per process, since USD’s plug system reads it once during static initialization).
Also registers the same schemas with ovstage, when ovstage is loaded, so an attached ovstage resolves them as it populates. Call before ovstage’s first populate. Never loads ovstage itself.
Calling this after USD has already been loaded has no retroactive effect on the plugin-path keys, which were bound at load.
This function does not allocate the ovrtx system, start the ovrtx runtime, load renderer plugins, or apply renderer settings; it only adjusts process-global environment used by USD discovery and USD-facing MDL/MaterialX setup.

Parameters:

config – Optional configuration (may be NULL). When non-null, the OVRTX_CONFIG_BINARY_PACKAGE_ROOT_PATH entry, if present, anchors the bundled usd_plugins/ tree. Pass the same config (or one with an equivalent binary_package_root_path) that you will subsequently supply to ovrtx_initialize() / ovrtx_create_renderer().

Returns:

Always OVRTX_API_SUCCESS. This API does not surface failure through the return code or ovrtx_get_last_error(); a mismatched root logs a warning to stderr instead. (This is the one exception to the file-level return-value rule above.)

size_t ovrtx_get_usd_plugin_path_count(const ovrtx_config_t *config)#

Number of USD schema/plugin directories ovrtx contributes for config.

Companion to ovrtx_get_usd_plugin_paths(): use this to size the destination array, then fill it in a follow-up call. Does not touch any environment variable and does not initialize the renderer. Same root-resolution rules as ovrtx_get_usd_plugin_paths() (see that function’s docstring for the first-call-wins pin).

Parameters:

config – Optional configuration (may be NULL). Root resolution matches ovrtx_register_schema_paths().

Returns:

Number of directories that ovrtx_get_usd_plugin_paths() will populate when given sufficient capacity.

size_t ovrtx_get_usd_plugin_paths( const ovrtx_config_t *config, ovx_string_t *out_paths, size_t out_paths_capacity )#

Enumerate ovrtx’s USD schema/plugin directories for config into out_paths, without mutating any environment variable.

Intended use: when a process co-loads a separate OpenUSD runtime that reads PXR_PLUGINPATH_NAME (for example usd-core in Python), the integrator calls this to obtain ovrtx’s contributions, filters out any directories that would collide with the host runtime’s built-in schemas (e.g. drop usd_particle_field on OpenUSD versions that already ship UsdVol particle schemas), and appends the remainder to PXR_PLUGINPATH_NAME before the external runtime opens its first stage. See the timing note on ovrtx_register_schema_paths() for why “before the first stage open” is critical.

Root resolution and first-call-wins pin: Root resolution matches ovrtx_register_schema_paths() (OMNI_USD_PLUGINS_BASE_PATH env, then OVRTX_CONFIG_BINARY_PACKAGE_ROOT_PATH from config, then the loader library directory). Enumeration participates in the same first-call-wins pin as registration: whichever of this function, ovrtx_register_schema_paths(), ovrtx_initialize(), or ovrtx_create_renderer() runs first pins the effective root for the process. A later call resolving a different root logs a mismatch warning to stderr and acts on the pinned root — enumeration returns the pinned root’s paths, and registration registers the pinned root. This keeps the directories the integrator publishes to PXR_PLUGINPATH_NAME consistent with what ovrtx’s bundled OpenUSD actually registers, regardless of the order the two APIs are called in.

String lifetime: Each returned ovx_string_t points into storage owned by the ovrtx loader and remains valid for the lifetime of the process. Callers must NOT free the ptr fields or otherwise modify the underlying bytes.

Parameters:

config – Optional configuration (may be NULL). Root resolution matches ovrtx_register_schema_paths().
out_paths – Destination array. May be NULL when out_paths_capacity is 0 — in that case only the count is returned. When non-NULL, the first min(count, capacity) entries are populated in a stable order (bundled schema plugins first, then the rtx_settings directory).
out_paths_capacity – Number of ovx_string_t slots available in out_paths.

Returns:

The total number of ovrtx plugin directories available for config (unchanged by capacity — a return value greater than out_paths_capacity signals truncation).

void ovrtx_library_telemetry_opt_out(void)#

Programmatically opts out of the OVRTX library startup reporting functionality for this process.

OVRTX sends one anonymous report that the library was initialized, from a background thread, the first time OVRTX initializes successfully in a process: when ovrtx_initialize() succeeds, or when ovrtx_create_renderer() initializes it implicitly. It reports at most once per process: creating more renderers, or shutting OVRTX down completely and initializing it again, does not report again. This call disables the report, and to take effect it must be called BEFORE the ovrtx_initialize() (or implicitly initializing ovrtx_create_renderer()) that first initializes OVRTX. Called afterwards it cannot take the report back, because this process has already used up its one reporting opportunity; at best it abandons a report that has not gone out yet, since the reporter waits briefly before assembling anything. The opt-out lasts for the rest of the process, across ovrtx_shutdown() and ovrtx_initialize() cycles. It does not load the OVRTX runtime or initialize anything; it can be called before ovrtx_initialize().

Note that if the NVIDIA_OMNIVERSE_PRODUCT_TELEMETRY_DISABLED environment variable is defined and set to 1 for this process, this call will be unnecessary. The environment variable based opt-out will always override the programmatic opt-out for the process: once observed it stays in effect for the lifetime of the process, and no OVRTX call can clear it. When used, this environment variable is expected to be defined for the process at launch time. Defining it programmatically with a call such as setenv() is strongly discouraged since that can lead to a race condition crash on Linux due to a known bug in the environment variable functions in glibc in versions earlier than 2.41.

Other Omniverse libraries in the same process, such as OVXR, send their own reports and have their own opt-out functions; this call affects only OVRTX. NVIDIA_OMNIVERSE_PRODUCT_TELEMETRY_DISABLED=1 covers all of them.

The startup event parameters contain the OVRTX library name and version. The surrounding request also includes a UTC timestamp, the library build variant (clientVariant: "Release", or "iBeta" for a debug library), and fixed protocol and placeholder fields. See TELEMETRY.md for the full request fields.

The message is sent as plain-text JSON over an HTTP connection, with no encryption or obfuscation of the body or the headers, and nothing is written to disk.

Note that this startup report will never contain any of the following information:

a user name, user ID, email address, real name, or geographical location.
any information about the process including process ID, host app name, module names, etc.
any personal information about a user.
any intellectual property information related to the host app or its developer.
any kind of session identifier or even an anonymous user ID.

The final ovrtx_shutdown() tears the reporter down and joins its worker thread, so it can block there. Ordinarily that is a join on a thread that finished long ago. The one case that is not bounded is a shutdown that lands while the worker sits in the platform DNS resolver, which takes no timeout and cannot be cancelled; against a black-holing DNS server that can be tens of seconds. An application that needs a hard bound on its own shutdown should opt out, which avoids the worker thread entirely.

Threading: safe to call from any thread without synchronization, with or without a live renderer.

ovrtx_result_t ovrtx_initialize(const ovrtx_config_t *config)#

Initialize the ovrtx loader or increase its ref count.

It is allowed to call this function multiple times and for each successful call a corresponding call to ovrtx_shutdown() is required.

Note that explicit initialization is not required: creating a render instance with ovrtx_create_renderer() will also initialize the system if needed. Calling ovrtx_initialize() and ovrtx_shutdown() can be used to prevent system shutdown and initialization if the renderer is recreated multiple times.

Parameters:

config – Configuration for the ovrtx system (see ovrtx_config.h). Must be non-null; may be empty (entry_count 0) for defaults.

Returns:

OVRTX_API_SUCCESS if the system was initialized or ref-count was increased successfully,
OVRTX_API_ERROR if initialization failed.

ovrtx_result_t ovrtx_shutdown()#

Shuts down the ovrtx system or decreases it’s ref count.

One call per call to ovrtx_initialize() is required. Note that any render instances that have not been destroyed will keep the system alive until they are destroyed.

A host that exits without shutting down keeps its exit code and gets stdout/stderr flushed, but the process ends in an exit handler that the ovrtx runtime installs (_exit() on Linux, TerminateProcess() on Windows), which skips some exit handlers, static destructors and stream flushes. See “Process Exit” in the Application Flow documentation.

Returns:

OVRTX_API_SUCCESS if the system was released successfully (though might still be loaded),
OVRTX_API_ERROR if the system shutdown failed or was not initialized.

ovrtx_result_t ovrtx_create_renderer(

const ovrtx_config_t *config,

ovrtx_renderer_t **out_renderer

)#

Create a new renderer instance.

System initialization is done automatically if ovrtx_initialize() has not been called yet, but in that case the config must contain both initialization and renderer settings. The system will be kept running until a corresponding call to ovrtx_destroy_renderer().

Parameters:

config – Configuration for the renderer (see ovrtx_config.h). Must be non-null; may be empty (entry_count 0) for defaults. Keys are enum-based (e.g. OVRTX_CONFIG_SYNC_MODE, OVRTX_CONFIG_LOG_FILE_PATH, OVRTX_CONFIG_ACTIVE_CUDA_GPUS); build entries with ovrtx_config_entry_bool() and ovrtx_config_entry_string().
out_renderer – [out] Renderer instance

Returns:

OVRTX_API_SUCCESS if the renderer was created successfully,
OVRTX_API_ERROR if the renderer creation failed.

ovrtx_result_t ovrtx_get_config( const ovrtx_renderer_t *renderer, ovrtx_config_t *out_config )#

Read back the configuration entries supplied when a renderer was created.

The returned config contains the explicit entries accepted by ovrtx_create_renderer(), in their original order. It does not add omitted defaults or expose internal settings derived from those entries.

The entry array and any string or blob payloads are owned by renderer and remain valid until ovrtx_destroy_renderer() is called. The caller must not free or modify them. The caller owns only the outer ovrtx_config_t value written to out_config.

Parameters:

renderer – Renderer instance from ovrtx_create_renderer().
out_config – [out] Borrowed view of the renderer’s explicit config.

Returns:

OVRTX_API_SUCCESS if the config was returned successfully,
OVRTX_API_ERROR if either argument is null or the OVRTX system is unavailable.

ovrtx_result_t ovrtx_destroy_renderer(ovrtx_renderer_t *renderer)#

Destroy a renderer instance.

If destruction of a valid renderer fails, the caller retains ownership of the renderer. Do not use it for any other operation; retry ovrtx_destroy_renderer() to finish cleanup.

Parameters:

renderer – Renderer instance to destroy

Returns:

OVRTX_API_SUCCESS if the renderer was destroyed successfully,
OVRTX_API_ERROR if the renderer destruction failed.

ovrtx_result_t ovrtx_attach_ovstage( ovrtx_renderer_t *renderer, ovstage_instance_t *stage )#

Attach an externally-owned ovstage instance to this renderer.

While attached, the renderer renders the scene held by that ovstage instead of one it builds itself.

A successful attach retains the stage until ovrtx_detach_ovstage() or renderer destruction. The caller may destroy its stage handle after attach; that invalidates only the caller’s handle and does not detach the renderer. To switch stages, detach the current stage before attaching another. At most one ovrtx renderer may be attached to an ovstage instance at a time. The stage may be attached to another renderer after it is detached.

Use ovrtx_update_from_stage() after ovstage population work and ovrtx_step_with_stage() to render a committed stage state.

Attaching rebuilds the renderer’s internal render state on the calling thread, so wait for previously enqueued operations with ovrtx_wait_op() before calling it; a step whose result ovrtx_fetch_results() has returned counts as completed, together with the operations enqueued before it. Note that an ovrtx_wait_op() timeout does not cancel an operation: it keeps running, so a timed-out wait does not make it safe to attach or detach. Attach and detach reject pending operations without changing the renderer; wait for completion before retrying. Callers must serialize attach and detach against each other and against calls that enqueue operations on the same renderer. The pending-operation check does not prevent another thread from enqueueing new work.

OVRTX validates the ovstage runtime version during attachment. An incompatible version returns OVRTX_API_ERROR without attaching; the error diagnostic reports the expected and supplied versions.

Parameters:

renderer – Renderer instance from ovrtx_create_renderer().
stage – ovstage instance to attach. Must be initialized and remain valid for the duration of this call.

Returns:

OVRTX_API_SUCCESS if the renderer was attached successfully,
OVRTX_API_ERROR if the renderer is already attached, the stage is already attached to another ovrtx renderer, operations are pending, the stage is invalid, or the attach failed. Rejection because operations are pending leaves the renderer unchanged. If attachment begins and then fails, internal state may have changed; do not use the renderer except to destroy it.

ovrtx_result_t ovrtx_detach_ovstage(ovrtx_renderer_t *renderer)#

Detach a previously-attached ovstage instance from this renderer.

The renderer returns to standalone mode and no longer renders data from the detached stage.

After a successful detach, the renderer may attach the same or a different initialized stage.

This tears down internal render state, so the in-flight operation rules described on ovrtx_attach_ovstage() apply here too. Rejection because operations are pending leaves the attachment and render state unchanged; the renderer remains usable and detach may be retried after completion. If teardown itself fails, it may be partial; do not use the renderer except to destroy it. The renderer retains any stage state still needed for safe destruction, so the caller may release its own stage handle before or after destroying the renderer.

Parameters:

renderer – Renderer instance previously passed to ovrtx_attach_ovstage().

Returns:

OVRTX_API_SUCCESS if the renderer was detached successfully,
OVRTX_API_ERROR if the renderer is not currently attached, operations are pending, or the detach failed.

ovrtx_enqueue_result_t ovrtx_update_from_stage( ovrtx_renderer_t *renderer, ovstage_ordinal_t stage_ordinal )#

Enqueue an update of the renderer’s internal state from the attached ovstage at the given ordinal.

Only valid while attached.

The stage must have committed at least once and stage_ordinal must not exceed its write floor. Call this before ovrtx_step_with_stage() so the renderer observes a stable committed snapshot.

Parameters:

renderer – Renderer instance.
stage_ordinal – Ordinal on the attached stage to update from. Must be <= the attached stage’s write floor.

Returns:

OVRTX_API_SUCCESS if the update was enqueued.
OVRTX_API_ERROR if no stage is attached or the enqueue failed.

Data Providers #

enum ovrtx_data_status_t#

Shared status domain for provider operations, accessor methods and close.

Values:

enumerator OVRTX_DATA_OK#: Operation succeeded; consume the documented outputs.

enumerator OVRTX_DATA_NOT_HANDLED#: Provider declines a root pin; only root resolution may try the next provider.

enumerator OVRTX_DATA_NOT_FOUND#: Requested resource, prim or attribute does not exist.

enumerator OVRTX_DATA_UNSUPPORTED#: Operation, representation, schema or required tracking is unavailable.

enumerator OVRTX_DATA_INVALID_ARGUMENT#: An argument or returned record violates the operation contract.

enumerator OVRTX_DATA_ACCESS_DENIED#: Provider authorization does not permit the requested access.

enumerator OVRTX_DATA_IO_ERROR#: Payload or metadata I/O failed, including an invalid short read of known-size data.

enumerator OVRTX_DATA_STALE#: The selected immutable revision can no longer be served; do not substitute newer data.

enumerator OVRTX_DATA_CANCELLED#: An accepted operation completed after honoring cancellation.

enumerator OVRTX_DATA_BUSY#: A synchronous removal/close cannot proceed while dependents remain; no ownership changes.

enumerator OVRTX_DATA_INVALID_STATE#: The service or operation is unavailable in its current lifecycle state.

enumerator OVRTX_DATA_INVALID_HANDLE#: An accessor or array lease handle is unknown or already released.

enumerator OVRTX_DATA_OUT_OF_RANGE#: A selector is outside its domain, or a scalar sizing query needs more storage.

enum ovrtx_data_submit_t#

Submission result, separate from the asynchronous operation completion status.

Values:

enumerator OVRTX_DATA_ACCEPTED#: Exactly one completion is owed, possibly inline.

enumerator OVRTX_DATA_RETRY#

Temporary backpressure; retain no arguments and invoke no completion.

Caller may resubmit.

enumerator OVRTX_DATA_REJECTED#

Submission refused; retain no arguments and invoke no completion.

No routing fallback.

enum ovrtx_data_kind_t#

Resource representation requested at pin time; the successful result must match.

Values:

enumerator OVRTX_DATA_BYTES#: Encoded bytes served by positioned reads and optional maps.

enumerator OVRTX_DATA_STRUCTURED#: Schema-defined data served by prepared accessors.

enum ovrtx_data_range_strategy_t#

Pin-time access-cost hint, independent of identity.

Structured resources use UNKNOWN.

Values:

enumerator OVRTX_DATA_RANGE_UNKNOWN#: No range-cost information is available.

enumerator OVRTX_DATA_RANGE_NATIVE#: Reads ranges directly without whole-object materialization.

enumerator OVRTX_DATA_RANGE_CACHED_READ_THROUGH#: Fetched data is cached for subsequent reads; not necessarily resident at pin time.

enumerator OVRTX_DATA_RANGE_MATERIALIZE_ONLY#: Range access materializes the whole object, without a cross-read reuse guarantee.

enumerator OVRTX_DATA_RANGE_UNSUPPORTED#: Subranges are unsupported; whole-object reads/maps may still succeed.

typedef enum ovrtx_data_status_t ovrtx_data_status_t: Shared status domain for provider operations, accessor methods and close.

typedef struct ovrtx_data_accessor_context_t ovrtx_data_accessor_context_t#: Provider-owned, non-NULL prepared state, valid until successful close_accessor().

typedef struct ovrtx_data_array_lease_id_t ovrtx_data_array_lease_id_t#

Accessor-local array borrow identity.

Zero is valid. Each live acquisition has its own release obligation on its accessor. Copying does not acquire a borrow, prove liveness, or identify the owning accessor.

typedef struct ovrtx_data_prim_info_t ovrtx_data_prim_info_t#: Value-copy prim metadata; no independent ownership or lease.

typedef struct ovrtx_data_attribute_info_t ovrtx_data_attribute_info_t#: Prepared attribute layout shared by metadata, scalar reads and array leases.

typedef struct ovrtx_data_cpu_array_t ovrtx_data_cpu_array_t#: Borrowed CPU array and its release obligation; the record itself may be copied.

typedef struct ovrtx_data_gpu_access_desc_t ovrtx_data_gpu_access_desc_t#: Caller-owned GPU selection descriptor, borrowed only during acquisition.

typedef struct ovrtx_data_gpu_array_t ovrtx_data_gpu_array_t#: Borrowed CUDA array, readiness information and explicit GPU lease.

typedef struct ovrtx_data_accessor_vtable_t ovrtx_data_accessor_vtable_t#

Access and traverse immutable data prepared by open_accessor_async().

Set struct_size to sizeof(ovrtx_data_accessor_vtable_t) and abi_version to OVRTX_DATA_ACCESSOR_ABI_VERSION. Keep the table immutable until accessor close. All methods are synchronous, thread-safe, and perform no I/O or hidden transfers. All get_* callbacks are required; only capability-controlled array pairs may be NULL. A live context is a precondition; NULL/dangling contexts cannot be safely validated. Paths and tokens must originate from the dictionary supplied when opening. The caller owns output records/buffers; providers do not retain their addresses. Unless a method explicitly documents a sizing result, consume outputs only on OK. Errors acquire no lease and transfer no ownership. Do not race successful close against any call, or release against reads using the same lease. Token/path values are borrowed dictionary handles, not independently owned strings. Scalar bytes are copied; arrays are immutable borrows protected by explicit per-accessor leases.

typedef struct ovrtx_data_accessor_t ovrtx_data_accessor_t#: Immutable structured result of open_accessor_async(); traversal performs no I/O.

typedef struct ovrtx_data_provider_id_t ovrtx_data_provider_id_t#

Process-local registration identity.

Zero is invalid; IDs are not reused during the process. Copying does not retain the provider or prove that it remains registered.

typedef struct ovrtx_data_request_t ovrtx_data_request_t#: Caller-owned opaque operation token for cancellation, borrowed through completion and submission/cancel return.

typedef enum ovrtx_data_submit_t ovrtx_data_submit_t: Submission result, separate from the asynchronous operation completion status.

typedef enum ovrtx_data_kind_t ovrtx_data_kind_t: Resource representation requested at pin time; the successful result must match.

typedef enum ovrtx_data_range_strategy_t ovrtx_data_range_strategy_t

Pin-time access-cost hint, independent of identity.

Structured resources use UNKNOWN.

typedef struct ovrtx_data_request_options_t ovrtx_data_request_options_t#

Request options.

NULL is equivalent to zero hints, timeout, priority and pin_flags. For a non-NULL record, struct_size must be initialized to sizeof(ovrtx_data_request_options_t). Hints never change revision, cancellation or completion guarantees. WHOLE_OBJECT describes future access; it never permits payload loading during pinning. Whole-object fallback reads also carry it on each positioned chunk, including unknown-size resources. It is not an exclusive stream or cursor lease: concurrent consumers may issue independent reads against the same pin. The runtime retains this record through completion and submission/cancel return. Unknown hint bits are ignored; unknown pin_flags or both tracking flags are invalid. pin_flags must be zero for read, map and accessor requests.

typedef struct ovrtx_data_resource_handle_t ovrtx_data_resource_handle_t#

Provider-owned state for a successful pin.

The runtime passes this opaque handle only to its owning provider and never dereferences it. Valid until unpin().

typedef struct ovrtx_data_resource_t ovrtx_data_resource_t#

Record and strings are callback-scoped.

The runtime copies strings before the completion returns. Only handle remains provider-owned until unpin().

UDIM manifest schema: Request OVRTX_DATA_STRUCTURED, schema “ovrtx.texture.udim”, schema_version=1; advertise CPU_ARRAYS and accept open_accessor_async(0, OVRTX_DATA_SIZE_UNKNOWN). In the supplied dictionary, /udim.tile_ids is a u32 CPU array of unique IDs in [1001,9999]. For each ID, /tiles/tile_<id>.asset is a scalar token naming a nonempty reference to pin relative to this manifest resource. All array leases must be released before close_accessor. The C++ helper ovrtx/providers/udim_manifest.hpp implements this accessor from a tile list without renderer-private dependencies. An empty tile list is valid. The built-in storage provider requires a supported tiling marker in the innermost basename for both loose and packaged resources; non-pattern STRUCTURED root requests return NOT_HANDLED; dependency requests return UNSUPPORTED without rerouting. A valid pattern with no matching tiles returns an empty manifest.
Package references: Package references use outer[member], including nested outer[a.usdz[b]]. Resolve the outer resource through the owning provider and retain its byte lease while member views are in use. ovrtx/providers/stored_package.hpp provides validated, zero-copy views of stored ZIP/ZIP64 members used by USDZ; compressed/encrypted members are unsupported. Views do not own storage. The built-in provider resolves relative dependencies inside the innermost package and rejects paths escaping it. Absolute paths and URI references resolve outside the package using the same built-in provider; they do not reroute to another provider. Custom providers define their own resolution.

typedef struct ovrtx_data_byte_view_t ovrtx_data_byte_view_t#: Callback-scoped map result; the bytes and opaque lease outlive the record until release_map().

typedef void (*ovrtx_data_pin_done_t)(void *user_data, ovrtx_data_status_t status, const ovrtx_data_resource_t *resource, ovx_string_t error)#

Complete one accepted pin operation, exactly once, possibly inline.

The caller copies the record and its strings during this call. OK transfers one pin obligation even when cancellation races success; failures transfer nothing and require NULL resource. This callback returns no status and may retire user_data. Never access user_data after invoking it. Error text is optional diagnostic context, not a status override.

Param user_data:: Unchanged opaque caller-owned context supplied to pin_async(); never dereference/free it.
Param status:: Terminal operation status; see pin_async(). NOT_HANDLED is only a root-routing decline.
Param resource:: Non-NULL ABI-valid callback-scoped record on OK, NULL otherwise. Its handle lives until unpin().
Param error:: Callback-scoped length-delimited diagnostic; empty is allowed. The caller copies it if needed.
Return:: No value; completion does not acknowledge subsequent consumer processing.

typedef void (*ovrtx_data_read_done_t)(void *user_data, ovrtx_data_status_t status, uint64_t bytes_read, ovx_string_t error)#

Complete one accepted positioned read, exactly once, possibly inline.

Stop accessing the destination before calling. The caller owns the destination, including on failure; no buffer ownership is transferred. Output bytes are consumed only on OK. A short successful read means EOF, subject to the pinned known-size checks in read_async(). The callback may retire user_data; do not use it again after invoking this callback.

Param user_data:: Unchanged opaque caller-owned context supplied to read_async(); never dereference/free it.
Param status:: Terminal operation status; NOT_HANDLED and BUSY are invalid. See read_async().
Param bytes_read:: Number of bytes written, at most the requested size; consumed only on OK.
Param error:: Optional callback-scoped diagnostic; empty is allowed and status remains authoritative.
Return:: No value; no additional completion is permitted.

typedef void (*ovrtx_data_accessor_done_t)(void *user_data, ovrtx_data_status_t status, const ovrtx_data_accessor_t *accessor, ovx_string_t error)#

Complete one accepted structured open, exactly once, possibly inline.

All preparation finishes before this callback. The caller copies the accessor record; its context, table and prepared data remain live until successful close_accessor(). OK transfers one close obligation, including raced cancellation successes. Failures pass NULL and transfer nothing. Do not access user_data after invoking this callback.

Param user_data:: Unchanged opaque caller-owned context supplied to open_accessor_async(); never dereference/free it.
Param status:: Terminal operation status; NOT_HANDLED and BUSY are invalid. See open_accessor_async().
Param accessor:: Non-NULL callback-scoped record on OK, NULL otherwise; dictionary remains caller-owned.
Param error:: Optional callback-scoped diagnostic; empty is allowed and status remains authoritative.
Return:: No value; consumer accessor calls may follow successful completion.

typedef void (*ovrtx_data_map_done_t)(void *user_data, ovrtx_data_status_t status, const ovrtx_data_byte_view_t *view, ovx_string_t error)#

Complete one accepted byte map, exactly once, possibly inline.

The record is callback-scoped. OK transfers one release_map obligation, including empty maps and raced cancellation successes; data remains immutable until that release. Failure requires NULL view and transfers nothing. UNSUPPORTED permits read fallback; other failures are terminal. Do not access user_data after invoking this callback.

Param user_data:: Unchanged opaque caller-owned context supplied to map_async(); never dereference/free it.
Param status:: Terminal operation status; NOT_HANDLED and BUSY are invalid. See map_async().
Param view:: Non-NULL ABI-valid callback-scoped record on OK, NULL otherwise; lease must be non-NULL even if empty.
Param error:: Optional callback-scoped diagnostic; empty is allowed and status remains authoritative.
Return:: No value; no additional completion is permitted.

typedef struct ovrtx_data_provider_context_t ovrtx_data_provider_context_t#

Opaque implementation state passed to every provider operation.

May be NULL for stateless providers.

typedef struct ovrtx_data_provider_desc_t ovrtx_data_provider_desc_t#

Registration metadata, separate from the provider implementation.

Set struct_size to sizeof(ovrtx_data_provider_desc_t) and abi_version to OVRTX_DATA_PROVIDER_ABI_VERSION.

typedef struct ovrtx_data_provider_vtable_t ovrtx_data_provider_vtable_t#

Immutable provider operations.

Multiple instances may share one table. Async operations pair done with caller-owned user_data; return user_data unchanged as done’s first argument, following the completion rules above. Set struct_size to sizeof(ovrtx_data_provider_vtable_t) and abi_version to OVRTX_DATA_PROVIDER_ABI_VERSION.

typedef struct ovrtx_data_provider_t ovrtx_data_provider_t#

Provider implementation instance.

Registration copies this pair; it borrows the immutable vtable and context until successful unregister or shutdown.

ovrtx_data_status_t ovrtx_register_data_provider( const ovrtx_data_provider_desc_t *desc, const ovrtx_data_provider_t *provider, ovrtx_data_provider_id_t *out_provider )#

Register one provider instance for process-wide resource resolution.

Call after ovrtx_initialize() and before submitting references that should use this provider. No renderer instance is required. Descriptor strings and the instance pair are copied; the application retains the immutable vtable, callback code and context until successful removal or completed shutdown. Registration does not take ownership of application storage. Failed registration retains nothing and leaves routes unchanged. Namespace keys must be unique among live registrations. Matching explicit schemes precede catch-alls; priority orders each group, with registration order breaking ties. Application routes precede eligible built-in providers. Only root NOT_HANDLED reroutes. Registration changes routing for future resolutions without changing existing pins. Do not race shutdown or invoke lifecycle operations from provider operation callbacks. Clears the calling thread’s last error; failures set ovrtx_get_last_error(). Copy that diagnostic before the next OVRTX API call on the same thread. Asynchronous provider failures instead use their completion status/error; accessor methods return status directly.

Parameters:

desc – Non-NULL registration metadata with current size/version and valid callback capabilities. Borrowed for this call; namespace/scheme strings are copied.
provider – Non-NULL implementation pair with a non-NULL ABI-valid vtable. The context may be NULL.
out_provider – [out] Non-NULL destination, set to a nonzero ID on success and zero on failure.

Returns:

OVRTX_DATA_OK if registration succeeded.
OVRTX_DATA_INVALID_ARGUMENT for null arguments, invalid sizes/versions, duplicate/invalid namespace, invalid URI scheme/capabilities, or missing required callbacks/pairs.
OVRTX_DATA_INVALID_STATE when the system/service is unavailable or draining.

ovrtx_data_status_t ovrtx_unregister_data_provider( ovrtx_data_provider_id_t provider )#

Remove an idle provider registration atomically without waiting for dependents.

Retire consumers, requests, pins, maps and accessors first. BUSY leaves registration and routing unchanged; release dependents and retry. On OK, no provider callback/state remains borrowed by this registration, and the application may release its table, context and code unless another registration uses them. Provider-owned background work (including monitoring) must also be quiesced before destroying its state/code; unregister accounts for runtime-held dependencies, not arbitrary application threads. The ID becomes invalid. Removing one provider does not invalidate pins belonging to another provider. Do not race shutdown or call from provider operation callbacks. Clears the calling thread’s last error and sets a diagnostic on failure; copy it before the next API call.

Parameters:

provider – Nonzero live registration ID returned by ovrtx_register_data_provider().

Returns:

OVRTX_DATA_OK if removed; ownership of application storage is unchanged.
OVRTX_DATA_BUSY while outstanding references or operations retain this provider.
OVRTX_DATA_INVALID_ARGUMENT for zero, unknown, already-removed or non-removable IDs.
OVRTX_DATA_INVALID_STATE when the system/service is unavailable.

ovrtx_data_status_t ovrtx_data_notify_changed( ovrtx_data_provider_id_t provider, const ovx_string_t *identifiers, uint64_t identifier_count )#

Notify consumers of a batch of changed canonical resource identifiers.

Publish all replacement revisions before calling, outside provider locks; callbacks may enqueue reads/reloads. The batch is delivered together, but does not establish an atomic snapshot across resources. Existing immutable pins/leases remain valid and unchanged. Currently only MDL subscribes; textures, SPG, IndeX and NuRec do not automatically reload from this event. Subscribers are called synchronously on this calling thread; callbacks from concurrent notifications may run on different threads. Return waits for notification callbacks, but not for asynchronous reloads or compilation. Do not call recursively from a change callback. No subscriber registration is forwarded to the provider; pin_flags express per-pin tracking interest. Notifications may also be published without interested pins. A tracked resource deletion is a change: publish the identifier and let a fresh pin report NOT_FOUND. Tracking never authorizes changing bytes of an existing pin.

Parameters:

provider – Live provider registration that owns the identifiers.
identifiers – Array of nonempty canonical identifiers returned by this provider, with no embedded NUL. The array and strings are borrowed for this call only. Duplicates are coalesced; an outer package identifier covers its members only for well-formed USDZ bracket paths (including nested packages). Other brackets in opaque identifiers do not imply containment. An inner package identifier includes its enclosing closing brackets. Delivery order is unspecified.
identifier_count – Number of array entries. Zero is a no-op for a live provider and permits a null array; it does not mean all resources changed.

Returns:

OVRTX_DATA_OK if accepted (even with no listeners), OVRTX_DATA_INVALID_ARGUMENT for an invalid/removed provider or malformed batch, or OVRTX_DATA_INVALID_STATE when the service is unavailable. The whole batch is validated before delivery; malformed input delivers no events. No notification is required when the logical resource never changes. Providers reporting change_tracking_enabled must deliver changes for the interested pin lifetime. Not callable from a provider operation callback, or concurrently with ovrtx shutdown.

OVRTX_DATA_ACCESSOR_ABI_VERSION#: Exact accessor layout version required by the runtime; independent of the provider ABI.

OVRTX_DATA_ACCESSOR_CAP_CPU_ARRAYS#: Every opened accessor supplies the acquire_array_cpu/release_array_cpu pair.

OVRTX_DATA_ACCESSOR_CAP_GPU_ARRAYS#: Every opened accessor supplies the acquire_array_gpu/release_array_gpu pair.

OVRTX_DATA_SIZE_UNKNOWN#

Unknown byte length, or map-through-EOF size.

Structured selectors are schema-defined. Not a read_async read-to-EOF request. Zero byte length means a known empty resource.

OVRTX_DATA_PIN_WATCH_CHANGES#

Request tracking if available; successful pin may report it disabled.

Mutually exclusive with REQUIRE_CHANGE_TRACKING. Neither flag requests no tracking; interest lasts until unpin.

OVRTX_DATA_PIN_REQUIRE_CHANGE_TRACKING#

Require tracking for this pin; unavailable tracking completes with UNSUPPORTED.

Mutually exclusive with WATCH_CHANGES. See pin_async for gap-free establishment and lifetime.

OVRTX_DATA_HINT_WHOLE_OBJECT#: Advisory future whole-object access intent; never authorizes payload I/O during pinning.

OVRTX_DATA_PROVIDER_ABI_VERSION#: Exact descriptor/vtable layout version required by registration; independent of accessor ABI.

OVRTX_INVALID_DATA_PROVIDER_ID#: Invalid value for ovrtx_data_provider_id_t.

struct ovrtx_data_array_lease_id_t

#include <ovrtx_data_provider.h>

Accessor-local array borrow identity.

Zero is valid. Each live acquisition has its own release obligation on its accessor. Copying does not acquire a borrow, prove liveness, or identify the owning accessor.

Public Members

uint64_t raw_id#

struct ovrtx_data_prim_info_t

#include <ovrtx_data_provider.h>

Value-copy prim metadata; no independent ownership or lease.

Public Members

ovx_token_t type_name#: Dictionary-owned type-name token, or zero when no type is supplied.

struct ovrtx_data_attribute_info_t

#include <ovrtx_data_provider.h>

Prepared attribute layout shared by metadata, scalar reads and array leases.

Public Members

ovrtx_attribute_type_t type#

Packed element type; this API currently supports only:

OVRTX_SEMANTIC_NONE: kDLUInt with 8/32/64 bits, kDLInt with 64 bits, or kDLFloat with 32/64 bits. dtype.lanes > 0 is the packed component count.
OVRTX_SEMANTIC_TOKEN_ID: {kDLUInt, 64, 1}, storing dictionary-owned ovx_token_t. Both forms support scalars and arrays. is_array distinguishes arrays (including one-element arrays) from scalars. No other dtype/semantic combinations are supported yet, even if ovrtx_attribute_type_t describes them. Providers return UNSUPPORTED for unsupported attributes, without coercion.

uint64_t count#: Logical element count; one for a scalar attribute.

struct ovrtx_data_cpu_array_t

#include <ovrtx_data_provider.h>

Borrowed CPU array and its release obligation; the record itself may be copied.

Public Members

ovrtx_data_array_lease_id_t lease#: Release exactly once using the matching accessor and memory kind.

const void *data#: Immutable bytes through lease release; non-NULL unless byte_size is zero.

uint64_t byte_size#: count * dtype.lanes * (dtype.bits / 8); tightly packed.

ovrtx_data_attribute_info_t layout#: Matches get_attribute_info; is_array is true.

struct ovrtx_data_gpu_access_desc_t

#include <ovrtx_data_provider.h>

Caller-owned GPU selection descriptor, borrowed only during acquisition.

Public Members

DLDevice device#: Requested CUDA device; acquisition does not migrate data.

struct ovrtx_data_gpu_array_t

#include <ovrtx_data_provider.h>

Borrowed CUDA array, readiness information and explicit GPU lease.

Public Members

ovrtx_data_array_lease_id_t lease#: Release exactly once using the matching accessor and memory kind.

DLTensor tensor#

Immutable CUDA tensor on the requested device.

dtype matches get_attribute_info; ndim = 1, shape[0] = count, strides is NULL or {1}, and byte_offset locates the first element. Tensor data, shape and strides remain valid through release.

ovstage_cuda_sync_t cuda_sync#

Producer readiness, using the OVStage handoff contract.

Before accessing tensor data, synchronize each nonzero field on tensor.device: stream 1 denotes the default stream, >1 a cudaStream_t to drain; wait_event is a cudaEvent_t to wait on. Both zero means the data is already ready. Provider-owned synchronization objects remain valid through lease release.

struct ovrtx_data_accessor_vtable_t

#include <ovrtx_data_provider.h>

Access and traverse immutable data prepared by open_accessor_async().

Set struct_size to sizeof(ovrtx_data_accessor_vtable_t) and abi_version to OVRTX_DATA_ACCESSOR_ABI_VERSION. Keep the table immutable until accessor close. All methods are synchronous, thread-safe, and perform no I/O or hidden transfers. All get_* callbacks are required; only capability-controlled array pairs may be NULL. A live context is a precondition; NULL/dangling contexts cannot be safely validated. Paths and tokens must originate from the dictionary supplied when opening. The caller owns output records/buffers; providers do not retain their addresses. Unless a method explicitly documents a sizing result, consume outputs only on OK. Errors acquire no lease and transfer no ownership. Do not race successful close against any call, or release against reads using the same lease. Token/path values are borrowed dictionary handles, not independently owned strings. Scalar bytes are copied; arrays are immutable borrows protected by explicit per-accessor leases.

Public Members

uint32_t struct_size#: Set to sizeof(ovrtx_data_accessor_vtable_t); must cover this ABI.

uint32_t abi_version#: Must equal OVRTX_DATA_ACCESSOR_ABI_VERSION.

ovrtx_data_status_t (*get_roots)(ovrtx_data_accessor_context_t *context, uint64_t start_index, ovx_primpath_t *storage, uint64_t capacity, uint64_t *out_total)#

Copy a page of root prim paths from the prepared selection.

The total and enumeration order are stable for this immutable accessor; no lexical ordering is required. NULL storage is a count-only query and ignores capacity. Otherwise copy exactly min(capacity, total - start_index) handles when start_index is below total. At or beyond total (including UINT64_MAX), or with zero capacity, succeed without writing storage. A short page is normal success, not OUT_OF_RANGE. Always write the full sequence length to out_total on success, independent of start_index and capacity. Entries beyond the written prefix remain untouched. Performs no I/O or hidden transfers and acquires no ownership or leases. The caller owns storage; copied handles remain dictionary-owned. Retain the dictionary while using them. An empty selection succeeds with total zero.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param start_index:

Zero-based start in the enumeration; indexes past the end are allowed.

Param storage:

[out] Optional caller-owned array of capacity prim-path handles; never retained.

Param capacity:

Storage capacity in elements, not bytes; ignored if storage is NULL.

Param out_total:

[out] Non-NULL destination for the full sequence length; consume only on success.

Return:

OVRTX_DATA_OK if out_total and the requested page were written, including empty pages.
OVRTX_DATA_INVALID_ARGUMENT if out_total is NULL.

ovrtx_data_status_t (*get_children)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, uint64_t start_index, ovx_primpath_t *storage, uint64_t capacity, uint64_t *out_total)#

Copy a page of immediate child prim paths from the prepared selection.

The total and enumeration order are stable for this immutable accessor; no lexical ordering is required. NULL storage is a count-only query and ignores capacity. Otherwise copy exactly min(capacity, total - start_index) handles when start_index is below total. At or beyond total (including UINT64_MAX), or with zero capacity, succeed without writing storage. A short page is normal success, not OUT_OF_RANGE. Always write the full sequence length to out_total on success, independent of start_index and capacity. Entries beyond the written prefix remain untouched. Performs no I/O or hidden transfers and acquires no ownership or leases. The caller owns storage; copied handles remain dictionary-owned. Retain the dictionary while using them. Excludes deeper descendants and children outside the prepared selection. A present leaf succeeds with total zero, distinct from an absent prim.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim from this accessor’s dictionary; must exist in the prepared selection.

Param start_index:

Zero-based start in the enumeration; indexes past the end are allowed.

Param storage:

[out] Optional caller-owned array of capacity prim-path handles; never retained.

Param capacity:

Storage capacity in elements, not bytes; ignored if storage is NULL.

Param out_total:

[out] Non-NULL destination for the full sequence length; consume only on success.

Return:

OVRTX_DATA_OK if out_total and the requested page were written, including empty pages.
OVRTX_DATA_NOT_FOUND if prim is absent, even for a count-only or empty-page query.
OVRTX_DATA_INVALID_ARGUMENT if out_total is NULL.

ovrtx_data_status_t (*get_attributes)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, uint64_t start_index, ovx_token_t *storage, uint64_t capacity, uint64_t *out_total)#

Copy a page of attribute-name tokens exposed by a prim.

The total and enumeration order are stable for this immutable accessor; no lexical ordering is required. NULL storage is a count-only query and ignores capacity. Otherwise copy exactly min(capacity, total - start_index) handles when start_index is below total. At or beyond total (including UINT64_MAX), or with zero capacity, succeed without writing storage. A short page is normal success, not OUT_OF_RANGE. Always write the full sequence length to out_total on success, independent of start_index and capacity. Entries beyond the written prefix remain untouched. Performs no I/O or hidden transfers and acquires no ownership or leases. The caller owns storage; copied handles remain dictionary-owned. Retain the dictionary while using them. Each name occurs once, including attributes whose types get_attribute_info() cannot represent. A present attribute-free prim succeeds with total zero. No attribute values are copied. Required independently of CPU/GPU array capabilities.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim from this accessor’s dictionary; must exist in the prepared selection.

Param start_index:

Zero-based start in the enumeration; indexes past the end are allowed.

Param storage:

[out] Optional caller-owned array of capacity attribute-name handles; never retained.

Param capacity:

Storage capacity in elements, not bytes; ignored if storage is NULL.

Param out_total:

[out] Non-NULL destination for the full sequence length; consume only on success.

Return:

OVRTX_DATA_OK if out_total and the requested page were written, including empty pages.
OVRTX_DATA_NOT_FOUND if prim is absent, even for a count-only or empty-page query.
OVRTX_DATA_INVALID_ARGUMENT if out_total is NULL.

ovrtx_data_status_t (*get_prim_info)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, ovrtx_data_prim_info_t *info)#

Copy metadata describing a prim in the prepared selection.

This retrieves prim metadata, not an attribute list or attribute values. Use get_attributes() to discover attribute names. The result record is a value copy; any tokens in it remain owned by the supplied dictionary. No lease is acquired, and a prim without a type name may return a zero type_name.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim path from this accessor’s dictionary; must identify a prim in the prepared selection.

Param info:

[out] Non-NULL destination for the metadata record.

Return:

OVRTX_DATA_OK if info was written.
OVRTX_DATA_NOT_FOUND if prim is absent.
OVRTX_DATA_INVALID_ARGUMENT if info is NULL.

ovrtx_data_status_t (*get_attribute_info)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, ovx_token_t attribute, ovrtx_data_attribute_info_t *info)#

Copy the storage type and logical element count of an attribute.

The result describes prepared storage; it does not acquire or copy the payload. Scalars have count one and is_array false. Arrays have is_array true even when count is zero or one. dtype.lanes is the packed component count per logical element. Only the type/semantic combinations documented by ovrtx_data_attribute_info_t are supported; do not silently coerce other types. Enumeration may expose unsupported attributes. This value copy acquires no lease and remains usable after the call.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim path from this accessor’s dictionary; must identify a prim in the prepared selection.

Param attribute:

Attribute-name token from the same dictionary as prim.

Param info:

[out] Non-NULL destination for the attribute layout.

Return:

OVRTX_DATA_OK if info was written.
OVRTX_DATA_NOT_FOUND if prim or attribute is absent.
OVRTX_DATA_UNSUPPORTED if the attribute type/semantic cannot be represented.
OVRTX_DATA_INVALID_ARGUMENT if info is NULL.

ovrtx_data_status_t (*get_scalar_attribute)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, ovx_token_t attribute, void *buffer, uint64_t capacity_bytes, uint64_t *required_bytes)#

Copy one scalar attribute into caller-owned storage.

Storage is tightly packed, using dtype.lanes * (dtype.bits / 8) bytes and the layout reported by get_attribute_info(). A NULL buffer or insufficient capacity is a sizing query: set required_bytes and return OUT_OF_RANGE without copying. With sufficient capacity, copy the whole scalar and set required_bytes to its size; never partially copy a scalar. An array, including a one-element array, is not a scalar. The copied bytes belong to the caller. A copied token remains dictionary-owned; retain the dictionary when interpreting it. No array lease is created.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim path from this accessor’s dictionary; must identify a prim in the prepared selection.

Param attribute:

Attribute-name token from the same dictionary as prim.

Param buffer:

[out] Destination of capacity_bytes bytes; may be NULL to query the required size.

Param capacity_bytes:

Available destination capacity in bytes.

Param required_bytes:

[out] Non-NULL size output, valid on OK and on the sizing-query OUT_OF_RANGE result.

Return:

OVRTX_DATA_OK if the entire scalar was copied.
OVRTX_DATA_OUT_OF_RANGE if buffer is NULL or capacity_bytes is insufficient; required_bytes is set.
OVRTX_DATA_NOT_FOUND if prim or attribute is absent.
OVRTX_DATA_UNSUPPORTED if its type/semantic cannot be represented.
OVRTX_DATA_INVALID_ARGUMENT if required_bytes is NULL or the attribute is an array.

ovrtx_data_status_t (*acquire_array_cpu)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, ovx_token_t attribute, ovrtx_data_cpu_array_t *array)#

Borrow an immutable, tightly packed CPU array from the prepared selection.

This callback and release_array_cpu must both be non-NULL exactly when the provider advertises OVRTX_DATA_ACCESSOR_CAP_CPU_ARRAYS. GPU support does not imply CPU support. Acquisition performs no I/O, copying to another device, or hidden materialization. The returned layout matches get_attribute_info(); byte_size equals count * dtype.lanes

(dtype.bits / 8). A successful empty array still acquires a lease and may have NULL data. Copy the result record as needed, but do not free or modify its data. Release each successful lease exactly once on this accessor before closing it. Data is valid only until that release; error results transfer no lease.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim path from this accessor’s dictionary; must identify a prim in the prepared selection.

Param attribute:

Attribute-name token from the same dictionary as prim.

Param array:

[out] Non-NULL destination for the data pointer, layout, byte size, and lease ID.

Return:

OVRTX_DATA_OK if a lease and array view were returned, including for an empty array.
OVRTX_DATA_NOT_FOUND if prim or attribute is absent.
OVRTX_DATA_UNSUPPORTED if the type or prepared CPU representation is unavailable.
OVRTX_DATA_INVALID_ARGUMENT if array is NULL or the attribute is scalar.

ovrtx_data_status_t (*release_array_cpu)(ovrtx_data_accessor_context_t *context, ovrtx_data_array_lease_id_t lease)#

Release one CPU array lease acquired from this accessor.

The caller must finish all reads of the borrowed array before releasing it. On success the lease and its data view become invalid, even if underlying storage is shared with other leases. Release empty arrays as well. This does not close the accessor or release its resource pin; other leases retain their own lifetime. This callback is required only with OVRTX_DATA_ACCESSOR_CAP_CPU_ARRAYS and must otherwise be NULL.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param lease:

Unreleased lease ID returned by acquire_array_cpu() on this accessor.

Return:

OVRTX_DATA_OK if the lease was released.
OVRTX_DATA_INVALID_HANDLE if the lease is unknown or already released; no ownership is transferred.

ovrtx_data_status_t (*acquire_array_gpu)(ovrtx_data_accessor_context_t *context, ovx_primpath_t prim, ovx_token_t attribute, const ovrtx_data_gpu_access_desc_t *access, ovrtx_data_gpu_array_t *array)#

Borrow an immutable CUDA tensor already prepared on the requested device.

This callback and release_array_gpu must both be non-NULL exactly when the provider advertises OVRTX_DATA_ACCESSOR_CAP_GPU_ARRAYS. CPU support does not imply GPU support. Do not initiate I/O, migrate data, or prepare another device representation here. The returned DLTensor has ndim 1, shape[0] equal to the logical element count, packed dtype matching get_attribute_info(), and strides NULL or {1}; honor byte_offset. Before reading the tensor on tensor.device, the consumer synchronizes both nonzero cuda_sync fields: stream 1 is the default stream, stream >1 is a cudaStream_t to drain, and wait_event is a cudaEvent_t to wait on. Both zero means the data is already ready. Tensor data, shape, strides, and synchronization objects remain provider-owned through lease release. Do not free them. Finish device accesses before release_array_gpu(). Every successful acquisition, including an empty array, requires exactly one release on this accessor before close. Error results transfer no lease.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param prim:

Prim path from this accessor’s dictionary; must identify a prim in the prepared selection.

Param attribute:

Attribute-name token from the same dictionary as prim.

Param access:

Non-NULL descriptor selecting the CUDA device; borrowed for this call.

Param array:

[out] Non-NULL destination for the tensor, readiness metadata, and lease ID.

Return:

OVRTX_DATA_OK if the tensor and lease were returned.
OVRTX_DATA_NOT_FOUND if prim or attribute is absent.
OVRTX_DATA_UNSUPPORTED for non-CUDA devices, unsupported types, or unavailable prepared representations.
OVRTX_DATA_INVALID_ARGUMENT if access or array is NULL, or the attribute is scalar.

ovrtx_data_status_t (*release_array_gpu)(ovrtx_data_accessor_context_t *context, ovrtx_data_array_lease_id_t lease)#

Release one GPU array lease after all consumer device accesses have completed.

The caller must synchronize outstanding device work using this view before release; this function is not a substitute for that synchronization. Success invalidates the lease, tensor data/metadata pointers, and provider-owned synchronization objects for this view. Other leases keep their own lifetime. Empty arrays also require release. This does not close the accessor or unpin its resource. Required only when the provider advertises OVRTX_DATA_ACCESSOR_CAP_GPU_ARRAYS; otherwise this callback must be NULL.

Param context:

Live, non-NULL accessor context returned by open_accessor_async(). Borrowed for this call.

Param lease:

Unreleased lease ID returned by acquire_array_gpu() on this accessor.

Return:

OVRTX_DATA_OK if the lease was released.
OVRTX_DATA_INVALID_HANDLE if the lease is unknown or already released; no ownership is transferred.

struct ovrtx_data_accessor_t

#include <ovrtx_data_provider.h>

Immutable structured result of open_accessor_async(); traversal performs no I/O.

Public Members

const ovrtx_data_accessor_vtable_t *vtable#: Non-NULL immutable table, borrowed until close succeeds.

ovrtx_data_accessor_context_t *context#: Non-NULL provider-owned state; never free directly.

struct ovrtx_data_provider_id_t

#include <ovrtx_data_provider.h>

Process-local registration identity.

Zero is invalid; IDs are not reused during the process. Copying does not retain the provider or prove that it remains registered.

Public Members

uint64_t raw_id#

struct ovrtx_data_request_options_t

#include <ovrtx_data_provider.h>

Request options.

NULL is equivalent to zero hints, timeout, priority and pin_flags. For a non-NULL record, struct_size must be initialized to sizeof(ovrtx_data_request_options_t). Hints never change revision, cancellation or completion guarantees. WHOLE_OBJECT describes future access; it never permits payload loading during pinning. Whole-object fallback reads also carry it on each positioned chunk, including unknown-size resources. It is not an exclusive stream or cursor lease: concurrent consumers may issue independent reads against the same pin. The runtime retains this record through completion and submission/cancel return. Unknown hint bits are ignored; unknown pin_flags or both tracking flags are invalid. pin_flags must be zero for read, map and accessor requests.

Public Members

size_t struct_size#: Set to sizeof(ovrtx_data_request_options_t).

uint64_t hints#: Bitwise OVRTX_DATA_HINT_* values; unknown bits are ignored.

uint64_t timeout_ns#: Advisory budget in nanoseconds from submission; zero = unspecified, not a deadline guarantee.

int32_t priority#: Advisory scheduling priority; higher requests earlier service, zero = normal.

uint64_t pin_flags#

Pin-only OVRTX_DATA_PIN_* flags.

WATCH_CHANGES requests optional tracking; REQUIRE_CHANGE_TRACKING fails with UNSUPPORTED when tracking cannot be established for this resource.

struct ovrtx_data_resource_t

#include <ovrtx_data_provider.h>

Record and strings are callback-scoped.

The runtime copies strings before the completion returns. Only handle remains provider-owned until unpin().

UDIM manifest schema: Request OVRTX_DATA_STRUCTURED, schema “ovrtx.texture.udim”, schema_version=1; advertise CPU_ARRAYS and accept open_accessor_async(0, OVRTX_DATA_SIZE_UNKNOWN). In the supplied dictionary, /udim.tile_ids is a u32 CPU array of unique IDs in [1001,9999]. For each ID, /tiles/tile_<id>.asset is a scalar token naming a nonempty reference to pin relative to this manifest resource. All array leases must be released before close_accessor. The C++ helper ovrtx/providers/udim_manifest.hpp implements this accessor from a tile list without renderer-private dependencies. An empty tile list is valid. The built-in storage provider requires a supported tiling marker in the innermost basename for both loose and packaged resources; non-pattern STRUCTURED root requests return NOT_HANDLED; dependency requests return UNSUPPORTED without rerouting. A valid pattern with no matching tiles returns an empty manifest.
Package references: Package references use outer[member], including nested outer[a.usdz[b]]. Resolve the outer resource through the owning provider and retain its byte lease while member views are in use. ovrtx/providers/stored_package.hpp provides validated, zero-copy views of stored ZIP/ZIP64 members used by USDZ; compressed/encrypted members are unsupported. Views do not own storage. The built-in provider resolves relative dependencies inside the innermost package and rejects paths escaping it. Absolute paths and URI references resolve outside the package using the same built-in provider; they do not reroute to another provider. Custom providers define their own resolution.

Public Members

size_t struct_size#: Set to sizeof(ovrtx_data_resource_t).

ovrtx_data_resource_handle_t *handle#: Non-NULL provider-owned pin; release exactly once with unpin.

ovx_string_t identifier#: Nonempty canonical identity within namespace_key; length-delimited, no embedded NUL.

ovx_string_t revision#: Equal nonempty IDs mean equal data for this identifier; empty disables cross-pin revision identity.

ovx_string_t content_hash#: Optional “sha256:<64 lowercase hex digits>”; callback-scoped, no embedded NUL.

ovrtx_data_kind_t kind#: Must equal the requested pin kind.

uint64_t byte_size#: Exact byte length (zero is empty), or SIZE_UNKNOWN; STRUCTURED requires SIZE_UNKNOWN.

ovx_string_t schema#: Nonempty schema identifier for STRUCTURED; callback-scoped, no embedded NUL.

uint32_t schema_version#: Nonzero version of schema for STRUCTURED.

ovrtx_data_range_strategy_t range_strategy#

Available at pin completion, before payload I/O.

UNKNOWN if not known. NATIVE reads ranges directly. CACHED_READ_THROUGH caches fetched data for subsequent reads (not necessarily resident yet). MATERIALIZE_ONLY must fetch the whole object and makes no cross-read cache guarantee. UNSUPPORTED cannot serve subranges; a whole-object read/map may succeed. This is a cost hint, not content identity. STRUCTURED uses UNKNOWN.

bool change_tracking_enabled#

True only when requested tracking was established.

False is valid for optional or unrequested tracking. This describes the pin, not immutable content identity.

int64_t modified_time_ns#

Optional source modification time, in nanoseconds since the Unix epoch (UTC).

Valid only when has_modified_time is true; zero and negative values are valid. Fixed for the lifetime of this pin. Source precision may be coarser than nanoseconds. Equal timestamps do not imply equal content: this is neither a revision nor a hash, and does not by itself authorize timestamp-based cache validation. For package members, report the containing source’s timestamp; virtual/aggregate resources without a meaningful single source leave has_modified_time false.

bool has_modified_time#

True when modified_time_ns is available at pin completion.

Optional for every provider; false means unavailable and consumers must ignore modified_time_ns. This metadata owns no storage and remains valid in a copied pin result.

struct ovrtx_data_byte_view_t

#include <ovrtx_data_provider.h>

Callback-scoped map result; the bytes and opaque lease outlive the record until release_map().

Public Members

size_t struct_size#: Set to sizeof(ovrtx_data_byte_view_t).

const void *data#: Immutable CPU-readable bytes through release_map; NULL allowed only for an empty view.

uint64_t size#: Actual byte count, clipped to EOF; fits SIZE_MAX; this is a count, not a sentinel.

void *lease#: Non-NULL opaque release obligation, including for empty views.

struct ovrtx_data_provider_desc_t

#include <ovrtx_data_provider.h>

Registration metadata, separate from the provider implementation.

Set struct_size to sizeof(ovrtx_data_provider_desc_t) and abi_version to OVRTX_DATA_PROVIDER_ABI_VERSION.

Public Members

size_t struct_size#: Set to sizeof(ovrtx_data_provider_desc_t).

uint32_t abi_version#: Must equal OVRTX_DATA_PROVIDER_ABI_VERSION.

ovx_string_t namespace_key#

Stable, unique among live registrations, nonempty cache/authorization domain; no embedded NUL.

Copied at registration.

ovx_string_t uri_scheme#

ASCII URI scheme without ‘:’, matched case-insensitively; empty is catch-all.

Copied at registration.

int32_t priority#: Higher values run first within a route group; ties retain registration order.

uint64_t accessor_capabilities#

OVRTX_DATA_ACCESSOR_CAP_*; unknown bits are invalid; CPU/GPU arrays are independently optional.

Each advertised bit requires its acquire/release pair on every accessor; unadvertised pairs must be NULL. Zero also permits scalar-only accessors.

struct ovrtx_data_provider_vtable_t

#include <ovrtx_data_provider.h>

Immutable provider operations.

Multiple instances may share one table. Async operations pair done with caller-owned user_data; return user_data unchanged as done’s first argument, following the completion rules above. Set struct_size to sizeof(ovrtx_data_provider_vtable_t) and abi_version to OVRTX_DATA_PROVIDER_ABI_VERSION.

Public Members

size_t struct_size#: Set to sizeof(ovrtx_data_provider_vtable_t).

uint32_t abi_version#: Must equal OVRTX_DATA_PROVIDER_ABI_VERSION.

ovrtx_data_submit_t (*pin_async)(ovrtx_data_provider_context_t *context, ovrtx_data_request_t *request, ovrtx_data_resource_handle_t *base, ovx_string_t reference, ovrtx_data_kind_t kind, const ovrtx_data_request_options_t *options, ovrtx_data_pin_done_t done, void *user_data)#

Resolve a reference and establish an immutable resource identity without loading payload data.

Required callback. With base NULL, reference is an absolute root path or URI. With a base pin, resolve the dependency using that pin’s provider and immutable dependency context; an empty dependency reference is allowed by the API and is provider-defined. Pinning may fetch metadata but must not read, prefetch, or map payload bytes, even with WHOLE_OBJECT. A successful pin does not promise that subsequent payload I/O succeeds. Complete with OK and a non-NULL resource record containing a non-NULL handle, the requested kind, canonical identifier, and valid metadata. Set struct_size; use SIZE_UNKNOWN for unknown length (zero means empty). STRUCTURED requires a nonempty schema, nonzero schema_version, SIZE_UNKNOWN byte_size, and UNKNOWN range_strategy. Equal nonempty revisions for one identifier mean equal content; an empty revision provides no cross-pin deduplication identity. The record and strings need live only through done(); the caller copies them. The handle and immutable content/dependency identity remain provider-owned until unpin(). Successful completion transfers one pin obligation, even if cancellation races success.

With WATCH_CHANGES, attempt tracking but allow success with change_tracking_enabled=false. With REQUIRE_CHANGE_TRACKING, complete with UNSUPPORTED and NULL resource if tracking cannot be established; success must report change_tracking_enabled=true. With neither flag, no tracking is requested and change_tracking_enabled must be false. Both flags or unknown pin_flags are INVALID_ARGUMENT. Providers need not implement tracking, but must honor required-mode failure. Establish tracking as part of snapshot selection: changes after the selected snapshot must not fall into a gap before monitoring starts. Buffer such events until successful completion has been invoked, then publish them through ovrtx_data_notify_changed() outside provider operation callbacks and provider locks (schedule delivery if necessary). Track the logical resource, including relevant package/dependency changes, through unpin(). Notifications do not mutate the pinned snapshot. Independent pins retain independent interest; providers may share monitoring internally until the last interested pin ends. A failed/cancelled pin that transfers no handle must release any provisional monitoring. Consumers subscribe to the notification dispatcher before submitting interested pins and retain early events until the pin’s canonical identity is known. Notification delivery can race consumer-side processing of the completion even after done() has returned. Tracking support is per resource; advertising a provider-wide capability is not required.

On failure, pass NULL resource; no pin transfers. Use NOT_HANDLED to decline a root so the next route may run. Dependency failures never reroute. NOT_FOUND, UNSUPPORTED, ACCESS_DENIED, IO_ERROR, STALE, and CANCELLED report terminal operation failures as applicable; BUSY is not submission backpressure (return RETRY for that). The caller retains request inputs through completion and return of submission/cancel. For ACCEPTED, retain done/user_data until the one completion, including cancellation. Do not access user_data after invoking done. For RETRY or REJECTED, retain no operation arguments and invoke no completion. Submission must not block waiting for payload I/O.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param request:

Opaque caller-owned operation identity used by cancel(); do not dereference or free it.

Param base:

NULL for a root, otherwise a live handle from this provider retained through completion.

Param reference:

Borrowed length-delimited reference; need not be NUL-terminated.

Param kind:

Requested OVRTX_DATA_BYTES or OVRTX_DATA_STRUCTURED resource kind.

Param options:

Borrowed request options, including pin_flags; NULL means no tracking and default hints. Unknown hint bits are ignored; invalid pin_flags are rejected.

Param done:

Non-NULL completion function; invoke exactly once if submission returns ACCEPTED.

Param user_data:

Opaque caller-owned completion context; pass unchanged to done and do not use afterward.

Return:

OVRTX_DATA_ACCEPTED: exactly one completion is owed, possibly inline before this call returns.
OVRTX_DATA_RETRY: temporary submission backpressure; no completion or retained callback state. The caller may resubmit.
OVRTX_DATA_REJECTED: submission refused; no completion or retained callback state. This is not a routing decline.

void (*unpin)(ovrtx_data_provider_context_t *context, ovrtx_data_resource_handle_t *resource)#

Release the provider-owned state for one successful pin.

Required callback, called exactly once per successful pin after all dependent requests, accessors, and byte mappings have retired. Release pin-owned resources and this pin’s change-tracking interest; the handle becomes invalid. Queued monitoring work must not dereference that released pin state; independent monitoring tasks need their own ownership. Shared backing storage may remain alive for other pins or caches. This is synchronous, nonblocking teardown with no failure channel. NULL, foreign, or already-unpinned handles violate the calling contract; no recovery is guaranteed. Do not invalidate independent pins or invoke outstanding completions from this release.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param resource:

Live handle returned by a successful pin_async() completion; consumed by this call.

Return:

No value. The resource pin is released when the call returns.

ovrtx_data_submit_t (*read_async)(ovrtx_data_provider_context_t *context, ovrtx_data_request_t *request, ovrtx_data_resource_handle_t *resource, uint64_t offset, void *destination, uint64_t size, const ovrtx_data_request_options_t *options, ovrtx_data_read_done_t done, void *user_data)#

Read a positioned byte range from an immutable byte-resource pin into caller storage.

Required for providers serving BYTES; may be NULL for structured-only providers. Concurrent reads have independent offsets: do not interpret calls as an exclusive stream or shared cursor. WHOLE_OBJECT remains advisory on each positioned read. Read at most size bytes beginning at offset and complete with OK and bytes_read. A short successful read means EOF; offset at or beyond EOF returns zero. For a known byte_size, return exactly min(size, byte_size - offset), or zero beyond EOF; premature short success is treated as IO_ERROR. A zero-byte request permits a NULL destination. The finite range must fit the address space and must not overflow offset + size; SIZE_UNKNOWN has no read-to-EOF meaning for this callback. Write only within destination[0..size). Stop accessing it before completing; it remains caller-owned. Failure may leave partial writes, which the caller must not consume. Complete using done(user_data, status, bytes_read, error); bytes_read must not exceed size, and is consumed only for OK. Use an appropriate terminal status such as ACCESS_DENIED, IO_ERROR, STALE, UNSUPPORTED, or CANCELLED; NOT_HANDLED and BUSY are invalid payload completions. The caller retains request inputs through completion and return of submission/cancel. For ACCEPTED, retain done/user_data until the one completion, including cancellation. Do not access user_data after invoking done. For RETRY or REJECTED, retain no operation arguments and invoke no completion. Submission must not block waiting for payload I/O.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param request:

Opaque caller-owned operation identity used by cancel(); do not dereference or free it.

Param resource:

Live pin handle owned by this provider, retained by the caller through completion.

Param offset:

Absolute byte offset from the start of the pinned resource.

Param destination:

[out] Writable caller-owned buffer of size bytes; may be NULL only when size is zero.

Param size:

Maximum byte count, interpreted literally rather than as a read-to-EOF sentinel.

Param options:

Borrowed request options; NULL means defaults. Unknown hints are ignored; pin_flags must be zero.

Param done:

Non-NULL completion function; invoke exactly once if submission returns ACCEPTED.

Param user_data:

Opaque caller-owned completion context; pass unchanged to done and do not use afterward.

Return:

OVRTX_DATA_ACCEPTED: exactly one completion is owed, possibly inline before this call returns.
OVRTX_DATA_RETRY: temporary submission backpressure; no completion or retained callback state. The caller may resubmit.
OVRTX_DATA_REJECTED: submission refused; no completion or retained callback state. This is not a routing decline.

ovrtx_data_submit_t (*open_accessor_async)(ovrtx_data_provider_context_t *context, ovrtx_data_request_t *request, ovrtx_data_resource_handle_t *resource, uint64_t offset, uint64_t size, path_dictionary_instance_t *dictionary, const ovrtx_data_request_options_t *options, ovrtx_data_accessor_done_t done, void *user_data)#

Load or prepare an independent structured selection from a pinned resource.

Required together with close_accessor for providers serving STRUCTURED; both may be NULL for byte-only providers. This is the explicit payload I/O/preparation boundary. The provider/consumer schema defines offset and size: records, chunks, or another region, not necessarily bytes. They are forwarded unchanged, without offset+size arithmetic or byte bounds. Zero and SIZE_UNKNOWN have no generic special meaning. Validate selectors against the schema; report INVALID_ARGUMENT or OUT_OF_RANGE when invalid, and UNSUPPORTED when the requested selection/representation is unavailable. Other terminal failures include ACCESS_DENIED, IO_ERROR, STALE, and CANCELLED. NOT_HANDLED and BUSY are invalid payload completions. On OK, pass a non-NULL accessor with a live non-NULL context and immutable, ABI-valid vtable. All traversal/scalar callbacks are required, including attribute enumeration; array acquire/release pairs must match the registered capability bits. The caller copies the accessor record during done(); keep its context/vtable and all prepared data alive until successful close_accessor(). Errors pass NULL and transfer no accessor. Use the supplied dictionary for every returned path/token. The caller must keep the dictionary and its backing owner alive through the accessor’s lifetime. Preparation must finish before completion; later accessor calls cannot fetch data or migrate it. Multiple opens on one pin may overlap; each success has independent leases and close. Failure, cancellation, or closure of one selection must not invalidate another. The pin remains live until all selections, leases, and pending operations retire. The caller retains request inputs through completion and return of submission/cancel. For ACCEPTED, retain done/user_data until the one completion, including cancellation. Do not access user_data after invoking done. For RETRY or REJECTED, retain no operation arguments and invoke no completion. Submission must not block waiting for payload I/O.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param request:

Opaque caller-owned operation identity used by cancel(); do not dereference or free it.

Param resource:

Live pin handle owned by this provider, retained by the caller through completion.

Param offset:

Provider/schema-defined selection origin; forwarded unchanged.

Param size:

Provider/schema-defined selection extent; forwarded unchanged.

Param dictionary:

Non-NULL caller-owned dictionary, borrowed through preparation and accessor lifetime.

Param options:

Borrowed request options; NULL means defaults. Unknown hints are ignored; pin_flags must be zero.

Param done:

Non-NULL completion function; invoke exactly once if submission returns ACCEPTED.

Param user_data:

Opaque caller-owned completion context; pass unchanged to done and do not use afterward.

Return:

OVRTX_DATA_ACCEPTED: exactly one completion is owed, possibly inline before this call returns.
OVRTX_DATA_RETRY: temporary submission backpressure; no completion or retained callback state. The caller may resubmit.
OVRTX_DATA_REJECTED: submission refused; no completion or retained callback state. This is not a routing decline.

ovrtx_data_status_t (*close_accessor)(ovrtx_data_provider_context_t *context, ovrtx_data_accessor_t *accessor)#

Destroy one prepared accessor after all its array leases have been released.

Required together with open_accessor_async. Stop concurrent calls on this accessor before closing; thread-safe queries do not permit racing context destruction. On OK, destroy accessor-owned state and clear both fields of the supplied record. All copies of this accessor then become invalid; the caller must not call its vtable again. Do not destroy the caller’s dictionary or release the underlying pin here. Outstanding CPU/GPU leases require BUSY without destroying or clearing the accessor; release them and retry. Errors transfer no ownership. Independent accessors remain valid.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param accessor:

[inout] Non-NULL caller-held accessor record from this provider; cleared only on success.

Return:

OVRTX_DATA_OK if the accessor was closed and cleared.
OVRTX_DATA_BUSY while array leases remain; accessor ownership is unchanged.
OVRTX_DATA_INVALID_ARGUMENT for an invalid record argument.
OVRTX_DATA_INVALID_HANDLE for an unknown or already-cleared accessor; arbitrary dangling/foreign contexts cannot be safely validated.

void (*cancel)(ovrtx_data_provider_context_t *context, ovrtx_data_request_t *request)#

Request best-effort cancellation of an accepted asynchronous operation.

Required callback. This is a nonblocking notification, not a join or ownership release. The operation still owes exactly one completion. It may finish normally if cancellation loses the race, or complete with CANCELLED; never complete twice. The runtime may suppress a raced successful result and release its transferred pin/accessor/map. Cancellation may race completion; a provider must tolerate a request no longer present in its active-work bookkeeping. Do not dereference or free the opaque request token. Request inputs and destinations stay live through completion and return of this call; cancellation alone does not allow either side to release them early. Do not retain user_data or write a destination after completing the operation.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param request:

Opaque caller-owned operation identity used by cancel(); do not dereference or free it.

Return:

No value. Return does not imply the operation has completed or its resources are released.

ovrtx_data_submit_t (*map_async)(ovrtx_data_provider_context_t *context, ovrtx_data_request_t *request, ovrtx_data_resource_handle_t *resource, uint64_t offset, uint64_t size, const ovrtx_data_request_options_t *options, ovrtx_data_map_done_t done, void *user_data)#

Acquire a leased, immutable CPU byte view of a positioned range.

Optional callback paired with release_map; both must be NULL or both non-NULL. read_async remains required for byte providers. This payload operation may perform I/O/materialization, which is forbidden during pinning. Return an already CPU-readable view; no deferred fetch is permitted when the consumer dereferences its data. A finite size maps up to that many bytes; SIZE_UNKNOWN means through EOF. A short OK view means EOF. For known resource length, view.size must equal the requested range clipped to EOF; offset at or beyond EOF gives an empty view. A zero-size request also returns an empty view. Finite offset+size must not overflow; returned sizes must fit SIZE_MAX and must not overflow when added to offset. On OK, pass a non-NULL record with struct_size set, non-NULL lease even for an empty view, and non-NULL data when size is nonzero. The record is callback-scoped; its data remains provider-owned and immutable until release_map(context, resource, lease). Each successful map transfers one release obligation, including empty views and raced cancellation successes. Errors pass NULL and transfer no lease. An UNSUPPORTED completion permits read_async fallback; other errors are terminal. Applicable failures include ACCESS_DENIED, IO_ERROR, STALE, and CANCELLED; NOT_HANDLED and BUSY are invalid payload completions. Snapshot consumers try mapping before positioned reads. Forward-only sources can materialize once here, including for SIZE_UNKNOWN, but read_async must still honor independent offsets. The caller retains request inputs through completion and return of submission/cancel. For ACCEPTED, retain done/user_data until the one completion, including cancellation. Do not access user_data after invoking done. For RETRY or REJECTED, retain no operation arguments and invoke no completion. Submission must not block waiting for payload I/O.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param request:

Opaque caller-owned operation identity used by cancel(); do not dereference or free it.

Param resource:

Live pin handle owned by this provider, retained by the caller through completion.

Param offset:

Absolute byte offset from the start of the pinned resource.

Param size:

Maximum byte count, or OVRTX_DATA_SIZE_UNKNOWN to map through EOF.

Param options:

Borrowed request options; NULL means defaults. Unknown hints are ignored; pin_flags must be zero.

Param done:

Non-NULL completion function; invoke exactly once if submission returns ACCEPTED.

Param user_data:

Opaque caller-owned completion context; pass unchanged to done and do not use afterward.

Return:

OVRTX_DATA_ACCEPTED: exactly one completion is owed, possibly inline before this call returns.
OVRTX_DATA_RETRY: temporary submission backpressure; no completion or retained callback state. The caller may resubmit.
OVRTX_DATA_REJECTED: submission refused; no completion or retained callback state. This is not a routing decline.

void (*release_map)(ovrtx_data_provider_context_t *context, ovrtx_data_resource_handle_t *resource, void *lease)#

Release one byte-view lease returned by a successful map_async() completion.

Required exactly when map_async is provided. Call exactly once per successful map, including empty views, using the same provider context and resource pin. The caller must finish all reads before releasing. The borrowed data and lease become invalid when released; do not modify or free the data separately. Other maps retain their own leases even when backing storage is shared. This does not unpin the resource: release all maps before unpin(), and keep the pin live throughout this call. This synchronous, nonblocking release has no error channel. NULL, foreign, or already released leases violate the calling contract; callers must not rely on validation or idempotent release. No completion callback is invoked.

Param context:

Registered provider context, possibly NULL for a stateless provider. Borrowed, never freed here.

Param resource:

Live pin handle used by the matching map_async() operation; borrowed for this call.

Param lease:

Non-NULL, unreleased provider-owned lease from that map, consumed by this call.

Return:

No value. The map lease is released when the call returns.

struct ovrtx_data_provider_t

#include <ovrtx_data_provider.h>

Provider implementation instance.

Registration copies this pair; it borrows the immutable vtable and context until successful unregister or shutdown.

Public Members

const ovrtx_data_provider_vtable_t *vtable#: Non-NULL, immutable and live through removal/shutdown.

ovrtx_data_provider_context_t *context#: Application-owned state; may be NULL for stateless providers.

Stage Building #

ovrtx_enqueue_result_t ovrtx_open_usd_from_file( ovrtx_renderer_t *instance, ovx_string_t file_name )#

Enqueue an asynchronous operation to open a USD file as the root layer of the runtime stage.

This resets the current stage to empty and then loads the given file as the root sublayer. Only one root layer can be active at a time; call this again to replace it.

Note that errors occuring during loading (including a given USD file not being found) will be reported through the ovrtx_op_wait_result_t::error_op_ids list.

Parameters:

instance – Renderer instance
file_name – Path to the USD file to open

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully.
OVRTX_API_ERROR if the operation was not enqueued successfully.

ovrtx_enqueue_result_t ovrtx_open_usd_from_string( ovrtx_renderer_t *instance, ovx_string_t root_layer_content )#

Enqueue an asynchronous operation to open a USD stage from inline USDA content.

This resets the current stage to empty and then loads the given layer content as the root sublayer. Only one root layer can be active at a time; call this again to replace it.

Parameters:

instance – Renderer instance
root_layer_content – USDA content string for the root layer

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully.
OVRTX_API_ERROR if the operation was not enqueued successfully.

ovrtx_enqueue_result_t ovrtx_add_usd_reference_from_file( ovrtx_renderer_t *instance, ovx_string_t layer_file, ovx_string_t prefix_path, ovrtx_usd_handle_t *out_handle )#

Enqueue an asynchronous operation to add a USD file as a reference at the given prim path.

A new prim is created at prefix_path and the layer is added as a reference on that prim. The prefix path must be an absolute prim path (starting with ‘/’) and must not already exist.

out_handle is reserved when the add operation is enqueued. A non-zero handle does not mean the USD was loaded. In normal async mode, execution errors are reported through ovrtx_wait_op(). If OVRTX_CONFIG_SYNC_MODE is active, this function returns OVRTX_API_ERROR for those execution errors. Details can be queried with ovrtx_get_last_error().

Parameters:

instance – Renderer instance
layer_file – Path to the USD file to add as a reference
prefix_path – Absolute prim path where the reference will be created
out_handle – [out] Reserved handle for the added reference. It may be used to queue dependent stream-ordered operations, but does not by itself indicate the load succeeded.

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully.
OVRTX_API_ERROR if the operation was not enqueued successfully, or if an execution error occurs in sync mode.

ovrtx_enqueue_result_t ovrtx_add_usd_reference_from_string( ovrtx_renderer_t *instance, ovx_string_t layer_content, ovx_string_t prefix_path, ovrtx_usd_handle_t *out_handle )#

Enqueue an asynchronous operation to add inline USDA content as a reference at the given prim path.

A new prim is created at prefix_path and the layer content is added as a reference on that prim. The prefix path must be an absolute prim path (starting with ‘/’) and must not already exist.

out_handle is reserved when the add operation is enqueued. A non-zero handle does not mean the USD was loaded. In normal async mode, execution errors are reported through ovrtx_wait_op(). If OVRTX_CONFIG_SYNC_MODE is active, this function returns OVRTX_API_ERROR for those execution errors. Details can be queried with ovrtx_get_last_error().

Parameters:

instance – Renderer instance
layer_content – USDA content string for the reference layer
prefix_path – Absolute prim path where the reference will be created
out_handle – [out] Reserved handle for the added reference. It may be used to queue dependent stream-ordered operations, but does not by itself indicate the load succeeded.

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully.
OVRTX_API_ERROR if the operation was not enqueued successfully, or if an execution error occurs in sync mode.

ovrtx_enqueue_result_t ovrtx_remove_usd( ovrtx_renderer_t *instance, ovrtx_usd_handle_t add_usd_handle )#

Enqueue an asynchronous operation to remove a previously added USD reference from the runtime stage.

All prims added to the stage during the add operation will be removed.

Parameters:

instance – Renderer instance
add_usd_handle – Handle obtained from ovrtx_add_usd_reference_from_file() or ovrtx_add_usd_reference_from_string(). OVRTX_INVALID_USD_HANDLE is rejected immediately with OVRTX_API_ERROR, an invalid operation index, and details from ovrtx_get_last_error().

Returns:

OVRTX_API_SUCCESS if the usd file was removed successfully,
OVRTX_API_ERROR if the usd file removal failed.

ovrtx_enqueue_result_t ovrtx_clone_usd( ovrtx_renderer_t *instance, ovx_string_t source_path_in_usd, const ovx_string_t *target_paths, size_t num_target_paths )#

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 and the target paths must not already exist in it. Both are checked before anything is cloned, so a rejected batch creates nothing, and the per-operation error string names the missing source or the targets that already exist, e.g. ovrtx_clone_usd: target prim already exists at '/Tile3'. Relationship targets, path values, and USD attribute connections that point inside the source subtree are rebased to each target subtree. External paths are copied unchanged.

Parameters:

instance – Renderer instance
source_path_in_usd – Path to the source path to clone
target_paths – Array of target paths to clone to
num_target_paths – Number of target paths to clone to

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully,
OVRTX_API_ERROR if the operation was not enqueued successfully. A missing source or an already-existing target fails the operation itself; observe it through ovrtx_wait_op and ovrtx_get_last_op_error.

ovrtx_enqueue_result_t ovrtx_reset_stage(ovrtx_renderer_t *instance)#

Enqueue an asynchronous operation to reset the runtime stage representation to an empty stage.

A successful reset invalidates all previously returned ovrtx_usd_handle_t reference handles. Their values stored by the caller are not cleared and must not be reused. In asynchronous mode, OVRTX_API_SUCCESS only confirms enqueue; use ovrtx_wait_op to observe execution completion.

Parameters:

instance – Renderer instance

Returns:

OVRTX_API_SUCCESS if the stage was reset successfully,
OVRTX_API_ERROR if the stage reset failed.

ovrtx_enqueue_result_t ovrtx_update_stage_from_usd_time( ovrtx_renderer_t *instance, double usd_time )#

Enqueue an asynchronous operation to update the runtime stage representation from a specific USD time.

This operation will update all time-sampled attributes in the runtime stage representation to the provided USD time.

Parameters:

instance – Renderer instance
usd_time – USD time to update the stage to

Returns:

OVRTX_API_SUCCESS if the stage was updated from the USD time successfully,
OVRTX_API_ERROR if the stage update from USD time failed.

Attribute Writes #

ovrtx_enqueue_result_t ovrtx_write_attribute( ovrtx_renderer_t *instance, const ovrtx_binding_desc_or_handle_t *binding_handle_or_desc, const ovrtx_input_buffer_t *data_array, ovrtx_data_access_t data_access )#

Enqueue an asynchronous write operation from source data into the system’s stage representation.

This write operation is not fully executed when the call returns and inputs with asynchronous access must remain valid until the stream execution of this operation has completed.

Parameters:

instance – Renderer instance
binding_handle_or_desc – Handle or description of the binding to write to. This binding defines the layout of the input data, both in terms of attribute data encoding as well as the layout of prims. The binding can be generated in place or a persistent handle can be provided to manually manage the lifetime. A ovrtx_binding_desc_or_handle_t::binding_handle equal to OVRTX_INVALID_ATTRIBUTE_BINDING_HANDLE selects the inline ovrtx_binding_desc_or_handle_t::binding_desc and is valid.
data_array – Source data to write. Based on the input_access this source is used during the execution of the write operation, not during the enqueue. So it is important that the data source remains valid until the write operation has completed. This can be determined through stream synchronization events using ovrtx_signal_event() and ovrtx_wait_all_events(). When using asynchronous access of GPU input data, the cuda synchronization event must be signaled when the input data is ready to be accessed.
data_access – Determines the time of access to the input data. With asynchronous access, the lifetime must be managed by the user, while synchronous access incurs a synchronous copy during this call but prevents any access after this call returns.

Returns:

OVRTX_API_SUCCESS if the attribute was written successfully,
OVRTX_API_ERROR if the attribute write failed.

ovrtx_result_t ovrtx_map_attribute( ovrtx_renderer_t *instance, const ovrtx_binding_desc_or_handle_t *binding_handle_or_desc, ovrtx_mapping_desc_t mapping_desc, ovrtx_attribute_mapping_t *out_attribute_mapping )#

Immediately provedes internal memory according to the binding description to be written to by the user and later applied to the stage representation via ovrtx_unmap_attribute().

Parameters:

instance – Renderer instance
binding_handle_or_desc – Handle or description of the binding to use to determine the layout of the data to write. The binding can be generated in place or a persistent handle can be provided to manually manage the lifetime. A ovrtx_binding_desc_or_handle_t::binding_handle equal to OVRTX_INVALID_ATTRIBUTE_BINDING_HANDLE selects the inline ovrtx_binding_desc_or_handle_t::binding_desc and is valid.
mapping_desc – Description of the mapping to use
out_attribute_mapping – [out] Handle to the attribute mapping

Returns:

OVRTX_API_SUCCESS if the attribute was mapped successfully,
OVRTX_API_ERROR if the attribute mapping failed.

ovrtx_enqueue_result_t ovrtx_unmap_attribute( ovrtx_renderer_t *instance, ovrtx_map_handle_t map_handle, ovrtx_cuda_sync_t cuda_sync )#

Enqueue an asynchronous operation to take the data written by the user and do whatever necessary to apply it to the system’s stage representation.

Note that while the map operation is not asynchronous, the unmap operation is and it determines the logical order of applying the written data to the stage. Multiple mappings can be outstanding on the same stage data with the effects on the stage representation depending on the order of the unmap operations. The data written by the user must be ready when the unmap operation is called for CPU data and when the cuda synchronization event is signaled for GPU data.

Parameters:

instance – Renderer instance
map_handle – Handle to the attribute mapping to unmap. OVRTX_INVALID_MAP_HANDLE is rejected immediately with OVRTX_API_ERROR, an invalid operation index, and details from ovrtx_get_last_error().
cuda_sync – optional cuda synchronization to wait for before the mapped memory is accessed during the application of the written data to the stage representation.

Returns:

OVRTX_API_SUCCESS if the attribute was unmapped successfully,
OVRTX_API_ERROR if the attribute unmap failed.

ovrtx_enqueue_result_t ovrtx_create_attribute_binding( ovrtx_renderer_t *instance, const ovrtx_binding_desc_t *description, ovrtx_attribute_binding_handle_t *out_attribute_binding_handle )#

Enqueue an asynchronous operation to create a persistent attribute binding that binds a list of prims to a buffer layout.

This operation is an optimization to manage the lifetime of internal resources used to perform write or map operations using this binding.

Parameters:

instance – Renderer instance
description – Description of the binding to create
out_attribute_binding_handle – [out] Handle to the attribute binding

Returns:

OVRTX_API_SUCCESS if the attribute binding was created successfully,
OVRTX_API_ERROR if the attribute binding creation failed.

ovrtx_enqueue_result_t ovrtx_destroy_attribute_binding( ovrtx_renderer_t *instance, ovrtx_attribute_binding_handle_t binding_handle )#

Enqueue an asynchronous operation to destroy a persistent attribute binding.

Successful destruction invalidates the binding handle. Copies stored by the caller are not cleared and must not be reused. In asynchronous mode, OVRTX_API_SUCCESS only confirms enqueue; use ovrtx_wait_op to observe execution completion and ovrtx_get_last_op_error for errors.

Parameters:

instance – Renderer instance
binding_handle – Handle to the attribute binding to destroy. In asynchronous mode, OVRTX_INVALID_ATTRIBUTE_BINDING_HANDLE is enqueued and reported as an operation execution error by ovrtx_wait_op(); retrieve details with ovrtx_get_last_op_error(). In synchronous mode it returns OVRTX_API_ERROR with details from ovrtx_get_last_error(); the returned operation index remains valid.

Returns:

OVRTX_API_SUCCESS if the attribute binding was destroyed successfully,
OVRTX_API_ERROR if the attribute binding destruction failed.

Attribute Reads #

ovrtx_enqueue_result_t ovrtx_read_attribute( ovrtx_renderer_t *instance, const ovrtx_binding_desc_or_handle_t *binding_handle_or_desc, const ovrtx_read_dest_t *read_dest, ovrtx_read_handle_t *out_read_handle )#

Enqueue an asynchronous stream-ordered read of attribute values from the runtime stage.

The binding identifies which prims and which attribute to read. It reuses the same ovrtx_binding_desc_or_handle_t used for write operations:

ovrtx_binding_desc_t::prims_list_handle or ovrtx_binding_desc_t::prim_list identifies the prims (typically obtained from a prior ovrtx_query_prims() result).
ovrtx_binding_desc_t::attribute_name selects the attribute.
ovrtx_binding_desc_t::attribute_type serves as an optional type hint for reads; if zero-initialized the system returns the native type.
ovrtx_binding_desc_t::prim_mode determines behavior for missing prims (EXISTING_ONLY skips them, MUST_EXIST errors, CREATE_NEW is not supported).

Persistent binding handles (ovrtx_attribute_binding_handle_t) optimize repeated reads.

The read sees the stage as-if all prior stream-ordered operations have completed.

Parameters:

instance – Renderer instance
binding_handle_or_desc – Binding identifying prims and attribute to read. A ovrtx_binding_desc_or_handle_t::binding_handle equal to OVRTX_INVALID_ATTRIBUTE_BINDING_HANDLE selects the inline ovrtx_binding_desc_or_handle_t::binding_desc and is valid.
read_dest – Optional destination tensor for scalar reads (NULL = allocate internally). Must be NULL for array attributes. GPU tensors (kDLCUDA) are supported.
out_read_handle – [out] Handle to the read result for use with ovrtx_fetch_read_result()

Returns:

OVRTX_API_SUCCESS if the read was enqueued successfully,
OVRTX_API_ERROR if the read failed to enqueue.

ovrtx_result_t ovrtx_fetch_read_result( ovrtx_renderer_t *instance, ovrtx_read_handle_t read_handle, ovrtx_timeout_t timeout, ovrtx_read_output_t *out_read_output )#

Fetch the results of a prior ovrtx_read_attribute().

This operation is synchronous and will block until the read completes or the timeout is reached. Passing 0 as the timeout makes it a non-blocking poll.

For fixed-size attributes the result contains one tensor with leading shape [prim_count]. For array attributes it contains one tensor per prim with variable length. Result tensors use scalar lanes and type-aware trailing dimensions: a point3f[] array with 10 points is shape [10,3], and a matrix-typed 4x4 double attribute for N prims is shape [N,4,4]. An untyped 16-component tuple is [N,16]. When a destination tensor was provided to ovrtx_read_attribute(), buffer_count is 0.

All pointers in the output are valid until ovrtx_release_read_result() is called with the same read handle.

Parameters:

instance – Renderer instance
read_handle – Handle obtained from ovrtx_read_attribute(). OVRTX_INVALID_READ_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
timeout – Timeout for the operation
out_read_output – [out] Read data

Returns:

OVRTX_API_SUCCESS if the read result was fetched successfully,
OVRTX_API_ERROR if the fetch failed,
OVRTX_API_TIMEOUT if the result could not be obtained within the timeout.

ovrtx_result_t ovrtx_release_read_result( ovrtx_renderer_t *instance, ovrtx_read_handle_t read_handle, ovrtx_cuda_sync_t before_destroy_cuda_sync )#

Release resources associated with a prior ovrtx_read_attribute().

Safe to call whether or not ovrtx_fetch_read_result() was invoked first; use this to clean up after errors or when the fetched output is no longer needed. After this call all pointers in any previously returned ovrtx_read_output_t become invalid.

Parameters:

instance – Renderer instance
read_handle – Handle from ovrtx_read_attribute(). OVRTX_INVALID_READ_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
before_destroy_cuda_sync – Optional CUDA synchronization to wait for before freeing GPU resources (zero-initialized = no sync)

Returns:

OVRTX_API_SUCCESS if the result was released successfully,
OVRTX_API_ERROR if the release failed.

Stage Queries #

ovrtx_enqueue_result_t ovrtx_query_prims( ovrtx_renderer_t *instance, const ovrtx_query_desc_t *query_desc, ovrtx_query_handle_t *out_query_handle )#

Enqueue an asynchronous stream-ordered query of the runtime stage.

The query finds all prims matching the filter criteria in the ovrtx_query_desc_t and groups them by attribute schema (all prims in a group share the same attributes).

Parameters:

instance – Renderer instance
query_desc – Description of the query (filters, attribute reporting)
out_query_handle – [out] Handle for use with ovrtx_fetch_query_results()

Returns:

OVRTX_API_SUCCESS if the query was enqueued successfully,
OVRTX_API_ERROR if the query failed to enqueue.

ovrtx_result_t ovrtx_fetch_query_results( ovrtx_renderer_t *instance, ovrtx_query_handle_t query_handle, ovrtx_timeout_t timeout, ovrtx_query_result_t *out_result )#

Retrieve the results of a prior ovrtx_query_prims() operation.

This operation is synchronous and will block until the query completes or the timeout is reached. Passing 0 as the timeout makes it a non-blocking poll.

The result contains one ovrtx_query_prim_group_t per matching bucket. Each group has a ovrtx_query_prim_group_t::prim_list_handle that can be plugged directly into ovrtx_binding_desc_t::prims_list_handle for subsequent read or write operations.

All pointers in the result are valid until ovrtx_release_query_results() is called.

Parameters:

instance – Renderer instance
query_handle – Handle obtained from ovrtx_query_prims(). OVRTX_INVALID_QUERY_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
timeout – Timeout for the operation
out_result – [out] Query result containing prim groups

Returns:

OVRTX_API_SUCCESS if the results were retrieved successfully,
OVRTX_API_ERROR if the retrieval failed,
OVRTX_API_TIMEOUT if the result could not be obtained within the timeout.

ovrtx_result_t ovrtx_release_query_results( ovrtx_renderer_t *instance, ovrtx_query_handle_t query_handle )#

Release all resources associated with a prior ovrtx_query_prims() result.

This destroys all ovrtx_query_prim_group_t::prim_list_handle values in the result, frees attribute descriptor arrays, and releases internal resources.

After this call all pointers in the previously returned ovrtx_query_result_t become invalid.

Parameters:

instance – Renderer instance
query_handle – Handle obtained from ovrtx_query_prims(). OVRTX_INVALID_QUERY_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().

Returns:

OVRTX_API_SUCCESS if the results were released successfully,
OVRTX_API_ERROR if the release failed.

ovrtx_result_t ovrtx_get_path_dictionary( ovrtx_renderer_t *instance, path_dictionary_instance_t *out_path_dictionary )#

Obtain the renderer’s path dictionary for converting between handles and strings.

The path dictionary can be used to:

Convert ovrtx_query_prim_group_t::prim_list_handle to string paths via get_paths_from_path_list / get_strings_from_tokens.
Pre-resolve filter names to tokens via create_tokens_from_strings for repeated queries.
Build prim lists from strings via create_path_list_from_strings.

The returned instance is valid for the lifetime of the renderer.

Parameters:

instance – Renderer instance
out_path_dictionary – [out] The renderer’s path dictionary

Returns:

OVRTX_API_SUCCESS if the path dictionary was retrieved successfully,
OVRTX_API_ERROR if the retrieval failed.

Sensor Simulation #

ovrtx_enqueue_result_t ovrtx_step( ovrtx_renderer_t *instance, ovrtx_render_product_set_t render_products, double delta_time, ovrtx_step_result_handle_t *out_step_result_handle )#

Enqueue an asynchronous operation that will perform a sensor simulation step for all render products in the provided render product set.

The simulation step will be performed for the time span [last_step_time, last_step_time + delta_time], where last_step_time is determined by the history of previous calls to ovrtx_step() or ovrtx_reset(). When performing the sensor simulation, the result of prior stream ordered operations affecting the stage since the last call of ovrtx_step() will be considered the state of the stage at time (last_step_time + delta_time). After the simulation step was executed, last_step_time will be updated to (last_step_time + delta_time) for the next call to ovrtx_step().

Parameters:

instance – Renderer instance
render_products – Render products to simulate during this simulation step. Accumulated sensor rendering history for all render products not in the provided set will be discarded.
delta_time – Finite, non-negative time step within the supported simulation time range
out_step_result_handle – [out] Handle to the step result

Returns:

OVRTX_API_SUCCESS if the step was enqueued successfully,
OVRTX_API_ERROR if the step enqueue failed, or if render_products is malformed: a null array with a non-zero count, or any entry with a null ptr.

ovrtx_enqueue_result_t ovrtx_step_with_stage( ovrtx_renderer_t *instance, ovrtx_render_product_set_t render_products, double delta_time, ovstage_ordinal_t ordinal, ovrtx_step_result_handle_t *out_step_result_handle )#

Attached-mode counterpart of ovrtx_step().

Use this while the renderer is attached to an ovstage via ovrtx_attach_ovstage(): ordinal selects which committed state of the attached instance to render. Selecting a state that has not been committed yet (i.e. ordinal > the attached stage’s write floor) is rejected.

A default stage, an instance of “history_latest”, keeps history off. It holds the latest value of every cell and renders it for every committed ordinal. A history-capable stage is an instance of “history_selective”, created with that name in the implementation member of ovstage_instance_desc_t. History is on for the (prim, attribute) pairs selected with ovstage_enable_history(). When the renderer was created with OVRTX_CONFIG_ENABLE_HISTORY_PRESENTATION, such a stage renders the retained values of the selected pairs at an ordinal below its write floor. It returns to the live values afterwards. Without that key the renderer makes no history calls, and a step at an ordinal below the write floor of a history-capable stage fails with a reason that names the key. Unselected pairs render at their latest values. The step fails with the reason when the stage cannot present the ordinal.

Parameters:

instance – Renderer instance (must be attached to an ovstage).
render_products – Render products to simulate during this step.
delta_time – Finite, non-negative time step within the supported simulation time range.
ordinal – ovstage ordinal selecting the committed state to render.
out_step_result_handle – [out] Handle to the step result.

Returns:

OVRTX_API_SUCCESS if the step was enqueued successfully,
OVRTX_API_ERROR if the renderer is not attached, the ordinal is not committed, the enqueue failed, or render_products is malformed: a null array with a non-zero count, or any entry with a null ptr. The step operation itself fails, with the reason in ovrtx_get_last_op_error(), when a history-capable stage cannot present the requested ordinal.

ovrtx_enqueue_result_t ovrtx_enqueue_pick_query( ovrtx_renderer_t *instance, const ovrtx_pick_query_desc_t *desc )#

Enqueue an NDC-space pick query for the next ovrtx_step() that renders the given RenderProduct.

Results appear as the multi-tensor render variable OVRTX_RENDER_VAR_PICK_HIT, with named CPU tensors (primPath, objectType, geometryInstanceId, worldPositionM, worldNormal) and uint32 params (magic = OVRTX_PICK_HIT_MAGIC, version = OVRTX_PICK_HIT_VERSION, hitCount). The primPath column stores ovx_primpath_t ids and is populated independently of the query flags; resolve strings via ovrtx_get_path_dictionary() if needed. For a one-pixel-equivalent pick, OVRTX_PICK_FLAG_INCLUDE_TRACKED_INFO requests tracked metadata for the first hit. Without that flag, objectType, geometryInstanceId, worldPositionM, and worldNormal remain zero-filled. Multi-pixel picks leave those tracked metadata tensors zero-filled even when the flag is set. The query rectangle is specified in normalized RenderProduct coordinates using [0, 1] top-left-origin NDC. It uses the same convention as the old pixel API: right/bottom mark the edge just past the last included pixel. For example, pixel (x, y) on a width x height RenderProduct is [x / width, y / height, (x + 1) / width, (y + 1) / height]; the full RenderProduct is [0, 0, 1, 1]. Out-of-bounds values are rejected (boundary values may be clamped to the valid range to account for floating-point roundoff). If multiple queries are enqueued for the same RenderProduct before a step, the last one wins.

ovrtx_enqueue_result_t ovrtx_set_selection_outline_group( ovrtx_renderer_t *instance, const ovx_primpath_t *prim_path_ids, size_t path_count, const uint8_t *group_ids )#

Set per-prim selection outline group ids for renderer-side outline drawing.

Group ids are uint8 (0..255). Group 0 clears selection outline state for a prim; non-zero group ids select the style configured by ovrtx_set_selection_group_styles. prim_path_ids must be ovx_primpath_t values from this renderer’s own path dictionary, as returned by ovrtx_get_path_dictionary(), or from this renderer’s pick-hit results. Path ids from any other path dictionary are invalid. prim_path_ids and group_ids are parallel arrays of length path_count. Duplicate prim path ids are allowed; the last occurrence wins.

The operation is renderer-only and stream-ordered: it does not write scene attributes or mutate an attached ovstage, and it takes effect on the next ovrtx_step or ovrtx_step_with_stage that occurs after this op completes.

ovrtx_enqueue_result_t ovrtx_set_selection_outline_group_strings( ovrtx_renderer_t *instance, const ovx_string_t *prim_paths, size_t path_count, const uint8_t *group_ids )#

Set per-prim selection outline group ids using string prim paths.

This is a convenience wrapper for callers that do not already have renderer path ids. prim_paths and group_ids are parallel arrays of length path_count. Duplicate prim paths are allowed; the last occurrence wins.

Group ids, stream ordering, and renderer-only state semantics match ovrtx_set_selection_outline_group.

ovrtx_enqueue_result_t ovrtx_set_pickable( ovrtx_renderer_t *instance, const ovx_primpath_t *prim_path_ids, size_t path_count, const bool *pickable )#

Set per-prim pickability for renderer viewport picking.

prim_path_ids must be ovx_primpath_t values from this renderer’s own path dictionary, as returned by ovrtx_get_path_dictionary(), or from this renderer’s pick-hit results. Path ids from any other path dictionary are invalid. prim_path_ids and pickable are parallel arrays of length path_count. False excludes a prim from viewport picking where supported.

The operation is renderer-only and stream-ordered: it does not write scene attributes or mutate an attached ovstage, and it takes effect on the next ovrtx_step or ovrtx_step_with_stage that occurs after this op completes.

ovrtx_enqueue_result_t ovrtx_set_pickable_strings( ovrtx_renderer_t *instance, const ovx_string_t *prim_paths, size_t path_count, const bool *pickable )#

Set per-prim pickability using string prim paths.

This is a convenience wrapper for callers that do not already have renderer path ids. prim_paths and pickable are parallel arrays of length path_count.

Pickability, stream ordering, and renderer-only state semantics match ovrtx_set_pickable.

ovrtx_enqueue_result_t ovrtx_set_selection_group_styles( ovrtx_renderer_t *instance, const uint8_t *group_ids, const ovrtx_selection_group_style_t *styles, size_t count )#

Set per-group visual styling (outline color, fill color, and outline width) for one or more selection groups.

Group ids are uint8 (0..255) and match the per-prim group id passed to ovrtx_set_selection_outline_group. group_ids and styles are parallel arrays of length count.

The operation is stream-ordered: it takes effect on the next ovrtx_step that occurs after this op completes. If multiple writes target the same group id (in this call or across calls), the last writer wins.

Fill mode and the default outline width are configured via OVRTX_CONFIG_SELECTION_FILL_MODE and OVRTX_CONFIG_SELECTION_OUTLINE_WIDTH at renderer creation time. Per-group width override and omit-means-unchanged semantics are on ovrtx_selection_group_style_t::outline_width.

Outline dashing is not supported by the underlying renderer.

Parameters:

instance – Renderer instance
group_ids – Array of count group ids
styles – Array of count styles, parallel to group_ids
count – Number of (group_id, style) pairs

Returns:

OVRTX_API_SUCCESS if the operation was enqueued successfully,
OVRTX_API_ERROR if the operation failed to enqueue (null arguments, etc.).

ovrtx_enqueue_result_t ovrtx_reset( ovrtx_renderer_t *instance, double time )#

Enqueue an asynchronous operation to reset the accumulated sensor rendering history for all render products and start future sensor simulation steps at the provided time.

After the reset was executed, last_step_time will be updated to the provided time for the next call to ovrtx_step().

Parameters:

instance – Renderer instance
time – Finite, non-negative time within the supported simulation time range

Returns:

OVRTX_API_SUCCESS if the reset was enqueued successfully,
OVRTX_API_ERROR if the reset enqueue failed.

ovrtx_enqueue_result_t ovrtx_clear_history( ovrtx_renderer_t *instance, ovrtx_render_product_set_t render_products, uint32_t flags, const ovrtx_render_quality_t *quality, const ovrtx_tile_list_t *tiles )#

Enqueue an operation that discards the temporal rendering history of RenderProducts.

The clear applies to the first frame each RenderProduct produces after this operation, and stays pending until that frame is produced. For a split exposure it applies from the next exposure’s first split. Unlike ovrtx_reset, it keeps the sensor schedule, frame numbers and the simulation time. It also resets sensor-model state such as lidar and radar random sequences.

The cleared frame renders once: it does not wait for streaming and adds no initial quality frames, while omni:rtx:quality:minSpp still applies. Pass OVRTX_CLEAR_HISTORY_FLAG_FIRST_FRAME_QUALITY to render it like the RenderProduct’s first frame instead, or quality to choose the streaming wait and quality explicitly. Frame 0 and the first frame of a RenderProduct that started paused by omni:sensor:frameLimit keep their first-frame quality. A RenderProduct resuming after frames dropped by omni:sensor:frameLimit keeps its history and its camera’s previous pose, but instance transforms from before the pause are not necessarily retained. Clear it before the step that resumes it when prims moved during the pause, or to start that frame afresh; otherwise motion vectors and temporal reprojection of the moved prims can be wrong on that frame.

Clears that have not been applied yet merge: flags combine, a streaming wait and the highest quality win, and tile lists are unioned. Clearing a whole RenderProduct also clears its tiles.

With tiles, only those tiles of a single tiled RenderProduct are cleared, which drops DLSS and DLSS-RR history for them. They apply to the next completed exposure, on its final split, which DLSS runs on. That render drops them if it resets the RenderProduct’s whole history. Flags and quality apply to that exposure as for a whole clear, but its streaming wait and quality frames render every tile, and only the listed tiles are reset, after the wait. A wait the exposure needs anyway, or another exposure’s wait after a stage change, still resets its whole history. Tile indices outside the RenderProduct’s tiles are ignored with a warning. They supersede the deprecated omni:rtx:viewTile:renderHistoryReset attributes.

Parameters:

instance – Renderer instance
render_products – RenderProducts to clear. An empty set clears every RenderProduct of the next step.
flags – Bitwise OR of OVRTX_CLEAR_HISTORY_FLAG_* values, or 0.
quality – Optional quality override for the cleared frame, or NULL.
tiles – Optional tiles to clear, or NULL for whole RenderProducts. Requires exactly one RenderProduct.

Returns:

OVRTX_API_SUCCESS if the clear was enqueued successfully,
OVRTX_API_ERROR if the arguments are invalid. RenderProducts that are not stepped yet are not an error.

ovrtx_result_t ovrtx_fetch_results( ovrtx_renderer_t *instance, ovrtx_step_result_handle_t result_handle, ovrtx_timeout_t timeout, ovrtx_render_product_set_outputs_t *out_render_product_set_outputs )#

Query the results of a prior enqueued step operation.

This operation is synchronous and will block until the results are available or the timeout has passed. By passing 0 as the timeout this operation becomes a non-blocking poll operation that returns immediately if the results are not yet available. The complete production of render outputs is not determined by the completion of the asynchronous ovrtx_step() operation within the stream, so it is not possible to ensure this operations returns the results immediately by waiting for a stream synchronization event signaled after the ovrtx_step() operation. Conversely, once this function has returned the step’s result, with OVRTX_API_SUCCESS or with OVRTX_API_ERROR and status OVRTX_EVENT_FAILURE for a failed step, the step operation and every operation enqueued before it have completed and left the operation stream, as after ovrtx_wait_op() on the step’s op_index, so they no longer count as pending for ovrtx_attach_ovstage() and ovrtx_detach_ovstage(). This covers neither operations enqueued after the step nor the errors of the operations enqueued before it, which only ovrtx_wait_op() reports, and OVRTX_API_TIMEOUT implies nothing about the operation. The result of this operation contains information about what results each render product has produced. Each render product can have produced 0-n frames of output for m render vars. This operation doesn’t return the actual output data, but rather a handle to the output data which can then be mapped to retrieve the actual output data. All strings and pointers inside the result are valid until the result is destroyed by ovrtx_destroy_results().

Parameters:

instance – Renderer instance
result_handle – Handle to the step result to query. OVRTX_INVALID_STEP_RESULT_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
timeout – Timeout for the operation. Passing 0 will make the operation non-blocking and return immediately with the current status of the operation.
out_render_product_set_outputs – [out] Render product set outputs

Returns:

OVRTX_API_SUCCESS if the render product set outputs were retrieved successfully,
OVRTX_API_ERROR if the operation failed,
OVRTX_API_TIMEOUT if the result could not be obtained within the timeout.

ovrtx_result_t ovrtx_map_render_var_output( ovrtx_renderer_t *instance, ovrtx_render_var_output_handle_t output_handle, const ovrtx_map_output_description_t *map_output_desc, ovrtx_timeout_t timeout, ovrtx_render_var_output_t *out_render_var_output )#

Maps the rendered output into user accessible memory when the result are available.

This operation is synchronous and will block until the output is mapped or the timeout has passed. By passing 0 as the timeout this operation becomes a non-blocking poll operation that returns immediately if the output is not yet mapped. The complete production of render outputs is not determined by the completion of the asynchronous ovrtx_step() operation within the stream, so it is not possible to ensure this operations returns the results immediately by waiting for a stream synchronization event signaled after the ovrtx_step() operation. The result of this operation contains the actual rendered output memory, but it can contain cuda events that must be synchronized to before actually accessing the output memory. Calling map on a output_handle that is part of a step result after calling destroy_results on the step result will return an error.

Tensor layout contract for ovrtx_render_var_output_t::tensors:

A render variable carries num_tensors named tensor slots; each tensors[i].dl describes one slot.
Image-shaped tensors are channel-last with:
- ndim = 3
- shape = [height, width, channels]
- dtype.lanes = 1
Non-image tensors may use different ranks/layouts (for example, 1D buffers for point clouds).
Strides, when provided, are in elements (DLPack convention).
Params (ovrtx_render_var_output_t::params) are always CPU-resident DLPack tensors; their shape encodes scalar vs. array (e.g. {1} for scalar, {N} for array).
OVRTX_API_SUCCESS if the output was mapped successfully.
OVRTX_API_ERROR if the output mapping failed.
OVRTX_API_TIMEOUT if the result could not be obtained within the timeout.

Parameters:

instance – Renderer instance
output_handle – Handle to the output to map. OVRTX_INVALID_RENDER_VAR_OUTPUT_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
map_output_desc – Description of the output to map
timeout – Timeout for the operation. Passing 0 will make the operation non-blocking and return immediately with the current status of the operation.
out_render_var_output – [out] Mapped render variable output

Returns:

ovrtx_result_t ovrtx_unmap_render_var_output( ovrtx_renderer_t *instance, ovrtx_render_var_output_map_handle_t map_handle, ovrtx_cuda_sync_t before_destroy_cuda_sync )#

Unmaps the render variable output and frees resources associated with the prior ovrtx_map_render_var_output().

When this is called all access to the buffer provided by map_render_var_output must be done. This call determines the lifetime of the resources made accessible through the prior map_render_var_output call and this lifetime is independent of ovrtx_destroy_results(). It is safe to call unmap on a map_handle that was produced from a step result that has been destroyed by destroy_results.

Parameters:

instance – Renderer instance.
map_handle – Handle to the map to unmap. OVRTX_INVALID_RENDER_VAR_OUTPUT_MAP_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
before_destroy_cuda_sync – CUDA synchronization to wait for before the mapped memory is destroyed.

Returns:

OVRTX_API_SUCCESS if the output was unmapped successfully,
OVRTX_API_ERROR if the output unmapping failed.

ovrtx_result_t ovrtx_destroy_results( ovrtx_renderer_t *instance, ovrtx_step_result_handle_t result_handle )#

Releases all resources associated with the result of a sensor simulation step, with the exception of resources provided by calls to ovrtx_map_render_var_output().

Those are only released through ovrtx_unmap_render_var_output(). Destroying a result does not wait for its step operation; unless ovrtx_fetch_results() has returned the result, wait with ovrtx_wait_op() before ovrtx_attach_ovstage() or ovrtx_detach_ovstage().

Parameters:

instance – Renderer instance
result_handle – Handle to the step result to destroy. OVRTX_INVALID_STEP_RESULT_HANDLE is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().

Returns:

OVRTX_API_SUCCESS if the step result was destroyed successfully,
OVRTX_API_ERROR if the step result destruction failed.

Stream Operations #

ovrtx_result_t ovrtx_wait_op( ovrtx_renderer_t *instance, ovrtx_op_id_t op_id, ovrtx_timeout_t time_out, ovrtx_op_wait_result_t *out_wait_result )#

Wait for completion of all operations up to and including the specified operation id.

This operation is synchronous and will block until the operations are completed or the timeout has passed. Passing 0 as the timeout makes the operation a non-blocking poll. The out structure returns any errors observed since the last wait call and, on timeout, the lowest still-pending op id. For each op id in out_wait_result->error_op_ids, call ovrtx_get_last_op_error(op_id) to get the corresponding error string. Both out_wait_result->error_op_ids and strings returned by ovrtx_get_last_op_error() are transient thread-local data and are invalidated by the next call to ovrtx_wait_op() on the same thread. Consume/copy them before the next wait call.

Parameters:

instance – Renderer instance
op_id – Non-zero operation id to wait for. OVRTX_INVALID_OP_ID is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
time_out – Timeout for the operation
out_wait_result – [out] Wait result information (error op ids and lowest pending op id)

Returns:

OVRTX_API_SUCCESS if the operations were waited for successfully,
OVRTX_API_ERROR if the wait failed (e.g., invalid op id),
OVRTX_API_TIMEOUT if not all operations completed within the timeout.

ovrtx_result_t ovrtx_query_op_status( ovrtx_renderer_t *instance, ovrtx_op_id_t op_id, ovrtx_op_status_t *out_status )#

Query the status of a long-running operation.

This operation is synchronous and returns immediately with the current status of the specified operation. The returned status structure contains progress information and named resource counters. All strings and pointers in out_status are valid until ovrtx_release_op_status is called. This function must be paired with ovrtx_release_op_status.

Counter semantics:

name: Identifies the resource type (e.g., “shaders”, “textures”, “materials”)
current: Number of items processed so far
total: Total items to process, or 0 if the total is not yet known
The set of counters varies by operation type

Parameters:

instance – Renderer instance
op_id – Operation ID to query (from ovrtx_enqueue_result_t.op_index). OVRTX_INVALID_OP_ID is rejected with OVRTX_API_ERROR and details from ovrtx_get_last_error().
out_status – [out] Status information for the operation

Returns:

OVRTX_API_SUCCESS if status was retrieved successfully, OVRTX_API_ERROR if op_id is invalid or query failed

ovrtx_result_t ovrtx_release_op_status( ovrtx_renderer_t *instance, ovrtx_op_status_t *status )#

Release resources associated with a previously queried operation status.

After this call, all pointers in the status structure become invalid. This must be called for every successful ovrtx_query_op_status call.

Parameters:

instance – Renderer instance
status – Status structure to release (previously obtained from ovrtx_query_op_status)

Returns:

OVRTX_API_SUCCESS if released successfully, OVRTX_API_ERROR if release failed

Extensions #

ovrtx_result_t ovrtx_query_extension(

const char *name,

const void **vtable

)#

Query for an extension interface by name.

This query entry point is part of the public OVRTX C API. All extension names and vtable contracts are internal.

Parameters:

name – The name of the extension
vtable – [out] Vtable with function pointers for the extension

Returns:

OVRTX_API_SUCCESS if the extension was queried successfully,
OVRTX_API_ERROR if unavailable, or if this extension requires initialization.

Performance Profiling #

Collect simplified performance metrics, grouped RTX stages, and grouped memory data. The update functions document retained-batch ownership, measurement meanings, and recommended copy intervals for data collection and live visualization. Each sample includes an execution ID identifying its CPU thread or RTX GPU, or zero if unspecified. Injection variants accept no ID, attribute the calling thread, or preserve a supplied ID.

Retain a zero-initialized batch and reuse ovrtx_get_performance_data_update or its JSON counterpart. Each batch has independent progress. Per-metric samples follow collection order, not timestamp order. A sample timestamp can precede an earlier returned sample or a previous collection time. collection_time_ns is informational, not a bound on sample timestamps. Release the batch before renderer teardown. No timestamp input is needed. Copying does not recover overwritten history or guarantee a complete concurrent snapshot.

typedef struct ovrtx_profiling_config_t ovrtx_profiling_config_t#

Optional file-capture configuration.

Strings are copied before start returns.

typedef struct ovrtx_performance_value_t ovrtx_performance_value_t#

One sampled scalar value.

Time is in nanoseconds since profiling started.

typedef struct ovrtx_performance_metric_t ovrtx_performance_metric_t#

Public metric information and its newly collected values.

Aggregate statistics cover the active profiling session, not only this update. RTX stages are grouped under GPU/render-graph and viewport hierarchies. RTX Memory categories are Geometry, Textures, Volumes, Gaussians, SPG, Output Buffers and Internal, with Geometry subcategories where available. Memory values use MiB; GPU, host and virtual-reservation scopes are separate. Tracked host allocations are not process physical memory. Do not add inclusive parents to their children, or reservations to allocations. Grouped RTX durations can combine separate intervals and do not represent contiguous GPU occupancy.

typedef struct ovrtx_performance_data_update_t ovrtx_performance_data_update_t#

Owned update batch.

Initialize to zero before its first use. Strings and arrays remain valid until this container is updated or released. Do not copy ownership or use the same container concurrently. Release before destroying the last renderer; serialize reads with capture restart/teardown.

ovrtx_result_t ovrtx_start_profiling( const ovrtx_profiling_config_t *config )#

Start process-wide CPU/GPU/RTX profiling, with optional file capture.

Call after creating a renderer. config may be NULL; either string may be {NULL, 0}. NULL config or both string pointers NULL disables file output. Providing either string pointer enables file capture; an empty provided string selects the default directory/name. Strings are UTF-8 views. When saving, the output directory must already exist and be writable. An already active profiling session is not replaced. Serialize capture-control calls with renderer teardown; rendering may continue concurrently.

Parameters:

config – [in] Optional output path/name configuration. NULL starts live-only profiling.

Returns:

OVRTX_API_SUCCESS or OVRTX_API_ERROR; see ovrtx_get_last_error().

ovrtx_result_t ovrtx_stop_profiling(void)#

Stop profiling and flush and close any file capture.

May block on output work. Call before destroying the last renderer. Stopping when no capture is active succeeds.

Returns:: OVRTX_API_SUCCESS or OVRTX_API_ERROR; see ovrtx_get_last_error().

void ovrtx_add_performance_metric_value( uint64_t metric_uid, double value )#

Inject a scalar value without execution attribution.

The sample’s execution ID is zero. This does not create a metric or start profiling.

Parameters:

metric_uid – [in] OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_FPS or OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_RENDER_THREAD_TIME.
value – [in] Frames per second for FPS, or elapsed milliseconds for Render Thread.

void ovrtx_add_performance_metric_value_with_thread_execution_id( uint64_t metric_uid, double value )#

Inject a scalar value attributed to the calling CPU thread.

This does not create a metric or start profiling.

Parameters:

metric_uid – [in] OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_FPS or OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_RENDER_THREAD_TIME.
value – [in] Frames per second for FPS, or elapsed milliseconds for Render Thread.

void ovrtx_add_performance_metric_value_with_custom_execution_id( uint64_t metric_uid, double value, uint32_t execution_id )#

Inject a scalar value with an explicitly supplied execution identity.

The sample carries the supplied identity.

Parameters:

metric_uid – [in] OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_FPS or OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_RENDER_THREAD_TIME.
value – [in] Frames per second for FPS, or elapsed milliseconds for Render Thread.
execution_id – [in] Caller-defined identity. Zero means unspecified.

ovrtx_result_t ovrtx_get_performance_data_update( ovrtx_performance_data_update_t *out_data )#

Collect one batch of public metrics without interrupting rendering.

Initialize the output container to zero, then retain and reuse it between calls. The first call returns retained history; later calls return newly available samples. Independent containers have independent progress, reset automatically after profiling restarts. Within each metric, samples follow collection order across batches, not timestamp order. Sample timestamps can precede an earlier returned sample or a previous collection time. collection_time_ns is informational, not a cursor or a bound on sample timestamps. Structured and JSON getters share progress. Prefer copying every 500 ms-1 s (1-2 Hz), or 200-250 ms (4-5 Hz) for live UI. At no more than 120 samples/s per metric, a 4 s interval accumulates 480 samples and fits retained history if bursts, scheduling and copying stay within its margin. Longer intervals make larger, slower batches; cost grows with metric/sample count. Copying does not change sampling cadence, recover overwritten history or guarantee a complete snapshot during concurrent updates. The output container can be reused. Copy metric and sample data before updating or releasing it.

Parameters:

out_data – [inout] Non-null, initially zeroed container. Its previous borrowed views are invalidated.

Returns:

OVRTX_API_SUCCESS or OVRTX_API_ERROR; see ovrtx_get_last_error().

ovrtx_result_t ovrtx_get_performance_data_update_as_json( ovrtx_performance_data_update_t *out_data )#

Collect the same public update as UTF-8 JSON in out_data->json.

JSON contains collection_time_ns and a metrics array. Each metric has uid, parent_uid, name, units, info, group_name and values (timestamp_ns, value, parent_uid, execution_id). Ownership, retained progress and polling guidance are identical to ovrtx_get_performance_data_update.

Parameters:

out_data – [inout] Non-null, initially zeroed or previously returned container; json is a borrowed view.

Returns:

OVRTX_API_SUCCESS or OVRTX_API_ERROR; see ovrtx_get_last_error().

ovrtx_result_t ovrtx_release_performance_data_update( ovrtx_performance_data_update_t *data )#

Release a batch and zero its container, invalidating every borrowed string and sample span.

Release before renderer teardown. Releasing an empty initialized container succeeds.

Parameters:

data – [inout] Non-null container initialized to zero or returned by an update function.

Returns:

OVRTX_API_SUCCESS, or OVRTX_API_ERROR for an invalid argument; see ovrtx_get_last_error().

OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_FPS#: Predefined metric UID for default-render-target frames per second.

OVRTX_PERFORMANCE_PREDEFINED_METRIC_UID_RENDER_THREAD_TIME#: Predefined metric UID for render-thread work time in milliseconds.

struct ovrtx_profiling_config_t

#include <ovrtx.h>

Optional file-capture configuration.

Strings are copied before start returns.

Public Members

ovx_string_t output_path#

Existing writable directory.

{NULL, 0} uses the persistent user directory.

ovx_string_t file_name#

Basename without an extension.

{NULL, 0} generates a timestamp-based name. Existing recordings are not overwritten; collisions add a timestamp suffix.

struct ovrtx_performance_value_t

#include <ovrtx.h>

One sampled scalar value.

Time is in nanoseconds since profiling started.

Public Members

uint64_t timestamp_ns#: Sample timestamp in nanoseconds since profiling started; duration samples use their start time.

double value#: Sampled value in the corresponding metric’s units.

uint64_t parent_uid#: Parent metric for this sample’s invocation; zero means root or unspecified.

uint32_t execution_id#: CPU-thread or RTX-GPU identity; zero means unspecified.

struct ovrtx_performance_metric_t

#include <ovrtx.h>

Public metric information and its newly collected values.

Aggregate statistics cover the active profiling session, not only this update. RTX stages are grouped under GPU/render-graph and viewport hierarchies. RTX Memory categories are Geometry, Textures, Volumes, Gaussians, SPG, Output Buffers and Internal, with Geometry subcategories where available. Memory values use MiB; GPU, host and virtual-reservation scopes are separate. Tracked host allocations are not process physical memory. Do not add inclusive parents to their children, or reservations to allocations. Grouped RTX durations can combine separate intervals and do not represent contiguous GPU occupancy.

Public Members

uint64_t uid#: Metric identity within the current profiling session; do not reuse across restarts.

uint64_t parent_uid#: Default hierarchy parent, or zero for a root; each value carries its invocation parent.

ovx_string_t name#: Borrowed UTF-8 display name.

ovx_string_t units#: Borrowed UTF-8 unit label; duration values normally use milliseconds.

ovx_string_t info#: Borrowed UTF-8 description of the measurement.

ovx_string_t group_name#: Borrowed UTF-8 category name.

const ovrtx_performance_value_t *values#: Borrowed sample span; read only value_count entries.

size_t value_count#: Number of samples in values; may be zero when this metric has no new sample.

double average#: Session-wide running average, in units; best-effort during concurrent injection.

double minimum#: Session-wide running minimum, in units; best-effort during concurrent injection.

double maximum#: Session-wide running maximum, in units; best-effort during concurrent injection.

struct ovrtx_performance_data_update_t

#include <ovrtx.h>

Owned update batch.

Initialize to zero before its first use. Strings and arrays remain valid until this container is updated or released. Do not copy ownership or use the same container concurrently. Release before destroying the last renderer; serialize reads with capture restart/teardown.

Public Members

uint64_t collection_time_ns#: Collection time in nanoseconds since profiling started; not a sample-time boundary.

const ovrtx_performance_metric_t *metrics#: Borrowed metric array owned by this batch; read only metric_count entries.

size_t metric_count#: Number of entries in metrics.

ovx_string_t json#: Borrowed UTF-8 JSON from the JSON getter; empty after the structured getter.

void *handle#

Opaque owner managed by the update/release functions.

Do not copy, replace or free it directly.

Error Handling #

ovx_string_t ovrtx_get_last_error()#

Returns the error string for the latest API call on the calling thread.

The string is valid until the next API call on the same thread.

ovx_string_t ovrtx_get_last_op_error(ovrtx_op_id_t op_id)#

Returns the error string for the provided operation id from the last call to ovrtx_wait_op on the calling thread.

The string is valid until the next call to ovrtx_wait_op on the same thread. This is a lookup-only identifier: OVRTX_INVALID_OP_ID and any operation id not present in the last wait result return an empty string rather than an API error.

Parameters:

op_id – Operation id to get the error string for

Configuration Helpers #

static inline ovrtx_config_entry_t ovrtx_config_entry_bool( ovrtx_config_bool_t key, bool value )#

Build a config entry for a boolean setting.

Parameters:

key – Config key (e.g. OVRTX_CONFIG_SYNC_MODE). Must be from ovrtx_config_bool_t.
value – Stored by value in the entry.

static inline ovrtx_config_entry_t ovrtx_config_entry_string( ovrtx_config_string_t key, ovx_string_t value )#

Build a config entry for a string setting.

Parameters:

key – Config key (e.g. OVRTX_CONFIG_LOG_FILE_PATH). Must be from ovrtx_config_string_t.
value – String value. value.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_int( ovrtx_config_int64_t key, int64_t value )#

Build a config entry for an int64 setting.

Parameters:

key – Config key (e.g. OVRTX_CONFIG_SELECTION_OUTLINE_WIDTH). Must be from ovrtx_config_int64_t.
value – Stored by value in the entry.

static inline ovrtx_config_entry_t ovrtx_config_entry_binary_package_root_path( ovx_string_t path )#

Configure the OVRTX “binary package root” directory.

This is used by the loader to locate the renderer shared library and required runtime resources. If not provided, the loader chooses a default based on the loader’s location.

Parameters:

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

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_spectral_rendering( bool enabled )#

Enable Spectral PathTracing before creating the first renderer in this process.

Also enable spectral rendering on its PathTracing RenderProducts. The choice cannot change during the process lifetime, including after destroying all renderer instances.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_crash_reporter( bool enabled )#

Enable or disable the OVRTX crash reporter.

Enabled by default.

Disable it when the host application owns crash handling: OVRTX then installs no crash handlers and does not upload crash dumps. The first renderer created in this process decides; the choice cannot change during the process lifetime. See OVRTX_CONFIG_ENABLE_CRASH_REPORTER.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_debug_validation( bool enabled )#

Enable or disable graphics API debug validation when creating shared graphics devices.

Omit this entry to preserve GPU Foundation’s default. Additional renderers reuse the existing validation mode; conflicting requests warn and continue with that mode. See OVRTX_CONFIG_ENABLE_DEBUG_VALIDATION for lifetime rules.

static inline ovrtx_config_entry_t ovrtx_config_entry_sync_mode( bool sync_mode )#

Configure synchronous stream execution.

When enabled, operations that are normally enqueued for stream-ordered execution will block the calling thread until the operation has completed. Any errors will be returned immediately.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_profiling( bool enable_profiling )#

Configure internal profiling.

When enabled, the renderer collects additional profiling data. This can add overhead.

static inline ovrtx_config_entry_t ovrtx_config_entry_read_gpu_transforms( bool read_gpu_transforms )#

Configure transform propagation mode.

When enabled, the renderer uses GPU world transform propagation during rendering.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_history_presentation( bool enable_history_presentation )#

Enable the history presentation of an attached history-capable ovstage.

When enabled, ovrtx_step_with_stage() at an ordinal below the write floor renders the retained values of the renderable history-enabled pairs and restores the live values afterwards. When disabled (the default), the renderer makes no history calls, and such a step fails with a reason that names OVRTX_CONFIG_ENABLE_HISTORY_PRESENTATION. Pass to ovrtx_create_renderer().

static inline ovrtx_config_entry_t ovrtx_config_entry_keep_system_alive( bool keep_system_alive )#

Keep the renderer system alive after all instances are destroyed.

When enabled (default), the shared RendererWrapperSystem (common GPU resources) is not destroyed when the last renderer instance is destroyed, so a subsequent create_renderer reuses it. When disabled, the system is destroyed when the last renderer instance is destroyed.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_minimal( bool enable_minimal )#

Enable or disable Minimal rendering at startup.

See OVRTX_CONFIG_ENABLE_MINIMAL.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_realtimepathtracing( bool enable_realtimepathtracing )#

Enable or disable real-time path tracing at startup.

See OVRTX_CONFIG_ENABLE_REALTIMEPATHTRACING.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_pathtracing( bool enable_pathtracing )#

Enable or disable path tracing at startup.

See OVRTX_CONFIG_ENABLE_PATHTRACING.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_mdl_displacement( bool enable_mdl_displacement )#: Enable or disable MDL material displacement at renderer creation.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_geometry_streaming( bool enable_geometry_streaming )#

Build a config entry for the geometry streaming opt-in flag.

Geometry streaming is disabled when this entry is not specified.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_geometry_streaming_lod( bool enable_geometry_streaming_lod )#: Build a config entry for the geometry streaming LOD opt-in flag.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_spg( bool enable_spg )#: Build a config entry for enabling/disabling RTX Sensor Processing Graphs (enabled by default).

static inline ovrtx_config_entry_t ovrtx_config_entry_suppress_deprecation_warnings( bool suppress_deprecation_warnings )#

Suppress runtime warnings emitted when deprecated OVRTX APIs are called.

This does not affect compile-time deprecation diagnostics from OVRTX_DEPRECATED. When omitted, runtime deprecation warnings remain enabled.

static inline ovrtx_config_entry_t ovrtx_config_entry_motion_bvh( ovrtx_motion_bvh_t mode )#

Configure motion BVH (ray-traced motion) behavior for sensor pipelines.

Parameters:

mode – One of ovrtx_motion_bvh_t. Must be set before the first ovrtx_create_renderer call; changing the value requires recreating the renderer. When not provided, the renderer uses the process’s own motion BVH settings, which default to OVRTX_MOTION_BVH_DISABLE; it does not inherit a mode set by an earlier renderer in the process.

static inline ovrtx_config_entry_t ovrtx_config_entry_texture_streaming_mode( ovrtx_texture_streaming_mode_t mode )#

Configure texture streaming behavior.

Parameters:

mode – One of ovrtx_texture_streaming_mode_t. When not provided, texture streaming defaults to OVRTX_TEXTURE_STREAMING_ASYNCHRONOUS. Synchronous mode processes texture feedback synchronously; it does not make all texture loading operations synchronous. This setting is process-global and applies to all active renderer instances.

static inline ovrtx_config_entry_t ovrtx_config_entry_aftermath_mode( ovrtx_aftermath_mode_t mode )#

Configure NVIDIA Nsight Aftermath diagnostics.

Parameters:

mode – One of ovrtx_aftermath_mode_t. OVRTX_AFTERMATH_DISABLE skips Aftermath initialization, OVRTX_AFTERMATH_ENABLE selects explicit diagnostics initialization, and omitted or OVRTX_AFTERMATH_AUTO selects the initialization mode automatically. This is process-global and must be selected before the first renderer is created; subsequent renderer configurations must use the same mode while the renderer system is alive.

static inline ovrtx_config_entry_t ovrtx_config_entry_log_file_path( ovx_string_t path )#

Configure log file path for carb logging.

This setting should be passed to ovrtx_initialize(). The log file is created when the first renderer is created via ovrtx_create_renderer().

The path may contain the ${start_timestamp} token which will be replaced with the startup timestamp in YYYYMMDD_HHMMSS format (e.g., “myapp_${start_timestamp}.log”).

If not specified, defaults to: <app_directory>/ovrtx_${start_timestamp}.log

Parameters:

path – Log file path. path.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_log_level( ovx_string_t level )#

Configure carb logging level (e.g.

“verbose”, “info”, “warn”, “error”, “fatal”).

This setting should be passed to ovrtx_initialize(). The log level is applied when the first renderer is created via ovrtx_create_renderer().

Parameters:

level – Log level string. The memory behind level.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_active_cuda_gpus( ovx_string_t cuda_gpus )#

Configure active CUDA GPUs for rendering.

Specifies which GPUs to use for rendering by their CUDA device indices. The indices are translated to Vulkan device indices internally by GPU Foundation. This is useful when CUDA and Vulkan enumerate devices in different orders.

Parameters:

cuda_gpus – Comma-separated list of CUDA device indices (e.g., “0,1,2”). cuda_gpus.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_sensors_allowed_deprecation_base( ovx_string_t base )#

Allow all soft-deprecated sensor versions while pinned to a specific framework release.

Soft-deprecated sensor versions are rejected by default. This opt-in allows them only while the value matches the current framework version, so it must be revisited on every framework upgrade (upgrading stops soft-deprecated sensors from loading, forcing migration).

Parameters:

base – “<major>.<minor>.<patch>” (e.g. “0.4.0”). Any non-matching value (or unset) allows none.

static inline ovrtx_config_entry_t ovrtx_config_entry_datastore_cache( ovx_string_t cache )#

Configure the datastore cache used by UJITSO.

Supported protocol-prefixed values are:

grpcdns://host:port for the Derived Data Cache with TLS
grpcdns_notls://host:port for the Derived Data Cache without TLS
local://path for a local datastore

Omitting this entry preserves the existing cache defaults and environment-variable behavior.

Parameters:

cache – Cache configuration string. cache.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_cache_root_path( ovx_string_t path )#

Set the process-wide ${omni_cache} root for OVRTX caches to a nonempty path that resolves to an absolute path.

Takes precedence over both the platform default and an ovrtx.portable marker beside the executable or OVRTX binaries. Supply this setting to the first ovrtx_initialize() call or when creating the first renderer in the process with ovrtx_create_renderer(). The chosen root applies to all renderers. If supplied again, use the same path string. Changing the root within the same process is unsupported, even after destroying all renderers and calling ovrtx_shutdown(). Start a new process to use a different root.

Parameters:

path – Nonempty root path. path.ptr must remain valid until the API call that consumes the config returns.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_global_cache_root( bool enabled )#

Select the platform’s global cache root for ${omni_cache} and OVRTX’s writable caches.

On Linux, this uses XDG_CACHE_HOME/ovrtx/<version> when XDG_CACHE_HOME is absolute, otherwise HOME/.cache/ovrtx/<version>. On Windows, this uses the LOCALAPPDATA%/ovrtx/<version>. <version> is the compiled OVRTX major.minor.patch version; VERSION.md is not consulted. True is the default when omitted. False in either ovrtx_initialize() or ovrtx_create_renderer() disables the platform root when no true value is supplied in the other call. Without a root request, existing cache-path settings and a nonempty ${omni_cache} token are preserved; an empty token defaults to the application directory. An ovrtx.portable file beside the executable or OVRTX binaries sets ${omni_cache} to the application directory even when this entry is true, while retaining the existing local shader-cache subfolders. A valid path supplied with ovrtx_config_entry_cache_root_path() takes precedence over both. Configure this option in the first ovrtx_initialize() call or when creating the first renderer in the process. Changing the cache root within the same process is unsupported, even after destroying all renderers and calling ovrtx_shutdown(). Start a new process to use a different root.

static inline ovrtx_config_entry_t ovrtx_config_entry_selection_outline_enabled( bool enabled )#

Enable the selection outline postprocessing pass.

When enabled, prims marked with a non-zero selection group (via ovrtx_set_selection_outline_group) will have a visible outline drawn in the rendered image. Selection outlines are enabled by default. Pass false to disable them. When disabled, selection groups are tracked but no outline is rendered.

static inline ovrtx_config_entry_t ovrtx_config_entry_selection_outline_width( int width )#

Configure the default selection outline width in pixels.

Applies to every selection group that has no per-group width of its own.

Init-time only; changing this default requires renderer recreation. Valid range is 0..15 (the underlying RTX outline pipeline cap), where 0 draws no outline ring. Out-of-range values are clamped by the renderer. Per-group overrides are applied at runtime via ovrtx_set_selection_group_styles.

static inline ovrtx_config_entry_t ovrtx_config_entry_selection_fill_mode( ovrtx_selection_fill_mode_t mode )#

Configure the selection-outline fill (interior) mode.

Init-time only; changing requires renderer recreation.

Attribute Helpers #

static inline ovrtx_enqueue_result_t ovrtx_set_xform_mat( ovrtx_renderer_t *instance, const ovx_string_t *paths, size_t path_count, const ovrtx_xform_matrix44d_t *transforms )#

static inline ovrtx_enqueue_result_t ovrtx_set_xform_pos_rot3x3( ovrtx_renderer_t *instance, const ovx_string_t *paths, size_t path_count, const ovrtx_xform_pos3d_rot3x3f_t *transforms )#

static inline ovrtx_enqueue_result_t ovrtx_set_xform_pos_rot_scale( ovrtx_renderer_t *instance, const ovx_string_t *paths, size_t path_count, const ovrtx_xform_pos3d_rot4f_scale3f_t *transforms )#

static inline ovrtx_enqueue_result_t ovrtx_set_reset_xform_stack( ovrtx_renderer_t *instance, const ovx_string_t *paths, size_t path_count, const bool *values )#

static inline ovrtx_enqueue_result_t ovrtx_set_path_attributes( ovrtx_renderer_t *instance, const ovx_string_t *prim_paths, size_t path_count, ovx_string_t attribute_name, const ovx_string_t *path_values )#

Write path string values as relationship arrays to an attribute on the specified prims.

Each prim receives a single-element array containing its path value, since USD relationship attributes are always arrays.

Types #

Core Types #

typedef struct ovrtx_renderer_t ovrtx_renderer_t#

typedef struct ovrtx_build_info_t ovrtx_build_info_t#

Immutable build identity for the loaded OVRTX loader binary that exports this API.

Future versions may append fields; callers should use struct_size before reading appended fields. String views remain valid while the OVRTX loader library remains loaded, and their lengths exclude the null terminator. Use ovrtx_get_version() for the semantic version.

struct ovrtx_build_info_t

#include <ovrtx_types.h>

Immutable build identity for the loaded OVRTX loader binary that exports this API.

Future versions may append fields; callers should use struct_size before reading appended fields. String views remain valid while the OVRTX loader library remains loaded, and their lengths exclude the null terminator. Use ovrtx_get_version() for the semantic version.

Public Members

uint32_t struct_size#

uint32_t build_number#

ovx_string_t build_string#

ovx_string_t git_branch#

ovx_string_t git_hash#

ovx_string_t build_location#

Handle Types #

Renderer resources, operations, provider registrations, and accessor array leases use distinct structs containing uint64_t raw_id. Keep that type through function arguments, arrays, callbacks, and result fields. Use .raw_id for numeric diagnostics, C comparisons, or serialization; C++ supports same-kind comparison and hashing.

C++ value initialization (Handle{}) produces the invalid value for renderer handles and provider IDs. Use the matching typed invalid constant for resets and comparisons, such as query == OVRTX_INVALID_QUERY_HANDLE in C++. These sentinels reserve zero for invalid renderer handles and provider IDs; OVRTX_INVALID_HANDLE is the raw numeric zero sentinel, not a typed handle. An array lease is different: zero is a valid accessor-local ID and must be released after a successful acquisition. Copying any identity does not retain its resource, prove liveness, or identify its renderer or accessor.

For Python handle types and usage, see Handle Types.

typedef struct ovrtx_usd_handle_t ovrtx_usd_handle_t#: Handle representing a USD stage.

typedef struct ovrtx_event_handle_t ovrtx_event_handle_t#: Handle representing an event.

typedef struct ovrtx_attribute_binding_handle_t ovrtx_attribute_binding_handle_t#: Handle representing a persistent attribute binding.

typedef struct ovrtx_map_handle_t ovrtx_map_handle_t#: Handle representing a resource mapping that can be used to unmap it.

typedef struct ovrtx_step_result_handle_t ovrtx_step_result_handle_t#: Handle to the result of a ovrtx_step() operation.

typedef struct ovrtx_render_var_output_handle_t ovrtx_render_var_output_handle_t#: Handle to a rendered output; pass to ovrtx_map_render_var_output() to access its data.

typedef struct ovrtx_render_var_output_map_handle_t ovrtx_render_var_output_map_handle_t#: Handle to the mapping of a rendered output that can be used to unmap it with ovrtx_unmap_render_var_output().

typedef struct ovrtx_op_id_t ovrtx_op_id_t#: Identifier of a particular asynchronous operation such as ovrtx_open_usd_from_file() that can be used to poll or wait.

OVRTX_INVALID_HANDLE#

Raw ID value representing an invalid/null renderer handle.

Valid renderer handles have non-zero raw IDs, so 0 is reserved to indicate “no handle” or “invalid handle”. Zero-initializing output handles and structures containing handles is valid API usage.

A non-zero value does not guarantee that a handle is still valid. Callers must track handle lifetime and stop using handles after their resources are released or invalidated. Destroying a resource or resetting a stage does not clear handle values stored by the caller. For asynchronous operations, distinguish successful enqueue from successful execution.

Use a kind-specific OVRTX_INVALID_* constant for comparisons and resets. OVRTX_INVALID_HANDLE is the legacy raw numeric sentinel; it cannot be assigned or passed as a typed handle. Array lease IDs are an exception: zero is a valid accessor-local lease ID.

An invalid handle is not universally an error when passed to an API: required live-handle parameters reject it, while discriminated inputs may use it to select an inline description instead. Each API parameter documents its specific behavior.

OVRTX_INVALID_USD_HANDLE#: Invalid value for ovrtx_usd_handle_t.

OVRTX_INVALID_EVENT_HANDLE#: Invalid value for ovrtx_event_handle_t.

OVRTX_INVALID_ATTRIBUTE_BINDING_HANDLE#: Invalid value for ovrtx_attribute_binding_handle_t.

OVRTX_INVALID_MAP_HANDLE#: Invalid value for ovrtx_map_handle_t.

OVRTX_INVALID_STEP_RESULT_HANDLE#: Invalid value for ovrtx_step_result_handle_t.

OVRTX_INVALID_RENDER_VAR_OUTPUT_HANDLE#: Invalid value for ovrtx_render_var_output_handle_t.

OVRTX_INVALID_RENDER_VAR_OUTPUT_MAP_HANDLE#: Invalid value for ovrtx_render_var_output_map_handle_t.

OVRTX_INVALID_OP_ID#: Invalid value for ovrtx_op_id_t.

OVRTX_INVALID_QUERY_HANDLE#: Invalid value for ovrtx_query_handle_t.

OVRTX_INVALID_READ_HANDLE#: Invalid value for ovrtx_read_handle_t.

struct ovrtx_usd_handle_t

#include <ovrtx_types.h>

Handle representing a USD stage.

Public Members

uint64_t raw_id#

struct ovrtx_event_handle_t

#include <ovrtx_types.h>

Handle representing an event.

Public Members

uint64_t raw_id#

struct ovrtx_attribute_binding_handle_t

#include <ovrtx_types.h>

Handle representing a persistent attribute binding.

Public Members

uint64_t raw_id#

struct ovrtx_map_handle_t

#include <ovrtx_types.h>

Handle representing a resource mapping that can be used to unmap it.

Public Members

uint64_t raw_id#

struct ovrtx_step_result_handle_t

#include <ovrtx_types.h>

Handle to the result of a ovrtx_step() operation.

Public Members

uint64_t raw_id#

struct ovrtx_render_var_output_handle_t

#include <ovrtx_types.h>

Handle to a rendered output; pass to ovrtx_map_render_var_output() to access its data.

Public Members

uint64_t raw_id#

struct ovrtx_render_var_output_map_handle_t

#include <ovrtx_types.h>

Handle to the mapping of a rendered output that can be used to unmap it with ovrtx_unmap_render_var_output().

Public Members

uint64_t raw_id#

struct ovrtx_op_id_t

#include <ovrtx_types.h>

Identifier of a particular asynchronous operation such as ovrtx_open_usd_from_file() that can be used to poll or wait.

Public Members

uint64_t raw_id#

Result Types #

enum ovrtx_api_status_t#

Return status from a synchronous function call.

Values:

enumerator OVRTX_API_SUCCESS#: The function completed successfully.

enumerator OVRTX_API_ERROR#

The function generated an error.

The associated error message can be queried with ovrtx_get_last_error().

enumerator OVRTX_API_TIMEOUT#: The timeout passed to the function was reached.

enum ovrtx_event_status_t#

Values:

enumerator OVRTX_EVENT_PENDING#

enumerator OVRTX_EVENT_COMPLETED#

enumerator OVRTX_EVENT_FAILURE#

struct ovrtx_result_t#

#include <ovrtx_types.h>

Result from a synchronous function call.

The status of the call can be checked with the ovrtx_result_t::status member.

Public Members

ovrtx_api_status_t status#: Status of the call.

struct ovrtx_enqueue_result_t#

#include <ovrtx_types.h>

Result from an asynchronous function call.

Contains the API call status and the operation index. A non-zero operation index can be used to poll or wait on completion, while a zero op ID means the operation could not be enqueued.

Note that if OVRTX_CONFIG_SYNC_MODE is active any error from the async operation itself will cause status to be OVRTX_API_ERROR and the error is obtainable using ovrtx_get_last_error(). In addition to this a valid operation index is still delivered and can be waited on (even though the operation has already failed).

Public Members

ovrtx_api_status_t status#: Status of the API call.

ovrtx_op_id_t op_index#: Non-zero operation identifier if operation enqueued successfully, a zero op ID otherwise.

Operation Wait Types #

struct ovrtx_op_wait_result_t#

#include <ovrtx_types.h>

Result of waiting on an ovrtx_op_id_t with ovrtx_wait_op().

Public Members

ovrtx_op_id_t *error_op_ids#: List of operation ids that errored since last wait call.

size_t num_error_ops#

ovrtx_op_id_t lowest_pending_op_id#: The lowest operation id that is still pending, or 0 if all operations are complete.

Synchronization Types #

static const ovrtx_timeout_t ovrtx_timeout_infinite = {(size_t)-1}#

ovrtx_timeout_t constant for infinity (i.e.

block indefinitely)

struct ovrtx_timeout_t#

#include <ovrtx_types.h>

Represents a timeout duration in nanoseconds.

Public Members

uint64_t time_out_ns#

struct ovrtx_cuda_sync_t#

#include <ovrtx_types.h>

CUDA synchronization inputs, or readiness information on mapped render-var outputs.

For input arguments, stream specifies the stream to synchronize to. On ovrtx_render_var_output_t, stream instead optionally identifies a borrowed producer stream; see that type’s contract. wait_event remains the output-ready event.

Note

Known driver scheduling interaction on Linux. A non-zero stream creates a stream-ordered CUDA wait that can reduce throughput when it is concurrent with the renderer’s Vulkan work; correct API use still triggers it. Windows is not affected. This applies to every ovrtx_cuda_sync_t and sync_stream field in the API. Refer to the “CUDA and Vulkan Scheduling on Linux” page in the ovrtx documentation for more details.

Public Members

uintptr_t stream#

Input: stream to synchronize to (0 = none, 1 = default, >1 = specific).

Mapped output: optional borrowed producer stream.

uintptr_t wait_event#: Event to wait on before operation (0 = none).

struct ovrtx_device_t#

#include <ovrtx_types.h>

Public Members

int32_t device_type#: DLDevice device_type.

int32_t device_id#: DLDevice device_id.

struct ovrtx_event_description_t#

#include <ovrtx_types.h>

Public Members

ovrtx_device_t device#: device to create the synchronization event on

Attribute Types #

enum ovrtx_write_bits_t#

Values:

enumerator OVRTX_DIRTY_MASK_REPLACE#: Replace consumer dirty mask.

enumerator OVRTX_DIRTY_MASK_OR#: OR masks together.

enumerator OVRTX_DIRTY_MASK_AND#: AND masks together.

enum ovrtx_data_access_t#

Values:

enumerator OVRTX_DATA_ACCESS_ASYNC#: Accesses the inputs asynchronously as part of the stream execution, so the input lifetime must remain valid until completion (use ovrtx_wait_op).

enumerator OVRTX_DATA_ACCESS_SYNC#: Copies all input data synchronously, so the data is no longer accessed when the call returns.

enum ovrtx_binding_prim_mode_t#

Describes how to handle attempts to write to paths in the runtime stage that do not exist.

Values:

enumerator OVRTX_BINDING_PRIM_MODE_EXISTING_ONLY#: Only existing attributes on existingprims are written to, prims that do not exist are ignored.

enumerator OVRTX_BINDING_PRIM_MODE_MUST_EXIST#: All attributes and prims must exist to write any data successfully.

enumerator OVRTX_BINDING_PRIM_MODE_CREATE_NEW#: New attribute/prim pairs are created when written to.

enum ovrtx_attribute_semantic_t#

Used to differentiate the intended data layout and usage of a given attribute type.

For example a transform attribute can be written as different data layouts that are automatically converted into renderer’s data layout. This enum is used to differentiate between data layouts written to the same attribute.

Values:

enumerator OVRTX_SEMANTIC_NONE#

enumerator OVRTX_SEMANTIC_XFORM_MAT4x4#: Transform of a prim expressed as row-major 4x4 matrix of double (kDLFloat, 64, 16).

enumerator OVRTX_SEMANTIC_XFORM_POS3d_ROT4f_SCALE3f#: Transform of a prim expressed as 3xdouble position, 4xfloat rotation and 3xfloat scale (kDLUInt, 8, 56).

enumerator OVRTX_SEMANTIC_XFORM_POS3d_ROT3x3f#: Transform of a prim expressed as 3xdouble position, 3x3float row-major rotation matrix (kDLUInt, 8, 64).

enumerator OVRTX_SEMANTIC_PATH_STRING#

Prim paths expressed as ovx_string_t (kDLUInt, 128, 1).

The strings must be valid for the duration of the write_attribute call. Only synchronous data access is supported.

enumerator OVRTX_SEMANTIC_TOKEN_STRING#

String token expressed as ovx_string_t (kDLUInt, 128, 1).

The strings must be valid for the duration of the write_attribute call. Only synchronous data access is supported.

enumerator OVRTX_SEMANTIC_TOKEN_ID#

Raw token identifier (kDLUInt, 64, 1).

Returned by query for token-valued attributes. Resolve to a string via the path dictionary.

enumerator OVRTX_SEMANTIC_PATH_ID#

Raw path identifier (kDLUInt, 64, 1).

Returned by query for path-valued attributes. Resolve to a string via the path dictionary.

enumerator OVRTX_SEMANTIC_TAG#

Name-only attribute with no value or storage.

Returned by query for tag attributes. No data should be read.

enumerator OVRTX_SEMANTIC_MATRIX#

Generic matrix-valued attribute (not a transform conversion).

Float64 2x2, 3x3, and 4x4 values retain the Fabric matrix role and read with square trailing dimensions.

enum ovrtx_binding_flag_t#

Flags giving hints to the renderer about the expected use of a binding.

Values:

enumerator OVRTX_BINDING_FLAG_NONE#

Indicates that the renderer should optimize it’s underlying data structures for frequent high volume writes to this binding.

The last created binding with this flag will be prioritized.

enumerator OVRTX_BINDING_FLAG_OPTIMIZE#

typedef struct ovrtx_prim_list_t ovrtx_prim_list_t#: A list of paths to prims in the runtime stage.

typedef enum ovrtx_binding_prim_mode_t ovrtx_binding_prim_mode_t: Describes how to handle attempts to write to paths in the runtime stage that do not exist.

typedef enum ovrtx_attribute_semantic_t ovrtx_attribute_semantic_t

Used to differentiate the intended data layout and usage of a given attribute type.

For example a transform attribute can be written as different data layouts that are automatically converted into renderer’s data layout. This enum is used to differentiate between data layouts written to the same attribute.

typedef struct ovrtx_xform_matrix44d_t ovrtx_xform_matrix44d_t#

typedef struct ovrtx_xform_pos3d_rot4f_scale3f_t ovrtx_xform_pos3d_rot4f_scale3f_t#

typedef struct ovrtx_xform_pos3d_rot3x3f_t ovrtx_xform_pos3d_rot3x3f_t#

typedef enum ovrtx_binding_flag_t ovrtx_binding_flag_t: Flags giving hints to the renderer about the expected use of a binding.

struct ovrtx_prim_list_t

#include <ovrtx_types.h>

A list of paths to prims in the runtime stage.

Public Members

const ovx_string_t *prim_paths#

size_t num_paths#

struct ovrtx_mapping_desc_t#

#include <ovrtx_types.h>

Public Members

int32_t device_type#: device_type from DLDevice

int32_t device_id#: device_id from DLDevice

struct ovrtx_xform_matrix44d_t

#include <ovrtx_types.h>

Public Members

double v[16]#

struct ovrtx_xform_pos3d_rot4f_scale3f_t

#include <ovrtx_types.h>

Public Members

double position[3]#

float rot_quat_xyzw[4]#

float scale[3]#

uint32_t padding#

struct ovrtx_xform_pos3d_rot3x3f_t

#include <ovrtx_types.h>

Public Members

double position[3]#

float rot_matrix[9]#

uint32_t padding#

struct ovrtx_attribute_type_t#

#include <ovrtx_types.h>

Describes the type of an attribute to be written to the runtime stage.

Public Members

DLDataType dtype#: Data type.

bool is_array#

Whether this attribute is an array attribute.

Array attributes are variable length per attribute

ovrtx_attribute_semantic_t semantic#: The interpretation of this array data in a USD stage.

struct ovrtx_binding_desc_t#

#include <ovrtx_types.h>

Describes a binding to an attribute on a list of prims so that they can be written to.

Public Members

ovrtx_prim_list_t prim_list#: Explicit list of prims when no handle provided.

ovx_primpath_list_t prims_list_handle#: Handle to a persistent prim list.

ovx_token_or_string_t attribute_name#: Name of the attribute.

ovrtx_attribute_type_t attribute_type#: Type of the attribute being bound.

ovrtx_binding_prim_mode_t prim_mode#: Mode to determine how prims are handled.

ovrtx_binding_flag_t flags#: Additional flags to control the binding behavior.

struct ovrtx_binding_desc_or_handle_t#

#include <ovrtx_types.h>

Represents either an ovrtx_binding_desc_t or an ovrtx_attribute_binding_handle_t allowing either to be passed to ovrtx_write_attribute() and ovrtx_map_attribute().

The use of persistent bindings allows for more optimal writes in the renderer when an attribute will be written to repeatedly.

If ovrtx_binding_desc_or_handle_t::binding_handle is non-zero then it will be used, otherwise ovrtx_binding_desc_or_handle_t::binding_desc will be used.

Public Members

ovrtx_binding_desc_t binding_desc#: binding description if no handle provided

ovrtx_attribute_binding_handle_t binding_handle#: handle to a persistent binding

struct ovrtx_input_buffer_t#

#include <ovrtx_types.h>

Input buffers as an array of tensors.

For array attributes the array length must match the number of prims in the attribute binding otherwise it must be 1.

The tensor object (not the data) are copied during the call and don’t have to persist for longer than the duration of the call.

DLTensor *tensors#: Array of tensors.

uint64_t tensor_count#: Number of tensors in the array.

Dirty bit tracking for selective updates.

The dirty bit array is copied and must not persist longer than the call.

uint8_t *dirty_bits#: Bitvector: 1 bit per prim for dirty tracking.

size_t dirty_bits_size#: Size of dirty_bits array: (prim_count + 7) / 8.

Synchronization

ovrtx_cuda_sync_t access_cuda_sync#: Optional synchronization hint used to guard access to the input data inside the renderer.

ovrtx_cuda_sync_t done_cuda_sync#: Optional synchronization hint used to signal that the input data is no longer accessed by the renderer.

struct ovrtx_read_dest_t#

#include <ovrtx_types.h>

Optional destination for ovrtx_read_attribute() scalar read data.

When the tensor pointer is non-null the read writes directly into the caller-provided buffer instead of allocating internal storage. The tensor must be pre-allocated with shape [prim_count] and a matching element size, including DLTensor::dtype.lanes for multi-component attributes. Its layout must be C-contiguous with DLTensor::byte_offset set to zero. For GPU tensors (kDLCUDA) the data is copied via cudaMemcpy. Must be NULL for array attributes (variable-length per prim).

Public Members

DLTensor *tensor#: Pre-allocated destination (NULL = use internal buffer).

ovrtx_cuda_sync_t access_cuda_sync#: Event to wait on before writing to the tensor.

ovrtx_cuda_sync_t done_cuda_sync#: Event to signal after writing is complete.

struct ovrtx_output_buffer_t#

#include <ovrtx_types.h>

Deprecated:: Use ovrtx_render_var_output_t tensors[]->dl instead. Kept for source compatibility with existing consumers.

Public Members

DLTensor dl#: Zero-copy tensor (required).

ovrtx_cuda_sync_t cuda_sync#: Optional CUDA synchronization hints associated with this buffer.

struct ovrtx_render_var_param_t#

#include <ovrtx_types.h>

Named render variable param represented as a DLTensor with labels.

The DLTensor’s dtype encodes the value type (e.g. kDLFloat/32 for float, kDLUInt/64 for uint64_t). Sensor scalar params use shape {1}, including CameraParams, InstanceIdTokenMapSD and point-cloud params. Inspect ndim and shape; vectors use {N} and matrices can use {4,4}. Params with ndim >= 1 provide strides. Other params, such as picking and compression metadata, may be rank 0 with NULL shape and strides. Param values are always CPU-resident: param.device is {kDLCPU, 0}.

Public Members

DLTensor dl#: Value tensor (dtype encodes type, shape encodes scalar/array).

ovx_string_t name#

Entry name (e.g.

“frameId”, “timestampNs”)

ovx_string_t doc#: Human-readable description.

struct ovrtx_attribute_mapping_t#

#include <ovrtx_types.h>

Mapped attribute that can be written to until unmapped.

Scalar lanes and compact strides match returned read tensors: scalars [N], tuples [N,C], and semantic square matrices [N,S,S] (S=2,3,4). Descriptor metadata is borrowed and must not be modified.

Public Members

ovrtx_map_handle_t map_handle#: Map handle for unmap operation.

DLTensor dl#: Mapped memory as tensor, valid until unmap.

Query Types #

enum ovrtx_filter_kind_t#

Values:

enumerator OVRTX_FILTER_PRIM_TYPE#: Match by USD prim type name (e.g., “Mesh”, “SphereLight”).

enumerator OVRTX_FILTER_HAS_ATTRIBUTE#: Match by attribute existence (e.g., “points”, “normals”).

enum ovrtx_attribute_filter_mode_t#

Values:

enumerator OVRTX_ATTRIBUTE_FILTER_NONE#: Do not report attributes (lightweight).

enumerator OVRTX_ATTRIBUTE_FILTER_ALL#: Report every attribute on each group.

enumerator OVRTX_ATTRIBUTE_FILTER_SPECIFIC#: Report only the named subset of attributes.

typedef struct ovrtx_query_handle_t ovrtx_query_handle_t#: Handle to the result of a ovrtx_query_prims() operation.

typedef enum ovrtx_filter_kind_t ovrtx_filter_kind_t

typedef struct ovrtx_filter_t ovrtx_filter_t#

typedef enum ovrtx_attribute_filter_mode_t ovrtx_attribute_filter_mode_t

typedef struct ovrtx_attribute_filter_t ovrtx_attribute_filter_t#

typedef struct ovrtx_query_desc_t ovrtx_query_desc_t#

typedef struct ovrtx_attribute_desc_t ovrtx_attribute_desc_t#

Describes a single attribute on a group of prims in the query result.

The name is a token that can be resolved to a string via the path dictionary’s get_strings_from_tokens.

typedef struct ovrtx_query_prim_group_t ovrtx_query_prim_group_t#

A group of prims sharing the same attribute schema, returned by ovrtx_fetch_query_results().

All prims in a group are guaranteed to have the same set of attributes. The ovrtx_query_prim_group_t::prim_list_handle can be plugged directly into ovrtx_binding_desc_t::prims_list_handle for subsequent read or write operations.

typedef struct ovrtx_query_result_t ovrtx_query_result_t#

Result of a ovrtx_query_prims() operation retrieved via ovrtx_fetch_query_results().

Contains one group per matching bucket. All pointers are valid until ovrtx_release_query_results() is called.

struct ovrtx_query_handle_t

#include <ovrtx_types.h>

Handle to the result of a ovrtx_query_prims() operation.

Public Members

uint64_t raw_id#

struct ovrtx_filter_t

#include <ovrtx_types.h>

Public Members

ovrtx_filter_kind_t kind#: What property to match.

ovx_token_or_string_t name#: Prim type name or attribute name.

struct ovrtx_attribute_filter_t

#include <ovrtx_types.h>

Public Members

ovrtx_attribute_filter_mode_t mode#: Which attributes to report.

const ovx_token_or_string_t *attribute_names#: Attribute names (used when mode is SPECIFIC).

size_t attribute_name_count#: Number of entries in attribute_names.

struct ovrtx_query_desc_t

#include <ovrtx_types.h>

Public Members

const ovrtx_filter_t *require_all#: Filters the prim must match (AND).

size_t require_all_count#: Number of require_all filters.

const ovrtx_filter_t *require_any#: Filters the prim must match at least one of (OR).

size_t require_any_count#: Number of require_any filters.

const ovrtx_filter_t *exclude#: Filters the prim must not match (NOT).

size_t exclude_count#: Number of exclude filters.

ovrtx_attribute_filter_t attribute_filter#: Which attributes to report per group.

struct ovrtx_attribute_desc_t

#include <ovrtx_types.h>

Describes a single attribute on a group of prims in the query result.

The name is a token that can be resolved to a string via the path dictionary’s get_strings_from_tokens.

Public Members

ovx_token_t name#: Attribute name token (resolve via path dictionary).

ovrtx_attribute_type_t type#: Attribute data type, array-ness, and semantic.

struct ovrtx_query_prim_group_t

#include <ovrtx_types.h>

A group of prims sharing the same attribute schema, returned by ovrtx_fetch_query_results().

All prims in a group are guaranteed to have the same set of attributes. The ovrtx_query_prim_group_t::prim_list_handle can be plugged directly into ovrtx_binding_desc_t::prims_list_handle for subsequent read or write operations.

Public Members

size_t prim_count#: Number of prims in this group.

ovx_primpath_list_t prim_list_handle#: Handle to the prim paths in this group.

const ovrtx_attribute_desc_t *attributes#: Array of attribute descriptors (NULL if not requested).

size_t attribute_count#: Number of entries in attributes.

struct ovrtx_query_result_t

#include <ovrtx_types.h>

Result of a ovrtx_query_prims() operation retrieved via ovrtx_fetch_query_results().

Contains one group per matching bucket. All pointers are valid until ovrtx_release_query_results() is called.

Public Members

const ovrtx_query_prim_group_t *groups#: Array of prim groups.

size_t group_count#: Number of groups.

size_t total_prim_count#: Sum of prim_count across all groups.

Read Types #

typedef struct ovrtx_read_handle_t ovrtx_read_handle_t#

Handle to the result of a ovrtx_read_attribute() operation.

The same handle is passed to ovrtx_fetch_read_result() and ovrtx_release_read_result().

typedef struct ovrtx_read_output_t ovrtx_read_output_t#

Attribute read output retrieved via ovrtx_fetch_read_result().

For fixed-size attributes ovrtx_read_output_t::buffer_count is 1 and the single tensor has leading shape [prim_count]. For array attributes ovrtx_read_output_t::buffer_count equals ovrtx_read_output_t::prim_count with one tensor per prim of variable length. Returned tensors have DLTensor::dtype.lanes == 1. Multi-component values add a trailing component dimension; matrix-typed values add two square dimensions instead (for example, matrix4d uses [prim_count, 4, 4]). All strides are explicit and compact.

When a user-provided destination tensor was passed to ovrtx_read_attribute(), buffer_count is 0 (the data was written directly into the caller’s tensor).

struct ovrtx_read_handle_t

#include <ovrtx_types.h>

Handle to the result of a ovrtx_read_attribute() operation.

The same handle is passed to ovrtx_fetch_read_result() and ovrtx_release_read_result().

Public Members

uint64_t raw_id#

struct ovrtx_read_output_t

#include <ovrtx_types.h>

Attribute read output retrieved via ovrtx_fetch_read_result().

For fixed-size attributes ovrtx_read_output_t::buffer_count is 1 and the single tensor has leading shape [prim_count]. For array attributes ovrtx_read_output_t::buffer_count equals ovrtx_read_output_t::prim_count with one tensor per prim of variable length. Returned tensors have DLTensor::dtype.lanes == 1. Multi-component values add a trailing component dimension; matrix-typed values add two square dimensions instead (for example, matrix4d uses [prim_count, 4, 4]). All strides are explicit and compact.

When a user-provided destination tensor was passed to ovrtx_read_attribute(), buffer_count is 0 (the data was written directly into the caller’s tensor).

Public Members

ovrtx_output_buffer_t *buffers#: Array of output tensors (NULL when dest tensor was used).

size_t buffer_count#: Number of buffers (1 for scalar, prim_count for array, 0 if dest tensor).

size_t prim_count#: Number of prims that were actually read.

bool is_array#: True if the attribute is variable-length per prim (resolved from stage).

Sensor Types #

enum ovrtx_renderer_event_status_t#

Enum representing the status of an asynchronous operation.

Values:

enumerator OVRTX_RENDERER_EVENT_PENDING#: Operation still in progress.

enumerator OVRTX_RENDERER_EVENT_COMPLETED#: Operation completed successfully.

enumerator OVRTX_RENDERER_EVENT_FAILED#: Operation failed with error.

enum ovrtx_map_device_type_t#

Specifies which device (CPU or GPU) should be used to map a given output.

Values:

enumerator OVRTX_MAP_DEVICE_TYPE_DEFAULT#

Provide the data in whatever format is most efficient.

Read back output from GPU to CPU. This will incur synchronization and copy.

enumerator OVRTX_MAP_DEVICE_TYPE_CPU#

Raw CUDA device memory as dltensor.

This will likely incur an additional copy when used for image outputs.

enumerator OVRTX_MAP_DEVICE_TYPE_CUDA#

CUDA array represented in dltensor as kDLCUDA / kDLOpaqueHandle.

This saves a copy for image outputs, but is not supported for other outputs.

enumerator OVRTX_MAP_DEVICE_TYPE_CUDA_ARRAY#

typedef struct ovrtx_render_product_set_t ovrtx_render_product_set_t#: Set of RenderProducts that will be stepped.

typedef struct ovrtx_tile_list_t ovrtx_tile_list_t#: Tiles of a tiled RenderProduct for ovrtx_clear_history, as indices into its view-tile grid.

typedef struct ovrtx_render_quality_t ovrtx_render_quality_t#

Quality override for the frame rendered after ovrtx_clear_history.

A zero-initialized value renders once, like passing NULL.

OVRTX_CLEAR_HISTORY_FLAG_FIRST_FRAME_QUALITY#

ovrtx_clear_history flag: render the cleared frame like the RenderProduct’s first frame, applying its omni:rtx:waitForEvents and omni:rtx:quality.

Cannot be combined with a quality override.

OVRTX_RENDER_VAR_PICK_HIT#

struct ovrtx_render_product_set_t

#include <ovrtx_types.h>

Set of RenderProducts that will be stepped.

Public Members

const ovx_string_t *render_products#: Array of paths to RenderProduct prims in the stage.

size_t num_render_products#: Number of paths in the array.

struct ovrtx_render_product_render_var_output_t#

#include <ovrtx_types.h>

Associates a RenderVar output handle with the RenderVar that produced it.

A rendered frame has an entry for every RenderVar in the render product’s orderedVars, in that order, including one OVRTX could not produce; a DLSS-G interpolated frame has entries only for its color RenderVars, and one fails when the same RenderVar’s compression fails on the rendered frame. A failed entry has status set to OVRTX_EVENT_FAILURE and says why in error_message; the render product’s other RenderVars are still rendered. Mapping a failed output fails with the same message.

Public Members

ovx_string_t render_var_path#: Full USD RenderVar prim path, or a reserved OVRTX synthetic output name.

ovx_string_t source_name#

RenderVar sourceName, e.g.

“LdrColor”.

ovx_string_t source_type#

RenderVar sourceType, e.g.

“raw” or “lpe”.

ovrtx_render_var_output_handle_t output_handle#: Handle to the rendered output.

ovrtx_event_status_t status#: OVRTX_EVENT_COMPLETED when the output was produced, OVRTX_EVENT_FAILURE when OVRTX could not produce it.

ovx_string_t error_message#

Why OVRTX could not produce the output, naming the RenderVar and, for an invalid setting, the attribute and its accepted values.

Empty when status is OVRTX_EVENT_COMPLETED.

struct ovrtx_accumulation_status_t#

#include <ovrtx_types.h>

Path-tracing accumulation status for a rendered frame.

Public Members

uint32_t progression#: PathTracing sample accumulation progress since the last reset; increments each time an output is rendered.

bool converged#: True when a stop criterion was reached (ex: omni:rtx:pt:samplesPerPixel).

struct ovrtx_render_product_frame_output_t#

#include <ovrtx_types.h>

Output of a particular RenderProduct for a particular frame.

May contain one or more RenderVar outputs in ovrtx_render_product_frame_output_t::output_render_vars which may each be mapped to get access to the output data using ovrtx_map_render_var_output().

Public Members

double frame_start_time#: Sensor time (based on step(delta_time) history) when the sensor simulation for this frame started.

double frame_end_time#: Sensor time (based on step(delta_time) history) when the sensor simulation for this frame ended.

ovrtx_render_product_render_var_output_t *output_render_vars#: Pointer to array of render var outputs.

size_t render_var_count#: Number of render var outputs for this render product frame.

ovrtx_accumulation_status_t accumulation_status#: Path-tracing accumulation status for this frame.

struct ovrtx_render_product_output_t#

#include <ovrtx_types.h>

The output of a particular RenderProduct for a particular ovrtx_step() operation.

Public Members

ovx_string_t render_product_path#: Path of the render product that produced this output.

float output_frames_produced#: Decimal value representing the amount of frames produced.

ovrtx_render_product_frame_output_t *output_frames#: pointer to array of output frames

size_t output_frame_count#: Number of frames for this render product.

struct ovrtx_render_product_set_outputs_t#

#include <ovrtx_types.h>

The set of RenderProduct outputs for a ovrtx_step() operation.

Depending on the sensor configuration, each ovrtx_step() may produce zero or more frames for each RenderProduct in the ovrtx_render_product_set_t passed to ovrtx_step().

Public Members

ovrtx_event_status_t status#: Current operation status.

ovx_string_t error_message#: Error description if failed, NULL if succeeded.

double simulation_start_time#: Sensor time (based on step(delta_time) history) when the step which produced this output started.

double simulation_end_time#: Sensor time (based on step(delta_time) history) when the step which produced this output ended.

ovrtx_render_product_output_t *outputs#: Array of outputs returned.

size_t output_count#: Number of outputs in the array.

double start_time#: Sensor time (based on step(delta_time) history) when the sensor simulation for this step started.

double end_time#: Sensor time (based on step(delta_time) history) when the sensor simulation for this step ended.

struct ovrtx_tile_list_t

#include <ovrtx_types.h>

Tiles of a tiled RenderProduct for ovrtx_clear_history, as indices into its view-tile grid.

Public Members

const uint32_t *tile_indices#: Array of tile indices.

size_t num_tiles#: Number of indices in the array.

struct ovrtx_render_quality_t

#include <ovrtx_types.h>

Quality override for the frame rendered after ovrtx_clear_history.

A zero-initialized value renders once, like passing NULL.

Public Members

bool wait_for_streaming#: Wait for asset streaming, as omni:rtx:waitForEvents = [AllLoadingFinished].

int32_t quality#: Initial quality in [0, 100], with the same meaning as omni:rtx:quality.

struct ovrtx_map_output_description_t#

#include <ovrtx_types.h>

Description of the device and synchronization for mapping an output to be passed to ovrtx_map_render_var_output().

The device_type applies to tensors only. Param entries are always mapped to CPU regardless of this setting.

Public Members

ovrtx_map_device_type_t device_type#: Requested device for tensors (params are always CPU).

uintptr_t sync_stream#

CUDA stream to synchronize production of the output with.

Providing a stream here means that after the map call returns the output data can immediately be accessed on a cuda stream that is synchronized to the provided stream. 0 = no synchronization. 1 = default cuda stream, >1 specific stream

struct ovrtx_render_var_tensor_t#

#include <ovrtx_types.h>

One tensor slot in a mapped render variable output (DLPack view plus labels).

Lifetime: pointers are valid from ovrtx_map_render_var_output() until ovrtx_unmap_render_var_output().

Public Members

const DLTensor *dl#: DLPack tensor (device per map request; may be CUDA array as opaque handle).

const ovx_string_t *name#

Tensor name (e.g.

channel or slice); never NULL when num_tensors > 0

const ovx_string_t *doc#: Human-readable tensor description; may point to an empty string.

struct ovrtx_render_var_output_t#

#include <ovrtx_types.h>

The output of a particular RenderVar for a particular RenderProduct on a particular frame.

Contains zero or more named tensor slots (ovrtx_render_var_tensor_t) and zero or more named param entries. Tensor data may reside on CPU or CUDA depending on the map request. Params are always CPU-resident.

Lifetime: valid from ovrtx_map_render_var_output() until ovrtx_unmap_render_var_output().

The stream is a moving queue tail, not the event’s fixed readiness point. Work enqueued here follows everything already queued on it, including later products, the end of the render graph, and already-submitted subsequent steps. This gives up per-product readiness even when wait_event is per-product; the same queue-tail rule applies with a per-device end-of-graph event. Consumers using the readiness event must ignore cuda_sync.stream rather than treat it as another dependency.

The stream is borrowed, enqueue-only, and is NOT kept alive by the mapping. Never destroy it, change its configuration, or begin CUDA graph capture on it. Use it only while the mapping is live and the renderer’s render graph is stable: serialize handoff with operations that may rebuild the graph, reset, or destroy the renderer. Finish consumer work and release mappings before such operations; never cache the handle across them or assume consecutive outputs use the same stream. Keep work short because it can delay subsequent renderer work sharing this stream. Unmapping still requires before_destroy_cuda_sync covering all consumer reads (or prior completion). Returning the borrowed stream as that input is supported, but may block the CPU; a consumer completion event can be used instead.

Note

Experimental producer-stream handoff: for uniform zero-copy CUDA outputs, cuda_sync.stream may be nonzero and identify the stream on which cuda_sync.wait_event was recorded. Enqueue read-only consumer work directly on that stream without an additional event wait. Use the CUDA context owning the stream on tensors[0].dl’s device.device_id (the renderer’s CUDA primary context). A zero stream means this path is unavailable: observe wait_event before reading on a consumer-owned stream. CPU, asynchronously copied, compressed, and composite outputs do not expose a stream. Map with sync_stream=0 to avoid an additional map-time cross-stream readiness wait.

Note

ABI break from pre-0.3: the ovrtx_output_buffer_t buffer field has been removed. Consumers must migrate to the tensors[]/params[] layout.

Public Members

ovrtx_event_status_t status#: Current operation status.

ovx_string_t error_message#: Error description if failed, NULL if succeeded.

ovrtx_render_var_output_map_handle_t map_handle#: Handle to use for unmap.

ovrtx_cuda_sync_t cuda_sync#: Readiness event covering all tensors; optional borrowed producer stream as described above.

ovx_string_t name#: Full USD prim path of the associated RenderVar.

ovx_string_t type#: Semantic type identifier.

ovx_string_t doc#: Human-readable description.

int version#: Output schema version.

size_t num_tensors#: Number of tensors in this output (may be 0).

const ovrtx_render_var_tensor_t *tensors#: Array of num_tensors tensor descriptors.

size_t num_params#: Number of param entries in this output (may be 0).

const ovrtx_render_var_param_t *params#: Array of num_params entries (always CPU).

Picking Types #

typedef struct ovrtx_pick_query_desc_t ovrtx_pick_query_desc_t#

Pick rectangle in normalized RenderProduct coordinates.

Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For example, pixel (x, y) on a width x height RenderProduct is [x / width, y / height, (x + 1) / width, (y + 1) / height]; the full RenderProduct is [0, 0, 1, 1]. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

OVRTX_PICK_FLAG_GIZMO#

OVRTX_PICK_FLAG_INCLUDE_TRACKED_INFO#

Include tracked metadata for a one-pixel-equivalent pick.

When available, the first hit’s objectType, geometryInstanceId, worldPositionM, and worldNormal tensors are populated. Without this flag, those tensors are present but zero-filled. Multi-pixel picks do not provide tracked metadata and leave those tensors zero-filled even when this flag is set.

OVRTX_PICK_HIT_MAGIC#

Schema-identity / schema-version handshake for the multi-tensor render variable OVRTX_RENDER_VAR_PICK_HIT.

The mapped output exposes both as named uint32 params (magic and version); consumers must validate magic == OVRTX_PICK_HIT_MAGIC and version == OVRTX_PICK_HIT_VERSION before reading the v1 tensor schema. The number of valid records is published as the hitCount param. Hits contain ovx_primpath_t handles only; resolve to UTF-8 with the renderer path dictionary if needed. ‘VPTH’

OVRTX_PICK_HIT_VERSION#

struct ovrtx_pick_query_desc_t

#include <ovrtx_types.h>

Pick rectangle in normalized RenderProduct coordinates.

Values use [0, 1] top-left-origin NDC: x increases left-to-right and y increases top-to-bottom. The rectangle uses the same convention as the old pixel API: right_ndc and bottom_ndc mark the edge just past the last included pixel. For example, pixel (x, y) on a width x height RenderProduct is [x / width, y / height, (x + 1) / width, (y + 1) / height]; the full RenderProduct is [0, 0, 1, 1]. Out-of-bounds values are rejected; boundary values may be clamped to the valid range to account for floating-point roundoff.

Public Members

ovx_string_t render_product_path#

float left_ndc#

float top_ndc#

float right_ndc#

float bottom_ndc#

uint32_t flags#

Optional pick flags.

Use OVRTX_PICK_FLAG_INCLUDE_TRACKED_INFO to request tracked metadata for a one-pixel-equivalent pick.

Selection Styling Types #

enum ovrtx_selection_fill_mode_t#

Selection-outline interior (fill) mode.

Mirrors OutlineMode in the underlying RTX shader. Set globally via OVRTX_CONFIG_SELECTION_FILL_MODE at renderer creation.

Values:

enumerator OVRTX_SELECTION_FILL_MODE_EDGE_ONLY#: No interior fill (outline edge only).

enumerator OVRTX_SELECTION_FILL_MODE_GLOBAL#: Global intersection color shared by all groups (kGlobalColorForInterior).

enumerator OVRTX_SELECTION_FILL_MODE_GROUP_OUTLINE_COLOR#: Use each group’s outline color as its interior fill (kOutlineColorForInterior).

enumerator OVRTX_SELECTION_FILL_MODE_GROUP_FILL_COLOR#: Use each group’s dedicated fill/shade color as its interior fill (kShadeColorForInterior).

enum ovrtx_motion_bvh_t#

Motion BVH (ray-traced motion) mode for sensor and motion-sensitive pipelines.

Set via OVRTX_CONFIG_MOTION_BVH at renderer creation.

Values:

enumerator OVRTX_MOTION_BVH_DISABLE#: Motion BVH disabled (the default global policy).

enumerator OVRTX_MOTION_BVH_ENABLE#: Motion BVH enabled from renderer creation.

enumerator OVRTX_MOTION_BVH_AUTO#: Motion BVH enabled at runtime when a non-visual sensor or motion-sensitive camera is rendered.

typedef enum ovrtx_selection_fill_mode_t ovrtx_selection_fill_mode_t

Selection-outline interior (fill) mode.

Mirrors OutlineMode in the underlying RTX shader. Set globally via OVRTX_CONFIG_SELECTION_FILL_MODE at renderer creation.

typedef enum ovrtx_motion_bvh_t ovrtx_motion_bvh_t

Motion BVH (ray-traced motion) mode for sensor and motion-sensitive pipelines.

Set via OVRTX_CONFIG_MOTION_BVH at renderer creation.

typedef struct ovrtx_selection_group_style_t ovrtx_selection_group_style_t#

Visual styling for one selection-outline group.

RGBA components in [0..1].

struct ovrtx_selection_group_style_t

#include <ovrtx_types.h>

Visual styling for one selection-outline group.

RGBA components in [0..1].

Public Members

float outline_color[4]#: Outline edge color (matches /persistent/app/viewport/outline/color).

float fill_color[4]#: Interior fill color (matches /persistent/app/viewport/outline/shadeColor; used when OVRTX_CONFIG_SELECTION_FILL_MODE selects per-group fill modes).

float outline_width#

Outline width in pixels, 1..15 (matches /persistent/app/viewport/outline/widths; group 255 sets /persistent/app/viewport/outline/width).

Overrides the renderer-creation default from OVRTX_CONFIG_SELECTION_OUTLINE_WIDTH for this group. Leaving it at 0 (C zero-init, so color-only initializers need not mention it) leaves the group’s current width in place rather than setting a width of 0; a group that has never been given an explicit width therefore keeps the configured default. Suppressing one group’s outline is not expressible here — clear the group instead.

Operation Status Types #

typedef struct ovrtx_op_counter_t ovrtx_op_counter_t#

Named resource counter for tracking progress of specific resource types.

Counter semantics:

name: Identifies the resource type (e.g., “shaders”, “textures”, “materials”)
current: Number of items processed so far
total: Total items to process, or 0 if the total is not yet known

typedef struct ovrtx_op_status_t ovrtx_op_status_t#

Operation status information for long-running operations.

Progress semantics:

Range [0.0, 1.0] where 1.0 = complete
Negative value indicates indeterminate progress

struct ovrtx_op_counter_t

#include <ovrtx_types.h>

Named resource counter for tracking progress of specific resource types.

Counter semantics:

name: Identifies the resource type (e.g., “shaders”, “textures”, “materials”)
current: Number of items processed so far
total: Total items to process, or 0 if the total is not yet known

Public Members

ovx_string_t name#: Counter name (e.g., “shaders”, “textures”).

uint64_t current#: Number of items processed so far.

uint64_t total#: Total number of items to process (0 if unknown).

struct ovrtx_op_status_t

#include <ovrtx_types.h>

Operation status information for long-running operations.

Progress semantics:

Range [0.0, 1.0] where 1.0 = complete
Negative value indicates indeterminate progress

Public Members

ovrtx_op_id_t op_id#: Operation ID this status refers to.

ovrtx_event_status_t state#: PENDING, COMPLETED, or FAILURE.

double progress#: Progress as fraction [0.0, 1.0], or negative if indeterminate.

ovrtx_op_counter_t *counters#: Named resource counters (variable count, operation-dependent).

size_t counter_count#

Logging Types #

enum ovx_log_severity_t#

Log severity levels for operation messages.

Values:

enumerator OVX_LOG_VERBOSE#: Verbose/debug message.

enumerator OVX_LOG_INFO#: Informational message.

enumerator OVX_LOG_WARNING#: Warning (operation continues).

enumerator OVX_LOG_ERROR#: Error (operation may have failed).

enumerator OVX_LOG_FATAL#: Fatal error (operation may have failed).

typedef enum ovx_log_severity_t ovx_log_severity_t: Log severity levels for operation messages.

typedef struct ovx_log_message_t ovx_log_message_t#

Metadata associated with a log message emitted by the runtime.

This struct is passed to the log callback for each message, providing rich contextual information to aid in debugging and analysis. Note that all of the strings in this object are only value for the duration of the log callback call. If they need to be stored or queued for later use, they must be copied during the callback.

typedef void (*ovx_log_callback_t)(const ovx_log_message_t *message, void *user_data)#

Callback function type for receiving log messages.

The callback is process-global and may be invoked from any thread. If the host app uses the same callback function for multiple OV libraries, it must protect access to any resources used inside the callback function since it may be called concurrently from multiple threads.

The strings passed in the message data are only valid for the duration of the callback. If the message needs to be retained, copy it before returning.

Param message:: [in] The log message and associated metadata. All string fields are only valid during the callback.
Param user_data:: [in] User-provided context from ovrtx_set_log_callback

struct ovx_log_message_t

#include <logging_types.h>

Metadata associated with a log message emitted by the runtime.

This struct is passed to the log callback for each message, providing rich contextual information to aid in debugging and analysis. Note that all of the strings in this object are only value for the duration of the log callback call. If they need to be stored or queued for later use, they must be copied during the callback.

Public Members

size_t thisSize#

The size of this object in bytes.

This is used as a versioning method for this struct and can be used to verify whether specific fields are valid. This is used by checking if the byte offset of a given field is less than this value. If the offset is larger than or equal to this value, it is not safe to access that field. When this happens, it means that the object came from an earlier version of this struct.

All fields up to and including message may be assumed to always be present and valid. Any fields after message must have their offset checked against this value to determine if they are valid or not.

ovx_log_severity_t severity#

Severity level of the message.

This will be one of the OVX_LOG_* log severity names.

ovx_string_t libraryName#

The name of the OV library that is emitting this log message.

This will be constant for all log messages emitted by a given OV library for the lifetime of the library.

ovx_string_t channel#

The log channel name that this log message was emitted against.

This channel name will be present and non-empty for all log messages.

uint64_t timestampNs#

Wall-clock time in nanoseconds since the Unix epoch of midnight January 1, 1970.

Note that this value may be subject to wall-clock adjustments (e.g. NTP) and should not be used for precise timing measurements; use elapsedTimeNs instead for that purpose.

uint64_t elapsedTimeNs#

Elapsed time in nanoseconds since the start of the process.

This time value is derived from the steady clock and will not be subject to wall-clock adjustments. The epoch of this timestamp should be considered arbitrary and should only be used for relative timing measurements.

ovx_string_t filePath#: Source file path where the log message was generated.

uint32_t lineNumber#: Source line number where the log message was generated.

ovx_string_t functionName#: Source function name where the log message was generated.

uint32_t processId#: System specific ID of the process that generated the log message.

uint32_t threadId#: System specific ID of the thread that generated the log message.

uint64_t sequenceNumber#

Monotonically increasing sequence number for ordering messages.

This value can be used to reorder a log postmortem if messages are received or stored out of order.

ovx_string_t message#: The log message text (UTF-8 string) itself.

Configuration Types #

enum ovrtx_texture_streaming_mode_t#

Texture streaming mode.

Set via OVRTX_CONFIG_TEXTURE_STREAMING_MODE at renderer creation. The setting is process-global and applies to all active renderer instances.

Values:

enumerator OVRTX_TEXTURE_STREAMING_DISABLE#

Disable texture streaming.

Textures are created as regular resources.

enumerator OVRTX_TEXTURE_STREAMING_SYNCHRONOUS#: Enable texture streaming and process texture feedback synchronously.

enumerator OVRTX_TEXTURE_STREAMING_ASYNCHRONOUS#: Enable texture streaming and process texture feedback asynchronously (default).

enum ovrtx_aftermath_mode_t#

NVIDIA Nsight Aftermath mode.

Set via OVRTX_CONFIG_AFTERMATH_MODE at renderer creation. This is process-global because Aftermath initialization is shared by active renderers.

Values:

enumerator OVRTX_AFTERMATH_DISABLE#: Disable Aftermath explicitly.

enumerator OVRTX_AFTERMATH_ENABLE#: Initialize Aftermath with explicit diagnostics enabled.

enumerator OVRTX_AFTERMATH_AUTO#: Select the Aftermath initialization mode automatically.

enum ovrtx_config_key_type_t#

Key type tag for ovrtx_config_entry_t; selects which key and value union members are valid.

Values:

enumerator OVRTX_CONFIG_KEY_TYPE_BOOL#

enumerator OVRTX_CONFIG_KEY_TYPE_INT64#

enumerator OVRTX_CONFIG_KEY_TYPE_UINT64#

enumerator OVRTX_CONFIG_KEY_TYPE_DOUBLE#

enumerator OVRTX_CONFIG_KEY_TYPE_STRING#

enumerator OVRTX_CONFIG_KEY_TYPE_BLOB#

enumerator OVRTX_CONFIG_KEY_TYPE_COUNT#

enum ovrtx_config_bool_t#

Boolean config keys.

Value type: bool. Used at init and create_renderer (must match).

Values:

enumerator OVRTX_CONFIG_SYNC_MODE#

If true, stream operations execute synchronously (enqueue blocks).

Init and create_renderer.

enumerator OVRTX_CONFIG_ENABLE_PROFILING#

If true, enables internal profiling.

Init and create_renderer.

enumerator OVRTX_CONFIG_READ_GPU_TRANSFORMS#

If true, uses GPU world transform propagation during rendering.

Create_renderer.

enumerator OVRTX_CONFIG_KEEP_SYSTEM_ALIVE#

If true, keeps the renderer system alive after all instances are destroyed (for reuse).

Create_renderer.

enumerator OVRTX_CONFIG_DEPRECATED_4#

Retired OVRTX_CONFIG_USE_VULKAN slot.

Passing this key returns an error.

enumerator OVRTX_CONFIG_SELECTION_OUTLINE_ENABLED#

If true, enables the selection outline postprocessing pass.

Create_renderer. When not specified, defaults to true.

enumerator OVRTX_CONFIG_ENABLE_GEOMETRY_STREAMING#

If true, enables geometry streaming.

Create_renderer. When not specified, defaults to false.

enumerator OVRTX_CONFIG_ENABLE_GEOMETRY_STREAMING_LOD#

API key for the geometry streaming LOD opt-in flag.

Create_renderer.

enumerator OVRTX_CONFIG_ENABLE_SPG#

If false, disables Sensor Processing Graphs (SPG), default: enabled.

This is a global setting, applying to all active renderer instances.

enumerator OVRTX_CONFIG_SUPPRESS_DEPRECATION_WARNINGS#

If true, suppresses runtime deprecation warnings emitted by legacy OVRTX APIs.

Compile-time deprecation diagnostics are unaffected. Create_renderer.

enumerator OVRTX_CONFIG_ENABLE_MINIMAL#

Controls whether Minimal rendering is available.

Pass to ovrtx_create_renderer(), not ovrtx_initialize(). The first ovrtx renderer instance initializes shared graphics resources: true enables this rendering mode, false disables it, and omission leaves availability unchanged. All three modes are enabled by default. Additional ovrtx renderer instances inherit this availability; conflicting explicit values fail creation. To reset availability, create an instance with OVRTX_CONFIG_KEEP_SYSTEM_ALIVE=false and omit all OVRTX_CONFIG_ENABLE_* entries. This clears retention left by earlier keep-alive instances. Then destroy every ovrtx renderer instance, including this temporary instance, before creating one with different modes. Do not create another keep-alive instance during teardown. At least one rendering mode must remain enabled. A RenderProduct requesting a disabled mode logs a warning and uses the first enabled mode in RT2, PathTracing, then Minimal order. For example, an RT2 request uses Minimal when only Minimal is enabled.

enumerator OVRTX_CONFIG_ENABLE_REALTIMEPATHTRACING#

Controls whether real-time path tracing (RT2) is available.

Pass to ovrtx_create_renderer(). Same creation-time, shared graphics resource, and omission rules as OVRTX_CONFIG_ENABLE_MINIMAL.

enumerator OVRTX_CONFIG_ENABLE_PATHTRACING#

Controls whether PathTracing is available.

Pass to ovrtx_create_renderer(). Same creation-time, shared graphics resource, and omission rules as OVRTX_CONFIG_ENABLE_MINIMAL.

enumerator OVRTX_CONFIG_ENABLE_MDL_DISPLACEMENT#

If true, enables MDL material displacement.

Pass to ovrtx_create_renderer(). When not specified, defaults to false.

enumerator OVRTX_CONFIG_ENABLE_SPECTRAL_RENDERING#

Enables Spectral PathTracing shaders, materials, and sampled physical illuminants.

Pass to ovrtx_create_renderer(). Set before the first renderer is created. Defaults to false; omission on later instances inherits the process choice. Conflicting explicit values fail, even after all instances are destroyed, because the material backend persists. Use a new process to change this option. Also author omni:rtx:pathtracing:spectral:enabled=true on each PathTracing RenderProduct. Use separate processes for RGB and spectral comparisons; mixed transport in one scene is unsupported.

enumerator OVRTX_CONFIG_ENABLE_CRASH_REPORTER#

If false, OVRTX does not start its crash reporter, so a host that owns crash handling keeps it.

Pass to ovrtx_create_renderer(). Defaults to true. The first renderer in the process decides; omission on later instances inherits that choice, and a conflicting explicit value fails, even after all instances are destroyed. Use a new process to change this option.

enumerator OVRTX_CONFIG_ENABLE_GLOBAL_CACHE_ROOT#

Select the platform’s global cache root for ${omni_cache} and OVRTX’s writable caches.

Omission defaults to true. False disables the platform root unless the other call supplies true. An ovrtx.portable file beside the executable or OVRTX binaries selects the application directory instead. A valid OVRTX_CONFIG_CACHE_ROOT_PATH takes precedence over both. Configure this option during the first initialization or renderer creation in the process. Changing the cache root within the same process is unsupported, including after ovrtx_shutdown().

enumerator OVRTX_CONFIG_ENABLE_DEBUG_VALIDATION#

Enable graphics API debug validation before creating shared graphics devices.

Create_renderer. Applies to Debug and Release builds. Omission preserves GPU Foundation’s default. Additional renderers inherit the existing mode. A conflicting explicit value logs a warning and creates the renderer with the existing mode. To change it, destroy all renderers and release OVRTX_CONFIG_KEEP_SYSTEM_ALIVE retention before creating new graphics devices. D3D12 validation disables NVIDIA Nsight Aftermath even when Aftermath is explicitly enabled.

enumerator OVRTX_CONFIG_ENABLE_HISTORY_PRESENTATION#

If true, an attached history-capable ovstage presents the retained values of the renderable history-enabled pairs when ovrtx_step_with_stage() names an ordinal below the write floor.

A history-capable ovstage is an instance of “history_selective”, created with that name in the implementation member of ovstage_instance_desc_t. History is on for the pairs that ovstage_enable_history() selects. The renderer restores the live values after the render. Pass to ovrtx_create_renderer(). Defaults to false: the renderer makes no history calls, and such a step fails with a reason that names this key. A default stage, an instance of “history_latest”, keeps history off and renders its latest values for every committed ordinal in both cases. Borrow mode with the Fabric stage provider only.

enumerator OVRTX_CONFIG_BOOL_COUNT#

enum ovrtx_config_string_t#

String config keys.

Value type: ovx_string_t. Used at init and create_renderer (must match).

Values:

enumerator OVRTX_CONFIG_BINARY_PACKAGE_ROOT_PATH#

Path to OVRTX binary package root.

Loader uses for dylib and resources. Init and create_renderer (must match).

enumerator OVRTX_CONFIG_LOG_FILE_PATH#

Log file path for carb logging.

Applied when first renderer is created. Init and create_renderer.

enumerator OVRTX_CONFIG_LOG_LEVEL#

Log level for carb logging (e.g.

“verbose”, “info”, “warn”, “error”). Init and create_renderer.

enumerator OVRTX_CONFIG_ACTIVE_CUDA_GPUS#

Comma-separated CUDA device indices to use (e.g.

“0,1,2”). Create_renderer.

enumerator OVRTX_CONFIG_DATASTORE_CACHE#

Protocol-prefixed datastore cache configuration used by UJITSO.

Supported values: “grpcdns://host:port”, “grpcdns_notls://host:port”, and “local://path”. System-level; init and create_renderer values must match when both are specified.

enumerator OVRTX_CONFIG_SENSORS_ALLOWED_DEPRECATION_BASE#

Allow all soft-deprecated sensor versions, but only while pinned to a specific framework release: “<major>.<minor>.<patch>”.

(e.g. “0.4.0”). Any other value (or unset) allows none.

enumerator OVRTX_CONFIG_CACHE_ROOT_PATH#

Override the process-wide ${omni_cache} token with a nonempty path that resolves to an absolute root.

Takes precedence over the platform default and an ovrtx.portable marker beside the executable or OVRTX binaries. System-level; paths supplied to init and create_renderer must match. Supply this path during the first initialization or renderer creation in the process. Changing it within the same process is unsupported, including after ovrtx_shutdown().

enumerator OVRTX_CONFIG_STRING_COUNT#

enum ovrtx_config_int64_t#

Int64 config keys.

Value type: int64_t. Used at create_renderer.

Values:

enumerator OVRTX_CONFIG_SELECTION_OUTLINE_WIDTH#

Selection outline width in pixels.

Valid range 0..15 (15 is the underlying RTX outline pipeline cap). Init-time only; changing requires renderer recreation. Default: 2 (set by the underlying renderer).

enumerator OVRTX_CONFIG_SELECTION_FILL_MODE#

Selection-outline interior (fill) mode.

Value type: ovrtx_selection_fill_mode_t. Out-of-range values are clamped by the renderer. Init-time only; changing requires renderer recreation. Default: OVRTX_SELECTION_FILL_MODE_GLOBAL.

enumerator OVRTX_CONFIG_MOTION_BVH#

Motion BVH mode.

Value type: ovrtx_motion_bvh_t. Per renderer instance. Init-time only; changing requires renderer recreation. When omitted, defaults to OVRTX_MOTION_BVH_DISABLE. Creating another renderer does not change this instance’s policy.

enumerator OVRTX_CONFIG_INT64_DEPRECATED_4#

Retired OVRTX_CONFIG_DOME_BAKING_RESOLUTION slot, replaced by the per-RenderProduct ‘omni:rtx:lights:dome:baking:resolution’ attribute.

Passing this key returns an error. It shipped as 4 in ovrtx 0.4.1, so do not reuse the value for a new key: a config array built against those headers would then be misread as that key instead of rejected.

enumerator OVRTX_CONFIG_TEXTURE_STREAMING_MODE#

Texture streaming mode.

Value type: ovrtx_texture_streaming_mode_t. Invalid values cause renderer creation to fail. When omitted, defaults to OVRTX_TEXTURE_STREAMING_ASYNCHRONOUS. Process-global; changing affects all active renderer instances.

enumerator OVRTX_CONFIG_AFTERMATH_MODE#

NVIDIA Nsight Aftermath mode.

Value type: ovrtx_aftermath_mode_t. OVRTX_AFTERMATH_DISABLE skips Aftermath initialization, OVRTX_AFTERMATH_ENABLE selects explicit diagnostics initialization, and omitted or OVRTX_AFTERMATH_AUTO selects the initialization mode automatically. This setting is process-global and must match the first renderer while the renderer system is alive.

enumerator OVRTX_CONFIG_INT64_COUNT#

enum ovrtx_config_uint64_t#

Uint64 config keys (reserved for future use).

Value type: uint64_t.

Values:

enumerator OVRTX_CONFIG_UINT64_COUNT#

enum ovrtx_config_double_t#

Double config keys (reserved for future use).

Value type: double.

Values:

enumerator OVRTX_CONFIG_DOUBLE_COUNT#

enum ovrtx_config_blob_t#

Blob config keys (reserved for future use).

Value type: ptr + size.

Values:

enumerator OVRTX_CONFIG_BLOB_COUNT#

typedef enum ovrtx_texture_streaming_mode_t ovrtx_texture_streaming_mode_t

Texture streaming mode.

Set via OVRTX_CONFIG_TEXTURE_STREAMING_MODE at renderer creation. The setting is process-global and applies to all active renderer instances.

typedef enum ovrtx_aftermath_mode_t ovrtx_aftermath_mode_t

NVIDIA Nsight Aftermath mode.

Set via OVRTX_CONFIG_AFTERMATH_MODE at renderer creation. This is process-global because Aftermath initialization is shared by active renderers.

typedef enum ovrtx_config_key_type_t ovrtx_config_key_type_t: Key type tag for ovrtx_config_entry_t; selects which key and value union members are valid.