Update documentation for v1.0

* Screenshots and icons are updated to latest style
* Many out-dated references and mentions of support updated.
* Documentation added for new windows like resource inspector and
  performance counter viewer, as well as new features like saving
  bookmarks, resource names.
* Added documentation for Android support as well as OpenGL ES support.

docs/behind_scenes/analytics.rst

@@ -0,0 +1,25 @@
+Analytics
+=========
+
+RenderDoc has some very minimal analytics gathering. The data is gathered only in the UI and **not during capture**. It is **not personally identifiable** and contains **absolutely no data from captures**.
+
+`The source <https://github.com/baldurk/renderdoc/blob/v1.x/qrenderdoc/Code/Interface/Analytics.h>`_ is freely available and auditable. If desired, a single ``#define RENDERDOC_ANALYTICS_ENABLE`` can be set to ``0`` in that linked file to disable all analytics code.
+
+A report is generated monthly and sent securely to RenderDoc's server. If you want, you can choose to manually approve each report before it's sent.
+
+If you wish to opt-out entirely then no statistics will be gathered or reported. However please consider this carefully as it will make it harder for me to decide which features to prioritise.
+
+To see a complete list of what data is gathered, go to the :doc:`../window/settings_window` in your build and under the :guilabel:`Anonymous Analytics` there will be a link to open a description of the currently gathered data. You can change your mind at any point in the settings window.
+
+For more information go to `the analytics homepage <https://renderdoc.org/analytics>`_.
+
+What data is gathered
+---------------------
+
+The precise data gathered may vary by build, but the principle is to gather as little data as possible while maximising the value of the data that is obtained.
+
+Each report will contain metadata such as operating system version, RenderDoc version, which APIs have been used, which GPU vendor is in use (AMD, Intel, nVidia, etc) and whether a development or release build was run.
+
+It may also include a handful of counters such as the average time taken to load a captured frame, and how many days in the month (as a number from 1-31) the program was used, to give a rough idea of how often people use RenderDoc.
+
+Otherwise the majority of data is simple boolean flags. For each feature in the UI a flag is kept - these flags are left as false by default, and if the feature is ever used then the flag is set to true. There is nothing that stores how often the feature is used, or what it's used for.

docs/behind_scenes/d3d12_support.rst

@@ -3,16 +3,14 @@ D3D12 Support
 
 This page documents the support of D3D12 in RenderDoc. This gives an overview of what RenderDoc is capable of, and primarily lists information that is relevant. You might also be interested in the :doc:`full list of features <../getting_started/features>`.
 
-The latest information and up-to-date support is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/Vulkan>`_.
-
 Performance notes
 -----------------
 
 D3D12 is intended as to have low CPU overhead and be fully threadable, and RenderDoc strives to maintain that performance as much as possible. 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 resources.
+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 resources. If you do have persistent maps, ensure that either the memory allocation is small or that you have only a few queue submits during the frame - since RenderDoc must compare the whole allocation at every submit to determine what might have changed and save out the delta.
 
-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.
+Likewise try to avoid making very large memory allocations in the range of 1GB and above. By its nature RenderDoc must save one or more 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.
 
 Current support
 ---------------

docs/behind_scenes/how_works.rst

@@ -3,33 +3,33 @@ How RenderDoc works
 
 RenderDoc works on very simple operating principles. This page outlines the basic idea behind its functioning to give people a better idea of what's going on.
 
-Capturing Logs
---------------
+Capturing Frames
+----------------
 
-Leaving aside the relatively uninteresting matter of injecting the RenderDoc DLL and calling functions to configure it in the target process, we begin by looking at how RenderDoc captures a logfile.
+Leaving aside the relatively uninteresting matter of injecting the RenderDoc DLL and calling functions to configure it in the target process, we begin by looking at how RenderDoc captures a capture file.
 
-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.
+We will use D3D11 as an example of a driver for RenderDoc - the driver layer is responsible both for faithfully capturing the application'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.
 
-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.
+After this point all accesses to the API remain wrapped and the driver essentially sets itself up as a "man-in-the-middle" between the application and the real API.
 
-The driver initialises in an idle logging state. In this state it's up to the specific implementation about what it serialises. As a general rule, creation and deletion type actions are always serialised, and data-upload calls can sometimes be serialised. In some cases the driver might choose to optimise out some of the data-upload calls and lazy initialise the contents of some resources to save on idle overhead.
+The driver initialises in a background capture state. In this state it's up to the specific implementation about what it serialises. As a general rule, creation and deletion type actions are always serialised, and data-upload calls can sometimes be serialised. In some cases the driver might choose to optimise out some of the data-upload calls and lazy initialise the contents of some resources to save on background overhead.
 
 This serialised data is stored in-memory in a chunk-based representation. Although it's up to the driver implementation it is generally refcounted such that resources which end up becoming unbound and destroyed will have their memory overhead deleted.
 
-When the capture button is hit the driver will enter active logging upon the beginning of the next frame. In this state every API call is serialised out in order and any initial contents and states are saved.
+When the capture button is hit the driver will enter active capturing upon the beginning of the next frame. In this state every API call is serialised out in order and any initial contents and states are saved.
 
-Once the frame completes this frame capture is serialised to disk along with the in-memory data for any resources that are referenced - by default resources which are not referenced are not included in the log.
+Once the frame completes, this frame capture is serialised to disk along with the in-memory data for any resources that are referenced - by default resources which are not referenced are not included in the capture.
 
-Replaying & Analysing Logs
---------------------------
+Replaying & Analysing Captures
+------------------------------
 
 The replay process is ostensibly simple, but as with the capturing the devil is in the details.
 
-When replaying, the initial section of the log (up to the beginning of the frame) is read and executed verbatim. Each resource created is mapped to the live version and vice versa so later parts of the log can obtain the replayed representation of the original resource.
+When replaying, the initial section of the capture (up to the beginning of the frame) is read and executed verbatim. Each resource created is mapped to the live version and vice versa so later parts of the capture can obtain the replayed representation of the original resource.
 
-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 & API Viewer, as well as a linked list with the linear sequence of drawcalls, since both representations are useful for iterating over 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 & API Inspector, 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.
 
@@ -39,10 +39,8 @@ When replaying from the beginning of a frame (and not a partial subset of the fr
 
 For example, let's assume the user has the 'depth test' overlay enabled, and selects a new event. This is the order of events that occur for the Texture Viewer - other viewers follow similar patterns, with a certain degree of sharing to reduce redundant replays:
 
-#. The log is replayed up to, but not including, the selected drawcall. After doing this the current pipeline state and contents of all resources exactly match the state at the point of this drawcall.
+#. The capture is replayed up to, but not including, the selected drawcall. After doing this the current pipeline state and contents of all resources exactly match the state at the point of this drawcall.
 #. We then save a copy of the pristine depth buffer, save the current pipeline state, and set the reversed depth test. Replacing the pixel shader with one that just writes red, we repeat the drawcall to draw all the areas that fail the depth test.
 #. Restoring the depth buffer and repeating this with a pixel shader which writes green, we fill in the overlay. Both of these renders happen to an off-screen buffer.
 #. After restoring the pipeline state we finally replay the original drawcall to get the final image.
 #. When we want to re-paint the viewed texture (either regular painting, or if the user changed a visualisation option which is just a constant buffer value) we bind the current render target as a resource and render it to the texture viewer control, then render the overlay texture on top of that.
-
-It's also worth mentioning that there is a bit of special handling for deferred contexts. When you select an event in a command list, RenderDoc will replay as normal up to just before the Execute() call, then it will replay all of the commands in the command list up to the currently selected event on the immediate context.

docs/behind_scenes/index.rst

@@ -3,6 +3,7 @@ Behind the scenes
 
 .. toctree::
 
+    analytics
     planned_features
     how_works
     opengl_support

docs/behind_scenes/opengl_support.rst

@@ -1,16 +1,25 @@
-OpenGL Support
-==============
+OpenGL & OpenGL ES Support
+==========================
 
-This page documents the support of OpenGL in RenderDoc. This gives an overview of what RenderDoc is capable of, and primarily lists information that is relevant. You might also be interested in the :doc:`full list of features <../getting_started/features>`.
+This page documents the support of OpenGL & OpenGL ES in RenderDoc. This gives an overview of what RenderDoc is capable of, and primarily lists information that is relevant. You might also be interested in the :doc:`full list of features <../getting_started/features>`.
 
 The latest information and up-to-date support is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/OpenGL>`_.
 
-OpenGL requirements, and limitations
-------------------------------------
+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. Note that to be more compatible with applications, RenderDoc will still attempt to capture on an older context, or on a compatibility context, but it will not replay successfully unless the given subset of functionality is used.
+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 assumes a certain minimum feature set on replay. You must be able to create a 3.2 context with the following extensions available:
+.. note::
+
+   that to be more compatible with applications, RenderDoc will still attempt to capture on a compatibility context, but it will not replay successfully unless the given subset of functionality is used.
+
+On OpenGL ES, any context version 2.0 and above is supported.
+
+Replay requirements
+-------------------
+
+RenderDoc assumes a certain minimum feature set on replay. On desktop this means you must be able to create a 3.2 context with the following extensions available:
 
 * GL_ARB_vertex_attrib_binding
 * GL_ARB_program_interface_query
@@ -19,26 +28,38 @@ RenderDoc assumes a certain minimum feature set on replay. You must be able to c
 * GL_ARB_explicit_attrib_location
 * GL_ARB_sampler_objects
 
-These extensions should not require newer hardware than the base 3.2 context, but they might need an updated driver to be listed as available. Also note that this is the *minimum* required extension set to replay, various features will be disabled unless you have more capable hardware features such as GL_ARB_shader_image_load_store, GL_ARB_compute_shader and GL_ARB_gpu_shader5.
+These extensions should not require newer hardware than the base 3.2 context, but they might need an updated driver to be listed as available. Also note that this is the *minimum* required extension set to replay, some analysis features will be disabled unless you have more capable hardware features such as GL_ARB_shader_image_load_store, GL_ARB_compute_shader and GL_ARB_gpu_shader5.
 
-Regarding multiple contexts and multithreading, RenderDoc assumes that all GL commands (with the exception of perhaps a SwapBuffers call) for frames will come from a single thread, and that all contexts are set up to share objects with each other. This means that e.g. if commands come from a second thread during loading, or some time during initialisation, this will be supported only if the second context shares with the primary context. During frame capture all commands are serialised as if they come from a single thread.
+On OpenGL ES, you must be able to create a GLES 3 context to replay.
 
-RenderDoc supports some ARB, EXT and other extensions - primarily those that are either very widespread and commonly used but aren't in core, or are quite simple to support. In general RenderDoc won't support extensions unless they match one of these requirements, and this means most vendor extensions will not be supported.
+Multiple contexts & multithreading
+----------------------------------
+
+RenderDoc assumes that all GL commands (with the exception of perhaps a SwapBuffers call) for frames will come from a single thread, and that all contexts are set up to share objects with each other. This means that e.g. if commands come from a second thread during loading, or some time during initialisation, this will be supported only if the second context shares with the primary context. During frame capture all commands are serialised as if they come from a single thread.
+
+Extension support
+-----------------
+
+RenderDoc supports many ARB, EXT and other vendor-agnostic extensions - primarily those that are either very widespread and commonly used but aren't in core, or are quite simple to support. In general RenderDoc won't support extensions unless they match one of these requirements, and this means most vendor extensions will not be supported.
 
 OpenGL remaining work
 ---------------------
 
