Add documentation for RRA 1.0 release

Author: ahosier

Release_Notes.txt

@@ -0,0 +1,17 @@
+Radeon Raytracing Analyzer V1.0 07/26/2022
+------------------------------------------
+
+V1.0
+------------------------------------
+This is the first public release of the Radeon Raytracing Analyzer.
+
+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.
+(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.
+(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.
+

documentation/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+
+
+img {
+  max-width: 100%;
+  max-height: auto;
+  box-shadow: 6px 6px #eee;
+  -ms-interpolation-mode: bicubic;
+  border: 1px solid #ccc;
+}
+
+table {
+	font-size: 12px;
+}

documentation/source/blas_instance_list.rst

@@ -0,0 +1,40 @@
+The BLAS Instances Tab
+----------------------
+
+The Instances tab displays a read-only table of properties and statistics for
+instances of the selected BLAS.
+
+.. image:: media/blas/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 address – The virtual address for the instance node within the TLAS.
+
+* Instance offset – The offset for the instance node within the TLAS.
+
+* Instance mask - The mask specified for the instance node.
+
+* 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 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.

documentation/source/blas_list.rst

@@ -0,0 +1,50 @@
+The BLAS List
+-------------
+
+The BLAS List tab displays a read-only table of BLAS properties and statistics.
+
+.. image:: media/tlas/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 within the parent TLAS.
+
+* 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.
+
+* 16-bit boxes – The total number of 16-bit box nodes 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.
+
+* 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 decending order.
+
+Double-clicking an item in the table will jump to the BLAS Viewer pane and show
+the selected BLAS.

documentation/source/blas_properties.rst

@@ -0,0 +1,7 @@
+The BLAS Properties Tab
+-----------------------
+
+The Properties tab displays a read-only table of properties and statistics for
+the selected BLAS.
+
+.. image:: media/blas/blas_properties_1.png

documentation/source/blas_viewer.rst

@@ -0,0 +1,46 @@
+The BLAS Viewer
+---------------
+
+This pane is very similar to the TLAS viewer, except the leaf nodes are triangles
+instead of instances.
+
+.. image:: media/blas/blas_viewer_1.png
+
+The most commonly used widgets are available in a row below the pane tabs.
+
+#. The **BLAS** dropdown allows selection of which BLAS to view.
+
+#. **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.
+
+#. **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.
+
+#. **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:
+
+#. 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.
+
+#. The section below the treeview gives details about the currently selected node,
+   including the surface area heuristic, and extents.
+   
+#. 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.

documentation/source/capture.rst

@@ -0,0 +1,8 @@
+How to generate a BVH trace
+---------------------------
+
+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.

documentation/source/conf.py

@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+#
+# Radeon Raytracing Analyzer documentation build configuration file, created by
+# sphinx-quickstart on Fri Jun 30 12:01:48 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Radeon Raytracing Analyzer'
+copyright = u'2022, Advanced Micro Devices, Inc. All rights reserved.'
+author = u'AMD Developer Tools'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0.0'
+# The full version, including alpha/beta/rc tags.
+release = u'1.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+#html_theme = 'alabaster'
+#html_theme = 'classic'
+#html_theme = 'sphinxdoc'
+#html_theme = 'scrolls'
+#html_theme = 'agogo'
+#html_theme = 'traditional'
+#html_theme = 'nature'
+#html_theme = 'haiku'
+#html_theme = 'pyramid'
+#html_theme = 'bizstyle'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {'stickysidebar': 'true'}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If a function setup(app) exists, Sphinx will call this function as a normal
+# extension during application startup. This method of using the overrides css
+# file works better with read the docs (more so than specifying it via the
+# html_context tag)
+def setup(app):
+    app.add_stylesheet('theme_overrides.css')
+
+html_show_sourcelink = False
+html_show_sphinx = False
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'RaytracingAnalyzerdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'RaytracingAnalyzer.tex', u'Raytracing Analyzer Documentation',
+     u'AMD Developer Tools', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'RaytracingAnalyzer', u'Raytracing Analyzer Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'RaytracingAnalyzer', u'Raytracing Analyzer Documentation',
+     author, 'RaytracingAnalyzer', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+