mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-06 01:50:38 +00:00
Initial commit of new restructuredtext docs
This commit is contained in:
Matthäus G. Chajdas
committed by
baldurk
baldurk
parent
6f8e0ae391
commit
c04dd86d8d
@@ -0,0 +1,193 @@
|
||||
FAQ
|
||||
===
|
||||
|
||||
.. toctree::
|
||||
|
||||
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.
|
||||
|
||||
How do I do some particular task?
|
||||
---------------------------------
|
||||
|
||||
Many specific tasks or functions are detailed in the "How Do I... ?" sections. These sections each take a feature or element of a workflow and explain how it fits into the program as a whole as well as any details of how it works.
|
||||
|
||||
If the task you have in mind isn't listed there you might find something similar, or you might find a related feature which can be used to do what you want. If the feature you want doesn't seem to exist at all you might want to check the Planned Future Features to see if it's coming soon - if it's not on that list please feel free to contact me and request it! Contact me. It has often been that simple features are very quick to implement and the prioritisation and scheduling of features is fairly fluid at this stage in development.
|
||||
|
||||
Why did you make RenderDoc?
|
||||
---------------------------
|
||||
|
||||
Although several tools do already exist for graphics debugging, none of them quite suited the functionality I desired and I would often find myself wishing for a feature of one in another and vice versa.
|
||||
|
||||
In addition to this, although the functionality overlaps to some degree many of these tools were primarily designed around the profiling of applications rather than debugging. While being able to inspect the state and contents of resources does often suffice for debugging, it's not necessarily the ideal workflow and often it can become cumbersome.
|
||||
|
||||
In principle I didn't see any reason why I couldn't write a home-brew graphics debugger with some fairly simple operating principles. While there were a whole lot of caveats and little stumbling blocks along the way, the original design has pretty much stayed consistent since the project was started back in July 2012. If you're interested you might want to read about How RenderDoc works.
|
||||
|
||||
Where did the name come from?
|
||||
-----------------------------
|
||||
|
||||
All of the good names were taken :-(.
|
||||
Who can I contact about bugs, feature requests, other queries?
|
||||
|
||||
At the moment there's just me at the wheel - feel free to contact me at Contact me if you have anything you'd like to ask or suggest. I use a github repository for tracking bugs and feature requests so that's the best place to file an issue.
|
||||
|
||||
I work on RenderDoc in my spare time but I am happy to help with anything and work with you if you have any issues that need attention.
|
||||
|
||||
How can I associate RenderDoc's file extensions with the program?
|
||||
-----------------------------------------------------------------
|
||||
|
||||
If you installed RenderDoc via the installer package rather than the zip folder, the option is available there to associate RenderDoc's file extensions with the program. Otherwise you can set them up from the Options Window.
|
||||
Note Note
|
||||
|
||||
RenderDoc will elevate itself to set up these file associations, but otherwise will not hold on to administrator permissions.
|
||||
|
||||
RenderDoc associates .rdc and .cap with itself when desired. The .rdc files are the logfiles output when you capture inside an application. .cap files describe the set up of a particular capture, and can be used to quickly re-launch a capture preset.
|
||||
|
||||
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.
|
||||
|
||||
What APIs does RenderDoc support?
|
||||
---------------------------------
|
||||
|
||||
Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available), Vulkan, and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of what is supported in its own page. Since Vulkan support is in its early stages, it also has its own page.
|
||||
|
||||
In future API support is planned for at D3D9 when time and scheduling allows. Higher priority is D3D12 now that Vulkan support is available. Mantle support will not happen as the API is not planned to be publically available anymore.
|
||||
|
||||
How can I backup or restore my settings?
|
||||
----------------------------------------
|
||||
|
||||
Everything RenderDoc relies upon is stored in %APPDATA%\RenderDoc. You can back up and restore this directory at will as nothing stored in there is machine specific aside from things like recent file lists.
|
||||
|
||||
Deleting this folder will also reset RenderDoc to the defaults - if you uninstall RenderDoc this folder will not be deleted.
|
||||
|
||||
RenderDoc doesn't install any registry keys aside from those 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 also uses TCP and UDP ports 39920 for remote replay connections, for when a remote host is used to replay and analyse the log.
|
||||
|
||||
Where can I get the source to RenderDoc?
|
||||
----------------------------------------
|
||||
|
||||
RenderDoc is licensed under the MIT license and the source is available on github.com
|
||||
|
||||
What are the requirements for RenderDoc?
|
||||
----------------------------------------
|
||||
|
||||
Currently RenderDoc expects Feature Level 11.0 hardware and above for D3D11. Lower levels will capture successfully, but on replay RenderDoc will fall back to WARP software emulation which will run quite slowly.
|
||||
|
||||
For OpenGL RenderDoc will only capture core profile applications, in general, and expects to be able to create a core 4.3 context which includes EXT_direct_state_access and ARB_buffer_storage. For more details see the OpenGL page.
|
||||
|
||||
With Vulkan RenderDoc should fully support any Vulkan application.
|
||||
|
||||
Why does my capture say "Failed to capture frame: Uncapped command list"?
|
||||
-------------------------------------------------------------------------
|
||||
|
||||
At the moment RenderDoc only begins capturing deferred command lists at the point that you trigger a capture. If you replay command lists from before this, RenderDoc will fail to capture the frame and try again next frame (and eventually give up after a few retries).
|
||||
|
||||
To change this behaviour, enable the Capture all cmd lists option - see that page for more details. This will capture all command lists from the start of the program, ready for when you decide to capture a frame. This currently has a fair overhead but it's something I want to improve in future
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Nothing is actually wrong here except perhaps that when visualising linear data it is often more convenient to "overcorrect" such that the data is perceptually linear. A good example to use is a normal map: The classic deep blue of (127,127,255) flat normals is technically incorrect as everyone is used to visualising these textures in programs that display the data as if it were SRGB (which is the convention for normal images that do not represent vectors).
|
||||
|
||||
You can override this behaviour on any texture that isn't listed as explicitly SRGB with the gamma (γ) button - toggle this off and the overcorrection will be disabled.
|
||||
|
||||
RenderDoc makes my bug go away! Or causes new artifacts that weren't there
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
For various tedious reasons RenderDoc's replay isn't (and in most cases can't be) a perfect reproduction of what your code was executing in the application when captured, and it can change the circumstances while running.
|
||||
|
||||
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:
|
||||
|
||||
#. Map()s that use DISCARD are filled with a marker value, so any values that aren't written to the buffer will be different - in application you can get lucky and they can be previous values that were uploaded, but in replay they will be 0xCCCCCCCC.
|
||||
|
||||
#. RenderDoc as an optimisation will not save or restore the contents of render targets at the start of the frame if it believes they will be entirely overwritten in the frame. This detection is typically accurate but means targets are cleared to black or full depth rather than accumulating, even if that accumulation is not intentional it may be the cause of the bug.
|
||||
|
||||
This behaviour can be overridden by enabling 'Save all initials' in the :doc:`capture options <capture_options>`.
|
||||
|
||||
I can't launch my program for capture directly. Can I capture it anyway?
|
||||
------------------------------------------------------------------------
|
||||
|
||||
There is an option for capturing programs using RenderDoc where you can't easily set up a direct launch of the process.
|
||||
|
||||
More details can be found in the capture options page which details how to use it, however you should take care to read the warnings! This option isn't without its risks, so you need to be sure you know what you're doing before using it. It should always be used as a last resort when there is no other option.
|
||||
|
||||
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.
|
||||
|
||||
RenderDoc supports these formats: .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. For dds files RenderDoc supports all DXGI formats, compressed formats, arrays and mips - all of which will display as expected.
|
||||
|
||||
Any modifications to the image while open in RenderDoc will be refreshed in the viewer. However if the image metadata changes (dimension, format, etc) then this will likely cause artifacts.
|
||||
|
||||
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.
|
||||
|
||||
To enable this behaviour, select the 'Verify Map() Writes' option when :doc:`capturing <capture>`.
|
||||
|
||||
RenderDoc is complaining about my OpenGL app in the overlay - what gives?
|
||||
-------------------------------------------------------------------------
|
||||
|
||||
The first thing to remember is that **RenderDoc only supports Core 3.2 and above OpenGL**. If your app is using features from before 3.2 it almost certainly won't work as most functionality is not supported. A couple of things like not creating a VAO (which are required in core profile) and luminance textures (which don't exist in core profile) are allowed, but none of the fixed function pipeline will work, etc etc.
|
||||
|
||||
If your app is not using the CreateContextAttribs API then RenderDoc will completely refuse to capture, and will display overlay text to this effect using the simplest fixed-function pipeline code, so it will run on any OpenGL app, even on a 1.4 context or similar.
|
||||
|
||||
If your app did use the CreateContextAttribs API, RenderDoc will allow you to capture, but compatibility profiles will have a warning displayed in the overlay - this is because you could easily use old functionality as it is all still available in the context.
|
||||
|
||||
Can I tell via the graphics APIs if RenderDoc is present at runtime?
|
||||
--------------------------------------------------------------------
|
||||
|
||||
Yes indeed. Some APIs offer ways to do this already - D3DPERF_GetStatus(), ID3DUserDefinedAnnotation::GetStatus() and ID3D11DeviceContext2::IsAnnotationEnabled().
|
||||
|
||||
In addition to those:
|
||||
|
||||
Querying an ID3D11Device for UUID ``{A7AA6116-9C8D-4BBA-9083-B4D816B71B78}`` will return an IUnknown* and S_OK when RenderDoc is present.
|
||||
|
||||
`GL_EXT_debug_tool <https://renderdoc.org/debug_tool.txt>`_ is implemented on RenderDoc, which is an extension I've proposed for this purpose (identifying when and which tool is injected in your program). It allows you to query for the presence name and type of a debug tool that's currently hooked. At the time of writing only RenderDoc implements this as I've only just proposed the extension publicly, but in future you can use the queries described in that spec.
|
||||
|
||||
.. note::
|
||||
|
||||
It's unlikely the extension will ever be 'made official', so these enumerants can be used:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
#define GL_DEBUG_TOOL_EXT 0x6789
|
||||
#define GL_DEBUG_TOOL_NAME_EXT 0x678A
|
||||
#define GL_DEBUG_TOOL_PURPOSE_EXT 0x678B
|
||||
|
||||
A similar extension for Vulkan will be proposed after release.
|
||||
My shaders have 'cbuffer0' and unnamed variables, how do I get proper debug info?
|
||||
|
||||
If you get textures that are just named 'texture0' and 'texture1' or constant/uniform buffers named 'cbuffer2' then this indicates that you have stripped optional reflection/debug information out of your shaders.
|
||||
|
||||
This optional information is generated by the compiler, but is not required for API correctness so some codebases will strip the information out after processing it offline, and so it will not be available for RenderDoc to fetch.
|
||||
|
||||
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.
|
||||
|
||||
For details on this method, check out :doc:`tips_tricks`.
|
||||
@@ -0,0 +1,153 @@
|
||||
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 D3D11, OpenGL, and Vulkan on Windows and Linux, although the UI only runs on Windows currently. API support for other APIs such as D3D12 is planned. A Qt UI will be written to fully support Linux and in future OS X, but currently this is just at the drawing board stage.
|
||||
|
||||
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.
|
||||
|
||||
Current Windows+D3D11 Feature set
|
||||
---------------------------------
|
||||
|
||||
* Support for D3D11 and D3D11.1, Windows Vista and above.
|
||||
* Trimming capture - capture file only contains data necessary for replaying the frame in question, not all textures & buffers ever created in the lifetime of the app.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Multiple frame capture with ability to open side-by-side to compare.
|
||||
* Event browsing, with standard perfmarker style tree.
|
||||
* Full D3D11 Pipeline display.
|
||||
|
||||
* Resources bound to the pipeline are trimmed to what is actually in use, e.g. if a shader only references SRV slot 0, only SRV slot 0 will be displayed, even if something is bound to slot 1.
|
||||
* Where available D3D11 debug names are displayed, along with reflection data with the shader to clarify usage.
|
||||
* Structured buffers have their total element count displayed, and UAVs also show the current structure count.
|
||||
* Export of the pipeline to HTML file.
|
||||
|
||||
* Shader source display (where possible - i.e. debug info available).
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* 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'
|
||||
|
||||
* 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.
|
||||
* 'Raw' buffer inspection, e.g. for UAVs, VBs or other buffers. Custom format can be set with HLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* Currently set RT/textures thumbnail strip - updates as you move through the frame. Follows the currently selected pipeline slot as it changes, rather than remaining on the given texture.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* Several debug overlays for render targets - Wireframe, Depth pass/fail, Stencil pass/fail, Clipping (below black/above white points), NaN/-ve/INF highlight, quad overdraw.
|
||||
|
||||
* Pixel history view.
|
||||
* Custom visualisation shader support - e.g. decode custom packed formats or gbuffers.
|
||||
* Vertex, Pixel and Compute shader debugging.
|
||||
* 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.
|
||||
|
||||
Most of these should be intuitive if you've used a graphics debugger before.
|
||||
|
||||
Current OpenGL Feature set
|
||||
--------------------------
|
||||
|
||||
Most features are present and supported for both D3D11 and OpenGL, but some are still in development. Feature parity is an important goal, but for now we list them separately just to be clear.
|
||||
|
||||
* Support for OpenGL Core profile 3.2+ on Windows and Linux.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Event browsing, with standard ARB extension based tree.
|
||||
* Full OpenGL Pipeline display.
|
||||
|
||||
* Resources are shown on the stage that references them, so each shader stage shows a list of the resources, image read/writes, uniform buffers etc that it uses.
|
||||
* Where available ``KHR_debug`` glObjectLabel names are displayed, along with reflection data with the shader to clarify usage.
|
||||
|
||||
* Shader source display.
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* 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'
|
||||
|
||||
* 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 TES, 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.
|
||||
* 'Raw' buffer inspection, e.g. for SSBOs, VBs or other buffers. Custom format can be set with GLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* Currently set RT/textures thumbnail strip - updates as you move through the frame. Follows the currently selected pipeline slot as it changes, rather than remaining on the given texture.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* Several debug overlays for render targets - Wireframe, Depth pass/fail, Stencil pass/fail, Clipping (below black/above white points), NaN/-ve/INF highlight, quad overdraw.
|
||||
|
||||
* 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.
|
||||
|
||||
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.
|
||||
|
||||
Current Vulkan Feature set
|
||||
--------------------------
|
||||
|
||||
As Vulkan is still in early support, some features are not yet supported. Feature parity is an important goal, but for now we list them separately just to be clear.
|
||||
|
||||
* Support for Vulkan 1.0 on Windows and Linux.
|
||||
* Optional network support. The main use case is capture & replay on the same machine, but you can also attach over the network, and replay on a remote host.
|
||||
* Event browsing, with debug marker extension based tree.
|
||||
* Full Vulkan Pipeline display.
|
||||
|
||||
* Resources are shown on the stage that references them, so each shader stage shows a list of the resources that it uses. Uniform buffers are separated out for clarity, but all other resources are listed together along with their descriptor set and binding point.
|
||||
* Where available debug marker labelled names are displayed, along with reflection data from the SPIR-V to clarify usage.
|
||||
|
||||
* SPIR-V disassembly display.
|
||||
* Timeline bar of the scene hierarchy.
|
||||
|
||||
* 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'
|
||||
|
||||
* 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. 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.
|
||||
* 'Raw' buffer inspection, e.g. for SSBOs, VBs or other buffers. Custom format can be set with HLSL or GLSL-lite syntax.
|
||||
* Buffer export to CSV or raw binary blob and texture saving to DDS.
|
||||
* Texture/render target viewer.
|
||||
|
||||
* List of textures/RTs in the frame, and filtering system.
|
||||
* Standard visualisation controls - zoom/fit to window, mip/face/slice selection.
|
||||
* RGBA channels or depth/stencil selection as appropriate for the type of resource.
|
||||
* Flexible 'range' selection tool, to set custom black/white points (default to 0 and 1).
|
||||
* Currently set RT/textures thumbnail strip - updates as you move through the frame. Follows the currently selected pipeline slot as it changes, rather than remaining on the given texture.
|
||||
* Tabbed view for locking a view of a particular resource over time.
|
||||
* Pixel value picking.
|
||||
* Save (in theory) any type of texture and format to various formats, dds as well as regular png/jpg.
|
||||
* Several debug overlays for render targets - Wireframe, Depth pass/fail, Stencil pass/fail, Clipping (below black/above white points), NaN/-ve/INF highlight, quad overdraw.
|
||||
|
||||
* 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.
|
||||
|
||||
Capturing on Linux is possible, although there is no native UI. The renderdoccmd program allows capturing on the command line, as well as opening a 'preview' window of the final frame of the framebuffer.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../behind_scenes/planned_features`
|
||||
@@ -0,0 +1,33 @@
|
||||
Gotchas & Known Issues
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
|
||||
This page (hopefully) keeps up to date with any known issues, bugs, unimplemented or partially unimplemented features.
|
||||
|
||||
Things to Note
|
||||
--------------
|
||||
|
||||
* 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 <capture_options>` 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.
|
||||
|
||||
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_to_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>`.
|
||||
@@ -0,0 +1,349 @@
|
||||
In-application API
|
||||
==================
|
||||
|
||||
Reference for RenderDoc in-application API
|
||||
|
||||
|
||||
This page describes the RenderDoc API exposed to applications being captured, both in overall organisation as well as a specific reference on each function.
|
||||
|
||||
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
.. cpp:function:: void GetAPIVersion(int *major, int *minor, int *patch)
|
||||
|
||||
|
||||
This function returns the actual API version of the implementation returned. Version numbers follow `semantic versioning <http://semver.org/>`_ which means the implementation returned may have a higher minor and/or patch version than requested: New patch versions are identical and backwards compatible in functionality. New minor versions add new functionality in a backwards compatible way.
|
||||
|
||||
:param int* major: will be filled with the major version of the implementation's version.
|
||||
:param int* minor: will be filled with the minor version of the implementation's version.
|
||||
:param int* patch: which will be filled with the patch version of the implementation's version.
|
||||
:return: None
|
||||
|
||||
|
||||
.. cpp:function:: void SetCaptureOptionU32(RENDERDOC_CaptureOption opt, uint32_t val)
|
||||
|
||||
Set one of the options for tweaking some behaviours of capturing. Note that each option only takes effect from after it is set - so it is advised to set these options as early as possible, ideally before any graphics API has been initialised.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be set.
|
||||
:param uint32_t val: the unsigned integer value to set for the above option.
|
||||
:return: The function returns 1 if the option is valid, and the value set on the option is within valid ranges. The function returns 0 if the option is not a :cpp:enum:`RENDERDOC_CaptureOption` enum, or the value is not valid for the option.
|
||||
|
||||
.. cpp:function:: void SetCaptureOptionF32(RENDERDOC_CaptureOption opt, float val)
|
||||
|
||||
Set one of the options for tweaking some behaviours of capturing. Note that each option only takes effect from after it is set - so it is advised to set these options as early as possible, ideally before any graphics API has been initialised..
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be set.
|
||||
:param float val: the floating point value to set for the above option.
|
||||
:return: The function returns 1 if the option is valid, and the value set on the option is within valid ranges. The function returns 0 if the option is not a :cpp:enum:`RENDERDOC_CaptureOption` enum, or the value is not valid for the option.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_CaptureOption
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_AllowVSync
|
||||
|
||||
specifies whether the application is allowed to enable vsync. Default is on.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_AllowFullscreen
|
||||
|
||||
specifies whether the application is allowed to enter exclusive fullscreen. Default is on.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugDeviceMode
|
||||
|
||||
specifies whether (where possible) API-specific debugging is enabled. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureCallstacks
|
||||
|
||||
specifies whether each API call should save a callstack. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_CaptureCallstacksOnlyDraws
|
||||
|
||||
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.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_VerifyMapWrites
|
||||
|
||||
specifies whether any 'map' type resource memory updates should be bounds-checked for overruns. Default is off.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_HookIntoChildren
|
||||
|
||||
specifies whether child processes launched by the initial application should be hooked as well - commonly if a launcher process is needed to run the application. Default is off.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_SaveAllInitials
|
||||
|
||||
specifies whether all initial states of resources at the start of the frame should be saved, rather than omitting large resource contents which are detected to be likely unused. Default is off.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_CaptureOption::eRENDERDOC_Option_DebugOutputMute
|
||||
|
||||
specifies whether to mute any API debug output messages when `DebugDeviceMode` is enabled. Default is on.
|
||||
|
||||
|
||||
.. cpp:function:: uint32_t GetCaptureOptionU32(RENDERDOC_CaptureOption opt)
|
||||
|
||||
Gets the current value of one of the different options listed above in :cpp:func:`SetCaptureOptionU32`.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be retrieved.
|
||||
:return: The function returns the value of the capture option, if the option is a valid :cpp:enum:`RENDERDOC_CaptureOption` enum. Otherwise returns ``0xffffffff``.
|
||||
|
||||
.. cpp:function:: float GetCaptureOptionF32(RENDERDOC_CaptureOption opt)
|
||||
|
||||
Gets the current value of one of the different options listed above in :cpp:func:`SetCaptureOptionF32`.
|
||||
|
||||
:param RENDERDOC_CaptureOption opt: specifies which capture option should be retrieved.
|
||||
:return: The function returns the value of the capture option, if the option is a valid :cpp:enum:`RENDERDOC_CaptureOption` enum. Otherwise returns `-FLT_MAX`.
|
||||
|
||||
.. cpp:function:: void SetFocusToggleKeys(RENDERDOC_InputButton *keys, int num)
|
||||
|
||||
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 int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_InputButton
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_0..eRENDERDOC_Key_9
|
||||
|
||||
are the number keys. The values of these match ASCII for '0' .. '9'.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_A..eRENDERDOC_Key_Z
|
||||
|
||||
are the letter keys. The values of these match ASCII for 'A' .. 'Z'.
|
||||
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Divide
|
||||
|
||||
is the Divide key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Multiply
|
||||
|
||||
is the Multiply key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Subtract
|
||||
|
||||
is the Subtract key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Plus
|
||||
|
||||
is the Plus key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_F1
|
||||
|
||||
. eRENDERDOC_Key_F12` are the function keys.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Home
|
||||
|
||||
is the Home key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_End
|
||||
|
||||
is the End key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Insert
|
||||
|
||||
is the Insert key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Delete
|
||||
|
||||
is the Delete key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PageUp
|
||||
|
||||
is the PageUp key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PageDn
|
||||
|
||||
is the PageDn key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Backspace
|
||||
|
||||
is the Backspace key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Tab
|
||||
|
||||
is the Tab key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_PrtScrn
|
||||
|
||||
is the PrtScrn key.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_InputButton::eRENDERDOC_Key_Pause
|
||||
|
||||
is the Pause key.
|
||||
|
||||
.. cpp:function:: void SetCaptureKeys(RENDERDOC_InputButton *keys, int num)
|
||||
|
||||
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 int num: specifies the number of keys in the ``keys`` array. If 0, the keybinding is disabled.
|
||||
|
||||
.. cpp:function:: uint32_t GetOverlayBits()
|
||||
|
||||
This function returns the current mask which determines what sections of the overlay render on each window.
|
||||
|
||||
:return: A mask containing bits from :cpp:enum:`RENDERDOC_OverlayBits`.
|
||||
|
||||
.. cpp:enum:: RENDERDOC_OverlayBits
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_Enabled
|
||||
|
||||
is an overall enable/disable bit. If this is disabled, no overlay renders.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_FrameRate
|
||||
|
||||
shows the average, min and max frame time in milliseconds, and the average framerate.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_FrameNumber
|
||||
|
||||
shows the current frame number, as counted by the number of presents.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_CaptureList
|
||||
|
||||
shows how many total captures have been made, and a list of captured frames in the last few seconds.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_Default
|
||||
|
||||
is the default set of bits, which is the value of the mask at startup.
|
||||
|
||||
.. cpp:enumerator:: RENDERDOC_OverlayBits::eRENDERDOC_Overlay_All
|
||||
|
||||
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.
|
||||
|
||||
.. cpp:function:: void MaskOverlayBits(uint32_t And, uint32_t Or)
|
||||
|
||||
This function modifies the current mask which determines what sections of the overlay render on each window.
|
||||
|
||||
:param uint32_t And: is a 32-bit value the mask is binary-AND'd with before processing ``Or``.
|
||||
:param uint32_t Or: is a 32-bit value the mask is binary-OR'd with after processing ``And``.
|
||||
|
||||
.. cpp:function:: void Shutdown()
|
||||
|
||||
This function will attempt to shut down and remove RenderDoc and its hooks from the target process. It must be called as early as possible in the process, and will have undefined results if any graphics API functions have been called.
|
||||
|
||||
.. cpp:function:: void UnloadCrashHandler()
|
||||
|
||||
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)
|
||||
|
||||
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()
|
||||
|
||||
Get the current log file path template.
|
||||
|
||||
:return: the current capture path template as a UTF-8 null-terminated string.
|
||||
|
||||
.. cpp:function:: uint32_t GetNumCaptures()
|
||||
|
||||
This function returns the number of frame captures that have been made.
|
||||
:return: Returns 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)
|
||||
|
||||
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 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.
|
||||
|
||||
.. note::
|
||||
|
||||
It is advised to call this function twice - first to obtain ``pathlength`` so that sufficient space can be allocated. Then again to actually retrieve the path.
|
||||
|
||||
|
||||
The path follows the template set in :cpp:func:`SetLogFilePathTemplate` so it may not be an absolute path.
|
||||
|
||||
.. cpp:function:: void TriggerCapture()
|
||||
|
||||
This function will trigger a capture as if the user had pressed one of the capture hotkeys. The capture will be taken from the next frame presented to whichever window is considered current.
|
||||
|
||||
.. cpp:function:: uint32_t IsRemoteAccessConnected()
|
||||
|
||||
This function returns a value to indicate whether the RenderDoc UI is currently connected to the current process.
|
||||
|
||||
:return: Returns ``1`` if the RenderDoc UI is currently connected, or ``0`` otherwise.
|
||||
|
||||
.. cpp:function:: uint32_t LaunchReplayUI(uint32_t connectRemoteAccess, const char *cmdline)
|
||||
|
||||
This function will determine the closest matching replay UI executable for the current RenderDoc module and launch it.
|
||||
|
||||
:param uint32_t connectRemoteAccess: should be set to 1 if the UI should immediately connect to the application.
|
||||
:param const char* cmdline: is an optional UTF-8 null-terminated string to be appended to the command line, e.g. a capture filename. If this parameter is NULL, the command line will be unmodified.
|
||||
:return: If the UI was successfully launched, this function will return the PID of the new process. Otherwise it will return ``0``.
|
||||
|
||||
.. cpp:function:: void SetActiveWindow(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
This function will explicitly set which window is considered active. The active window is the one that will be captured when the keybind to trigger a capture is pressed.
|
||||
|
||||
:param RENDERDOC_DevicePointer device: is a handle to the API 'device' object that will be set active. Must be valid.
|
||||
:param RENDERDOC_WindowHandle wndHandle: is a handle to the platform window handle that will be set active. Must be valid.
|
||||
|
||||
.. note::
|
||||
|
||||
``RENDERDOC_DevicePointer`` is a typedef to ``void *``. The contents of it are API specific:
|
||||
|
||||
* For D3D11 it must be the ``ID3D11Device`` device object.
|
||||
* For OpenGL it must be the ``HGLRC`` or ``GLXContext`` context object.
|
||||
* For Vulkan it must be the dispatch table pointer within the ``VkInstance``. This is a pointer-sized value at the location pointed to by the ``VkInstance``. NOTE - this is not the actual ``VkInstance`` pointer itself.
|
||||
|
||||
``RENDERDOC_WindowHandle`` is a typedef to ``void *``. It is the platform specific ``HWND``, ``xcb_window_t``, or Xlib ``Window``.
|
||||
|
||||
.. cpp:function:: void StartFrameCapture(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
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.
|
||||
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
.. cpp:function:: uint32_t IsFrameCapturing()
|
||||
|
||||
This function returns a value to indicate whether the current frame is capturing.
|
||||
|
||||
:return: Returns ``1`` if the frame is currently capturing, or ``0`` otherwise.
|
||||
|
||||
.. cpp:function:: void EndFrameCapture(RENDERDOC_DevicePointer device, RENDERDOC_WindowHandle wndHandle)
|
||||
|
||||
This function will immediately end an active 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.
|
||||
|
||||
.. 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.
|
||||
|
||||
Wildcard matching of `device` and `wndHandle` is described above in :cpp:func:`BeginFrameCapture`.
|
||||
|
||||
There will be undefined results if there is not an active frame capture for the device/window combination.
|
||||
@@ -0,0 +1,12 @@
|
||||
Getting started
|
||||
===============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
faq
|
||||
gotchas_known_issues
|
||||
quick_start
|
||||
features
|
||||
tips_tricks
|
||||
in_application_api
|
||||
@@ -0,0 +1,191 @@
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
|
||||
This document serves as a brief introduction to how to use RenderDoc to capture and analyse your application. It doesn't go into much detail about exactly what functionality is available for digging into things, as this can be found elsewhere. Instead it focuses on just the workflow from start to finish and roughly where to look for different things.
|
||||
|
||||
For this tutorial we will be using a slightly modified version of the CascadedShadowMaps sample from the Microsoft DirectX SDK (June 2010).
|
||||
|
||||
Capturing a log
|
||||
---------------
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/QuickStart1.png
|
||||
|
||||
Capturing a Log
|
||||
|
||||
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.
|
||||
|
||||
More details of the specific options and their functionality can be found in the details page for the :doc:`capture_window`.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
It's best to choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa
|
||||
|
||||
You can only capture a 64-bit process with a 64-bit build of RenderDoc. A 32-bit process can be captured by any build of RenderDoc.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/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.
|
||||
|
||||
|
||||
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:`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!
|
||||
|
||||
RenderDoc layout
|
||||
----------------
|
||||
|
||||
RenderDoc's layout can be customised fairly heavily so this section will only cover the default layout. We'll go over the windows that are open by default and how each can be used in analysing your program.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/QuickStart3.png
|
||||
|
||||
The Texture Viewer
|
||||
|
||||
Texture Viewer
|
||||
--------------
|
||||
|
||||
More details can be found on the :doc:`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.
|
||||
|
||||
There are various visualisation controls that allow you to select different channels, mip levels or other aspects of the texture, and more detail is available in the above page. Here we'll just touch on the highlights:
|
||||
|
||||
* The thumbnail strip (by default to the right) lists either the output targets, or shader inputs bound and used at present. Selecting each of these (the red outline on the thumbnail indicating which is selected) will follow whatever resource is bound to that slot as you browse through the scene.
|
||||
|
||||
E.g. if you select render target 0 then the texture display will update to show the currently bound render target 0 regardless of which texture that is. If the slot you are following becomes unbound or unused, the previous texture will still be displayed up until you select a different pipeline slot, or the slot is bound again. Unbound texture slots show up with _Unbound_ listed under their thumbnail.
|
||||
|
||||
To open a specific texture and watch it even as it changes slots or becomes unbound, you can open it in a new locked tab. Right click on the thumbnail and 'open in new locked tab', or :doc:`open it by name <how_view_texture>`.
|
||||
|
||||
* The format and dimensions of the texture are displayed on the status bar just below the texture display itself.
|
||||
Also on this status bar you can see the current pixel co-ordinate that you are hovering over, as well as the 'picked' pixel value which can be inspected by right clicking anywhere on the texture display.
|
||||
|
||||
* Further to this, there is a small zoomed section of context around the last picked pixel available in the bottom right of the texture viewer window. From here you can also launch the pixel history or debugger, as detailed in :doc:`how_debug_shader`.
|
||||
|
||||
* The last thing we will highlight is the range control. This is a fairly flexible tool that allows you to adjust the visible range in the image. This is particular useful when viewing HDR images with a range outside of *[0, 1]*.
|
||||
|
||||
To use the range control you can drag the white and black points to make fine adjustments or type values to change the values of the white and black points (by default 0 and 1 respectively). There are also some useful controls to the right of the range control itself, which are detailed again in the :doc:`texture_viewer` page.
|
||||
|
||||
Event Browser
|
||||
`````````````
|
||||
|
||||
.. figure:: ../images/QuickStart4.png
|
||||
|
||||
The Event Browser
|
||||
|
||||
More details can be found on the :doc:`event_browser` page.
|
||||
|
||||
.. |timeline_marker| image:: ../images/timeline_marker.png
|
||||
|
||||
The Event Browser is the primary method of stepping through the frame and browsing the events that occurred within. The first column EID (Event ID) indicates which event or API call this was in the frame, chronologically. Events which are listed here are generally output/draw type events, including Clears. Copy and Map type calls are not included and are available in the API Calls view (see below).
|
||||
|
||||
The columns can be customised and reordered, the |timeline_marker| select columns button (or right-click) will allow you to choose which columns are displayed.
|
||||
|
||||
Standard performance markers are available and create the hierarchy/labels as you would expect. These can be expanded or collapsed and keyboard browsing is available through normal controls - left and right go higher or lower in the hierarchy, and up and down goes up and down through siblings.
|
||||
|
||||
.. |flag_green| image:: ../images/flag_green.png
|
||||
.. |find| image:: ../images/find.png
|
||||
.. |asterisk_orange| image:: ../images/asterisk_orange.png
|
||||
|
||||
The 'current' event - i.e. the event at which we are inspecting the graphics state - is highlighted with a green Flag |flag_green| and the row is highlighted. As any row is selected it immediately becomes the new current event.
|
||||
|
||||
While the Event Browser is selected, you can press the shortcut keys :kbd:`CTRL-F` or :kbd:`CTRL-G` to find |find| or jump to a given EID |flag_green| respectively.
|
||||
|
||||
|
||||
The |asterisk_orange| bookmark button will allow you to bookmark an event, the shortcut key is :kbd:`CTRL-B`.
|
||||
|
||||
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.
|
||||
|
||||
API Inspector
|
||||
`````````````
|
||||
|
||||
.. figure:: ../images/QuickStart5.png
|
||||
|
||||
The API Calls + Callstack Panel
|
||||
|
||||
More details can be found on the :doc:`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.
|
||||
|
||||
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_capture_callstack`.
|
||||
|
||||
Timeline Bar
|
||||
````````````
|
||||
|
||||
.. figure:: ../images/QuickStart6.png
|
||||
|
||||
The Timeline Bar
|
||||
|
||||
More details can be found on the :doc:`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 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.
|
||||
|
||||
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.
|
||||
|
||||
This can be a very useful tool to trace data through a frame, as well as highlighting potential redundancy or errors if a target is being written to where it should not.
|
||||
|
||||
Pipeline State
|
||||
``````````````
|
||||
|
||||
.. figure:: ../images/QuickStart7.png
|
||||
|
||||
The Pipeline State Viewer
|
||||
|
||||
More details can be found on the :doc:`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:: ../images/GoArrow.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.
|
||||
|
||||
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.
|
||||
|
||||
For more details, check out the how-to: :doc:`how_view_object`.
|
||||
|
||||
Mesh Output
|
||||
```````````
|
||||
|
||||
.. figure:: ../images/QuickStart8.png
|
||||
|
||||
Mesh Output Viewer
|
||||
|
||||
More details can be found on the :doc:`mesh_view` page.
|
||||
|
||||
.. |undo_arrow| image:: ../images/UndoArrow.png
|
||||
.. |cog| image:: ../images/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.
|
||||
|
||||
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.
|
||||
|
||||
Closing Notes
|
||||
-------------
|
||||
|
||||
Obviously what you accomplish in the program will vary a lot by what you need to investigate, but hopefully this gives you an overview of the functionality available. There are many more detailed features that are available, and the rest of this help will aid you in finding those.
|
||||
|
||||
It is probably a good idea to check out the :doc:`tips_tricks` page which lists several useful notes that aren't obvious but might save you a lot of time.
|
||||
@@ -0,0 +1,94 @@
|
||||
Tips & Tricks
|
||||
=============
|
||||
|
||||
.. |go_arrow| image:: ../images/GoArrow.png
|
||||
.. |wand| image:: ../images/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:`option_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.
|
||||
#. 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:`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:`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.
|
||||
#. You can double click on a thumbnail in the texture viewer to open a :doc:`locked texture <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:
|
||||
|
||||
.. 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 renderdoc_app.h header in the source code.
|
||||
|
||||
#. When you have right clicked to select a pixel in the texture viewer, you can perform precise refinements with the arrow keys to nudge the selection in each direction.
|
||||
#. To get API debug or error messages, enable "Create Debug Device" when capturing then check out the :doc:`debug_messages` window.
|
||||
#. 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:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
// For D3D11:
|
||||
ID3D11Device *devicePointer = ...;
|
||||
IUnknown *unk = NULL;
|
||||
HRESULT hr = devicePointer->QueryInterface(MAKE_GUID({A7AA6116-9C8D-4BBA-9083-B4D816B71B78}), &unk);
|
||||
if(SUCCEEDED(hr)) { /* renderdoc is present; */ }
|
||||
|
||||
// For OpenGL:
|
||||
// if GL_EXT_debug_tool is present (see https://renderdoc.org/debug_tool.txt)
|
||||
glIsEnabled(GL_DEBUG_TOOL_EXT);
|
||||
|
||||
// Until enumerants are assigned (if that ever happens):
|
||||
#define GL_DEBUG_TOOL_EXT 0x6789
|
||||
#define GL_DEBUG_TOOL_NAME_EXT 0x678A
|
||||
#define GL_DEBUG_TOOL_PURPOSE_EXT 0x678B
|
||||
|
||||
#. RenderDoc can be informed about separated debug shader blobs through API specific ways:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
// For D3D11:
|
||||
GUID RENDERDOC_ShaderDebugMagicValue = RENDERDOC_ShaderDebugMagicValue_value; // GUID value in renderdoc_app.h
|
||||
|
||||
ID3D11VertexShader *shader = ...;
|
||||
std::string pathName = ...; // path name is in UTF-8
|
||||
|
||||
// string parameter must be NULL-terminated, and in UTF-8
|
||||
shader->SetPrivateData(RENDERDOC_ShaderDebugMagicValue, (UINT)pathName.length(), pathName.c_str());
|
||||
|
||||
// Alternatively at build time:
|
||||
struct { GUID guid; char name[MAX_PATH]; } path;
|
||||
|
||||
path.guid = RENDERDOC_ShaderDebugMagicValue;
|
||||
// must include NULL-terminator, and be in UTF-8
|
||||
memcpy(path.name, debugPath.c_str(), debugPath.length() + 1);
|
||||
|
||||
size_t pathSize = sizeof(GUID) + debugPath.length() + 1;
|
||||
|
||||
D3DSetBlobPart(strippedBlob->GetBufferPointer(), strippedBlob->GetBufferSize(), D3D_BLOB_PRIVATE_DATA, 0, &path, pathSize, &annotatedBlob);
|
||||
// use annotatedBlob instead of strippedBlob from here on
|
||||
|
||||
#. More coming soon hopefully :).
|
||||
Reference in New Issue
Block a user