Update documentation for RRA v1.7 release

ahosier · ahosier · commit dde6f7175bde · 2024-10-03T11:11:42.000-04:00
diff --git a/BUILD.md b/BUILD.md
@@ -1,5 +1,7 @@
 ## Build instructions
 
+To build RRA from source, third party software will need to be installed on your system.  A script may be provided that, when executed by you, automatically fetches and installs software onto your system, where such software originates from (a) elsewhere on your system, if such software is already present on your system, or (b) the internet, if such software is not already present on your system. BY EXECUTING THE SCRIPT AND INSTALLING THE THIRD PARTY SOFTWARE, YOU AGREE TO BE BOUND BY THE LICENSE AGREEMENT(S) APPLICABLE TO SUCH SOFTWARE. You agree to carefully review and abide by the terms and conditions of all license(s) that govern such software.  You acknowledge and agree that AMD is not distributing to you any of such software and that you are solely responsible for the installation of such software on your system.
+
 ### Download Source code
 
 Clone the project radeon_raytracing_analyzer from github.com
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ to reduce performance bottlenecks.
 
 ## Important notes
 1. In order to capture BVH data, please ensure that acceleration structures are rebuilt each frame.
-2. In order to capture ray history information, please ensure that all command buffer are rebuilt each frame.
+2. In order to capture ray history information, please ensure that all command buffers are rebuilt each frame.
 3. RayQuery is currently only supported from compute shaders. Calling RayQuery from the graphics pipeline is not supported.
 
 ## Supported APIs
@@ -43,6 +43,7 @@ to reduce performance bottlenecks.
 * Windows® 10
 * Windows® 11
 * Ubuntu 22.04 LTS (Vulkan only)
+* Ubuntu 24.04 LTS (Vulkan only)
 
 ## Build instructions
 See [BUILD.md](BUILD.md) for more details.
@@ -81,4 +82,4 @@ CMake is a registered trademark of Kitware, Inc.
 Qt and the Qt logo are registered trademarks of the Qt Company Ltd and/or its subsidiaries worldwide.
 
 
-© 2022-2023 Advanced Micro Devices, Inc. All rights reserved.
+© 2022-2024 Advanced Micro Devices, Inc. All rights reserved.
diff --git a/RELEASE_NOTES.txt b/RELEASE_NOTES.txt
@@ -1,10 +1,14 @@
-Radeon Raytracing Analyzer V1.6 07/01/2024
+Radeon Raytracing Analyzer V1.7 10/01/2024
 ------------------------------------------
 
-V1.6 Changes
+V1.7 Changes
 ------------------------------------
-1) Updated to use Qt 6.7.0.
-2) Stability/bug fixes.
+1) Dark mode user interface support, allowing the user to choose between a light and dark theme (or have RRA follow the OS theme setting).
+2) UI support for driver experiments.
+3) Support for naming dispatches with user markers.
+4) The total number of procedural nodes has been added for each TLAS in the Overview|Summary pane.
+5) The "Device configuration" pane has been renamed to "System information."
+6) Bug/stability fixes.
 
 Known Issues
 ------------------------------------
@@ -24,6 +28,11 @@ Known Issues
 Release Notes History
 ------------------------------------
 
+V1.6 Changes
+------------------------------------
+1) Updated to use Qt 6.7.0.
+2) Stability/bug fixes.
+
 V1.5 Changes
 ------------------------------------
 1) Ray inspector has been updated to display the ray hierarchy, recursive rays will now display under the parent rays that shot them.
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
@@ -54,9 +54,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'1.6.0'
+version = u'1.7.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.6.0'
+release = u'1.7.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/documentation/source/index.rst b/documentation/source/index.rst
@@ -43,6 +43,8 @@ Supported graphics APIs, RDNA hardware, and operating systems
 
 -  Ubuntu® 22.04 LTS (Vulkan only)
 
+-  Ubuntu® 24.04 LTS (Vulkan only)
+
 DISCLAIMER
 ----------
 The information contained herein is for informational purposes only, and is subject to change without notice. While every