-There are several places where OpenGL is not yet at feature parity with D3D11.
+There are a couple of places where OpenGL is not yet at feature parity with other APIs.
 
 * Full & complete support for multiple threads feeding GL simultaneously, or multiple contexts that don't share with each other (or only share within defined groups).
 * Shader debugging is not supported on any shader stage.
 * Pixel history is not implemented.
 
+Android
+-------
 
-Linux and OS X
---------------
+OpenGL ES capture and replay on Android is natively supported. For more information on how to capture with Android see :doc:`../how/how_android_capture`.
 
-Linux and OS X support follows naturally when thinking about OpenGL support. There is full support for capturing and replaying on linux, with the UI based on Qt. It is also possible to capture on linux, and then replay on windows. For more information on this see :doc:`../how/how_network_capture_replay`.
+OS X
+----
+
+OS X is not yet supported for OpenGL capture, in part due to some of the required replay extensions above being missing, and also due to missing platform-specific hooking code.
 
 See Also
 --------

docs/behind_scenes/planned_features.rst

@@ -1,7 +1,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!
+This is a list of 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/Roadmap>`_.
 
@@ -12,10 +12,8 @@ Planned features
 
 * Debugging of all shader stages.
 * HLSL Debugging.
-* Mesh display after HS stage.
+* Mesh display after hull shader stage.
 * Perfkit/PerfHUD integration for vendor-specific detailed performance timers.
-* Multiple frames in a single capture/logfile.
-* Replacing .NET UI with the Qt UI.
 * Diffing events in a given frame.
 * Modifying the pipeline on the fly to change state.
 * Highlighting redundant state-setting.

docs/behind_scenes/vulkan_support.rst

@@ -3,8 +3,6 @@ Vulkan Support
 
 This page documents the support of Vulkan in RenderDoc. This gives an overview of what RenderDoc is capable of, and primarily lists information that is relevant. You might also be interested in the :doc:`full list of features <../getting_started/features>`.
 
-The latest information and up-to-date support is always available on the `GitHub wiki <https://github.com/baldurk/renderdoc/wiki/Vulkan>`_.
-
 Vulkan capture
 --------------
 
@@ -42,10 +40,10 @@ RenderDoc has initial support for Vulkan at the launch of version 1.0, but it co
 * Shader debugging is not currently supported.
 * Mesh output of geometry/tessellation shader stages is not available.
 
-Non-windows platforms
----------------------
+Android
+-------
 
-Linux and other pltaform support follows naturally when thinking about Vulkan support. There is full support for capturing and replaying on linux, with the UI based on Qt. It is also possible to capture on another platform, and then replay on windows or windows. For more information on this see :doc:`../how/how_network_capture_replay`.
+Vulkan capture and replay on Android is natively supported. For more information on how to capture with Android see :doc:`../how/how_android_capture`.
 
 See Also
 --------

docs/conf.py

@@ -108,7 +108,7 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'sphinx_exts']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'sphinx_exts', 'include']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/credits_acknowledgements.rst

@@ -8,29 +8,13 @@ RenderDoc wouldn't have been possible without both the tools and libraries that
 
 The following libraries and components are incorporated into RenderDoc, listed here in no particular order. Thanks go out to the developers and contributors behind each of these libraries who generously donated their work to other free projects!
 
-* `TreeView with Columns <http://www.codeproject.com/Articles/23746/TreeView-with-Columns>`_ - Copyright 2008 by jkristia, distributed under the `CPOL license <http://www.codeproject.com/info/cpol10.aspx>`_.
-
-  An invaluable control filling a much needed niche in .NET winforms.
-
-* `DockPanel <http://dockpanelsuite.com/>`_ - Copyright 2007 Weifen Luo, distributed under the MIT license.
-
-  A mature and stable library that adds the docking and flexibility of RenderDoc's UI.
-
-* `famfamfam Silk Icon set <http://www.famfamfam.com/lab/icons/silk/>`_ - Authored by Mark James, distributed under Creative Commons Attribution 2.5.
-
-  Lending an air of professionalism and artistic quality to the UI, the Silk icon set is used throughout RenderDoc.
-
-* `Scintilla.NET <http://scintillanet.codeplex.com/>`_ - ScintillaNET Copyright 2002-2006 Garrett Serack, `Scintilla <http://www.scintilla.org/>`_ Copyright 1998-2006 Neil Hodgson, distributed under the MIT license.
-
-  Scintilla and the wrapper Scintilla.NET provide a powerful text editor for the shader viewers.
-
 * `Google Breakpad <https://chromium.googlesource.com/breakpad/breakpad/>`_ - Copyright 2006 Google Inc, distributed under the New BSD License (3 Clause).
 
-  provides a rock-solid crash handling and reporting base that help keep RenderDoc stable.
+  Crash handling and report preparation system.
 
 * `miniz <https://code.google.com/p/miniz/>`_ - Released to the Public Domain by Rich Geldreich.
 
-  Public domain zip library is used to compress the crash reports for sending.
+  Used for zip read/write in several places.
 
 * `ILM's half implementation <https://github.com/openexr/openexr/tree/master/IlmBase/Half>`_ - Copyright 2002 Industrial Light & Magic, a division of Lucas Digital Ltd. LLC, distributed under BSD license.
 
@@ -38,11 +22,11 @@ The following libraries and components are incorporated into RenderDoc, listed h
 
 * `jpeg-compressor <https://code.google.com/p/jpeg-compressor/>`_ - Released to the Public Domain by Rich Geldreich.
 
-  Used to compress screenshots into jpg format for thumbnail previews.
+  Used for jpg reading and writing.
 
 * `lz4 <https://github.com/lz4/lz4>`_ - Copyright 2013 Yann Collet, distributed under the BSD 2-Clause license.
 
-  Compresses large data transfers (textures and buffers) when going across network connections as well as in the capture files themselves.
+  Used for fast compression where speed is more important than compression ratio.
 
 * `stb <https://github.com/nothings/stb>`_ - Released to the Public Domain by Sean Barrett.
 
@@ -52,10 +36,6 @@ The following libraries and components are incorporated into RenderDoc, listed h
 
   Font used for the in-program overlay.
 
-* `IronPython <http://ironpython.net/>`_ - Copyright IronPython Team, distributed under the Apache 2.0 license.
-
-  Used for the Python shell/integration in the UI.
-
 * `tinyexr <https://github.com/syoyo/tinyexr>`_ - Copyright 2014 Syoyo Fujita, distributed under the New BSD License (3 Clause).
 
   Used for the OpenEXR file loading and saving.
@@ -127,7 +107,9 @@ The following libraries and components are incorporated into RenderDoc, listed h
 Thanks
 ------
 
-There have been many people who have helped in the creation of RenderDoc. Whether testing, feedback or contributing artwork and design critique everyone listed here and many more besides have been invaluable in taking RenderDoc from an idea on paper to its current state. Greets fly out to the following people, listed in no particular order.
+Screenshots in this documentation are from `Sascha Willems' Vulkan demos <https://github.com/SaschaWillems/Vulkan>`_.
+
+There have been many people who have helped in the creation of RenderDoc. Whether testing, providing feedback, or contributing artwork and design critique everyone listed here and many more besides have been invaluable in taking RenderDoc from an idea on paper to its current state. Greets fly out to the following people, listed in no particular order.
 
 * Chris Bunner, Charlie Cole, James Chilvers, Andrew Khan, Benjamin Hill, Jake Turner, Alex Weighell and the rest of the Crytek UK R&D team.
 * Colin Bonstead, Marco Corbetta, Pascal Eggert, Marcel Hatam, Sascha Hoba, Theodor Mader, Mathieu Pinard, Chris Raine, Nicolas Schulz, Tiago Sousa, Sean Tracy, Carsten Wenzel, and everyone else at the rest of the Crytek Studios.
@@ -164,6 +146,14 @@ There have been many people who have helped in the creation of RenderDoc. Whethe
 * Ian Elliot
 * Callan McInally
 * Gordon Selley
+* Cody Northrop
+* Dominik Baumeister
+* Adrian Bucur
+* Peter Gal
+* Janos Pantos
+* Marton Tamas
+* Nat Duca
+* Ben Clayton
 
 Contributors
 ------------
@@ -172,7 +162,7 @@ The following list highlights notable open source contributions. Many other peop
 
 * Michael Vance - Implemented a sophisticated frame statistics system for D3D11 around binding and draw API calls.
 * Matthäus G. Chajdas - Converted this documentation from sandcastle to sphinx.
-* Michael Rennie - Added support for Android platform capture.
+* Michael Rennie, Peter Gal, and Janos Pantos at Samsung - Added support for Android platform capture as well as Vulkan and OpenGL ES support.
 * Adrian Bucur - Added custom SPIR-V disassembler support.
 * James Fulop - Updated the vertex picking algorithm.
 * Balazs Torok - Implemented the RenderDoc in-application overlay for D3D9.

docs/getting_started/faq.rst

@@ -1,14 +1,25 @@
 FAQ
 ===
 
-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.
+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.
+
+What are the details of RenderDoc's Anonymous Analytics?
+--------------------------------------------------------
+
+RenderDoc has some very light anonymous analytics to allow analysis of which features and platforms are used more, to prioritise and guide future development.
+
+The complete details of the analytics can be found in the page about :doc:`../behind_scenes/analytics`, but the brief outline is that RenderDoc records data **only in the replay program** and does not record any data that is specific to any captured programs. The data recorded is primarily boolean flags indicating whether or not a given feature, API, or platform is used or not. You can see the precise list of data gathered on your current RenderDoc build in the settings menu under the :guilabel:`Anonymous Analytics` section.
+
+The analytics data is summarised and transmitted securely and anonymously to RenderDoc's server. The aggeregated statistics are available for anyone to see at `the analytics homepage <https://renderdoc.org/analytics>`_.
+
+Enabling the analytics is greatly appreciated, if you have any concerns about the data gathered you can choose to manually verify each report before it's submitted.
 
 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.
+Many specific tasks or functions are detailed in the :doc:`"How Do I... ?" <../how/index>` 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 :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.
+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 depending on user needs.
 
 Why did you make RenderDoc?
 ---------------------------
@@ -29,47 +40,49 @@ 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 <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.
+I work on RenderDoc full time contracting for Valve Software, and I am happy to help with anything and work with you if you have any issues that need attention.
+
+In particular I'm used to working with people who have strong NDA protection over their projects - as long as you are able to spend time to diagnose the issue by running builds and debugging by suggestion, it's not a requirement to send me a repro case - which may be impossible.
 
 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 :doc:`../window/options_window`.
+On Windows if you installed RenderDoc via the msi installer, the option is available there to associate RenderDoc's file extensions with the program.
 
-.. note::
+On linux the binary tarball comes with files to place under ``/usr/share`` to associate RenderDoc with files. This obviously also requires ``qrenderdoc`` to be available in your ``PATH``.
 
-  RenderDoc will elevate itself to set up these file associations, but otherwise will not hold on to administrator permissions.
+RenderDoc can be associated with ``.rdc`` and ``.cap`` files. The ``.rdc`` files are the frame capture containers generated from your application. ``.cap`` files describe the set up of a particular capture, and can be used to quickly re-launch a capture preset.
 
