Various improvements/tweaks/missing bits/extra links

* General proof-reading pass on the new docs, so some of these issues are old and just haven't been noticed before.
2026-05-04 09:00:44 +00:00 · 2016-05-16 19:19:15 +02:00
parent 3146b905b5
commit 8bc80b41b0
23 changed files with 189 additions and 127 deletions
@@ -10,7 +10,7 @@ Leaving aside the relatively uninteresting matter of injecting the RenderDoc DLL

 We will use D3D11 as an example of a driver for RenderDoc - the driver layer is responsible both for faithfully capturing the logfile's API usage, as well as then replaying and analysing it later. Essentially anything built on top of a driver layer can be used agnostically of the API the application in question is using.

-When the driver initialises it will hook into every entry point into the API such that when application uses the API it passes through the driver wrapper. In the case of D3D11 this is the D3D11CreateDevice and CreateDXGIFactory functions.
+When the driver initialises it will hook into every entry point into the API such that when application uses the API it passes through the driver wrapper. In the case of D3D11 this is the ``D3D11CreateDevice`` and ``CreateDXGIFactory`` functions.

 After this point all accesses to the API remain wrapped and the driver essentially "man-in-the-middle"s between the application and the real API.

@@ -31,7 +31,7 @@ When replaying, the initial section of the log (up to the beginning of the frame

 RenderDoc then does an initial pass over the captured frame. This allows us to build up a list of all the 'drawcall' events, analyse dependencies and check which resources are used at each drawcall for read, write, and so on. An internal tree is built up similar to what you see in the Event Browser &amp; API Viewer, as well as a linked list with the linear sequence of drawcalls, since both representations are useful for iterating over the frame.

-After this point most work is done in response to user actions. The basic building block is replaying a partial frame. Most analysis tools are built out of either replaying up to the current event, replaying up to the event - not including the current drawcall - and replaying _only_ the current drawcall.
+After this point most work is done in response to user actions. The basic building block is replaying a partial frame. Most analysis tools are built out of either replaying up to the current event, replaying up to the event - not including the current drawcall - and replaying *only* the current drawcall.

 Care is taken to minimise this as much as possible as this tends to be the slowest operation given the overheads of serialisation and decoding the command stream.

@@ -3,7 +3,7 @@ Planned future features

 This is a list of all features that are planned to be added at some point. Probably none of them have timelines or estimates yet, and they are in no particular order. I just would like to add them eventually. It's mostly here for interest, and for reference if you have a new feature request - it might be on here already!

-For more detail and a more up to date list, check the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki>`_.
+For more detail and a more up to date list, check the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/Roadmap>`__.

 Also note that none of these features are guaranteed. In an ideal world they would all happen but since work hasn't started on any of them some may turn out to be impractical or delayed indefinitely.

@@ -12,7 +12,7 @@ Vulkan capture
 RenderDoc's Vulkan support uses the sophisticated layering mechanism built into the Vulkan API. This means that once RenderDoc has registered its capture layers, there is no need for invasive process hooking - we can simply launch the target process with an environment variable set.


-The one requirement of this however is that the layer does need to be registered in an OS specific way - on windows this is in the registry, on linux this is in an /etc folder. That way the Vulkan loader can scan and initialise the layer.
+The one requirement of this however is that the layer does need to be registered in an OS specific way - on windows this is in the registry, on linux this is in ``/usr/share/vulkan/implicit_layer.d``, ``/etc/vulkan/implicit_layer.d``, or ``$HOME/.local/share/vulkan/implicit_layer.d``. That way the Vulkan loader can scan and initialise the layer.


 Usually this will happen for you if you install RenderDoc with a proper installer, or update from a previous version. However if you are compiling RenderDoc yourself or running a loose unzipped build, the capture panel will show a warning indicating that the layers need to be registered. Just click this and the registration will be applied.
@@ -27,7 +27,7 @@ Performance notes

 Vulkan is intended as a high-performance low CPU overhead API, and RenderDoc strives to maintain that performance contract at a reasonable level. While some overhead is inevitable RenderDoc aims to have no locks on the 'hot path' of command buffer recording, minimal or no allocation, and in general to have low performance overhead while not capturing.

-Some patterns of access are more or less conducive to good performance on RenderDoc, so if you are having trouble with slow capture, large memory/disk overhead or slow replay you might want to try eliminating use of persistent maps of memory from coherent heaps - you can use vkFlushMappedMemoryRanges to emulate non-coherent heaps and RenderDoc will take advantage of that, or you can use non-persistent maps.
+Some patterns of access are more or less conducive to good performance on RenderDoc, so if you are having trouble with slow capture, large memory/disk overhead or slow replay you might want to try eliminating use of persistent maps of memory from coherent heaps - you can use ``vkFlushMappedMemoryRanges`` to emulate non-coherent heaps and RenderDoc will take advantage of that, or you can use non-persistent maps.

 Likewise try to avoid making very large memory allocations in the range of 1GB and above. By its nature RenderDoc must save one or mor copies of memory allocations to enable proper capture, so having allocations limited to only a few 100s of MBs can help gain granularity of management and limit the memory overhead RenderDoc adds. There may be optimisation of this in future on RenderDoc's side but there are no easy guarantees.

@@ -1,14 +1,14 @@
 FAQ
 ===

-Here is a list of commonly asked questions about RenderDoc. Feel free to contact me if you have another question that isn't covered here or in this document.
+Here is a list of commonly asked questions about RenderDoc. Feel free to `contact me <mailto:baldurk@baldurk.org?subject=RenderDoc%20question>`__ if you have another question that isn't covered here or in this document.

 How do I do some particular task?
 ---------------------------------

 Many specific tasks or functions are detailed in the "How Do I... ?" sections. These sections each take a feature or element of a workflow and explain how it fits into the program as a whole as well as any details of how it works.

-If the task you have in mind isn't listed there you might find something similar, or you might find a related feature which can be used to do what you want. If the feature you want doesn't seem to exist at all you might want to check the Planned Future Features to see if it's coming soon - if it's not on that list please feel free to contact me and request it! Contact me. It has often been that simple features are very quick to implement and the prioritisation and scheduling of features is fairly fluid at this stage in development.
+If the task you have in mind isn't listed there you might find something similar, or you might find a related feature which can be used to do what you want. If the feature you want doesn't seem to exist at all you might want to check the :doc:`../behind_scenes/planned_features` to see if it's coming soon - if it's not on that list please feel free to `contact me <mailto:baldurk@baldurk.org?subject=RenderDoc%20request>`__ and request it! It has often been that simple features are very quick to implement and the prioritisation and scheduling of features is fairly fluid at this stage in development.

 Why did you make RenderDoc?
 ---------------------------
@@ -17,7 +17,7 @@ Although several tools do already exist for graphics debugging, none of them qui

 In addition to this, although the functionality overlaps to some degree many of these tools were primarily designed around the profiling of applications rather than debugging. While being able to inspect the state and contents of resources does often suffice for debugging, it's not necessarily the ideal workflow and often it can become cumbersome.

-In principle I didn't see any reason why I couldn't write a home-brew graphics debugger with some fairly simple operating principles. While there were a whole lot of caveats and little stumbling blocks along the way, the original design has pretty much stayed consistent since the project was started back in July 2012. If you're interested you might want to read about How RenderDoc works.
+In principle I didn't see any reason why I couldn't write a home-brew graphics debugger with some fairly simple operating principles. While there were a whole lot of caveats and little stumbling blocks along the way, the original design has pretty much stayed consistent since the project was started back in July 2012. If you're interested you might want to read about :doc:`../behind_scenes/how_works`.

 Where did the name come from?
 -----------------------------
@@ -27,17 +27,18 @@ All of the good names were taken :-(.
 Who can I contact about bugs, feature requests, other queries?
 --------------------------------------------------------------

-At the moment there's just me at the wheel - feel free to contact me at Contact me if you have anything you'd like to ask or suggest. I use a github repository for tracking bugs and feature requests so that's the best place to file an issue.
+At the moment there's just me at the wheel - feel free to `contact me <mailto:baldurk@baldurk.org?subject=RenderDoc%20feedback>`__ if you have anything you'd like to ask or suggest. I use a `github repository <https://github.com/baldurk/renderdoc>`__ for tracking bugs and feature requests so that's the best place to file an issue.

 I work on RenderDoc in my spare time but I am happy to help with anything and work with you if you have any issues that need attention.

 How can I associate RenderDoc's file extensions with the program?
 -----------------------------------------------------------------

-If you installed RenderDoc via the installer package rather than the zip folder, the option is available there to associate RenderDoc's file extensions with the program. Otherwise you can set them up from the Options Window.
-Note Note
+If you installed RenderDoc via the installer package rather than the zip folder, the option is available there to associate RenderDoc's file extensions with the program. Otherwise you can set them up from the :doc:`../window/options_window`.

-RenderDoc will elevate itself to set up these file associations, but otherwise will not hold on to administrator permissions.
+.. note::
+
+  RenderDoc will elevate itself to set up these file associations, but otherwise will not hold on to administrator permissions.

 RenderDoc associates .rdc and .cap with itself when desired. The .rdc files are the logfiles output when you capture inside an application. .cap files describe the set up of a particular capture, and can be used to quickly re-launch a capture preset.

@@ -50,14 +51,14 @@ If .rdc files are associated with RenderDoc a thumbnail handler is set up, so th
 What APIs does RenderDoc support?
 ---------------------------------

-Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available), Vulkan, and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of what is supported in its own page. Since Vulkan support is in its early stages, it also has its own page.
+Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available), Vulkan, and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of what is supported in :doc:`its own page <../behind_scenes/opengl_support>`. Since Vulkan support is in its early stages, it also has :doc:`its own page <../behind_scenes/vulkan_support>`.

 In future API support is planned for at D3D9 when time and scheduling allows. Higher priority is D3D12 now that Vulkan support is available. Mantle support will not happen as the API is not planned to be publically available anymore.

 How can I backup or restore my settings?
 ----------------------------------------

