# nvidia-rtx/rtxmg architecture

> Architecture diagram of the GitHub repository nvidia-rtx/rtxmg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia-rtx/rtxmg
- Repository: https://github.com/nvidia-rtx/rtxmg

## Overview

1. **Repository shape**
   - This is a C++/HLSL SDK-style repo with a **core RTX Mega Geometry library** under `rtxmg/` and a **reference demo application** under `demo/`.
   - The root `CMakeLists.txt` builds multiple targets, with shader compilation driven by `shaders.cfg` files in each feature area.

2. **Primary purpose**
   - The system demonstrates how to build **ray-tracing acceleration structures for subdivision surfaces** using **structured clusters**.
   - The runtime supports both **DirectX 12/DXR** and **Vulkan**, with NVIDIA-specific acceleration features: **NVAPI** for DXR and `VK_NV_cluster_acceleration_structure` on Vulkan.

3. **Core data path**
   - Scene content is loaded from files, parsed into the `rtxmg::scene` model layer, then converted into subdivision and cluster representations.
   - Those representations feed the **cluster acceleration builder**, which produces the BLAS/cluster data used by the ray-tracing demo shaders.
   - In the render loop, camera state, scene state, and per-frame parameters drive shader dispatches and ray tracing.

4. **Scene and asset ingestion**
   - `rtxmg/scene` contains the asset pipeline: OBJ import, JSON scene parsing, camera, and scene-model structures.
   - The demo consumes this layer via command-line selection of `.scene.json` or OBJ input, then routes the loaded scene into rendering and UI controls.

5. **Subdivision and topology subsystem**
   - `rtxmg/subdivision` is the geometric foundation: Catmull-Clark-style subdivision, topology caching/mapping, patch parameters, and surface evaluation.
   - This layer also includes HLSL-facing headers, indicating that subdivision evaluation is split between CPU-side planning and GPU-side evaluation.

6. **Cluster acceleration subsystem**
   - `rtxmg/cluster_builder` is responsible for creating the structured cluster representation used for ray tracing.
   - It includes GPU compute shaders and parameter headers for tasks such as cluster tiling, filling cluster data, instance descriptors, and building BLAS-from-CLAS inputs.
   - Conceptually, this is the bridge from subdivision surfaces to ray-tracing acceleration structures.

7. **Hi-Z / visibility subsystem**
   - `rtxmg/hiz` implements a hierarchical Z-buffer and related reduction/display passes.
   - The demo uses this as a visibility aid to reduce tessellation work for non-primary-ray geometry, so it is part of the adaptive rendering path rather than a standalone utility.

8. **Demo renderer boundary**
   - `demo/rtxmg_demo*`, `demo/rtxmg_renderer*`, `demo/render_targets*`, `demo/zrenderer*`, and `demo/blit_params.h` form the sample application’s rendering layer.
   - The demo includes a path-tracing shader, motion-vector generation, Z rendering, blit passes, and render-target management.
   - This layer is the main consumer of the core `rtxmg` library.

9. **User interaction and presentation**
   - `demo/gui*`, `demo/trackball*`, and `demo/args*` handle interactive control, camera manipulation, and runtime configuration.
   - `demo/envmap` provides environment-map preprocessing via compute shaders, which feeds lighting/background content for the renderer.
   - `demo/audio` is a separate sample support path for audio playback/loading, not central to the geometry pipeline.

10. **Profiling and diagnostics**
   - `rtxmg/profiler` provides timing/statistics/sampling utilities and a UI layer for inspecting performance.
   - `rtxmg/utils` contains lower-level support code such as buffers, formatting, debug helpers, CSV dumping, and shader-debug utilities.
   - These pieces are cross-cutting support used by both the core library and the demo.

11. **External dependencies and build-time integration**
   - `extern/` contains bundled third-party components, including `donut`, `osd_lite`, and NRD configuration.
   - CMake fetch scripts pull in DXC, ImPlot, and NVAPI as needed, so shader compilation and vendor-specific ray-tracing support are integral to the build.
   - The repo is Windows-focused, with build/run expectations centered on MSVC, Windows SDK, DX12 Agility SDK, and Vulkan SDK.

12. **Architectural boundary to capture in a diagram**
   - A useful diagram should show four main zones: **asset/scene ingestion**, **geometry/subdivision + cluster build**, **frame rendering/demo UI**, and **supporting utilities/profiling**.
   - The key flow is: **loaded scene → subdivision/topology processing → cluster acceleration build → ray-tracing/path-tracing shaders**, with **Hi-Z and camera/UI state** modulating the per-frame work.

