/spg

# 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: spg
description: >
  Sensor Processing Graphs: run your own GPU code as a pass over RTX render outputs.
  Covers the three-file node contract in CUDA and Slang, wiring a graph in USD, built-in
  nodes, cross-frame state, sensor composites, ray generation, scene queries and
  diagnosis. Use when the user asks to add SPG to a scene, write or debug an SPG node or
  launch script, work with `.cu.lua` or `.slang.lua`, author `info:spg:sourceAsset`,
  `omni:rtx:aov`, `orderedVars` or a `spg:` built-in node, post-process an AOV on the GPU,
  read a lidar or radar point cloud in a kernel, trace the scene from a node, or work out
  why an SPG output is empty or black.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - spg
  - cuda
  - slang
  - usd
tools:
  - Read
  - Grep
  - Shell
  - Edit
  - Write

Sensor Processing Graphs

When to Use

Any task where the user's own GPU code has to run inside the renderer, over the images or sensor data the renderer produces. Trigger vocabulary: SPG, `.cu.lua`, `.slang.lua`, `info:spg:sourceAsset`, `subIdentifier`, `omni:rtx:aov`, `orderedVars`, `cuda.kernel`, `slang.dispatch`, `spg:rtx.spg.stdlib/...`, "post-process the AOV", "custom kernel on the render output", "my SPG AOV is black". Not this skill: reading a finished AOV back on the host, which is `reading-render-output`.

Task → Sections

Read **The Model**, **Instructions** and **The Traps** for any task. Then only what the row names.

| The user asks for | Also read | |---|---| | A new node that transforms an AOV | The Three Files, Choosing a Backend, Values, Resources, Launch Geometry | | Wiring an existing node into a scene | Wiring the Graph | | A common operation with no code | Built-In Nodes | | A node that remembers a previous frame | Cross-Frame State | | Data built in Lua on the GPU | Uploading Data | | Retuning a value without reloading | Runtime Changes | | Lidar or radar point cloud input | Sensor Composites | | A node that traces the scene | Ray Generation | | Pre-compiled `.ptx` / `.slang-module` / `.spv` | Pre-Compiled Sources | | A node that reads its camera, a prim of the scene, or its product | Scene Queries | | An output that is empty, black or wrong | Troubleshooting |

Prerequisites

• ovrtx 0.4 or later. SPG is enabled by default.
• The user can already render: a stage, a RenderProduct with a camera, and a step loop.
• Slang nodes need the renderer on Vulkan, which is the ovrtx default on Linux and Windows.
• Proficiency with CUDA kernels or Slang/HLSL compute shaders, and with USD authoring, is

assumed. This skill maps those onto SPG rather than teaching them.

Inputs

The user's scene file, their kernel if they have one, and which backend they want. If they have not said, choose by what the node needs: **Choosing a Backend**.

**Every `examples/` and `docs/` path below is relative to the ovrtx public root**: `rendering/ovrtx/public/` in the kit repository, the package root in an installed ovrtx.

Precedence when facts conflict: the code under `examples/python/spg-*` first, then the pages under `docs/spg/`, then this skill. Every code reference below names a snippet marker in a runnable example, a pair of comments `// [snippet:name]` and `// [/snippet:name]` (`--` in `.lua`, `#` in `.py` and `.usda`). Read the file between the markers rather than relying on memory; this skill is not the source of truth for API shape. Conventions in `skills/README.md`.

The Model

SPG runs a directed graph of GPU nodes inside the renderer's frame, over its Arbitrary Output Variables (AOVs). Everything stays on the GPU.

**A node is three files that share a name**: the GPU code, `Kernel.cu` or `Kernel.slang`; the launch script beside it, `Kernel.cu.lua` or `Kernel.slang.lua`, which validates inputs, describes outputs and returns the launch configuration; and the USD shader definition, `Kernel.usda`, which declares the ports and points at the GPU source.

Three facts drive most mistakes:

1. **The launch script is found by appending `.lua` to the source asset path**, and cannot be redirected. `GrayscaleKernel.cu` pairs with `GrayscaleKernel.cu.lua`. 2. **The launch script runs once per rendered frame**, on the CPU, before the GPU work, and sees resource *descriptors* — shape, dtype, rank — never pixel or point *data*. 3. **Execution is driven backwards from what is asked for.** A node whose output nothing consumes and which publishes no RenderVar never runs at all.

Instructions

1. **Decide built-in or custom.** If a stdlib node covers the operation, author only a USD Shader prim and write no code: **Built-In Nodes**. Do not invent node IDs. 2. **Write the GPU code**, one entry point, named the same in all three files and `extern "C"` on CUDA so the symbol survives. 3. **Write the launch script**, one global Lua function of that name taking `(inputs, outputs)`, assigning a descriptor to every declared output and returning a launch configuration. 4. **Write the shader definition**: `info:implementationSource = "sourceAsset"`, `info:spg:sourceAsset` at the GPU file, `subIdentifier` naming the entry point, and one `opaque inputs:`/`outputs:` port per resource. Details in **The Three Files**. 5. **Wire it into the scene**: **Wiring the Graph**. 6. **Verify by content, not by exit code.** A node that never ran leaves an AOV of zeros, so a clean run proves nothing. Assert som