/application-flow

# 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: application-flow
description: >
  High-level overview of a typical ovrtx application lifecycle. Use when user asks how
  to structure an ovrtx program, what the main steps are, or how the pieces fit
  together.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - workflow
  - lifecycle
tools:
  - Read
  - Grep

Application Flow

When to Use

Use this skill when the user asks how to structure an ovrtx program, what the main steps are, or how the pieces fit together.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, or both.
• Application lifecycle stage: renderer creation, scene loading, stepping, warmup, output readback, or cleanup.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant `> **Source:**` snippet before writing or explaining API usage.
• Validate ovrtx workflows only on a machine with an NVIDIA RTX-capable GPU, a supported NVIDIA driver listed in `docs/driver_requirements.rst`, and unsandboxed runtime execution.
• If NVIDIA driver detection fails, the driver is inaccessible, or the detected version is older than the relevant baseline in `docs/driver_requirements.rst`, rerun validation outside the sandbox. If the driver is still missing or incompatible, stop runtime validation and tell the user they need a supported NVIDIA driver.
• For the repository minimal examples, require internet access because the scene is loaded from S3.
• Python 3.10-3.13 are supported.
• For code changes, preserve renderer lifecycle ordering and cleanup semantics for the selected language.

Instructions

1. Identify the requested language and lifecycle stage before choosing an example. 2. Read the referenced snippet that matches the requested stage and language. 3. Preserve the normal ovrtx order: create or initialize the renderer, load or compose USD, step or wait for work, read outputs when needed, then release C resources explicitly. 4. Apply the async, status-query, error-handling, and warmup skills when the workflow crosses those concerns. 5. When changing code, run the narrow example or docs test that owns the snippet whenever practical.

Output Format

• For explanations, return an ordered lifecycle with the relevant follow-on skills.
• For code changes, summarize the lifecycle files touched and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Every ovrtx application follows the same core lifecycle, whether in Python or C. This skill gives the high-level sequence and points to the detailed skill for each step.

Runtime Verification

Run the minimal example first when validating an ovrtx environment:

| Path | Command | Success signal | |------|---------|----------------| | Python minimal | `cd examples/python/minimal && uv run main.py --png` | Writes `_output/render.png`; compare it to `img/example-minimal.jpg`. | | C minimal (Linux) | `cd examples/c/minimal && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ./build/static/minimal` | Writes `out.png`; compare it to `img/example-minimal.jpg`. | | C minimal (Windows) | `cd examples/c/minimal && cmake -B build && cmake --build build --config Release && .\build\static\Release\minimal.exe` | Writes `out.png`; compare it to `img/example-minimal.jpg`. |

Do not claim runtime validation from parse-only checks, docs-only checks, or execution on a host without a supported RTX GPU and driver.

Key Concepts

The USD stage contains three prim types that work together to produce rendered output:

• **Camera** (or sensor) prim -- defines the sensor itself: position, orientation, lens properties (focal length, aperture), exposure settings. This is a standard `UsdGeomCamera` prim in the scene hierarchy.
• **RenderProduct** prim -- the thing you actually point the renderer at. It ties together a Camera (via `rel camera`), an output resolution (`int2 resolution`), and a list of output variables (via `rel orderedVars`). When you call `step()`, you pass RenderProduct paths, not Camera paths.
• **RenderVar** prim -- declares a single output. Its full prim path identifies the output in step results; its `sourceName` (e.g., `LdrColor`, `HdrColor`, `DepthSD`) selects the renderer AOV.

/World/Camera          ← Camera prim (sensor definition)
/Render/Camera         ← RenderProduct prim (render configuration)
    /Render/Camera/LdrColor  ← RenderVar prim (output variable)
    /Render/Camera/HdrColor  ← RenderVar prim (output variable)

Key implications for agents:

• **`step()` takes RenderProduct paths**, not Camera paths. If you pass a Camera path, nothing will render.
• **Render settings** (e.g., `omni:rtx:rtpt:maxBounces`) are written as attributes on the **RenderProduct** prim, not on the Camera prim. See the `render-settings` skill.
• **Scene properties** (position, materials, visibility) are on scene prims under `/World`. **Render configuration** (resolution, outputs, render mode) is on RenderProduct prims, typically under `/Render`.
• A single Camera can be referenced by multiple RenderProducts with di