The Radeon™ Raytracing Analyzer (RRA)

The Radeon Raytracing Analyzer is a tool designed to help developers improve the raytracing performance on AMD Radeon 6000 and 7000 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 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.

Supported graphics APIs, RDNA hardware, and operating systems

Supported APIs

  • DirectX 12

  • Vulkan

Supported RDNA hardware

  • AMD Radeon RX 7000 series

  • AMD Radeon RX 6000 series

Supported Operating Systems

  • Windows® 10

  • Windows® 11

  • Ubuntu® 22.04 LTS (Vulkan only)

Radeon Raytracing Analyzer - Quick Start

How to generate a BVH scene

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 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/

Starting the Radeon Raytracing Analyzer

Start RadeonRaytracingAnalyzer.exe (this is the tool used to view RRA scene data).

How to load a scene

There are a few ways to load a scene into RRA.

  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…”

  3. Go to the “Welcome” view and click on a scene that you have previously loaded in the Recent list.

_images/welcome_1.png
  1. 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 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 scene file is on the disk.

_images/recent_traces_1.png
  1. 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

There are four main menus in the Radeon Raytracing Analyzer and each may have a number of sub-windows..

  1. START

    1. Welcome - Shows links to help documentation, and a list of recently opened scenes.

    2. Recent scenes - Displays a list of the recently opened scenes.

    3. About - Shows build information about RRA and useful links.

  2. OVERVIEW

    1. Summary - Gives an overview of the scene, showing the number of acceleration structures, the resources they use and their memory usage.

    2. Device configuration - Provides details of the GPU used to record the scene.

  3. TLAS

    1. Viewer - The main viewer for a top-level acceleration structure.

    2. Instances - Lists statistics for all instances referenced in the selected top-level acceleration structure.

    3. BLAS List - Lists statistics for all bottom-level acceleration structures referenced in the selected TLAS.

    4. Properties - Lists statistics and properties for the currently selected top-level acceleration structure.

  4. BLAS

    1. Viewer - The main viewer for a bottom-level acceleration structure.

    2. Instances - Lists statistics for all instances of the selected bottom-level acceleration structure.

    3. Triangles - Lists statistics for all triangles of the selected bottom-level acceleration structure.

    4. Geometries - Lists statistics for all geometries of the selected selected bottom-level acceleration structure.

    5. Properties - Lists statistics and properties for the currently selected bottom-level acceleration structure.

  5. RAY

    1. Dispatches - The main viewer for visualizing various types of dispatches that shot rays.

    2. Inspector - A viewer for inspecting rays and how they interact with the scene.

Settings

The settings tab is used to control global settings throughout the product. These settings are stored, and are persistent for all instances of RRA.

General

Check for updates If checked, the Radeon Raytracing Analyzer will alert you that a new version is available for download.

Camera reset If checked, the camera will reset to the starting position and orientation each time the camera’s control style is changed.

Viewer UI state If checked, certain elements of the viewer UI’s are persistent between RRA sessions. These are typically selections that are seldom changed. The following UI elements are shared between all viewers:

  • Culling mode

  • Up axis

  • Invert vertical

  • Invert horizontal

  • Continuous update

  • Projection mode

The following UI elements are saved per-view:

  • Control style

  • BVH coloring mode

  • Geometry coloring mode

  • Heatmap coloring mode

  • Traversal counter coloring mode

  • Rendering mode

  • Show geometry checkbox

  • Show axis-aligned BVH checkbox

  • Show instance transform checkbox (TLAS viewer only)

  • Show wireframe checkbox

  • Accept first hit checkbox

  • Cull back-facing triangles

  • Cull front-facing triangles

Automatic updates Check for updates to Radeon Raytracing Analyzer when starting the program.

Camera reset If enabled, the camera will reset position when the camera control style is changed.

Viewer UI state If enabled, the state of the TLAS, BLAS and RAY inspector panes will be remembered from the last session. Otherwise they will be reset to default settings. Some state, like camera movement speed, will not be remembered in either case.

TLAS/BLAS Node display Will allow the choice between showing the nodes in the treeviews on the viewer panes either by their GPU address, or by an offset.

Maximum traversal count Is used to set the maximum value of the traversal counter slider. The value can be lowered in the case where the scene has low counter values which will increase the resolution of the slider, or raised in the case where the traversal count of the scene exceeds the default value.

Maximum camera movement speed Sets the maximum speed of the camera when navigating around the scene. The speed is altered using a slider on the viewer panes. The default maximum speed is optimal in most cases but for very large scenes, it may be useful to increase this value.

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 its full precision through a tooltip.

_images/general_1.png

Themes and colors

The Radeon Raytracing Analyzer makes heavy use of coloring to display its information. This pane allows users to thoroughly customize those colors. These include being able to specify how to color geometry based on different attributes and showing node types using different colors.

The Bounding volume refers to the colors used to show the bounding volume wireframe when the “Volume type” BVH coloring mode is selected (coloring modes are described later).

The Wireframe coloring colors are used when displaying the wireframe between each triangle.

