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 #

All operations return a status code indicating success or failure:

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

Creation and Destruction #

ovrtx_result_t ovrtx_register_schema_paths( const ovrtx_config_t *config, )#

Register ovrtx’s USD schema and plugin discovery paths with the process’s USD plugin search 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 is populated only once for the process, so every subsystem that contributes schema/plugin paths must have published them before the registry is first consulted (typically when the first stage is opened). Each subsystem calls its own equivalent (e.g. ovphysx_prepare_usd_plugins(), ovrtx_register_schema_paths(...)) before any of them initialize, 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 directory of the loaded ovrtx loader library (default).

Notes:

Safe to call before ovrtx_initialize() and before ovrtx_create_renderer().
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).
Calling this after USD has already been loaded and the schema registry populated has no retroactive effect on previously-discovered schemas.
This function does not allocate the ovrtx system; it only adjusts process-global environment used by USD’s plugin discovery.

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.)

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.

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_destroy_renderer(ovrtx_renderer_t *renderer)#

Destroy a renderer instance.

Parameters:

renderer – Renderer instance to destroy

Returns:

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

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()

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. The target paths must not already exist in the stage.

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 path was cloned successfully,
OVRTX_API_ERROR if the path cloning failed.

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.

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.
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.
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
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.

Parameters:

instance – Renderer instance
binding_handle – Handle to the attribute binding to destroy

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
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 scalar attributes the result contains a single tensor of shape [prim_count]. For array attributes the result contains one tensor per prim with variable length. Multi-component C attribute tensors encode component count in DLTensor::dtype.lanes: for example, a point3f[] array with 10 points is shape [10] with lanes=3, and a 4x4 double matrix attribute for N prims is shape [N] with lanes=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.

Parameters:

instance – Renderer instance
read_handle – Handle obtained from ovrtx_read_attribute()
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_map_handle_t map_handle, ovrtx_cuda_sync_t before_destroy_cuda_sync, )#

Release resources from a prior ovrtx_fetch_read_result().

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

Parameters:

instance – Renderer instance
map_handle – Handle from ovrtx_read_output_t::map_handle
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()
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()

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 – Time step to simulate
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.

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

Enqueue a 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; resolve strings via ovrtx_get_path_dictionary() if needed. If multiple queries are enqueued for the same RenderProduct before a step, the last one wins.

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 and fill color) for one or more selection groups.

Group ids are uint8 (0..255) and match the value written to a prim’s omni:selectionOutlineGroup attribute (see OVRTX_ATTR_NAME_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.

Global state (outline thickness, fill mode) is configured via OVRTX_CONFIG_SELECTION_OUTLINE_WIDTH and OVRTX_CONFIG_SELECTION_FILL_MODE at renderer creation time.

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 – Time to reset the simulation to

Returns:

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

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. 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
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
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.
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().

Parameters:

instance – Renderer instance
result_handle – Handle to the step result to destroy

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_HANDLE is not waitable
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)
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 internal extension interface by name.

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 the extension is unavailable or if the system is not initialized yet.

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.

Parameters:

op_id – Operation id to get the error string for

ovrtx_result_t ovrtx_set_log_callback( ovrtx_log_severity_t severity, const ovx_string_t *channel_filter, ovrtx_log_callback_t callback, void *user_data, )#

Set a process-global callback that receives every carb log message produced by ovrtx (and by any plugin or framework code loaded under it).

The callback is shared across the whole ovrtx process, not per-renderer: its lifetime is tied to ovrtx_initialize / ovrtx_shutdown, not to any particular renderer instance. As a result the callback receives messages emitted before the first ovrtx_create_renderer (framework startup, plugin loading, the OVRTX logging banner) as well as messages emitted during and after ovrtx_destroy_renderer (e.g. asset eviction during teardown).

Only one callback can be active at a time; calling this function replaces the previous callback. Pass NULL as callback to disable delivery.

Calling this function before ovrtx_initialize or after ovrtx_shutdown returns OVRTX_API_ERROR with a descriptive error string accessible via ovrtx_get_last_error().