-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.
-
-If .rdc files are associated with RenderDoc a thumbnail handler is set up, so that in explorer you'll get thumbnail previews for your captures.
-
-.. note::
-
-    Note that if you move the directory that RenderDoc is you will need to re-configure the file associations as the registry entries contain absolute paths.
+There is also a thumbnail handler available for ``.rdc`` so that while browsing through files you will get a thumbnail preview of the capture where available.
 
 What APIs does RenderDoc support?
 ---------------------------------
 
-Currently RenderDoc supports Vulkan, D3D11 (including D3D11.x), D3D12, 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>`. Vulkan support has :doc:`a few notes <../behind_scenes/vulkan_support>`, as does :doc:`D3D12 <../behind_scenes/d3d12_support>`.
+Currently RenderDoc supports Vulkan 1.0, D3D11 (up to D3D11.3), D3D12, OpenGL 3.2+, and OpenGL ES 2.0 - 3.2. Note that OpenGL (and similarly OpenGL ES) is a complex & sprawling API, so see the details of what is supported in :doc:`its own page <../behind_scenes/opengl_support>`. In particular on desktop only modern GL is supported - legacy GL that is only available via the compatibility profile in OpenGL 3.2 is not supported.
 
-Future API support is at this point not clear, GLES, Metal and perhaps D3D9 all being possible. Higher priority is better operating system/platform support which is currently underway, as well as feature improvements for existing platforms and APIs.
+Vulkan support has :doc:`a few notes <../behind_scenes/vulkan_support>`, as does :doc:`D3D12 <../behind_scenes/d3d12_support>`.
+
+Future API support is at this point not clear; Metal, WebGL, and perhaps D3D9/D3D10 all being possible. Support for new APIs will be balanced against all other work such as features for existing APIs, bugfixes. So if you care strongly about support for a new API make sure to `file an issue on github <https://github.com/baldurk/renderdoc/issues>`_ or comment on an existing issue to register your interest.
 
 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.
+RenderDoc stores data in two folders:
 
-Deleting this folder will also reset RenderDoc to the defaults - if you uninstall RenderDoc this folder will not be deleted.
+The UI stores data in a ``qrenderdoc`` folder underneath your OS's user settings folder. On windows this is ``%APPDATA%`` and on linux this will be somewhere in your home directory, perhaps in ``~/.local/share``. Nothing in this data is machine specific aside from paths, so you can back up and restore this directory at will.
 
-RenderDoc doesn't install any registry keys aside from those to set up file associations.
+Deleting this folder will also reset QRenderDoc to the defaults - if you uninstall RenderDoc this folder will not be deleted.
+
+The core code may save cached data in a ``renderdoc`` folder - either ``%APPDATA%/renderdoc`` or ``~/.renderdoc/`` but this doesn't contain settings, so is not important to back up.
+
+RenderDoc doesn't install any registry keys on windows aside from those required to set up file associations.
 
 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 capture.
 
 Where can I get the source to RenderDoc?
 ----------------------------------------
@@ -83,32 +96,32 @@ Currently RenderDoc expects Feature Level 11.0 hardware and above for D3D11. Low
 
 For OpenGL RenderDoc will only capture core profile applications, in general, and expects at minimum to be able to create a core 3.2 context which includes a few key extensions. For more details see :doc:`../behind_scenes/opengl_support`.
 
-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.
+With Vulkan, RenderDoc should fully support any Vulkan application. However replaying a Vulkan capture 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 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).
+On D3D11, 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 :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.
+To change this behaviour, enable the ``Capture all cmd lists`` option - see :doc:`../window/capture_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.
 
-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 the color space it's stored in.
 
 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 application 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).
 
@@ -121,13 +134,13 @@ For various tedious reasons RenderDoc's replay isn't (and in most cases can't be
 
 During capture the main impact of having RenderDoc enabled is that timings will change, and more memory (sometimes much more) will be allocated. There are also slight differences to the interception of Map() calls as they go through an intermediate buffer to be captured. Generally the only problem this can expose is that when capturing a frame, if something is timing dependent RenderDoc causes one or two very slow frames, and can cause the bug to disappear.
 
-The two primary causes of differences between the captured program and the replayed log (for better or for worse) are:
+The two primary causes of differences between the captured program and the replayed capture (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``.
 
-#. 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.
+#. 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.
 
-  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_frame>`.
 
 I can't launch my program for capture directly. Can I capture it anyway?
 ------------------------------------------------------------------------
@@ -143,7 +156,7 @@ I'd like to use RenderDoc's texture viewer for dds files, or other images. Can I
 
 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.
+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 capture 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.
 
@@ -152,20 +165,20 @@ Any modifications to the image while open in RenderDoc will be refreshed in the
 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.
+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_attach>`.
 
 Note this is only supported on D3D11 and OpenGL currently, since Vulkan and D3D12 are lower overhead and do not have the infrastructure to intercept map writes.
 
 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.
+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 is required in core profile) and using 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 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 which is still available in the context.
 
 Can I tell via the graphics APIs if RenderDoc is present at runtime?
 --------------------------------------------------------------------
@@ -189,8 +202,6 @@ Querying an ``ID3D11Device`` for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}``
         #define GL_DEBUG_TOOL_NAME_EXT            0x678A
         #define GL_DEBUG_TOOL_PURPOSE_EXT         0x678B
 
-A similar extension for Vulkan will be proposed after release.
-
 .. _unstripped-shader-info:
 
 My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?
@@ -202,17 +213,17 @@ This optional information is generated by the compiler, but is not required for
 
 The simplest solution is just to avoid stripping the data when using RenderDoc, but that isn't always possible. Instead RenderDoc allows you to use API-specific methods to specify where the unstripped data can be found. This means you can save the unstripped shader to a debug location and then either store this location with the shader, or specify it at runtime. On replay RenderDoc will expect the data to be available at that location and it will load it up instead.
 
-The path you specify (with the stripped shader, or at runtime) can be either absolute or relative. If it's relative, you must configure a shader search path in the :doc:`../window/options_window`.
+The path you specify (with the stripped shader, or at runtime) can be either absolute or relative. If it's relative, you must configure a shader search path in the :doc:`../window/settings_window`.
 
 The stripped shader file stored on disk can also be compressed with LZ4 to save space as often most of the size is made up for shader source text which compresses well. To do this, simply compress the contents of the file and prepend the pathname (either absolute or relative, specified in the shader blob or at runtime) with ``lz4#``.
 
 For example code using this method, check out :doc:`tips_tricks`.
 
-I want to debug a process that my program launches itself, how can I inject RenderDoc?
---------------------------------------------------------------------------------------
+I want to debug a child process that my program launches, how can I inject RenderDoc?
+-------------------------------------------------------------------------------------
 
 When launching a process in RenderDoc, by default only this process is debugged and any children it launches are not affected. This better ensures compatibility for the most common case where you are able to start the process to be debugged directly.
 
-In the case where your program launches sub-processes that you would like to debug, you can enable the ``Hook into Children`` 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.
+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 <child-process-hook>` in the documentation for the :doc:`../window/capture_log_attach` window.
+There are :ref:`more details available <child-process-hook>` in the documentation for the :doc:`../window/capture_attach` window.

docs/getting_started/features.rst

@@ -3,9 +3,9 @@ Features
 
 This page documents the current feature set of RenderDoc. This gives an overview of what RenderDoc is capable of, and where it is in its development. You might also be interested in the :doc:`../behind_scenes/planned_features`.
 
-Currently RenderDoc supports Vulkan, D3D11, D3D12, and OpenGL on Windows and Linux. The primary UI only runs on Windows currently, a Qt UI is in progress to replace it as a cross-platform UI.
+Currently RenderDoc supports Vulkan, D3D11, D3D12, OpenGL, and OpenGL ES on Windows, Linux, and Android. The UI runs in Qt and will work on any desktop platform.
 
-RenderDoc can also double as an image viewer in a simplistic fashion, separate to its functionality as a debugger. Drag in or open any of a variety of image file formats and RenderDoc will display them as a texture in a log. This way it can be used as a simple e.g. dds viewer, with support for all sorts of formats, encodings and things typical image viewers don't tend to handle like mips, cubemaps and arrays.
+RenderDoc can also double as an image viewer in a simplistic fashion, separate to its functionality as a debugger. Drag in or open any of a variety of image file formats and RenderDoc will display them as if they were the only texture in a capture. This way it can be used as a simple e.g. dds viewer, with support for all sorts of formats, encodings and things typical image viewers don't tend to handle like mips, cubemaps and arrays.
 
 Current Common Feature set
 --------------------------
@@ -26,7 +26,15 @@ Current Common Feature set
     * Displays scene left-to-right in time, event hierarchy top-to-bottom.
     * *Not* scaled based on time of each drawcall
     * Individual draw events are shown as dots when the tree is full expanded.
-    * The currently selected resource in the texture viewer is highlighted below individual drawcalls visible that use it - e.g. purple for 'used for write', green for 'used for read'
+    * The currently selected resource in the texture viewer is highlighted below individual drawcalls visible that use it - e.g. red for 'used for read', green for 'used for write'
+
+* Flexible resource inspector.
+
+    * Anywhere in the UI that a resource is mentioned by name or handle, it is linked back to the resource inspector.
+    * Contains full list of all resources and API objects.
+    * Each resource is linked to any parent or child object, visualising construction dependencies.
+    * The API calls used to create the object before its use in the frame are displayed.
+    * Any object can be renamed, and its name automatically updates everywhere in the UI.
 
 * For each drawcall, a list of all API calls (state/resource setting) is available, with each call optionally having a complete callstack to locate where it came from in-app.
 * Mesh buffer inspection and visualisation before/after vertex shader and at the end of the geometry pipeline (after GS or DS, whichever is later). All views have arcball and flycam controls, Projected data is not limited to the 2D viewport, RenderDoc attempts to unproject to allow viewing in world-space.
@@ -48,15 +56,21 @@ Current Common Feature set
 * Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.
 * Hot shader editing and replacement.
 * Auto-range fitting to min/max values in texture data, and histogram display.
-* Simple per-drawcall timings.
-* Python scripting console, giving access to some of the RenderDoc internals and core data structures.
+* Simple per-drawcall timings and tabular view of GPU counter data.
+* Python scripting console with full documented API, giving complete access to RenderDoc internals, core data structures, and the Qt UI itself.
+* Import and Export of captures
+
+    * Captures have an internal in-memory representation containing the full serialised data of all function calls, as well as associated metadat.
+    * This capture representation can be used to export an ``.rdc`` file to another form that's easier for external tools to work with such as ``.xml``.
+    * If the external format contains full expression of data, it can then be imported again back into an ``.rdc`` after modification.
+    * This also allows generation of RenderDoc captures from arbitrary data into a standard format.
 
 Most of these should be intuitive if you've used a graphics debugger before.
 
 D3D11
 -----
 
-* Support for D3D11 and D3D11.x, Windows Vista and above. Where hardware support isn't available for feature level 11, WARP will be used.
+* 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.
 * Debug marker support comes from any available D3D interface (ID3DUserDefinedAnnotation, D3DPERF\_ functions, etc)
 * Pixel history view.
 * Vertex, Pixel and Compute shader debugging.
