Update documentation for RRA v1.4 release

ahosier · ahosier · commit bcb42eef6be7 · 2023-12-07T12:46:37.000-05:00
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -5,7 +5,7 @@ version: 2
 build:
    os: ubuntu-22.04
    tools:
-      python: "3.7"
+      python: "3.11"
    jobs:
       post_checkout:
          # Download and uncompress the binary
@@ -23,5 +23,11 @@ build:
          # Make local files to have the real content on them
          - ./git-lfs checkout
 
+# Build documentation in the docs/source directory with Sphinx
 sphinx:
    configuration: documentation/source/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: documentation/requirements.txt
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ to reduce performance bottlenecks.
    * Radeon Developer Service CLI (RDS headless)
    * Radeon Developer Panel (RDP)
    * Radeon Raytracing Analyzer (RRA)
-3. To capture a trace from a game, run the Radeon Developer Panel and follow the instructions in the Help. Help can be found in the following locations:
+3. To capture a scene from a game, run the Radeon Developer Panel and follow the instructions in the Help. Help can be found in the following locations:
    * Help web pages exist in the "help" sub directory
    * Help web pages can be accessed from the **Help** button in the Developer Panel
    * Help web pages can be accessed from the Welcome screen in the Radeon Raytracing Analyzer, or from the **Help** menu
@@ -47,6 +47,9 @@ to reduce performance bottlenecks.
 ## Build instructions
 See [BUILD.md](BUILD.md) for more details.
 
+## Support ##
+For support, please visit the RRA repository github page: https://github.com/GPUOpen-Tools/radeon_raytracing_analyzer
+
 ## License ##
 Radeon Raytracing Analyzer is licensed under the MIT license. See the [LICENSE.txt](LICENSE.txt) file for complete license information.
 
diff --git a/RELEASE_NOTES.txt b/RELEASE_NOTES.txt
@@ -1,19 +1,20 @@
-Radeon Raytracing Analyzer V1.3.1 10/18/2023
---------------------------------------------
+Radeon Raytracing Analyzer V1.4 12/07/2023
+------------------------------------------
 
-V1.3.1 Changes
+V1.4 Changes
 ------------------------------------
-1) A bugfix has been made to use the correct dispatch size for future versions of RRA to ensure backwards compatibility.
+1) Ray direction visualization added to dispatch pane.
+2) Bugs/stability fixes.
 
 Known Issues
 ------------------------------------
-(1) When capturing raytracing applications, it is strongly recommended not to reuse buffers immediately after a DispatchRays() call, since the capture process can take quite a bit of time and this will lead to partially created BVH data being written out. This will show up in RRA as missing BLAS/TLAS data. The trace should still load but certain parts of the scene will be missing.
+(1) When capturing raytracing applications, it is strongly recommended not to reuse buffers immediately after a DispatchRays() call, since the capture process can take quite a bit of time and this will lead to partially created BVH data being written out. This will show up in RRA as missing BLAS/TLAS data. The scene should still load but certain parts of the scene will be missing.
 (2) RRA is very memory-intensive, particularly for large scenes. To reduce the memory footprint as much as possible, please limit the number of concurrent instances of RRA. This will be dependent on the amount of video and system memory available, and in most uses-cases will not be an issue.
-(3) Radeon Developer Panel will NOT capture RRA traces from AMD multi-GPU configurations (e.g. two AMD GPUs). It will work with one AMD GPU and other non-AMD cards installed in the same machine. Please note that the primary monitor will need to be configured for the AMD GPU/monitor combination. For systems consisting of an AMD APU and AMD discrete GPU, capturing profiles should work, but an error may be logged in the Radeon Developer Panel regarding not being able to set peak clock mode. It is recommended that the GPU in the APU be disabled in the BIOS.
-(4) Radeon Developer Panel can only capture an RRA trace on a single AMD GPU at a time.
-(5) Radeon Developer Panel cannot capture RRA traces from non-AMD GPUs.
+(3) Radeon Developer Panel will NOT capture RRA scenes from AMD multi-GPU configurations (e.g. two AMD GPUs). It will work with one AMD GPU and other non-AMD cards installed in the same machine. Please note that the primary monitor will need to be configured for the AMD GPU/monitor combination. For systems consisting of an AMD APU and AMD discrete GPU, capturing profiles should work, but an error may be logged in the Radeon Developer Panel regarding not being able to set peak clock mode. It is recommended that the GPU in the APU be disabled in the BIOS.
+(4) Radeon Developer Panel can only capture an RRA scene on a single AMD GPU at a time.
+(5) Radeon Developer Panel cannot capture RRA scenes from non-AMD GPUs.
 (6) Unicode folders and filenames are currently not supported.