Main entry points: [`demo/rtxmg_renderer.cpp`](https://github.com/nvidia-rtx/rtxmg/blob/main/demo/rtxmg_renderer.cpp) (Renderer), [`CMakeLists.txt`](https://github.com/nvidia-rtx/rtxmg/blob/main/CMakeLists.txt) (CMake build), [`rtxmg/cluster_builder`](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/cluster_builder) (Cluster build), [`rtxmg/subdivision`](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/subdivision) (Subdivision core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_scene_ingest["Scene ingest<br/>asset pipeline"]
  node_subdivision_core["Subdivision core<br/>geometry core"]
  node_cluster_builder["Cluster build<br/>rtx accel builder"]
  node_hiz_core["Hi-Z<br/>visibility buffer"]
  node_profiler_core["Profiler<br/>timing/ui"]
  node_utils_core["Utils<br/>support lib"]
end

subgraph group_demo["Demo app"]
  node_demo_app["Demo shell<br/>sample app<br/>[rtxmg_demo.cpp]"]
  node_demo_renderer["Renderer<br/>render backend<br/>[rtxmg_renderer.cpp]"]
  node_demo_targets["Targets<br/>frame resources<br/>[render_targets.cpp]"]
  node_demo_shaders["Ray shaders<br/>hlsl shaders"]
  node_demo_ui["UI & camera<br/>interaction<br/>[gui.cpp]"]
  node_envmap["Envmap prep<br/>compute preprocess"]
  node_audio["Audio<br/>sample support"]
end

subgraph group_build["Build/deps"]
  node_build_system["CMake build<br/>build orchestration<br/>[CMakeLists.txt]"]
  node_extern_deps["Bundled deps<br/>third-party"]
end

node_build_system -->|"builds"| node_scene_ingest
node_build_system -->|"builds"| node_subdivision_core
node_build_system -->|"builds"| node_cluster_builder
node_build_system -->|"builds"| node_hiz_core
node_build_system -->|"builds"| node_demo_app
node_build_system -->|"integrates"| node_extern_deps
node_scene_ingest -->|"feeds"| node_subdivision_core
node_subdivision_core -->|"produces"| node_cluster_builder
node_cluster_builder -->|"supplies"| node_demo_renderer
node_hiz_core -->|"guides"| node_demo_renderer
node_profiler_core -->|"measures"| node_demo_renderer
node_utils_core -->|"supports"| node_scene_ingest
node_utils_core -->|"supports"| node_subdivision_core
node_utils_core -->|"supports"| node_cluster_builder
node_demo_app -->|"orchestrates"| node_demo_renderer
node_demo_app -->|"controls"| node_demo_ui
node_demo_ui -->|"updates"| node_demo_renderer
node_demo_renderer -->|"uses"| node_demo_targets
node_demo_renderer -->|"dispatches"| node_demo_shaders
node_demo_renderer -->|"lights"| node_envmap
node_demo_renderer -.->|"optionally uses"| node_audio
node_extern_deps -->|"enables"| node_demo_renderer
node_extern_deps -->|"enables"| node_cluster_builder

click node_build_system "https://github.com/nvidia-rtx/rtxmg/blob/main/CMakeLists.txt"
click node_extern_deps "https://github.com/nvidia-rtx/rtxmg/tree/main/extern"
click node_scene_ingest "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/scene"
click node_subdivision_core "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/subdivision"
click node_cluster_builder "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/cluster_builder"
click node_hiz_core "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/hiz"
click node_profiler_core "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/profiler"
click node_utils_core "https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/utils"
click node_demo_app "https://github.com/nvidia-rtx/rtxmg/blob/main/demo/rtxmg_demo.cpp"
click node_demo_renderer "https://github.com/nvidia-rtx/rtxmg/blob/main/demo/rtxmg_renderer.cpp"
click node_demo_targets "https://github.com/nvidia-rtx/rtxmg/blob/main/demo/render_targets.cpp"
click node_demo_shaders "https://github.com/nvidia-rtx/rtxmg/tree/main/demo/shaders"
click node_demo_ui "https://github.com/nvidia-rtx/rtxmg/blob/main/demo/gui.cpp"
click node_envmap "https://github.com/nvidia-rtx/rtxmg/tree/main/demo/envmap"
click node_audio "https://github.com/nvidia-rtx/rtxmg/tree/main/demo/audio"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scene_ingest,node_subdivision_core,node_cluster_builder,node_hiz_core,node_profiler_core,node_utils_core toneBlue
class node_demo_app,node_demo_renderer,node_demo_targets,node_demo_shaders,node_demo_ui,node_envmap,node_audio toneAmber
class node_build_system,node_extern_deps toneMint
```

## Components

### Core library

Scene ingestion, subdivision, cluster building, Hi-Z, profiling, and shared utilities.

- [Scene ingest](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/scene): asset pipeline · OBJ import, JSON scene parsing, camera, and scene model structures. · `rtxmg/scene`
- [Subdivision core](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/subdivision): geometry core · Catmull-Clark-style subdivision, topology caching, patch parameters, and evaluation support. · `rtxmg/subdivision`
- [Cluster build](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/cluster_builder): rtx accel builder · Builds structured cluster data and BLAS/CLAS inputs for ray tracing. · `rtxmg/cluster_builder`
- [Hi-Z](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/hiz): visibility buffer · Hierarchical Z-buffer reduction and display passes used to guide adaptive work. · `rtxmg/hiz`
- [Profiler](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/profiler): timing/ui · Timing, statistics, sampling, and profiler UI support. · `rtxmg/profiler`
- [Utils](https://github.com/nvidia-rtx/rtxmg/tree/main/rtxmg/utils): support lib · Shared buffer, formatting, debug, CSV, and shader-debug helpers. · `rtxmg/utils`

### Demo app

Reference renderer, UI, render targets, and sample-side helpers.

- [Demo shell](https://github.com/nvidia-rtx/rtxmg/blob/main/demo/rtxmg_demo.cpp): sample app · Application entrypoints and orchestration for the reference demo. · `demo/rtxmg_demo.cpp`
- [Renderer](https://github.com/nvidia-rtx/rtxmg/blob/main/demo/rtxmg_renderer.cpp): render backend · Main sample rendering layer that drives ray tracing, passes, and frame assembly. · `demo/rtxmg_renderer.cpp`
- [Targets](https://github.com/nvidia-rtx/rtxmg/blob/main/demo/render_targets.cpp): frame resources · Render target allocation and frame resource management. · `demo/render_targets.cpp`
- [Ray shaders](https://github.com/nvidia-rtx/rtxmg/tree/main/demo/shaders): hlsl shaders · Path tracing, motion vectors, Z rendering, and blit shaders used by the demo. · `demo/shaders`
- [UI & camera](https://github.com/nvidia-rtx/rtxmg/blob/main/demo/gui.cpp): interaction · Args, GUI, trackball camera, and runtime controls for the sample. · `demo/gui.cpp`
- [Envmap prep](https://github.com/nvidia-rtx/rtxmg/tree/main/demo/envmap): compute preprocess · Environment-map preprocessing pipeline feeding lighting/background content. · `demo/envmap`
- [Audio](https://github.com/nvidia-rtx/rtxmg/tree/main/demo/audio): sample support · Optional audio loading and playback support for the demo. · `demo/audio`

### Build/deps

Top-level CMake integration and bundled third-party dependencies.

- [CMake build](https://github.com/nvidia-rtx/rtxmg/blob/main/CMakeLists.txt): build orchestration · Root and feature CMake files that wire targets and shader compilation. · `CMakeLists.txt`
- [Bundled deps](https://github.com/nvidia-rtx/rtxmg/tree/main/extern): third-party · Vendored and fetched external components used by the SDK and demo. · `extern`

## Connections

- CMake build → Scene ingest: builds · CMake config compiles the scene subsystem.
- CMake build → Subdivision core: builds · CMake config compiles the subdivision subsystem.
- CMake build → Cluster build: builds · CMake config compiles the cluster builder and shaders.
- CMake build → Hi-Z: builds · CMake config compiles the Hi-Z subsystem.
- CMake build → Demo shell: builds · CMake config builds the reference application.
- CMake build → Bundled deps: integrates · Top-level build wires bundled and fetched dependencies.
- Scene ingest → Subdivision core: feeds · Loaded scenes and models become subdivision-ready geometry.
- Subdivision core → Cluster build: produces · Subdivision topology and evaluation data feed cluster construction.
- Cluster build → Renderer: supplies · Built cluster/BLAS data is consumed by the renderer.
- Hi-Z → Renderer: guides · Hi-Z visibility data informs adaptive rendering work.
- Profiler → Renderer: measures · Timing and statistics are used during frame execution.
- Utils → Scene ingest: supports · Shared helpers are used by asset ingestion.
- Utils → Subdivision core: supports · Shared helpers are used by subdivision code.
- Utils → Cluster build: supports · Shared helpers are used by acceleration building.
- Demo shell → Renderer: orchestrates · Application entrypoints drive the renderer.
- Demo shell → UI & camera: controls · CLI and interaction layer configure runtime behavior.
- UI & camera → Renderer: updates · Camera and UI state drive frame parameters.
- Renderer → Targets: uses · Renderer reads and writes frame targets.
- Renderer → Ray shaders: dispatches · Renderer launches ray-tracing and compute passes.
- Renderer → Envmap prep: lights · Environment map preprocessing feeds lighting/background content.
- Renderer → Audio: optionally uses · Audio is a side-path sample feature.
- Bundled deps → Renderer: enables · Vendor SDKs and libraries enable the demo runtime.
- Bundled deps → Cluster build: enables · Vendor ray-tracing support enables cluster building.