@@ -68,21 +82,20 @@ D3D12
 * Support for D3D12, Windows 10 only.
 * Debug marker uses the PIXSetMarker macros that go through SetMarker/BeginEvent/EndEvent on the command list
 
-OpenGL
-------
-
-* Support for OpenGL Core profile 3.2+ on Windows and Linux.
-* Tree heirarchy of events defined by any of the standard or vendor-specific extensions, and ``KHR_debug`` object labels used for object naming.
-
-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. For most work though, you have to transfer the .rdc capture file (by default placed in /tmp) to windows and open it in the UI there - logs are completely interchangeable between windows and linux.
-
 Vulkan
 ------
 
-* Support for Vulkan 1.0 on Windows and Linux.
+* Support for Vulkan 1.0 on Windows, Linux, and Android.
 * Event markers and object naming both come from ``VK_EXT_debug_marker``.
 
-Logs have a very limited amount of portability between machines. Many hardware-specific feature uses are baked into logs, and portability depends on how similar the captuer and replay hardware are, whether these feature uses can map the same in both cases. Logs are however completely portable between different OSes with sufficiently comparable hardware.
+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.
+* 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 captuer 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.
 
 See Also
 --------

docs/getting_started/gotchas_known_issues.rst

@@ -6,26 +6,22 @@ This page (hopefully) keeps up to date with any known issues, bugs, unimplemente
 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_log>` before capturing, as this will force RenderDoc to serialise out all initial contents regardless, at the cost of larger logfiles and slightly slower replay app analysis.
+  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 logfiles and slightly slower replay app analysis.
 
 * 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.
 
 * RenderDoc relies on saving out the graphics command stream and replaying it back at inspection time. This means if a bug is timing, machine or driver specific it is in no way guaranteed to reproduce the bug on a different machine or driver.
 
-  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.
+  RenderDoc has few runtime dependencies, and should run anywhere that a normal application will run. In particular it has no dependencies on any SDKs being installed and will run 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`.
 * 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.
-
-Partially Implemented Features
-------------------------------
-
-
-* Deferred context & command list support will probably run into problems with non-trivial use-cases. Let me know if you find a use-case that breaks, as I don't have many test programs!
-* The API Inspector shows essentially the raw serialised form of the commands in the log file and so is not always very useful beyond showing which functions were called. There isn't a way yet to see what views a particular ID corresponds to, and some of the parameters are a little different from their official function signature.
-* There are several such notes for OpenGL, which are noted on :any:`its own page <../behind_scenes/opengl_support>`, as well as for Vulkan on :doc:`its own page <../behind_scenes/vulkan_support>`.

docs/getting_started/index.rst

@@ -4,8 +4,8 @@ Getting started
 .. toctree::
     :maxdepth: 1
 
+    quick_start
     faq
     gotchas_known_issues
-    quick_start
     features
     tips_tricks

docs/getting_started/quick_start.rst

@@ -3,25 +3,25 @@ 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.
+For this tutorial we will be using the `debugmarker <https://github.com/SaschaWillems/Vulkan#vk_ext_debug_marker>`_. sample from `Sascha Willems' Vulkan samples repository <https://github.com/SaschaWillems/Vulkan>`_..
 
-Capturing a log
----------------
+Capturing a frame
+-----------------
 
-To capture a log, begin by opening the File menu and selecting Capture Log. By default this will open a new docked window where you can configure different settings that will be used when capturing.
+To capture a frame, begin by selecting :guilabel:`File` → :guilabel:`Launch Application`. By default this will open a new docked window where you can configure different settings that will be used when capturing. You may find this window is already available.
 
 .. figure:: ../imgs/QuickStart/QuickStart1.png
 
-    Capturing a Log
+    Launching an executable
 
-The defaults work pretty well in most situations, so you can just either browse to or drag in your exe into the Executable box. If the working directory box is empty then the Executable's directory will be used. Enter any command line you may need and click 'Capture' to launch the application with RenderDoc.
+The defaults work pretty well in most situations, so you can just either browse to or drag in your exe into the Executable box. If the working directory box is empty then the Executable's directory will be used. Enter any command line you may need and click Launch to launch the application with RenderDoc.
 
-More details of the specific options and their functionality can be found in the details page for the :doc:`../window/capture_log_attach`.
+More details of the specific options and their functionality can be found in the details page for the :doc:`../window/capture_attach`.
 
 
 .. note::
 
-    You should choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa
+    You should choose the build 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 either build of RenderDoc.
 
@@ -31,13 +31,13 @@ RenderDoc in-app
 RenderDoc has a fairly minimal in-app overlay, just to indicate that RenderDoc has successfully loaded and is ready to capture a frame.
 
 
-When ready, press the Capture Key (:kbd:`F12` or	:kbd:`Print Screen`) and the next frame after the keypress will be captured, and this will show up on the overlay to let you know that a frame has been successfully saved.
+When ready, press the Capture Key (:kbd:`F12` or :kbd:`Print Screen`) and the next frame after the keypress will be captured, and this will show up on the overlay to let you know that a frame has been successfully saved.
 
 .. figure:: ../imgs/QuickStart/QuickStart2.png
 
     The in-application RenderDoc Overlay
 
-When the application exits, if you captured a log it will automatically start to open in the RenderDoc UI. If you didn't capture a log then nothing will happen and the RenderDoc UI will be back as it was when you clicked Capture.
+When the application exits, if you captured a frame it will automatically start to open in the RenderDoc UI. If you didn't capture a frame then nothing will happen and the RenderDoc UI will be back as it was when you clicked Lanuch.
 
 
 If you made multiple captures you will see a thumbnail list that allows you to open (in the current instance or a new instance to compare side-by-side), save and delete them as you wish. You can also access this view while the program is still running, see :doc:`../window/capture_connection` for more information on taking multiple frame captures. Note however that for the simple use-case, you don't need to worry about this!
@@ -50,13 +50,13 @@ RenderDoc's layout can be customised fairly heavily so this section will only co
 
 Each of these windows has a section that is much more in depth and gives details about every function and feature, for the more complex windows such as the texture viewer you may well wish to skim these to get an idea of what is available and use them as reference in the future.
 
+Texture Viewer
+``````````````
+
 .. figure:: ../imgs/QuickStart/QuickStart3.png
 
     The Texture Viewer
 
-Texture Viewer
---------------
-
 More details can be found on the :doc:`../window/texture_viewer` page.
 
 The texture viewer does pretty much what you'd expect - it allows you to inspect textures and render targets in your application.
@@ -108,6 +108,8 @@ The |asterisk_orange| bookmark button will allow you to bookmark an event, the s
 
 A list of bookmarked events will show up on a toolbar at the top of the event browser, they and the shortcut keys :kbd:`CTRL-1`  to :kbd:`CTRL-0` will jump to the respective bookmarked EID. These shortcuts will work anywhere in the application.
 
