mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-04 09:00:44 +00:00
Add all How do I ...? pages.
This commit is contained in:
Matthäus G. Chajdas
committed by
baldurk
baldurk
parent
c04dd86d8d
commit
925f33bfb5
@@ -0,0 +1,51 @@
|
||||
How do I capture callstacks?
|
||||
============================
|
||||
|
||||
This page gives an overview of the callstack-capturing capability in RenderDoc, with details and important information about how to enable this.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
It can be useful when tracking down problems to have an idea of where each API call came from. In any non-trivial program it's not necessarily obvious where every single call was made, and giving a code-side callstack up to the API entry point can pinpoint errant calls that are causing problems.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. note::
|
||||
|
||||
Callstack gathering has a reasonable overhead during capture and can slow things down as well as cause more memory overhead. This can be mitigated with the 'only drawcall callstacks' option that only lists callstacks for each drawcall event.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/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.
|
||||
|
||||
Replaying the capture
|
||||
---------------------
|
||||
|
||||
When the capture is loaded in RenderDoc the callstacks will be available in the API inspector. The bottom section of the dialog is a panel that can be expanded to show the callstack. Initially this section will indicate that symbols need to be resolved.
|
||||
|
||||
.. figure:: ../images/NeedResolve.png
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
By default a symbol server will be used, as well as a few default locations such as the location indicated in the PE metadata (i.e. the original build location). If a pdb cannot be found you will be prompted for the location of the pdb, and this new location will then be remembered for subsequent pdbs.
|
||||
|
||||
.. figure:: ../images/NeedPDB.png
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,62 @@
|
||||
How do I capture a log?
|
||||
=======================
|
||||
|
||||
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` window.
|
||||
|
||||
Capturing logs
|
||||
--------------
|
||||
|
||||
The basic process of capturing logs is fairly straightforward.
|
||||
|
||||
Opening the capture window from the menus via File -> Capture Log, the typical capture setup simply requires you to enter the executable location.
|
||||
|
||||
By default the working directory remains empty and defaults to the directory that contains the executable location.
|
||||
|
||||
.. figure:: ../images/CapturePathCmdline.png
|
||||
|
||||
Capturing: Capturing a logfile specifying its executable path and command line.
|
||||
|
||||
Likewise, the default options generally work well for most situations, however there are a few common options to customise:
|
||||
|
||||
* Allow Fullscreen/Allow VSync aid in debugging by preventing the app from switching into fullscreen (or vsynced) display modes, which makes them easier to attach to from a debugger on the same computer.
|
||||
* Seconds attach delay causes RenderDoc to pause for a certain number of seconds after launching the process to allow you to attach in the debugger - so that the debugger can be present to catch any problems from the beginning of the application, in case there is an issue very early in initialisation.
|
||||
* Collect callstacks allows you to get callstacks at the site of each API. There are more details available in :doc:`how_capture_callstack`.
|
||||
|
||||
Injecting into a Process
|
||||
------------------------
|
||||
|
||||
It is possible to inject to an already running process. By selecting the "Inject to Process" entry in the File menu, the capture dialog will modify to list the running processes rather than asking for an executable and command line parameters.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/Injecting.png
|
||||
|
||||
Injecting to a selected existing process.
|
||||
|
||||
.. warning::
|
||||
|
||||
The important thing to note about injecting is that RenderDoc can only inject to processes that **have not initialised or used the target API**. If this is the case RenderDoc can insert its hooks before any use of the API and work as normal. If the API has been used or initialised the results are undefined and likely RenderDoc will simply not function as it's too late to hook in.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If RenderDoc is not running as administrator, it cannot inject into processes that are running with elevated permissions. In this case you can either run RenderDoc as administrator (not recommended unless necessary), or re-run the process as the normal user running RenderDoc.
|
||||
|
||||
Capture setting files
|
||||
---------------------
|
||||
|
||||
Commonly in development, the capture parameters don't change. In fact most likely the same application or couple of applications are launched in exactly the same way repeatedly as development iterates.
|
||||
|
||||
To make this process easier RenderDoc supports saving and loading configuration sets to a file. While on the capture dialog, click 'Save' to save to a .cap file which contains both the executable, working directory and command line - as well as the options that are selected.
|
||||
|
||||
This .cap file can be executed when RenderDoc's file associations are set up, and RenderDoc will load this file and present you with the capture dialog on startup.
|
||||
|
||||
You can also use the "Auto start" option - when this option is enabled then a .cap file will immediately launch the program when it is loaded. This can allow you to configure a .cap which will open RenderDoc and launch the target application with the pre-configured settings in one click. If you wish to disable this, just uncheck the option and re-save to the same .cap file.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../window/capture_log`
|
||||
@@ -0,0 +1,205 @@
|
||||
How do I use a custom visualisation shader?
|
||||
===========================================
|
||||
|
||||
This page details how to set up a custom shader for visualisation. This can be used in the :doc:`../window/texture_viewer` to unpack or decode complex formats, or simply apply a custom complex transformation to the image beyond the default controls.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Predefined inputs
|
||||
-----------------
|
||||
|
||||
There are several pre-defined inputs that can either be taken as parameters to the shader entry point, or defined as global variables with a particular name that will then be filled in. There are also definitions for the different type of input textures.
|
||||
|
||||
.. warning::
|
||||
|
||||
Type and capitalisation is important for these variables, so ensure you use the right declaration!
|
||||
|
||||
The shader editor when using the UI can be used to insert these snippets for you, with the right type and spelling. Be careful for GL though, as these snippets are inserted at the top of the file and so are inserted before the #version statement.
|
||||
|
||||
UV co-ordinates (D3D11 only)
|
||||
````````````````````````````
|
||||
|
||||
.. code:: c
|
||||
|
||||
float4 main(float4 pos : SV_Position, float4 uv : TEXCOORD0) : SV_Target0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
|
||||
This input is defined as two parameters to the shader entry point. The first defines the usual SV_Position system semantic, and the first two components of the second TEXCOORD0 parameter gives UV co-ordinates from 0 to 1 in each dimension over the size of the texture (or texture slice).
|
||||
|
||||
.. note::
|
||||
|
||||
You must bind these parameters like this in this order to ensure the linkage with the vertex shader matches.
|
||||
|
||||
Texture dimensions
|
||||
``````````````````
|
||||
|
||||
.. code:: c
|
||||
|
||||
uint4 RENDERDOC_TexDim; // hlsl
|
||||
uvec4 RENDERDOC_TexDim; // glsl
|
||||
|
||||
|
||||
This variable will be filled out with the following values:
|
||||
|
||||
* ``.x =`` Width
|
||||
* ``.y =`` Height (if 2D or 3D)
|
||||
* ``.z =`` Depth if 3D or array size if an array
|
||||
* ``.w =`` Number of mip levels
|
||||
|
||||
Selected Mip level
|
||||
``````````````````
|
||||
|
||||
.. code:: c
|
||||
|
||||
uint RENDERDOC_SelectedMip;
|
||||
|
||||
This variable will be filled out with the selected mip level in the UI.
|
||||
|
||||
Current texture type
|
||||
````````````````````
|
||||
|
||||
.. code:: c
|
||||
|
||||
uint RENDERDOC_TextureType;
|
||||
|
||||
|
||||
This variable will be set to a given integer value, depending on the type of the current texture being displayed. This can be used to sample from the correct resource.
|
||||
|
||||
.. note::
|
||||
|
||||
The value varies depending on whether this is an HLSL shader or GLSL, as they have different resource types.
|
||||
|
||||
D3D11 / HLSL
|
||||
^^^^^^^^^^^^
|
||||
|
||||
#. 1D texture
|
||||
#. 2D texture
|
||||
#. 3D texture
|
||||
#. Depth
|
||||
#. Depth + Stencil
|
||||
#. Depth (Multisampled)
|
||||
#. Depth + Stencil (Multisampled)
|
||||
#. Cubemap
|
||||
#. 2D texture (Multisampled)
|
||||
|
||||
OpenGL / GLSL
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
#. 1D texture
|
||||
#. 2D texture
|
||||
#. 3D texture
|
||||
#. Cubemap
|
||||
#. 1D array texture
|
||||
#. 2D array texture
|
||||
#. Cubemap array
|
||||
#. Rectangle
|
||||
#. Buffer texture
|
||||
#. 2D texture (Multisampled)
|
||||
|
||||
Samplers (D3D11 only)
|
||||
`````````````````````
|
||||
|
||||
.. code:: c
|
||||
|
||||
SamplerState pointSampler : register(s0);
|
||||
SamplerState linearSampler : register(s1);
|
||||
|
||||
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 / HLSL
|
||||
^^^^^^^^^^^^
|
||||
|
||||
.. code:: c++
|
||||
|
||||
Texture1DArray<float4> texDisplayTex1DArray : register(t1);
|
||||
Texture2DArray<float4> texDisplayTex2DArray : register(t2);
|
||||
Texture3D<float4> texDisplayTex3D : register(t3);
|
||||
Texture2DArray<float2> texDisplayTexDepthArray : register(t4);
|
||||
Texture2DArray<uint2> texDisplayTexStencilArray : register(t5);
|
||||
Texture2DMSArray<float2> texDisplayTexDepthMSArray : register(t6);
|
||||
Texture2DMSArray<uint2> texDisplayTexStencilMSArray : register(t7);
|
||||
Texture2DArray<float4> texDisplayTexCubeArray : register(t8);
|
||||
Texture2DMSArray<float4> texDisplayTex2DMSArray : register(t9);
|
||||
|
||||
Texture1DArray<uint4> texDisplayUIntTex1DArray : register(t11);
|
||||
Texture2DArray<uint4> texDisplayUIntTex2DArray : register(t12);
|
||||
Texture3D<uint4> texDisplayUIntTex3D : register(t13);
|
||||
Texture2DMSArray<uint4> texDisplayUIntTex2DMSArray : register(t19);
|
||||
|
||||
Texture1DArray<int4> texDisplayIntTex1DArray : register(t21);
|
||||
Texture2DArray<int4> texDisplayIntTex2DArray : register(t22);
|
||||
Texture3D<int4> texDisplayIntTex3D : register(t23);
|
||||
Texture2DMSArray<int4> texDisplayIntTex2DMSArray : register(t29);
|
||||
|
||||
OpenGL / GLSL
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. code:: c
|
||||
|
||||
// Unsigned int samplers
|
||||
layout (binding = 1) uniform usampler1D texUInt1D;
|
||||
layout (binding = 2) uniform usampler2D texUInt2D;
|
||||
layout (binding = 3) uniform usampler3D texUInt3D;
|
||||
// skip cube = 4
|
||||
layout (binding = 5) uniform usampler1DArray texUInt1DArray;
|
||||
layout (binding = 6) uniform usampler2DArray texUInt2DArray;
|
||||
// skip cube array = 7
|
||||
layout (binding = 8) uniform usampler2DRect texUInt2DRect;
|
||||
layout (binding = 9) uniform usamplerBuffer texUIntBuffer;
|
||||
layout (binding = 10) uniform usampler2DMS texUInt2DMS;
|
||||
|
||||
// Int samplers
|
||||
layout (binding = 1) uniform isampler1D texSInt1D;
|
||||
layout (binding = 2) uniform isampler2D texSInt2D;
|
||||
layout (binding = 3) uniform isampler3D texSInt3D;
|
||||
// skip cube = 4
|
||||
layout (binding = 5) uniform isampler1DArray texSInt1DArray;
|
||||
layout (binding = 6) uniform isampler2DArray texSInt2DArray;
|
||||
// skip cube array = 7
|
||||
layout (binding = 8) uniform isampler2DRect texSInt2DRect;
|
||||
layout (binding = 9) uniform isamplerBuffer texSIntBuffer;
|
||||
layout (binding = 10) uniform isampler2DMS texSInt2DMS;
|
||||
|
||||
// Floating point samplers
|
||||
layout (binding = 1) uniform sampler1D tex1D;
|
||||
layout (binding = 2) uniform sampler2D tex2D;
|
||||
layout (binding = 3) uniform sampler3D tex3D;
|
||||
layout (binding = 4) uniform samplerCube texCube;
|
||||
layout (binding = 5) uniform sampler1DArray tex1DArray;
|
||||
layout (binding = 6) uniform sampler2DArray tex2DArray;
|
||||
layout (binding = 7) uniform samplerCubeArray texCubeArray;
|
||||
layout (binding = 8) uniform sampler2DRect tex2DRect;
|
||||
layout (binding = 9) uniform samplerBuffer texBuffer;
|
||||
layout (binding = 10) uniform sampler2DMS tex2DMS;
|
||||
|
||||
|
||||
These resources are bound sparsely with the appropriate type for the current texture. With a couple of exceptions there will only be one texture bound at any one time.
|
||||
|
||||
When a cubemap texture is bound, it is bound both to the 2D Array as well as the Cube Array. If a depth-stencil texture has both components, the relevant depth and stencil resources will both be bound at once.
|
||||
|
||||
To determine which resource to sample from you can use the RENDERDOC_TexType variable above.
|
||||
|
||||
Usually the float textures are used, but for unsigned and signed integer formats, the relevant integer resources are used.
|
||||
|
||||
As with the samplers, these textures are bound by slot and not by name, so while you are free to name the variables as you wish, you must bind them explicitly to the slots listed here.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
* :doc:`../window/texture_viewer`
|
||||
@@ -0,0 +1,117 @@
|
||||
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.
|
||||
|
||||
Including debug info in shaders
|
||||
-------------------------------
|
||||
|
||||
For the most part at least some debug information is included with shaders unless it is being explicitly stripped out at some point. There is usually an option to also include additional debug information - such as original source code in a high-level language. The exact process varies by API, but for D3D11 the flag ``/Zi`` to fxc or the equivalent flag to D3DCompile() will include additional debugging information, and ``/Qstrip_debug`` and ``/Qstrip_reflection`` will remove reflection information that can be useful - such as the names of variables in constant buffers.
|
||||
|
||||
Debugging a vertex
|
||||
------------------
|
||||
|
||||
Vertex debugging is invoked from the mesh viewer. With the mesh viewer open you can select the input vertex you wish to debug.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/VertexDebug.png
|
||||
|
||||
Vertex Debugging: Launching vertex debugging from the mesh viewer.
|
||||
|
||||
From here the debugger will open with the vertex shader in the shader debugger. The inputs are automatically filled in from the mesh data.
|
||||
|
||||
.. note::
|
||||
|
||||
Geometry and tessellation shaders are not yet debuggable.
|
||||
|
||||
Debugging a Pixel
|
||||
-----------------
|
||||
|
||||
Pixel debugging is launched from the texture viewer. For more details on selecting the pixel to debug see :doc:`how_inspect_pixel`.
|
||||
|
||||
When a given pixel is selected you can click the debug button underneath the pixel context. This will launch the shader viewer with the selected pixel and sample being debugged. The inputs to the pixel will be automatically filled in.
|
||||
|
||||
There are a couple of things to note while pixel debugging:
|
||||
|
||||
* If the drawcall selected doesn't write to the pixel you have highligted, a pixel history window will open to let you choose which draw call to debug.
|
||||
* If a drawcall overdraws the same pixel several times then the results of debugging will come from the last fragment that passed the depth test. If you wish to choose a particular fragment from the list then first launch the pixel history and choose which fragment to debug from the list there.
|
||||
|
||||
Debugging a Compute thread
|
||||
--------------------------
|
||||
|
||||
To debug a compute thread simply go to the compute shader section of the pipeline state viewer and enter the group and thread ID of the thread you would like to debug. This thread will be debugged in isolation as with any other shader invocation.
|
||||
|
||||
This means there can be no synchronisation with any other compute thread running and the debugging will run from start to finish as if no other thread had run.
|
||||
|
||||
.. warning::
|
||||
|
||||
This feature is **highly** experimental and is provided with no guarantees yet! It may work on simple shaders which is why it is available.
|
||||
|
||||
Debugging Controls
|
||||
------------------
|
||||
|
||||
When debugging, at the moment the controls are fairly basic.
|
||||
|
||||
.. figure:: ../images/ShaderControls.png
|
||||
|
||||
Shader controls: Controls for stepping through shaders.
|
||||
|
||||
.. |runfwd| image:: ../images/runfwd.png
|
||||
.. |runback| image:: ../images/runback.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 keyboard shortcuts for these controls are :kbd:`F5` and :kbd:`Shift-F5` respectively.
|
||||
|
||||
You can set a breakpoint by pressing F9 (this will also remove a breakpoint that is already there). When running in each direction or to cursor (see below) if execution hits a breakpoint it will stop.
|
||||
|
||||
.. |stepnext| image:: ../images/stepnext.png
|
||||
.. |stepprev| image:: ../images/stepprev.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.
|
||||
|
||||
|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`
|
||||
|
||||
.. |runcursor| image:: ../images/runcursor.png
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
The highlighted instruction at any given point indicates the *next* instruction to be executed - not the instruction that was just executed.
|
||||
|
||||
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.
|
||||
|
||||
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:: ../images/ShaderConsts.png
|
||||
|
||||
Constants window: Constant, input and resource registers.
|
||||
|
||||
The other window will contain variable/mutable registers. These contain temporaries that are typically allocated up front and will update as you step through the execution of the shader. This window also contains the output registers.
|
||||
|
||||
.. figure:: ../images/ShaderRegs.png
|
||||
|
||||
Variable window: Variable registers - temporaries and outputs.
|
||||
|
||||
The final window is initially empty but can be filled out as needed. This shows custom watch expressions and their values. Here you can write any expression involving an input, temporary or output register along with a swizzle and typecast.
|
||||
|
||||
Swizzles follow the standard hlsl rules - .[xyzw] or .[rgba] in any permutation or repetition will show those channels.
|
||||
|
||||
The custom typecast can be any of ,x ,i ,d ,f ,u ,b to display the register as hex, signed integer, double, float, unsigned, or bitwise respectively.
|
||||
|
||||
.. figure:: ../images/ShaderWatch.png
|
||||
|
||||
Watch window: Watch window - custom register expressions evaluated.
|
||||
@@ -0,0 +1,52 @@
|
||||
How do I edit a shader?
|
||||
=======================
|
||||
|
||||
|
||||
.. |page_white_edit| image:: ../images/page_white_edit.png
|
||||
|
||||
This page details how to edit shaders. This applies both to :doc:`custom visualisation shaders <how_custom_visualisation>` for the :doc:`../window/texture_viewer`, but can also be used to temporarily replace or edit a shader used in the actual scene.
|
||||
|
||||
How to edit a custom shader
|
||||
---------------------------
|
||||
|
||||
:doc:`Custom visualisation shaders <how_custom_visualisation>` allow you to define your own transformation on any texture you're viewing before it is displayed. Mostly this is useful for decoding packed or custom-format data, or displaying some data in a more visually intuitive fashion.
|
||||
|
||||
These shaders live as .hlsl/.glsl files in ``%APPDATA%\RenderDoc\``, and can be edited in your editor of choice, any changes saved will be reloaded. Note however that there is currently no way to see the compile warnings or errors produced. This is probably best for when you have an existing shader to drop-in.
|
||||
|
||||
To edit a shader inside RenderDoc simply click the edit button |page_white_edit| when you have selected your custom shader for use. This will launch a new window with the custom shader and any changes you make to this shader will be saved to the .hlsl/.glsl file and compiled and reflected in the texture viewer as long as you have that custom shader selected.
|
||||
|
||||
How to edit a scene shader
|
||||
--------------------------
|
||||
|
||||
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.
|
||||
|
||||
This can also interact badly with another artifact - macro definitions passed directly to the compiler are not included in the debug info and so RenderDoc can't include them when recompiling. If you rely on any defines, you will need to add them manually to the top of your root hlsl file.
|
||||
|
||||
|
||||
Using the built-in shader editor
|
||||
--------------------------------
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
.. warning::
|
||||
|
||||
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.
|
||||
|
||||
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`
|
||||
@@ -0,0 +1,65 @@
|
||||
How do I inspect a pixel value?
|
||||
===============================
|
||||
|
||||
When in the texture viewer you can inspect the pixel values to obtain the exact contents of any pixel in the texture.
|
||||
|
||||
Selecting appropriate subresource
|
||||
---------------------------------
|
||||
|
||||
More details can be found in the :doc:`../window/texture_viewer` page, but the first step is to select the appropriate subresource - array element, cubemap face or mip slice.
|
||||
|
||||
The values that are picked out of the texture are always exact values, and will not be affected by the currently selected channels or range adaption control.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/HoverStatus.png
|
||||
|
||||
Hover Status Bar: The status bar showing position and colour
|
||||
|
||||
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/option`.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/RMBStatus.png
|
||||
|
||||
Picked Pixel: The value of a pixel that has been picked
|
||||
|
||||
If the right mouse button is just clicked, the picked pixel value will remain with the same value as the mouse moves. If you hold the right mouse button and drag, it will update as the mouse moves to allow some amount of refinement.
|
||||
|
||||
To make fine adjustments by a single pixel at a time, it's easiest to use the arrow keys on the keyboard. Pressing these will shift the picked location by a single pixel in each direction.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../images/PixelContext.png
|
||||
|
||||
Pixel Context: The zoomed in context around the pixel currently selected
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
You can expand each event to see if there were multiple fragments, and see the shader output value from each fragment.
|
||||
|
||||
Right clicking will allow you to launch the shader debugger at the given event for the selected pixel. If you select a particular fragment or primitive, this will be the fragment that is debugged.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../window/texture_viewer`
|
||||
@@ -0,0 +1,78 @@
|
||||
How do I view details of an object?
|
||||
===================================
|
||||
|
||||
.. toctree::
|
||||
|
||||
|
||||
|
||||
.. |goarrow| image:: ../images/GoArrow.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.
|
||||
|
||||
Viewing Shaders
|
||||
---------------
|
||||
|
||||
Each shader stage that is active on the pipeline can be expanded to see both the high-level shader language and the low-level disassembly. At the top of the pipeline stage there is a box showing the currently bound shader - by its entry point if known.
|
||||
|
||||
.. figure:: ../images/CurrentShader.png
|
||||
|
||||
Bound Shader: Box showing the currently used shader.
|
||||
|
||||
Much of the information that is available from the shader is only available when debugging information is made available. :doc:`More details are available <how_debug_shader>`.
|
||||
|
||||
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.
|
||||
|
||||
If available, the reflection data from the shader debugging information will be used in other areas of the pipeline state viewer. It will be used for naming texture slots, showing which resources that are bound are to be used in the shader, as well as showing the names of any constants that are used in the shader.
|
||||
|
||||
When this shader reflection information is available it will be integrated into the disassembly to make it easier to read.
|
||||
|
||||
.. |page_white_edit| image:: ../images/page_white_edit.png
|
||||
|
||||
Note from here you can also :doc:`live-edit a shader <how_edit_shader>` by clicking the edit button |page_white_edit|. If debug info isn't available to provide HLSL, a basic stub function with the input & output signatures but no body will be created.
|
||||
|
||||
Viewing Textures
|
||||
----------------
|
||||
|
||||
The :doc:`../window/texture_viewer` is the primary way of viewing details of textures, so this section concerns itself with how textures are displayed in other parts of the UI, and how to open a texture in the texture viewer. More details can be found in :doc:`how_view_texture`.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
This layout can be customised by entering a format in a simple style that mimics defining a structure that outlines a single element in the buffer.
|
||||
|
||||
.. figure:: ../images/RawBuffer.png
|
||||
|
||||
Custom Buffer Layout: Customising the layout of the buffer by defining a structure.
|
||||
|
||||
.. note::
|
||||
|
||||
This window supports copy and paste, so simply select the entries and ctrl-c to copy to the clipboard
|
||||
|
||||
Viewing Constant Buffers
|
||||
------------------------
|
||||
|
||||
Constant buffers can be viewed by clicking on their Go Arrow |goarrow|. This will open up a new docked section to the right of the pipeline state viewer that tracks that constant buffer slot.
|
||||
|
||||
Whenever this shader slot has a constant buffer in it, both the constant names and types as well as values will be displayed.
|
||||
|
||||
.. figure:: ../images/CBuffer.png
|
||||
|
||||
Constant Buffer: An updating preview of the contents of this constant buffer.
|
||||
|
||||
.. note::
|
||||
|
||||
This window supports copy and paste, so simply select the entries and ctrl-c to copy to the clipboard
|
||||
@@ -0,0 +1,73 @@
|
||||
How do I view a specific texture?
|
||||
=================================
|
||||
|
||||
This page documents how to annotate your resources with user-friendly names to make it easier to follow use of them throughout the frame, as well as the functions for finding and following textures by name rather than by usage.
|
||||
|
||||
Annotating resources with names
|
||||
-------------------------------
|
||||
|
||||
It is much easier to browse and debug frames when the resources are given meaningful names - along with including :doc:`debugging information in shaders <how_debug_shader>` and marking up the frame with :doc:`hierarchical user-defined regions <../window/event_browser>`.
|
||||
|
||||
The way this is done varies by API. In D3D11 the resource is named in this way:
|
||||
|
||||
.. code:: c++
|
||||
|
||||
// Creating an example resource - a 2D Texture.
|
||||
ID3D11Texture2D *tex2d = NULL;
|
||||
d3dDevice->CreateTexture2D(&descriptor, NULL, &tex2d);
|
||||
|
||||
// Give the buffer a useful name
|
||||
tex2d->SetPrivateData(WKPDID_D3DDebugObjectName, "Example Texture", sizeof("Example Texture"));
|
||||
|
||||
In OpenGL this can be done with ``GL_KHR_debug`` - ``glObjectLabel``.
|
||||
|
||||
When this texture is bound to the pipeline it will be listed like so:
|
||||
|
||||
.. figure:: ../images/NamedTex.png
|
||||
|
||||
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.
|
||||
|
||||
Texture list in Texture Viewer
|
||||
------------------------------
|
||||
|
||||
.. |page_white_link| image:: ../images/page_white_link.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.
|
||||
|
||||
.. figure:: ../images/TexList.png
|
||||
|
||||
Texture list: The sidebar showing the list of textures
|
||||
|
||||
This list of textures can be filtered by a custom string which will narrow the list of textures displayed, or simply by their creation flags as either a render target or a texture.
|
||||
|
||||
When selecting and opening one of the textures from here, a new tab is opened in the texture viewer that follows that texture.
|
||||
|
||||
Locked tab of a Texture
|
||||
-----------------------
|
||||
|
||||
By default the tab open in the texture viewer follows whichever pipeline slot is currently selected. When a new event is selected this tab can display a new texture if the contents of that slot has changed.
|
||||
|
||||
If you want to follow a particular texture even as it becomes unbound or moves from output to input and vice versa, you can open a new locked tab that will stay consistently on this texture.
|
||||
|
||||
.. figure:: ../images/CurrentVsLockedTab.png
|
||||
|
||||
Texture Tabs: Default tab following pipeline slot vs Locked tab.
|
||||
|
||||
This can be done by locating the texture by name as above, then clicking on the entry in the list. This will open up a new tab for this texture which will not change regardless of the current pipeline state, or current event.
|
||||
|
||||
|
||||
Opening a texture from the pipeline state viewer (:doc:`how_object_details`) will also open a new locked tab for the texture in question. You can also open a new locked tab by right clicking on the texture thumbnail while it is currently bound.
|
||||
|
||||
.. figure:: ../images/OpenLockedTab.png
|
||||
|
||||
Opening new Tab: Opening a new locked tab for a texture.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
Other Resources
|
||||
```````````````
|
||||
|
||||
* :doc:`../window/texture_viewer`
|
||||
@@ -0,0 +1,13 @@
|
||||
How do I ...?
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
|
||||
how_debug_shader
|
||||
how_capture_log
|
||||
how_inspect_pixel
|
||||
how_view_texture
|
||||
how_object_details
|
||||
how_capture_callstack
|
||||
how_custom_visualisation
|
||||
how_edit_shader
|
||||
@@ -15,6 +15,7 @@ Contents:
|
||||
credits_acknowledgements
|
||||
getting_started/index
|
||||
behind_scenes/index
|
||||
how/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
Reference in New Issue
Block a user