-Everything RenderDoc relies upon is stored in %APPDATA%\RenderDoc. You can back up and restore this directory at will as nothing stored in there is machine specific aside from things like recent file lists.
+Everything RenderDoc relies upon is stored in ``%APPDATA%\RenderDoc``. You can back up and restore this directory at will as nothing stored in there is machine specific aside from things like recent file lists.

 Deleting this folder will also reset RenderDoc to the defaults - if you uninstall RenderDoc this folder will not be deleted.

@@ -66,50 +67,52 @@ RenderDoc doesn't install any registry keys aside from those to set up file asso
 Which network ports does RenderDoc use?
 ---------------------------------------

-RenderDoc uses TCP and UDP ports 38920-38927 consecutively for remote access and control (ie. capturing remotely) for each new program that is opened on a machine. Note that even if you initiate a capture locally these ports are still opened for listening. These are the ports that are probed on a remote host to see if a connection exists.
+RenderDoc uses TCP and UDP ports ``38920``-``38927`` consecutively for remote access and control (ie. capturing remotely) for each new program that is opened on a machine. Note that even if you initiate a capture locally these ports are still opened for listening. These are the ports that are probed on a remote host to see if a connection exists.

-RenderDoc also uses TCP and UDP ports 39920 for remote replay connections, for when a remote host is used to replay and analyse the log.
+RenderDoc also uses TCP and UDP ports ``39920`` for remote replay connections, for when a remote host is used to replay and analyse the log.

 Where can I get the source to RenderDoc?
 ----------------------------------------

-RenderDoc is licensed under the MIT license and the source is available on github.com
+RenderDoc is licensed under the MIT license and the source is available on `github <https://github.com/baldurk/renderdoc>`__.

 What are the requirements for RenderDoc?
 ----------------------------------------

 Currently RenderDoc expects Feature Level 11.0 hardware and above for D3D11. Lower levels will capture successfully, but on replay RenderDoc will fall back to WARP software emulation which will run quite slowly.

-For OpenGL RenderDoc will only capture core profile applications, in general, and expects to be able to create a core 4.3 context which includes EXT_direct_state_access and ARB_buffer_storage. For more details see the OpenGL page.
+For OpenGL RenderDoc will only capture core profile applications, in general, and expects to be able to create a core 4.3 context which includes ``EXT_direct_state_access`` and ``ARB_buffer_storage``. For more details see :doc:`../behind_scenes/opengl_support`.

-With Vulkan RenderDoc should fully support any Vulkan application.
+With Vulkan, RenderDoc should fully support any Vulkan application. However replaying a Vulkan log may not work if the hardware used to capture it is different - portability of captures between hardware is not guaranteed.

 Why does my capture say "Failed to capture frame: Uncapped command list"?
 -------------------------------------------------------------------------

-At the moment RenderDoc only begins capturing deferred command lists at the point that you trigger a capture. If you replay command lists from before this, RenderDoc will fail to capture the frame and try again next frame (and eventually give up after a few retries).
+At the moment on some APIs like D3D9, RenderDoc only begins capturing deferred command lists at the point that you trigger a capture. If you replay command lists that were recorded before the captured frame, RenderDoc will fail to capture the frame and try again next frame (and eventually give up after a few retries).

-To change this behaviour, enable the Capture all cmd lists option - see that page for more details. This will capture all command lists from the start of the program, ready for when you decide to capture a frame. This currently has a fair overhead but it's something I want to improve in future
+To change this behaviour, enable the ``Capture all cmd lists`` option - see :doc:`../window/capture_log_attach` for more details. This will capture all command lists recorded from the start of the program, ready for when you decide to capture a frame. This currently has a fair amount of overhead.

 Why does my capture say "Failed to capture frame: Uncapped Map()/Unmap()"?
 --------------------------------------------------------------------------

-If you start a Map() before a Present() call then call Unmap() after the Present() during the frame RenderDoc wants to capture, RenderDoc won't have intercepted this call and so will fail to capture this frame and try again next time. This usually only invalidates the first frame you try to capture, but if you Map() many resources, and Unmap() them one by one in subsequent frames, you could hit this failed capture scenario many times in a row.
+If you start a ``Map()`` before a ``Present()`` call then call ``Unmap()`` after the ``Present()`` during the frame RenderDoc wants to capture, RenderDoc won't have intercepted this call and so will fail to capture this frame and try again next time. This usually only invalidates the first frame you try to capture, but if you ``Map()`` many resources, and ``Unmap()`` them one by one in subsequent frames, you could hit this failed capture scenario many times in a row.

-Currently the only solution to this is to change the pattern of Map()/Unmap() such that they are contained within a frame.
+Currently the only solution to this is to change the pattern of ``Map()``/``Unmap()`` such that they are contained within a frame.
+
+.. _gamma-linear-display:

 Gamma display of linear data, or "Why doesn't my texture look right?"
 ---------------------------------------------------------------------

-Gamma/SRGB correctness is a rather painful subject. If we could all just agree to store everything in 32bit float data we could probably do away with it. Until that time we have to worry about displaying textures while making sure to respect SRGB.
+Gamma/sRGB correctness is a rather painful subject. If we could all just agree to store everything in 32bit float data we could probably do away with it. Until that time we have to worry about displaying textures while making sure to respect sRGB.

-For texture formats that explicitly specify that they contain SRGB data this isn't a problem and everything works smoothly. Note that RenderDoc shows picked texel values in linear float format, so if you pick a pixel that is 0.5, 0.5, 0.5, the actual bytes might be stored as say 186, 186, 186.
+For texture formats that explicitly specify that they contain sRGB data this isn't a problem and everything works smoothly. Note that RenderDoc shows picked texel values in linear float format, so if you pick a pixel that is 0.5, 0.5, 0.5, the actual bytes might be stored as say 186, 186, 186.

-For other textures it's more difficult - for starters they may actually contain SRGB data but the correction is handled by shaders so there's no markup. Or indeed the app may not be gamma-correct so the data is SRGB but uncorrected. If we display these textures in a technically correct way, such that the data is not over or under gamma-corrected, the result often looks 'wrong' or unintuitively different from expected.
+For other textures it's more difficult - for starters they may actually contain sRGB data but the correction is handled by shaders so there's no markup. Or indeed the app may not be gamma-correct so the data is sRGB but uncorrected. If we display these textures in a technically correct way, such that the data is not over or under gamma-corrected, the result often looks 'wrong' or unintuitively different from expected.

-Nothing is actually wrong here except perhaps that when visualising linear data it is often more convenient to "overcorrect" such that the data is perceptually linear. A good example to use is a normal map: The classic deep blue of (127,127,255) flat normals is technically incorrect as everyone is used to visualising these textures in programs that display the data as if it were SRGB (which is the convention for normal images that do not represent vectors).
+Nothing is actually wrong here except perhaps that when visualising linear data it is often more convenient to "overcorrect" such that the data is perceptually linear. A good example to use is a normal map: The classic deep blue of (127,127,255) flat normals is technically incorrect as everyone is used to visualising these textures in programs that display the data as if it were sRGB (which is the convention for normal images that do not represent vectors).

-You can override this behaviour on any texture that isn't listed as explicitly SRGB with the gamma (γ) button - toggle this off and the overcorrection will be disabled.
+You can override this behaviour on any texture that isn't listed as explicitly sRGB with the gamma (γ) button - toggle this off and the overcorrection will be disabled.

 RenderDoc makes my bug go away! Or causes new artifacts that weren't there
 --------------------------------------------------------------------------
@@ -120,18 +123,20 @@ During capture the main impact of having RenderDoc enabled is that timings will

 The two primary causes of differences between the captured program and the replayed log (for better or for worse) are:

-#. 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.
+#. ``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 as an optimisation 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.