diff --git a/documentation/source/media/overview/device_config_1.png b/documentation/source/media/overview/device_config_1.png
diff --git a/documentation/source/media/overview/driver_experiments_1.png b/documentation/source/media/overview/driver_experiments_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d885892d3003a1626982b85572cab54d4298564a0ccf64826a2f09027e55ece4
+size 75427
diff --git a/documentation/source/media/overview/summary_1.png b/documentation/source/media/overview/summary_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:73b59e35602caeccc5799eb348f79f6433170d5c404341a11920bc3cb714b633
-size 93368
+oid sha256:434e4cab8e06be8c1e7f6eed2f4a58816699b4b2afa49920e098405807dae47d
+size 107497
diff --git a/documentation/source/media/overview/system_info_1.png b/documentation/source/media/overview/system_info_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e21477bca066d90c6d608cb3f8ee9bcb05ebe8c22cbeb233705c4da9ab243a9d
+size 49906
diff --git a/documentation/source/media/overview/user_markers.png b/documentation/source/media/overview/user_markers.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d56436a641078cca8627cfb19efe1168502716cf10a923fab16608c203ceeae
+size 26234
diff --git a/documentation/source/media/ray/ray_history_1.png b/documentation/source/media/ray/ray_history_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ee890ba80fa7468f6c0f9a564361305ebdda55baff4c8a3c06e5407b8fe664a8
-size 782016
+oid sha256:298b4657ec5f6aa1fa9963ef94f92b4d4847616687ce89a7dece06f08d711f2d
+size 177928
diff --git a/documentation/source/media/ray/ray_history_2.png b/documentation/source/media/ray/ray_history_2.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:e64c86fb936f939ca7175f68af227ae4cde4a81e4e213841ca5553fe6f672997
-size 743904
+oid sha256:0c64203df84011f2c24e9d3eb8a63e8fb2f6f30f9b066f7a01d0d821d368f414
+size 149905
diff --git a/documentation/source/media/ray/ray_inspector_1.jpg b/documentation/source/media/ray/ray_inspector_1.jpg
diff --git a/documentation/source/media/ray/ray_inspector_1.png b/documentation/source/media/ray/ray_inspector_1.png
diff --git a/documentation/source/media/ray/ray_inspector_3.jpg b/documentation/source/media/ray/ray_inspector_3.jpg
diff --git a/documentation/source/media/ray/ray_inspector_3.png b/documentation/source/media/ray/ray_inspector_3.png
diff --git a/documentation/source/media/ray/ray_user_markers.png b/documentation/source/media/ray/ray_user_markers.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fa76d7dbea091ed1b06cfef26cc8c43e2a9cb19cddb6725bc3f3577aa489eeeb
+size 16338
diff --git a/documentation/source/media/settings/dark_theme_1.png b/documentation/source/media/settings/dark_theme_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bda97a5ec0ccf50ba971717dae14eb31e6858923a443f268d9e10d5a6c453e86
+size 83321
diff --git a/documentation/source/media/settings/dark_theme_prompt.png b/documentation/source/media/settings/dark_theme_prompt.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f3b707e2e459d21e70d34ea6cc1e77f88e1a0930d4454a263d07a9ad911eda0
+size 9393
diff --git a/documentation/source/media/settings/general_1.png b/documentation/source/media/settings/general_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:88651a7c24d22a9a1396d631cf4a6235ea842a12104dc000d6b4fd194a6d0f85
-size 37694
+oid sha256:b8a1c17bdb7dcf252d1420e55db49381789c8b6203d0ead90a1f16f54b17ad3d
+size 44935
diff --git a/documentation/source/media/settings/keyboard_shortcuts_1.png b/documentation/source/media/settings/keyboard_shortcuts_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:93ca4f6f0cf871def6e72ff8ae55d43442a79922103af439f882b4fe1e5816a7
-size 56794
+oid sha256:15390ed0ca544b4d3a1dd63459b4680ab9462a4b627d8db66971c692300fa71c
+size 52964
diff --git a/documentation/source/media/settings/themes_and_colors_1.png b/documentation/source/media/settings/themes_and_colors_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:44f27bab880265d6c3a577e133dd9f9475a15211c876887a917cc3a248a86cf0
-size 39705
+oid sha256:afde1fa2fe5e2450f7d180cb82822e6950cca5c873c829d6232dc762d7d5e6ad
+size 46829
diff --git a/documentation/source/media/tlas/loop_count.jpg b/documentation/source/media/tlas/loop_count.jpg
diff --git a/documentation/source/media/tlas/loop_count.png b/documentation/source/media/tlas/loop_count.png
diff --git a/documentation/source/media/tlas/tlas_viewer_1.jpg b/documentation/source/media/tlas/tlas_viewer_1.jpg
diff --git a/documentation/source/media/tlas/tlas_viewer_1.png b/documentation/source/media/tlas/tlas_viewer_1.png
diff --git a/documentation/source/overview.rst b/documentation/source/overview.rst
@@ -50,7 +50,9 @@ If dispatches was enabled from the Radeon Developer Panel, the **Dispatch list**
 a list of all ray dispatches that were executed during the captured frame.
 
 Each dispatch is shown as a card. The title text shows the API function name that launched