+Bookmarks can be saved with the capture and shared with others. For more on this see the :doc:`../how/how_annotate_capture` page.
+
 API Inspector
 `````````````
 
@@ -117,12 +119,12 @@ API Inspector
 
 More details can be found on the :doc:`../window/api_inspector` page.
 
-The API Calls window updates as a new event is selected. It shows the individual API calls and their parameters (in some fashion) between the previous and current event. The bottom entry in this list always corresponds to the event that is currently selected, and each row can be expanded to show the parameters that were passed to that API call.
+The API Calls window updates as a new event is selected. It shows the individual API calls and their parameters between the previous and current event. The bottom entry in this list always corresponds to the event that is currently selected, and each row can be expanded to show the parameters that were passed to that API call.
 
 At the bottom of the window is an optional expandable section which shows the callstack (if available and recorded) from the application code into the API function.
 
 
-In order to view these callstacks you must first resolve the symbols recorded with the log. To do this click on :kbd:`Resolve Symbols` under the :kbd:`Tools` menu. More details on this process can be found in the guide: :doc:`../how/how_capture_callstack`.
+In order to view these callstacks you must first resolve the symbols recorded with the capture. To do this click on :guilabel:`Resolve Symbols` under the :guilabel:`Tools` menu. More details on this process can be found in the guide: :doc:`../how/how_capture_callstack`.
 
 Timeline Bar
 ````````````
@@ -133,9 +135,11 @@ Timeline Bar
 
 More details can be found on the :doc:`../window/timeline_bar` page.
 
-The timeline bar is essentially an alternate view of the frame, with the horizontal axis being time in the frame. The scale however is non-linear and is weighted to try and show each section of the frame equally and visibly, rather than scaling by duration.
+The timeline bar is essentially an alternate view of the frame, with the horizontal axis being time in the frame. The horizontal axis is scaled evenly by API calls, such that every API call has the same width at any given zoom level.
 
-The frame marker hierarchy is top-down in this case, and can be expanded or collapsed by clicking on each section. In this image, Cascades and Cascade 1 are both expanded, but the other sections remain collapsed. Each drawcall is rendered as a blue circle underneath the section of the hierarchy that it is a child of. The current drawcall (if visible) is rendered as a green circle and there are two vertical bars - red for the current mouse highlight, and light grey for the current drawcall, so it is visible regardless of the hierarchy expansion.
+The frame marker hierarchy is top-down in this case, and can be expanded or collapsed by clicking on each section. In this image, "Render Scene" and "Toon shading draw" are both expanded, but the other sections remain collapsed. Each drawcall is rendered as a blue pip underneath the section of the hierarchy that it is a child of. The current drawcall (if visible) is rendered as a green circle.
+
+There is a vertical line around the current drawcall, as well as a |flag_green| above, and a grey outline around the event where the mouse is hovering.
 
 When the currently selected texture is used in the frame, each drawcall that references it draws a marker below the bar. A purple marker indicates that the drawcall at that point is writing to the texture, and a green marker indicates that it is reading. If the markers are too close together they will space themselves to be readable and will not necessarily line up to a particular drawcall unless you zoom in.
 
@@ -153,11 +157,15 @@ More details can be found on the :doc:`../window/pipeline_state` page.
 
 The Pipeline State window is perhaps the most detailed but also the simplest to understand. This window simply lists every stateful aspect of the graphics pipeline and what value or object is present at the current event.
 
-.. |go_arrow| image:: ../imgs/icons/GoArrow.png
+.. |go_arrow| image:: ../imgs/icons/action_hover.png
 
-By default the pipeline will not contain empty or unused entries - i.e. if a shader only reads from resources 0 and 1, even if something is bound to slot 2 it will not be displayed. Likewise say slots 3-128 are empty - they will also not be displayed. This behaviour can be modified by the :guilabel:`Show Disabled Items` and :guilabel:`Show Empty Items` toggles on the toolbar. Show Disabled will show slot 2 even if the shader does not read from it. Show Empty will show slots 3-128.
+By default the pipeline will not contain empty or unused entries - i.e. if a shader only reads from resources 0 and 1, even if something is bound to slot 2 it will not be displayed. Likewise say slots 3-128 are empty - they will also not be displayed. This behaviour can be modified by the :guilabel:`Show Disabled Items` and :guilabel:`Show Empty Items` toggles on the toolbar. Show Disabled will show slot 2 even if the shader does not read from it. Show Empty will show slots 3-128. This behaviour varies significantly by API since the shader binding model is often quite different.
 
-The most important thing to note is that most things in the sections for each pipeline stage can be expanded to view in more detail. Look for the Go Icon (|go_arrow|) to indicate that a more detailed view is available. Typically this will mean for shaders the shader source/disassembly will be opened, for texture-type resources the texture viewer will open a new tab for that resource, and for buffers it will open either the Mesh Output window, a raw view of that buffer, or a popup with the constant contents - depending on where the buffer is bound.
+One important thing to note is that most things in the sections for each pipeline stage can be expanded to view in more detail. Look for the Go Icon (|go_arrow|) to indicate that a more detailed view is available. Typically this will mean for shaders the shader source/disassembly will be opened, for texture-type resources the texture viewer will open a new tab for that resource, and for buffers it will open either the Mesh Output window, a raw view of that buffer, or a popup with the constant contents - depending on where the buffer is bound.
+
+.. |link| image:: ../imgs/icons/link.png
+
+Another useful convention is that anywhere an API object is mentioned, its name is written in *bold* followed by a |link|. This is a clickable link to the :doc:`../window/resource_inspector` window which allows you to examine in more detail how the object is defined and what other API objects it is linked to.
 
 For more details, check out the how-to: :doc:`../how/how_object_details`.
 
@@ -170,16 +178,18 @@ Mesh Output
 
 More details can be found on the :doc:`../window/buffer_viewer` page.
 
-.. |undo_arrow| image:: ../imgs/icons/UndoArrow.png
+.. |arrow_undo| image:: ../imgs/icons/arrow_undo.png
 .. |cog| image:: ../imgs/icons/cog.png
 
 Mesh Output allows you to inspect the geometry data as it passes through the pipeline. Both raw data in a grid view and 3D inspection is possible. The tabs in the preview window allow you to choose at which part of the pipeline you'd like to visualise the data.
 
-When in the VS Input tab (or VS Output if tessellating), you can select to solid shader the object with either flat shading or a secondary shading, which lets you right click on any column to select it as colour data to render on the mesh.
+By default the preview shows a wireframe rendering of the mesh, but you can choose solid shading options. This can either be simple shading or use a secondary attribute as color. Right clicking on any column allows you to choose the secondary attribute for rendering.
+
+You can also select which attribute is the position, in case either the auto-detection failed or you want to visualise another attribute like texture co-ordinates in 3D space.
 
 You can hold or click the right mouse button on the mesh preview to select the vertex in the mesh data tables.
 
-When in the VS/GS/DS Output tabs there is the option to show the context leading up to this drawcall by showing everything since the last clear. The default view (which you can reset to with the reset button |undo_arrow|) shows the camera at the view origin looking out through the viewport. By default the output attempts to guess a perspective matrix from the output data, but this can be refined or changed to an orthographic view by opening up the options |cog| and entering more accurate or corrected values.
+The default view for final vertex output data (which you can reset to with the reset button |arrow_undo|) shows the camera at the view origin looking out through the viewport. By default the output attempts to guess a perspective matrix from the output data, but this can be refined or changed to an orthographic view by opening up the options |cog| and entering more accurate or corrected values.
 
 Closing Notes
 -------------

docs/getting_started/tips_tricks.rst

@@ -1,54 +1,26 @@
 Tips & Tricks
 =============
 
-.. |go_arrow| image:: ../imgs/icons/GoArrow.png
+.. |go_arrow| image:: ../imgs/icons/action_hover.png
 .. |wand| image:: ../imgs/icons/wand.png
 
 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.
-
-   .. note::
-
-       These associations must be re-created if RenderDoc is moved to another folder.
-
-#. 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.
+#. 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 the only texture in a capture. 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.
+   For more information check out the :doc:`../window/capture_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`.
+#. If you'd like to see the geometry data visualised in 3D and with each component separated out and formatted, either open "Mesh Output" under the window menu, or click the Go Arrow |go_arrow| on the vertex input attributes 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:
-
-   .. highlight:: c++
-   .. code:: c++
-
-       #include "renderdoc_app.h"
-
-       RENDERDOC_API_1_0_1 *rdoc_api = NULL;
-
-       // At init
-       if(HMODULE mod = GetModuleHandleA("renderdoc.dll"))
-       {
-           pRENDERDOC_GetAPI RENDERDOC_GetAPI = (pRENDERDOC_GetAPI)GetProcAddress(mod, "RENDERDOC_GetAPI");
-           int ret = RENDERDOC_GetAPI(eRENDERDOC_API_Version_1_0_1, (void **)&rdoc_api);
-           assert(ret == 1);
-       }
-
-       // When you wish to trigger the capture
-       if(rdoc_api) rdoc_api->TriggerCapture();
-
-   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 :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.
+#. 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 distributed builds.
 #. To get API debug or error messages, enable "Enable API validation" when capturing then check out the :doc:`../window/debug_messages` window.
+#. You can annotate a capture by adding bookmarks, renaming resources, and adding comments. These can all be saved and embedded in the capture, so that when you share it with someone else.
+#. Dragging an executable onto the RenderDoc window anywhere will open the :guilabel:`Launch Executable` panel with the executable path filled in.
 #. Detecting RenderDoc from your code can either be done by trying to load and use the renderdoc :doc:`../in_application_api`, or through API specific ways:
 
    .. highlight:: c++
@@ -97,5 +69,13 @@ This page is a random hodge-podge of different tips and tricks that might not be
        D3DSetBlobPart(strippedBlob->GetBufferPointer(), strippedBlob->GetBufferSize(), D3D_BLOB_PRIVATE_DATA, 0, &path,        pathSize, &annotatedBlob);
        // use annotatedBlob instead of strippedBlob from here on
 
-#. You can hit :kbd:`Ctrl-G` to open a popup that lets you jump to a particular co-ordinate.
 #. More coming soon hopefully :).
+
+Keyboard Shortcuts
+------------------
+
+#. In the texture viewer you can hit :kbd:`Ctrl-G` to open a popup that lets you jump to a particular pixel co-ordinate.
+#. In the texture viewer, after selecting a pixel you can use the arrow keys to 'nudge' one pixel at a time in any direction to fine-tune the selection.
+#. To close a capture, press :kbd:`Ctrl-F4`. This will prompt to save if there are any unsaved changes.
+#. Anywhere in the UI, you can use :kbd:`Ctrl-Left` and :kbd:`Ctrl-Right` to jump to the previous or next drawcall.
+#. If you :doc:`add some bookmarks <../how/how_annotate_capture>` you can globally press any key from :kbd:`Ctrl-1` to :kbd:`Ctrl-0` to jump to the first 10 bookmarks.

docs/how/how_android_capture.rst

@@ -0,0 +1,61 @@
+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.
+
+Android support is still quite new, so if you run into any rough spots please `open an issue on github <https://github.com/baldurk/renderdoc/issues/new>`_ or `email me <mailto:baldurk@baldurk.org?subject=RenderDoc%20on%20Android>`_.
+
+.. caution::
+
+  For RenderDoc's android support, your package must be installed and it **must be debuggable**.
+
+Quick start
+-----------
+
+Android is supported by using :doc:`Remote Contexts <../how/how_network_capture_replay>` to debug applications on your device from a host computer. To begin, look at the bottom left of the normal RenderDoc UI to see the remote context selection dropdown:
+
+.. figure:: ../imgs/Screenshots/android_remotecontext.png
+
+By default when you start up, this is set to "Local" which means all capture and replay happens on the host computer. To switch to a connected android device, click the drop-down and select your device from the options:
+
+.. note::
+
+  If you don't see your android device listed, try waiting a few seconds as available devices are scanned every so often.
+
+.. |cross| image:: ../imgs/icons/cross.png
+
+Each device listed will likely have a |cross| next to it, indicating that RenderDoc's capture & replay app is not yet running on the device. Select a device, and RenderDoc will check that RenderDoc's app is installed and run it.
+
+.. note::
+
+  After the app is installed once, it will not need to be reinstalled until you update your version of RenderDoc.
+
+Once RenderDoc's app is running, you are ready to capture and replay on android, and the drop-down will indicate the new active connection.
+
+.. figure:: ../imgs/Screenshots/android_connected.png
+
+You can now use the RenderDoc UI as normal, and the entire workflow is exactly the same as you are used to on desktop, except that the capture and replay will happen on the selected android device. For example, when you click browse for an executable to run, it will list the installed packages.
+
+If your package is not debuggable, you will not generally be able to capture it with RenderDoc. Instead build a development copy of your package that has the debuggable flag. In UE4 this is done by unchecking "For Distribution" and in Unity this is done by building a "Development Mode" build.
+
+.. figure:: ../imgs/Screenshots/android_browsepackages.png
+
+Then once connected, you can trigger captures and open them as normal.
+
+Avoiding timeouts on certain packages
+-------------------------------------
+
+If your package can take a long time to startup, you can go to the :doc:`settings window <../window/settings_window>` under the :guilabel:`Android` section and increase the :guilabel:`Max Connection Timeout`.
+
+Troubleshooting
+---------------
+
+RenderDoc assumes your device is already configured for debugging. Check that it appears in ``adb devices``. `See here <https://developer.android.com/studio/run/device.html>`_ for instructions on how to configure that.
+
+If you have Android Studio open, it will interfere with RenderDoc's debugging by attaching to the package itself. Either close it or disable adb integration in "Tools → Android → Enable ADB integration".
+
+RenderDoc does its best to locate or provide necessary android tools. On windows, these tools are shipped with the distributions and all that's required is java - either in your ``PATH`` or via the ``JAVA_HOME`` environment variable. If these tools aren't present then RenderDoc searches through ``PATH`` and other variables like ``ANDROID_HOME`` or ``ANDROID_SDK_ROOT`` to find the SDK. If you don't have those variables set, you can browse to the SDK and JDK folders in the :doc:`settings window <../window/settings_window>` under the :guilabel:`Android` section.
+
+If something goes wrong with these steps, please `open an issue on github <https://github.com/baldurk/renderdoc/issues/new>`__! The process should be as smooth as possible given Android's platform limitations, so if you encounter problems then it may well be fixable.
+
+Often when an operation fails, more information is available via :guilabel:`Help` → :guilabel:`View Diagnostic Log`.

docs/how/how_annotate_capture.rst

