Add documentation for RRA 1.1 release

ahosier · ahosier · commit 8b316b41a033 · 2022-12-14T13:44:10.000-05:00
diff --git a/README.md b/README.md
@@ -1,18 +1,18 @@
 # Radeon™ Raytracing Analyzer
 
-The Radeon Raytracing Analyzer (RRA) is a tool designed to help improve the raytracing performance of AMD GPU's that support raytracing.
+The Radeon Raytracing Analyzer (RRA) is a tool designed to help improve the raytracing performance of AMD GPUs that support raytracing.
 The tool thus far focuses on the visualization of the Acceleration Structures, which consist of Bounding Volume Hierarchies.
 
 Game developers are responsible for creating the acceleration structures and so need a method of visualizing these acceleration structures
 and how they can affect performance.
 
 RRA allows the developer to visualize the bounding box hierarchies, and related scene geometries, via a standard rasterizer renderer or using
-a traversal counter view which will quickly hightlight areas of concern. Once identified, the developer can revisit their BVH generation strategy
+a traversal counter view which will quickly highlight areas of concern. Once identified, the developer can revisit their BVH generation strategy
 to reduce performance bottlenecks.
 
 ## Getting Started
 
-1. Install the latest AMD Video/display driver. Completely remove previously installed drivers.  On Windows, the driver installation factory reset option should be used.
+1. Install the latest AMD Video/display driver. Completely remove previously installed drivers. On Windows, the driver installation factory reset option should be used.
 2. Unzip/Untar the download file. The directory includes the following:
    * Radeon Developer Service (RDS)
    * Radeon Developer Service CLI (RDS headless)
@@ -31,6 +31,7 @@ to reduce performance bottlenecks.
  * Vulkan
 
 ## Supported ASICs
+* AMD Radeon RX 7000 series
 * AMD Radeon RX 6000 series
 
 ## Supported Operating Systems
diff --git a/Release_Notes.txt b/Release_Notes.txt
@@ -1,9 +1,21 @@
-Radeon Raytracing Analyzer V1.0 07/26/2022
+Radeon Raytracing Analyzer V1.1 12/14/2022
 ------------------------------------------
 
-V1.0
+V1.1 Changes
 ------------------------------------
-This is the first public release of the Radeon Raytracing Analyzer.
+1) Addition of an axis-free camera.
+2) Camera placed at 45 degrees above the scene on trace load.
+3) Support for rebraided instances:
+  a) Coloring mode to show which instances are rebraided.
+  b) Allow selection of rebraided siblings.
+4) Support for split triangles:
+  a) Improved selection.
+  b) Coloring mode to show which triangles are split.
+  c) Sibling triangles shown and selectable from the UI.
+5) The 'Frustum cull ratio' in the settings has been replaced with "Small object culling". This should be more intuitive.
+6) Additional fields added to the instance and triangles tables.
+7) Keyboard shortcuts added for all panes on the Welcome and Settings lists. Some keys have also been remapped to avoid conflict with the Adrenaline software. See the documentation or keyboard shortcuts pane for details.
+8) Bug/stability fixes.
 
 Known Issues
 ------------------------------------