The Selected triangles is the color used in the BLAS view to show the currently selected triangle nodes. Note that the selected triangle color is only available in the geometry rendering mode.

The Background coloring refers to the 2 colors that are used to paint the viewer background. By default, it consists of a checkerboard. Making the 2 colors the same will result in a single solid color.

The Opacity coloring is used for the Opacity geometry coloring mode.

The Flag indication colors are the 2 colors used for the build flag geometry coloring modes, indicating if the build flag is enabled or disabled.

The Build type coloring combines the FastBuild and FastTrace flags. These colors are used for the fast build/trace geometry coloring mode. Specifying both build flags is improper API usage, but coloring it allows the user to spot potential errors.

The Instance force opaque/no-opaque combines the ForceOpaque and ForceNoOpaque flags. These colors are used for the opacity geometry coloring mode. Specifying both build flags is improper API usage, but coloring it allows the user to spot potential errors.

The Shader invocation coloring determines the colors of the ray tracing shaders shown in the donut chart on the Overview pane.

The Ray coloring determines the colors of the rays shown in the 3D view of the Ray inspector.

_images/themes_and_colors_1.png

Keyboard shortcuts

Here users will find the Keyboard shortcuts pane:

The Global navigation section refers to keystrokes that aid user navigation, and are always detected regardless of which pane is visible.

The Camera hotkeys shortcuts are specific to moving and panning operations that can be performed with the camera (see below).

The Render hotkeys shortcuts enable certain rendering operations to be toggled, such as wireframe rendering.

The Global hotkeys section refers to any hotkeys available anywhere in the product.

_images/keyboard_shortcuts_1.png

All users are encouraged to adopt these keystrokes while using RRA.

UI Navigation

In an effort to improve workflow, RRA supports keyboard shortcuts and back and forward history to quickly navigate throughout the UI.

Back and forward navigation

RRA tracks navigation history, which allows users to navigate back and forward between all of RRA’s panes. This is achieved using global navigation hotkeys shown above, or the back and forward buttons on all panes in the top left below the file menu.

Currently, back and forward navigation is restricted to pane switches.

The OVERVIEW windows

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 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 scene.

  • 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 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 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 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 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 than the total memory displayed above.

  • The right section displays some useful statistics for each TLAS are shown so each can be easily identified.

_images/summary_1.png

Clicking on the TLAS name or address (text in blue) will navigate to the TLAS Viewer pane.

If dispatches was enabled from the Radeon Developer Panel, the Dispatch list shows 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 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 and the number of instance intersections. The size of these values relative to the size of the dispatch may give the user an indication of the efficiency of a particular dispatch.

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.

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.

_images/device_config_1.png

The TLAS windows

These panes show information about a top-level acceleration structure and its associated bottom-level acceleration structures.

The TLAS Viewer

The top-level acceleration structure consists of a bounding volume hierarchy. Each bounding volume will consist of child bounding volumes or instances. An instance is simply a set of geometry inside a bounding volume. There can be multiple instances in a scene. Each instance corresponds to a BLAS structure, described below. The TLAS pane will therefore show a rendering of the complete scene inside the very top bounding volume. There can be multiple TLAS’s in a scene.

Each viewer pane in RRA has a UI reset button, in the top-right corner of the UI:

_images/reset.png

This allows the rendering and camera controls, and coloring modes to be reset to their factory defaults. Certain UI controls are shared between viewers, so resetting these on one viewer pane will be reflected on the other viewer panes. Examples of these would be the up axis and inverting the horizontal or vertical axes, since these parameters are considered global to the scene. The movement speed slider isn’t currently reset since its initial value is calculated depending on the scene size, so smaller scenes will have a smaller movement speed.

An example TLAS viewer pane is shown below:

_images/tlas_viewer_1.png

The view is split into 3 sections:

The left section shows a summary of the currently selected TLAS:

  1. The TLAS dropdown allows selection of which TLAS to view.

  2. The Expand tree text is a toggle button and clicking it will expand the treeview so all items in the tree are visible. Pressing it again will collapse the treeview.

  3. The treeview will show the structure of the TLAS. In a TLAS, there are box nodes (either Box16 or Box32 for 16-bit or 32-bit floating point values, respectively). Each box node can contain up to 4 child nodes, which can be box nodes or instance nodes. Instance nodes are leaf nodes. An instance node contains a reference to a bottom-level acceleration structure which contains the geometry to render.

    1. Selecting a node will highlight the node and all its child nodes in the treeview. Any instance nodes selected will be shown selected in the scene as having a highlighted wireframe around the triangles. This wireframe coloring can be customized in the Settings Themes and colors pane.

    2. If a node has child nodes, it will have a ‘>’ to the left of it. Clicking this will open the node and show the child nodes. Typically all box nodes will have child nodes.

    3. Nodes can be shown/hidden using the checkbox for that node, located to the left of the node name. Any hidden nodes will be grayed out in the treeview and will not be rendered in the scene. This allows the user to just see the geometry of interest.

    4. Double-clicking on an instance node will open the BLAS it references in the BLAS pane.

  4. The section below the treeview gives details about the currently selected node, including the parent node and extents. Clicking the parent address will select the parent node.

  5. If the selected node is an instance then instance specific information passed to the API will be displayed, including the instance transform, instance mask, flags, and the BLAS address. Clicking the BLAS address will navigate to that BLAS in the BLAS tab. The position of the instance can be found in the last column of the instance transform, separated by a vertical bar.

