Update to v2.3.0

.gitmodules

@@ -1,5 +1,5 @@
 [submodule "donut"]
-	path = donut
+	path = external/donut
 	url = https://github.com/NVIDIAGameWorks/donut.git
 	branch = main
 [submodule "external/RayTracingDenoiser"]

CHANGELOG.md

@@ -1,5 +1,35 @@
 # RTXGI SDK Change Log
 
+## 2.3.0
+
+### RTXGI
+- Project structure change: the Donut framework is now located inside `/external` and no longer resides directly in the repo root.
+- Update NRD and Donut dependencies.
+- Removal of obsolete function definitions from `/samples/pathtracer/pathtracer.hlsl`.
+- Minor refactor to improve consistency and readability.
+- Minor documentation updates for `/docs/QuickStart.md` to reflect recent UI changes.
+- UI restructure for the path tracer sample project to intuitively group settings.
+
+### SHaRC
+- Update to version 1.4.3.0.
+- Split SHaRC parameters to SharcParameters and SharcState which is used only during the update stage.
+- API naming changes to account for `Sharc` and `HashGrid` prefixes to avoid collisions. Most of tweakable `#defines` can now be overridden outside of the main source files.
+- Added extra dynamic parameters to give move control with multiple SHaRC instances.
+- Moved GLSL code snippets to a separate file.
+- Addition of an optional anti-firefly filter.
+- Minor bug fixes with maximum number of accumulated frames.
+
+### NRC
+- Update to version 0.13.2.0.
+- API modification to support loading of custom paths for dependent DLLs.
+- API modification to enable network config file hot-reloading.
+- Bugfix for Vulkan memory type checking.
+- Bugfix type definition for `NrcPackableFloat` when using 16-bit packing.
+- Bugfix for stub functions in `Nrc.hlsli`.
+- Expose the ability to configure the number of training iterations.
+- Refactor and removal of deprecated or obsolete options.
+- Update documentation to reflect recent changes.
+
 ## 2.2.0
 
 ### RTXGI

CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright (c) 2020-2024, NVIDIA CORPORATION.  All rights reserved.
+# Copyright (c) 2023-2025, NVIDIA CORPORATION.  All rights reserved.
 #
 # NVIDIA CORPORATION and its licensors retain all intellectual property
 # and proprietary rights in and to this software, related documentation
@@ -33,7 +33,7 @@ set(CMAKE_COMPILE_WARNING_AS_ERROR ON)
 
 # Helper to download and unzip a package from a URL
 # Uses a zero-length file to identify the version of the package
-function(CheckAndDownloadPackage NAME VERSION LOCAL_PATH URL)
+function(CheckAndDownloadPackage NAME VERSION LOCAL_PATH URL ARCHIVE_TYPE)
     # Do we already have the correct version?
     if(NOT EXISTS ${LOCAL_PATH}/${VERSION}.ver)
         # Was there a previous version that we need to delete?
@@ -42,17 +42,17 @@ function(CheckAndDownloadPackage NAME VERSION LOCAL_PATH URL)
             file(REMOVE_RECURSE ${LOCAL_PATH})
         endif()
         message(STATUS "Obtaining " ${NAME} " " ${VERSION})
-        file(DOWNLOAD ${URL} ${LOCAL_PATH}.zip)
+        file(DOWNLOAD ${URL} ${LOCAL_PATH}.${ARCHIVE_TYPE})
         message(STATUS "Extracting " ${NAME})
-        file(ARCHIVE_EXTRACT INPUT ${LOCAL_PATH}.zip DESTINATION ${LOCAL_PATH})
-        file(REMOVE ${LOCAL_PATH}.zip)
+        file(ARCHIVE_EXTRACT INPUT ${LOCAL_PATH}.${ARCHIVE_TYPE} DESTINATION ${LOCAL_PATH})
+        file(REMOVE ${LOCAL_PATH}.${ARCHIVE_TYPE})
         # Create an empty file so we know which version we have
         file(WRITE ${LOCAL_PATH}/${VERSION}.ver)
     endif()
 endfunction()
 