-(7) There is currently no default "Application 'up' axis" in the viewer panes. When loading or reloading RRA traces, orient your scene and press the "U" key to automatically set the up axis.
+(7) There is currently no default "Application 'up' axis" in the viewer panes. When loading or reloading RRA scenes, orient your scene and press the "U" key to automatically set the up axis.
 (8) The axis free camera does not properly "Jump to ray" when the view is reset with 'F' key press.
 (9) Only the X dimension is captured for the applications that use indirect dispatches.
 (10) The fov and camera speed does not get properly transmitted when jumping from ray inspector to TLAS viewer via the links on the left panel.
@@ -22,6 +23,10 @@ Known Issues
 Release Notes History
 ------------------------------------
 
+V1.3.1 Changes
+------------------------------------
+1) A bugfix has been made to use the correct dispatch size for future versions of RRA to ensure backwards compatibility.
+
 V1.3 Changes
 ------------------------------------
 1) Addition of a RAY tab, to enable the ability to visualize dispatches and individual rays.
@@ -46,7 +51,7 @@ V1.1.1 Changes
 V1.1 Changes
 ------------------------------------
 1) Addition of an axis-free camera.
-2) Camera placed at 45 degrees above the scene on trace load.
+2) Camera placed at 45 degrees above the scene on scene load.
 3) Support for rebraided instances:
   a) Coloring mode to show which instances are rebraided.
   b) Allow selection of rebraided siblings.
diff --git a/documentation/requirements.txt b/documentation/requirements.txt
@@ -0,0 +1,4 @@
+# Defining requirements for docs
+sphinx==5.3.0
+sphinx_rtd_theme==1.1.1
+readthedocs-sphinx-search==0.1.1
diff --git a/documentation/source/blas_instance_list.rst b/documentation/source/blas_instance_list.rst
@@ -43,3 +43,4 @@ Typically, instances are created with their own local co-ordinate system. When
 placed in the scene, each instance requires a transformation from its local
 co-ordinate system to the world co-ordinate system. This is shown by the
 position and transform matrix in the table.
+
diff --git a/documentation/source/blas_list.rst b/documentation/source/blas_list.rst
@@ -48,3 +48,4 @@ sorting is in ascending or descending order.
 
 Double-clicking an item in the table will jump to the BLAS Viewer pane and show
 the selected BLAS.
+
diff --git a/documentation/source/blas_properties.rst b/documentation/source/blas_properties.rst
@@ -5,3 +5,4 @@ The Properties tab displays a read-only table of properties and statistics for
 the selected BLAS.
 
 .. image:: media/blas/blas_properties_1.png
+
diff --git a/documentation/source/blas_viewer.rst b/documentation/source/blas_viewer.rst
@@ -81,3 +81,4 @@ When a split triangle is selected, the left-side pane will indicate that the tri
 A list of the split triangle siblings is also shown, allowing easy selection.
 
 .. image:: media/blas/split_triangles_stats_1.png
+
diff --git a/documentation/source/capture.rst b/documentation/source/capture.rst
@@ -1,9 +1,9 @@
-How to generate a BVH trace
+How to generate a BVH scene
 ---------------------------
 
-The first thing you will need to do is generate a BVH trace. Currently,
+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 trace.
+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
 available online at:
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.3.1'
+version = u'1.4.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.3.1'
+release = u'1.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/documentation/source/geometries_list.rst b/documentation/source/geometries_list.rst
@@ -21,3 +21,4 @@ The following fields are displayed:
 
 The columns can be sorted by clicking on the column header. The arrow in the heading shows if
 sorting is in ascending or descending order.