The left-pane can be resized by moving the mouse over the area of the screen where the left pane and view pane meet. The cursor will change, showing the pane can be resized by clicking and dragging the mouse.

The center section shows a rendering of the scene:

In the center is a rendering of the scene. The scene will consist of a series of bounding volumes with geometry contained within that volume. Various display modes can be altered by the user to change how the scene is rendered.

The viewport camera can be manipulated using a mouse and keyboard using a preset control style (described later).

Pressing the “R” key in all camera modes will reset the camera to its default position. This is useful to recover from disorientation such as losing sight of the scene in the 3D view.

It is possible to select an instance within the scene by clicking on any mesh within the viewport. Multiple instances can be selected by holding down the Ctrl key while clicking. The TLAS hierarchy tree view will expand as necessary to focus on the selected instance. Pressing the “F” key will focus the camera on the selected object in the scene. If multiple instances are selected, the view will be adjusted so all selected instances are visible.

An orientation gizmo is overlaid on the scene, in the top-right corner. This shows how the coordinate axes are aligned with the scene.

A context menu can be displayed by right-clicking on the scene.

_images/context_menu_1.png

The list of options are:

  1. Add instance under mouse to selection - Select the instance under the mouse. It is possible to have more than one instance selected. One possible use-case is to select the instances that are of interest and hide everything else in the scene.

  2. Deselect all - Deselect any instances that are selected.

  3. Focus on selection - Focus the camera to look at the selected instances. If more than one instance is selected, the camera will pan back to show all selected instances. Pressing the “F” key will accomplish the same thing.

  4. Hide selected - Hide any selected instances in the scene. Pressing the “H” key will accomplish the same thing. By using the mouse to select instances and the “H” key to hide them, the scene can be quickly cleared of instances that are not relevant or obscuring areas of interest.

  5. Select all visible - Select all visible instances in the scene.

  6. Show everything - Make everything in the scene visible. Pressing the “J” key will accomplish the same thing.

  7. Show only selection - Show only instances that are currently selected; all other instances will be hidden.

Below the scene is a segmented bar:

_images/depth_slider.png

This tree depth slider is used to select which tree depths to show bounding volumes for. The default has the first segment selected, indicating that only the highest level bounding volume is to be shown.

To use the slider, click on a segment. Holding the mouse button and dragging will allow selection of the depth range.

The minimum and maximum tree depths selected are also shown at either side of the slider. In this case here, just tree level 0 (the root) is shown, so the range is from 0 to 0.

The right section allows control over the rendering and camera:

On the right is a ‘Show/hide controls’ button. It can be clicked on and will open a side panel to the right of the rendering. This opens the view controls pane:

_images/popout_view_1.png

Rendering controls

The Rendering controls section includes checkboxes to control how the scene is rendered.

The rendering mode radio buttons allow selection of the rendering mode. The default is the Geometry rendering mode, showing the triangles which make up the scene. An example of this rendering mode can be seen at the beginning of this section.

The Traversal counter mode is a display mode that counts ray intersections with elements from within the acceleration structure. Examples would include triangle/box hit and test counts. See the section below for more information on the traversal counters.

In geometry rendering mode, there are 4 checkboxes that control what is visible in the scene:

  • Show geometry will only draw the scene if enabled. Switching it off will allow the bounding volumes or wireframes to be seen more easily.

  • Show axis aligned BVH will display the bounding volumes overlaid as wireframes if enabled. This bounding volume will be axis aligned in the TLAS.

  • Show instance transform will display the instance bounding volume overlaid as a dashed wireframe. This bounding volume has the instance transform applied, so is effectively in BLAS-space.

  • Show wireframe will show a wireframe overlay over the geometry, which will allow the individual triangles to be seen.

Finally, a Culling mode combo box is available. In geometry rendering mode, this is the standard frontface/backface/none culling mode which only affects the viewport and does not reflect the state of your application when it was captured.

In traversal counter rendering mode, the controls are slightly different, as seen below:

_images/popout_view_3.png
  • The Accept first hit checkbox simulates the accept first hit ray flag that can be passed to the trace ray invocation in the shader. The traversal algorithm visualized by the heatmap will be altered based on this flag.

  • The Box sort heuristic describes how box nodes are sorted during traversal. This determines the order in which box nodes are checked for intersections. It’s dependent on ray flags and system configuration.

    • The Closest sort heuristic checks the closest box nodes first for intersections.

    • The Middle point sort heuristic checks the box nodes with the closest centers first for intersections.

    • The Largest sort heuristic checks the largest box nodes first for intersections.

  • The Counter range slider allows the user to set a minimum and maximum traversal count limit to display on in the heatmap. The results of changing the slider values can be seen instantly in the viewport.

    • The Counter range slider has a range between 0 and 1000 but the limit can be changed in the General section of the settings under Maximum traversal count.

    • The values under the slider are the current minimum and maximum values of the 2 slider handles, as well as the average of the traversal counts of each pixel visible in the viewport.

  • The Counter histogram above the counter slider shows the distribution of traversal counts in the current viewport. The leftmost end of the histogram is 0 and the rightmost end is the maximum slider traversal count set in the settings. The histogram lines up with the slider below it, where each vertical slice represents the same traversal count for the slider and the histogram.

  • Clicking on the Wand icon will automatically adjust the slider values to the minimum and maximum pixel values visible in the viewport.

  • The Continuous update checkbox, when enabled, will automatically adjust the counter range slider to the minimum and maximum pixel values visible as the viewport camera is moved around. It saves the work of clicking on the wand icon to update the color range of the scene. NOTE: When Continuous update is enabled, the wand icon is disabled.

The Show axis aligned BVH, Show instance transform, and Show wireframe checkboxes are also present, along with the culling mode combo box.

In traversal counter rendering mode, the selected culling mode plays the part of the frontface/backface triangle culling flags passed to the trace ray call in the shader. This means that the culling behavior can be overridden or modified for each instance via instance flags.

In other words, the instance flags set up for the instance in the application will override the UI settings, and not the other way round.

For example, the culling mode ray flags set up in RRA will only have an effect if D3D12_RAYTRACING_INSTANCE_FLAG_TRIANGLE_CULL_DISABLE or VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR are not set.

Camera controls

The Camera controls section allows selection of the camera controls.

  • A combo box allows selection of the camera control style. This can be either CAD control style, FPS control style or Axis-free control style and is chosen depending on the control style the user is most familiar with, whether it be a modeling (CAD) package or a gaming application (FPS). The Axis-free camera does not constrain the camera by orienting itself with a global up-axis. This is useful for applications that do not have a natural up-axis, like space exploration games. The camera setting is global, so changing the camera style on the TLAS viewer pane selects the same camera style on the BLAS viewer pane, and vice versa. Switching from CAD control style to FPS control style will not retain the CAD focal point, so upon switching back to CAD you will need to focus on an instance again to revolve the camera around it.

_images/popout_view_2.png
  • The Mouse and keyboard icon will display a list of all the valid hotkeys for the currently 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.

  • 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 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.

  • The Camera position edit-boxes show the current camera position. These values can be edited manually if needed. The reset icon can be clicked to move the camera to the origin.

  • The Field of view slider changes the camera’s field of view.

  • 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.

Traversal counter visualization

Given the complexity of acceleration structures and the specifics of the ray traversal algorithms that operates on these structures, it can be very difficult to evaluate the performance cost of a given scene.

The traversal counter visualization will help simplify this complexity and help reduce traversal count signatures by editing BLASes and repositioning of instances in the TLAS.

  • The counters are calculated on-the-fly and are not the same as those provided by the Radeon GPU Profiler.

  • RRA counters terminate on closest hit and ignore any subsequent rays that are launched.

  • RRA also counts custom intersection volumes as a single unit.

An example of a typical scene using the traversal counters is shown below.

_images/loop_count.png

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 alter the coloration of the scene. The colors are displayed as a heatmap, so blue represents a low counter value and red represents a higher counter value by default. Generally, the lower the counter value, the more optimal the scene will be. This visualization shows how costly ray traversals are, but does not account for TLAS and BLAS build times which also affect overall performance.

There are several different counter types to choose from:

  • The Loop count is the number of iterations the ray performs on the acceleration structure. It allows the user to identify parts of the acceleration structure that are the most taxing for the rays. The loop count will have the largest counter range of all the counters.

  • The Instance hit is the number of instances that the ray has hit. This is useful in terms of how instance positioning affects traversal time. As a ray traverses into the scene, it is optimized to discard bounding volumes as needed. A ray can discard a volume if a triangle closest hit candidate has been found and the volume is behind the closest hit candidate.

    When a ray hits an instance node, it has to context switch into the BLAS and traverse the BLAS to get a closest-hit triangle and compare this to the current closest-hit triangle, which may be from a different TLAS node. In addition, if instance nodes overlap, the ray must wait until each instance is fully checked.

    It is therefore essential to arrange instances so that context switching into BLAS nodes is minimized.

  • The Box volume hit, Box volume miss, and Box volume test count how many box nodes were hit, missed, and tested, respectively. The number of tests is equal to the sum of the number of hits and misses. Some parts of the scene may be denser depending on the perspective. The dense parts may overlap so the ray may not be able to discard volumes.

  • The Triangle hit counter is the number of triangles that have been used as the closest hit candidate. As the ray traverses an acceleration structure, it may encounter triangles in an unspecified order. If the ray hits a triangle, it will compare this triangle with the current closest hit triangle. If there isn’t a closest hit triangle, this triangle will be assigned as the closest hit. The Triangle miss is the number of triangles that have been tested but were not a closest hit. The Triangle test is the sum of hits and misses.

