How nvidia-rtx/rtxmg works
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: rtxmg_renderer.cpp Renderer · CMakeLists.txt CMake build · cluster_builder Cluster build · subdivision Subdivision core
Components 15
Core library
Scene ingestion, subdivision, cluster building, Hi-Z, profiling, and shared utilities.
- Scene ingest · OBJ import, JSON scene parsing, camera, and scene model structures.
rtxmg/scene - Subdivision core · Catmull-Clark-style subdivision, topology caching, patch parameters, and evaluation support.
rtxmg/subdivision - Cluster build · Builds structured cluster data and BLAS/CLAS inputs for ray tracing.
rtxmg/cluster_builder - Hi-Z · Hierarchical Z-buffer reduction and display passes used to guide adaptive work.
rtxmg/hiz - Profiler · Timing, statistics, sampling, and profiler UI support.
rtxmg/profiler - Utils · Shared buffer, formatting, debug, CSV, and shader-debug helpers.
rtxmg/utils
Demo app
Reference renderer, UI, render targets, and sample-side helpers.
- Demo shell · Application entrypoints and orchestration for the reference demo.
demo/rtxmg_demo.cpp - Renderer · Main sample rendering layer that drives ray tracing, passes, and frame assembly.
demo/rtxmg_renderer.cpp - Targets · Render target allocation and frame resource management.
demo/render_targets.cpp - Ray shaders · Path tracing, motion vectors, Z rendering, and blit shaders used by the demo.
demo/shaders - UI & camera · Args, GUI, trackball camera, and runtime controls for the sample.
demo/gui.cpp - Envmap prep · Environment-map preprocessing pipeline feeding lighting/background content.
demo/envmap - Audio · Optional audio loading and playback support for the demo.
demo/audio
Build/deps
Top-level CMake integration and bundled third-party dependencies.
- CMake build · Root and feature CMake files that wire targets and shader compilation.
CMakeLists.txt - Bundled deps · Vendored and fetched external components used by the SDK and demo.
extern
Connections 23
- 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.