-the dispatch and the dispatch dimensions.
+the dispatch and the dispatch dimensions. If the dispatch has been named (using
+vkCmdBeginDebugUtilsLabelEXT or equivalent in Vulkan, or agsDriverExtensionsDX12_PushMarker
+or equivalent in DirectX 12), the name will show below the API name.
 
 The **Traversal statistics** show information pertaining to how much computation
 was done by this dispatch, such as the number of rays that were cast, the traversal loop counts
@@ -60,13 +62,24 @@ dispatch may give the user an indication of the efficiency of a particular dispa
 The **Shader invocations** shows the number of shaders that were executed and their type. This
 is also represented as a donut, showing the relative counts of the shader types.
 
-Clicking on the Dispatch name (text in blue) will navigate to the RAY Dispatches pane.
+Clicking on the Dispatch API function name (text in blue) will navigate to the RAY Dispatches pane.
 
-Device configuration
---------------------
-This pane will show some of the parameters of the video hardware on which the
-scene was recorded, showing such things as the name of the video card and
-the memory bandwidth.
+Since RRA 1.7 it is possible to associate each dispatch with a user-defined string called a user marker.
+If a user marker has been associated with a dispatch, it will be shown below the dispatch API call as
+shown below:
 
-.. image:: media/overview/device_config_1.png
+.. image:: media/overview/user_markers.png
+
+The **Radeon GPU Profiler** documentation provides a comprehensive description of adding user markers
+to your application.
+
+System information
+------------------
+This pane will show some of the parameters of the video hardware on which the scene was
+recorded, showing such things as the name of the video card and the memory bandwidth.
+In addition, if any Driver experiments are included when the scene was captured, they will
+be displayed here under the section labeled **Driver experiments**. Hovering over a driver
+experiment name or value with the mouse pointer displays a tooltip describing that item.
+
+.. image:: media/overview/system_info_1.png
 
diff --git a/documentation/source/quickstart.rst b/documentation/source/quickstart.rst
@@ -8,7 +8,7 @@ The first thing you will need to do is generate a BVH scene. Currently,
 this is done via the Radeon Developer Panel. Please read the documentation
 provided with this distribution for information on how to create a BVH scene.
 This can be obtained from within the Radeon Developer Panel or from the link
-on the Radeon Raytracing Analyzer “Welcome” view. The documentation is also
+on the Radeon Raytracing Analyzer "Welcome" view. The documentation is also
 available online at:
 http://radeon-developer-panel.readthedocs.io/en/latest/
 
@@ -71,7 +71,7 @@ number of sub-windows..
    a. **Summary** - Gives an overview of the scene, showing the number
       of acceleration structures, the resources they use and their memory usage.
 
-   b. **Device configuration** - Provides details of the GPU used to
+   b. **System information** - Provides details of the GPU used to
       record the scene.
 
 3. **TLAS**
@@ -108,4 +108,27 @@ number of sub-windows..
    a. **Dispatches** - The main viewer for visualizing various types of dispatches that shot rays.
 
    b. **Inspector** - A viewer for inspecting rays and how they interact with
-      the scene.
+      the scene.
+
+Driver experiments
+------------------
+   
+Driver experiments are configured when capturing a scene and allow the behavior
+of certain driver operations to be adjusted.  Please see the Radeon Developer
+Panel documentation for more details on configuring Driver experiments. Modified
+Driver experiments included in a scene file will be listed on the System information
+pane under the section labeled **Driver experiments**. 
+
+.. image:: media/overview/system_info_1.png
+
+When a scene file that includes Driver experiments is loaded, a notification
+banner is displayed below the main drop down menu. 
+
+.. image:: media/overview/driver_experiments_1.png
+
+The notification banner includes a "see details" shortcut link that navigates
+to the System information pane. The banner can be dismissed by clicking the "X"
+button. Clicking the "Do not show again" link prevents the banner from being
+shown for subsequently loaded scene files. The notification banner can be
+re-enabled from the Settings pane.
+
diff --git a/documentation/source/ray_windows.rst b/documentation/source/ray_windows.rst
@@ -19,6 +19,11 @@ The Information section
 As well as selecting dispatches from the **Overview pane**, they can also be selected from a dropdown
 in the top-left. The UI will be updated according to the dispatch selected.
 