Coloring modes

The coloring modes are available in a row above the scene rendering.

  1. BVH Coloring allows the bounding volume wireframes to be painted depending on a number of different parameters. The following BVH coloring modes are currently supported within the TLAS viewer:

    • Volume type

      The bounding volume coloring is based on the node types, allowing box, triangle, procedural geometry and instance nodes to be distinguished from one another. The selected BVH is also colored differently. These colors can be configured from the Themes and colors settings pane.

    • Tree depth

      Each bounding volume is assigned a color based on how deep in the hierarchy it is.

  2. Geometry Coloring is only available for the Geometry rendering mode and allows the scene to be painted depending on a number of different parameters, for example, each BLAS can be colored differently enabling the user to see if their grouping of objects in the scene is optimal.

    Some of these coloring modes use a heatmap coloring scheme, some use fixed colors and some have colors that are selectable from the Themes and colors pane. The type of heatmap can be selected from the Heatmap combo box to the right of the Geometry coloring combo box. This is described in a bit more detail later on.

    Several coloring modes mention the surface area heuristic (SAH) of triangles. This is a value between 0 and 1 which is proportional to the probability a ray will intersect with a triangle given that it intersects with its bounding box, where 0 (bad) means low probability and 1 (good) means high probability. Triangles with low SAH often are long, skinny, and not axis-aligned in BLAS space.

    The following geometry coloring modes are supported within the TLAS viewer, and its coloring scheme:

    • Average SAH (BLAS)

      A heatmap showing the average surface area heuristic of all triangles in a BLAS.

    • SAH (Triangle)

      A heatmap showing the surface area heuristic of each individual triangle.

    • Minimum SAH (BLAS)

      A heatmap showing the minimum surface area heuristic of all triangles in a BLAS.

    • Mask (Instance)

      A unique color for each combination of instance mask flags.

    • Opacity (Geometry)

      A color showing the final opacity of each geometry as a function of instance and geometry flags. These colors can be configured in the Themes and colors section of the Settings under ‘Opacity coloring’.

    • Opacity (Geometry)

      A color showing the presence of the opacity flag. These colors can be configured in the Themes and colors section of the Settings under ‘Opacity coloring’.

    • Force opaque / no opaque flag (Instance)

      Combines the ForceOpaque and ForceNoOpaque instance flags, giving 4 possible color combinations. These colors can be configured in the Themes and colors section of the Settings under ‘Instance force opaque/no-opaque’.

    • Geometry index (Geometry)

      A unique color for each geometry index within a BLAS.

    • Fast build/trace flag (BLAS)

      Combines the FastBuild and FastTrace build flags, giving 4 possible color combinations. These colors can be configured in the Themes and colors section of the Settings under ‘Build type coloring’.

    • Allow update flag (BLAS)

      Shows whether the ‘AllowUpdate’ build flag is enabled. These colors can be configured in the Themes and colors section of the Settings under ‘Build type coloring’.

    • Allow compaction flag (BLAS)

      Shows whether the ‘AllowCompaction’ build flag is enabled. These colors can be configured in the Themes and colors section of the Settings under ‘Flag indication colors’.

    • Low memory flag (BLAS)

      Shows whether the ‘LowMemory’ build flag is enabled. These colors can be configured in the Themes and colors section of the Settings under ‘Flag indication colors’.

    • Facing cull disable flag (Instance)

      Shows whether the ‘FacingCullDisable’ instance flag is enabled. These colors can be configured in the Themes and colors section of the Settings under ‘Flag indication colors’.

    • Flip facing flag (Instance)

      Shows whether the ‘FlipFacing’ instance flag is enabled. These colors can be configured in the Themes and colors section of the Settings under ‘Flag indication colors’.

    • Tree level (Triangle)

      A heatmap showing the triangle’s depth within the BVH.

    • Max tree depth (BLAS)

      A heatmap showing the maximum tree depth of each BLAS.

    • Average tree depth (BLAS)

      A heatmap showing the average tree depth of each BLAS.

    • Unique color (BLAS)

      A unique color for each BLAS.

    • Unique color (Instance)

      A unique color for each instance.

    • Instance count (BLAS)

      A heatmap showing how many instances each BLAS has.

    • Triangle count (BLAS)

      A heatmap showing the triangle count of each BLAS.

    • Rebraiding (Instance)

      Shows which instances have been rebraided by the driver. See the section on Rebraiding below for more information.

    • Triangle splitting (Triangle)

      Shows which triangles have been split by the driver. See the section on Triangle splitting in the BLAS viewer section for more information.

    • Lighting

      Directionally lit shading.

    • Technical drawing

      Directionally lit Gooch shading.

  3. 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. There are a number of counters available and details of each can be obtained by opening up the combo box and mousing over each option which will display a tooltip. All of the traversal counter coloring modes use the heatmap coloring scheme.

    The following counters are supported:

    • Loop count

      The number of iterations the ray performs on the acceleration structure.

    • Instance hit

      The number of instances that are hit before the closest hit is found.

    • Box volume hit

      The number of volumes the ray intersects with.

    • Box volume miss

      The number of volumes the ray has been tested with but doesn’t intersect with.

    • Box volume test

      The number of volumes the ray is tested with. This is the sum of box hits and misses.

    • Triangle hit

      The number of triangles which have been considered the closest hit candidate.

    • Triangle miss

      The number of triangles which have been tested but not considered the closest hit candidate.

    • Triangle test

      The number of triangles which the ray has been tested against. This is the sum of triangle hits and misses.

  4. Heatmap selection allows which heatmap to use. The default heatmap uses a Temperature scheme where the colors vary from red to green to blue. The Spectrum scheme uses more of the visible color spectrum, giving a wider range of colors. The Viridis and Plasma color schemes are perceptually uniform heatmaps. Each heatmap will show the scene slightly differently with some heatmaps showing certain areas of the scene better than others.

