C API Reference#

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

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.

Known Limitations#

In the current version, if you wish to use OpenUSD in the same process as ovrtx, you must use the same version of OpenUSD as the one used to build ovrtx. This means that you must use OpenUSD v25.11, built as non-monolithic libraries with Python support enabled (the default). You must also use oneTBB v2021.13.0 or later when building OpenUSD.

Functions#

Creation and Destruction#

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

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

    • ”binary_package_root_path” (STRING): path to the OVRTX binary package root directory.

    • ”sync_mode” (BOOL): if true, stream operations execute synchronously (enqueue blocks).

    • ”enable_profiling” (BOOL): if true, enables internal profiling.

    • ”read_gpu_transforms” (BOOL): if true, uses GPU world transform propagation during rendering.

    • ”log_file_path” (STRING): log file path for carb logging. The crash dump directory is automatically set to the same directory as the log file.

    • ”log_level” (STRING): log level string for carb logging (e.g., “verbose”, “info”, “warn”, “error”).

  • 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_add_usd(
ovrtx_renderer_t *instance,
ovrtx_usd_input_t usd_input,
ovx_string_t path_prefix,
ovrtx_usd_handle_t *out_add_usd_handle,
)#

Enqueue an asynchronous operation to add a USD file to the runtime stage representation.

Exactly one of the fields in the ovrtx_usd_input_t must be set.

ovrtx_add_usd() will add the given USD input as a reference at the given path prefix. An empty path prefix will instead result in the USD file being added as a sublayer.

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

  • usd_input – Input to add a USD file to the runtime stage representation

  • path_prefix – Prefix path that will be added to all paths in the USD file. This is useful when adding multiple USD files, so that the prims in each USD file have unique, known paths. If a combined prefix path and prim path inside the loaded usd file already exists an error will be returned and the usd file will not be added.

  • out_add_usd_handle – [out] Handle to the added usd file to be used with ovrtx_remove_usd().

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_remove_usd(
ovrtx_renderer_t *instance,
ovrtx_usd_handle_t add_usd_handle,
)#

Enqueue an asynchronous operation to remove a prior added usd file from the runtime stage representation.

All prims added to the stage during ovrtx_add_usd() will be removed from the stage.