@@ -0,0 +1,41 @@
+How do I annotate a capture?
+============================
+
+RenderDoc allows some annotation of capture files, meaning that you can make notes and bookmark important events, then save your changes within the capture itself for sharing with other people. This can be useful for example when investigating a bug or repro case and passing on your findings natively to someone else, instead of having to include additional text like 'texture 148 is the buggy texture'.
+
+All of these modifications can be saved with a capture. Pressing :kbd:`Ctrl-S` or :guilabel:`File` → :guilabel:`Save` will save the capture with any changes that have been made to it in the UI. If you haven't already saved a temporary capture, or the capture is on a remote context, this will need to you save it to a local path.
+
+Bookmarks
+---------
+
+.. |asterisk_orange| image:: ../imgs/icons/asterisk_orange.png
+
+The event browser allows you to make bookmarks on events of particular interest. This allows quick navigation of a frame or jumping back and forth between two events that may be quite separated.
+
+The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`Ctrl-B`. Once you have several bookmarks, you can jump between them by pressing the :kbd:`Ctrl-1` to :kbd:`Ctrl-0` shortcuts from anywhere in the UI, without any need to focus the event browser.
+
+.. figure:: ../imgs/Screenshots/BookmarksBar.png
+
+	Bookmarks bar: The bookmarks bar with several EIDs bookmarks.
+
+When loading any capture with saved bookmarks they will be automatically populated into the UI. This will allow you to highlight particular problematic events and anyone opening the capture will be able to use the shortcuts above to jump immediately to where the problem is.
+
+Resource Renaming
+-----------------
+
+From within the :doc:`../window/resource_inspector` window, you can rename any resource in the capture. Whether the resource already had a custom-specified name, or if it had a default-generated name, you can provide overrides at any time.
+
+To do so, simply select the resource in question in the resource inspector - either by clicking a link from where it is bound, or searching for it by name or type. Then click on the :guilabel:`Rename Resource` button next to the name, and it will open an editing textbox to let you change the name. When you've set the name, press :kbd:`Enter` or click :guilabel:`Rename Resource` again. To cancel a rename, press :kbd:`Escape` or click :guilabel:`Reset name` to restore the name to its original value.
+
+.. figure:: ../imgs/Screenshots/resource_rename.png
+
+	Resource Inspector: Renaming a resource in a capture.
+
+As with bookmarks, these renames can be saved with a capture and are automatically used when loading the capture subsequently. This can be useful to point the way to which resources are causing problems, or specifically how a given resource with a more general name is being used in this particular capture.
+
+Capture Comments
+----------------
+
+In the :doc:`../window/capture_comments` window there is a simple text field allowing you to store any arbitrary text you want within the capture. This could be notes on the environment or build version that was stored.
+
+By default, any capture that is newly opened that contains comments will show those comments first and foremost when opening. This behaviour can be disabled in the :doc:`../window/settings_window`.

docs/how/how_capture_callstack.rst

@@ -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.
+	On Windows 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::
 
@@ -19,13 +19,13 @@ It can be useful when tracking down problems to have an idea of where each API c
 Launching Capture
 -----------------
 
-When launching a capture (as in :doc:`how_capture_log`) you should enable 'collect callstacks'. This will set RenderDoc to collect callstacks at every API entry point that will be serialised into the log.
+When launching a capture (as in :doc:`how_capture_frame`) you should enable :guilabel:`Collect callstacks`. This will set RenderDoc to collect callstacks at every API entry point that will be serialised into the capture file.
 
 .. figure:: ../imgs/Screenshots/Callstacks.png
 
 	Collect Callstacks: Option enabled on the capture dialog.
 
-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.
+If you wish to save some time & overhead you can then enable :guilabel:`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 :guilabel:`Tools` menu and select :guilabel:`Resolve Symbols`. If this menu option isn't available the callstacks did not successfully collect in the capture file.
 
 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.
 
@@ -46,6 +46,6 @@ By default a symbol server will be used, as well as a few default locations such
 
 	PDB locate prompt: Prompt to locate a PDB that cannot be found.
 
-If a PDB cannot be located then you have the option of permanently ignoring that PDB. This can be useful for third party libraries for which no PDB will ever be available. If you don't ignore the PDB you will be prompted to locate it the next time you open a log that references it.
+If a PDB cannot be located then you have the option of permanently ignoring that PDB. This can be useful for third party libraries for which no PDB will ever be available. If you don't ignore the PDB you will be prompted to locate it the next time you open a capture that references it.
 
 Once the symbols have been successfully resolved the callstack section of the API inspector will contain any callstack that was collected for the given drawcall or API call. You can select and copy any levels and paste them elsewhere if you wish.

docs/how/how_capture_frame.rst

@@ -1,22 +1,22 @@
-How do I capture a log?
-=======================
+How do I capture a frame?
+=========================
 
-Capturing logfiles is the starting point to using RenderDoc. Although the basic use is very simple, there are various customisations and more advanced uses. More information on these can be found in the details of the :doc:`../window/capture_log_attach` window.
+Capturing frames is the starting point to using RenderDoc. Although the basic use is very simple, there are various customisations and more advanced uses. More information on these can be found in the details of the :doc:`../window/capture_attach` window.
 
-Capturing logs
---------------
+Capturing frames
+----------------
 
-The basic process of capturing logs is fairly straightforward.
+The basic process of capturing frames 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 launch application window from the menus via :guilabel:`File` → :guilabel:`Launch Application`, 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.
 
 .. figure:: ../imgs/Screenshots/CapturePathCmdline.png
 
-	Capturing: Capturing a logfile specifying its executable path and command line.
+	Capturing: Launching an executable specifying its path and command line.
 
-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`.
+Likewise, the default options generally work well for most situations, however you can look at the details of each option in :doc:`../window/capture_attach`.
 
 Injecting into a Process
 ------------------------
@@ -25,7 +25,7 @@ Injecting into a Process
 
 	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.
+It is possible to inject to an already running process as long as it hasn't yet initialised a graphics API. By selecting :guilabel:`File` → :guilabel:`Inject to Process`, 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.
 
@@ -37,12 +37,12 @@ This can be useful if launching your application from a single exe is non-trivia
 
 	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.
 
-Capture setting files
----------------------
+Capture settings
+----------------
 
 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 path, 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.
 
@@ -51,5 +51,5 @@ You can also use the "Auto start" option - when this option is enabled then a .c
 See Also
 --------
 
-* :doc:`../window/capture_log_attach`
+* :doc:`../window/capture_attach`
 * :doc:`how_network_capture_replay`

docs/how/how_custom_visualisation.rst

@@ -6,15 +6,13 @@ 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 or D3D12, and glsl for OpenGL or Vulkan.
 
 There are several special global variables that can be specified and will be filled in with values by RenderDoc.
 
 Your pixel shader defines an operation that transforms the raw value from the input texture into a value that will then be displayed by the texture viewer. The usual texture viewer controls for range adaption and channels will still be available on the resulting texture.
 
-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 the application storage directory ( ``%APPDATA%/qrenderdoc/`` on windows or ``~/.local/share/qrenderdoc`` elsewhere). 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 capture, and RenderDoc watches for any changes to the files (either externally or in the shader editor in RenderDoc) and automatically reloads them.
 
 .. note::
 
@@ -32,7 +30,7 @@ There are several pre-defined inputs that can either be taken as parameters to t
 The shader editor when using the UI can be used to insert these snippets for you, with the right type and spelling. For GLSL these snippets are inserted at the top of the file just after any ``#version`` statement.
 
 UV co-ordinates
-```````````````
+~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -62,7 +60,7 @@ You can also use the auto-generated system co-ordinates - ``SV_Position`` or ``g
 	You must bind these parameters like this in this order to ensure the linkage with the vertex shader matches.
 
 Constant Parameters
-```````````````````
+~~~~~~~~~~~~~~~~~~~
 
 There are several constant parameters available, each detailed below with the values they contain. Where possible these are bound by name as globals for convenience, but in Vulkan all variables must be contained within a single uniform buffer. The parameters correspond with the GLSL documentation but are contained within a uniform buffer at binding 0, with a structure given as so:
 
@@ -79,10 +77,10 @@ There are several constant parameters available, each detailed below with the va
 		int SelectedSample;
 	} RENDERDOC;
 
-In this way you can access the properties as ``RENDERDOC.TexDim`` insetad of ``RENDERDOC_TexDim``.
+In this way you can access the properties as ``RENDERDOC.TexDim`` instead of ``RENDERDOC_TexDim``.
 
 Texture dimensions
-``````````````````
+~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -99,7 +97,7 @@ This variable will be filled out with the following values:
 * ``.w``  Number of mip levels
 
 Selected Mip level
-``````````````````
+~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -111,7 +109,7 @@ Selected Mip level
 This variable will be filled out with the selected mip level in the UI.
 
 Selected Slice/Face
-```````````````````
+~~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -123,7 +121,7 @@ Selected Slice/Face
 This variable will be filled out with the selected texture array slice (or cubemap face) in the UI.
 
 Selected Multisample sample
-```````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -137,7 +135,7 @@ This variable will be filled out with the selected multisample sample index as c
 So for example in a 4x MSAA texture, the valid values are ``0``, ``1``, ``2``, ``3`` to select a sample, or ``-4`` for 'average value'.
 
 Current texture type
-````````````````````
+~~~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -188,7 +186,7 @@ Vulkan / GLSL
 #. 2D texture (Multisampled)
 
 Samplers (D3D11/D3D12 only)
-```````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. highlight:: c++
 .. code:: c++
@@ -199,7 +197,7 @@ Samplers (D3D11/D3D12 only)
 These samplers are provided to allow you to sample from the resource as opposed to doing straight loads. They are bound by slot and not by variable name - so this means you can name them as you wish but you must specify the register binding explicitly.
 
 Resources
-`````````
+~~~~~~~~~
 
 D3D11 or D3D12 / HLSL
 ^^^^^^^^^^^^^^^^^^^^^

docs/how/how_debug_shader.rst

@@ -3,6 +3,10 @@ How do I debug a shader?
 
 This page goes into detail about how to set up your captures for debugging shaders, as well as how to debug a shader and what controls are available.
 
+.. warning::
+
+   Shader debugging is currently only supported in D3D11. On other APIs the debug options listed below will either be hidden or disabled.
+
 Including debug info in shaders
 -------------------------------
 
@@ -17,7 +21,7 @@ Vertex debugging is invoked from the mesh viewer. With the mesh viewer open you
 
 When a vertex is selected in the mesh data for the vertex input it will be highlighted along with the primitive it is part of in the mesh display, provided the display is in vertex input mode.
 
-Either right click and choose debug vertex from the context menu, or click on the debug icon in the toolbar.
+Right click and choose debug vertex from the context menu.
 
 .. figure:: ../imgs/Screenshots/VertexDebug.png
 
@@ -63,33 +67,35 @@ When debugging, at the moment the controls are fairly basic.
 
 	Shader controls: Controls for stepping through shaders.
 
-.. |runfwd| image:: ../imgs/icons/runfwd.png
-.. |runback| image:: ../imgs/icons/runback.png
+.. |runfwd| image:: ../imgs/icons/control_end_blue.png
+.. |runback| image:: ../imgs/icons/control_start_blue.png
 
-The toolbar at the top gives controls for the program flow through the shader. |runfwd| Run and |runback| Run Backward simply run from the current position all the way through to the end or start of the program respectively.
+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.
+|runfwd| Run and |runback| Run Backward simply run from the current position all the way through to the end or start of the program respectively. The keyboard shortcuts for these controls are :kbd:`F5` and :kbd:`Shift-F5` respectively.
 
 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.
 
-.. |runsample| image:: ../imgs/icons/runsample.png
+.. |runsample| image:: ../imgs/icons/control_sample_blue.png
 
-This button will run to the next texture load, gather or sample operation, and stop as if a breakpoint had been placed on that instruction.
+|runsample| will run to the next texture load, gather or sample operation, and stop as if a breakpoint had been placed on that instruction.
 
-.. |runnaninf| image:: ../imgs/icons/runnaninf.png
+.. |runnaninf| image:: ../imgs/icons/control_nan_blue.png
 
-This button will run to the next operation that generates either a NaN or infinity value instead of a floating point value. This will not apply to operations that produce integer results which may be NaN/infinity when interpreted as float.
+|runnaninf| will run to the next operation that generates either a NaN or infinity value instead of a floating point value. This will not apply to operations that produce integer results which may be NaN/infinity when interpreted as float.
 