UI Persistent state

The state of some of the lesser-used user interface controls is remembered between RRA sessions. This is to try to avoid having to configure the UI each time RRA is loaded, particularly in the case where the same application is being analyzed between sessions. The persistent state can be toggled from the settings, described in the Settings section.

Above the ‘Show/hide controls’ text button in the top-right of the view is an icon that allows the UI to be reset to its default settings. There is a similar button on the BLAS Viewer pane. Hoving over the button will display a help tooltip. Clicking on the button will reset the persistent UI controls back to their defaults. Since some elements are shared between the BLAS and TLAS viewers, both the TLAS and BLAS controls will be reset, regardless of which reset button was pressed.

The following UI elements are shared between all viewers:

  • Culling mode

  • Up axis

  • Invert vertical

  • Invert horizontal

  • Continuous update

  • Projection mode

The following UI elements are saved per-view:

  • Control style

  • BVH coloring mode

  • Geometry coloring mode

  • Heatmap coloring mode

  • Traversal counter coloring mode

  • Rendering mode

  • Show geometry checkbox

  • Show axis-aligned BVH checkbox

  • Show instance transform checkbox (TLAS viewer only)

  • Show wireframe checkbox

  • Accept first hit checkbox

  • Cull back-facing triangles

  • Cull front-facing triangles

The movement speed and field of view states currently do not persist between RRA sessions.

Instance mask filter

The instance mask filter allows setting an 8-bit instance mask to simulate the effect of the InstanceInclusionMask argument of TraceRay() in HLSL or the cullMask argument of traceRayEXT() in GLSL. In both geometry rendering mode and traversal rendering mode, the instances not included in the mask will be culled.

_images/instance_mask_filter.png

The mask can be set either by clicking the individual bits to toggle them on the left side, or by typing or pasting in a hex value on the right side.

Rebraiding

Rebraiding is a TLAS build strategy used by the driver. When the build algorithm determines that the combination of an instance transform with a particular BLAS will yield a small SAH number it may decide to rebraid that instance to reduce the amount of empty bounding box volume. A rebraided instance will be split into the number of immediate child nodes of the BLAS root node. The instances that are split will retain all the data used by the original instance, however, the extents of each instance will now use the extent of the BLAS node it corresponds to. Rebraiding is an optimization done automatically by the driver, so the application developer has no direct control over it.

Rebraided instances will be clearly marked on the left-side pane when an instance is selected, as seen below. If the instance has been rebraided, the sibling nodes will be listed, allowing for easy selection.

_images/rebraiding_stats_1.png

The TLAS Instances Tab

The TLAS Instances tab displays a read-only table of properties and statistics for all instances in the selected TLAS.

_images/tlas_instances_1.png

The following fields are displayed:

  • Instance index - The API index for the instance.

  • Instance address – The virtual GPU address for the instance node within the TLAS.

  • 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.

  • Cull disable - Instance flag specifying if the cull mode is disabled.

  • 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.

  • Y Position – The Y-position of the instance in the scene.

  • Z Position – The Z-position of the instance in the scene.

  • Transform[x][y] - The instance transform, comprising of the rotation and scaling components.

The columns can be sorted by clicking on them. The arrow in the heading shows if sorting is in ascending or descending 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 position and transform matrix in the table.

The BLAS List

The BLAS List tab displays a read-only table of BLAS properties and statistics.

_images/blas_list_1.png

The following fields are displayed:

  • Address – The virtual address for the BLAS structure in application memory.

  • Allow update - The state of the AllowUpdate build flag.

  • Allow compaction - The state of the AllowCompaction build flag.

  • Low memory - The state of the LowMemory build flag.

  • Build type - The state of the FastTrace/FastBuild build flags.

  • 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 box nodes with 32-bit floating point precision bounding boxes 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 AABB nodes within the BLAS.

  • Memory usage - The amount of GPU memory used to store this BLAS.

  • Root SAH – The computed surface area heuristic for the BLAS.

  • Min SAH – The minimum surface area heuristic for the BLAS.

  • Mean SAH – The average surface area heuristic for the BLAS.

  • Max. depth – The maximum depth of the BLAS.

  • Avg. depth – The average depth of the BLAS.