-    This behaviour can be overridden by enabling 'Save all initials' in the :doc:`capture options <../how/how_capture_log>`.
+  This behaviour can be overridden by enabling 'Save all initials' in the :doc:`capture options <../how/how_capture_log>`.

 I can't launch my program for capture directly. Can I capture it anyway?
 ------------------------------------------------------------------------

 There is an option for capturing programs using RenderDoc where you can't easily set up a direct launch of the process.

-More details can be found in the capture options page which details how to use it, however you should take care to read the warnings! This option isn't without its risks, so you need to be sure you know what you're doing before using it. It should always be used as a last resort when there is no other option.
+More details can be found in the :ref:`capture options page <global-process-hook>` which details how to use it, however you should take care to read the warnings! The global process hooking option isn't without its risks, so you need to be sure you know what you're doing before using it. It should always be used as a last resort when there is no other option.
+
+.. _view-image-files:

 I'd like to use RenderDoc's texture viewer for dds files, or other images. Can I?
 ---------------------------------------------------------------------------------
@@ -140,34 +145,34 @@ Yes you can!

 Simply drag in an image file, or open it via file → open. RenderDoc will open the image if it is supported, and display it as if there were a log open with only one texture.

-RenderDoc supports these formats: .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. For dds files RenderDoc supports all DXGI formats, compressed formats, arrays and mips - all of which will display as expected.
+RenderDoc supports these formats: ``.dds``, ``.hdr``, ``.exr``, ``.bmp``, ``.jpg``, ``.png``, ``.tga``, ``.gif``, ``.psd``. For ``.dds`` files RenderDoc supports all DXGI formats, compressed formats, arrays and mips - all of which will display as expected.

-Any modifications to the image while open in RenderDoc will be refreshed in the viewer. However if the image metadata changes (dimension, format, etc) then this will likely cause artifacts.
+Any modifications to the image while open in RenderDoc will be refreshed in the viewer. However if the image metadata changes (dimension, format, etc) then this will likely cause artifacts or incorrect rendering, and you'll have to re-open the image.

 I think I might be overwriting Map() boundaries, can I check this?
 ------------------------------------------------------------------

-Yes RenderDoc can be configured to insert a boundary marker at the end of the memory returned from a Map() call. If this marker gets overwritten during a captured frame then a message box will pop up alerting you, and clicking Yes will break into the program in the debugger so that you can investigate the callstack.
+Yes RenderDoc can be configured to insert a boundary marker at the end of the memory returned from a ``Map()`` call. If this marker gets overwritten during a captured frame then a message box will pop up alerting you, and clicking Yes will break into the program in the debugger so that you can investigate the callstack.

-To enable this behaviour, select the 'Verify Map() Writes' option when :doc:`capturing <../window/capture_log_attach>`.
+To enable this behaviour, select the ``Verify Map() Writes`` option when :doc:`capturing <../window/capture_log_attach>`.

 RenderDoc is complaining about my OpenGL app in the overlay - what gives?
 -------------------------------------------------------------------------

 The first thing to remember is that **RenderDoc only supports Core 3.2 and above OpenGL**. If your app is using features from before 3.2 it almost certainly won't work as most functionality is not supported. A couple of things like not creating a VAO (which are required in core profile) and luminance textures (which don't exist in core profile) are allowed, but none of the fixed function pipeline will work, etc etc.

-If your app is not using the CreateContextAttribs API then RenderDoc will completely refuse to capture, and will display overlay text to this effect using the simplest fixed-function pipeline code, so it will run on any OpenGL app, even on a 1.4 context or similar.
+If your app is not using the ``CreateContextAttribs`` API then RenderDoc will completely refuse to capture, and will display overlay text to this effect using the simplest fixed-function pipeline code, so it will run on any OpenGL app, even on a 1.4 context or similar.

-If your app did use the CreateContextAttribs API, RenderDoc will allow you to capture, but compatibility profiles will have a warning displayed in the overlay - this is because you could easily use old functionality as it is all still available in the context.
+If your app did use the ``CreateContextAttribs`` API, RenderDoc will allow you to capture, but compatibility profiles will have a warning displayed in the overlay - this is because you could easily use old functionality as it is all still available in the context.

 Can I tell via the graphics APIs if RenderDoc is present at runtime?
 --------------------------------------------------------------------

-Yes indeed. Some APIs offer ways to do this already - D3DPERF_GetStatus(), ID3DUserDefinedAnnotation::GetStatus() and ID3D11DeviceContext2::IsAnnotationEnabled().
+Yes indeed. Some APIs offer ways to do this already - ``D3DPERF_GetStatus()``, ``ID3DUserDefinedAnnotation::GetStatus()`` and ``ID3D11DeviceContext2::IsAnnotationEnabled()``.

 In addition to those:

-Querying an ID3D11Device for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}`` will return an IUnknown* and S_OK when RenderDoc is present.
+Querying an ``ID3D11Device`` for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}`` will return an ``IUnknown*`` and ``S_OK`` when RenderDoc is present.

 `GL_EXT_debug_tool <https://renderdoc.org/debug_tool.txt>`_ is implemented on RenderDoc, which is an extension I've proposed for this purpose (identifying when and which tool is injected in your program). It allows you to query for the presence name and type of a debug tool that's currently hooked. At the time of writing only RenderDoc implements this as I've only just proposed the extension publicly, but in future you can use the queries described in that spec.

@@ -175,12 +180,12 @@ Querying an ID3D11Device for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}`` wil

    It's unlikely the extension will ever be 'made official', so these enumerants can be used:

-.. highlight:: c++
-.. code:: c++
+    .. highlight:: c++
+    .. code:: c++

-    #define GL_DEBUG_TOOL_EXT                 0x6789
-    #define GL_DEBUG_TOOL_NAME_EXT            0x678A
-    #define GL_DEBUG_TOOL_PURPOSE_EXT         0x678B
+        #define GL_DEBUG_TOOL_EXT                 0x6789
+        #define GL_DEBUG_TOOL_NAME_EXT            0x678A
+        #define GL_DEBUG_TOOL_PURPOSE_EXT         0x678B

 A similar extension for Vulkan will be proposed after release.

@@ -189,7 +194,7 @@ A similar extension for Vulkan will be proposed after release.
 My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?
 ---------------------------------------------------------------------------------

-If you get textures that are just named 'texture0' and 'texture1' or constant/uniform buffers named 'cbuffer2' then this indicates that you have stripped optional reflection/debug information out of your shaders.
+If you get textures that are just named ``texture0`` and ``texture1`` or constant/uniform buffers named ``cbuffer2`` then this indicates that you have stripped optional reflection/debug information out of your shaders.

 This optional information is generated by the compiler, but is not required for API correctness so some codebases will strip the information out after processing it offline, and so it will not be available for RenderDoc to fetch.

@@ -108,11 +108,11 @@ As Vulkan is still in early support, some features are not yet supported. Featur

 * Support for Vulkan 1.0 on Windows and Linux.
 * Optional network support. The main use case is capture &amp; replay on the same machine, but you can also attach over the network, and replay on a remote host.
-* Event browsing, with debug marker extension based tree.
+* Event browsing, with ``VK_EXT_debug_marker`` extension based tree.
 * Full Vulkan Pipeline display.

    * Resources are shown on the stage that references them, so each shader stage shows a list of the resources that it uses. Uniform buffers are separated out for clarity, but all other resources are listed together along with their descriptor set and binding point.
-    * Where available debug marker labelled names are displayed, along with reflection data from the SPIR-V to clarify usage.
+    * Where available ``VK_EXT_debug_marker`` labelled names are displayed, along with reflection data from the SPIR-V to clarify usage.

 * SPIR-V disassembly display.
 * Timeline bar of the scene hierarchy.
@@ -142,7 +142,7 @@ As Vulkan is still in early support, some features are not yet supported. Featur
 * Simple per-drawcall timings.
 * Python scripting console, giving access to some of the RenderDoc internals and core data structures.

-Capturing on Linux is possible, although there is no native UI. The renderdoccmd program allows capturing on the command line, as well as opening a 'preview' window of the final frame of the framebuffer.
+Capturing on Linux is possible, although there is no native UI. The ``renderdoccmd`` program allows capturing on the command line, as well as opening a 'preview' window of the final frame of the framebuffer.

 See Also
 --------
@@ -17,7 +17,7 @@ Things to Note
  RenderDoc has no runtime dependencies on Visual Studio or the DirectX or Windows SDK, and should run anywhere that a normal DirectX application will run - i.e. on Artist or QA machines.

  Currently RenderDoc also assumes feature level 11+ hardware for the replay app. It can capture applications running at a lower feature level, but when replaying if 11+ hardware isn't available, RenderDoc will fall back to WARP software emulation and will run slowly.