+
diff --git a/documentation/source/index.rst b/documentation/source/index.rst
@@ -40,35 +40,35 @@ Radeon Raytracing Analyzer - Quick Start
 Starting the Radeon Raytracing Analyzer
 ---------------------------------------
 
-Start **RadeonRaytracingAnalyzer.exe** (this is the tool used to view RRA trace data).
+Start **RadeonRaytracingAnalyzer.exe** (this is the tool used to view RRA scene data).
 
-How to load a trace
+How to load a scene
 -------------------
 
-There are a few ways to load a trace into RRA.
+There are a few ways to load a scene into RRA.
 
-1) Use the “File/Open trace” pull down menu, or the “File/Recent
-   trace” pull down menu item.
+1) Use the "File/Open scene" pull down menu, or the "File/Recent
+   scene" pull down menu item.
 
-2) Go to the “Welcome” view and click on the “Open a Radeon Raytracing Analyzer file…”
+2) Go to the "Welcome" view and click on the "Open a Radeon Raytracing Analyzer file…"
 
-3) Go to the “Welcome” view and click on a trace that you have
+3) Go to the "Welcome" view and click on a scene that you have
    previously loaded in the Recent list.
 
 .. image:: media/welcome_1.png
 
-4) Go to the Recent traces view to see a full list of all your recent traces.
+4) Go to the Recent scenes view to see a full list of all your recent scenes.
 
-  Notice that there is additional information provided for each trace when
-  viewed in this pane, such as the date when the trace was last accessed. It is
-  also possible to remove recent traces from the list using the "Remove from list"
+  Notice that there is additional information provided for each scene when
+  viewed in this pane, such as the date when the scene was last accessed. It is
+  also possible to remove recent scenes from the list using the "Remove from list"
   link button. Note that they will only be removed from the list; they won't be
   deleted from the file system. There is also a link button, "Open file location"
-  to open the folder where that trace file is on the disk.
+  to open the folder where that scene file is on the disk.
 
 .. image:: media/recent_traces_1.png
 
-5) Drag and drop an RRA trace file onto the **Radeon Raytracing Analyzer**
+5) Drag and drop an RRA scene file onto the **Radeon Raytracing Analyzer**
    executable, or onto an already open RRA instance.
 
 The Radeon Raytracing Analyzer user interface
@@ -80,20 +80,20 @@ number of sub-windows..
 1. **START**
 
    a. **Welcome** - Shows links to help documentation, and a list of
-      recently opened traces.
+      recently opened scenes.
 
-   b. **Recent traces** - Displays a list of the recently opened
-      traces.
+   b. **Recent scenes** - Displays a list of the recently opened
+      scenes.
 
    c. **About** - Shows build information about RRA and useful links.
 
 2. **OVERVIEW**
 
-   a. **Summary** - Gives an overview of the trace, showing the number
+   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
-      record the trace.
+      record the scene.
 
 3. **TLAS**
 
@@ -223,3 +223,4 @@ Windows is a registered trademark of Microsoft Corporation in the US and other j
 
 
 © 2022-2023 Advanced Micro Devices, Inc. All rights reserved.
+
diff --git a/documentation/source/overview.rst b/documentation/source/overview.rst
@@ -1,33 +1,33 @@
-These panes show the overview of the trace and the system.
+These panes show the overview of the scene and the system.
 
 Summary
 -------
 The summary pane presents a high-level view of the acceleration structures in
-a trace. If dispatches was specified when taking a capture, the dispatches
+a scene. If dispatches was specified when taking a capture, the dispatches
 that shot rays will also be shown.
 
 At the top, a small table will show the number of acceleration structures by type
 and if there are any acceleration structures that are empty or missing.
 
-* **Total TLASes** is the total number of top-level acceleration structures in the trace.
+* **Total TLASes** is the total number of top-level acceleration structures in the scene.
 