-CheckAndDownloadPackage("Agility SDK" "v1.610.4" ${CMAKE_CURRENT_SOURCE_DIR}/external/AgilitySDK https://www.nuget.org/api/v2/package/Microsoft.Direct3D.D3D12/1.610.4)
-CheckAndDownloadPackage("DXC" "v1.7.2308" ${CMAKE_CURRENT_SOURCE_DIR}/external/dxc https://github.com/microsoft/DirectXShaderCompiler/releases/download/v1.7.2308/dxc_2023_08_14.zip)
+CheckAndDownloadPackage("Agility SDK" "v1.610.4" ${CMAKE_CURRENT_SOURCE_DIR}/external/AgilitySDK https://www.nuget.org/api/v2/package/Microsoft.Direct3D.D3D12/1.610.4 "zip")
+CheckAndDownloadPackage("DXC" "v1.7.2308" ${CMAKE_CURRENT_SOURCE_DIR}/external/dxc https://github.com/microsoft/DirectXShaderCompiler/releases/download/v1.7.2308/dxc_2023_08_14.zip "zip")
 
 # -----------------------------------------------------------------------------
 # Configure options
@@ -107,7 +107,7 @@ unset(NVRHI_WITH_VULKAN CACHE)
 option(DONUT_WITH_VULKAN "Enable the Vulkan version of Donut" ON)
 
 # Add projects
-add_subdirectory(donut)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/external/donut)
 
 message(STATUS "NVRHI Vulkan support " "${NVRHI_WITH_VULKAN}")
 message(STATUS "Donut Vulkan support " "${DONUT_WITH_VULKAN}")

README.md

@@ -25,7 +25,6 @@ RTXGI SDK provides an example integration (DX12 and Vulkan) of two state-of-the-
 |Directory                   |Details                                      |
 |----------------------------|---------------------------------------------|
 |[/docs][docs]               |_Documentation for showcased tech_           |
-|[/donut][donut]             |_Framework used for the samples_             |
 |[/external][external]       |_Helper dependencies for the samples_        |
 |[/media][media]             |_Assets and scene definitions_               |
 |[/samples][samples]         |_Samples showcasing usage of NRC, SHaRC_     |
@@ -61,7 +60,7 @@ Use the following BibTex entry to cite the usage of RTXGI in published research:
 See [LICENSE.md](LICENSE.md)
 
 ## RTXGI v1.x
-Version v1.x of RTXGI which includes the DDGI algorithm is located in a separate repo at the following url: https://github.com/NVIDIAGameWorks/RTXGI-DDGI".
+Version v1.x of RTXGI which includes the DDGI algorithm is located in a separate repo at the following url: https://github.com/NVIDIAGameWorks/RTXGI-DDGI.
 
 
 [ChangeLog]: CHANGELOG.md
@@ -70,7 +69,6 @@ Version v1.x of RTXGI which includes the DDGI algorithm is located in a separate
 [NrcGuide]: docs/NrcGuide.md
 [ProjectStructure]: #project-structure
 [docs]: docs
-[donut]: donut
 [external]: external
 [media]: media
 [samples]: samples/pathtracer

docs/NrcGuide.md

@@ -33,7 +33,7 @@ Instead of tracing a ray or a path to get incident radiance at a given point, we
 The decision to terminate the path early into the cache is informed by a path spread (ray cone) heuristic. The cone approximates the ray and spreads along the path as it intersects surface with various material properties. The interaction with a diffuse surface will significantly increase the cone's radius, whereas smooth/specular surfaces do not contribute as much to the cone's spread. When the radius of the cone reaches a user-specified threshold, the path is safe to terminate early in the cache. This allows the application to control the trade-off between bias and noise.
 
 
-> 📗 **Background materials**
+> 📗 **Related materials**
 >
 >- *[Real-time Neural Radiance Caching for Path Tracing][SiggraphPaper], SIGGRAPH 2021.*
 >- *[Advancing Real-Time Path Tracing with the Neural Radiance Cache][GTC2], GTC 2023.*
@@ -316,28 +316,25 @@ void Shutdown()
 
 # Debugging
 
-## Debug visualizations
-The NRC library provides several ways to visually inspect the quality of the cache data and narrow down potential integration errors. This can be achieved at the pathtracer level and at the resolve pass level.
+## Debug visualizations using the Resolve Modes
+The NRC library provides several ways to visually inspect the quality of the cache data and narrow down potential integration errors. This can be achieved through the default Resolve pass modes.
 
 ### Resolve pass debug visualization 
-Similar to the path tracer debug views, the in-built Resolve pass can be used for debugging by switching its `ResolveMode`. This caters for several types of debug cache data visualizations including a result of the query, a training bounce heatmap, training radiance (raw and smoothed) output, and a direct visualization of the cache. 
-
-When inspecting the direct visualization of the cache, indirect signal as well as defined shadows should be present. Boiling-like artifacts are expected as the NRC is not intended to be _used_ in this way, only previewed for troubleshooting.
-
-![DebugCacheVis][DebugCacheVis]
-<p align="center">
-    <em><small>Figure 5. Direct visualization of the cache - querying at vertex index 0.</small></em>
-</p>
-
-> 💡 This debug view should match the pathtracer's intensity closely. If it does not match the intensity or looks flat and lacks details (such as shadows), it could indicate that the radiance is not correctly recorded in the pathtracer passes, or that the update pass does not trace a small fraction to the full length.
-
-The training bounce heatmap is similar to the pathtracer bounce visualization and ensures that during the update pass, paths are traced on average to four bounces and a  fraction (~16th of the paths) at full length. The visualization of the training radiances at the primary path vertex, should match closely, when accumulated/smoothed, to the ground-truth path tracer output (when the NRC is disabled).
-
-![DebugAll][DebugAll]
-<p align="center">
-    <em><small>Figure 6. Resolve pass debug modes. LHS: query results. Centre: Training bounces heatmap (Red encodes two bounces, yellow-three, green-four, white-eight). RHS: Smoothed training radiance for the primary ray. </small></em>
-</p>
-
+Similar to the path tracer debug views, the in-built Resolve pass can be used for debugging through the `ResolveMode`. This caters for several types of debug cache data visualizations covered below:
+
+ResolveMode | Description | Correctness Interpretation | Reference Image
+---|---|---|---
+AddQueryResultToOutput | The default behaviour. The query result is added to the output buffer. | The result should be similar to the GT pathtracer but with reduced noise and possibly brighter signal depending on materials and GT pathtracer setup (one SPP and roughly eight bounces or less). | <img max-width="100%" height="auto" src="./figures/nrc_rm0_addquery.png">
+ReplaceOutputWithQueryResult | This mode overwrites the output buffer with the query results. | | <img max-width="100%" height="auto" src="./figures/nrc_rm1_showquery.png">
+TrainingBounceHeatMap | This mode shows a heatmap for the number of training bounces. | You should see more bounces in corners and from smooth surfaces. The number of vertices in the training path maps to debug colors as follows: <br> - 1 : Dark red           (0.5, 0.0, 0.0) <br> - 2 : Red (1.0, 0.0, 0.0) <br> - 3 : Dark yellow (0.5, 0.5, 0.0) <br> - 4 : Green (0.0, 1.0, 0.0) <br> - 5 : Dark cyan (0.0, 0.5, 0.5) <br> - 6 : Blue (0.0, 0.0, 1.0) <br> - 7 : Dark blue (0.5, 0.5, 1.0) <br> - 8 or miss : White (1.0, 1.0, 1.0) | <img max-width="100%" height="auto" src="./figures/nrc_rm2_trainingheatmap.png">
+TrainingBounceHeatMapSmoothed | Same as TrainingBounceHeatMap, but smoothed over time. | | <img max-width="100%" height="auto" src="./figures/nrc_rm3_trainingheatmapsmooth.png">
+PrimaryVertexTrainingRadiance | This mode shows the reconstructed radiance for the primary ray segment. | This should look like a low resolution version of the path traced result, and it will be noisy. The radiance shown here will include 'self training', where cache lookups are injected at the tails of many of the paths. When debugging cache issues, it can sometimes be useful to disable this self training using `nrc::FrameSettings::selfTrainingAttenuation`. | <img max-width="100%" height="auto" src="./figures/nrc_rm4_primarytrainingradiance.png">
+PrimaryVertexTrainingRadianceSmoothed | Same as PrimaryVertexTrainingRadiance, but smoothed over time. | | <img max-width="100%" height="auto" src="./figures/nrc_rm5_primarytrainingradiancesmooth.png">
+SecondaryVertexTrainingRadiance | As PrimaryVertexTrainingRadiance, but for the secondary ray segment. | | <img max-width="100%" height="auto" src="./figures/nrc_rm6_secondarytrainingradiance.png">
+SecondaryVertexTrainingRadianceSmoothed | Same as SecondaryVertexTrainingRadiance, but smoothed over time. | | <img max-width="100%" height="auto" src="./figures/nrc_rm7_secondarytrainingradiancesmooth.png">
+QueryIndex | Debug mode that shows a random color that's a hash of the query index. | When things are working correctly this should look like colored noise. | <img max-width="100%" height="auto" src="./figures/nrc_rm8_queryindex.png">
+TrainingQueryIndex | Same as QueryIndex but for the training pass' self-training records. | When things are working correctly - this should look like coloured noise. | <img max-width="100%" height="auto" src="./figures/nrc_rm9_trainingqueryindex.png">
+DirectCacheView | Direct visualization of the cache (equivalent of querying at vertex zero). | The recommended tool to assess correctness of integration, this debug view should capture features such as shadows and view-dependent specular highlights and display them in a low-detail, over-smoothed output. | <img max-width="100%" height="auto" src="./figures/nrc_rm10_cacheview.gif">
 
 ## Nsight Graphics Frame Debugging
 During the integration it is important to ensure that the NRC buffers are correctly written to by the application's pathtracer. This can be achieved with Nsight Graphics frame capture in conjunction with custom structure definitions for ease of readability.
@@ -382,8 +379,6 @@ The Structured Memory Configuration feature in Nsight comes in handy for inspect
 [NrcTermination]: figures/nrc_introtermination.svg
 [NrcIntegWorkflow]: figures/nrc_integworkflow.svg
 [DebugMethods]: #debugging
-[DebugCacheVis]: figures/nrc_debugcachevis.gif
-[DebugAll]: figures/nrc_debugresolve.png
 [DebugNsight]: figures/nrc_debugnsight.png
 [NrcD3d12h]: https://github.com/NVIDIAGameWorks/NRC/blob/main/include/NrcD3d12.h
 [NrcVkh]: https://github.com/NVIDIAGameWorks/NRC/blob/main/include/NrcVk.h

docs/QuickStart.md

@@ -1,40 +1,37 @@
 # Quick Start Guide
 
-This document lists the necessary steps to get up and running with the RTXGI SDK pathtracer sample showcasing an example integration of the NRC and SHARC libraries in a simplified unidirectional Monte Carlo path tracer. 
+This document lists the necessary steps to get up and running with the RTXGI SDK pathtracer sample showcasing an example integration of the NRC and SHaRC libraries in a simplified unidirectional Monte Carlo path tracer. 
 
-For documentation and programming/integration guides specific to each technique, see the individual [NRC][NrcGuide] and [SHaRC][SharcGuide] guides.
+For programming/integration guides specific to each technique, see the individual [NRC][NrcGuide] and [SHaRC][SharcGuide] guides.
 
-
-### Build steps
+## Build steps
 Assuming the tools specified in the [prerequisites][Prereq] section are available:
 
 1. Clone the project recursively to a preferred location for the `local-repo-path` field:
     ```
     git clone --progress --recursive --branch main -v "https://github.com/NVIDIAGameWorks/RTXGI.git" "local-repo-path"
     ``` 
 
-2. Configure and then generate the solution using CMake GUI (or the CLI) by setting the repository root as _source_ and specifying a new _build_ directory in the root.
+2. Configure and then generate the solution using CMake GUI (or the CLI). The `source` directory should be the root of the repository and `build` directory should be a new directory located in the repository root.
 
-3. Build the solution and run the `pathtracer` sample. Optionally, use the debug command line argument `-vk` to run the NVRHI Vulkan rendering backend version. 
+3. The newly generated solution `rtxgi2_samples.sln` should be located in the `build` directory. Open it and run the `pathtracer` project. Optionally, use the debug command line argument `-vk` to run the NVRHI Vulkan rendering backend version. 
 
-### The pathtracer sample
+## The pathtracer sample
 This showcases an elementary path tracer that relies on either NRC or SHaRC to terminate early into the respective radiance/irradiance cache for an improved signal.
 
 ![overview](figures/quickstart_ui.png)
 
-**1. Global settings.** New scenes can be loaded from here via a JSON file that specifies GLTF assets and user-defined properties for common constructs such as lights and camera. Additionally, four more settings that affect the sample (regardless of radiance caching and denoising) can be toggled here.
-
-**2. Pathtracer settings.** This section addresses typical pathtracer settings such as the number of bounces (maximum of eight), samples per pixel (SPP, maximum of 12), a global dial for altering material roughness, and a list of debug views that ensure the scene data is correctly represented (normals, worldspace positions, etc.).
+**Generic settings.** New scenes can be loaded from here via a JSON file that specifies GLTF assets and user-defined properties for common constructs such as lights and camera. Additionally, four more settings that affect the pathtracer and either of the radiance caching techniques can be toggled here.
 
-**3. Denoiser selection.** This is an optional setting required when the `Animations` toggle is enabled as accumulation would not be compatible with animated content. Presently, NRD is the only supported denoising tech in this sample.
+**Path tracing settings.** This section addresses typical pathtracer settings such as the number of bounces, samples per pixel, a global dial for altering material properties, and a list of debug views that ensure the scene data is correctly represented (normals, worldspace positions, etc.). From this panel, the radiance/irradiance caching modes as well as the denoising modes can be selected.
 
-**4. NRC settings.** In this section, NRC can be toggled, fine-tuned, as well as debugged visually via the `Resolve Mode` or by directly visualizing the cache data when disabling `Enable Termination Heuristic` and visualizing the state at vertex index 0. For further details see the [in-depth NRC guide][NrcGuide]. 
+**NRC settings.** In this section, NRC can be toggled, fine-tuned, as well as debugged visually via the `Resolve Mode`. For further details see the [in-depth NRC guide][NrcGuide].
 
-**5. SHARC settings.** These provide a way to toggle the tech, manually invoke a clearing of the cache, fine-tune factors that contribute to the hash-grid data, as well as visually inspect the direct contents of the cache via the `Enable Debug` option. For further details see the [in-depth SHaRC guide][SharcGuide].
+**SHaRC settings.** These provide a way to toggle the tech, manually invoke a clearing of the cache, fine-tune factors that contribute to the hash-grid data, as well as visually inspect the direct contents of the cache via the `Enable Debug` option. For further details see the [in-depth SHaRC guide][SharcGuide].
 
-**6. Lighting.** This section allows for modifying the initial light data specified in the JSON scene file.
+**Lighting.** This section allows for modifying the initial light data specified in the JSON scene file.
 
-**7. Tone mapping.** Post processing section that currently only accounts for tone mapping - useful for clamping radiance values.
+**Tone mapping.** Post processing section that currently only accounts for tone mapping - useful for clamping radiance values.
 
 [NrcGuide]: NrcGuide.md
 [SharcGuide]: SharcGuide.md