The columns can be sorted by clicking on them. The arrow in the heading shows if 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.

The TLAS Properties Tab

The Properties tab displays a read-only table of properties and statistics for the selected TLAS.

_images/tlas_properties_1.png

The BLAS windows

These panes show information about a bottom-level acceleration structure.

The BLAS Viewer

This pane is very similar to the TLAS viewer, except the leaf nodes are triangles instead of instances.

_images/blas_viewer_1.png

The most commonly used widgets are available in a row below the pane tabs.

  1. The BLAS dropdown allows selection of which BLAS to view.

  2. BVH Coloring allows the bounding volume wireframes to be painted depending on a number of different parameters. See the TLAS documentation for more details on these coloring modes.

  3. Geometry coloring allows the scene to be painted depending on a number of different parameters. The list of coloring modes is a subset used by the TLAS geometry modes combo box. See the TLAS documentation for more details on these coloring modes.

  4. Heatmap selection allows changing the color scheme of the heatmap. See the TLAS documentation for more details on these coloring modes.

On the left will be information for the bottom level acceleration structure:

  1. The treeview under the dropdown will show the structure of the BLAS. As seen here, the topmost level contains a Box32 structure. This Box32 contains 4 more Box32 structures. The currently opened box shows a list of triangles inside this box.

  2. The section below the treeview gives details about the currently selected node, including the surface area heuristic, and extents.

  3. If the selected node is a triangle node then the triangle vertex positions will be displayed, as well as geometry flags of the geometry that the triangle is a part of.

In the center is a rendering of the bounding volume and geometry contained within that volume. Please see the TLAS help section for more information since the control modes and functionality is similar to the TLAS scene display.

It is possible to select individual triangles within the scene by clicking on a mesh within the viewport. The BLAS hierarchy tree view will expand as necessary to focus on the 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.

Culling mode ray flags

These work slightly differently to those in the TLAS pane, since at the BLAS level there is no concept of an instance. That means there are no instance flags to override the ray flags set up in the RRA user interface.

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).

_images/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).

_images/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.

_images/split_triangles_stats_1.png

The BLAS Instances Tab

The Instances tab displays a read-only table of properties and statistics for instances of the selected BLAS.

_images/blas_instances_1.png

Above the table is the base address of the BLAS used by all the instances.

The following fields are displayed:

  • Instance index - The API index for the instance.

  • Instance address – The virtual GPU address for the instance node within the TLAS.

  • 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.

  • Cull disable - Instance flag specifying if the cull mode is disabled.

  • 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.

  • Y Position – The Y-position of the instance in the scene.

  • Z Position – The Z-position of the instance in the scene.

  • Transform[x][y] - The instance transform, comprising of the rotation and scaling components.

The columns can be sorted by clicking on them. The arrow in the heading shows if sorting is in ascending or descending 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 position and transform matrix in the table.

The Triangles Tab

The Triangles tab displays a read-only table of properties and statistics for triangle nodes in the selected BLAS.

_images/triangles_1.png

Above the table is the base address of the BLAS used by all the triangles, and the base address of the TLAS containing the BLAS.

The following fields are displayed:

  • Geometry index - The index of the geometry that the triangle belongs to.

  • Opaque - Presence of the opaque geometry flag.

  • No duplicate any hit invocation - Presence of the no duplicate any hit invocation geometry flag.

  • Primitive index - The API index of the triangle accessible in shaders.

  • Node address - The virtual address of this node in GPU memory.

  • Node offset - The relative address of this node relative to the BLAS address.

  • Active - Whether or not this triangle is active according to the API specification definition.

  • Triangle surface area - The surface area of the triangle node.

  • SAH - The surface area heuristic of the triangle node.

  • Vertex0 - The vertex position of the first triangle vertex.

  • Vertex1 - The vertex position of the second triangle vertex.

  • Vertex2 - The vertex position of the third triangle vertex.

The columns can be sorted by clicking on the column header, apart from the vertex columns; sorting is disabled for these columns. The arrow in the heading shows if sorting is in ascending or descending order.

The Geometries Tab

The Geometries tab displays a read-only table of properties and statistics for the geometries in the selected BLAS.

_images/geometries_1.png

Above the table is the base address of the BLAS used by all the geometries, and the base address of the TLAS containing the BLAS.

The following fields are displayed:

  • Geometry index - The index of the geometry in the BLAS. This refers to the first column in the triangles table.

  • Opaque - Presence of the opaque geometry flag.

  • No duplicate any hit invocation - Presence of the no duplicate any hit invocation geometry flag.

  • Primitive count - The number of primitives contained in the geometry.

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.

The BLAS Properties Tab

The Properties tab displays a read-only table of properties and statistics for the selected BLAS.

_images/blas_properties_1.png

The RAY windows

These panes allow dispatches and rays to be visualized.

The Dispatches Tab

The main ray dispatches pane allows you to see more information about the selected dispatch, and select individual dispatch coordinates for further inspection.