-* 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`.
+* 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.
@@ -3,7 +3,7 @@ Quick Start

 This document serves as a brief introduction to how to use RenderDoc to capture and analyse your application. It doesn't go into much detail about exactly what functionality is available for digging into things, as this can be found elsewhere. Instead it focuses on just the workflow from start to finish and roughly where to look for different things.

-For this tutorial we will be using a slightly modified version of the CascadedShadowMaps sample from the Microsoft DirectX SDK (June 2010).
+For this tutorial we will be using a slightly modified version of the CascadedShadowMaps sample from the Microsoft DirectX SDK.

 Capturing a log
 ---------------
@@ -21,9 +21,9 @@ More details of the specific options and their functionality can be found in the

 .. note::

-    It's best to choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa
+    You should choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa

-    You can only capture a 64-bit process with a 64-bit build of RenderDoc. A 32-bit process can be captured by any build of RenderDoc.
+    You can only capture a 64-bit process with a 64-bit build of RenderDoc. A 32-bit process can be captured by either build of RenderDoc.

 RenderDoc in-app
 ----------------
@@ -67,7 +67,7 @@ There are various visualisation controls that allow you to select different chan

  E.g. if you select render target 0 then the texture display will update to show the currently bound render target 0 regardless of which texture that is. If the slot you are following becomes unbound or unused, the previous texture will still be displayed up until you select a different pipeline slot, or the slot is bound again. Unbound texture slots show up with *Unbound* listed under their thumbnail.

-  To open a specific texture and watch it even as it changes slots or becomes unbound, you can open it in a new locked tab. Right click on the thumbnail and 'open in new locked tab', or :doc:`open it by name <../how/how_view_texture>`.
+  To open a specific texture and watch it even as it changes slots or becomes unbound, you can open it in a new locked tab. Double click on it, right click on it and 'open in new locked tab', or :doc:`open it by name <../how/how_view_texture>`.

 * The format and dimensions of the texture are displayed on the status bar just below the texture display itself.
  Also on this status bar you can see the current pixel co-ordinate that you are hovering over, as well as the 'picked' pixel value which can be inspected by right clicking anywhere on the texture display.
@@ -6,25 +6,24 @@ Tips & Tricks

 This page is a random hodge-podge of different tips and tricks that might not be obvious and aren't practical to make clear in the UI - e.g. keyboard shortcuts, edge cases and suchlike.

-#. File associations for .rdc and .cap files can be set up in the installer or in the :doc:`../window/options_window`. These allow automatic opening of capture logs or capture settings files directly from files.
+#. File associations for ``.rdc`` and ``.cap`` files can be set up in the installer or in the :doc:`../window/options_window`. These allow automatic opening of capture logs or capture settings files directly from files.

   .. note::

       These associations must be re-created if RenderDoc is moved to another folder.

-.. _view-image-files:
-
-#. RenderDoc can be used as an image viewer! If you drag in or use file → open, you can open images in a variety of formats - .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. The image will load up in RenderDoc's texture viewer and you can use the normal controls to view it as if it were a texture in a log. Note that dds files support all DXGI formats, compressed formats, arrays and mips - all of which will display as expected. If the file is modified, RenderDoc will reload it and display it. Note that changing the image's dimensions or format will likely cause problems.
-#. If a .cap file is saved with the "auto-start" option enabled, launching RenderDoc by opening this file will cause RenderDoc to automatically trigger a capture with the given options. This is useful for saving a common path & set of options that you regularly re-run.
+#. RenderDoc can be used as an image viewer! If you drag in or use file → open, you can open images in a variety of formats - ``.dds``, ``.hdr``, ``.exr``, ``.bmp``, ``.jpg``, ``.png``, ``.tga``, ``.gif``, ``.psd``. The image will load up in RenderDoc's texture viewer and you can use the normal controls to view it as if it were a texture in a log. Note that ``.dds`` files support all DXGI formats, compressed formats, arrays and mips - all of which will display as expected. If the file is modified, RenderDoc will reload it and display it. Note that changing the image's dimensions or format will likely cause problems.
+#. If a ``.cap`` file is saved with the "auto-start" option enabled, launching RenderDoc by opening this file will cause RenderDoc to automatically trigger a capture with the given options. This is useful for saving a common path & set of options that you regularly re-run.

   For more information check out the :doc:`../window/capture_log_attach` page.

 #. If you'd like to see the geometry data with each component separated out and formatted, either open "Mesh Output" under the window menu, or click the Go Arrow |go_arrow| on the input layouts in the :doc:`../window/pipeline_state`.
 #. Right clicking on one of the channel buttons in the texture viewer (R, G, B, A) will either select only that channel, or if it's already the only one selected it will select all of the others. This is useful e.g. to toggle between viewing RGB and alpha, or for looking at individual channels in a packed texture or render target.
 #. Similarly, right-clicking on the 'auto-fit' button |wand| will auto-fit whenever the texture or event changes, so that the visible range is maintained as you move through the frame. This can be useful if jumping between places where the visible range is very different.
+   Note though that by default the range will be remembered or each texture, so once you have fitted the range once for each texture you should be able to flip back and forth more easily.
 #. You can double click on a thumbnail in the texture viewer to open a :doc:`locked texture <../how/how_view_texture>` tab
 #. You can close tabs by middle clicking on them.
-#. You can trigger a capture from code. renderdoc.dll exports an :doc:`../in_application_api` for this purpose, defined in ``renderdoc_app.h`` in the distributions:
+#. You can trigger a capture from code. ``renderdoc.dll`` exports an :doc:`../in_application_api` for this purpose, defined in ``renderdoc_app.h`` in the distributions:

   .. highlight:: c++
   .. code:: c++
@@ -46,7 +45,7 @@ This page is a random hodge-podge of different tips and tricks that might not be

   The next ``Swap()`` after this call will begin the captured frame, and the ``Swap()`` after that will end it (barring  complications)

-   You can also use the RENDERDOC_StartFrameCapture and RENDERDOC_EndFrameCapture functions to precisely define the period to be  captured. For more information look at the renderdoc_app.h header in the source code.
+   You can also use the ``RENDERDOC_StartFrameCapture()`` and ``RENDERDOC_EndFrameCapture()`` functions to precisely define the period to be captured. For more information look at the :doc:`../in_application_api` documentation or the ``renderdoc_app.h`` header.

 #. When you have right clicked to select a pixel in the texture viewer, you can perform precise refinements with the arrow keys to nudge the selection in each direction.
 #. To get API debug or error messages, enable "Create Debug Device" when capturing then check out the :doc:`../window/debug_messages` window.
@@ -65,12 +64,12 @@ This page is a random hodge-podge of different tips and tricks that might not be
       // if GL_EXT_debug_tool is present (see https://renderdoc.org/debug_tool.txt)
       glIsEnabled(GL_DEBUG_TOOL_EXT);

-       // Until enumerants are assigned (if that ever happens):
+       // Use reserved enumerants as the extension will not become official
       #define GL_DEBUG_TOOL_EXT                 0x6789
       #define GL_DEBUG_TOOL_NAME_EXT            0x678A
       #define GL_DEBUG_TOOL_PURPOSE_EXT         0x678B

-#. RenderDoc can be informed about separated debug shader blobs through API specific ways:
+#. RenderDoc can be informed about separated debug shader blobs through API specific ways - see :ref:`unstripped-shader-info` for more details:

   .. highlight:: c++
   .. code:: c++
@@ -10,7 +10,7 @@ It can be useful when tracking down problems to have an idea of where each API c

 .. warning::

-	The callstack gathering uses dbghelp.dll. If you're using this dll for some other debugging functionality in your app it is highly recommended that you disable it, otherwise it can conflict and break RenderDoc's callstack capture.
+	The callstack gathering uses ``dbghelp.dll``. If you're using this dll for some other debugging functionality in your app it is highly recommended that you disable it, otherwise it can conflict and break RenderDoc's callstack capture.

 .. note::

@@ -25,7 +25,7 @@ When launching a capture (as in :doc:`how_capture_log`) you should enable 'colle

 	Collect Callstacks: Option enabled on the capture dialog.

-If you wish to save some time &amp; overhead you can then enable 'Only drawcall stacks'. This will only collect callstacks when a drawcall-type API call is made. This can be a good-enough trade off that still gets you the information you need, at a lower cost. After this point you can run the program and capture as usual.
+If you wish to save some time & overhead you can then enable 'Only drawcall stacks'. This will only collect callstacks when a drawcall-type API call is made. This can be a good-enough trade off that still gets you the information you need, at a lower cost. After this point you can run the program and capture as usual.

 Replaying the capture
 ---------------------
@@ -36,7 +36,7 @@ When the capture is loaded in RenderDoc the callstacks will be available in the

 	Callstack section: The callstack section expanded in API inspector.

-To resolve the symbols referenced in the capture, go to the **Tools** menu and select Resolve Symbols. If this menu option isn't available the callstacks did not successfully capture in the logfile.
+To resolve the symbols referenced in the capture, go to the Tools menu and select Resolve Symbols. If this menu option isn't available the callstacks did not successfully capture in the logfile.

 The resolving symbols process may take some time the first few instances you use it, as it may have to download symbols from the Microsoft symbol server. Each module that is loaded in the application at the time of capture will be saved and its symbols searched for.

@@ -8,7 +8,7 @@ Capturing logs

 The basic process of capturing logs is fairly straightforward.

-Opening the capture window from the menus via File -> Capture Log, the typical capture setup simply requires you to enter the executable location.
+Opening the capture window from the menus via File → Capture Log, the typical capture setup simply requires you to enter the executable location.

 By default the working directory remains empty and defaults to the directory that contains the executable location.

@@ -16,16 +16,16 @@ By default the working directory remains empty and defaults to the directory tha

 	Capturing: Capturing a logfile specifying its executable path and command line.

-Likewise, the default options generally work well for most situations, however there are a few common options to customise:
-
-* Allow Fullscreen/Allow VSync aid in debugging by preventing the app from switching into fullscreen (or vsynced) display modes, which makes them easier to attach to from a debugger on the same computer.
-* Seconds attach delay causes RenderDoc to pause for a certain number of seconds after launching the process to allow you to attach in the debugger - so that the debugger can be present to catch any problems from the beginning of the application, in case there is an issue very early in initialisation.
-* Collect callstacks allows you to get callstacks at the site of each API. There are more details available in :doc:`how_capture_callstack`.
+Likewise, the default options generally work well for most situations, however you can look at the details of each option in :doc:`../window/capture_log_attach`.

 Injecting into a Process
 ------------------------

-It is possible to inject to an already running process. By selecting the "Inject to Process" entry in the File menu, the capture dialog will modify to list the running processes rather than asking for an executable and command line parameters.
+.. warning::
+
+	The important thing to note about injecting is that RenderDoc can only inject to processes that **have not initialised or used the target API**. If this is the case RenderDoc can insert its hooks before any use of the API and work as normal. If the API has already been used or initialised the results are undefined and likely RenderDoc will simply not function as it's too late to hook in.
+
+It is possible to inject to an already running process as long as it hasn't yet initialised a graphics API. By selecting the "Inject to Process" entry in the File menu, the capture dialog will modify to list the running processes rather than asking for an executable and command line parameters.

 This can be useful if launching your application from a single exe is non-trivial and it's easier to inject into the process after it has been launched.

@@ -33,11 +33,6 @@ This can be useful if launching your application from a single exe is non-trivia

 	Injecting to a selected existing process.

-.. warning::
-
-	The important thing to note about injecting is that RenderDoc can only inject to processes that **have not initialised or used the target API**. If this is the case RenderDoc can insert its hooks before any use of the API and work as normal. If the API has been used or initialised the results are undefined and likely RenderDoc will simply not function as it's too late to hook in.
-
-
 .. note::

 	If RenderDoc is not running as administrator, it cannot inject into processes that are running with elevated permissions. In this case you can either run RenderDoc as administrator (not recommended unless necessary), or re-run the process as the normal user running RenderDoc.
@@ -47,11 +42,11 @@ Capture setting files

 Commonly in development, the capture parameters don't change. In fact most likely the same application or couple of applications are launched in exactly the same way repeatedly as development iterates.

-To make this process easier RenderDoc supports saving and loading configuration sets to a file. While on the capture dialog, click 'Save' to save to a .cap file which contains both the executable, working directory and command line - as well as the options that are selected.
+To make this process easier RenderDoc supports saving and loading configuration sets to a file. While on the capture dialog, click 'Save' to save to a ``.cap`` file which contains both the executable, working directory and command line - as well as the options that are selected.

-This .cap file can be executed when RenderDoc's file associations are set up, and RenderDoc will load this file and present you with the capture dialog on startup.
+This ``.cap`` file can be executed when RenderDoc's file associations are set up, and RenderDoc will load this file and present you with the capture dialog on startup.

-You can also use the "Auto start" option - when this option is enabled then a .cap file will immediately launch the program when it is loaded. This can allow you to configure a .cap which will open RenderDoc and launch the target application with the pre-configured settings in one click. If you wish to disable this, just uncheck the option and re-save to the same .cap file.
+You can also use the "Auto start" option - when this option is enabled then a .cap file will immediately launch the program when it is loaded. This can allow you to configure a .cap which will open RenderDoc and launch the target application with the pre-configured settings in one click. If you wish to disable this, just uncheck the option and re-save to the same ``.cap`` file.

 See Also
 --------
@@ -6,7 +6,7 @@ This page details how to set up a custom shader for visualisation. This can be u
 Introduction
 ------------

-The basic process of setting up the custom shader involves writing a .hlsl or .glsl file that will be compiled and used by RenderDoc. Note that the type used matches the API used, and RenderDoc will automatically list only the hlsl shaders you have if you load a log with D3D11, and vice-versa for OpenGL.
+The basic process of setting up the custom shader involves writing a ``.hlsl`` or ``.glsl`` file that will be compiled and used by RenderDoc. Note that the type used matches the API used, and RenderDoc will automatically list only the hlsl shaders you have if you load a log with D3D11, and vice-versa for OpenGL.

 There are several special global variables that can be specified and will be filled in with values by RenderDoc.

@@ -14,7 +14,7 @@ Your pixel shader defines an operation that transforms the raw value from the in

 Multisampled textures will be resolved before being passed to your function. Depth and stencil textures will be bound separately and passed as multisampled resources.

-To set up your shader, it's recommended that you use the UI defined in the documentation for the :doc:`../window/texture_viewer`, but you can manually create a .hlsl or .glsl file in ``%APPDATA%\RenderDoc\``. The file must contain an entry point main() that returns float4, and uses any of the below inputs. These shaders are loaded when RenderDoc loads a logfile, and RenderDoc watches for any changes to the files (either externally or in the shader editor in RenderDoc) and automatically reloads them.
+To set up your shader, it's recommended that you use the UI defined in the documentation for the :doc:`../window/texture_viewer`, but you can manually create a ``.hlsl`` or ``.glsl`` file in ``%APPDATA%\RenderDoc\``. The file must contain an entry point ``main()`` that returns float4, and uses any of the below inputs. These shaders are loaded when RenderDoc loads a logfile, and RenderDoc watches for any changes to the files (either externally or in the shader editor in RenderDoc) and automatically reloads them.

 Predefined inputs
 -----------------
