/update-0_3-0_4-c

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: update-0_3-0_4-c
description: >
  Upgrade skill: migrate user C/C++ application code from ovrtx 0.3.x standalone
  stage APIs to ovrtx 0.4.x attached to ovstage 0.1.x. Use when the user asks to
  "upgrade from 0.3 to 0.4 with ovstage", "ovrtx 0.4 ovstage 0.1 migration",
  "migrate my ovrtx app", or "port my application to ovstage". Reference
  implementations: `examples/c/minimal` and `examples/c/status-queries` (Recipe A).
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - upgrade
  - "0.4"
  - ovstage
  - c/c++

tools:
  - Read
  - Grep
  - Edit

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

| | Version | What changes | |---|---|---| | Source | ovrtx 0.3.x | Standalone stage ownership: `ovrtx_open_usd_*`, `ovrtx_write_attribute`, `ovrtx_query_prims`, `ovrtx_step` with the renderer-owned runtime stage | | Target ovrtx | ovrtx 0.4.x | Attach APIs (`ovrtx_attach_ovstage`, `ovrtx_update_from_stage`, `ovrtx_step_with_stage`); `OVRTX_DEPRECATED` markers on stage-building/query/write/read entry points in [`../../include/ovrtx/ovrtx.h`](../../include/ovrtx/ovrtx.h) | | New dependency | ovstage 0.1.x | Scene data plane (`<ovstage/ovstage.h>`), population bridge (`<ovstage/ovstage_population.h>`), ordinal-keyed writes |

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`](../../skills/update-0_2-0_3/SKILL.md)).
• 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`](../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`](../../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`](../../include/ovrtx/ovrtx.h).
• `ovrtx_set_selection_group_styles` in [`ovrtx.h`](../../include/ovrtx/ovrtx.h).
• `ovrtx_set_selection_outline_group` and `ovrtx_set_pickable` in [`ovrtx_attributes.h`](../../include/ovrtx/ovrtx_attributes.h).

The [`picking-selection`](../../skills/picking-selection/SKILL.md) 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`](../../include/ovrtx/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