The display consists of 2 sections; an information section on the left, and a heatmap image of the dispatch output on the right.

_images/ray_history_1.png

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.

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.

Below this is the Dispatch coordinates table. This shows the information for each dispatch coordinate, including the ray count, the traversal loop count and the number of instance intersections. The table columns can be sorted to help highlight problematic areas, for example, sorting by Ray count to find coordinates that cast too many rays. Note that only the coordinates with at least 1 ray cast will be displayed.

The Image section

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 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. 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 a rectangle is selected, the unselected area will be grayed out, and the Ray list will update to filter out the unselected dispatch coordinates. The right mouse button can be used to cancel or deselect the selected area. Since some dispatches can be large, the mouse wheel can be used to zoom in or out while the middle mouse button will pan when the mouse is dragged. The zoom will be focused on the mouse cursor position.

Zoom controls

Zoom control buttons are provided to view sections of interest in the heatmap image and are displayed in the top right, immediately above the heatmap image. These are:

ZoomSelectionRef Zoom to selection

When Zoom to selection is clicked, the zoom level is increased to show the currently selected region. If there is no selected region, the button will be grayed out and non-functional.

ZoomResetRef Zoom reset

When Zoom reset is clicked, the zoom level is returned to the original default zoom level.

ZoomInRef Zoom in

Increases the zoom level incrementally to show a smaller area of the image, and duplicates the functionality accomplished with the mouse wheel. The button will be grayed out and non-functional if at the maximum zoom level.

ZoomOutRef Zoom out

Decreases the zoom level incrementally to show a larger area of the image, and duplicates the functionality accomplished with the mouse wheel. The button will be grayed out and non-functional if at the minimum zoom level.

Clicking a pixel without dragging will select just that pixel, displaying a cursor icon directly below it. This dispatch coordinate will be selected in the dispatch coordinates table as well.

An area of interest is shown in the image below:

_images/ray_history_2.png

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.

The Inspector Tab

_images/ray_inspector_1.png

The screen layout is similar to the TLAS and BLAS viewer panes, and is split into 3 areas.

The left section shows a summary of the currently selected dispatch coordinate from the Dispatches tab:

_images/ray_inspector_2.png

In the top-left is the Ray table. The ray index provides the order in which the rays were cast in the application’s shaders; index 0 will be the first ray generated.

Rays can be chosen by clicking on an entry in the table. The selected ray will be outlined in yellow by default. The ray colors can be changed in the Themes and colors settings pane.

Underneath this is the Selected ray section showing the values passed to the TraceRay() call in the shader. Clicking on the box icon to the right of the Selected ray header will focus ray in the 3D view.

The Ray result section shows the distance of the accept hit as well as the instance index, geometry index, and primitive index of the hit triangle. These fields will be blank if the ray misses.

The center section shows a rendering of the scene:

_images/ray_inspector_3.png

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.

Clicking on a ray in the 3D view will select it, as indicated by a yellow (by default) outline around it. The bottom of the screen shows a legend for the color of the rays, which can be modified in the Themes and colors settings pane. The TLAS geometry shown cannot be selected in the ray inspector, it’s just shown as a visual aid providing context to the rays.

The instance mask in the top left shows the instance mask of the currently selected ray, and will update the 3D view to only show instances which are included by the mask. Unlike in the TLAS tab, the instance mask filter is read-only in the Ray tab. The rays with an instance filter mask of 0 will be colored red (by default) to indicate that the ray will have no chance of invoking a hit shader.

The right section allows control over the rendering and camera:

_images/ray_inspector_4.png

These controls function almost identically to those in the TLAS and BLAS viewer panes.

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.

DISCLAIMER

The information contained herein is for informational purposes only, and is subject to change without notice. While every precaution has been taken in the preparation of this document, it may contain technical inaccuracies, omissions and typographical errors, and AMD is under no obligation to update or otherwise correct this information. Advanced Micro Devices, Inc. makes no representations or warranties with respect to the accuracy or completeness of the contents of this document, and assumes no liability of any kind, including the implied warranties of noninfringement, merchantability or fitness for particular purposes, with respect to the operation or use of AMD hardware, software or other products described herein. No license, including implied or arising by estoppel, to any intellectual property rights is granted by this document. Terms and limitations applicable to the purchase or use of AMD’s products are as set forth in a signed agreement between the parties or in AMD’s Standard Terms and Conditions of Sale.

AMD, the AMD Arrow logo, Radeon, Ryzen, RDNA and combinations thereof are trademarks of Advanced Micro Devices, Inc. Other product names used in this publication are for identification purposes only and may be trademarks of their respective companies.

DirectX is a registered trademark of Microsoft Corporation in the US and other jurisdictions.

Vulkan and the Vulkan logo are registered trademarks of the Khronos Group Inc.

Microsoft is a registered trademark of Microsoft Corporation in the US and other jurisdictions.

Windows is a registered trademark of Microsoft Corporation in the US and other jurisdictions.

© 2022-2023 Advanced Micro Devices, Inc. All rights reserved.