@@ -15,3 +27,9 @@ Known Issues
 (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.
 
+Release Notes History
+------------------------------------
+
+V1.0
+------------------------------------
+This is the first public release of the Radeon Raytracing Analyzer.
diff --git a/documentation/source/blas_instance_list.rst b/documentation/source/blas_instance_list.rst
@@ -10,11 +10,21 @@ Above the table is the base address of the BLAS used by all the instances.
 
 The following fields are displayed:
 
-* Instance address – The virtual address for the instance node within the TLAS.
+* Instance index - The API index for the instance.
 
-* Instance offset – The offset for the instance node within the TLAS.
+* Instance address – The virtual GPU address for the instance node within the TLAS.
 
-* Instance mask - The mask specified for the instance node.
+* Instance offset – The relative address for the instance node with respect to the TLAS address.
+
+* Instance mask - The mask specified for the instance node determining which trace ray calls will interact with it.
+
+* Flip facing - Instance flag specifying whether triangles front face should be inverted.
+
+* Force opaque - Instance flag specifying if this instance should be opaque regardless of geometry flags.
+
+* Force no opaque - Instance flag specifying if this instance should be non-opaque regardless of geometry flags.
+
+* Rebraid sibling count - If this instance was split into multiple instance nodes by the driver, this is how many sibling instance nodes this instance has.
 
 * X Position – The X-position of the instance in the scene.
 
@@ -30,11 +40,4 @@ sorting is in ascending or decending order.
 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
-positional information in the table; if an instance is used more than once,
-each instance will have a unique position. If there are duplicate positions,
-then there are multiple instances at the same world position, which is
-redundant; the duplicates can be removed.
-
-In some cases, the positions can all be 0. This just means that the instance
-has been created in world-space co-ordinates and does not need to be translated.
-This is typically done when only one instance of a BLAS is used in a scene.
+position and transform matrix in the table.
diff --git a/documentation/source/blas_list.rst b/documentation/source/blas_list.rst
@@ -17,19 +17,19 @@ The following fields are displayed:
 
 * Build type - The state of the FastTrace/FastBuild build flags.
 
-* Instances – The number of instances of the given BLAS within the parent TLAS.
+* Instances – The number of instances of the given BLAS in all TLASes.
 
 * Nodes – The total number of nodes in the BLAS, including leaf nodes.
 
 * Boxes – The total number of box nodes within the BLAS, including both Box16 and Box32.
 
-* 32-bit boxes – The total number of 32-bit box nodes in the BLAS.
+* 32-bit boxes – The total number of box nodes with 32-bit floating point precision bounding boxes in the BLAS.
 
-* 16-bit boxes – The total number of 16-bit box nodes in the BLAS.
+* 16-bit boxes – The total number of box nodes with 16-bit floating point precision bounding boxes in the BLAS.
 
 * Triangle nodes – The total number of triangle nodes within the BLAS.
 
-* Procedural nodes – The total number of procedural nodes within the BLAS.
+* Procedural nodes – The total number of AABB nodes within the BLAS.
 
 * Memory usage - The amount of GPU memory used to store this BLAS.
 
diff --git a/documentation/source/blas_viewer.rst b/documentation/source/blas_viewer.rst
@@ -44,3 +44,35 @@ selected triangle node.
 On the right are the same rendering and camera controls as seen in the TLAS pane; the functionality of
 these are nearly identical. The only difference is that there is no option to show instance transforms
 in the BLAS pane.
+
+.. _triangle-splitting-label:
+
+Triangle splitting
+~~~~~~~~~~~~~~~~~~
+Triangle splitting is another driver optimization that can be used if a triangle isn't axis aligned. This
+can result in a lot of empty space in the bounding volume. In this case, the triangle is split into
+smaller triangles, each with a smaller bounding volume. This reduces the triangle-area to bounding volume
+ratio.
+
+It should be noted that all split triangles will share the same 3 triangle vertices, and parts of the
+triangle will lie outside of the split triangle bounding volume. This can be seen with geometry rendering
+(below).
+
+.. image:: media/blas/split_triangles_1.png
+
+Image (a) Shows the bounding volume around the entire triangle geometry. Notice that this triangle is about
+45 degrees to one of the axes; the unused space in the bounding volume can be clearly seen. Images (b) and (c)
+show the individual split triangles making up the triangle geometry in (a).
+
+Since ray tracing deals with bounding volumes, only the part of the triangle inside the bounding volume
+will be considered. This can be seen with the traversal rendering, where only the area of the triangle inside
+the bounding volume is visible (below).
+
+.. image:: media/blas/split_triangles_2.png
+
+These 2 images are from the same scene, but seen from a slightly different angle.
+
+When a split triangle is selected, the left-side pane will indicate that the triangle is split, as seen below.
+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
@@ -5,4 +5,9 @@ The first thing you will need to do is generate a BVH trace. 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.
 This can be obtained from within the Radeon Developer Panel or from the link
-on the Radeon Raytracing Analyzer “Welcome” view.
+on the Radeon Raytracing Analyzer “Welcome” view. The documentation is also
+available online at:
+http://radeon-developer-panel.readthedocs.io/en/latest/
+
+This documentation can also be found online at:
+http://radeon-raytracing-analyzer.readthedocs.io/en/latest/
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.0.0'
+version = u'1.1.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0'
+release = u'1.1.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
@@ -4,7 +4,7 @@ The Radeon™ Raytracing Analyzer (RRA)
 The Radeon Raytracing Analyzer is a tool designed to help developers improve the raytracing performance on AMD Radeon 6000 series GPU's. The tool
 focuses on the visualization of Acceleration Structures, which in our case consist of Bounding Volume Hierarchies. RRA allows the developer to
 visualize the bounding box hierarchies, and related scene geometries, to quickly identify issues with the bounding volume hierarchies, such as
-overlaping bounding volumes and sparse geometry layout within bounding volumes. Once identified, the developer can revisit their BVH generation
+overlapping bounding volumes and sparse geometry layout within bounding volumes. Once identified, the developer can revisit their BVH generation
 strategy.
 
 This document describes how the Radeon Raytracing Analyzer can be used to examine a bounding volume hierarchy.
@@ -20,6 +20,8 @@ Supported graphics APIs, RDNA hardware, and operating systems
 
 \ **Supported RDNA hardware**
 
+-  AMD Radeon RX 7000 series
+
 -  AMD Radeon RX 6000 series
 
 \ **Supported Operating Systems**
@@ -28,8 +30,6 @@ Supported graphics APIs, RDNA hardware, and operating systems
 
 -  Windows® 11
 
--  Ubuntu 20.04 LTS (Vulkan only)
-
 -  Ubuntu 22.04 LTS (Vulkan only)
 
 Radeon Raytracing Analyzer - Quick Start
diff --git a/documentation/source/media/blas/blas_instances_1.png b/documentation/source/media/blas/blas_instances_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:53d3ddb69d6c0fb632a12aa6d82e1529db5491f892cb4ef514eca32066f98b10
-size 99255
+oid sha256:b234ae6b2b007c6a27b1085284a0341c8f6f5289aa0a16f2c2320f07b472bb9e
+size 96066
diff --git a/documentation/source/media/blas/blas_properties_1.png b/documentation/source/media/blas/blas_properties_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:72bbfd8a7f77cf18c6ab159b8d5a2ceba3d8c10366b2b0ce2a9b8f68f447b0cf
-size 35112
+oid sha256:5624dca375eaac128d6d759c0dbb46500f8b9a31f02df4940646dcf5a53ade1f
+size 48726
diff --git a/documentation/source/media/blas/split_triangles_1.png b/documentation/source/media/blas/split_triangles_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ebb9c57ea1e8879e95fc87bee5405a568a16567e07e9592b6bf601e923db74bb
+size 22081
diff --git a/documentation/source/media/blas/split_triangles_2.png b/documentation/source/media/blas/split_triangles_2.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3728f639b83424613e9b865e49f4493394fd449fd1337fc3a20567c4162f90b1
+size 28587
diff --git a/documentation/source/media/blas/split_triangles_stats_1.png b/documentation/source/media/blas/split_triangles_stats_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:50d5e8e855ca8a093456d44f637c22a1874b69dbb97b5a2795e9126a5f9e0618
+size 28577
diff --git a/documentation/source/media/blas/triangles_1.png b/documentation/source/media/blas/triangles_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6b3064e1eae99d887c1364582df5e94873dd49c8825430eac340d6900706ba52
-size 50321
+oid sha256:9ed786d912a5e4a779d253e11b9032792014aff5ba8dce16fdfd7e22aa2891e2
+size 130211
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:fd43a4834890d04d534baa0caf68f8ad7af876c2eb82cfc5cb28dd2a80fa8870
-size 32606
+oid sha256:d525804735a18ae111588bd1b4d2cfd3e570e7a350429c4beeb8509b5606bd68
+size 53881
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:0c2024d488e3b46a431371462af0673c3beebe0822f8b71927e04bcc85cac6c9
-size 50757
+oid sha256:1eb383c55341fc02e36a703aa6b7de7b514f8557018a4dabd4d94a35cdd81be2
+size 73202
diff --git a/documentation/source/media/tlas/popout_view_1.png b/documentation/source/media/tlas/popout_view_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:f4c06f66191841470b3af0df414ac165d78bf52478427a42242ce8004807af28
-size 21637
+oid sha256:6d2df503919c2e322a75111885441a67862e0cea95d318caaef3e1e3d1391dd5
+size 33212
diff --git a/documentation/source/media/tlas/popout_view_2.png b/documentation/source/media/tlas/popout_view_2.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:8c251015123f32e9ef591a73e11a5384b4ea86b0e668bde5d2f9fb81c2bb7823
-size 24010
+oid sha256:2cd53e303a61e5b6c25b06fef85bb08f5bfe6ee12c84e3f50a50f061d0b8af3a
+size 31147
diff --git a/documentation/source/media/tlas/popout_view_3.png b/documentation/source/media/tlas/popout_view_3.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:620fb310c36b5769a02818b59b9cc241f077e462b1d9e19c7f884bd52a61d892
-size 11912
+oid sha256:7e00f413f429784fd1fca3e38a0c5729b066851c0cc0bb4519ce8345b0683608
+size 16597
diff --git a/documentation/source/media/tlas/rebraiding_stats_1.png b/documentation/source/media/tlas/rebraiding_stats_1.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9ed6f1af7f797476ed2509ee970c6979fb2fff8c2ae498d64e5c795925211fe0
+size 32381
diff --git a/documentation/source/media/tlas/tlas_instances_1.png b/documentation/source/media/tlas/tlas_instances_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:29a8cb391dcc8a62d9e985ef842b4cc29447624ff0b235df2c3e3af23b49662b
-size 83330
+oid sha256:a712ef41fcd53e2a2c082e8f4da7bdef6427357e043da66df370bebeaaa6194e
+size 141636
diff --git a/documentation/source/media/tlas/tlas_properties_1.png b/documentation/source/media/tlas/tlas_properties_1.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:a372f47b96877c4437c4f022b79f9f05a12ad099c8f8581216061d6d4e6bf451
-size 29326
+oid sha256:6471bc186932db2e6bd97271c43f0b0e94d5a2d7f43f01173518c979921aa9f0
+size 34835
diff --git a/documentation/source/overview.rst b/documentation/source/overview.rst
@@ -8,16 +8,31 @@ a trace.
 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.
 
-The **Total Memory** is the memory used for all the acceleration structures.
+* **Total TLASes** is the total number of top-level acceleration structures in the trace.
 
-The **TLAS List** shows a list of all Top-level acceleration structures in
+* **Total BLASes** is the total number of bottom-level acceleration structures in the trace.
+
+* **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.
+
+* **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.
+
+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 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
   memory used. The total here is the combined memory used by the TLAS and all the BLASes
   it references. TLASes can, and do, share BLASes so the totals for all the TLASes can
-  sometimes be larger that the total memory displayed above.
+  sometimes be larger than the total memory displayed above.
 
 * The right section displays some useful statistics for each TLAS are shown so each
   can be easily identified.
diff --git a/documentation/source/settings.rst b/documentation/source/settings.rst
@@ -19,9 +19,9 @@ around the scene. The speed is altered using a slider on the viewer panes. The d
 maximum speed is optimal in most cases but for very large scenes, it may be useful
 to increase this value.
 
-**Frustum cull ratio** Objects which take small amounts of screenspace are culled for
-efficiency. Lowering this ratio will allow further objects to be rendered at the cost
-of rendering time. The default value is sufficient for most needs.
+**Small object culling** Objects which take small amounts of screen space are culled for
+efficiency. Moving the slider closer to the high setting will result in more culling
+and better performance.
 
 **Decimal precision** The number of decimal places that floating point values throughout
 the app will be displayed at. Hovering the mouse over a floating point value will display
diff --git a/documentation/source/tlas_instance_list.rst b/documentation/source/tlas_instance_list.rst
@@ -8,11 +8,21 @@ all instances in the selected TLAS.
 
 The following fields are displayed:
 
-* Instance address – The virtual address for the instance node within the TLAS.
+* Instance index - The API index for the instance.
 
-* Instance offset – The offset for the instance node within the TLAS.
+* Instance address – The virtual GPU address for the instance node within the TLAS.
 
-* Instance mask - The mask specified for the instance node.
+* Instance offset – The relative address for the instance node with respect to the TLAS address.
+
+* Instance mask - The mask specified for the instance node determining which trace ray calls will interact with it.
+
+* Flip facing - Instance flag specifying whether triangles front face should be inverted.
+
+* Force opaque - Instance flag specifying if this instance should be opaque regardless of geometry flags.
+
+* Force no opaque - Instance flag specifying if this instance should be non-opaque regardless of geometry flags.
+
+* Rebraid sibling count - If this instance was split into multiple instance nodes by the driver, this is how many sibling instance nodes this instance has.
 
 * X Position – The X-position of the instance in the scene.
 
@@ -29,7 +39,3 @@ 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.
-
-In some cases, the positions can all be 0. This just means that the instance
-has been created in world-space co-ordinates and does not need to be translated.
-This is typically done when only one instance of a BLAS is used in a scene.
diff --git a/documentation/source/tlas_viewer.rst b/documentation/source/tlas_viewer.rst
diff --git a/documentation/source/triangle_list.rst b/documentation/source/triangle_list.rst