-* **Total BLASes** is the total number of bottom-level acceleration structures in the trace.
+* **Total BLASes** is the total number of bottom-level acceleration structures in the scene.
 
 * **Empty BLASes** is the number of BLASes which have no geometry data.
 
 * **Missing BLASes** is the number of instances which contain a reference to a BLAS that isn't
-  present in the trace file.
+  present in the scene file.
 
 * **Inactive instances** is the number of instances which either have a null handle in place of their
   BLAS reference or have an instance mask of 0x0. This does not exactly match the DirectX 12 and Vulkan
   specification definitions of inactive instances in which an instance mask of 0x0 is not considered
   inactive. The reason for this is that the driver internally converts inactive instances to have an
-  instance mask of 0x0 so they are indistinguishable in the trace file.
+  instance mask of 0x0 so they are indistinguishable in the scene file.
 
 The **Total memory** is the memory used for all the acceleration structures.
 
 The **TLAS list** shows a list of all Top-level acceleration structures in
-the trace. It is split into several sections:
+the scene. It is split into several sections:
 
 * The left section shows a high level diagram of the TLAS, showing the number
   of instances and BLASes. Also shown is the memory used by the TLAS and the total
@@ -62,7 +62,8 @@ Clicking on the Dispatch name (text in blue) will navigate to the RAY Dispatches
 Device configuration
 --------------------
 This pane will show some of the parameters of the video hardware on which the
-memory trace was taken, showing such things as the name of the video card and
+scene was recorded, showing such things as the name of the video card and
 the memory bandwidth.
 
 .. image:: media/overview/device_config_1.png
+
diff --git a/documentation/source/ray_dispatches.rst b/documentation/source/ray_dispatches.rst
@@ -24,20 +24,20 @@ The table columns can be sorted to help highlight problematic areas, for example
 to find coordinates that cast too many rays. Note that only the coordinates with at least 1 ray cast
 will be displayed.
 
-The Heatmap section
+The Image section
 ~~~~~~~~~~~~~~~~~~~
-On the right hand side is a heatmap visualizing traversal statistics of the dispatch. A typical heatmap
+On the right hand side is an image visualizing traversal statistics of the dispatch. A typical
 image will be a 2D image that correlates closely to the final 2D rendered image in the capture application.
 However, applications are free to use 1D, 2D, or 3D dispatches in an arbitrary way that may or may not be
 easily mappable to the final rendered image. For 3D dispatches, they can be displayed as a series of 2D
 'slices' by changing the **XY image with Z index at** dropdown to change the slice plane displayed, and
 index into the slices by editing the number to the right of the dropdown.
 
-The image can visualize each column of the dispatch coordinates table using the **Color heatmap by ..**
-dropdown, and the color palette of the heatmap can be changed using the **Heatmap as ..** dropdown.
+The image can visualize each column of the ray table as a heatmap. It can visualize the ray direction as well. 
+Ray directions will be mapped from the normalized directions into color space. The coloring mode of the image can be changed by using the dropdown above the viewer. 
 
 A slider bar below the image can be used to adjust the heatmap range, which enables potential problems to be
-seen easier.
+seen easier. In the case of ray directions, the slider will allow the selection of the ray index for each dispatch coordinate.
 
 The rendered image can be manipulated with the mouse. An area of interest can be selected by holding down
 the left mouse button and dragging the mouse. Repeating this process will select a new rectangle. When
@@ -87,3 +87,4 @@ An area of interest is shown in the image below:
 After selecting a region, the dispatch table will be updated to only contain the rays within the dispatch
 coordinates of the selected region and the dispatch counters statistics will be updated as well. Double-clicking
 on an entry in the table or a pixel in the heatmap image will navigate to the **Ray Inspector** pane.
+
diff --git a/documentation/source/ray_inspector.rst b/documentation/source/ray_inspector.rst
@@ -50,3 +50,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
@@ -144,3 +144,4 @@ the product.
 .. image:: media/settings/keyboard_shortcuts_1.png
 
 All users are encouraged to adopt these keystrokes while using RRA.
