diff --git a/docs/behind_scenes/analytics.rst b/docs/behind_scenes/analytics.rst new file mode 100644 index 000000000..affe57377 --- /dev/null +++ b/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 `_ 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 `_. + +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. diff --git a/docs/behind_scenes/d3d12_support.rst b/docs/behind_scenes/d3d12_support.rst index fe072a4f8..b969cc446 100644 --- a/docs/behind_scenes/d3d12_support.rst +++ b/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 `_. - 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 --------------- diff --git a/docs/behind_scenes/how_works.rst b/docs/behind_scenes/how_works.rst index 4a6aea23d..87180e4e9 100644 --- a/docs/behind_scenes/how_works.rst +++ b/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. diff --git a/docs/behind_scenes/index.rst b/docs/behind_scenes/index.rst index 8c137ba73..1e04a149d 100644 --- a/docs/behind_scenes/index.rst +++ b/docs/behind_scenes/index.rst @@ -3,6 +3,7 @@ Behind the scenes .. toctree:: + analytics planned_features how_works opengl_support diff --git a/docs/behind_scenes/opengl_support.rst b/docs/behind_scenes/opengl_support.rst index bd29840aa..75328b547 100644 --- a/docs/behind_scenes/opengl_support.rst +++ b/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 `_. -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 -------- diff --git a/docs/behind_scenes/planned_features.rst b/docs/behind_scenes/planned_features.rst index 7934424dc..1501e57da 100644 --- a/docs/behind_scenes/planned_features.rst +++ b/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 `_. @@ -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. diff --git a/docs/behind_scenes/vulkan_support.rst b/docs/behind_scenes/vulkan_support.rst index 01312957d..c08be876c 100644 --- a/docs/behind_scenes/vulkan_support.rst +++ b/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 `_. - 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 -------- diff --git a/docs/conf.py b/docs/conf.py index da172142e..f2962b06d 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/credits_acknowledgements.rst b/docs/credits_acknowledgements.rst index 2d90368fa..e88e7f597 100644 --- a/docs/credits_acknowledgements.rst +++ b/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 `_ - Copyright 2008 by jkristia, distributed under the `CPOL license `_. - - An invaluable control filling a much needed niche in .NET winforms. - -* `DockPanel `_ - 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 `_ - 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 `_ - ScintillaNET Copyright 2002-2006 Garrett Serack, `Scintilla `_ 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 `_ - 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 `_ - 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 `_ - 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 `_ - 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 `_ - 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 `_ - 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 `_ - Copyright IronPython Team, distributed under the Apache 2.0 license. - - Used for the Python shell/integration in the UI. - * `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 `_. + +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. diff --git a/docs/getting_started/faq.rst b/docs/getting_started/faq.rst index 39c593062..09cab0956 100644 --- a/docs/getting_started/faq.rst +++ b/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 `__ 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 `_ 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 `_. + +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 `__ 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 `__ 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 `__ if you have anything you'd like to ask or suggest. I use a `GitHub repository `_ for tracking bugs and feature requests so that's the best place to file an issue. -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 `_ 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 ` in the documentation for the :doc:`../window/capture_log_attach` window. +There are :ref:`more details available ` in the documentation for the :doc:`../window/capture_attach` window. diff --git a/docs/getting_started/features.rst b/docs/getting_started/features.rst index 5d25af718..8270066de 100644 --- a/docs/getting_started/features.rst +++ b/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 -------- diff --git a/docs/getting_started/gotchas_known_issues.rst b/docs/getting_started/gotchas_known_issues.rst index f676da639..399f2404b 100644 --- a/docs/getting_started/gotchas_known_issues.rst +++ b/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>`. diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 64fd35eaf..e387e2657 100644 --- a/docs/getting_started/index.rst +++ b/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 diff --git a/docs/getting_started/quick_start.rst b/docs/getting_started/quick_start.rst index 2edf46032..de7aec7fa 100644 --- a/docs/getting_started/quick_start.rst +++ b/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 `_. sample from `Sascha Willems' Vulkan samples repository `_.. -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 ------------- diff --git a/docs/getting_started/tips_tricks.rst b/docs/getting_started/tips_tricks.rst index 48e8aa738..62f6cd111 100644 --- a/docs/getting_started/tips_tricks.rst +++ b/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. diff --git a/docs/how/how_android_capture.rst b/docs/how/how_android_capture.rst new file mode 100644 index 000000000..52df86582 --- /dev/null +++ b/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 `_ or `email me `_. + +.. 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 `_ 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 `__! 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`. diff --git a/docs/how/how_annotate_capture.rst b/docs/how/how_annotate_capture.rst new file mode 100644 index 000000000..4c1740f0c --- /dev/null +++ b/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`. diff --git a/docs/how/how_capture_callstack.rst b/docs/how/how_capture_callstack.rst index 846237850..c19fb5409 100644 --- a/docs/how/how_capture_callstack.rst +++ b/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. diff --git a/docs/how/how_capture_log.rst b/docs/how/how_capture_frame.rst similarity index 68% rename from docs/how/how_capture_log.rst rename to docs/how/how_capture_frame.rst index dea03d8db..c53d00f9b 100644 --- a/docs/how/how_capture_log.rst +++ b/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` diff --git a/docs/how/how_custom_visualisation.rst b/docs/how/how_custom_visualisation.rst index a0ac9d3de..4e729a989 100644 --- a/docs/how/how_custom_visualisation.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/how/how_debug_shader.rst b/docs/how/how_debug_shader.rst index 294b3415f..007645549 100644 --- a/docs/how/how_debug_shader.rst +++ b/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 diff --git a/docs/how/how_edit_shader.rst b/docs/how/how_edit_shader.rst index 77754cd0e..79315b9e4 100644 --- a/docs/how/how_edit_shader.rst +++ b/docs/how/how_edit_shader.rst @@ -11,34 +11,33 @@ How to edit a custom shader :doc:`Custom visualisation shaders ` 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` diff --git a/docs/how/how_import_export.rst b/docs/how/how_import_export.rst new file mode 100644 index 000000000..a77ab39b4 --- /dev/null +++ b/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:: + + + 146 + + 43 + + 158 + 130 + + + 0 + 0 + + + 1280 + 720 + + + 0 + + + 0 + diff --git a/docs/how/how_inspect_pixel.rst b/docs/how/how_inspect_pixel.rst index 2cedb9934..403ccb79c 100644 --- a/docs/how/how_inspect_pixel.rst +++ b/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. diff --git a/docs/how/how_network_capture_replay.rst b/docs/how/how_network_capture_replay.rst index c0e7948bb..6d3327bbd 100644 --- a/docs/how/how_network_capture_replay.rst +++ b/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` diff --git a/docs/how/how_object_details.rst b/docs/how/how_object_details.rst index fd57fd310..49ff991e5 100644 --- a/docs/how/how_object_details.rst +++ b/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 `. +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 `. 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 ` 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 ` 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. diff --git a/docs/how/how_view_texture.rst b/docs/how/how_view_texture.rst index 7f49c2571..471bb8c05 100644 --- a/docs/how/how_view_texture.rst +++ b/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 diff --git a/docs/how/index.rst b/docs/how/index.rst index 1fc24bfe4..11f3ef80b 100644 --- a/docs/how/index.rst +++ b/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 diff --git a/docs/imgs/QuickStart/QuickStart1.png b/docs/imgs/QuickStart/QuickStart1.png index 28c6ba03f..2b10439bc 100644 Binary files a/docs/imgs/QuickStart/QuickStart1.png and b/docs/imgs/QuickStart/QuickStart1.png differ diff --git a/docs/imgs/QuickStart/QuickStart2.png b/docs/imgs/QuickStart/QuickStart2.png index 7cd25e18a..3476979d0 100644 Binary files a/docs/imgs/QuickStart/QuickStart2.png and b/docs/imgs/QuickStart/QuickStart2.png differ diff --git a/docs/imgs/QuickStart/QuickStart3.png b/docs/imgs/QuickStart/QuickStart3.png index 1a7e117f3..b4e0e93e7 100644 Binary files a/docs/imgs/QuickStart/QuickStart3.png and b/docs/imgs/QuickStart/QuickStart3.png differ diff --git a/docs/imgs/QuickStart/QuickStart4.png b/docs/imgs/QuickStart/QuickStart4.png index 37ad6c4c0..05d029bd1 100644 Binary files a/docs/imgs/QuickStart/QuickStart4.png and b/docs/imgs/QuickStart/QuickStart4.png differ diff --git a/docs/imgs/QuickStart/QuickStart5.png b/docs/imgs/QuickStart/QuickStart5.png index a2f15d204..e9ffb73c5 100644 Binary files a/docs/imgs/QuickStart/QuickStart5.png and b/docs/imgs/QuickStart/QuickStart5.png differ diff --git a/docs/imgs/QuickStart/QuickStart6.png b/docs/imgs/QuickStart/QuickStart6.png index 4b349b6f6..92d0b7df1 100644 Binary files a/docs/imgs/QuickStart/QuickStart6.png and b/docs/imgs/QuickStart/QuickStart6.png differ diff --git a/docs/imgs/QuickStart/QuickStart7.png b/docs/imgs/QuickStart/QuickStart7.png index c85035c8a..cc8343b18 100644 Binary files a/docs/imgs/QuickStart/QuickStart7.png and b/docs/imgs/QuickStart/QuickStart7.png differ diff --git a/docs/imgs/QuickStart/QuickStart8.png b/docs/imgs/QuickStart/QuickStart8.png index 89c8f2a81..4b18aedac 100644 Binary files a/docs/imgs/QuickStart/QuickStart8.png and b/docs/imgs/QuickStart/QuickStart8.png differ diff --git a/docs/imgs/Screenshots/APIList.png b/docs/imgs/Screenshots/APIList.png index 9611ca59d..25aca18a7 100644 Binary files a/docs/imgs/Screenshots/APIList.png and b/docs/imgs/Screenshots/APIList.png differ diff --git a/docs/imgs/Screenshots/AfterRangeZoom.png b/docs/imgs/Screenshots/AfterRangeZoom.png index aea3dcdd9..4a0b8f2e6 100644 Binary files a/docs/imgs/Screenshots/AfterRangeZoom.png and b/docs/imgs/Screenshots/AfterRangeZoom.png differ diff --git a/docs/imgs/Screenshots/BeforeRangeZoom.png b/docs/imgs/Screenshots/BeforeRangeZoom.png index 8b5d0dba2..40246e17a 100644 Binary files a/docs/imgs/Screenshots/BeforeRangeZoom.png and b/docs/imgs/Screenshots/BeforeRangeZoom.png differ diff --git a/docs/imgs/Screenshots/BookmarksBar.png b/docs/imgs/Screenshots/BookmarksBar.png index facef3961..ddbcac2ae 100644 Binary files a/docs/imgs/Screenshots/BookmarksBar.png and b/docs/imgs/Screenshots/BookmarksBar.png differ diff --git a/docs/imgs/Screenshots/BufferOptions.png b/docs/imgs/Screenshots/BufferOptions.png index 5d06ee6ed..8d0f7fb03 100644 Binary files a/docs/imgs/Screenshots/BufferOptions.png and b/docs/imgs/Screenshots/BufferOptions.png differ diff --git a/docs/imgs/Screenshots/CBuffer.png b/docs/imgs/Screenshots/CBuffer.png index e4e575b0a..37509e08b 100644 Binary files a/docs/imgs/Screenshots/CBuffer.png and b/docs/imgs/Screenshots/CBuffer.png differ diff --git a/docs/imgs/Screenshots/CallstackPanel.png b/docs/imgs/Screenshots/CallstackPanel.png index af65e9649..d8dbd0656 100644 Binary files a/docs/imgs/Screenshots/CallstackPanel.png and b/docs/imgs/Screenshots/CallstackPanel.png differ diff --git a/docs/imgs/Screenshots/Callstacks.png b/docs/imgs/Screenshots/Callstacks.png index 36031733f..fd118b929 100644 Binary files a/docs/imgs/Screenshots/Callstacks.png and b/docs/imgs/Screenshots/Callstacks.png differ diff --git a/docs/imgs/Screenshots/CaptureEnvVarEditor.png b/docs/imgs/Screenshots/CaptureEnvVarEditor.png index bc5cb9eda..c4ed9861f 100644 Binary files a/docs/imgs/Screenshots/CaptureEnvVarEditor.png and b/docs/imgs/Screenshots/CaptureEnvVarEditor.png differ diff --git a/docs/imgs/Screenshots/CapturePathCmdline.png b/docs/imgs/Screenshots/CapturePathCmdline.png index 60352ade0..c79c87ed3 100644 Binary files a/docs/imgs/Screenshots/CapturePathCmdline.png and b/docs/imgs/Screenshots/CapturePathCmdline.png differ diff --git a/docs/imgs/Screenshots/CurrentShader.png b/docs/imgs/Screenshots/CurrentShader.png index 705862c26..bf6af84bb 100644 Binary files a/docs/imgs/Screenshots/CurrentShader.png and b/docs/imgs/Screenshots/CurrentShader.png differ diff --git a/docs/imgs/Screenshots/CurrentVsLockedTab.png b/docs/imgs/Screenshots/CurrentVsLockedTab.png index 9ed71d1cc..87b9a5842 100644 Binary files a/docs/imgs/Screenshots/CurrentVsLockedTab.png and b/docs/imgs/Screenshots/CurrentVsLockedTab.png differ diff --git a/docs/imgs/Screenshots/CustomDisplay.png b/docs/imgs/Screenshots/CustomDisplay.png index 757e4c003..5a80b6aa4 100644 Binary files a/docs/imgs/Screenshots/CustomDisplay.png and b/docs/imgs/Screenshots/CustomDisplay.png differ diff --git a/docs/imgs/Screenshots/DebugMessages.png b/docs/imgs/Screenshots/DebugMessages.png index 639ee6a87..227c3e9e8 100644 Binary files a/docs/imgs/Screenshots/DebugMessages.png and b/docs/imgs/Screenshots/DebugMessages.png differ diff --git a/docs/imgs/Screenshots/FindResults.png b/docs/imgs/Screenshots/FindResults.png index 9112318f2..ba7b71ee6 100644 Binary files a/docs/imgs/Screenshots/FindResults.png and b/docs/imgs/Screenshots/FindResults.png differ diff --git a/docs/imgs/Screenshots/HoverStatus.png b/docs/imgs/Screenshots/HoverStatus.png index afc718fd3..1a6d2627f 100644 Binary files a/docs/imgs/Screenshots/HoverStatus.png and b/docs/imgs/Screenshots/HoverStatus.png differ diff --git a/docs/imgs/Screenshots/Injecting.png b/docs/imgs/Screenshots/Injecting.png index 609363e7f..6392caffa 100644 Binary files a/docs/imgs/Screenshots/Injecting.png and b/docs/imgs/Screenshots/Injecting.png differ diff --git a/docs/imgs/Screenshots/JumpEID.png b/docs/imgs/Screenshots/JumpEID.png index f9534f18f..fd7d0d250 100644 Binary files a/docs/imgs/Screenshots/JumpEID.png and b/docs/imgs/Screenshots/JumpEID.png differ diff --git a/docs/imgs/Screenshots/LabelledTexViewer.png b/docs/imgs/Screenshots/LabelledTexViewer.png index c29026431..871700d28 100644 Binary files a/docs/imgs/Screenshots/LabelledTexViewer.png and b/docs/imgs/Screenshots/LabelledTexViewer.png differ diff --git a/docs/imgs/Screenshots/LayerRegistration.png b/docs/imgs/Screenshots/LayerRegistration.png index 516d4ff71..5d6fa7f77 100644 Binary files a/docs/imgs/Screenshots/LayerRegistration.png and b/docs/imgs/Screenshots/LayerRegistration.png differ diff --git a/docs/imgs/Screenshots/LiveCaptureTools.png b/docs/imgs/Screenshots/LiveCaptureTools.png index 213afe666..1a41c088e 100644 Binary files a/docs/imgs/Screenshots/LiveCaptureTools.png and b/docs/imgs/Screenshots/LiveCaptureTools.png differ diff --git a/docs/imgs/Screenshots/MultipleCaptures.png b/docs/imgs/Screenshots/MultipleCaptures.png index e1b4e8c7b..086ecd00d 100644 Binary files a/docs/imgs/Screenshots/MultipleCaptures.png and b/docs/imgs/Screenshots/MultipleCaptures.png differ diff --git a/docs/imgs/Screenshots/NamedTex.png b/docs/imgs/Screenshots/NamedTex.png index a571f471b..f0bdf4cdb 100644 Binary files a/docs/imgs/Screenshots/NamedTex.png and b/docs/imgs/Screenshots/NamedTex.png differ diff --git a/docs/imgs/Screenshots/NeedPDB.png b/docs/imgs/Screenshots/NeedPDB.png index 396ba4cb3..cb675ee30 100644 Binary files a/docs/imgs/Screenshots/NeedPDB.png and b/docs/imgs/Screenshots/NeedPDB.png differ diff --git a/docs/imgs/Screenshots/NeedResolve.png b/docs/imgs/Screenshots/NeedResolve.png index 29168aa8f..b25422e6b 100644 Binary files a/docs/imgs/Screenshots/NeedResolve.png and b/docs/imgs/Screenshots/NeedResolve.png differ diff --git a/docs/imgs/Screenshots/OpenCapNewInstance.png b/docs/imgs/Screenshots/OpenCapNewInstance.png index 682387643..2ac50c849 100644 Binary files a/docs/imgs/Screenshots/OpenCapNewInstance.png and b/docs/imgs/Screenshots/OpenCapNewInstance.png differ diff --git a/docs/imgs/Screenshots/OpenLockedTab.png b/docs/imgs/Screenshots/OpenLockedTab.png index 09e926819..0bd8229da 100644 Binary files a/docs/imgs/Screenshots/OpenLockedTab.png and b/docs/imgs/Screenshots/OpenLockedTab.png differ diff --git a/docs/imgs/Screenshots/OverlaySelect.png b/docs/imgs/Screenshots/OverlaySelect.png index 89eb871a3..210d56619 100644 Binary files a/docs/imgs/Screenshots/OverlaySelect.png and b/docs/imgs/Screenshots/OverlaySelect.png differ diff --git a/docs/imgs/Screenshots/PipelineBar.png b/docs/imgs/Screenshots/PipelineBar.png index 5e766808c..3218e0df2 100644 Binary files a/docs/imgs/Screenshots/PipelineBar.png and b/docs/imgs/Screenshots/PipelineBar.png differ diff --git a/docs/imgs/Screenshots/PixelContext.png b/docs/imgs/Screenshots/PixelContext.png index 1c3b88338..49a05145a 100644 Binary files a/docs/imgs/Screenshots/PixelContext.png and b/docs/imgs/Screenshots/PixelContext.png differ diff --git a/docs/imgs/Screenshots/PixelHistoryTimeline.png b/docs/imgs/Screenshots/PixelHistoryTimeline.png index 9561447dd..fb46b93e1 100644 Binary files a/docs/imgs/Screenshots/PixelHistoryTimeline.png and b/docs/imgs/Screenshots/PixelHistoryTimeline.png differ diff --git a/docs/imgs/Screenshots/RGBAChannels.png b/docs/imgs/Screenshots/RGBAChannels.png index 485548aa1..738c5492d 100644 Binary files a/docs/imgs/Screenshots/RGBAChannels.png and b/docs/imgs/Screenshots/RGBAChannels.png differ diff --git a/docs/imgs/Screenshots/RGBMChannels.png b/docs/imgs/Screenshots/RGBMChannels.png index 46fdb3b39..8f8aaff85 100644 Binary files a/docs/imgs/Screenshots/RGBMChannels.png and b/docs/imgs/Screenshots/RGBMChannels.png differ diff --git a/docs/imgs/Screenshots/RMBStatus.png b/docs/imgs/Screenshots/RMBStatus.png index 9e4c8f8f9..e3dc37dc4 100644 Binary files a/docs/imgs/Screenshots/RMBStatus.png and b/docs/imgs/Screenshots/RMBStatus.png differ diff --git a/docs/imgs/Screenshots/RangeControl.png b/docs/imgs/Screenshots/RangeControl.png index b62f54404..a3167112b 100644 Binary files a/docs/imgs/Screenshots/RangeControl.png and b/docs/imgs/Screenshots/RangeControl.png differ diff --git a/docs/imgs/Screenshots/RangeHistogram.png b/docs/imgs/Screenshots/RangeHistogram.png index a73f61d76..26805e18b 100644 Binary files a/docs/imgs/Screenshots/RangeHistogram.png and b/docs/imgs/Screenshots/RangeHistogram.png differ diff --git a/docs/imgs/Screenshots/RawBuffer.png b/docs/imgs/Screenshots/RawBuffer.png index df70b8acf..5d13db0ca 100644 Binary files a/docs/imgs/Screenshots/RawBuffer.png and b/docs/imgs/Screenshots/RawBuffer.png differ diff --git a/docs/imgs/Screenshots/RemoteContextChooser.png b/docs/imgs/Screenshots/RemoteContextChooser.png index 2ee20f396..9dff6e5e7 100644 Binary files a/docs/imgs/Screenshots/RemoteContextChooser.png and b/docs/imgs/Screenshots/RemoteContextChooser.png differ diff --git a/docs/imgs/Screenshots/RemoteContextStatus.png b/docs/imgs/Screenshots/RemoteContextStatus.png index 4580fb31e..ea7930257 100644 Binary files a/docs/imgs/Screenshots/RemoteContextStatus.png and b/docs/imgs/Screenshots/RemoteContextStatus.png differ diff --git a/docs/imgs/Screenshots/RemoteFileBrowse.png b/docs/imgs/Screenshots/RemoteFileBrowse.png index 7b26ebe6d..41f561683 100644 Binary files a/docs/imgs/Screenshots/RemoteFileBrowse.png and b/docs/imgs/Screenshots/RemoteFileBrowse.png differ diff --git a/docs/imgs/Screenshots/RemoteHostCapturePrompt.png b/docs/imgs/Screenshots/RemoteHostCapturePrompt.png index 284dea6e5..8387bec1b 100644 Binary files a/docs/imgs/Screenshots/RemoteHostCapturePrompt.png and b/docs/imgs/Screenshots/RemoteHostCapturePrompt.png differ diff --git a/docs/imgs/Screenshots/RemoteHostConfigure.png b/docs/imgs/Screenshots/RemoteHostConfigure.png index 60a6f9a09..a882da3f6 100644 Binary files a/docs/imgs/Screenshots/RemoteHostConfigure.png and b/docs/imgs/Screenshots/RemoteHostConfigure.png differ diff --git a/docs/imgs/Screenshots/RemoteHostManager.png b/docs/imgs/Screenshots/RemoteHostManager.png index 063911e63..a974cd12a 100644 Binary files a/docs/imgs/Screenshots/RemoteHostManager.png and b/docs/imgs/Screenshots/RemoteHostManager.png differ diff --git a/docs/imgs/Screenshots/ResourceUsage.png b/docs/imgs/Screenshots/ResourceUsage.png index e75bd3b24..e8467b94e 100644 Binary files a/docs/imgs/Screenshots/ResourceUsage.png and b/docs/imgs/Screenshots/ResourceUsage.png differ diff --git a/docs/imgs/Screenshots/ShaderConsts.png b/docs/imgs/Screenshots/ShaderConsts.png index 7ae731a0a..bca948d45 100644 Binary files a/docs/imgs/Screenshots/ShaderConsts.png and b/docs/imgs/Screenshots/ShaderConsts.png differ diff --git a/docs/imgs/Screenshots/ShaderControls.png b/docs/imgs/Screenshots/ShaderControls.png index 2c12c3d99..6a05a7039 100644 Binary files a/docs/imgs/Screenshots/ShaderControls.png and b/docs/imgs/Screenshots/ShaderControls.png differ diff --git a/docs/imgs/Screenshots/ShaderRegs.png b/docs/imgs/Screenshots/ShaderRegs.png index 893c20704..6709f9692 100644 Binary files a/docs/imgs/Screenshots/ShaderRegs.png and b/docs/imgs/Screenshots/ShaderRegs.png differ diff --git a/docs/imgs/Screenshots/ShaderWatch.png b/docs/imgs/Screenshots/ShaderWatch.png index a34b30679..78ce03737 100644 Binary files a/docs/imgs/Screenshots/ShaderWatch.png and b/docs/imgs/Screenshots/ShaderWatch.png differ diff --git a/docs/imgs/Screenshots/SolidPreview.png b/docs/imgs/Screenshots/SolidPreview.png index 91a068f7e..45207432a 100644 Binary files a/docs/imgs/Screenshots/SolidPreview.png and b/docs/imgs/Screenshots/SolidPreview.png differ diff --git a/docs/imgs/Screenshots/SubresourceSelect.png b/docs/imgs/Screenshots/SubresourceSelect.png index d51ae8d08..e7c33ccc3 100644 Binary files a/docs/imgs/Screenshots/SubresourceSelect.png and b/docs/imgs/Screenshots/SubresourceSelect.png differ diff --git a/docs/imgs/Screenshots/TexList.png b/docs/imgs/Screenshots/TexList.png index cd4edb68e..05be01b11 100644 Binary files a/docs/imgs/Screenshots/TexList.png and b/docs/imgs/Screenshots/TexList.png differ diff --git a/docs/imgs/Screenshots/TimelineBar.png b/docs/imgs/Screenshots/TimelineBar.png index 098e7ca38..cc53bce1b 100644 Binary files a/docs/imgs/Screenshots/TimelineBar.png and b/docs/imgs/Screenshots/TimelineBar.png differ diff --git a/docs/imgs/Screenshots/VertexDebug.png b/docs/imgs/Screenshots/VertexDebug.png index e10844d80..fd78a2f24 100644 Binary files a/docs/imgs/Screenshots/VertexDebug.png and b/docs/imgs/Screenshots/VertexDebug.png differ diff --git a/docs/imgs/Screenshots/ZoomControls.png b/docs/imgs/Screenshots/ZoomControls.png index 74ab0eae9..713f91310 100644 Binary files a/docs/imgs/Screenshots/ZoomControls.png and b/docs/imgs/Screenshots/ZoomControls.png differ diff --git a/docs/imgs/Screenshots/android_browsepackages.png b/docs/imgs/Screenshots/android_browsepackages.png new file mode 100644 index 000000000..1fd39a3fe Binary files /dev/null and b/docs/imgs/Screenshots/android_browsepackages.png differ diff --git a/docs/imgs/Screenshots/android_captured.png b/docs/imgs/Screenshots/android_captured.png new file mode 100644 index 000000000..ebda00ff6 Binary files /dev/null and b/docs/imgs/Screenshots/android_captured.png differ diff --git a/docs/imgs/Screenshots/android_connected.png b/docs/imgs/Screenshots/android_connected.png new file mode 100644 index 000000000..92a12831e Binary files /dev/null and b/docs/imgs/Screenshots/android_connected.png differ diff --git a/docs/imgs/Screenshots/android_remotecontext.png b/docs/imgs/Screenshots/android_remotecontext.png new file mode 100644 index 000000000..a6f21f06f Binary files /dev/null and b/docs/imgs/Screenshots/android_remotecontext.png differ diff --git a/docs/imgs/Screenshots/capture_comments.png b/docs/imgs/Screenshots/capture_comments.png new file mode 100644 index 000000000..3252ab0bd Binary files /dev/null and b/docs/imgs/Screenshots/capture_comments.png differ diff --git a/docs/imgs/Screenshots/counter_selection.png b/docs/imgs/Screenshots/counter_selection.png new file mode 100644 index 000000000..c9998b095 Binary files /dev/null and b/docs/imgs/Screenshots/counter_selection.png differ diff --git a/docs/imgs/Screenshots/counter_view.png b/docs/imgs/Screenshots/counter_view.png new file mode 100644 index 000000000..ad43ef6a4 Binary files /dev/null and b/docs/imgs/Screenshots/counter_view.png differ diff --git a/docs/imgs/Screenshots/pythonshell.png b/docs/imgs/Screenshots/pythonshell.png index b7c156229..079892a03 100644 Binary files a/docs/imgs/Screenshots/pythonshell.png and b/docs/imgs/Screenshots/pythonshell.png differ diff --git a/docs/imgs/Screenshots/resource_inspector.png b/docs/imgs/Screenshots/resource_inspector.png new file mode 100644 index 000000000..ff05caec9 Binary files /dev/null and b/docs/imgs/Screenshots/resource_inspector.png differ diff --git a/docs/imgs/Screenshots/resource_rename.png b/docs/imgs/Screenshots/resource_rename.png new file mode 100644 index 000000000..d56a3408f Binary files /dev/null and b/docs/imgs/Screenshots/resource_rename.png differ diff --git a/docs/imgs/icons/GoArrow.png b/docs/imgs/icons/GoArrow.png deleted file mode 100644 index b244731cb..000000000 Binary files a/docs/imgs/icons/GoArrow.png and /dev/null differ diff --git a/docs/imgs/icons/UndoArrow.png b/docs/imgs/icons/UndoArrow.png deleted file mode 100644 index 6972c5e59..000000000 Binary files a/docs/imgs/icons/UndoArrow.png and /dev/null differ diff --git a/docs/imgs/icons/action_hover.png b/docs/imgs/icons/action_hover.png new file mode 100644 index 000000000..1025413f6 Binary files /dev/null and b/docs/imgs/icons/action_hover.png differ diff --git a/docs/imgs/icons/add.png b/docs/imgs/icons/add.png index 6332fefea..0ea124a74 100644 Binary files a/docs/imgs/icons/add.png and b/docs/imgs/icons/add.png differ diff --git a/docs/imgs/icons/arrow_join.png b/docs/imgs/icons/arrow_join.png index a128413d8..51e7de976 100644 Binary files a/docs/imgs/icons/arrow_join.png and b/docs/imgs/icons/arrow_join.png differ diff --git a/docs/imgs/icons/arrow_left.png b/docs/imgs/icons/arrow_left.png new file mode 100644 index 000000000..d9c50c4d3 Binary files /dev/null and b/docs/imgs/icons/arrow_left.png differ diff --git a/docs/imgs/icons/arrow_out.png b/docs/imgs/icons/arrow_out.png new file mode 100644 index 000000000..0609b3e1a Binary files /dev/null and b/docs/imgs/icons/arrow_out.png differ diff --git a/docs/imgs/icons/arrow_right.png b/docs/imgs/icons/arrow_right.png new file mode 100644 index 000000000..8d204afeb Binary files /dev/null and b/docs/imgs/icons/arrow_right.png differ diff --git a/docs/imgs/icons/arrow_undo.png b/docs/imgs/icons/arrow_undo.png index 6972c5e59..a588266dc 100644 Binary files a/docs/imgs/icons/arrow_undo.png and b/docs/imgs/icons/arrow_undo.png differ diff --git a/docs/imgs/icons/asterisk_orange.png b/docs/imgs/icons/asterisk_orange.png index 1ebebde54..86fde52fc 100644 Binary files a/docs/imgs/icons/asterisk_orange.png and b/docs/imgs/icons/asterisk_orange.png differ diff --git a/docs/imgs/icons/chart_curve.png b/docs/imgs/icons/chart_curve.png index 01e933a61..fafb7e144 100644 Binary files a/docs/imgs/icons/chart_curve.png and b/docs/imgs/icons/chart_curve.png differ diff --git a/docs/imgs/icons/checkerboard.png b/docs/imgs/icons/checkerboard.png new file mode 100644 index 000000000..2792ef086 Binary files /dev/null and b/docs/imgs/icons/checkerboard.png differ diff --git a/docs/imgs/icons/cog.png b/docs/imgs/icons/cog.png index 67de2c6cc..8f4eeb761 100644 Binary files a/docs/imgs/icons/cog.png and b/docs/imgs/icons/cog.png differ diff --git a/docs/imgs/icons/color_wheel.png b/docs/imgs/icons/color_wheel.png index 809fb00e5..287a34458 100644 Binary files a/docs/imgs/icons/color_wheel.png and b/docs/imgs/icons/color_wheel.png differ diff --git a/docs/imgs/icons/control_cursor_blue.png b/docs/imgs/icons/control_cursor_blue.png new file mode 100644 index 000000000..2dd1f960c Binary files /dev/null and b/docs/imgs/icons/control_cursor_blue.png differ diff --git a/docs/imgs/icons/control_end_blue.png b/docs/imgs/icons/control_end_blue.png new file mode 100644 index 000000000..88dc738c3 Binary files /dev/null and b/docs/imgs/icons/control_end_blue.png differ diff --git a/docs/imgs/icons/control_nan_blue.png b/docs/imgs/icons/control_nan_blue.png new file mode 100644 index 000000000..a5b1506e3 Binary files /dev/null and b/docs/imgs/icons/control_nan_blue.png differ diff --git a/docs/imgs/icons/control_play_blue.png b/docs/imgs/icons/control_play_blue.png new file mode 100644 index 000000000..184be2312 Binary files /dev/null and b/docs/imgs/icons/control_play_blue.png differ diff --git a/docs/imgs/icons/control_reverse_blue.png b/docs/imgs/icons/control_reverse_blue.png new file mode 100644 index 000000000..f2aaee040 Binary files /dev/null and b/docs/imgs/icons/control_reverse_blue.png differ diff --git a/docs/imgs/icons/control_sample_blue.png b/docs/imgs/icons/control_sample_blue.png new file mode 100644 index 000000000..a63b5b2f5 Binary files /dev/null and b/docs/imgs/icons/control_sample_blue.png differ diff --git a/docs/imgs/icons/control_start_blue.png b/docs/imgs/icons/control_start_blue.png new file mode 100644 index 000000000..172a73ce4 Binary files /dev/null and b/docs/imgs/icons/control_start_blue.png differ diff --git a/docs/imgs/icons/cross.png b/docs/imgs/icons/cross.png index 1514d51a3..33a383748 100644 Binary files a/docs/imgs/icons/cross.png and b/docs/imgs/icons/cross.png differ diff --git a/docs/imgs/icons/crosshatch.png b/docs/imgs/icons/crosshatch.png deleted file mode 100644 index 09275f9c0..000000000 Binary files a/docs/imgs/icons/crosshatch.png and /dev/null differ diff --git a/docs/imgs/icons/del.png b/docs/imgs/icons/del.png new file mode 100644 index 000000000..ace289edd Binary files /dev/null and b/docs/imgs/icons/del.png differ diff --git a/docs/imgs/icons/delete.png b/docs/imgs/icons/delete.png deleted file mode 100644 index 08f249365..000000000 Binary files a/docs/imgs/icons/delete.png and /dev/null differ diff --git a/docs/imgs/icons/find.png b/docs/imgs/icons/find.png index 154747964..1d6f4f13f 100644 Binary files a/docs/imgs/icons/find.png and b/docs/imgs/icons/find.png differ diff --git a/docs/imgs/icons/fit_window.png b/docs/imgs/icons/fit_window.png deleted file mode 100644 index 2e9bc42be..000000000 Binary files a/docs/imgs/icons/fit_window.png and /dev/null differ diff --git a/docs/imgs/icons/flag_green.png b/docs/imgs/icons/flag_green.png index e4bc611f8..46bb194e0 100644 Binary files a/docs/imgs/icons/flag_green.png and b/docs/imgs/icons/flag_green.png differ diff --git a/docs/imgs/icons/flip_y.png b/docs/imgs/icons/flip_y.png index e3fb21ea0..9cba2cc49 100644 Binary files a/docs/imgs/icons/flip_y.png and b/docs/imgs/icons/flip_y.png differ diff --git a/docs/imgs/icons/link.png b/docs/imgs/icons/link.png new file mode 100644 index 000000000..c4f00cb22 Binary files /dev/null and b/docs/imgs/icons/link.png differ diff --git a/docs/imgs/icons/new_window.png b/docs/imgs/icons/new_window.png deleted file mode 100644 index 2e945076c..000000000 Binary files a/docs/imgs/icons/new_window.png and /dev/null differ diff --git a/docs/imgs/icons/page_white_code.png b/docs/imgs/icons/page_white_code.png index 0c76bd129..931b0d6a7 100644 Binary files a/docs/imgs/icons/page_white_code.png and b/docs/imgs/icons/page_white_code.png differ diff --git a/docs/imgs/icons/page_white_database.png b/docs/imgs/icons/page_white_database.png index bddba1f98..44b3fd705 100644 Binary files a/docs/imgs/icons/page_white_database.png and b/docs/imgs/icons/page_white_database.png differ diff --git a/docs/imgs/icons/page_white_delete.png b/docs/imgs/icons/page_white_delete.png index af1ecaf29..8fe8138a7 100644 Binary files a/docs/imgs/icons/page_white_delete.png and b/docs/imgs/icons/page_white_delete.png differ diff --git a/docs/imgs/icons/page_white_edit.png b/docs/imgs/icons/page_white_edit.png index b93e77600..8bc294fa6 100644 Binary files a/docs/imgs/icons/page_white_edit.png and b/docs/imgs/icons/page_white_edit.png differ diff --git a/docs/imgs/icons/page_white_link.png b/docs/imgs/icons/page_white_link.png deleted file mode 100644 index bf7bd1c9b..000000000 Binary files a/docs/imgs/icons/page_white_link.png and /dev/null differ diff --git a/docs/imgs/icons/page_white_stack.png b/docs/imgs/icons/page_white_stack.png new file mode 100644 index 000000000..86bc481bc Binary files /dev/null and b/docs/imgs/icons/page_white_stack.png differ diff --git a/docs/imgs/icons/red_x_16.png b/docs/imgs/icons/red_x_16.png deleted file mode 100644 index 8277651a3..000000000 Binary files a/docs/imgs/icons/red_x_16.png and /dev/null differ diff --git a/docs/imgs/icons/runback.png b/docs/imgs/icons/runback.png deleted file mode 100644 index 5dc696781..000000000 Binary files a/docs/imgs/icons/runback.png and /dev/null differ diff --git a/docs/imgs/icons/runcursor.png b/docs/imgs/icons/runcursor.png deleted file mode 100644 index e3e14c5a6..000000000 Binary files a/docs/imgs/icons/runcursor.png and /dev/null differ diff --git a/docs/imgs/icons/runfwd.png b/docs/imgs/icons/runfwd.png deleted file mode 100644 index b1a181923..000000000 Binary files a/docs/imgs/icons/runfwd.png and /dev/null differ diff --git a/docs/imgs/icons/runnaninf.png b/docs/imgs/icons/runnaninf.png deleted file mode 100644 index e99310424..000000000 Binary files a/docs/imgs/icons/runnaninf.png and /dev/null differ diff --git a/docs/imgs/icons/runsample.png b/docs/imgs/icons/runsample.png deleted file mode 100644 index 99d324fca..000000000 Binary files a/docs/imgs/icons/runsample.png and /dev/null differ diff --git a/docs/imgs/icons/save.png b/docs/imgs/icons/save.png index 5ca4d1062..d0d400ec6 100644 Binary files a/docs/imgs/icons/save.png and b/docs/imgs/icons/save.png differ diff --git a/docs/imgs/icons/stepnext.png b/docs/imgs/icons/stepnext.png deleted file mode 100644 index d29136c46..000000000 Binary files a/docs/imgs/icons/stepnext.png and /dev/null differ diff --git a/docs/imgs/icons/stepprev.png b/docs/imgs/icons/stepprev.png deleted file mode 100644 index 24f8bbe29..000000000 Binary files a/docs/imgs/icons/stepprev.png and /dev/null differ diff --git a/docs/imgs/icons/time.png b/docs/imgs/icons/time.png index 911da3f1d..f69c02d13 100644 Binary files a/docs/imgs/icons/time.png and b/docs/imgs/icons/time.png differ diff --git a/docs/imgs/icons/timeline_marker.png b/docs/imgs/icons/timeline_marker.png index a3fbddf88..c2b7480ec 100644 Binary files a/docs/imgs/icons/timeline_marker.png and b/docs/imgs/icons/timeline_marker.png differ diff --git a/docs/imgs/icons/wand.png b/docs/imgs/icons/wand.png index 44ccbf812..1da4964f2 100644 Binary files a/docs/imgs/icons/wand.png and b/docs/imgs/icons/wand.png differ diff --git a/docs/imgs/icons/wrench.png b/docs/imgs/icons/wrench.png index 5c8213fef..7c8cc7a2a 100644 Binary files a/docs/imgs/icons/wrench.png and b/docs/imgs/icons/wrench.png differ diff --git a/docs/imgs/icons/zoom.png b/docs/imgs/icons/zoom.png index 908612e39..3280a45d2 100644 Binary files a/docs/imgs/icons/zoom.png and b/docs/imgs/icons/zoom.png differ diff --git a/docs/imgs/logo.png b/docs/imgs/logo.png index 048b42293..3cb1ed5db 100644 Binary files a/docs/imgs/logo.png and b/docs/imgs/logo.png differ diff --git a/docs/in_application_api.rst b/docs/in_application_api.rst index d06e43741..2cbcea7a6 100644 --- a/docs/in_application_api.rst +++ b/docs/in_application_api.rst @@ -1,7 +1,7 @@ In-application API ================== -Reference for RenderDoc in-application API version 1.1.1 +Reference for RenderDoc in-application API version 1.1.2. This API is not necessary to use RenderDoc by default, but if you would like more control or custom triggering of captures this API can provide the mechanism to do so. Make sure to use a matching API header for your build - if you use a newer header, the API version may not be available. All RenderDoc builds supporting this API ship the header in their root directory. @@ -9,11 +9,11 @@ This page describes the RenderDoc API exposed to applications being captured, bo To begin using the API you need to fetch the ``RENDERDOC_GetAPI`` function. You should do this dynamically, it is not recommended to actually link against RenderDoc's DLL as it's intended to be injected or loaded at runtime. The header does not declare ``RENDERDOC_GetAPI``, it declares a function pointer typedef ``pRENDERDOC_GetAPI`` that you can use. -The two common ways to integrate RenderDoc are either to passively check if the DLL is loaded, and use the API. This lets you continue to use RenderDoc entirely as normal, launching your program through the UI, but you can access additional functionality to e.g. trigger captures at custom times. +There are two common ways to integrate RenderDoc. The first is to passively check if the DLL is loaded, and use the API. This lets you continue to use RenderDoc entirely as normal, launching your program through the UI, but you can access additional functionality to e.g. trigger captures at custom times. To do this you'll use your platforms dynamic library functions to see if the library is open already - e.g. ``GetModuleHandle`` on Windows, or ``dlopen`` with the ``RTLD_NOLOAD`` flag if available on \*nix systems. Just searching for the module name - ``renderdoc.dll`` or ``librenderdoc.so`` is sufficient here, so you don't need to know the path to where RenderDoc is running from. Then you can use ``GetProcAddress`` or ``dlsym`` to fetch the ``RENDERDOC_GetAPI`` function using the typedef above. -The other way is a closer integration, where your code will explicitly load up RenderDoc. This needs more care taken as it can be a bit more complex. You will need to locate the RenderDoc module yourself, and load it as soon as possible after startup of your program. Due to the nature of RenderDoc's API hooking, the earlier you can load it the better in general. Once you've loaded it you can fetch the ``RENDERDOC_GetAPI`` entry point as above, and use the API as normal. +The other way is a closer integration, where your code will explicitly load RenderDoc's library at runtime. This needs more care taken as it can be a bit more complex. You will need to locate the RenderDoc module yourself, and load it as soon as possible after startup of your program. Due to the nature of RenderDoc's API hooking, the earlier you can load it the better in general. Once you've loaded it you can fetch the ``RENDERDOC_GetAPI`` entry point as above, and use the API as normal. .. cpp:function:: int RENDERDOC_GetAPI(RENDERDOC_Version version, void **outAPIPointers) @@ -21,11 +21,31 @@ The other way is a closer integration, where your code will explicitly load up R This function is the only entry point actually exported from the RenderDoc module. You call this function with the desired API version, and pass it the address of a pointer to the appropriate struct type. If successful, RenderDoc will set the pointer to point to a struct containing the function pointers for the API functions (detailed below) and return 1. Note that version numbers follow `semantic versioning `_ which means the implementation returned may have a higher minor and/or patch version than requested. - - :param RENDERDOC_Version version: is the version number of the API for which you want the interface struct. - :param void** outAPIPointers: will be filled with the address of the API's function pointer struct, if supported. E.g. if ``eRENDERDOC_API_Version_1_1_1`` is requested, outAPIPointers will be filled with ``RENDERDOC_API_1_1_1*``. - :return: The function returns 1 if the API version is valid and available, and the struct pointer is filled. The function returns 0 if the API version is invalid or not supported, or the pointer parameter is invalid. + Example code: + + .. highlight:: c++ + .. code:: c++ + + #include "renderdoc_app.h" + + RENDERDOC_API_1_1_2 *rdoc_api = NULL; + + // At init, on windows + if(HMODULE mod = GetModuleHandleA("renderdoc.dll")) + { + pRENDERDOC_GetAPI RENDERDOC_GetAPI = (pRENDERDOC_GetAPI)GetProcAddress(mod, "RENDERDOC_GetAPI"); + int ret = RENDERDOC_GetAPI(eRENDERDOC_API_Version_1_1_2, (void **)&rdoc_api); + assert(ret == 1); + } + + // When you wish to trigger the capture + if(rdoc_api) rdoc_api->TriggerCapture(); + + + :param RENDERDOC_Version version: is the version number of the API for which you want the interface struct. + :param void** outAPIPointers: will be filled with the address of the API's function pointer struct, if supported. E.g. if ``eRENDERDOC_API_Version_1_1_1`` is requested, outAPIPointers will be filled with ``RENDERDOC_API_1_1_1*`` or any newer version that is compatible with API 1.1.1, but nothing lower. + :return: The function returns 1 if the API version is valid and available, and the struct pointer is filled. The function returns 0 if the API version is invalid or not supported, or the pointer parameter is invalid. .. cpp:function:: void GetAPIVersion(int *major, int *minor, int *patch) @@ -56,6 +76,8 @@ The other way is a closer integration, where your code will explicitly load up R .. cpp:enum:: RENDERDOC_CaptureOption + Many values in this enum correspond to options in the :doc:`window/capture_attach` window, so more documentation about their meaning can be found there. Some values here are only available programmatically through this API. + .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_AllowVSync specifies whether the application is allowed to enable vsync. Default is on. @@ -74,15 +96,15 @@ The other way is a closer integration, where your code will explicitly load up R .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureCallstacksOnlyDraws - specifies whether - if `CaptureCallstacks` is enabled - callstacks are only saved on drawcalls. Default is off. + specifies whether - if ``CaptureCallstacks`` is enabled - callstacks are only saved on drawcalls. Default is off. .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DelayForDebugger - specifies a delay in seconds after launching a process to pause, to allow debuggers to attach. Default is 0. + specifies a delay in seconds after launching a process to pause, to allow debuggers to attach. This will only apply to child processes since the delay happens at process startup. Default is 0. .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_VerifyMapWrites - specifies whether any 'map' type resource memory updates should be bounds-checked for overruns. Default is off. + specifies whether any mapped memory updates should be bounds-checked for overruns. Only supported on D3D11 and OpenGL. Default is off. .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_HookIntoChildren @@ -90,7 +112,7 @@ The other way is a closer integration, where your code will explicitly load up R .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_RefAllResources - specifies whether all live resources at the time of capture should be included in the log, even if they are not referenced by the frame. Default is off. + specifies whether all live resources at the time of capture should be included in the capture, even if they are not referenced by the frame. Default is off. .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_SaveAllInitials @@ -98,11 +120,11 @@ The other way is a closer integration, where your code will explicitly load up R .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureAllCmdLists - specifies whether all command lists should be captured on APIs where multithreaded submission is not optimal such as D3D11, rather than only capturing those submitted during the frame. Default is off. + specifies whether all command lists should be captured on D3D11 where multithreaded submission is not optimal, rather than only capturing those recorded after frame capture begins. Default is off. .. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugOutputMute - specifies whether to mute any API debug output messages when `APIValidation` is enabled. Default is on. + specifies whether to mute any API debug output messages when `APIValidation` is enabled, and not pass them along to the application. Default is on. .. cpp:function:: uint32_t GetCaptureOptionU32(RENDERDOC_CaptureOption opt) @@ -123,7 +145,7 @@ The other way is a closer integration, where your code will explicitly load up R This function changes the key bindings in-application for changing the focussed window. - :param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is NULL, ``num`` must be 0. + :param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is ``NULL``, ``num`` must be 0. :param int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled. .. cpp:enum:: RENDERDOC_InputButton @@ -201,7 +223,7 @@ The other way is a closer integration, where your code will explicitly load up R This function changes the key bindings in-application for triggering a capture on the current window. - :param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is NULL, ``num`` must be 0. + :param RENDERDOC_InputButton* keys: lists the keys to bind. If this parameter is ``NULL``, ``num`` must be 0. :param int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled. .. cpp:function:: uint32_t GetOverlayBits() @@ -234,11 +256,11 @@ The other way is a closer integration, where your code will explicitly load up R .. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_All - is equal to `~0U` so all bits are enabled. + is equal to ``~0U`` so all bits are enabled. .. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_None - is equal to `0` so all bits are disabled. + is equal to ``0`` so all bits are disabled. .. cpp:function:: void MaskOverlayBits(uint32_t And, uint32_t Or) @@ -255,31 +277,39 @@ The other way is a closer integration, where your code will explicitly load up R This function will remove RenderDoc's crash handler from the target process. If you have your own crash handler that you want to handle any exceptions, RenderDoc's handler could interfere so it can be disabled. -.. cpp:function:: void SetLogFilePathTemplate(const char *pathtemplate) +.. cpp:function:: void SetCaptureFilePathTemplate(const char *pathtemplate) Set the template for new captures. The template can either be a relative or absolute path, which determines where captures will be saved and how they will be named. If the path template is ``my_captures/example`` then captures saved will be e.g. ``my_captures/example_frame123.rdc`` and ``my_captures/example_frame456.rdc``. Relative paths will be saved relative to the process's current working directory. The default template is in a folder controlled by the UI - initially the system temporary folder, and the filename is the executable's filename. :param const char* pathtemplate: specifies the capture path template to set, as UTF-8 null-terminated string. -.. cpp:function:: const char *GetLogFilePathTemplate() +.. note:: - Get the current log file path template. + This function was renamed, in earlier versions of the API it was declared as ``SetLogFilePathTemplate``. This rename is backwards compatible as the function signature did not change. + +.. cpp:function:: const char *GetCaptureFilePathTemplate() + + Get the current capture path template, see :cpp:func:`SetCaptureFilePathTemplate`. :return: the current capture path template as a UTF-8 null-terminated string. +.. note:: + + This function was renamed, in earlier versions of the API it was declared as ``GetLogFilePathTemplate``. This rename is backwards compatible as the function signature did not change. + .. cpp:function:: uint32_t GetNumCaptures() This function returns the number of frame captures that have been made. :return: the number of frame captures that have been made -.. cpp:function:: uint32_t GetCapture(uint32_t idx, char *logfile, uint32_t *pathlength, uint64_t *timestamp) +.. cpp:function:: uint32_t GetCapture(uint32_t idx, char *filename, uint32_t *pathlength, uint64_t *timestamp) This function returns the details of a particular frame capture, as specified by an index from 0 to :cpp:func:`GetNumCaptures` - 1. :param uint32_t idx: specifies which capture to return the details of. Must be less than the return value of :cpp:func:`GetNumCaptures`. - :param char* logfile: is an optional parameter filled with the UTF-8 null-terminated path to the file. There must be enough space in the array to contain all characters including the null terminator. If set to NULL, nothing is written. - :param uint32_t* pathlength: is an optional parameter filled with the byte length of the above `logfile` including the null-terminator. If set to NULL, nothing is written. + :param char* filename: is an optional parameter filled with the UTF-8 null-terminated path to the file. There must be enough space in the array to contain all characters including the null terminator. If set to NULL, nothing is written. + :param uint32_t* pathlength: is an optional parameter filled with the byte length of the above `filename` including the null terminator. If set to NULL, nothing is written. :param uint64_t* timestamp: is an optional parameter filled with the 64-bit timestamp of the file - equivalent to the `time()` system call. If set to NULL, nothing is written. :return: Returns ``1`` if the capture index was valid, or ``0`` if it was out of range. @@ -300,6 +330,10 @@ The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it ma :return: Returns ``1`` if the RenderDoc UI is currently connected, or ``0`` otherwise. +.. note:: + + This function was renamed, in earlier versions of the API it was declared as ``IsRemoteAccessConnected``. This rename is backwards compatible as the function signature did not change. + .. cpp:function:: uint32_t LaunchReplayUI(uint32_t connectTargetControl, const char *cmdline) This function will determine the closest matching replay UI executable for the current RenderDoc module and launch it. @@ -329,19 +363,19 @@ The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it ma This function will immediately begin a capture for the specified device/window combination. - :param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be NULL to wildcard match. - :param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. May be NULL to wildcard match. + :param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. May be ``NULL`` to wildcard match. + :param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. May be ``NULL`` to wildcard match. .. note:: ``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`. - ``device`` and ``wndHandle`` can either or both be set to NULL to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. + ``device`` and ``wndHandle`` can either or both be set to ``NULL`` to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. - For example if ``device`` is NULL but ``wndHandle`` is set, RenderDoc will begin a capture on the first API it finds that is active on that window. + For example if ``device`` is ``NULL`` but ``wndHandle`` is set, RenderDoc will begin a capture on the first API it finds that is active on that window. If the wildcard match has multiple possible candidates, it is not defined which will be chosen. Wildcard matching should only be used when e.g. it is known that only one API is active on a window, or there is only one window active for a given API. - If no window has been created and all rendering is off-screen, NULL can be specified for the window handle and the device object can be passed to select that API. If both are set to NULL, RenderDoc will simply choose one at random so is only recommended for the case where only one is present. + If no window has been created and all rendering is off-screen, ``NULL`` can be specified for the window handle and the device object can be passed to select that API. If both are set to ``NULL``, RenderDoc will simply choose one at random so is only recommended for the case where only one is present. .. cpp:function:: uint32_t IsFrameCapturing() @@ -359,7 +393,7 @@ The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it ma .. note:: ``RENDERDOC_DevicePointer`` and ``RENDERDOC_WindowHandle`` are described above in :cpp:func:`SetActiveWindow`. - ``device`` and ``wndHandle`` can either or both be set to NULL to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. + ``device`` and ``wndHandle`` can either or both be set to ``NULL`` to wildcard match against active device/window combinations. This wildcard matching can be used if the handle is difficult to obtain where frame captures are triggered. Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`BeginFrameCapture`. @@ -369,4 +403,6 @@ The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it ma This function will trigger multiple sequential frame captures as if the user had pressed one of the capture hotkeys before each frame. The captures will be taken from the next frames presented to whichever window is considered current. + Each capture will be taken independently and saved to a separate file, with no reference to the other frames. + :param uint32_t numFrames: the number of frames to capture, as an unsigned integer. diff --git a/docs/include/intro_header_inc.rst b/docs/include/intro_header_inc.rst new file mode 100644 index 000000000..9bd67ea92 --- /dev/null +++ b/docs/include/intro_header_inc.rst @@ -0,0 +1,8 @@ +.. image:: imgs/logo.png + :align: center + +Welcome to RenderDoc - a graphics debugger currently available for Vulkan, D3D11, D3D12, OpenGL, and OpenGL ES development on Windows, Linux and Android. + +This document serves as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them. + +The latest information and discussion is always available on the `GitHub repository `_. diff --git a/docs/index.rst b/docs/index.rst index 3003e71d2..27cece2f3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,7 @@ RenderDoc ========= -.. |renderdoc_logo| image:: imgs/logo.png - -|renderdoc_logo| - -Welcome to RenderDoc - a graphics debugger currently available for Vulkan, D3D11, D3D12, and OpenGL development on windows. - -This document serves primarily as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them. - -The latest information and discussion is always available on the `GitHub wiki `_. +.. include:: include/intro_header_inc.rst Table of Contents ================= @@ -18,10 +10,10 @@ Table of Contents :maxdepth: 2 introduction - in_application_api credits_acknowledgements - python_api/index getting_started/index behind_scenes/index + in_application_api + python_api/index how/index window/index diff --git a/docs/introduction.rst b/docs/introduction.rst index 2a5a15e09..cbcde275c 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1,20 +1,12 @@ Introduction ============ -.. |renderdoc_logo| image:: imgs/logo.png - -|renderdoc_logo| - -Welcome to RenderDoc - a graphics debugger currently available for Vulkan, D3D11, D3D12, and OpenGL development on windows. - -This document serves primarily as reference guide, introductory document and explanation of which features are available in RenderDoc and how to best use them. - -The latest information and discussion is always available on the `GitHub wiki `_. +.. include:: include/intro_header_inc.rst License ------- -RenderDoc is released under the MIT license, so there are no restrictions on your use of it either commercial or non-commercial. This includes the source release available on `GitHub `_. +RenderDoc is released under the MIT license, so there are no restrictions on your use of it either commercially or non-commercially. This includes the source release available on `GitHub `_. Details of the licenses of third party software used in RenderDoc are included in the LICENSE file in the RenderDoc directory as well as in the :doc:`credits_acknowledgements`. @@ -47,7 +39,7 @@ Contact info, Feedback, Bug reports If you want to get in touch with any feature requests, suggestions, comments etc then feel free to contact me: `Contact me `_. -Bug reports can be submitted directly via email, or also on the `GitHub issues list `_ where you can also find the full source code. +Bug reports can be submitted directly `via email `_, or also on the `GitHub issues list `_ where you can also find the full source code. The `Builds page `_ always has the latest stable build downloads, as well as builds made from the source code each night for the bleeding edge. Stable releases update every month or so and are the typical releases to stick to for the most reliable experience. diff --git a/docs/python_api/index.rst b/docs/python_api/index.rst index a0c4f856c..47999586b 100644 --- a/docs/python_api/index.rst +++ b/docs/python_api/index.rst @@ -3,7 +3,7 @@ Python API The python API is accessible via scripting in the QRenderDoc tool. This gives access to both the base replay API that the UI is built on top of, as well as scripting ability for the UI itself and some higher level utility functionality. -It is also possible to build a standalone module of just the base API which can be loaded into python and used for scripting directly without the UI. Due to the inherent difficulty of distributing C python modules this isn't included by default in distributed builds at the time of writing, but is generated by default in source builds - ``renderdoc.py`` and ``_renderdoc.dll`` or ``_renderdoc.so`` make up this module. +It is also possible to build a standalone module of just the base API which can be loaded into python and used for scripting directly without the UI. Due to the inherent difficulty of distributing C python modules this isn't included by default in distributed builds at the time of writing, but is generated by default in source builds - ``renderdoc.pyd`` on windows or ``renderdoc.so`` elsewhere. .. toctree:: base/index diff --git a/docs/renderdoc.hhk b/docs/renderdoc.hhk index 867ae82cd..95ee1c95d 100644 --- a/docs/renderdoc.hhk +++ b/docs/renderdoc.hhk @@ -21,11 +21,11 @@
  • - +
  • - +
  • @@ -45,7 +45,7 @@
  • - + @@ -87,7 +87,7 @@
  • - +
  • @@ -104,7 +104,7 @@
  • - +
  • @@ -130,10 +130,6 @@ -
  • - - -
  • @@ -208,8 +204,8 @@
  • - - + +
  • @@ -225,7 +221,7 @@
  • - +
  • @@ -257,7 +253,7 @@
  • - +
  • @@ -339,8 +335,8 @@
  • - - + +
  • @@ -355,8 +351,8 @@
  • - - + +
  • diff --git a/docs/window/api_inspector.rst b/docs/window/api_inspector.rst index a971e5be0..98b14bf88 100644 --- a/docs/window/api_inspector.rst +++ b/docs/window/api_inspector.rst @@ -8,7 +8,7 @@ UI Elements The API Inspector is divided into two sections - the top section is the most common, detailing all of the API calls leading up to and including the current drawcall. The special case for this is the end of the frame where there may not be a final drawcall but the API Inspector lists the API calls that preceded the final flip of the backbuffer that marks the end of RenderDoc's captured frame. -The bottom section is less common but shows the callstack from user code into the API entry point, if such a callstack is available and the symbols are resolved. For more information check out the page on :doc:`../how/how_capture_callstack`. +The bottom section is less commonly used but shows the callstack from user code into the API entry point, if such a callstack is available and the symbols are resolved. For more information check out the page on :doc:`../how/how_capture_callstack`. API Calls --------- diff --git a/docs/window/buffer_viewer.rst b/docs/window/buffer_viewer.rst index 933dcf586..3f8d6d12e 100644 --- a/docs/window/buffer_viewer.rst +++ b/docs/window/buffer_viewer.rst @@ -1,7 +1,7 @@ Buffer Viewer/Mesh Output ========================= -The buffer viewer has two reasonably distinct modes - the first rather specialised to show meshes and mesh data as it passes through the pipeline. The other shows a raw arbitrary buffer with a custom (and arbitrary) formatting. +The buffer viewer has two reasonably distinct modes - the first rather specialised to show meshes and the mesh data as it passes through the pipeline. The other shows a raw arbitrary buffer with a custom (and arbitrary) formatting. Mesh Viewer ----------- @@ -10,9 +10,9 @@ The Mesh Viewer shows both the mesh data as well as a visual representation of t .. |arrow_join| image:: ../imgs/icons/arrow_join.png -Each distinct point has a display that shows the mesh data, the format of which is pulled from the relevant stage of the pipeline - shader input or output, or input layout. You can choose to sync these views |arrow_join| as well as specify an offset which will stay consistent, so that you can see the same row as you move between different events. +Each vertex has a display that shows the mesh data, the format of which is pulled from the relevant stage of the pipeline - shader input or output, or vertex input attributes. You can choose to sync these views |arrow_join| as well as specify an offset which will stay consistent, so that you can see the same row as you move between different events. -Below this is a 3D view which will show one stage at any given time, and can be switched with the tabs above it. There are two control schemes for viewing the 3D mesh - Arcball which is the default for pre-transform (VS in), and WASD controls which is the default for post-transform (VS out). You can switch between these at any time with the dropdown on the toolbar above the mesh view. +Below this is a 3D view which will show one stage at any given time, and can be switched with the tabs above it. There are two control schemes for viewing the 3D mesh - Arcball which is the default for pre-transform (VS input), and WASD controls which is the default for post-transform (VS output). You can switch between these at any time with the dropdown on the toolbar above the mesh view. .. note:: @@ -45,11 +45,11 @@ Mesh Preview In the 3D Mesh preview, you have the option to display the mesh with some solid shading modes, not just as a wireframe mesh. When solid shading you can toggle the wireframe on and off. -* Solid Colour simply displays a solid colour for each triangle. +* Solid Color simply displays a solid color for each triangle. * Flat Shaded will perform basic flat lighting calculations based on triangle normals to give a better idea of the topology of the mesh. * Secondary will display the selected secondary mesh element. -To select which element will be displayed as secondary, simply right click on the column you would like to use. This can be done on the input and output separately, and 4-component columns have the option to either show RGB as colour, or alpha as greyscale. +To select which element will be displayed as secondary, simply right click on the column you would like to use. This can be done on the input and output separately, and 4-component columns have the option to either show RGB as color, or alpha as greyscale. The selection will be remembered as long as the mesh format stays consistent between draws. @@ -57,15 +57,15 @@ You can also use this if the position data isn't detected in your inputs and you .. figure:: ../imgs/Screenshots/SolidPreview.png - Preview: Previewing the uv co-ordinates as colour on the mesh. + Preview: Previewing the uv co-ordinates as color on the mesh. When displaying the post-projection output - typically the VS output, but possibly tessellation/geometry output - you can select how much data to display. -The dropdown above the mesh view will let you choose ``Only this draw``, ``Show previous instances``, ``Show all instances``, or ``Show whole pass``. +The dropdown above the mesh view will let you choose to show :guilabel:`this draw`, :guilabel:`previous instances` as well, :guilabel:`all instances` in the drawcall, or the :guilabel:`whole pass` up to this point. These let you narrow or expand the mesh outputs displayed. At minimum you will see the current draw - a specific instance, if the drawcall is an instanced draw. You can also display other instances in the same drawcall (either up to the selected instance, or all instances before or after the selected instance). Finally you can opt to display all other meshes up to the current draw in the same notional render pass. -The current draw is always dark tinted, instances within the same draw have a lighter red colour, and other drawcalls in the pass will be light grey. +The current draw is always dark tinted, instances within the same draw have a lighter red color, and other drawcalls in the pass will be light grey. Raw Buffer Viewer ----------------- diff --git a/docs/window/capture_log_attach.rst b/docs/window/capture_attach.rst similarity index 65% rename from docs/window/capture_log_attach.rst rename to docs/window/capture_attach.rst index f2beaa2ae..b56471c48 100644 --- a/docs/window/capture_log_attach.rst +++ b/docs/window/capture_attach.rst @@ -1,28 +1,28 @@ -Capture Log & Attach -==================== +Launching & Attaching to Programs +================================= -The Capture Dialog (which doubles as the inject-into-process dialog) is the single point where programs are launched and logfiles are captured to disk. +The Capture Dialog (which doubles as the inject-into-process dialog) is the single point where programs are launched and captures are saved to disk. After launching a capture a connection dialog will open to allow you to manage and open any captures you take. See :doc:`capture_connection` for more details. .. note:: - NOTE: The Load Settings and Save Settings buttons on this dialog refer to loading and saving the set of settings and options configured on this dialog. They do *not* refer to loading and saving the logs produced from capturing - that is done from the File menu. + NOTE: The Load Settings and Save Settings buttons on this dialog refer to loading and saving the set of settings and options configured on this dialog. They do *not* refer to loading and saving the logs produced from capturing - that is done from the :guilabel:`File` menu. Capturing --------- -To capture a program you simply need to provide the details of the application to be launched. +To capture a program you need to provide the details of the application to be launched, at minimum locating the executable to run. -The Program section of the dialog prompts for the executable to be launched, the working directory, any command-line arguments to be passed to the program, and any modifications to the environment to make. +The Program section of the dialog prompts for the executable to be launched, the working directory, any command-line arguments to be passed to the program. It also lets you specify any modifications you want to make to the environment variables. .. figure:: ../imgs/Screenshots/CapturePathCmdline.png Program Capture: Configuring and launching an exe directly from RenderDoc. -The ``...`` buttons next to the executable path and working directory can be used to browse through the file system. If you are working in :doc:`a remote context <../how/how_network_capture_replay>` then the file and directory browser will be replaced by one that browses in the file system of the remote context. By default if the working directory box is left empty then the directory containing the executable will be used as the working directory. +The :guilabel:`...` buttons next to the executable path and working directory can be used to browse through the file system. If you are working in :doc:`a remote context <../how/how_network_capture_replay>` then the file and directory browser will be replaced by one that browses in the file system of the remote context. By default if the working directory box is left empty then the directory containing the executable will be used as the working directory. -The ``...`` button next to the environment variables line will open up a custom editor that allows you to specify any changes to the environment varibales that you'd like to make when launching the program. This could be used for example to set a configuration option, or perform necessary setup for correct running like configuring a path or setting the ``DISPLAY`` variable. +The :guilabel:`...` button next to the environment variables line will open up an editing that allows you to specify any changes to the environment variables that you'd like to make when launching the program. This could be used for example to set a configuration option, or perform necessary setup for correct running like configuring a path or setting the ``DISPLAY`` variable. .. figure:: ../imgs/Screenshots/CaptureEnvVarEditor.png @@ -30,13 +30,14 @@ The ``...`` button next to the environment variables line will open up a custom In the environment variable editor you can choose the name of the variable to change, and the value to use. Then you can choose the function to use. -* ``Set`` will overwrite any existing value or create the variable with the value you specify. -* ``Prepend`` and ``Append`` will add the value you specify to the start or beginning of the existing variable. If the variable does not already exist it will be created with the value. - When prepending or appending you can also choose the separator to apply, for example if you are modifying the ``PATH`` variable. You can choose either colons (``:``), semi-colons (``;``), platform style (``;`` on windows and ``:`` on other platforms), or no separator at all. If the variable does not exist, the separator won't be added, but if the variable does exist the separator will be added in between the existing value and the value you chose to add. +* :guilabel:`Set` will overwrite any existing value or create the variable with the value you specify. +* :guilabel:`Prepend Value` and :guilabel:`Append Value` will add the value you specify to the start or beginning of the existing variable. If the variable does not already exist it will be created with the value. -When you are ready to capture simply click the ``Capture`` button in the bottom right. + When prepending or appending you can also choose the separator to apply, for example if you are modifying the ``PATH`` variable. You can choose either colons ( ``:``), semi-colons ( ``;``), platform style ( ``;`` on Windows and ``:`` on other platforms), or no separator at all. If the variable does not exist, the separator won't be added, but if the variable does exist the separator will be added in between the existing value and the value you chose to add. -If you wish to save these particular settings you can click ``Save`` to save them to a ``.cap`` file. This ``.cap`` file can either be loaded in manually, accessed through the ``Recent Captures`` menu. The ``.cap`` file can be associated with RenderDoc, and if so launching RenderDoc from this file will automatically load the capture settings. If "Auto start" is checked then double clicking on the ``.cap`` file will immediately trigger a capture with the given settings. +When you are ready to capture simply click the :guilabel:`Capture` button in the bottom right. + +If you wish to save these particular settings you can click :guilabel:`Save Settings` to save them to a ``.cap`` file. This ``.cap`` file can either be loaded in manually, accessed through the :guilabel:`File` → :guilabel:`Recent Captures` menu. The ``.cap`` file can be associated with RenderDoc, and if so launching RenderDoc from this file will automatically load the capture settings. If :guilabel:`Auto start` is checked then double clicking on the ``.cap`` file will immediately trigger a capture with the given settings. .. note:: The process will be launched with the same permissions and by the same user as RenderDoc was launched. If your process requires specific permissions (such as administrator permissions) you will need to launch RenderDoc with these permissions. @@ -47,9 +48,9 @@ Inject into Process .. caution:: The process **must not** have invoked or initialised the API to be used, as this will be too late for RenderDoc to hook and capture it. At best RenderDoc will not capture, at worst it may cause crashes or undefined behaviour. Only inject to processes you can guarantee are early enough in their initialisation that they have not used the graphics API. -When invoked through ``Inject into Process`` the capture dialog modifies itself to give a list of processes running on the target system. +When invoked through :guilabel:`File` → :guilabel:`Inject into Process` the capture dialog modifies itself to give a list of processes running on the target system. -A list of processes is fetched once when the dialog is opened, but this can be refreshed by clicking on the refresh button below the list. Select the process you would like to inject into and click Inject. +A list of processes is fetched once when the dialog is opened, but this can be refreshed by clicking on the :guilabel:`Refresh` button below the list. Select the process you would like to inject into and click :guilabel:`Inject`. .. figure:: ../imgs/Screenshots/Injecting.png @@ -58,7 +59,7 @@ A list of processes is fetched once when the dialog is opened, but this can be r Capture Options --------------- - | ``Allow Fullscreen`` Default: ``Enabled`` + | :guilabel:`Allow Fullscreen` Default: ``Enabled`` Allow Fullscreen simply means that RenderDoc will not interfere with any attempt by the application to switch into an exclusive fullscreen video mode. While debugging sometimes this can be awkward as you may wish to quickly switch to your debugger or another program. @@ -66,13 +67,13 @@ If this option is unchecked, RenderDoc will attempt to modify any such attempt t ---------- - | ``Allow VSync`` Default: ``Enabled`` + | :guilabel:`Allow VSync` Default: ``Enabled`` Allow VSync functions very similarly to Allow Fullscreen. When disabled, RenderDoc will prevent any attempt to VSync by the application. This can be useful given that there is a certain degree of inevitable overhead from running with RenderDoc and VSync can amplify that. ---------- - | ``Seconds Delay`` Default: ``0 Seconds (Disabled)`` + | :guilabel:`Seconds Delay` Default: ``0 Seconds (Disabled)`` This option causes RenderDoc to stall for a defined number of seconds immediately after launching the process. Most commonly this is used so that you can launch a program in RenderDoc and immediately attach a traditional debugger before any significant code is executed. @@ -80,67 +81,65 @@ This can be useful e.g. when early initialisation needs to be debugged. ---------- - | ``Collect Callstacks`` Default: ``Disabled`` + | :guilabel:`Collect Callstacks` Default: ``Disabled`` This option will cause RenderDoc to save a callstack from user code into the API at every API call during the frame being captured. This can then be resolved later and used to determine where the application is calling each API call. More details can be found in :doc:`../how/how_capture_callstack`. ---------- - | ``Only Drawcall Callstacks`` Default: ``Disabled`` + | :guilabel:`Only Drawcall Callstacks` Default: ``Disabled`` This option modifies the above capturing of callstacks to only be saved for drawcall-type API calls. This can reduce the CPU load, as well as file-size and memory overhead of capturing callstacks for every API call which may not be desired. Only valid if ``Collect Callstacks`` is enabled. ---------- - | ``Enable API validation`` Default: ``Disabled`` + | :guilabel:`Enable API validation` Default: ``Disabled`` Enable API validation causes RenderDoc to enable the API's built-in debugging, and where possible serialise this out and include it in the logfile for later inspection in the :doc:`debug_messages` window. -* On D3D11 this will activate the D3D debug layer and save out any messages. +* On D3D11 & D3D12 this will activate the D3D debug layer and save out any messages. * For OpenGL this means ``ARB_debug_output`` is automatically enabled. * For Vulkan the ``VK_LAYER_LUNARG_standard_validation`` meta-layer is enabled and ``VK_EXT_debug_report`` is used to fetch any warnings or errors. The overhead from enabling this option is largely the same as the overhead of enabling the debug device without RenderDoc involved. ---------- - | ``Hook into Children`` Default: ``Disabled`` + | :guilabel:`Capture Child Processes` Default: ``Disabled`` -This option causes RenderDoc to hook into CreateProcess and intercept any calls to it from the target application. When this option is enabled those child processes will be injected with RenderDoc in the same way as the parent - which can be useful if you must launch your program through a launcher or level of indirection and still wish to use RenderDoc with one of the child processes. +This option causes RenderDoc to hook into process creation calls from the target application. When this option is enabled those child processes will be injected with RenderDoc in the same way as the parent - which can be useful if you must launch your program through a launcher or level of indirection and still wish to use RenderDoc with one of the child processes. -See below for more information on handling of child processes. +:ref:`See below ` for more information on handling of child processes. + +.. note:: + Due to the hook implementation on linux, child processes will always be hooked regardless of whether this option is enabled or disabled. ---------- - | ``Save All Initials`` Default: ``Disabled`` + | :guilabel:`Save All Initials` Default: ``Disabled`` -RenderDoc will attempt to save overhead and particularly logfile size by omitting the initial contents of 2D textures that it believes will be unnecessary. Typically these textures are render targets or depth buffers that will be written to and fully covered in the course of the frame before they are ever read, and so saving their initial contents is unnecessary. +RenderDoc will attempt to save overhead and particularly capture filesize by omitting the initial contents of 2D textures that it believes will be unnecessary. Typically these textures are render targets or depth buffers that will be written to and fully covered in the course of the frame before they are ever read, and so saving their initial contents is unnecessary. In some cases this detection will be wrong, such as targets that are partially written such as pools, or if a target is accumulated to via blend modes. When this is the case, enabling Save All Initials will force RenderDoc to save these textures regardless of any auto-detection. ---------- - | ``Ref All Resources`` Default: ``Disabled`` + | :guilabel:`Ref All Resources` Default: ``Disabled`` One method RenderDoc uses to keep logfile sizes down is to only include the referenced dependencies of a frame within a capture. This means that even if 100 textures are allocated and present, if 50 of them are never bound to the pipeline or otherwise referenced then they will not be included in the logfile. Enabling this option will cause RenderDoc to include all live resources at the time of capture regardless of whether they are used or not. ---------- - | ``Capture All Cmd Lists`` Default: ``Disabled`` + | :guilabel:`Capture All Cmd Lists` Default: ``Disabled`` + +.. note:: + This option applies to D3D11 only. It may also have a significant performance hit. By default RenderDoc only begins capturing when you hit the capture key - any commands issued before this point are not available and so if a deferred command list was created before you hit capture and replayed after, it would not be available and RenderDoc would have to fall back and capture again in the hopes that next frame everything will be available. If the application creates a command list early and replays it indefinitely without recreating it, RenderDoc will essentially have missed its chance to capture it by the time you hit the capture key. Enabling this option will cause RenderDoc to pre-emptively capture all command lists just in case they are used. -.. note:: - This option has no effect on Vulkan - all command buffers are always captured. - -.. caution:: - This may have a significant performance hit on APIs with poor multithreading such as D3D11. - -.. - ---------- - | ``Verify Map() Writes`` Default: ``Disabled`` + | :guilabel:`Verify Map() Writes` Default: ``Disabled`` This option adds checking to any ``Map()`` calls that adds a boundary marker after any ``Map()`` pointer returned during a captured frame. These markers are checked on ``Unmap()`` and if they have been modified a message box will pop up alerting you to this, and you can click Yes to break in the debugger in the target application and investigate the problem. @@ -148,11 +147,13 @@ Note this is only supported on D3D11 and OpenGL currently, since Vulkan and D3D1 ---------- - | ``Auto start`` Default: ``Disabled`` + | :guilabel:`Auto start` Default: ``Disabled`` This option is slightly different from the others in that it doesn't change anything for an immediate capture. When a ``.cap`` settings file is saved with the details of a particular capture, if this option is enabled then loading a ``.cap`` file from the command line (i.e. most commonly from a file association) will trigger a capture as soon as RenderDoc loads. This is useful for saving a common capture setting and running it with just one click. - | ``Queue Capture of Frame`` Default: ``Disabled`` +---------- + + | :guilabel:`Queue Capture of Frame` Default: ``Disabled`` This option allows you to queue up a precise capture of a given frame number after the program has started. @@ -161,7 +162,7 @@ This option allows you to queue up a precise capture of a given frame number aft Child Processes --------------- -RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check "Hook into Children" in the options above. +RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check :guilabel:`Capture Child Processes` in the options above. RenderDoc has a particular handling of child processes to help you navigate to the process of interest. Whenever a child process is launched, the UI is notified and a list of processes is displayed in a box on the :doc:`capture_connection` window. You can double click on any of these entries to open up a new connection to that process, in a new window. @@ -176,7 +177,9 @@ Global Process Hook This option is risky and should not be used lightly. Know what you're doing and use it as a last resort. -To expose this option you have to enable it in :doc:`the settings `, to prevent it being used accidentally. + It is only supported on Windows currently. + +To expose this option you have to enable it in :doc:`the settings `, to prevent it being used accidentally. When you've entered a path, or filename, in the executable text at the top of the window, this option will then insert a global hook that causes **every** new process created to load a very small shim dll. @@ -197,5 +200,5 @@ See Also * :doc:`../getting_started/quick_start` * :doc:`../how/how_capture_callstack` -* :doc:`../how/how_capture_log` +* :doc:`../how/how_capture_frame` * :doc:`../how/how_network_capture_replay` diff --git a/docs/window/capture_comments.rst b/docs/window/capture_comments.rst new file mode 100644 index 000000000..6f42aaa14 --- /dev/null +++ b/docs/window/capture_comments.rst @@ -0,0 +1,8 @@ +Capture Comments +================ + +.. figure:: ../imgs/Screenshots/capture_comments.png + + Capture Comments: Adding free-form text notes to be saved with a capture + +The capture comments panel allows for adding arbitrary comments to a capture. This is mostly used for :doc:`annotating a capture <../how/how_annotate_capture>` since the comments written here will be available to anyone loading the capture. It's also a useful to permanently store the build or machine configuration where the capture was created. diff --git a/docs/window/capture_connection.rst b/docs/window/capture_connection.rst index e3e21fddb..9a8ccb042 100644 --- a/docs/window/capture_connection.rst +++ b/docs/window/capture_connection.rst @@ -1,18 +1,18 @@ Capture Connection ================== -The Live capture window opens up when you launch a capture of a program, as well as when you attach to an existing program. +The capture connection window opens up when you launch a capture of a program, as well as when you attach to an existing program. Attaching to an existing instance --------------------------------- -After you've launched a program through RenderDoc and its hooks are added you can freely disconnect (by closing the live capture window) or close the main UI. You can then connect to this again later, either from the same computer or another computer connecting over the network. For more information, see the page about :doc:`network capture and replay <../how/how_network_capture_replay>`. +After you've launched a program through RenderDoc and its hooks are added you can freely disconnect (by closing the capture connection window) or close the main UI. You can then connect to this again later, either from the same computer or another computer connecting over the network. For more information, see the page about :doc:`network capture and replay <../how/how_network_capture_replay>`. -To connect to an existing hooked program, select Attach to Running Instance from the File menu. This opens up the remote host management window that allows you to select a remote host to connect to. localhost is always in the list, but you can add and remove other hosts. +To connect to an existing hooked program, select :guilabel:`File` → :guilabel:`Attach to Running Instance`. This opens up the remote host management window that allows you to select a remote host to connect to. localhost is always in the list, but you can add and remove other hosts. .. warning:: - Please note that none of the connections RenderDoc makes or uses are encrypted or authenticated/protected, so if this is a concern you should look into securing the connections by hand. + Please note that none of the connections RenderDoc makes or uses are encrypted or authenticated/protected, so if this is a concern you should look into securing the connections manually. .. figure:: ../imgs/Screenshots/RemoteHostManager.png @@ -22,18 +22,18 @@ When the window opens, when you add a new host, or when you click refresh then t Once a host has been scanned, if any instances are found then that host can be expanded to see the list, and details are listed about each instance. The name is OS-dependent but is usually the executable name. The API name is listed, as well as the username of any user that is already connected. -When you click connect, a live capture window will be opened up - just the same as the window that is automatically opened when you start a program. Any captures that have already been made before you connect will then populate. +When you click connect, a capture connection window will be opened up - just the same as the window that is automatically opened when you start a program. Any captures that have already been made before you connect will then populate. .. note:: - If you connect to a running instance, any existing user will be kicked off. Just seeing the instances running on a host will not. + If you connect to a running instance, any existing user will be disconnected. Just seeing the instances running on a host will not. For more information about specifically a network capture-and-replay workflow, please see :doc:`../how/how_network_capture_replay`. Capture Connection window ------------------------- -When a capture is launched (or attached to) the connection window is opened in the main UI. If you end up only taking one capture and closing the program afterwards the connection window will automatically close - likewise if you take no captures at all. These cases don't need the management options the connection window provides. +When a capture is launched (or attached to) the connection window is opened in the main UI. If you end up only taking one capture and closing the program afterwards the connection window will automatically close and open that capture. Similarly if you don't take any captures at all the window will close when the program exits. These cases don't need the management options the connection window provides. While a program is running, a couple of tools are available for triggering specific captures, which can be used as well as the keystroke capture triggers in the application. @@ -41,9 +41,9 @@ While a program is running, a couple of tools are available for triggering speci Connection Window: Tools for triggering specific frame captures. -Firstly you can trigger a capture, with an optional delay in seconds, and for an arbitrary number of frames. When you click ``Trigger Capture`` the delay will count down, and then the application will capture the selected number of sequential frames into separate captures. By default the delay is 0 seconds and only one frame is captured. +Firstly you can trigger a capture, with an optional delay in seconds, and for an arbitrary number of frames. When you click :guilabel:`Trigger Capture` the delay will count down, and then the application will capture the selected number of sequential frames into separate captures. By default the delay is 0 seconds and only one frame is captured. -Next you can trigger a specific frame number, if you know that a bug will happen at a given point. +Next you can queue a capture at a specific frame number, if you know that a bug will happen at a given point. .. note:: @@ -55,7 +55,7 @@ During running or after the application has closed, all captures will appear as Connection Window: Viewing multiple captures taken in a program. -In this example we have a connection window open to the CascadedShadowMaps11 sample from the DirectX SDK. Two captures have been made and we can see their thumbnails to help distinguish between them. This is visible at any point, regardless of whether you have close the program or not - you can simply switch back to RenderDoc while it's running. +In this example we have a connection window open to the debugmarker sample from Sascha Willms' Vulkan examples. Three captures have been made and we can see their thumbnails to help distinguish between them. This is visible at any point, regardless of whether you have close the program or not - you can simply switch back to RenderDoc while it's running. .. note:: @@ -74,7 +74,7 @@ You can press F2 or single click on a selected capture (not double click) to ren Child Processes --------------- -RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check "Hook into Children" in the :doc:`capture_log_attach`. +RenderDoc is able to automatically inject into any child processes started by the initial process launched from the UI. To do this simply check :guilabel:`Capture Child Processes` when :doc:`capture_attach`. RenderDoc has a particular handling of child processes to help you navigate to the process of interest. Whenever a child process is launched, the UI is notified and a list of processes is displayed in a box on the capture connection window. You can double click on any of these entries to open up a new connection to that process, in a new window. @@ -86,4 +86,4 @@ See Also -------- * :doc:`../how/how_network_capture_replay` -* :doc:`capture_log_attach` +* :doc:`capture_attach` diff --git a/docs/window/debug_messages.rst b/docs/window/debug_messages.rst index 44b9edc04..f38a1ea91 100644 --- a/docs/window/debug_messages.rst +++ b/docs/window/debug_messages.rst @@ -3,12 +3,12 @@ Debug Messages The Debug Messages window shows messages from the API including warnings about performance issues or concerns about potential hazards, as well as errors on invalid use of the API. -RenderDoc will alert you if there are any debug messages to show from the log, by flashing in the status bar. Sometimes RenderDoc will also add new alerts there that aren't part of the original log if there are warnings or problems that it encounters while processing and analysing the log. +RenderDoc will alert you if there are any debug messages to show from the log by flashing in the status bar. Sometimes RenderDoc will also add new alerts there that aren't part of the original log if there are warnings or problems that it encounters while processing and analysing the log. Capturing with debug messages included -------------------------------------- -To include these debug messages in a log, check on the "Enable API validation" option in the capture options. For more information see :doc:`capture_log_attach` +To include these debug messages in a log, check on the :guilabel:`Enable API validation` option in the capture options. For more information see :doc:`capture_attach` Debug Messages -------------- diff --git a/docs/window/event_browser.rst b/docs/window/event_browser.rst index 2a70ab3e9..fd3fdc744 100644 --- a/docs/window/event_browser.rst +++ b/docs/window/event_browser.rst @@ -8,23 +8,60 @@ Annotating your frame The Event Browser becomes most useful when the application has user-defined annotations of sections and subsections of the frames, to allow for a more logical and ordered browsing of the frame. -Doing this is API and platform specific. Example code for D3D11 is included below, using the ``D3DPERF`` library that is exported by ``d3d9.dll``, which can still be used in D3D11. (The newer ``ID3DUserDefinedAnnotation`` API is also supported). +Doing this is API and platform specific. Example code for D3D11 is included below, using the ``D3DPERF`` library that is exported by ``d3d9.dll``, which can still be used in D3D11: .. highlight:: c++ .. code:: c++ - D3DPERF_BeginEvent(0xffffffff, L"Start of example"); + D3DPERF_BeginEvent(0xffffffff, L"Start of example"); - D3DPERF_BeginEvent(0xff00ff00, L"Sub section"); - // events inside the subsection - D3DPERF_EndEvent(); + D3DPERF_BeginEvent(0xff00ff00, L"Sub section"); + // events inside the subsection + D3DPERF_EndEvent(); - // events outside the subsection - D3DPERF_EndEvent(); + // events outside the subsection + D3DPERF_EndEvent(); + + // the newer ID3DUserDefinedAnnotation API is also supported + ID3DUserDefinedAnnotation *annot; + immediateContext->QueryInterface(__uuidof(ID3DUserDefinedAnnotation), (void **)&annot); + + annot->BeginEvent(L"Sub section 2") + + annot->EndEvent(); This will generate a section of the frame with a subsection that includes some events, and then some further events that are siblings of the subsection. -OpenGL can make use of the ``KHR_debug`` extension, and Vulkan can use the ``VK_EXT_debug_marker`` extension. +OpenGL can make use of the ``KHR_debug`` extension: + +.. highlight:: c++ +.. code:: c++ + + // omitted code to initialise the extension + + glPushDebugGroupKHR(GL_DEBUG_SOURCE_APPLICATION, 0, -1, "Begin Section"); + + // contents of section here + + glPopDebugGroupKHR(); + +Vulkan can use the ``VK_EXT_debug_marker`` extension: + +.. highlight:: c++ +.. code:: c++ + + // omitted code to initialise the extension + + VkCommandBuffer cmd = ...; + + VkDebugMarkerMarkerInfoEXT markerInfo = {}; + markerInfo.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT; + markerInfo.pMarkerName = "Begin Section"; + vkCmdDebugMarkerBeginEXT(cmd, &markerInfo); + + // contents of section here + + vkCmdDebugMarkerEndEXT(cmd); Selecting available columns --------------------------- @@ -33,10 +70,7 @@ By default, the columns in the event browser are EID and Name. Name cannot be re .. |timeline_marker| image:: ../imgs/icons/timeline_marker.png -To select which columns should be visible, right click the header or click the |timeline_marker| select columns button. - -To rearrange the columns simply click and drag on the header. - +To select which columns should be visible, right click the header or click the |timeline_marker| select columns button. To rearrange the columns simply click and drag on the header. .. note:: @@ -51,13 +85,14 @@ To time the GPU duration of each drawcall, click the timer button |time|. This will automatically run a process to get the time of each drawcall and display it in the duration column, which will be added if necessary. +You can configure which time unit is used for the duration column on the fly in the :doc:`settings_window`. -You can configure which time unit is used for the duration column on the fly in the :doc:`options_window`. +To examine more GPU counters than just plain duration, see :doc:`performance_counter_viewer`. Browsing the frame ------------------ -The event browser is primarily intended as a tool to browse through the frame. Events are listed as entries in the browser and the hierarchical labels mentioned above become tree nodes. +The event browser is the primary way to browse through the frame. Events are listed as entries in the browser and the hierarchical labels mentioned above become tree nodes. .. |flag_green| image:: ../imgs/icons/flag_green.png @@ -84,13 +119,15 @@ Bookmarks .. |asterisk_orange| image:: ../imgs/icons/asterisk_orange.png -The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`CTRL-B`. +The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`Ctrl-B`. .. figure:: ../imgs/Screenshots/BookmarksBar.png Bookmarks bar: The bookmarks bar with several EIDs bookmarks. -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. +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. + +For more information see :doc:`../how/how_annotate_capture`. Searching and Jumping --------------------- @@ -109,11 +146,11 @@ Matching events will be highlighted with a find icon |find|, and pressing enter The find toolbar isn't dismissed until you press escape in the text box, or click the close button |cross|. -.. |stepprev| image:: ../imgs/icons/stepprev.png -.. |stepnext| image:: ../imgs/icons/stepnext.png +.. |arrow_left| image:: ../imgs/icons/arrow_left.png +.. |arrow_right| image:: ../imgs/icons/arrow_right.png -You can also jump up and down between find results with the previous |stepprev| and next |stepnext| buttons. +You can also jump up and down between find results with the previous |arrow_left| and next |arrow_right| buttons. .. figure:: ../imgs/Screenshots/FindResults.png diff --git a/docs/window/index.rst b/docs/window/index.rst index 36a54c4ea..6459d08eb 100644 --- a/docs/window/index.rst +++ b/docs/window/index.rst @@ -5,11 +5,14 @@ Window reference texture_viewer api_inspector buffer_viewer - capture_log_attach + capture_attach event_browser - options_window + settings_window pipeline_state timeline_bar capture_connection debug_messages python_shell + resource_inspector + performance_counter_viewer + capture_comments diff --git a/docs/window/options_window.rst b/docs/window/options_window.rst deleted file mode 100644 index 6e7907b1e..000000000 --- a/docs/window/options_window.rst +++ /dev/null @@ -1,218 +0,0 @@ -Options Window -============== - -.. _settings-window: - -The options window contains various advanced or niche settings that configure the analysis UI. - -Options -------- - -Below each tab of the options window is detailed with explanations of the given settings. - -Some settings may not be saved until the application is closed, although most will come into immediate effect. - -The settings are contained in ``%APPDATA%\RenderDoc\UI.config`` if you wish to back up or reset these settings. - -General options ---------------- - - | ``Associate .rdc with RenderDoc`` Default: ``N/A`` - -This button will elevate RenderDoc to administrator privileges temporarily, and associate the ``.rdc`` file extension with RenderDoc. After doing this double clicking any ``.rdc`` file will open it in a new instance of RenderDoc. - ---------------- - - | ``Associate .cap with RenderDoc`` Default: ``N/A`` - -This button will elevate RenderDoc to administrator privileges temporarily, and associate the ``.cap`` file extension with RenderDoc. After doing this double clicking any ``.cap`` file will open a new instance of RenderDoc and show the capture dialog with the settings contained inside. - -If the setting "Auto Start" is enabled, RenderDoc will then immediately trigger a capture of the target executable. - ---------------- - - | ``Minimum decimal places on float values`` Default: ``2`` - -Defines the smallest number of decimal places to display on a float, padding with 0s. - -Examples: - -* With a value of 2, ``0.1234f`` will be displayed as *0.1234* - -* With a value of 2, ``1.0f`` will be displayed as *1.00* - -* With a value of 6, ``0.1234f`` will be displayed as *0.123400* - -* With a value of 6, ``1.0f`` will be displayed as *1.000000* - ---------------- - - | ``Maximum significant figures on decimals`` Default: ``5`` - -Defines the smallest number of decimal places to display on a float, padding with 0s. - -Examples: - -* With a value of 5, ``0.123456789f`` will be displayed as *0.12345* - -* With a value of 5, ``1.0f`` will be displayed as *1.00* - -* With a value of 10, ``0.123456789f`` will be displayed as *0.123456789* - -* With a value of 10, ``1.0f`` will be displayed as *1.00* - ---------------- - - | ``Negative exponential cutoff value`` Default: ``5`` - -Any floating point numbers that are below *E-v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal. - -Examples: - -* With a value of 5, ``0.1234f`` will be displayed as *0.1234* - -* With a value of 5, ``0.000001f`` will be displayed as *1.0E-6* - -* With a value of 10, ``0.1234f`` will be displayed as *0.1234* - -* With a value of 10, ``0.000001f`` will be displayed as *0.000001* - ---------------- - - | ``Positive exponential cutoff value`` Default: ``7`` - -Any floating point numbers that are larger *E+v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal. - -Examples: - -* With a value of 7, ``8000.5f`` will be displayed as *8005.5* - -* With a value of 7, ``123456789.0f`` will be displayed as *1.2345E8* - -* With a value of 2, ``8000.5f`` will be displayed as *8.0055E3* - -* With a value of 2, ``123456789.0f`` will be displayed as *1.2345E8* - ---------------- - - | ``Directory for temporary capture files`` Default: ``%TEMP%`` - -This allows you to choose where on disk temporary capture files are stored between when the capture is made, and when it is either discarded or saved to a permanent location on disk. - -By default the system temporary directory is used, but if this lies on drive with limited space, large captures could become a problem so here you can redirect the storage elsewhere. - ---------------- - - | ``Default save directory for captures`` Default: ``Empty`` - -This allows you to choose which directory the save dialog will default to when prompting to save a capture file. By default the value is empty, which means that it follows the system behaviour (e.g. to begin on whichever folder was last browsed to in a file dialog). - -The folder must exist, it will not be created when browsed to. - ---------------- - - | ``Allow global process hooking`` Default: ``Disabled`` - -This option enables the functionality allowing capturing of programs that aren't launched directly from RenderDoc, but are launched from somewhere else. - -This option **can be dangerous** which is why you have to deliberately enable it here. Be careful when using this and only do so when necessary - more details can be found in the :ref:`global process hook ` details. - ---------------- - - | ``Allow periodic anonymous update checks`` Default: ``Enabled`` - -Every couple of days RenderDoc will send a single web request to a server to see if a new version is available and let you know about it. The only information transmitted is the version of RenderDoc that is running. - -If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's recommended that you manually check for updates as new versions will be made available regularly with bugfixes. - ---------------- - - | ``Prefer monospaced fonts in UI`` Default: ``Disabled`` - -This option will use a monospaced font for every place in the UI where any data or output is displayed. - -Changing this option will need the UI to be restarted before it takes effect. - ---------------- - - | ``Always replay logs locally`` Default: ``Disabled`` - -Normally, when RenderDoc begins to load a capture file that was created on a different type of machine, it will prompt you to ask if you really want to replay it locally (and perhaps get different results or even failed loading), or if you'd like to choose a :doc:`replay context <../how/how_network_capture_replay>` to replay it remotely on the type of machine it was recorded. - -In that prompt you can choose to always replay logs locally, which enables this option. If enabled, RenderDoc will always just load the log locally. - -Core options ------------- - - | ``Shader debug search paths`` Default: ``Empty`` - -Here you can choose which locations to search in, and in which order, when looking up a relative path for unstripped debug info. - -For more information you can consult :ref:`the FAQ entry about providing unstripped shader debug information `. - -Texture Viewer options ----------------------- - - | ``Reset Range on changing selection`` Default: ``Disabled`` - -When changing texture from one to another, when this option is enabled the range control will reset itself to [0, 1]. This will happen between any two textures, and going back and forth between two textures will also reset the range. - ---------------- - - | ``Visible channels, mip/slice, and range saved per-texture`` Default: ``Enabled`` - -Settings including which channels are displayed (red, green, blue, alpha or depth/stencil), the mip or slice/cubemap face to display, or the visible min/max range values are remembered with the texture you were looking at. In other words if you display a render target with only the alpha channel visible, then switching to view another texture will default back to RGB - and switching back to that render target will view alpha again. - -Shader Viewer options ---------------------- - - | ``Rename disassembly registers`` Default: ``Enabled`` - -This option tries to make the disassembly of shaders easier to read by substituting variable names where available in for constant register names. - -Event Browser options ---------------------- - - | ``Time unit used for event browser timings`` Default: ``Microseconds`` - -This option allows you to select the unit that will be shown in the duration column in the event browser when you time individual drawcalls. - -Seconds through to nanoseconds are supported. - ---------------- - - | ``Hide empty marker sections`` Default: ``Disabled`` - -Marker sections that contain no API calls or drawcalls will be completely removed. This also applies to the Timeline Bar. - -This option only applies itself the next time you load a log. - - ---------------- - - | ``Hide marker sections with only non-draw API calls`` Default: ``Disabled`` - -Marker sections that contain only miscellaneous non-draw API calls like queries or state setting will be completely removed. This also applies to the Timeline Bar. - -This can be useful if you have markers around occlusion queries or where you have a minor state change, and you don't want them cluttering up the capture. - -This option only applies itself the next time you load a log. - - ---------------- - - | ``Apply marker colours`` Default: ``Enabled`` - -Some APIs can provide an RGBA colour alongside the marker name when setting or pushing a marker region. This option enables applying those colours in the UI. Usually you'd leave it on unless your code is passing garbage for the colours or something instead of 0s (which will then be ignored rather than coming out black). - -This option only applies itself the next time you load a log. - - ---------------- - - | ``Colourise whole row for marker regions`` Default: ``Enabled`` - -If the above option to apply colours is enabled, this will colourise the whole row in the event browser for any marker regions with colours, rather than just applying a strip of colour along the side of their children. - -This option only applies itself the next time you load a log. - diff --git a/docs/window/performance_counter_viewer.rst b/docs/window/performance_counter_viewer.rst new file mode 100644 index 000000000..5fb6a8639 --- /dev/null +++ b/docs/window/performance_counter_viewer.rst @@ -0,0 +1,36 @@ +Performance Counter Viewer +========================== + +The performance counter viewer provides a very simple way to fetch the results of GPU counters across all events in a capture. + +Counter selection +----------------- + +Once a capture is opened, clicking the :guilabel:`Capture Counters` button will open up the selection dialog, listing all of the counters available. + +.. figure:: ../imgs/Screenshots/counter_selection.png + + Performance Counter Viewer: Selecting the set of counters. + +On the left-hand side will be a tree view with the available counters. These will be grouped in a hierarchy to allow for easier browsing. + +When a counter is selected, the counter description will list a brief summary of what value or quantity the counter is measuring and may indicate where it is useful. + +Each counter has a checkbox, as well as each category. Counters can be toggled individually, or else whole categories can be toggled on and off at once which enables or disables all counters within that category. On the lower right is a list of all enabled counters - double clicking on any counter will jump to it in the list and display its description. + +The set of counters to be sampled can be saved and loaded to a configuration file using the :guilabel:`Save` and :guilabel:`Load` buttons. + +Counter Results +--------------- + +When clicking :guilabel:`Sample Counters` in the counter selection dialog above, RenderDoc will then iterate over every event and fetch all of the data for the selected counters, and display it in a large table. + +.. figure:: ../imgs/Screenshots/counter_view.png + + Performance Counter Viewer: Viewing the results of the counters. + +By default the table is sorted by EID, but each column is sortable individually so that you can easily identify the drawcall with the highest or lowest value for any given counter. + +.. |save| image:: ../imgs/icons/save.png + +Clicking the |save| button lets you save the results of the counters as csv. diff --git a/docs/window/pipeline_state.rst b/docs/window/pipeline_state.rst index 27c39fef3..d3f819c3a 100644 --- a/docs/window/pipeline_state.rst +++ b/docs/window/pipeline_state.rst @@ -10,20 +10,20 @@ At the top of the Pipeline Viewer is the pipeline flowchart - this shows the hig Each block is a separate page which contains the relevant state and contents for that piece of the graphics pipeline, with specific details varying by API and the type of data to be displayed. -The currently selected block is outlined with red, and the page in view reflects the contents of that section of the pipeline. Light grey parts of the pipeline are those which are currently active and participating in this drawcall. Dark grey parts of the pipeline are not present and can be considered pass-through/do-nothing. +The currently selected block is outlined with red, and the page in view reflects the contents of that section of the pipeline. Light grey parts of the pipeline are those which are currently active and participating in this drawcall. Dark grey parts of the pipeline are not enabled and can be considered pass-through/do-nothing. .. figure:: ../imgs/Screenshots/PipelineBar.png - Pipeline: Pictured here, the high-level parts of the D3D11 Pipeline. + Pipeline: Pictured here, the high-level parts of the Vulkan Pipeline. .. note:: - In D3D11, the Stream-Out stage is available under the Geometry Shader block, with the buffers being used for stream-out shown. Similarly for GL, the transform feedback is listed in the geometry shader block. + In D3D11 and OpenGL, the Stream-Out / Transform Feedback stage is available under the Geometry Shader block, with the buffers being used for stream-out shown. Pipeline Section Display ------------------------ -The pipeline state viewer always displays the state of the pipeline after the execution of the drawcall, as with the other viewers in RenderDoc. +The pipeline state viewer always displays the state of the pipeline _after_ the execution of the drawcall, as with the other viewers in RenderDoc. Any resources that are bound to the pipeline can be opened in more detailed viewers, such as vertex buffers, constant buffers and textures. More details of this process can be found in the page :doc:`../how/how_object_details`. diff --git a/docs/window/python_shell.rst b/docs/window/python_shell.rst index b96e71785..b43f70ca8 100644 --- a/docs/window/python_shell.rst +++ b/docs/window/python_shell.rst @@ -1,14 +1,24 @@ Python Shell ============ -The python shell allows a limited form of scripting for RenderDoc, including the ability to run simple scripts over the whole dataset in ways not easy to do in the UI. +The python shell allows flexible of RenderDoc, including the ability to run simple scripts over the whole dataset in ways not easy to do in the UI. Depending on the build-time configuration the Qt UI itself may also be exposed to python for customisation. Overview -------- +.. figure:: ../imgs/Screenshots/pythonshell.png + + The python shell + You can open the python shell from the window menu. It offers both an interactive shell and a window that can open and run scripts and display the output. -Currently the support is fairly bare bones, and typically you will need some understanding of the code to use the scripting support well. The :code:`pyrenderdoc` object corresponds to the :code:`Core` object type used throughout the UI, and the :code:`renderdoc` python module corresponds to the :code:`renderdoc` namespace in C# and it provides a jumping off point for most operations from there. +The full :doc:`python API reference <../python_api/index>` contains the explicit detail of the whole API, but you can also use the ``help()`` command to obtain information about a particular object or function call. -So while not particularly friendly to discovery, you can use this to perform an automated iteration over e.g. all events or all textures for something of interest. +To get started the :code:`pyrenderdoc` object corresponds to a :py:class:`qrenderdoc.CaptureContext` object through which the internal API and UI windows can be obtained. +For Qt integration, if available, you can import :code:`PySide2` which provides python bindings for the Qt API. + +See Also +-------- + +* :doc:`../python_api/index` diff --git a/docs/window/resource_inspector.rst b/docs/window/resource_inspector.rst new file mode 100644 index 000000000..7b68f3bd9 --- /dev/null +++ b/docs/window/resource_inspector.rst @@ -0,0 +1,46 @@ +Resource Inspector +================== + +The resource inspector window allows you to see a full list of all API objects included in the frame capture. You can see the relationships between objects - such as parent/child links - as well as the full creation details of any object. + +.. |link| image:: ../imgs/icons/link.png + +Links to the resource inspector exist throughout the UI indicated by a **bold resource name** and the |link| icon. + +.. figure:: ../imgs/Screenshots/resource_inspector.png + + Resource Inspector: Examining the details of a resource in a capture. + +Related Resources +----------------- + +For the selected resource, if there are any parent resources which this resource depends on, they will be listed under related resources. Similarly in the parent resource, any children are listed here too. This lets you easily click from one to the other. + +An example of a parent-child relationship is a 'view' type object that is created in reference to a concrete 'image' or 'texture' type object. + +Usage in Frame +-------------- + +Some resources such as textures and buffers have information available about where and how they're used in the frame. + +In this list, each entry lists an EID range and a type of usage. + +Resource Initialisation Parameters +---------------------------------- + +Before any API object is used in the frame, it must be initialised and set up exactly as it was in the captured application. + +The function calls used to initialise the object are listed here, which will normally contain at least one creation function. + +Renaming resources +------------------ + +To rename resources, 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. + +This name will be used consistently throughout the UI anywhere the resource is referenced, and will update whenever you rename it again. + +.. figure:: ../imgs/Screenshots/resource_rename.png + + Resource Inspector: Renaming a resource in a capture. + +For more information, see :doc:`../how/how_annotate_capture`. diff --git a/docs/window/settings_window.rst b/docs/window/settings_window.rst new file mode 100644 index 000000000..63f73d350 --- /dev/null +++ b/docs/window/settings_window.rst @@ -0,0 +1,285 @@ +Settings Window +=============== + +.. _settings-window: + +The settings window contains various advanced or niche settings that configure the analysis UI. + +Some settings may not be saved until the application is closed, although most will come into immediate effect. + +The settings are saved in the application-specific settings directory (On windows that's ``%APPDATA%\qrenderdoc\UI.config`` and on linux that's a path like ``~/.local/share/qrenderdoc``) if you wish to back up or reset these settings. + +General options +--------------- + + | :guilabel:`Visual theme of the UI` Default: ``Light`` or ``Dark`` depending on native color theme. + +This allows you to choose what theme to use in RenderDoc. By default when first starting either the light or dark native RenderDoc theme will be selected, but you can change that or switch to any other supported theme here. + +.. note:: + + The theme won't fully apply until the next restart, although most elements will update immediately to give you a preview. + +--------------- + + | :guilabel:`Minimum decimal places on float values` Default: ``2`` + +Defines the smallest number of decimal places to display on a float, padding with 0s. + +Examples: + +* With a value of 2, ``0.1234`` will be displayed as *0.1234* + +* With a value of 2, ``1.0`` will be displayed as *1.00* + +* With a value of 6, ``0.1234`` will be displayed as *0.123400* + +* With a value of 6, ``1.0`` will be displayed as *1.000000* + +--------------- + + | :guilabel:`Maximum significant figures on decimals` Default: ``5`` + +Defines the smallest number of decimal places to display on a float, padding with 0s. + +Examples: + +* With a value of 5, ``0.123456789`` will be displayed as *0.12346* + +* With a value of 5, ``1.0`` will be displayed as *1.00* + +* With a value of 10, ``0.123456789`` will be displayed as *0.123456789* + +* With a value of 10, ``1.0`` will be displayed as *1.00* + +--------------- + + | :guilabel:`Negative exponential cutoff value` Default: ``5`` + +Any floating point numbers that are below *E-v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal. + +Examples: + +* With a value of 5, ``0.1234`` will be displayed as *0.1234* + +* With a value of 5, ``0.000001`` will be displayed as *1.0E-6* + +* With a value of 10, ``0.1234`` will be displayed as *0.1234* + +* With a value of 10, ``0.000001`` will be displayed as *0.000001* + +--------------- + + | :guilabel:`Positive exponential cutoff value` Default: ``7`` + +Any floating point numbers that are larger *E+v* for this value *v* will be displayed in scientific notation rather than as a fixed point decimal. + +Examples: + +* With a value of 7, ``8000.5`` will be displayed as *8005.5* + +* With a value of 7, ``123456789.0`` will be displayed as *1.2345E8* + +* With a value of 2, ``8000.5`` will be displayed as *8.0055E3* + +* With a value of 2, ``123456789.0`` will be displayed as *1.2345E8* + +--------------- + + | :guilabel:`Directory for temporary capture files` Default: ``%TEMP%`` + +This allows you to choose where on disk temporary capture files are stored between when the capture is made, and when it is either discarded or saved to a permanent location on disk. + +By default the system temporary directory is used, but if this lies on drive with limited space, large captures could become a problem so here you can redirect the storage elsewhere. + +--------------- + + | :guilabel:`Default save directory for captures` Default: ``Empty`` + +This allows you to choose which directory the save dialog will default to when prompting to save a capture file. By default the value is empty, which means that it follows the system behaviour (e.g. to begin on whichever folder was last browsed to in a file dialog). + +The folder must exist, it will not be created when browsed to. + +--------------- + + | :guilabel:`Allow global process hooking` Default: ``Disabled`` + +This option enables the functionality allowing capturing of programs that aren't launched directly from RenderDoc, but are launched from somewhere else. + +This option **can be dangerous** which is why you have to deliberately enable it here. Be careful when using this and only do so when necessary - more details can be found in the :ref:`global process hook ` details. + +--------------- + + | :guilabel:`Allow periodic anonymous update checks` Default: ``Enabled`` + +Every couple of days RenderDoc will send a single web request to a secure server to see if a new version is available and let you know about it. The only information transmitted is the version of RenderDoc that is running. + +If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's recommended that you manually check for updates as new versions will be made available regularly with bugfixes. + +--------------- + + | :guilabel:`Prefer monospaced fonts in UI` Default: ``Disabled`` + +This option will use a monospaced font for every place in the UI where any data or output is displayed. + +Changing this option will need the UI to be restarted before it takes effect. + +--------------- + + | :guilabel:`Always replay captures locally` Default: ``Disabled`` + +Normally, when RenderDoc begins to load a capture file that was created on a different type of machine, it will prompt you to ask if you really want to replay it locally (and perhaps get different results or even failed loading), or if you'd like to choose a different :doc:`replay context <../how/how_network_capture_replay>` to replay it remotely on the type of machine it was recorded. + +In that prompt you can choose to always replay captures locally, which enables this option. If enabled, RenderDoc will always just load the capture locally. + +--------------- + + | :guilabel:`Anonymous Analytics` + +When you first run a build of RenderDoc that's analytics-enabled, RenderDoc will prompt you for your preference. + +You have three alternatives: + +* *Gather anonymous low-detail statistics and submit automatically*. This will gather analytics in the background and submit the anonymous report automatically each month to RenderDoc's secure server. +* *Gather anonymous low-detail statistics, but manually verify before submitting*. This will gather analytics in the background but prompt the user each month to verify the contents of the report before submitting the anonymous report to RenderDoc's secure server. +* *Do not gather or submit any statistics*. This will disable all statistics gathering completely. + +This option allows you to change modes at any time, although note that if you previously had statistics disabled the program must be restarted to enable gathering. + +The complete details of the analytics can be found in the page about :doc:`../behind_scenes/analytics`. + +Core options +------------ + + | :guilabel:`Shader debug search paths` Default: ``Empty`` + +Here you can choose which locations to search in, and in which order, when looking up a relative path for unstripped debug info. + +For more information you can consult :ref:`the FAQ entry about providing unstripped shader debug information `. + +Texture Viewer options +---------------------- + + | :guilabel:`Reset Range on changing selection` Default: ``Disabled`` + +When changing texture from one to another, when this option is enabled the range control will reset itself to [0, 1]. This will happen between any two textures, and going back and forth between two textures will also reset the range. + +--------------- + + | :guilabel:`Visible channels, mip/slice, and range saved per-texture` Default: ``Enabled`` + +Settings including which channels are displayed (red, green, blue, alpha or depth/stencil), the mip or slice/cubemap face to display, or the visible min/max range values are remembered with the texture you were looking at. In other words if you display a render target with only the alpha channel visible, then switching to view another texture will default back to RGB - and switching back to that render target will view alpha again. + +Shader Viewer options +--------------------- + + | :guilabel:`Rename disassembly registers` Default: ``Enabled`` + +This option tries to make the disassembly of shaders easier to read by substituting variable names where available in for constant register names. + +--------------- + + | :guilabel:`Vulkan Disassemblers` + +Here you can configure external tools that disassemble binary SPIR-V into a human-readable representation. + +Some built-in tools are supported such as SPIRV-Cross and spirv-dis, for these tools if they can be autodetected they will already be present, and they may be distributed with RenderDoc builds in case a version isn't installed on the system. + +Other custom tools can be configured, but for those the command line arguments must be configured. The command line arguments will have ``{spv_bin}`` replaced with the full path to the binary SPIR-V file, and ``{spv_disasm}`` with the path of where the human-readable output must be written to. + +Event Browser options +--------------------- + + | :guilabel:`Time unit used for event browser timings` Default: ``Microseconds`` + +This option allows you to select the unit that will be shown in the duration column in the event browser when you time individual drawcalls. + +Seconds through to nanoseconds are supported. + +--------------- + + | :guilabel:`Add fake markers if none present` Default: ``Enable`` + +If a capture is found to contain no markers whatsoever, RenderDoc will generate some default markers based on grouping drawcalls by the different output targets that they are drawing to. Roughly forming 'passes' of different types. + +You can disable this option here if you want to view a pure list of drawcalls with no annotations. + +This option only applies itself the next time you load a capture. + + +--------------- + + | :guilabel:`Hide empty marker sections` Default: ``Disabled`` + +Marker sections that contain no API calls or drawcalls will be completely removed. This also applies to the Timeline Bar. + +This option only applies itself the next time you load a capture. + + +--------------- + + | :guilabel:`Hide marker sections with only non-draw API calls` Default: ``Disabled`` + +Marker sections that contain only miscellaneous non-draw API calls like queries or state setting will be completely removed. This also applies to the Timeline Bar. + +This can be useful if you have markers around occlusion queries or where you have a minor state change, and you don't want them cluttering up the capture. + +This option only applies itself the next time you load a capture. + + +--------------- + + | :guilabel:`Apply marker colors` Default: ``Enabled`` + +Some APIs can provide an RGBA color alongside the marker name when setting or pushing a marker region. This option enables applying those colors in the UI. Usually you'd leave it on unless your code is passing garbage for the colors or something instead of 0s (which will then be ignored rather than coming out black). + +This option only applies itself the next time you load a capture. + + +--------------- + + | :guilabel:`Colorise whole row for marker regions` Default: ``Enabled`` + +If the above option to apply colors is enabled, this will colorise the whole row in the event browser for any marker regions with colors, rather than just applying a strip of color along the side of their children. + +This option only applies itself the next time you load a capture. + +Comments options +---------------- + + | :guilabel:`Show capture commends on load` Default: ``Enabled`` + +If a capture is newly loaded (i.e. it is not in the recent captures list having been loaded before) and it contains a comments section, then the capture comments panel will be displayed and brought to the front to show the comments on load. + +Newly created captures will not have any comments, they are only added through the UI, so this only applies to captures made somewhere else that have had comments added to them. + +For more information, see :doc:`../how/how_annotate_capture`. + +Android options +--------------- + + | :guilabel:`Android SDK root path` Default: ``Empty`` + +RenderDoc requires some android tools from the android SDK to be able to function. In most cases it's able to locate the tools automatically without any configuration needed, but if not this option allows you to manually locate the JDK root. + +By default it will try to auto-locate those tools by looking in different environment variables like ``ANDROID_HOME`` and ``ANDROID_SDK``, or else searching the default executable path. If it fails completely it will try to use the tools bundled with RenderDoc's installation. + +This setting, if present, will override all other search paths and be looked in first. + +--------------- + + | :guilabel:`Java JDK root path` Default: ``Empty`` + +RenderDoc may require tools from the Java JDK in some rare circumstances. In most cases it's able to locate the tools automatically without any configuration needed, but if not this option allows you to manually locate the JDK root. + +By default it will try to auto-locate the tools by looking in ``JAVA_HOME`` or else searching the default executable path. + +This setting, if present, will override all other search paths and be looked in first. + +--------------- + + | :guilabel:`Max Connection Timeout` Default: ``30 seconds`` + +Some Android programs take a long time to start up before they begin renderding. This setting allows you to define a timeout before RenderDoc will consider the execution and connection to have failed. + +This only applies to running Android programs. diff --git a/docs/window/texture_viewer.rst b/docs/window/texture_viewer.rst index a1b4b159b..cd5d41168 100644 --- a/docs/window/texture_viewer.rst +++ b/docs/window/texture_viewer.rst @@ -8,7 +8,11 @@ Overview The texture viewer consists of a couple of different sections, which will be outlined here. -Several specific techniques or features used within the texture viewer have their own separate pages that go into more detail. You might find more useful information there if they cover what you are looking for: :doc:`../how/how_view_texture`, :doc:`../how/how_inspect_pixel`, :doc:`../how/how_custom_visualisation` +Several specific techniques or features used within the texture viewer have their own separate pages that go into more detail. You might find more useful information there if they cover what you are looking for: + +* :doc:`../how/how_view_texture` +* :doc:`../how/how_inspect_pixel` +* :doc:`../how/how_custom_visualisation` .. figure:: ../imgs/Screenshots/LabelledTexViewer.png @@ -19,7 +23,7 @@ Main Texture Display The main texture display takes up the largest portion of the window, and is simply a container for the textures to display. -It is a tabbed control and although one tab is always present showing the currently followed texture bound to the pipeline, other locked tabs can be opened up showing a single resource. More details are available on the page :doc:`../how/how_view_texture`. +It is a tabbed control, and the first tab is always present showing a particular texture slot on the current pipeline state such as an input texture, or the color/depth outputs. Other locked tabs can be opened up showing a single resource. More details are available on the page :doc:`../how/how_view_texture`. The mouse wheel can be used to zoom in and out of the texture. When zoomed in, holding the left mouse button and dragging will pan the image from side to side. @@ -34,9 +38,9 @@ The status bar below the main texture display contains information on the curren * Dimensions - Width, height, depth and array size as applicable. * Mip Count. * MSAA sample count and quality, if applicable. -* Format - e.g. RGB8. The exact phrasing of this will vary by API. +* Format - e.g. ``RGBA8_UNORM``. -After this information there are a few displays that are pixel-based. The pixel that is under the cursor is displayed as a colour swatch, followed by its co-ordinates. Then any :doc:`picked pixel <../how/how_inspect_pixel>` is displayed afterwards with its numeric value displayed. +After this information there are a few displays that are pixel-based. The pixel that is under the cursor is displayed as a color swatch, followed by its co-ordinates. Then any :doc:`picked pixel <../how/how_inspect_pixel>` is displayed afterwards with its numeric value displayed. .. figure:: ../imgs/Screenshots/RMBStatus.png @@ -49,9 +53,9 @@ There are several thumbnail strip panels available, by default they are docked i These strips display thumbnails of the resources bound to their respective parts of the pipeline, to give some context and allow quick preview without having to switch the main display between these textures. -The texture that the following tab is currently displaying is highlighted in red, and each thumbnail shows both the slot number and the name of the texture bound at that point. To follow a given slot simply left click on it. If the currently followed texture slot is empty (i.e. it was following a texture and then that slot was unbound) it will show up simply named "Unbound" and with no name or slot number. +The texture that the following tab is currently displaying is highlighted in red, and each thumbnail shows both the slot number and the name of the texture bound at that point. To follow a given slot simply left click on it. If the currently followed texture slot is empty (i.e. it was following a texture and then that slot became unbound in a different drawcall) it will show up simply named "Unbound" and with no name or slot number. -Each thumbnail has a context menu available via right click. This menu allows you to open a locked tab (:doc:`../how/how_view_texture`), as well as containing a list of all the uses of this texture - as read-only resource and writable output. This is similar to the resource display strip on the :doc:`timeline_bar`. Clicking on any of these entries will jump to the first of the events in the event range listed. +Each thumbnail has a context menu available via right click. This menu allows you to open a locked tab (:doc:`../how/how_view_texture`), jump to the :doc:`resource inspector <../window/resource_inspector>`, as well as containing a list of all the uses of this texture - as read-only resource and writable output. This is similar to the resource display strip on the :doc:`timeline_bar`. Clicking on any of these entries will jump to the first of the events in the event range listed. .. figure:: ../imgs/Screenshots/OpenLockedTab.png @@ -66,6 +70,8 @@ The Pixel context display is a small panel by default in the bottom right of the Whenever a pixel is picked small area of the texture around it is rendered at maximum zoom to this panel. This gives you some context for the pixels nearby to the one you're picking and allows fine refinement without needing to zoom in and lose your place in the overall image. +You can adjust the selected pixel with the arrow keys on your keyboard after picking, using this context to guide your selection. + .. figure:: ../imgs/Screenshots/PixelContext.png Pixel context: Pixel context displaying the surrounds of the picked pixel. @@ -89,7 +95,7 @@ There are four other buttons available for control of the range: .. |zoom| image:: ../imgs/icons/zoom.png .. |wand| image:: ../imgs/icons/wand.png -.. |UndoArrow| image:: ../imgs/icons/UndoArrow.png +.. |arrow_undo| image:: ../imgs/icons/arrow_undo.png .. |chart_curve| image:: ../imgs/icons/chart_curve.png * |zoom| **Zoom in** - This button will zoom the extreme values in to whichever fine values have been selected by the draggable handles. @@ -108,7 +114,7 @@ There are four other buttons available for control of the range: Right clicking on this button will cause it to always auto-fit until you disable this. ie. when you move to another event or another texture, the range will be auto-fit again. This is useful if jumping between events or textures where the visible ranges are very different. -* |UndoArrow| **Reset** - Simply resets the range back to the default of [0, 1] - useful for resetting after changing to a new texture where the range settings aren't applicable. +* |arrow_undo| **Reset** - Simply resets the range back to the default of [0, 1] - useful for resetting after changing to a new texture where the range settings aren't applicable. * |chart_curve| **Histogram** - This is a toggle switch. When enabled it will change the thin bar of the range control into a thicker bar that contains a range-value histogram, showing the distribution of values. @@ -137,28 +143,28 @@ Channels selector .. |CustomDisplay| image:: ../imgs/Screenshots/CustomDisplay.png .. |add| image:: ../imgs/icons/add.png .. |page_white_edit| image:: ../imgs/icons/page_white_edit.png -.. |delete| image:: ../imgs/icons/delete.png +.. |delete| image:: ../imgs/icons/del.png .. | |RGBAChannels| Default RGBA channels | |RGBMChannels| RGBM mode - | |CustomDisplay| |add| |page_white_edit| |delete| :doc:`Custom Shader mode <../how/how_custom_visualisation>` + | |CustomDisplay| :doc:`Custom Shader mode <../how/how_custom_visualisation>` This selector switches between displaying standard RGBA channels, RGBM encoding with a custom multiplier and using a custom visualiser shader. -When in **RGBA** mode, by default only the RGB channels are displayed and alpha is forced to fully opaque. Each of the channels can be toggled off independently and any combination can be used. Any RGB channel which is disabled is forced to fully black in the output. When Alpha is enabled, the background will be rendered with a solid colour or checkerboard pattern to indicate semi-transparent areas. +When in **RGBA** mode, by default only the RGB channels are displayed and alpha is forced to fully opaque. Each of the channels can be toggled off independently and any combination can be used. Any RGB channel which is disabled is forced to fully black in the output. When Alpha is enabled, the background will be rendered with a solid color or checkerboard pattern to indicate semi-transparent areas. -Also note that when a single channel is displayed solo, the image is rendered as grayscale in that channel rather than displaying a monochromatic coloured image. +Also note that when a single channel is displayed solo, the image is rendered as grayscale in that channel rather than displaying a monochromatic colored image. .. tip:: 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. -Note that these channel selections are by default saved as per-texture state, so switching to a different texture will revert back to the default RGB, but going back to the first texture will remember which channels you were viewing. See the option in the :doc:`options_window`. +Note that these channel selections are by default saved as per-texture state, so switching to a different texture will revert back to the default RGB, but going back to the first texture will remember which channels you were viewing. See the option in the :doc:`settings_window`. -When **RGBM** is selected, the RGB value will be multiplied by the specified multiplier and then by the alpha value. This is a common encoding used to pack a larger range into an 8-bit RGB image. +When **RGBM** is selected, the RGB value will be multiplied by the specified multiplier and then by the alpha value. This is a common encoding used to pack HDR values into an 8-bit RGBA image by using the alpha channel as a scaling factor. -With **Custom** selected a dropdown will be populated with any ``.hlsl`` or ``.glsl`` files as appropriate in the ``%APPDATA%\renderdoc`` folder. When choosing a custom shader the raw image will be passed through this shader before being displayed with the usual controls on the main display. +With **Custom** selected a dropdown will be populated with any custom shaders available for decoding and displaying textures. When choosing a custom shader the raw image will be passed through this shader before being displayed with the usual controls on the main display. For more information see :doc:`../how/how_custom_visualisation`. You can create a new custom shader with the |add| button, edit a shader with the |page_white_edit| button, and delete an one with the |delete| button. @@ -172,14 +178,14 @@ A proper explanation of this is available in the :ref:`FAQ `. This lets you see the raw data of the underlying texture and format it as you wish if the data represents more complex data than is easy to display in the texture viewer. -.. warning:: - - The buffer viewer may not be able to handle the full number of columns that are appropriate for the full width of a texture, so it is better to limit the number of columns and manually calculate the offset into the table of data. - Goto Location ~~~~~~~~~~~~~ @@ -249,6 +251,21 @@ Goto Location This button opens a small popup above the main texture view that lets you type in a pixel location to jump to. This is useful if you're investigating a particular issue where you know what pixel the problem will lie on. +.. note:: + + This popup is also available with the keyboard shortcut :kbd:`Ctrl-G`. + +Open Resource Inspector +~~~~~~~~~~~~~~~~~~~~~~~ + +.. |link| image:: ../imgs/icons/link.png + +.. + + | |link| Open resource inspector + +This button opens a the currently visible texture in the :doc:`resource inspector ` which allows you to see more details about how the object was created and any other resources it may be related to. + .. note:: This popup is also available with the keyboard shortcut :kbd:`Ctrl-G`. @@ -256,7 +273,7 @@ This button opens a small popup above the main texture view that lets you type i Zoom Controls ~~~~~~~~~~~~~~~~~ -.. |fit_window| image:: ../imgs/icons/fit_window.png +.. |arrow_out| image:: ../imgs/icons/arrow_out.png .. |ZoomControls| image:: ../imgs/Screenshots/ZoomControls.png .. @@ -265,7 +282,7 @@ Zoom Controls The zoom controls are fairly self explanatory - a pre-existing zoom value can be chosen from the drop down or a custom value (clamped to the minimum and maximum zoom) can be entered as a percentage. Click the ``1:1`` button to zoom to the exact size. -To automatically fit the texture to the space available in the window, regardless of its dimensions, you can click the |fit_window| Fit button. +To automatically fit the texture to the space available in the window, regardless of its dimensions, you can click the |arrow_out| Fit button. This will toggle on and adjust the fit as different textures are displayed. Flip Y ~~~~~~ @@ -276,8 +293,8 @@ Flip Y | |flip_y| Flip Y -This button toggles flipping the co-ordinate system in Y - y=0 is at the bottom of the window instead of at the top. - +This button toggles flipping the co-ordinate system in Y, changing y=0 to be at the bottom of the window instead of at the top. + .. _render-overlay: Render Overlay @@ -291,7 +308,7 @@ Render Overlay This is a powerful tool for quickly diagnosing issues and can be very useful for locating what you're looking for. Several overlays are available that can be rendered over any texture, although most of them are only meaningful for currently bound render targets. -* ``Highlight Drawcall`` will do pretty much as it says. It darkens everything except the current drawcall which is highlighted in flat colour. This makes whatever is being drawn stand out and can be useful for seeing where the current object is on screen, especially if rapidly browsing through the frame. +* ``Highlight Drawcall`` will do show the area covered by the drawcall. It darkens everything except the current drawcall which is highlighted in a flat color. This makes whatever is being drawn stand out and can be useful for seeing where the current object is on screen, especially if rapidly browsing through the frame. * ``Wireframe Mesh`` will render a wireframe mesh of the current drawcall over the top of the image. @@ -301,7 +318,7 @@ This is a powerful tool for quickly diagnosing issues and can be very useful for * ``Backface Cull`` works as above but with backface culling. -* ``Viewport/Scissor`` shows a coloured overlay on the image that corresponds to the viewport and scissor regions. +* ``Viewport/Scissor`` shows a colored overlay on the image that corresponds to the viewport and scissor regions. * ``NaN/Inf/-ve display`` will render the image in grayscale (using the typical luminance calculation - ``dot(col.xyz, float3(0.2126, 0.7152, 0.0722)).xxx``) with red pixels highlighting any NaNs found, green pixels highlighting any infinities, and blue pixels for any negative values. Note that in any case where only one or some channels in a multi-channel texture pass, that pixel will still be highlighted (so ``{0.5, -1.0, 0.0}`` would highlight blue). diff --git a/docs/window/timeline_bar.rst b/docs/window/timeline_bar.rst index 970bda813..c32863119 100644 --- a/docs/window/timeline_bar.rst +++ b/docs/window/timeline_bar.rst @@ -10,7 +10,7 @@ The timeline bar shows the scene horizontally with the hierarchical frame marker This alternate view can be a useful way to get an overview of the whole frame, allowing you to jump around very different parts of the frame. -Given that the timeline bar shows the whole frame it also provides a secondary function of showing dependencies in a global way. For whichever texture is currently selected in the texture viewer, the timeline bar shows reads and writes to that texture throughout the frame. This can be especially useful for render targets that are used in both ways, as well as simply to see where a given texture is used in a frame without laboriously searching. +Given that the timeline bar shows the whole frame it also provides a secondary function of showing dependencies in a global way. For whichever texture is currently selected in the texture viewer, pixel history, or resource inspector, the timeline bar shows accesses of that texture throughout the frame. This can be especially useful for render targets that are cleared, written to and read from, as well as simply to see where a given texture is used in a frame without laboriously searching. .. figure:: ../imgs/Screenshots/TimelineBar.png @@ -21,10 +21,6 @@ Timeline Display By default the timeline bar views the whole frame, but with the mouse wheel you can zoom in and out. When zoomed in, you can scroll through the frame with the horizontal scroll bar. -The timeline bar sizes the sections that it contains to try and make the frame markers as visible as possible. This attempts to keep the frame browsable for as long as possible, such that small sections (in time or number of events) are still visible rather than being crushed to tiny bars. - -For this reason the timeline can resize itself when bars are expanded, as this can reveal new sections which must be allocated enough room. When there is slack space to be allocated it is given to the sections which have more events than others. - Underneath expanded sections, a blue pip is rendered for each drawcall-type event. The currently selected event is shown as a green pip, as well as there being a light grey vertical line to indicate the current position, such that this is visible even when the relevant section is not expanded. Clicking on any section will toggle it between expanded and unexpanded, and any sections underneath a section which is collapsed will remain in their previous state but will not be visible. @@ -36,17 +32,11 @@ Resource usage Display The timeline bar also shows the usage of the currently displayed texture. -Whichever texture is currently displayed in the :doc:`texture_viewer` (whether that be a currently bound texture, or a locked tab) will have its usage laid out across the frame on the timeline bar. +If the :doc:`texture_viewer` is active then whichever texture is being displayed will have its usage laid out across the frame on the timeline bar. If the :doc:`resource_inspector` is active then whichever resource is currently being inspected will have its usage displayed. If your textures have their names annotated you will see which texture is being inspected in the label for the usage bar. -A green arrow will be drawn under each pip that reads from the texture. If the pips are too close together to resolve the arrow, the arrows will stay distinct and lose the 1:1 association with event pips. - -Similarly, a purple arrow will be drawn under pips where the event writes to the texture. In the case that a resource is bound such that it can be read or written, the arrow will be half-green, half-purple. - -Clear calls will be shown with a light grey. - -In cases where the arrows are too close together to show distinctly, they will not all draw. To see exactly what usage is happening you can zoom into the context around that area of the frame. +A colored triangle will be drawn under each pip that reads from the texture. If the pips are too close together some triangles may be hidden, so zoom in anywhere that there is a great deal of usage in a small place to make it more visible. .. figure:: ../imgs/Screenshots/ResourceUsage.png diff --git a/scripts/installer/LICENSE.rtf b/scripts/installer/LICENSE.rtf index e135b3996..d779ec9da 100644 Binary files a/scripts/installer/LICENSE.rtf and b/scripts/installer/LICENSE.rtf differ