The callback does NOT carry per-renderer attribution. ovrtx may add a v2 callback type with (renderer, op_id) once per-op TLS plumbing exists.

Thread safety: The callback may be invoked from any thread. The implementation guarantees that callbacks are serialized for the process (no concurrent invocations).

ovrtx_result_t ovrtx_flush_log(ovrtx_timeout_t timeout)#

Flush all pending log messages through the global callback.

This operation blocks until all log messages generated up to this point have been delivered through the log callback. This is useful when you need to ensure all logs have been processed before proceeding (e.g., after an operation completes or fails, or before tearing the system down).

If no log callback is set, this function returns immediately with success.

Calling this function before ovrtx_initialize or after ovrtx_shutdown returns OVRTX_API_ERROR.

Note: This only flushes messages generated before this call. Messages generated concurrently or after this call may not be included.

Parameters:

timeout – Maximum time to wait for flush to complete

Returns:

OVRTX_API_SUCCESS if all pending logs were flushed, OVRTX_API_TIMEOUT if flush did not complete within timeout, OVRTX_API_ERROR if flush failed (system not initialized)

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.

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_keep_system_alive( bool keep_system_alive, )#

Keep the renderer system alive after all instances are destroyed.

When enabled, 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 (default), the system is destroyed when the last renderer instance is destroyed.

static inline ovrtx_config_entry_t ovrtx_config_entry_use_vulkan( bool use_vulkan, )#

Select graphics API.

When true, the renderer uses Vulkan. When false, it uses DX12 (Windows only). If this entry is not provided, the platform default is used (DX12 on Windows, Vulkan on Linux).

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.

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 (experimental).

Known issue: do not enable SPG with content that uses MaterialX material graphs.

static inline ovrtx_config_entry_t ovrtx_config_entry_enable_motion_bvh( bool enable_motion_bvh, )#

Enable motion BVH for sensor pipelines.

When enabled, the renderer builds motion acceleration structures required by non-visual sensor render products (lidar, radar, acoustic). Must be set before the first ovrtx_create_renderer call; changing the value requires recreating the renderer.

When not provided, defaults to false.

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”).

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. 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_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. When disabled (default), 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 selection outline width in pixels.

Init-time only; changing requires renderer recreation. Valid range is 0..15 (the underlying RTX outline pipeline cap). Out-of-range values are clamped by the renderer.

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#

Handle Types #

typedef uint64_t ovrtx_usd_handle_t#: Handle representing a USD stage.

typedef uint64_t ovrtx_event_handle_t#: Handle representing an event.

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

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

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

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

typedef uint64_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 uint64_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#

Sentinel value representing an invalid/null ovrtx handle.

Valid handles non-zero, so 0 is reserved to indicate “no handle” or “invalid handle”. Zero initialization of structures containing handles is valid API usage to indicate that no valid handle is provided.

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 OVRTX_INVALID_HANDLE 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, OVRTX_INVALID_HANDLE 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>

Represents a CUDA event to wait for on a particular stream.

Public Members

uintptr_t stream#

Cuda stream to synchronize to.

0 = no synchronization. 1 = default cuda stream, >1 specific 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 attributes whose Fabric base type is Token. Resolve to a string via the path dictionary.

enumerator OVRTX_SEMANTIC_PATH_ID#

Raw path identifier (kDLUInt, 64, 1).

Returned by query for attributes whose Fabric base type is Path. Resolve to a string via the path dictionary.

enumerator OVRTX_SEMANTIC_TAG#

Name-only attribute with no value or storage.

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

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_string_or_token_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. 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) and shape encodes scalar vs. array (e.g. {1} for scalar, {N} for array, {4,4} for a matrix). 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.

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 uint64_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_filter_t

#include <ovrtx_types.h>

Public Members

ovrtx_filter_kind_t kind#: What property to match.

ovx_string_or_token_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_string_or_token_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 uint64_t ovrtx_read_handle_t#: Handle to the result of a ovrtx_read_attribute() operation.

typedef uint64_t ovrtx_read_map_handle_t#: Handle to a fetched read result that can be released.

typedef struct ovrtx_read_output_t ovrtx_read_output_t#