@@ -25,7 +25,7 @@ There are several pre-defined inputs that can either be taken as parameters to t

 	Type and capitalisation is important for these variables, so ensure you use the right declaration!

-The shader editor when using the UI can be used to insert these snippets for you, with the right type and spelling. Be careful for GL though, as these snippets are inserted at the top of the file and so are inserted before the #version statement.
+The shader editor when using the UI can be used to insert these snippets for you, with the right type and spelling. Be careful for GL though, as these snippets are inserted at the top of the file and so are inserted before the ``#version`` statement.

 UV co-ordinates (D3D11 only)
 ````````````````````````````
@@ -56,10 +56,10 @@ Texture dimensions

 This variable will be filled out with the following values:

-* ``.x =``  Width
-* ``.y =``  Height (if 2D or 3D)
-* ``.z =``  Depth if 3D or array size if an array
-* ``.w =``  Number of mip levels
+* ``.x``  Width
+* ``.y``  Height (if 2D or 3D)
+* ``.z``  Depth if 3D or array size if an array
+* ``.w``  Number of mip levels

 Selected Mip level
 ``````````````````
@@ -200,7 +200,7 @@ These resources are bound sparsely with the appropriate type for the current tex

 When a cubemap texture is bound, it is bound both to the 2D Array as well as the Cube Array. If a depth-stencil texture has both components, the relevant depth and stencil resources will both be bound at once.

-To determine which resource to sample from you can use the RENDERDOC_TexType variable above.
+To determine which resource to sample from you can use the ``RENDERDOC_TexType`` variable above.

 Usually the float textures are used, but for unsigned and signed integer formats, the relevant integer resources are used.

@@ -34,17 +34,19 @@ Debugging a Pixel

 Pixel debugging is launched from the texture viewer. For more details on selecting the pixel to debug see :doc:`how_inspect_pixel`.

-When a given pixel is selected you can click the debug button underneath the pixel context. This will launch the shader viewer with the selected pixel and sample being debugged. The inputs to the pixel will be automatically filled in.
+When a given pixel is selected you can click the history button underneath the pixel context. This will launch the :ref:`pixel-history` window with the selected pixel showing every modification. You can then choose to debug any of the triangles that generated a change.
+
+If you already have the current drawcall selected that you want to debug, you can click the debug button to skip the pixel history and jump straight to the debugger. The inputs to the pixel will be automatically filled in.

 There are a couple of things to note while pixel debugging:

-* If the drawcall selected doesn't write to the pixel you have highligted, a pixel history window will open to let you choose which draw call to debug.
+* If the drawcall selected doesn't write to the pixel you have highlighted, the pixel history window will open to let you choose which draw call to debug.
 * If a drawcall overdraws the same pixel several times then the results of debugging will come from the last fragment that passed the depth test. If you wish to choose a particular fragment from the list then first launch the pixel history and choose which fragment to debug from the list there.

 Debugging a Compute thread
 --------------------------

-To debug a compute thread simply go to the compute shader section of the pipeline state viewer and enter the group and thread ID of the thread you would like to debug. This thread will be debugged in isolation as with any other shader invocation.
+To debug a compute thread simply go to the compute shader section of the pipeline state viewer and enter the group and thread ID of the thread you would like to debug. This thread will be debugged in isolation with no other threads in the group running.

 This means there can be no synchronisation with any other compute thread running and the debugging will run from start to finish as if no other thread had run.

@@ -68,7 +70,7 @@ The toolbar at the top gives controls for the program flow through the shader. |

 The keyboard shortcuts for these controls are :kbd:`F5` and :kbd:`Shift-F5` respectively.

-You can set a breakpoint by pressing F9 (this will also remove a breakpoint that is already there). When running in each direction or to cursor (see below) if execution hits a breakpoint it will stop.
+You can set a breakpoint by pressing :kbd:`F9` (this will also remove a breakpoint that is already there). When running in each direction or to cursor (see below) if execution hits a breakpoint it will stop.

 .. |stepnext| image:: ../imgs/icons/stepnext.png
 .. |stepprev| image:: ../imgs/icons/stepprev.png
@@ -110,9 +112,9 @@ The other window will contain variable/mutable registers. These contain temporar

 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.

-Swizzles follow the standard hlsl rules - .[xyzw] or .[rgba] in any permutation or repetition will show those channels.
+Swizzles follow the standard hlsl rules - ``.[xyzw]`` or ``.[rgba]`` in any permutation or repetition will show those channels.

-The custom typecast can be any of ,x ,i ,d ,f ,u ,b to display the register as hex, signed integer, double, float, unsigned, or bitwise respectively.
+The custom typecast can be any of ``,x`` ``,i`` ``,d`` ``,f`` ``,u`` ``,b`` to display the register as hex, signed integer, double, float, unsigned, or bitwise respectively.

 .. figure:: ../imgs/Screenshots/ShaderWatch.png

@@ -11,9 +11,9 @@ How to edit a custom shader

 :doc:`Custom visualisation shaders <how_custom_visualisation>` allow you to define your own transformation on any texture you're viewing before it is displayed. Mostly this is useful for decoding packed or custom-format data, or displaying some data in a more visually intuitive fashion.

-These shaders live as .hlsl/.glsl files in ``%APPDATA%\RenderDoc\``, and can be edited in your editor of choice, any changes saved will be reloaded. Note however that there is currently no way to see the compile warnings or errors produced. This is probably best for when you have an existing shader to drop-in.
+These shaders live as ``.hlsl``/``.glsl`` files in ``%APPDATA%\RenderDoc\``, and can be edited in your editor of choice, any changes saved will be reloaded. Note however that there is currently no way to see the compile warnings or errors produced. This is probably best for when you have an existing shader to drop-in.

-To edit a shader inside RenderDoc simply click the edit button |page_white_edit| when you have selected your custom shader for use. This will launch a new window with the custom shader and any changes you make to this shader will be saved to the .hlsl/.glsl file and compiled and reflected in the texture viewer as long as you have that custom shader selected.
+To edit a shader inside RenderDoc simply click the edit button |page_white_edit| when you have selected your custom shader for use. This will launch a new window with the custom shader and any changes you make to this shader will be saved to the ``.hlsl``/``.glsl`` file and compiled and reflected in the texture viewer as long as you have that custom shader selected.

 How to edit a scene shader
 --------------------------
@@ -33,9 +33,6 @@ Any changes to the shader will affect any drawcall using this shader, not just t

 	One unfortunate artifact of how the shader debug info works, not all #included hlsl files will come along with the debug info, only those files that contain compiled code. RenderDoc automatically replaces any #includes to missing files with just an empty comment, but unfortunately this can lead to compile errors in unused code.

-	This can also interact badly with another artifact - macro definitions passed directly to the compiler are not included in the debug info and so RenderDoc can't include them when recompiling. If you rely on any defines, you will need to add them manually to the top of your root hlsl file.
-
-
 Using the built-in shader editor
 --------------------------------

@@ -45,6 +45,10 @@ This context display shows a zoomed in view of the texture around the area that

 The pixel context viewer can also allow you to launch pixel debugging. Once a pixel is picked the button below the context is activated which will launch the shader debugger. More information about this is available: :doc:`how_debug_shader`.

+It also allows you to launch a pixel history view, showing every modification to this pixel in the frame up to the current point.
+
+.. _pixel-history:
+
 Pixel History
 -------------

@@ -22,6 +22,8 @@ The way this is done varies by API. In D3D11 the resource is named in this way:

 In OpenGL this can be done with ``GL_KHR_debug`` - ``glObjectLabel``.

+In Vulkan you can enable the ``VK_EXT_debug_marker`` extension, which is provided by RenderDoc, and use the ``vkDebugMarkerSetObjectName`` function.
+
 When this texture is bound to the pipeline it will be listed like so:

 .. figure:: ../imgs/Screenshots/NamedTex.png
@@ -1,8 +1,3 @@
-.. RenderDoc documentation master file, created by
-   sphinx-quickstart on Thu May 12 16:59:09 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 RenderDoc
 =========

@@ -10,7 +5,7 @@ RenderDoc

 |renderdoc_logo|

-Welcome to RenderDoc - a graphics debugger, currently available for D3D11, Vulkan and OpenGL development on windows.
+Welcome to RenderDoc - a graphics debugger currently available for D3D11, Vulkan and OpenGL development on windows.

 This document serves primarily as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them.

@@ -5,7 +5,7 @@ Introduction

 |renderdoc_logo|

-Welcome to RenderDoc - a graphics debugger, currently available for D3D11, Vulkan and OpenGL development on windows.
+Welcome to RenderDoc - a graphics debugger currently available for D3D11, Vulkan and OpenGL development on windows.

 This document serves primarily as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them.

@@ -72,7 +72,7 @@ In addition to this, you can specify a row offset which is useful in remaining a

 	Buffer specification: Specifying a custom buffer format.

-Below are listed the basic types. You can append a number to each of these to make an N-wide vector (e.g. ushort4 or float3, or uvec4/vec3). You can also specify matrices as float3x4 or mat3x4. By default matrices are column major, but you can change this by prepending row_major as you would in hlsl.
+Below are listed the basic types. You can append a number to each of these to make an N-wide vector (e.g. ``ushort4`` or ``float3``, or ``uvec4``/``vec3``). You can also specify matrices as ``float3x4`` or ``mat3x4``. By default matrices are column major, but you can change this by prepending ``row_major`` as you would in hlsl.

 * ``uint`` - unsigned 32bit integer
 * ``bool`` - unsigned 32bit integer (this is the format for hlsl bools)
@@ -7,7 +7,7 @@ After launching a capture a connection dialog will open to allow you to manage a

 .. note::

-  NOTE: The Load Settings and Save Settings buttons on this dialog refer to loading and saving the set of settings and options configured on this dialog. They do _not_ refer to loading and saving the logs produced from capturing - that is done from the File menu.
+  NOTE: The Load Settings and Save Settings buttons on this dialog refer to loading and saving the set of settings and options configured on this dialog. They do *not* refer to loading and saving the logs produced from capturing - that is done from the File menu.

 Capturing
 ---------
@@ -24,7 +24,7 @@ The ``...`` buttons next to the executable path and working directory can be use

 When you are ready to capture simply click the ``Capture`` button in the bottom right.

-If you wish to save these particular settings you can click ``Save`` to save them to a .cap file. This .cap file can either be loaded in manually, accessed through the ``Recent Captures`` menu. The .cap file can be associated with RenderDoc, and if so launching RenderDoc from this file will automatically load the capture settings. If "Auto start" is checked then double clicking on the .cap file will immediately trigger a capture with the given settings.
+If you wish to save these particular settings you can click ``Save`` to save them to a ``.cap`` file. This ``.cap`` file can either be loaded in manually, accessed through the ``Recent Captures`` menu. The ``.cap`` file can be associated with RenderDoc, and if so launching RenderDoc from this file will automatically load the capture settings. If "Auto start" is checked then double clicking on the ``.cap`` file will immediately trigger a capture with the given settings.

 .. note::
  The process will be launched with the same permissions and by the same user as RenderDoc was launched. If your process requires specific permissions (such as administrator permissions) you will need to launch RenderDoc with these permissions.
@@ -32,6 +32,9 @@ If you wish to save these particular settings you can click ``Save`` to save the
 Inject into Process
 -------------------