-.. |stepnext| image:: ../imgs/icons/stepnext.png
-.. |stepprev| image:: ../imgs/icons/stepprev.png
+.. |stepnext| image:: ../imgs/icons/control_play_blue.png
+.. |stepprev| image:: ../imgs/icons/control_reverse_blue.png
 
-The other controls allow for single stepping and limited running. |stepnext| Step forward will execute the current instruction and continue to the next - this includes following any flow control statements such as jumps, loops, etc.
+|stepnext| Step forward will execute the current instruction and continue to the next - this includes following any flow control statements such as jumps, loops, etc.
 
-|stepprev| Step backwards will jump back to whichever instruction lead to the current instruction. This does not necessarily mean the previous instruction in the program as it could be the destination of a jump. Stepping forwards and stepping backwards will always reverse each other. The shortcuts for these commands are :kbd:`F10` and :kbd:`Shift-F10`
+|stepprev| Step backwards will jump back to whichever instruction lead to the current instruction. This does not necessarily mean the previous instruction in the program as it could be the destination of a jump. Stepping forwards and stepping backwards will always reverse each other.
 
-.. |runcursor| image:: ../imgs/icons/runcursor.png
+The shortcuts for these commands are :kbd:`F10` and :kbd:`Shift-F10`
 
-The final control is to |runcursor| Run to the cursor. This will perform in a similar fashion to the "Run" command, but when it reaches the line that the cursor highlights it will stop and pause execution. It will also stop if it reaches the end of the shader.
+.. |runcursor| image:: ../imgs/icons/control_cursor_blue.png
+
+|runcursor| will run to the cursor. This will perform in a similar fashion to the "Run" command, but when it reaches the line that the cursor highlights it will stop and pause execution. It will also stop if it reaches the end of the shader. The shortcut for this is :kbd:`Ctrl-F10`
 
 
 .. note::
@@ -98,14 +104,11 @@ The final control is to |runcursor| Run to the cursor. This will perform in a si
 
 Hovering over a register in either the disassembly or in the view windows will open a tooltip showing the value in different interpretations.
 
-There is also a toggle available to control the 'default' interpretation of temporary register values - float or int. Since registers are typeless typically they are interpreted as float values, but with this toggle you can toggle them to be interpreted as integers.
+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.
 
 Debugging Displays
 ------------------
 
-Currently there is only a very basic display when debugging shaders.
-
-
 There are two windows that display different types of registers. The constants window will display input and constant buffer registers that are immutable throughout execution. This will also list registers for resources and samplers (with basic format information).
 
 .. figure:: ../imgs/Screenshots/ShaderConsts.png

docs/how/how_edit_shader.rst

@@ -11,34 +11,33 @@ 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`` or ``.glsl`` files in the application storage directory ( ``%APPDATA%/qrenderdoc/`` on windows or ``~/.local/share/qrenderdoc`` elsewhere), 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 when editing externally.
 
-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 file and compiled and reflected in the texture viewer as long as you have that custom shader selected.
 
 How to edit a scene shader
 --------------------------
 
 RenderDoc allows you to edit a shader used in the capture and make changes to it and see the effects in real-time.
 
-
 To launch the shader editor, go to the pipeline stage you wish to change in the :doc:`../window/pipeline_state` windows, and click on the edit button |page_white_edit| next to the shader.
 
-.. note::
-
-	This feature is intended to be used when shader debug info is available and the hlsl source can be used. If the hlsl isn't available, RenderDoc will generate a stub function with the input and output signatures available from the reflection data that you can fill in if you wish.
-
 Any changes to the shader will affect any drawcall using this shader, not just the currently-selected drawcall. The changes will persist until the edit window is closed.
 
 .. warning::
 
 	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.
 
+For SPIR-V shaders in Vulkan, if there is embedded source info it will be used for compilation, however in many cases the source is not available.
+
+RenderDoc allows you to configure a SPIR-V disassembler in the :doc:`../window/settings_window`. By default if ``spirv-cross`` is available it will be pre-configured and invoked automatically to decompile the SPIR-V into compilable GLSL.
+
 Using the built-in shader editor
 --------------------------------
 
-When you have launched the shader editor, the main window will be filled with the hlsl of your shader. In here you can make edits and changes with the basic controls and syntax highlighting available with the Scintilla editor.
+When you have launched the shader editor, the main window will be filled with the source of your shader. In here you can make edits and changes with the basic controls and syntax highlighting available with the Scintilla editor.
 
-To compile the shader and apply your changes, either click the save button in the toolbar or press :kbd:`Ctrl-S`. This will compile the shader and apply it, any warnings and errors will be added to the box below the main source.
+To compile the shader and apply your changes, either click the refresh button in the toolbar or press :kbd:`F5`. This will compile the shader and apply it, any warnings and errors will be added to the box below the main source.
 
 Custom shaders are built with a simple set of flags, any shaders from the scene will be compiled with the flags that were originally passed to the compiler.
 
@@ -46,4 +45,6 @@ Custom shaders are built with a simple set of flags, any shaders from the scene
 
 	If there are errors compiling a visualisation shader, it will be removed from the texture viewer and normal RGB display will be used until you fix the error.
 
+  If there are errors compiling a shader-replacement shader, it will revert back to the original shader from the capture until the error is fixed.
+
 In addition, when editing visualisation shaders a button will be available to insert several useful snippets for custom shaders with the pre-defined variables that can be bound. For more detail, see :doc:`how_custom_visualisation`

docs/how/how_import_export.rst

@@ -0,0 +1,86 @@
+How do I import or export a capture?
+====================================
+
+RenderDoc capture files are in an opaque format containing all of the data needed to construct every API object used in a capture, and then replay the captured frame.
+
+The data is known internally as *structured data* and it can be examined in memory while a capture is opened, and exported to an external file in another format. Similarly, if the external file format contains the full set of data required then it can be imported as a RenderDoc capture.
+
+In-capture access
+-----------------
+
+The structured data is available through the :doc:`python scripting <../window/python_shell>`. As an example, we look at one function call from a capture:
+
+First we obtain the :py:class:`APIEvent` that we want to examine, as the last event in a drawcall's list of events and find the chunk index it refers to:
+
+   .. highlight:: python
+   .. code:: python
+
+       event = pyrenderdoc.GetDrawcall(111).events[-1]
+       print("event %d is at chunk %d" % (event.eventId, event.chunkIndex))
+
+   .. highlight:: none
+   .. code::
+
+       > event 111 is at chunk 223
+
+The structured data is organised as one chunk per function call or logical unit of work, so in this case we can obtain the chunk corresponding to the function call we're interested in.
+
+Once we have the chunk, we can examine its members:
+
+   .. highlight:: python
+   .. code:: python
+
+       chunk = pyrenderdoc.GetStructuredFile().chunks[event.chunkIndex]
+
+       print("We have chunk '%s'" % chunk.name)
+
+       for child in chunk.data.children:
+           print("Parameter %s" % child.name)
+
+   .. highlight:: none
+   .. code::
+
+       > Parameter commandBuffer
+       > Parameter RenderPassBegin
+       > Parameter contents
+       > Parameter DebugMessages
+
+From here we can drill down even further to iterate into struct members, arrays, and all the way down to basic types.
+
+Import/Export to file
+---------------------
+
+RenderDoc offers several built-in file formats for export. Not all of these export the full set of data that can then be re-imported, some only export a certain subset.
+
+One format that shows the full set of data is the XML exporter. There are two options - XML only, which is quick to export as it writes only the structured data, and XML+ZIP which is slower as it also exports the large buffers of data with things like texture and buffer contents.
+
+The XML+ZIP format contains all of the data needed to construct a RenderDoc capture, and so it can also be imported from a file and loaded as a capture.
+
+An example of the above function call exported as XML is here below:
+
+   .. highlight:: xml
+   .. code::
+
+      <chunk id="1045" name="vkCmdBeginRenderPass" length="69" threadID="17140" timestamp="865021" duration="6">
+        <ResourceId name="commandBuffer" typename="VkCommandBuffer" width="8" string="ResourceId::146">146</ResourceId>
+        <struct name="RenderPassBegin" typename="VkRenderPassBeginInfo">
+          <enum name="sType" typename="VkStructureType" string="VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO">43</enum>
+          <null name="pNext" typename="VkGenericStruct" />
+          <ResourceId name="renderPass" typename="VkRenderPass" width="8" string="ResourceId::158">158</ResourceId>
+          <ResourceId name="framebuffer" typename="VkFramebuffer" width="8" string="ResourceId::130">130</ResourceId>
+          <struct name="renderArea" typename="VkRect2D">
+            <struct name="offset" typename="VkOffset2D">
+              <int name="x" typename="int32_t" width="4">0</int>
+              <int name="y" typename="int32_t" width="4">0</int>
+            </struct>
+            <struct name="extent" typename="VkExtent2D">
+              <uint name="width" typename="uint32_t" width="4">1280</uint>
+              <uint name="height" typename="uint32_t" width="4">720</uint>
+            </struct>
+          </struct>
+          <uint name="clearValueCount" typename="uint32_t" width="4">0</uint>
+          <array name="pClearValues" typename="VkClearValue" />
+        </struct>
+        <enum name="contents" typename="VkSubpassContents" string="VK_SUBPASS_CONTENTS_INLINE">0</enum>
+        <array name="DebugMessages" typename="DebugMessage" hidden="true" />
+      </chunk>

docs/how/how_inspect_pixel.rst

@@ -13,13 +13,13 @@ The values that are picked out of the texture are always exact values, and will
 Picking a Pixel Value
 ---------------------
 
-At any point while hovering over the texture the status bar contains the current pixel location that the cursor is hovering over, as well as a basic colour swatch to give some indication of where you are.
+At any point while hovering over the texture the status bar contains the current pixel location that the cursor is hovering over, as well as a basic color swatch to give some indication of where you are.
 
 .. figure:: ../imgs/Screenshots/HoverStatus.png
 
-	Hover Status Bar: The status bar showing position and colour
+	Hover Status Bar: The status bar showing position and color
 
-When the right mouse button is pressed, the currently hovered pixel value will be displayed with the current float precision settings - for more information on how to tune these look at the window reference for the :doc:`../window/options_window`.
+When the right mouse button is pressed, the currently hovered pixel value will be displayed with the current float precision settings - for more information on how to tune these look at the window reference for the :doc:`../window/settings_window`.
 
 For depth textures the depth and stencil values will be displayed separately. The stencil value (as with any integer formatted texture) will be displayed as an integer.
 
@@ -34,7 +34,7 @@ To make fine adjustments by a single pixel at a time, it's easiest to use the ar
 Pixel Context Display
 ---------------------
 
-Whenever a pixel is picked, the pixel context display is updated to surround the currently selected pixel. This dialog is by default docked in the bottom right of the texture viewer, adjacent to the thumbnail strip.
+Whenever a pixel is picked, the pixel context display is updated to surround the currently selected pixel. This dialog is by default docked in the bottom right of the texture viewer, next to the thumbnail strip.
 
 .. figure:: ../imgs/Screenshots/PixelContext.png
 
@@ -43,9 +43,9 @@ Whenever a pixel is picked, the pixel context display is updated to surround the
 This context display shows a zoomed in view of the texture around the area that you've selected so that it's easier to make small adjustments without zooming in and losing a sense of the whole texture.
 
 