Parameters:

  • instance – Renderer instance

  • add_usd_handle – Handle obtained from add_usd to identify the usd file to remove

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

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.

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_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_rendered_output(
ovrtx_renderer_t *instance,
ovrtx_rendered_output_handle_t output_handle,
const ovrtx_map_output_description_t *map_output_desc,
ovrtx_timeout_t timeout,
ovrtx_rendered_output_t *out_rendered_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.

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_rendered_output – [out] Rendered output

Returns:

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

ovrtx_result_t ovrtx_unmap_rendered_output(
ovrtx_renderer_t *instance,
ovrtx_rendered_output_map_handle_t map_handle,
ovrtx_cuda_sync_t before_destroy_cuda_sync,
)#

Unmaps the rendered output and frees resources associated with the prior map_rendered_output.

When this is called all access to the buffer provided by map_rendered_output must be done. This call determines the lifetime of the resources made accessible through the prior map_rendered_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 map_rendered_output.

Those are only released through unmap_rendered_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 list of still-active op ids. All error strings returned by this operation must be released by calling ovrtx_release_errors.

Parameters:

  • instance – Renderer instance

  • op_id – Operation id to wait for

  • time_out – Timeout for the operation

  • out_wait_result – [out] Wait result information (errors and active operation ids)

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.

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 (or any call that might perform a fiber switch) 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 (or any call that might perform a fiber switch) on the same thread.

Parameters:

op_id – Operation id to get the error string for

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

Handle to a rendered output.

typedef uint64_t ovrtx_rendered_output_map_handle_t#

Handle to the mapping of a rendered output that can be used to unmap it.

typedef uint64_t ovrtx_op_id_t#

Identifier of a particular asynchronous operation such as ovrtx_add_usd() 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 aynschronous function call.

The immediate status of the call can be checked with the ovrtx_enqueue_result_t::status field, and ovrtx_enqueue_result_t::op_index can be used to poll or wait on the completion of the asynchronous work.

Public Members

ovrtx_api_status_t status#

Status of the call.

ovrtx_op_id_t op_index#

Operation identifier that can be used to poll or wait on the completion of the enqueued work.

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#

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

User Task Types#

Warning

doxygengroup: Cannot find group “ovrtx_user_task_types” in doxygen xml output for project “ovrtx” from directory: _doxygen/xml

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 usage of a given attribute type.

For example, an attribute with 3-float elements could be interpreted as a vector or as an RGB color. This enum differentiates between them.

Values:

enumerator OVRTX_SEMANTIC_NONE#
enumerator OVRTX_SEMANTIC_TRANSFORM_4x4#

Transform of a prim expressed as column-major 4x4 matrix of double (kDLFloat, 64, 16)

enumerator OVRTX_SEMANTIC_TRANSFORM_POS3d_ROT4f_SCALE3f#

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

enumerator OVRTX_SEMANTIC_TRANSFORM_POS3d_ROT3x3f#

Transform of a prim expressed as 3xdouble position, 3x3float 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_COLOR_RGBA4b#

A color expressed as 4 bytes (kDLUInt, 8, 4)

enumerator OVRTX_SEMANTIC_COLOR_RGB3f#

A color expressed as 3 floats (kDLFloat, 32, 3)

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 usage of a given attribute type.

For example, an attribute with 3-float elements could be interpreted as a vector or as an RGB color. This enum differentiates between them.

typedef enum ovrtx_binding_flag_t ovrtx_binding_flag_t

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

typedef struct ovrtx_usd_input_t ovrtx_usd_input_t#

Represents a USD stage or layer to be used as input to ovrtx_add_usd()

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_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_usd_input_t
#include <ovrtx_types.h>

Represents a USD stage or layer to be used as input to ovrtx_add_usd()

Public Members

ovx_string_t usd_file_path#

Path to the USD file to add.

uint64_t usd_stage_id#

Stage ID of a USD runtime stage to add.

ovx_string_t usd_layer_content#

Usda content of the layer to add.

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_output_buffer_t#
#include <ovrtx_types.h>

Output DLTensor generated for a particular frame, product and var.

Public Members

DLTensor dl#

Zero-copy tensor (required)

ovrtx_cuda_sync_t cuda_sync#

Optional CUDA synchronization hints associated with this buffer.

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.

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#
enum ovrtx_renderer_config_value_type_t#

Type of a value contained in ovrtx_renderer_config_value_t.

Values:

enumerator OVRTX_CONFIG_VALUE_BOOL#
enumerator OVRTX_CONFIG_VALUE_INT64#
enumerator OVRTX_CONFIG_VALUE_UINT64#
enumerator OVRTX_CONFIG_VALUE_DOUBLE#
enumerator OVRTX_CONFIG_VALUE_STRING#
enumerator OVRTX_CONFIG_VALUE_BLOB#
typedef struct ovrtx_render_product_set_t ovrtx_render_product_set_t#

Set of RenderProducts that will be stepped.

typedef enum ovrtx_renderer_config_value_type_t ovrtx_renderer_config_value_type_t

Type of a value contained in ovrtx_renderer_config_value_t.

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

ovrtx_timeout_t constant for infinity (i.e.

block indefinitely)

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

Public Members

ovrtx_map_device_type_t device_type#

Device type of the output.

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_rendered_output_t#
#include <ovrtx_types.h>

The output of a particular RenderVar for a particular RenderProduct on a particular frame.

Public Members

ovrtx_event_status_t status#

Current operation status.

ovx_string_t error_message#

Error description if failed, NULL if succeeded.

ovrtx_rendered_output_map_handle_t map_handle#

Handle to use for unmap.

ovx_string_t name#

Name of the output (e.g., “rgb”, “depth”)

ovrtx_output_buffer_t buffer#

Buffer containing the rendered data.

struct ovrtx_renderer_config_value_t#
#include <ovrtx_types.h>

A value to be passed as an entry in the ovrtx_config_t configuration dictionary.

Public Members

ovrtx_renderer_config_value_type_t type#
bool bool_value#
int64_t int_value#
uint64_t uint_value#
double double_value#
ovx_string_t string_value#
const void *data#
size_t size#
struct ovrtx_renderer_config_value_t blob_value#
union ovrtx_renderer_config_value_t
struct ovrtx_renderer_config_entry_t#
#include <ovrtx_types.h>

An key/value entry in the ovrtx_config_t configuration dictionary.

Public Members

ovx_string_t key#
ovrtx_renderer_config_value_t value#
struct ovrtx_config_t#
#include <ovrtx_types.h>

A dictionary of key/value pairs that can be passed to ovrtx_initialize() or ovrtx_create_renderer().

Public Members

const ovrtx_renderer_config_entry_t *entries#
size_t entry_count#
On this page