+If a user marker has been associated with a dispatch, it will show up under the dispatch dropdown as
+show here:
+
+.. image:: media/ray/ray_user_markers.png
+
 Below the dispatch selection dropdown is the **Dispatch counters** table which shows some high-level
 statistics for the selected regions in the heatmap (see below), such as the ray count and number of instance
 intersections per ray.
@@ -96,7 +101,7 @@ on an entry in the table or a pixel in the heatmap image will navigate to the **
 The Inspector Tab
 -----------------
 
-.. image:: media/ray/ray_inspector_1.png
+.. image:: media/ray/ray_inspector_1.jpg
 
 The screen layout is similar to the TLAS and BLAS viewer panes, and is split into 3 areas.
 
@@ -121,7 +126,7 @@ index of the hit triangle. These fields will be blank if the ray misses.
 The center section shows a rendering of the scene:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: media/ray/ray_inspector_3.png
+.. image:: media/ray/ray_inspector_3.jpg
 
 Super-imposed on the scene are the rays corresponding to the pixel selected from the Ray dispatches pane. The scene
 coloring defaults to a new grayscale heatmap coloring mode so that the rays stand out from the background.
@@ -146,3 +151,4 @@ These controls function almost identically to those in the TLAS and BLAS viewer
 A notable difference is that this pane contains a lock button to the right of the Camera position label. When locked,
 the camera will preserve its position when changing the selected dispatch coordinate in the Dispatches tab instead of
 focusing on the first ray in that coordinate's ray list.
+
diff --git a/documentation/source/settings.rst b/documentation/source/settings.rst
@@ -87,6 +87,10 @@ and better performance.
 the app will be displayed at. Hovering the mouse over a floating point value will display
 its full precision through a tooltip.
 
+**Show Driver experiment notifications** If checked, the Radeon Raytracing Analyzer
+will display a notification banner under the main drop down menu of the user
+interface indicating when a scene contains modified Driver experiments.
+
 .. image:: media/settings/general_1.png
 
 Themes and colors
@@ -130,6 +134,25 @@ The **Ray coloring** determines the colors of the rays shown in the 3D view of t
 
 .. image:: media/settings/themes_and_colors_1.png
 
+**Color theme:** The color theme can be changed with the "Color Theme" drop down combo box. 
+This changes the application-wide background and text color. The "Light" option maintains 
+RRA's default look of white backgrounds with black text. The "Dark" option changes RRA to 
+have a dark background color with lighter color text. The "Detect OS" option uses the system's 
+color theme to determine whether the color theme should be light or dark. If the system's 
+color theme cannot be detected, RRA will default to light theme. If the system's color 
+theme is changed while RRA is open with the "Detect OS" option selected it will not apply
+until the application has been restarted. On Windows operating systems when changing the color 
+theme a pop-up prompt will recommend restarting the application. This is because not all parts 
+of RRA will update to a change in color theme until the application is restarted. Changing 
+the color theme will not change any other color customization options that have been selected.
+
+.. image:: media/settings/dark_theme_prompt.png
+
+This is an example of how RRA will look when the color theme is changed to dark: 
+
+.. image:: media/settings/dark_theme_1.png
+
+
 Keyboard shortcuts
 ------------------
 
@@ -167,3 +190,4 @@ on all panes in the top left below the file menu.
 
 Currently, back and forward navigation is restricted to pane switches.
 
+
diff --git a/documentation/source/tlas_windows.rst b/documentation/source/tlas_windows.rst
@@ -28,7 +28,7 @@ have a smaller movement speed.
 
 An example TLAS viewer pane is shown below:
 
-.. image:: media/tlas/tlas_viewer_1.png
+.. image:: media/tlas/tlas_viewer_1.jpg
 
 The view is split into 3 sections:
 
@@ -289,7 +289,7 @@ signatures by editing BLASes and repositioning of instances in the TLAS.
 
 An example of a typical scene using the traversal counters is shown below.
 
-    .. image:: media/tlas/loop_count.png
+    .. image:: media/tlas/loop_count.jpg
 
 The visualization depends on a counter range provided by the user via the **Counter range** slider. 
 The range is determined by the scene layout and the counter type selected. Adjusting the slider will
@@ -663,3 +663,4 @@ The Properties tab displays a read-only table of properties and statistics for
 the selected TLAS.
 
 .. image:: media/tlas/tlas_properties_1.png
+
