nvidia-omniverse/ovrtx/update-0-3-0-4-c

Update 0.3 to 0.4 + ovstage 0.1 (C API)

Standalone ovrtx 0.3.x stage APIs -> ovrtx 0.4.x + ovstage 0.1.x attached mode, for user application code.

Version Scope

When to Use

Use this skill when the user asks to upgrade an existing C/C++ ovrtx application from 0.3.x to 0.4.x, where the same code must now feed the renderer through an attached ovstage instance. Typical prompts: "upgrade from 0.3 to 0.4 with ovstage", "ovrtx 0.4 ovstage 0.1 migration", "migrate my ovrtx app", "port my application to ovstage".

Do not use this skill for:

• 0.2 -> 0.3 (see `update-0_2-0_3`).
• Python migration — only the C API is covered here.

In scope for example work: porting or validating the public C examples minimal and status-queries (Recipe A — one-shot load + render). These are the canonical reference implementations for this skill.

Out of scope for example work: material-editor, vulkan-interop, lidar, radar, and Python examples — blocked on ovstage API gaps or sensor output (see Example Port Status below).

Inputs

Resolve inputs in this order:

• Target language: C or C++ (skill covers only the C API surface).
• Dependency manager and package pin (the app's CMakeLists.txt / ovrtx.cmake or equivalent must be able to add ovstage::ovstage_static).
• Which deprecated ovrtx entry points the app currently calls (see the mapping table below).
• Whether the app does one-shot scene loading (open a USD file once, then step) or incremental scene edits (references, resets, attribute writes, time samples).
• Whether the app uses picking, selection outlines, or the renderer's path dictionary — these stay on ovrtx and change independently.

Prerequisites

• Read `../update-0_3-0_4-common/Reference.md` for language-agnostic ownership, ordering, path-dictionary, transform, exposure, and async-boundary guidance.
• Read the CHANGELOG.md [0.4.0] section in `../../CHANGELOG.md` for release-level context, but if any bullet contradicts this skill or the current doxygen in ovrtx.h, trust the header and this skill. The definitive statements for the attach-mode update contract live at the top of the [0.4.0] ### Changed block.
• The app must be able to pull ovstage 0.1.x (a new dependency in 0.4). Confirm the CMake / package fetch step provides both ovrtx::ovrtx_static and ovstage::ovstage_static.
• Preserve user code structure. This is an API migration, not a refactor.

C API Notes After Reading The Common Reference

The common reference covers language-agnostic migration gotchas. This section only adds C API specifics for those topics.

Renderer-side APIs that stay on ovrtx

Keep renderer-side selection and picking calls on ovrtx:

• ovrtx_enqueue_pick_query and the OVRTX_RENDER_VAR_PICK_HIT render variable in `ovrtx.h`.
• ovrtx_set_selection_group_styles in `ovrtx.h`.
• ovrtx_set_selection_outline_group and ovrtx_set_pickable in `ovrtx_attributes.h`.

The `picking-selection` topic skill stays authoritative for the API shape; only the scene-ingest and step calls around it change.

Path dictionaries

• For ovstage queries and writes, use ovstage_get_path_dictionary(stage).
• For ovrtx outputs and functions that expose or consume ovrtx path IDs, use ovrtx_get_path_dictionary(renderer).

Transform and attribute helpers

The ovstage public include tree does not provide an equivalent ovstage_attributes.h. Convenience helpers in `ovrtx_attributes.h` - transform writers, ovrtx_set_path_attributes, ovrtx_set_token_attributes, ovrtx_set_selection_outline_group, and ovrtx_set_pickable - do not have drop-in ovstage counterparts. For ovstage writes, user code must:

1. Build a path list or query with ovstage_query / ovstage_query_from_path_list.
2. Intern any tokens with ovstage_get_path_dictionary.
3. Fill ovstage_write_data_t explicitly and call ovstage_write_attribute.

Ovstage transform writes use canonical omni:xform as a 2-D 4x4 `double` matrix with OVSTAGE_SEMANTIC_MATRIX (row-vector convention, translation in the last row; ndim=2, shape=[4,4], dtype={kDLFloat,64,1}, is_array=false). See the transform recipe in `ovstage examples/c/runtime-loop/main.cpp`. If the 0.3 app used ovrtx_set_reset_xform_stack, author omni:resetXformStack = true on the affected prims so the ovstage-side transforms are still interpreted as world-space.

Async wait APIs

Ovstage exposes two independent async models. Using the wrong waiter is a common porting bug.

Notes:

• ovstage_get_last_error() and ovstage_population_get_last_error() take no instance argument (parameterless). Do not pass stage — older drafts did and will not compile against current headers.
• ovrtx_query_op_status / ovrtx_wait_op apply only to ovrtx ops (e.g. ovrtx_step_with_stage). They do not report progress for ovstage population loads. The ported status-queries example polls status while waiting on render steps; USD open uses wait_population_op (blocking wait, no query_op_status).

What 0.4 Adds

From CHANGELOG.md [0.4.0]:

• Attach APIs. ovrtx_attach_ovstage, ovrtx_detach_ovstage, and ovrtx_step_with_stage(renderer, render_products, delta_time, ordinal, ...) in `ovrtx.h`. While attached, stage-building / write / map entry points return OVRTX_API_ERROR; read-only queries and rendering flow through the attached stage.
• State refresh. ovrtx_update_from_stage(renderer, ordinal) — required after incremental population / attribute changes (see Recipe B). It performs a Hydra rebuild after a wholesale ovstage_population_open_usd_*, but that rebuild also happens implicitly on the first ovrtx_step_with_stage, so it can be skipped for one-shot loads. Time-only updates (ovstage_population_apply_usd_time) are documented no-ops.
• Write-floor gates. ovrtx_step_with_stage and ovrtx_update_from_stage reject calls until ovstage_advance_write_floor has run at least once (write floor must be > 0), pointing users at ovstage_population_open_usd_* / ovstage_write_* + ovstage_advance_write_floor.
• Picking NDC. ovrtx_pick_query_desc_t now uses left_ndc / top_ndc / right_ndc / bottom_ndc instead of pixel fields.
• Read handle release. ovrtx_release_read_result(renderer, read_handle, cuda_sync) now takes the ovrtx_read_handle_t directly; the ovrtx_read_map_handle_t typedef and ovrtx_read_output_t::map_handle are removed.

The 0.3 deprecated entry points still compile in 0.4 — the compiler emits OVRTX_DEPRECATED warnings for each — but they should be replaced with the ovstage-based equivalents below.

For a phased migration, ovrtx_config_entry_suppress_deprecation_warnings(true) temporarily suppresses native runtime warnings. It does not suppress OVRTX_DEPRECATED compiler diagnostics, change deprecated behavior, or extend the API removal schedule.

Architecture

                    ┌────────────────────────────────────────┐
User app code       │  ovstage_instance_t  (owns scene data) │
────────────────────┤  ovstage_population_open_usd_*         │
                    │  ovstage_write_attribute               │
                    │  ovstage_advance_write_floor(ordinal)  │
                    └──────────────┬─────────────────────────┘
                                   │ ovrtx_attach_ovstage
                                   ▼
                    ┌────────────────────────────────────────┐
                    │  ovrtx_renderer_t  (owns rendering)    │
                    │  ovrtx_update_from_stage(ordinal)      │
                    │  ovrtx_step_with_stage(..., ordinal)   │
                    │  picking / selection / render outputs  │
                    └────────────────────────────────────────┘

Headers, CMake, and Runtime Setup

Headers

• Include both headers in user code: #include <ovrtx/ovrtx.h> and #include <ovstage/ovstage.h>. They coexist in the same translation unit via the shared OVX_SHARED_STRING_TYPES_DEFINED sentinel guard (see CHANGELOG.md [0.4.0]).
• <ovrtx/ovrtx.h> already pulls in <ovstage/ovstage_api/ovstage_api_types.h> internally for the attach types. Do not add a second explicit include of <ovstage/ovstage_api/ovstage_api_types.h> alongside <ovrtx/ovrtx.h> — the direct-include path redefines ovstage_instance_t incompatibly.
• <ovstage/ovstage.h> transitively includes <ovstage/ovstage_population.h> — no separate population include is required for ovstage_population_open_usd_from_file.

CMake and linking

Each library is an independent package with its own FetchContent / find_package target:

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/../cmake")
include(ovrtx)
include(ovstage)
ovrtx_fetch()
ovstage_fetch()
 
target_link_libraries(myapp PRIVATE ovrtx::ovrtx_static ovstage::ovstage_static)
ovrtx_setup_runtime(myapp)
ovstage_setup_runtime(myapp)

Source: `examples/c/minimal/CMakeLists.txt`, `examples/c/cmake/ovrtx.cmake`, `examples/c/cmake/ovstage.cmake`.

Copy ovstage.cmake from the examples tree — do not reduce it to "copy ovstage.dll next to the exe." The runtime setup is load-order sensitive.

Windows: ovstage.dll must not load at process init

Attach mode needs one shared USD runtime in-process. On Windows, ovstage.dll statically imports ov_25.11usd_ms.dll and tbb12.dll. If the OS loads ovstage.dll at process init (before ovrtx_create_renderer has loaded the single plugins/ov_25.11usd_ms.dll from ovrtx's package), you get a second USD module instance → split PlugRegistry / TfType state → crashes or subtle corruption.