+.. caution::
+  The process **must not** have invoked or initialised the API to be used, as this will be too late for RenderDoc to hook and capture it. At best RenderDoc will not capture, at worst it may cause crashes or undefined behaviour. Only inject to processes you can guarantee are early enough in their initialisation that they have not used the graphics API.
+
 When invoked through ``Inject into Process`` the capture dialog modifies itself to give a list of processes running on the target system.

 A list of processes is fetched once when the dialog is opened, but this can be refreshed by clicking on the refresh button below the list. Select the process you would like to inject into and click Inject.
@@ -40,9 +43,6 @@ A list of processes is fetched once when the dialog is opened, but this can be r

  Injecting: Injecting into an already-running process via RenderDoc.

-.. caution::
-  The process **must not** have invoked or initialised the API to be used, as this will be too late for RenderDoc to hook and capture it. At best RenderDoc will not capture, at worst it may cause crashes or undefined behaviour. Only inject to processes you can guarantee are early enough in their initialisation that they have not used the graphics API.
-
 Capture Options
 ---------------

@@ -52,23 +52,33 @@ Allow Fullscreen simply means that RenderDoc will not interfere with any attempt

 If this option is unchecked, RenderDoc will attempt to modify any such attempt to an equivalent windowed mode.

+----------
+
  | ``Allow VSync`` Default: ``Enabled``

 Allow VSync functions very similarly to Allow Fullscreen. When disabled, RenderDoc will prevent any attempt to VSync by the application. This can be useful given that there is a certain degree of inevitable overhead from running with RenderDoc and VSync can amplify that.

+----------
+
  | ``Seconds Delay`` Default: ``0 Seconds (Disabled)``

 This option causes RenderDoc to stall for a defined number of seconds immediately after launching the process. Most commonly this is used so that you can launch a program in RenderDoc and immediately attach a traditional debugger before any significant code is executed.

 This can be useful e.g. when early initialisation needs to be debugged.

+----------
+
  | ``Collect Callstacks`` Default: ``Disabled``

 This option will cause RenderDoc to save a callstack from user code into the API at every API call during the frame being captured. This can then be resolved later and used to determine where the application is calling each API call. More details can be found in :doc:`../how/how_capture_callstack`.

+----------
+
  | ``Only Drawcall Callstacks`` Default: ``Disabled``

-This option modifies the above capturing of callstacks to only be saved for drawcall-type API calls. This can reduce the CPU load, as well as file-size and memory overhead of capturing callstacks for every API call which may not be desired. Only valid if Collect Callstacks is enabled.
+This option modifies the above capturing of callstacks to only be saved for drawcall-type API calls. This can reduce the CPU load, as well as file-size and memory overhead of capturing callstacks for every API call which may not be desired. Only valid if ``Collect Callstacks`` is enabled.
+
+----------

  | ``Create Debug Device`` Default: ``Disabled``

@@ -78,22 +88,30 @@ Create Debug Device causes RenderDoc to enable the API's built-in debugging, and
 * For OpenGL this means ``ARB_debug_output`` is automatically enabled.
 * For Vulkan the ``VK_LAYER_LUNARG_standard_validation`` meta-layer is enabled and ``VK_EXT_debug_report`` is used to fetch any warnings or errors. The overhead from enabling this option is largely the same as the overhead of enabling the debug device without RenderDoc involved.

+----------
+
  | ``Hook into Children`` Default: ``Disabled``

 This option causes RenderDoc to hook into CreateProcess and intercept any calls to it from the target application. When this option is enabled those child processes will be injected with RenderDoc in the same way as the parent - which can be useful if you must launch your program through a launcher or level of indirection and still wish to use RenderDoc with one of the child processes.

 See below for more information on handling of child processes.

+----------
+
  | ``Save All Initials`` Default: ``Disabled``

 RenderDoc will attempt to save overhead and particularly logfile 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.

+----------
+
  | ``Ref All Resources`` Default: ``Disabled``

 One method RenderDoc uses to keep logfile sizes down is to only include the referenced dependencies of a frame within a capture. This means that even if 100 textures are allocated and present, if 50 of them are never bound to the pipeline or otherwise referenced then they will not be included in the logfile. Enabling this option will cause RenderDoc to include all live resources at the time of capture regardless of whether they are used or not.

+----------
+
  | ``Capture All Cmd Lists`` Default: ``Disabled``

 By default RenderDoc only begins capturing when you hit the capture key - any commands issued before this point are not available and so if a deferred command list was created before you hit capture and replayed after, it would not be available and RenderDoc would have to fall back and capture again in the hopes that next frame everything will be available.
@@ -108,10 +126,14 @@ If the application creates a command list early and replays it indefinitely with

 ..

+----------
+
  | ``Verify Map() Writes`` Default: ``Disabled``

 This option adds checking to any ``Map()`` calls that adds a boundary marker after any ``Map()`` pointer returned during a captured frame. These markers are checked on ``Unmap()`` and if they have been modified a message box will pop up alerting you to this, and you can click Yes to break in the debugger in the target application and investigate the problem.

+----------
+
  | ``Auto start`` Default: ``Disabled``

 This option is slightly different from the others in that it doesn't change anything for an immediate capture. When a ``.cap`` settings file is saved with the details of a particular capture, if this option is enabled then loading a ``.cap`` file from the command line (i.e. most commonly from a file association) will trigger a capture as soon as RenderDoc loads. This is useful for saving a common capture setting and running it with just one click.
@@ -125,9 +147,11 @@ Child Processes

 RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check "Hook into Children" in the options above.

-RenderDoc has a particular handling of child processes to help you navigate to the process of interest. Whenever a child process is launched, the UI is notified and a list of processes is displayed in a box on the doc:`capture_connection` window. You can double click on any of these entries to open up a new connection to that process, in a new window.
+RenderDoc has a particular handling of child processes to help you navigate to the process of interest. Whenever a child process is launched, the UI is notified and a list of processes is displayed in a box on the :doc:`capture_connection` window. You can double click on any of these entries to open up a new connection to that process, in a new window.

-If a process exits, instead of just closing the connection window if there have been no captures, instead RenderDoc looks at the child processes - if there is only one child process, it assume that process must be of interest and immediately switches to tracking that process. If there are _more_ than one child process open, the capture connection window will stay open to give you a chance to double click on those child processes to open a new connection window.
+If a process exits, instead of just closing the connection window if there have been no captures, instead RenderDoc looks at the child processes - if there is only one child process, it assume that process must be of interest and immediately switches to tracking that process. If there are *more* than one child process open, the capture connection window will stay open to give you a chance to double click on those child processes to open a new connection window.
+
+.. _global-process-hook:

 Global Process Hook
 -------------------
@@ -142,9 +166,9 @@ When you've entered a path, or filename, in the executable text at the top of th

 The shim dll will load, create a thread that checks to see if the process matches the path or filename specified, and then unload. If the process matches it will also inject RenderDoc and capturing will continue as normal. At this point you should *first disable the global hook*, then you can use the 'Attach to running instance' menu option to continue as normal.

-RenderDoc implements this behaviour by modifying the `AppInit_DLLs <http://support2.microsoft.com/kb/197571>`__ registry key to reference RenderDoc's dlls. This is not a particularly safe method but it's the only reliable method to do what we want. The shim dll is deliberately made as small and thin as possible, referencing only kernel32.dll, to minimise any risks.
+RenderDoc implements this behaviour by modifying the `AppInit_DLLs <http://support2.microsoft.com/kb/197571>`__ registry key to reference RenderDoc's dlls. This is not a particularly safe method but it's the only reliable method to do what we want. The shim dll is deliberately made as small and thin as possible, referencing only ``kernel32.dll``, to minimise any risks.

-If RenderDoc crashes or something otherwise goes wrong while these registry keys are modified, the shim dll will continue to be injected into every process which is certainly not desireable. Should anything go wrong, RenderDoc writes a .reg file that restores the registry to its previous state in ``%TEMP%``.
+If RenderDoc crashes or something otherwise goes wrong while these registry keys are modified, the shim dll will continue to be injected into every process which is certainly not desireable. Should anything go wrong, RenderDoc writes a ``.reg`` file that restores the registry to its previous state in ``%TEMP%``.

 Again, **this method should be a last resort**. Given the risks you should always try to capture directly in some way before trying this.

@@ -8,7 +8,7 @@ Annotating your frame

 The Event Browser becomes most useful when the application has user-defined annotations of sections and subsections of the frames, to allow for a more logical and ordered browsing of the frame.

-Doing this is API and platform specific. Example code for D3D11 is included below, using the D3DPERF library that is defined in d3d9.lib, which can still be used in D3D11. (The newer ID3DUserDefinedAnnotation API is also supported).
+Doing this is API and platform specific. Example code for D3D11 is included below, using the ``D3DPERF`` library that is exported by ``d3d9.dll``, which can still be used in D3D11. (The newer ``ID3DUserDefinedAnnotation`` API is also supported).

 .. highlight:: c++
 .. code:: c++