+
diff --git a/documentation/source/tlas_instance_list.rst b/documentation/source/tlas_instance_list.rst
@@ -41,3 +41,4 @@ Typically, instances are created with their own local co-ordinate system. When
 placed in the scene, each instance requires a transformation from its local
 co-ordinate system to the world co-ordinate system. This is shown by the
 position and transform matrix in the table.
+
diff --git a/documentation/source/tlas_properties.rst b/documentation/source/tlas_properties.rst
@@ -5,3 +5,4 @@ The Properties tab displays a read-only table of properties and statistics for
 the selected TLAS.
 
 .. image:: media/tlas/tlas_properties_1.png
+
diff --git a/documentation/source/tlas_viewer.rst b/documentation/source/tlas_viewer.rst
@@ -248,17 +248,12 @@ The **Camera controls** section allows selection of the camera controls.
   selected control style and are primarily used to drive the camera. 
   Common keyboard shortcuts are also described in the keyboard shortcuts section in the settings menu. 
 
-.. only:: internal
-
-   * The **Copy camera params** and **paste camera params** allow the camera position to be
-     saved and restored. This can be helpful to return to a point of interest in a scene later.
-
 * The **Projection** combo box allows selection of the projection mode, switching between
   perspective and orthographic viewing modes. The default is perspective.
 
 * The **Up axis** radio buttons allow the orientation of the scene to be changed according to
   the specified **up** axis. This will be dependent on the coordinate system of the application
-  from where the trace file originated. Alternatively, the scene can be oriented in the 3D view
+  from where the scene originated. Alternatively, the scene can be oriented in the 3D view
   so it looks correct, then the "U" key can be pressed. RRA will then set the up axis automatically.
 
 * The **Coordinate system** checkboxes allow the inversion of the horizontal and vertical axes.
@@ -268,11 +263,6 @@ The **Camera controls** section allows selection of the camera controls.
 
 * The **Field of view** slider changes the camera's field of view.
 
-.. only:: internal
-
-    * The **Near plane** slider changes the near clipping plane. (The far plane is set to a
-      large constant.)
-
 * The **Movement speed** slider changes the speed of the camera. The maximum speed can be set in the
   **General** section of the settings under **Maximum camera movement speed**.
 
@@ -441,11 +431,6 @@ The coloring modes are available in a row above the scene rendering.
    * Technical drawing
       Directionally lit Gooch shading.
 
-     .. only:: internal
-
-      * Leaf node triangle index (Triangle)
-         The triangle index within a leaf node.
-
 #. **Traversal counters** is only available when the traversal rendering mode is
    enabled, and allows for different hit and test counters to be used when colorizing
    the scene. Each pixel shows how many bounding volume tests or hits were performed.
@@ -569,3 +554,4 @@ Rebraided instances will be clearly marked on the left-side pane when an instanc
 If the instance has been rebraided, the sibling nodes will be listed, allowing for easy selection.
 
 .. image:: media/tlas/rebraiding_stats_1.png
+
diff --git a/documentation/source/triangle_list.rst b/documentation/source/triangle_list.rst

Original file line number	Diff line number	Diff line change
`@@ -48,3 +48,4 @@ sorting is in ascending or descending order.`
`48`	`48`
`49`	`49`	`Double-clicking an item in the table will jump to the BLAS Viewer pane and show`
`50`	`50`	`the selected BLAS.`
	`51`	`+`
Original file line number	Diff line number	Diff line change
`@@ -5,3 +5,4 @@ The Properties tab displays a read-only table of properties and statistics for`
`5`	`5`	`the selected BLAS.`
`6`	`6`
`7`	`7`	`.. image:: media/blas/blas_properties_1.png`
	`8`	`+`
Original file line number	Diff line number	Diff line change
`@@ -81,3 +81,4 @@ When a split triangle is selected, the left-side pane will indicate that the tri`
`81`	`81`	`A list of the split triangle siblings is also shown, allowing easy selection.`
`82`	`82`
`83`	`83`	`.. image:: media/blas/split_triangles_stats_1.png`
	`84`	`+`