-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`.
+The pixel context viewer can also allow you to launch pixel debugging, if the API supports it. 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.
+It also allows you to launch a pixel history view if supported, showing every modification to this pixel in the frame up to the current point.
 
 .. _pixel-history:
 
@@ -54,7 +54,7 @@ Pixel History
 
 When you have a pixel selected, you can click 'History' to open up a pixel history view showing every modification to the selected texture from the start of the frame to the currently selected event.
 
-This display shows each modifying event as its own row, coloured as to whether any modifications happened from this event or not - green for fragments that passed all pipeline tests, red for where fragments failed some test, and light grey for UAV writes where it's unknown if there was a write.
+This display shows each modifying event as its own row, colored as to whether any modifications happened from this event or not - green for fragments that passed all pipeline tests, red for where fragments failed some test, and light grey for arbitrary shader writable resources where it's unknown if there was a write.
 
 You can expand each event to see if there were multiple fragments, and see the shader output value from each fragment.
 

docs/how/how_network_capture_replay.rst

@@ -3,6 +3,8 @@ How do I capture and replay over a network?
 
 RenderDoc supports capture and replay over a network connection. While slightly more complicated than the default workflow of doing everything on one machine, there are a number of scenarios where this can be useful.
 
+This is also the same mechanism used for Android capture and replay, except with built-in native support for supporting Android targets.
+
 If you can run the minimal RenderDoc support for capturing on a target machine such as an embedded device or devkit, the bulk of the replay work can be done on an existing machine where the UI is running.
 
 Likewise if you have a capture that you'd like to run on a different driver or hardware, you don't have to set up a full environment to run RenderDoc, you can just run the minimal remote server.
@@ -12,9 +14,9 @@ Overview
 
 RenderDoc's network support has the core concept of a "Replay Context".
 
-The idea is that by default you are in the "local" replay context. All operations happen relative to your own machine - from executables that you launch to capture, to how replays are processed and instantiated. This is the familiar process, where you browse and launch executables on a machine and all the replaying happens locally.
+By default you are in the "local" replay context. All operations happen relative to your own machine - from executables that you launch, to how replays are processed and instantiated. This is the familiar process, where you browse and launch executables on a machine and all the replaying happens locally.
 
-To use a remote machine, you define a replay context for that machine. Otherwise everything works exactly the same way, but executables are run on that machine and captures are replayed on that machine.
+To use a remote machine, you define a replay context for that machine. Everything else works exactly the same way, but executables are run on that machine and captures are replayed on that machine.
 
 Configuring Remote Hosts
 ------------------------
@@ -29,7 +31,7 @@ This manager allows you to configure both which remote hosts are available, as w
 
 To add a new host, simply type its hostname in the hostname box and click ``Add``. It will be added to the list of known remote hosts, and immediately a network lookup will happen to see if the remote server or any running RenderDoc-injected applications are alive.
 
-At minimum, this is all you must configure. However it is recommended that you configure a command which can be run on the host machine which will remotely start the remote server on that host. The reason for this is that it allows easy capture each time with zero manual extra steps.
+At minimum, this is all you must configure. However it is recommended that you configure a command which can be run on the **local** machine which will **remotely** start the remote server on that host. The reason for this is that it allows easy capture each time with zero manual extra steps.
 
 .. figure:: ../imgs/Screenshots/RemoteHostConfigure.png
 
@@ -55,7 +57,7 @@ An example for this for linux would be to use ``plink.exe`` and passwordless key
 
     plink.exe user@host DISPLAY=:0.0 renderdoccmd remoteserver -d
 
-Assuming that plink.exe is in ``PATH`` on the host machine, and ``renderdoccmd`` is on the host machine.    
+Assuming that plink.exe is in ``PATH`` on the host machine, and ``renderdoccmd`` is on the host machine.
 
 Switching to a Replay Context
 -----------------------------
@@ -81,7 +83,7 @@ Working in a remote replay context
 
 By and large, working in a remote replay context is designed to be transparent to the user. All the familiar operations and workflows will work as expected, perhaps with some small decrease in responsiveness that comes with a network connection's added latency and possible lower specifications of the target system.
 
-In the :doc:`../window/capture_log_attach` window the file and directory browsing is by definition relative to the replay context you are working in. For this reason, a custom dialog is used to display the contents of the remote filesystem instead of the default system dialog for browsing the local computer.
+In the :doc:`../window/capture_attach` window the file and directory browsing is by definition relative to the replay context you are working in. For this reason, a custom dialog is used to display the contents of the remote filesystem instead of the default system dialog for browsing the local computer.
 
 .. figure:: ../imgs/Screenshots/RemoteFileBrowse.png
 
@@ -116,7 +118,7 @@ To whitelist an IP range, add a line such as this:
 
     whitelist 192.168.0.0/16
 
-Which will allow any IP 192.168.x.x to connect. When the remote server starts, it prints the IP ranges it will allow. If no IP ranges are configured, it will by default listen to all private ranges - ``10.0.0.0/24``, ``192.168.0.0/16``, and ``172.16.0.0/12``.
+Which will allow any IP ``192.168.x.x`` to connect. When the remote server starts, it prints the IP ranges it will allow. If no IP ranges are configured, it will by default listen to all private ranges - ``10.0.0.0/24``, ``192.168.0.0/16``, and ``172.16.0.0/12``.
 
 To prevent the server from ever executing any commands regardless of whether the IP is allowed, add a line such as this:
 
@@ -132,4 +134,4 @@ See Also
 --------
 
 * :doc:`../window/capture_connection`
-* :doc:`../window/capture_log_attach`
+* :doc:`../window/capture_attach`

docs/how/how_object_details.rst

@@ -1,10 +1,13 @@
 How do I view details of an object?
 ===================================
 
-.. |goarrow| image:: ../imgs/icons/GoArrow.png
+.. |goarrow| image:: ../imgs/icons/action_hover.png
+.. |link| image:: ../imgs/icons/link.png
 
 The pipeline state viewer allows you to view more details of given resources that are bound to the pipeline. The go arrow |goarrow| is a sign that more details for this resource are available.
 
+Resources that are written in **bold text** with a |link| are clickable links that lead to the :doc:`../window/resource_inspector` with more information about a given resource.
+
 Viewing Shaders
 ---------------
 
@@ -14,7 +17,7 @@ Each shader stage that is active on the pipeline can be expanded to see both the
 
 	Bound Shader: Box showing the currently used shader.
 
-Much of the information that is available from the shader is only available when debugging information is made available. :doc:`More details are available <how_debug_shader>`.
+Much of the information that is available from the shader is only available when debugging information is made available. :doc:`More details are available separately <how_debug_shader>`.
 
 Each file passed to the compiler for this the shader is shown with simple syntax highlighting, as well as the disassembly generated from the bytecode itself.
 
@@ -24,7 +27,7 @@ When this shader reflection information is available it will be integrated into
 
 .. |page_white_edit| image:: ../imgs/icons/page_white_edit.png
 
-Note from here you can also :doc:`live-edit a shader <how_edit_shader>` by clicking the edit button |page_white_edit|. If debug info isn't available to provide HLSL, a basic stub function with the input & output signatures but no body will be created.
+Note from here you can also :doc:`live-edit a shader <how_edit_shader>` by clicking the edit button |page_white_edit|.
 
 Viewing Textures
 ----------------
@@ -33,18 +36,16 @@ The :doc:`../window/texture_viewer` is the primary way of viewing details of tex
 
 A texture that is bound to the pipeline as a resource or output the relevant section of the pipeline will display their dimensions and format. In each place the go arrow |goarrow| will indicate that a new locked tab can be opened up in the texture viewer.
 
-In addition to opening a new view of the texture, the timeline bar will also show the usage of this texture - a green triangle will indicate a place where the texture is read from, and a purple triangle indicates a writing operation. These triangles don't necessarily correspond 1:1 with the event - more details are available on the :doc:`../window/timeline_bar` page.
+In addition to opening a new view of the texture, the timeline bar will also show the usage of this texture - a green triangle will indicate a place where the texture is written to, and a green triangle indicates a read operation. More details are available on the :doc:`../window/timeline_bar` page.
 
 Viewing Buffers
 ---------------
 
 More details on this section are available on the :doc:`../window/buffer_viewer` page.
 
-When opened either from the input layouts or from the 'Window' menu, the buffer viewer opens up in the mesh viewer mode. This is a specialisation of the buffer viewer which will show a 3D display of the mesh represented, as well as viewing the mesh buffers at different points in the pipeline.
+When opened either from the vertex input section the pipeline state view, or from the :guilabel:`Window` menu under :guilabel:`Mesh Output`, the buffer viewer opens up in the mesh viewer mode. This is a specialisation of the buffer viewer which will show a 3D display of the mesh represented, as well as viewing the mesh buffers at different points in the pipeline.
 
-In the general case, buffers bound to the pipeline can be opened as a raw buffer viewer.
-
-This will open up a view of the buffer similar to the mesh viewer, but with a completely customisable buffer layout.
+In the general case, buffers bound to the pipeline can be opened as a raw buffer viewer. This will open up a view of the buffer similar to the mesh viewer, but with a completely customisable buffer layout.
 
 By default if the buffer is bound to the pipeline with a pre-existing structure that can be reflected from the shader then this will be the default, otherwise the default layout will be 4 32bit unsigned integers per element.
 

docs/how/how_view_texture.rst

@@ -62,7 +62,7 @@ In Vulkan you can enable the ``VK_EXT_debug_marker`` extension, which is provide
   nameInfo.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT;
   nameInfo.objectType = VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT;
   nameInfo.object = (uint64_t)tex2d; // this cast may vary by platform/compiler
-  nameInfo.pObjectName = "Example Texture";
+  nameInfo.pObjectName = "Off-screen color framebuffer";
   vkDebugMarkerSetObjectNameEXT(device, &nameInfo);
 
 When this texture is bound to the pipeline it will be listed like so:
@@ -71,14 +71,14 @@ When this texture is bound to the pipeline it will be listed like so:
 
 	Named Texture: The example texture bound with name displayed.
 
-In a similar way any other resource can be named and this will be useful throughout the rest of the analysis.
+In a similar way any other resource can be named and this will be useful throughout the rest of the analysis. If a custom name is not provided, a default name will be generated - as seen above with the Render Pass and Framebuffer objects.
 
 Texture list in Texture Viewer
 ------------------------------
 
-.. |page_white_link| image:: ../imgs/icons/page_white_link.png
+.. |page_white_stack| image:: ../imgs/icons/page_white_stack.png
 
-In the texture viewer you can open a filterable list of all textures in the capture. This can be opened with the texture list icon |page_white_link|. When clicked on this will open a sidebar on the texture viewer that lists all textures.
+In the texture viewer you can open a filterable list of all textures in the capture. This can be opened with the texture list icon |page_white_stack|. When clicked on this will open a sidebar on the texture viewer that lists all textures.
 
 .. figure:: ../imgs/Screenshots/TexList.png
 

docs/how/index.rst

@@ -4,7 +4,7 @@ How do I ...?
 .. toctree::
 
 	how_debug_shader
-	how_capture_log
+	how_capture_frame
 	how_inspect_pixel
 	how_view_texture
 	how_object_details
@@ -12,3 +12,6 @@ How do I ...?
 	how_custom_visualisation
 	how_edit_shader
 	how_network_capture_replay
+	how_android_capture
+	how_annotate_capture
+	how_import_export