Attribute read output retrieved via ovrtx_fetch_read_result().

For scalar attributes ovrtx_read_output_t::buffer_count is 1 and the single tensor has 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. Multi-component C attribute tensors encode component count in DLTensor::dtype.lanes.

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_output_t

#include <ovrtx_types.h>

Attribute read output retrieved via ovrtx_fetch_read_result().

For scalar attributes ovrtx_read_output_t::buffer_count is 1 and the single tensor has 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. Multi-component C attribute tensors encode component count in DLTensor::dtype.lanes.

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_read_map_handle_t map_handle#: Handle to use with ovrtx_release_read_result()

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.

OVRTX_ATTR_NAME_SELECTION_OUTLINE_GROUP#

OVRTX_ATTR_NAME_PICKABLE#

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>

Name an associated handle of a particular RenderVar’s output in a RenderProduct output.

Public Members

ovx_string_t render_var_name#: Name of the associated render var.

ovrtx_render_var_output_handle_t output_handle#: Handle to the rendered output.

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.

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_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().

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#: Single sync covering all tensors.

ovx_string_t name#: Render variable name (e.g., “PointCloud”, “HdrColor”)

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 RenderProduct pixel coordinates (inclusive left/top, exclusive right/bottom).

OVRTX_PICK_FLAG_GIZMO#

OVRTX_PICK_FLAG_INCLUDE_TRACKED_INFO#

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 RenderProduct pixel coordinates (inclusive left/top, exclusive right/bottom).

Public Members

ovx_string_t render_product_path#

int32_t left#

int32_t top#

int32_t right#

int32_t bottom#

uint32_t flags#

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).

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 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).

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 ovrtx_log_severity_t#

Log severity levels for operation messages.

Values:

enumerator OVRTX_LOG_INFO#: Informational message.

enumerator OVRTX_LOG_WARNING#: Warning (operation continues)

enumerator OVRTX_LOG_ERROR#: Error (operation may have failed)

enumerator OVRTX_LOG_FATAL#: Fatal error (operation may have failed)

typedef enum ovrtx_log_severity_t ovrtx_log_severity_t: Log severity levels for operation messages.

typedef void (*ovrtx_log_callback_t)(ovrtx_log_severity_t severity, double timestamp, ovx_string_t message, void *user_data)#

Callback function type for receiving log messages.

The callback is process-global (see ovrtx_set_log_callback) and may be invoked from any thread. The implementation serializes invocations so the callback body itself does not need its own mutex, but it must still be thread-safe with respect to whatever data it touches outside.

The message string is only valid for the duration of the callback. If the message needs to be retained, copy it before returning.

Param severity:: Severity level of the message
Param timestamp:: Wall-clock time in seconds since the epoch
Param message:: Log message text (valid only during callback)
Param user_data:: User-provided context from ovrtx_set_log_callback

Configuration Types #

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_USE_VULKAN#

If true, uses Vulkan; if false, uses DX12 (Windows only).

Create_renderer. When not specified, defaults to platform default (DX12 on Windows, Vulkan on Linux).

enumerator OVRTX_CONFIG_SELECTION_OUTLINE_ENABLED#

If true, enables the selection outline postprocessing pass.

Create_renderer. When not specified, defaults to false.

enumerator OVRTX_CONFIG_ENABLE_GEOMETRY_STREAMING#

API key for the geometry streaming opt-in flag.

Create_renderer.

enumerator OVRTX_CONFIG_ENABLE_GEOMETRY_STREAMING_LOD#

API key for the geometry streaming LOD opt-in flag.

Create_renderer.

enumerator OVRTX_CONFIG_ENABLE_SPG#

Experimental: if true, enable Sensor Processing Graphs (SPG), default: disabled.

This is a global setting, applying to all active renderer instances. Known issue: do not enable SPG with content that uses MaterialX material graphs

enumerator OVRTX_CONFIG_ENABLE_MOTION_BVH#

If true, enables motion BVH (ray-traced motion blur) for sensor pipelines.

Required when rendering non-visual sensor render products (lidar, radar, acoustic). When not specified, defaults to false.

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_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_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_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.