@@ -24,6 +24,8 @@ Doing this is API and platform specific. Example code for D3D11 is included belo

 This will generate a section of the frame with a subsection that includes some events, and then some further events that are siblings of the subsection.

+OpenGL can make use of the ``KHR_debug`` extension, and Vulkan can use the ``VK_EXT_debug_marker`` extension.
+
 Selecting available columns
 ---------------------------

@@ -17,14 +17,18 @@ General options

  | ``Associate .rdc with RenderDoc`` Default: ``N/A``

-This button will elevate RenderDoc to administrator privileges temporarily, and associate the .rdc file extension with RenderDoc. After doing this double clicking any .rdc file will open it in a new instance of RenderDoc.
-  
+This button will elevate RenderDoc to administrator privileges temporarily, and associate the ``.rdc`` file extension with RenderDoc. After doing this double clicking any ``.rdc`` file will open it in a new instance of RenderDoc.
+
+---------------
+
  | ``Associate .cap with RenderDoc`` Default: ``N/A``

-This button will elevate RenderDoc to administrator privileges temporarily, and associate the .cap file extension with RenderDoc. After doing this double clicking any .cap file will open a new instance of RenderDoc and show the capture dialog with the settings contained inside.
+This button will elevate RenderDoc to administrator privileges temporarily, and associate the ``.cap`` file extension with RenderDoc. After doing this double clicking any ``.cap`` file will open a new instance of RenderDoc and show the capture dialog with the settings contained inside.

 If the setting "Auto Start" is enabled, RenderDoc will then immediately trigger a capture of the target executable.

+---------------
+
  | ``Minimum decimal places on float values`` Default: ``2``

 Defines the smallest number of decimal places to display on a float, padding with 0s.
@@ -39,6 +43,8 @@ Examples:

 * With a value of 6, ``1.0f`` will be displayed as *1.000000*

+---------------
+
  | ``Maximum significant figures on decimals`` Default: ``5``

 Defines the smallest number of decimal places to display on a float, padding with 0s.
@@ -53,6 +59,8 @@ Examples:

 * With a value of 10, ``1.0f`` will be displayed as *1.00*

+---------------
+
  | ``Negative exponential cutoff value`` Default: ``5``

 Any floating point numbers that are below *E-v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal.
@@ -67,6 +75,8 @@ Examples:

 * With a value of 10, ``0.000001f`` will be displayed as *0.000001*

+---------------
+
  | ``Positive exponential cutoff value`` Default: ``7``

 Any floating point numbers that are larger *E+v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal.
@@ -81,17 +91,23 @@ Examples:

 * With a value of 2, ``123456789.0f`` will be displayed as *1.2345E8*

+---------------
+
  | ``Directory for temporary capture files`` Default: ``%TEMP%``

 This allows you to choose where on disk temporary capture files are stored between when the capture is made, and when it is either discarded or saved to a permanent location on disk. 

 By default the system temporary directory is used, but if this lies on drive with limited space, large captures could become a problem so here you can redirect the storage elsewhere.
  
+---------------
+
  | ``Allow global process hooking`` Default: ``Disabled``

 This option enables the functionality allowing capturing of programs that aren't launched directly from RenderDoc, but are launched from somewhere else.

-This option **can be dangerous** which is why you have to deliberately enable it here. Be careful when using this and only do so when necessary - more details can be found in the :doc:`capture options <capture_log_attach>` page.
+This option **can be dangerous** which is why you have to deliberately enable it here. Be careful when using this and only do so when necessary - more details can be found in the :ref:`global process hook <global-process-hook>` details.
+
+---------------

  | ``Allow periodic anonymous update checks`` Default: ``Enabled``

@@ -99,6 +115,8 @@ Every couple of days RenderDoc will send a single web request to a server to see

 If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's recommended that you manually check for updates as new versions will be made available regularly with bugfixes.

+---------------
+
  | ``Prefer monospaced fonts in UI`` Default: ``Disabled``

 This option will use a monospaced font for every place in the UI where any data or output is displayed.
@@ -121,6 +139,8 @@ Texture Viewer options

 When changing texture from one to another, when this option is enabled the range control will reset itself to [0, 1]. This will happen between any two textures, and going back and forth between two textures will also reset the range.

+---------------
+
  | ``Visible channels, mip/slice, and range saved per-texture`` Default: ``Enabled``

 Settings including which channels are displayed (red, green, blue, alpha or depth/stencil), the mip or slice/cubemap face to display, or the visible min/max range values are remembered with the texture you were looking at. In other words if you display a render target with only the alpha channel visible, then switching to view another texture will default back to RGB - and switching back to that render target will view alpha again.
@@ -141,6 +161,8 @@ This option allows you to select the unit that will be shown in the duration col

 Seconds through to nanoseconds are supported.

+---------------
+
  | ``Hide empty marker sections`` Default: ``Disabled``

 Marker sections that contain no API calls or drawcalls will be completely removed. This also applies to the Timeline Bar.
@@ -8,7 +8,7 @@ Overview

 The texture viewer consists of a couple of different sections, which will be outlined here.

-Several specific techniques or features used within the texture viewer have their own separate pages that go into more detail. You might find more useful information there if they cover what you are looking for: :doc:`../how/how_view_texture`, :doc:`../how/how_inspect_pixel`, :doc:`../how/how_custom_visualisation`.
+Several specific techniques or features used within the texture viewer have their own separate pages that go into more detail. You might find more useful information there if they cover what you are looking for: :doc:`../how/how_view_texture`, :doc:`../how/how_inspect_pixel`, :doc:`../how/how_custom_visualisation`

 .. figure:: ../imgs/Screenshots/LabelledTexViewer.png

@@ -30,7 +30,7 @@ Information Status Bar

 The status bar below the main texture display contains information on the currently visible texture.

-* The name (if available - if not a default name will be used).
+* The name (if available - if not an auto-generated name will be used).
 * Dimensions - Width, height, depth and array size as applicable.
 * Mip Count.
 * MSAA sample count and quality, if applicable.
@@ -70,7 +70,7 @@ Whenever a pixel is picked small area of the texture around it is rendered at ma

  Pixel context: Pixel context displaying the surrounds of the picked pixel.

-From here, once you have selected a pixel, you can also launch the :doc:`pixel debugger <../how/how_debug_shader>` if you have the drawcall that you want to debug selected. You can also launch the `pixel history <../how/how_inspect_pixel>` view which shows all modifications that have happened to the texture since the start of the frame to the currently selected event.
+From here, once you have selected a pixel, you can also launch the :doc:`pixel debugger <../how/how_debug_shader>` if you have the drawcall that you want to debug selected. You can also launch the :ref:`pixel-history` view which shows all modifications that have happened to the texture since the start of the frame to the currently selected event.

 Visible Range Control
 ---------------------
@@ -158,7 +158,7 @@ Note that these channel selections are by default saved as per-texture state, so

 When **RGBM** is selected, the RGB value will be multiplied by the specified multiplier and then by the alpha value. This is a common encoding used to pack a larger range into an 8-bit RGB image.

-With **Custom** selected a dropdown will be populated with any .hlsl or .glsl files as appropriate in the ``%APPDATA%\renderdoc`` folder. When choosing a custom shader the raw image will be passed through this shader before being displayed with the usual controls on the main display.
+With **Custom** selected a dropdown will be populated with any ``.hlsl`` or ``.glsl`` files as appropriate in the ``%APPDATA%\renderdoc`` folder. When choosing a custom shader the raw image will be passed through this shader before being displayed with the usual controls on the main display.

 You can create a new custom shader with the |add| button, edit a shader with the |page_white_edit| button, and delete an one with the |delete| button.

@@ -167,7 +167,7 @@ Gamma display of Linear Data

  | γ Gamma display

-A proper explanation of this is available in the :doc:`FAQ <../getting_started/faq>`. In short, linear data is 'overcorrected' to look as expected, but this behaviour can be overridden by toggling off this option.
+A proper explanation of this is available in the :ref:`FAQ <gamma-linear-display>`. In short, linear data is 'overcorrected' to look as expected, but this behaviour can be overridden by toggling off this option.

 Alpha background
 ~~~~~~~~~~~~~~~~
@@ -223,6 +223,21 @@ Open Texture List

 This button opens the texture list of all textures present in the capture. More details can be seen in :doc:`../how/how_view_texture`.

+View Texture as Buffer
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. |page_white_code| image:: ../imgs/icons/page_white_code.png
+
+..
+
+  | |page_white_code| Open Texture data in Buffer Viewer
+
+This button opens the texture in the :doc:`raw buffer viewer <buffer_viewer>`. This lets you see the raw data of the underlying texture and format it as you wish if the data represents more complex data than is easy to display in the texture viewer.
+
+.. warning::
+
+  The buffer viewer may not be able to handle the full number of columns that are appropriate for the full width of a texture, so it is better to limit the number of columns and manually calculate the offset into the table of data.
+
 Zoom Controls
 ~~~~~~~~~~~~~~~~~