diff --git a/docs/behind_scenes/opengl_support.rst b/docs/behind_scenes/opengl_support.rst index 763d42113..d1b7d2f07 100644 --- a/docs/behind_scenes/opengl_support.rst +++ b/docs/behind_scenes/opengl_support.rst @@ -8,7 +8,7 @@ The latest information and up-to-date support is always available on the `GitHub Capture requirements -------------------- -RenderDoc only supports the core profile of OpenGL - from 3.2 up to 4.5 inclusive. This means any compatibility profile functionality will generally not be supported. There are a couple of concessions where it was easy to do so - like allowing the use of VAO 0, or luminance/intensity formats, but this in general will not happen. +RenderDoc only supports the core profile of OpenGL - from 3.2 up to 4.6 inclusive. This means any compatibility profile functionality will generally not be supported. There are a couple of concessions where it was easy to do so - like allowing the use of VAO 0, or luminance/intensity formats, but this in general will not happen. .. note:: diff --git a/docs/behind_scenes/planned_features.rst b/docs/behind_scenes/planned_features.rst index e59529fa6..4837673de 100644 --- a/docs/behind_scenes/planned_features.rst +++ b/docs/behind_scenes/planned_features.rst @@ -11,7 +11,6 @@ Planned features ---------------- * Debugging of all shader stages. -* HLSL Debugging. * Mesh display after hull shader stage. * Diffing events in a given frame. * Modifying the pipeline on the fly to change state. diff --git a/docs/behind_scenes/vulkan_support.rst b/docs/behind_scenes/vulkan_support.rst index a96eb1af3..8d8e41112 100644 --- a/docs/behind_scenes/vulkan_support.rst +++ b/docs/behind_scenes/vulkan_support.rst @@ -31,7 +31,7 @@ Likewise try to avoid making very large memory allocations in the range of 1GB a Current support --------------- -RenderDoc has initial support for Vulkan at the launch of version 1.0, but it contains some caveats. In addition, not all replay features are currently supported, but this is being actively worked on. +RenderDoc has support for Vulkan version 1.1, as well as a number of extensions, but it contains some caveats. In addition, not all replay features are currently supported, but this is being actively worked on. * RenderDoc assumes that even if multiple GPUs are present, that only one VkDevice will be created and used. * RenderDoc captures will in general not be portable between different systems, only currently supporting capture and replay on the same or similar enough machines. diff --git a/docs/getting_started/faq.rst b/docs/getting_started/faq.rst index 39bd8a9be..07c39f26d 100644 --- a/docs/getting_started/faq.rst +++ b/docs/getting_started/faq.rst @@ -138,9 +138,8 @@ The two primary causes of differences between the captured program and the repla #. ``Map()`` s that use DISCARD are filled with a marker value, so any values that aren't written to the buffer will be different - in application you can get lucky and they can be previous values that were uploaded, but in replay they will be ``0xCCCCCCCC``. -#. RenderDoc will not save or restore the contents of render targets at the start of the frame if it believes they will be entirely overwritten in the frame. This detection is typically accurate but means targets are cleared to black or full depth rather than accumulating, even if that accumulation is not intentional it may be the cause of the bug. +#. When buffers are created they have undefined contents - graphics APIs do not promise that they are filled with 0s. RenderDoc fills buffers with garbage data which can change behaviour. - This behaviour can be overridden by enabling 'Save all initials' in the :doc:`capture options <../how/how_capture_frame>`. I can't launch my program for capture directly. Can I capture it anyway? ------------------------------------------------------------------------ @@ -227,3 +226,14 @@ When launching a process in RenderDoc, by default only this process is debugged In the case where your program launches sub-processes that you would like to debug, you can enable the ``Capture Child Processes`` capture option, which causes RenderDoc to recursively inject itself into all children (and grand-children, and so on). When you open a capture connection, the child processes will be displayed and you can open a connection to each child to locate the process you wish to debug. There are :ref:`more details available ` in the documentation for the :doc:`../window/capture_attach` window. + +I'm debugging a program using an OpenGL ES emulator, how can I capture the underlying API? +------------------------------------------------------------------------------------------ + +Wherever possible on Windows RenderDoc will capture OpenGL ES natively and ignore any underlying API calls it makes. For libraries such as ANGLE that emulate GLES on windows using calls to D3D11, this means the GLES itself gets captured and debugged. + +If you don't want this to happen and you'd prefer OpenGL ES to be ignored during capture you can set the ``RENDERDOC_HOOK_EGL`` environment variable to ``0``. + +.. note:: + + This toggle only has effect on windows. On other platforms GLES is always natively captured as it is expected to have system-level support rather than being emulated. \ No newline at end of file diff --git a/docs/getting_started/features.rst b/docs/getting_started/features.rst index a028df672..ed3f17f1c 100644 --- a/docs/getting_started/features.rst +++ b/docs/getting_started/features.rst @@ -70,7 +70,7 @@ Most of these should be intuitive if you've used a graphics debugger before. D3D11 ----- -* Support for D3D11 up to D3D11.3, Windows Vista and above. Where hardware support isn't available for feature level 11, WARP will be used. +* Support for D3D11 up to D3D11.4, Windows Vista and above. Where hardware support isn't available for feature level 11, WARP will be used. * Debug marker support comes from any available D3D interface (ID3DUserDefinedAnnotation, D3DPERF\_ functions, etc) * Pixel history view. * Vertex, Pixel and Compute shader debugging. @@ -79,20 +79,20 @@ D3D11 D3D12 ----- -* Support for D3D12, Windows 10 only. +* Support for D3D12 up to D3D12.3, Windows 10 only. * Debug marker uses the PIXSetMarker macros that go through SetMarker/BeginEvent/EndEvent on the command list Vulkan ------ -* Support for Vulkan 1.0 on Windows, Linux, and Android. +* Support for Vulkan 1.1 on Windows, Linux, and Android. * Event markers and object naming both come from ``VK_EXT_debug_marker``. OpenGL & OpenGL ES ------------------ -* Support for OpenGL Core profile 3.2+ on Windows and Linux. -* Support for OpenGL ES 2.0 - 3.2 on Linux and Android. +* Support for OpenGL Core profile 3.2 - 4.6 on Windows and Linux. +* Support for OpenGL ES 2.0 - 3.2 on Linux, Windows, and Android. * Tree hierarchy of events defined by any of the standard or vendor-specific extensions, and ``KHR_debug`` object labels used for object naming. Captures have a very limited amount of portability between machines. Many hardware-specific feature uses are baked into captures, and portability depends on how similar the capture and replay hardware are, whether these feature uses can map the same in both cases. Captures are however completely portable between different OSes with sufficiently comparable hardware. diff --git a/docs/getting_started/gotchas_known_issues.rst b/docs/getting_started/gotchas_known_issues.rst index 2a2cbf913..9b9a496fd 100644 --- a/docs/getting_started/gotchas_known_issues.rst +++ b/docs/getting_started/gotchas_known_issues.rst @@ -8,11 +8,7 @@ Things to Note * Vulkan captures are not portable between different vendor GPUs, or possibly even between different GPUs from the same vendor if the hardware changes significantly enough. -* OpenGL is only supported from 3.2 on, so legacy GL features from 2.0 and before that were deprecated in 3.2 will not work. Similarly OpenGL ES is only supported from 2.0 and above. In addition in both cases, multiple GL contexts are only supported if they share with each other. - -* RenderDoc doesn't serialise out the initial contents of large graphics resources when it believes that they will not be used in replay. e.g. a G-Buffer render target will not be saved out as it is initialised and written to in-frame. This detection will go wrong if a render target is partially written to but partially re-used, as RenderDoc will count this as initialised in-frame. This could happen e.g. with an accumulating texture that is written to in the frame over the top of previous results. - - You can override this behaviour by selecting 'Save All Initials' in the :doc:`capture options <../how/how_capture_frame>` before capturing, as this will force RenderDoc to serialise out all initial contents regardless, at the cost of larger capture files and slightly slower replay app analysis. +* OpenGL is only supported from 3.2 on, so legacy GL features from 2.0 and before that were deprecated in 3.2 will not work. Similarly OpenGL ES is only supported from 2.0 and above. * When capturing, only one swapchain is captured at any given time. The in-app overlay renders to all swapchains but only one is considered "active" at any given time - this can be cycled with the F11 key. The capture key will trigger a capture at the next swap of the currently active swapchain. @@ -24,4 +20,4 @@ Things to Note * If capturing callstacks from the app, ensure that ``dbghelp.dll`` is not loaded or used by the application as this can easily interfere with RenderDoc's use and cause undefined or empty results. More information on this can be found in :doc:`../how/how_capture_callstack`. * RenderDoc can have a significant memory overhead, especially when a lot of resources are allocated as shadow copies in main memory are created. - If running in 32bit, it's possible that an application can run out of memory - particularly when capturing, as this causes a significant spike in memory use. Improvements in memory management are planned but for now it's recommended to use 64bit, or to limit captures to simple scenes wherever possible. + If running in 32bit, it's possible that an application can run out of memory - particularly when capturing, as this causes a significant spike in memory use. It's recommended to use 64bit, or to limit captures to lower resolutions or simple scenes wherever possible. diff --git a/docs/how/how_android_capture.rst b/docs/how/how_android_capture.rst index 61746df64..5c0a57c67 100644 --- a/docs/how/how_android_capture.rst +++ b/docs/how/how_android_capture.rst @@ -3,6 +3,8 @@ How do I use RenderDoc on Android? RenderDoc contains support for Android for both Vulkan and OpenGL ES. It requires a couple of extra steps more than capturing on a desktop computer, but generally the workflow is very similar. +The Android device must be running at least Android 6.0. + Android support is still quite new, so if you run into any rough spots please `open an issue on GitHub `_ or `email me `_. .. caution:: diff --git a/docs/how/how_debug_shader.rst b/docs/how/how_debug_shader.rst index 007645549..dc8198b7e 100644 --- a/docs/how/how_debug_shader.rst +++ b/docs/how/how_debug_shader.rst @@ -12,6 +12,8 @@ Including debug info in shaders For the most part at least some debug information is included with shaders unless it is being explicitly stripped out at some point. There is usually an option to also include additional debug information - such as original source code in a high-level language. The exact process varies by API, but for D3D11 the flag ``/Zi`` to fxc or the equivalent flag to ``D3DCompile()`` will include additional debugging information, and ``/Qstrip_debug`` and ``/Qstrip_reflection`` will remove reflection information that can be useful - such as the names of variables in constant buffers. +For shader debugging it's recommended that you build with ``/Od`` or ``D3DCOMPILE_SKIP_OPTIMIZATION``, as this will enable HLSL debugging by default. + For more information on how to get this unstripped debug information to renderdoc, see :ref:`unstripped-shader-info`. Debugging a vertex @@ -106,6 +108,25 @@ Hovering over a register in either the disassembly or in the view windows will o There is also a toggle available to control the 'default' interpretation of temporary register values - float or int. D3D registers are typeless but typically they are interpreted as float values. With this toggle you can toggle them to be interpreted as integers by default instead. +HLSL Debugging +-------------- + +When debug information is available in the shader, RenderDoc allows debugging at the HLSL level. This is activated by default if the shader was built with optimisation disabled, but as long as debug information is available you can toggle between assembly and HLSL debugging at any time. + +In the toolbar there will be a 'Debug in HLSL' button when HLSL debugging is available, and similarly in reverse a 'Debug in Assembly' button. You can also right-click and select 'Go to Disassembly' or 'Go to Source'. + +While source debugging, the same controls are available to set breakpoints, run forwards and backwards, etc. Note that stepping and running in HLSL may skip over several assembly instructions at once. + +Debug information also includes HLSL callstack and locals mapping, which allows RenderDoc to display the function callstack at the current instruction and the name and values of any local variables that are in scope. They are displayed in the callstack and locals windows respectively. + +.. figure:: ../imgs/Screenshots/ShaderStackLocals.png + + Callstack and Locals windows. + +.. note:: + + Callstack and local mapping information is only available with windows 8.0 and later versions of fxc. That corresponds to ``D3DCompiler_47.dll``. + Debugging Displays ------------------ @@ -119,9 +140,9 @@ The other window will contain variable/mutable registers. These contain temporar .. figure:: ../imgs/Screenshots/ShaderRegs.png - Variable window: Variable registers - temporaries and outputs. + Registers window: Variable registers - temporaries and outputs. -The final window is initially empty but can be filled out as needed. This shows custom watch expressions and their values. Here you can write any expression involving an input, temporary or output register along with a swizzle and typecast. +The final window is initially empty but can be filled out as needed. This shows custom watch expressions and their values. Here you can write any expression involving an input, temporary or output register along with a swizzle and typecast. When debug information is present you can also include locals here. Swizzles follow the standard hlsl rules - ``.[xyzw]`` or ``.[rgba]`` in any permutation or repetition will show those channels. diff --git a/docs/how/how_rgp_profile.rst b/docs/how/how_rgp_profile.rst new file mode 100644 index 000000000..44e19226b --- /dev/null +++ b/docs/how/how_rgp_profile.rst @@ -0,0 +1,43 @@ +How do I generate an RGP profile? +================================= + +RenderDoc has integration with AMD's Radeon GPU Profiler. This allows you to generate an RGP profile from a RenderDoc capture, embed the profile in the capture file, and synchronise the view of the frames between RenderDoc and RGP. + +Generating a profile +-------------------- + +To begin you will need to go to the :guilabel:`Tools` menu and select :guilabel:`Create new RGP Profile`. If this menu option isn't available, you need to have the latest AMD drivers installed on your machine. + +Selecting this menu item will open a small popup and spend a few second creating the profile itself. After the profile is created, the RGP profiling tool will automatically open up. + +.. note:: + + If you haven't configured the path to the RGP tool, you will be prompted to here. Once the path has been configured successfully the tool will open. + +Opening a previously created profile +------------------------------------ + +After generating a profile above, the RGP data is embedded in the ``.rdc`` file. + +Since RGP can open a profile on any machine without needing AMD drivers or hardware, this embedded RGP profile can be opened at any time by going to the :guilabel:`Tools` menu and select :guilabel:`Open RGP Profile`. + +The RGP tool will open just the same as if the profile was newly created. + +Correlating information between RenderDoc and RGP +------------------------------------------------- + +If using RGP version 1.2 or higher, once both tools are open they have a synchronised view of the underlying data. + +This means that within RGP you can select an event, right click and choose :guilabel:`Select RenderDoc Event`. This will bring RenderDoc to the foreground with the event selected. Similarly in RenderDoc you can right-click on an event in the event browser and choose :guilabel:`Select RGP Event` which will perform the same operation in reverse. + +.. figure:: ../imgs/Screenshots/SelectRGPEvent.png + + Select an RGP event from RenderDoc + +.. figure:: ../imgs/Screenshots/SelectRenderDocEvent.png + + Select a RenderDoc event from RGP + +.. note:: + + Since RGP and RenderDoc have different scopes, purposes, and views of the frame the numbering of events will not be the same between the two tools. \ No newline at end of file diff --git a/docs/how/index.rst b/docs/how/index.rst index 11f3ef80b..f9266a14a 100644 --- a/docs/how/index.rst +++ b/docs/how/index.rst @@ -3,8 +3,9 @@ How do I ...? .. toctree:: - how_debug_shader how_capture_frame + how_android_capture + how_debug_shader how_inspect_pixel how_view_texture how_object_details @@ -12,6 +13,6 @@ How do I ...? how_custom_visualisation how_edit_shader how_network_capture_replay - how_android_capture how_annotate_capture how_import_export + how_rgp_profile diff --git a/docs/imgs/Screenshots/PixelHistoryTimeline.png b/docs/imgs/Screenshots/PixelHistoryTimeline.png index fb46b93e1..ea4372d1d 100644 Binary files a/docs/imgs/Screenshots/PixelHistoryTimeline.png and b/docs/imgs/Screenshots/PixelHistoryTimeline.png differ diff --git a/docs/imgs/Screenshots/ResourceUsage.png b/docs/imgs/Screenshots/ResourceUsage.png index e8467b94e..72c34f489 100644 Binary files a/docs/imgs/Screenshots/ResourceUsage.png and b/docs/imgs/Screenshots/ResourceUsage.png differ diff --git a/docs/imgs/Screenshots/SelectRGPEvent.png b/docs/imgs/Screenshots/SelectRGPEvent.png new file mode 100644 index 000000000..cf0d0d3b8 Binary files /dev/null and b/docs/imgs/Screenshots/SelectRGPEvent.png differ diff --git a/docs/imgs/Screenshots/SelectRenderDocEvent.png b/docs/imgs/Screenshots/SelectRenderDocEvent.png new file mode 100644 index 000000000..7be79811d Binary files /dev/null and b/docs/imgs/Screenshots/SelectRenderDocEvent.png differ diff --git a/docs/imgs/Screenshots/ShaderRegs.png b/docs/imgs/Screenshots/ShaderRegs.png index 6709f9692..6e7fdff15 100644 Binary files a/docs/imgs/Screenshots/ShaderRegs.png and b/docs/imgs/Screenshots/ShaderRegs.png differ diff --git a/docs/imgs/Screenshots/ShaderStackLocals.png b/docs/imgs/Screenshots/ShaderStackLocals.png new file mode 100644 index 000000000..edcb0a1bf Binary files /dev/null and b/docs/imgs/Screenshots/ShaderStackLocals.png differ diff --git a/docs/imgs/Screenshots/TimelineBar.png b/docs/imgs/Screenshots/TimelineBar.png index cc53bce1b..94609008b 100644 Binary files a/docs/imgs/Screenshots/TimelineBar.png and b/docs/imgs/Screenshots/TimelineBar.png differ diff --git a/docs/renderdoc.hhk b/docs/renderdoc.hhk index a1dd87bfe..fdc13e224 100644 --- a/docs/renderdoc.hhk +++ b/docs/renderdoc.hhk @@ -1,4 +1,12 @@
    +
  • + + + +
  • + + +
  • @@ -33,20 +41,20 @@
    • - - + +
    • - - + +
    • - - + +
    • - - + +
  • @@ -57,6 +65,10 @@ +
  • + + +
  • @@ -65,6 +77,10 @@ +
  • + + +
  • @@ -89,6 +105,10 @@ +
  • + + +
  • @@ -98,13 +118,21 @@
      +
    • + + + +
    • + + +
    • - - + +
    • @@ -122,6 +150,14 @@ +
    • + + + +
    • + + +
    • @@ -204,8 +240,8 @@
    • - - + +
    • @@ -231,6 +267,10 @@ +
    • + + +
    • @@ -247,6 +287,14 @@ +
    • + + + +
    • + + +
    • @@ -261,24 +309,28 @@
      • - - + +
      • - - + +
      • - - + +
      • - - + +
      • - - + + + +
      • + +
    • @@ -327,15 +379,15 @@
    • - - + +
    • - +
    • @@ -346,14 +398,18 @@ -
    • - - -
    • +
    • + + + +
    • + + +
    • @@ -362,6 +418,14 @@ +
    • + + + +
    • + + +
    • diff --git a/docs/window/capture_attach.rst b/docs/window/capture_attach.rst index 4b3fc7770..fdf800f4c 100644 --- a/docs/window/capture_attach.rst +++ b/docs/window/capture_attach.rst @@ -1,5 +1,5 @@ -Launching & Attaching to Programs -================================= +Capture Dialog +============== The Capture Dialog (which doubles as the inject-into-process dialog) is the single point where programs are launched and captures are saved to disk. @@ -112,14 +112,6 @@ This option causes RenderDoc to hook into process creation calls from the target .. note:: Due to the hook implementation on linux, child processes will always be hooked regardless of whether this option is enabled or disabled. ----------- - - | :guilabel:`Save All Initials` Default: ``Disabled`` - -RenderDoc will attempt to save overhead and particularly capture file size by omitting the initial contents of 2D textures that it believes will be unnecessary. Typically these textures are render targets or depth buffers that will be written to and fully covered in the course of the frame before they are ever read, and so saving their initial contents is unnecessary. - -In some cases this detection will be wrong, such as targets that are partially written such as pools, or if a target is accumulated to via blend modes. When this is the case, enabling Save All Initials will force RenderDoc to save these textures regardless of any auto-detection. - ---------- | :guilabel:`Ref All Resources` Default: ``Disabled`` diff --git a/docs/window/performance_counter_viewer.rst b/docs/window/performance_counter_viewer.rst index 546212c44..d629b3e74 100644 --- a/docs/window/performance_counter_viewer.rst +++ b/docs/window/performance_counter_viewer.rst @@ -34,3 +34,11 @@ By default the table is sorted by EID, but each column is sortable individually .. |save| image:: ../imgs/icons/save.png Clicking the |save| button lets you save the results of the counters as CSV. + +Hardware Counters +----------------- + +RenderDoc ships with support for AMD's GPA library, which will allow access to AMD's hardware counters when running with a supported AMD GPU. + +RenderDoc also has support for nVidia's NvPerfKit library, but it does not ship as the library's license forbids redistribution. To enable support, place the ``NvPmApi.Core.dll`` file into either ``plugins/nv/counters/x64`` for 64-bit RenderDoc builds and ``plugins/nv/counters/x86`` for 32-bit RenderDoc builds. + diff --git a/docs/window/pipeline_state.rst b/docs/window/pipeline_state.rst index 1405d61d6..c825306a0 100644 --- a/docs/window/pipeline_state.rst +++ b/docs/window/pipeline_state.rst @@ -36,6 +36,8 @@ Likewise it will omit any slots which are completely empty (and also unused), an In some cases whole sections will be omitted unless there is anything set there - this is primarily for unused or rarely used features like shader subroutines/class linkage, and Read/Write bindings (Image load store or UAVs). +Sections can be expanded and collapsed by clicking on the title text above them to toggle them in and out of the collapsed state. This can be used to temporarily close down some sections that you don't need to make room for more vertical space in sections you do need. + When showing disabled or empty entries, they will either be in *italics* or on a dark red background respectively. .. |save| image:: ../imgs/icons/save.png diff --git a/docs/window/settings_window.rst b/docs/window/settings_window.rst index b30ecc732..3459e7732 100644 --- a/docs/window/settings_window.rst +++ b/docs/window/settings_window.rst @@ -157,6 +157,12 @@ Here you can choose which locations to search in, and in which order, when looki For more information you can consult :ref:`the FAQ entry about providing unstripped shader debug information `. + | :guilabel:`Radeon GPU Profiler executable` Default: ``Empty`` + +Here you can choose where ``RadeonGPUProfiler`` executable is, for use with the RGP integration. + +For more information you can see :doc:`../how/how_rgp_profile`. + Texture Viewer options ----------------------