lee/renderdoc
1
0
Fork 0
mirror of https://github.com/baldurk/renderdoc.git synced 2026-05-06 10:00:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit of existing code.

Browse Source 
* All renderdoc code up to this point was written by me, history is available by request
This commit is contained in:
baldurk
2014-05-02 08:14:55 +01:00
parent 04b1549c0f
commit c38affcded
695 changed files with 230316 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/HowTo/HowToCallstacks.aml
+80
View File
@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="14048aef-0053-4e38-98cd-541f4d15d12e" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This page gives an overview of the callstack-capturing capability in RenderDoc,
with details and important information about how to enable this.</para>
</introduction>
<section address="Overview">
<title>Overview</title>
<content>
<para>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.</para>
<alert class="caution">
<para>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.</para>
</alert>
<alert class="note">
<para>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.</para>
</alert>
</content>
</section>
<section address="Capture">
<title>Launching Capture</title>
<content>
<para>When launching a capture (as in <link xlink:href="0dd6fe0d-4130-46f4-b2ea-9565de13111d" />)
you should enable 'collect callstacks'. This will set RenderDoc to collect callstacks at every
API entry point that will be serialised into the log.</para>
<mediaLink>
<caption placement="after" lead="Collect Callstacks">Option enabled on the capture dialog.</caption>
<image xlink:href="Callstacks"/>
</mediaLink>
<para>If you wish to save some time &amp; overhead you can then enable 'Only drawcall stacks'.
This will only collect callstacks when a drawcall-type API call is made. This can be a good-enough
trade off that still gets you the information you need, at a lower cost. After this point you can
run the program and capture as usual.</para>
</content>
</section>
<section address="Replay">
<title>Replaying the capture</title>
<content>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Callstack section">The callstack section expanded in API inspector.</caption>
<image xlink:href="NeedResolve"/>
</mediaLink>
<para>To resolve the symbols referenced in the capture, go to the <ui>Tools</ui> menu and
select <action>Resolve Symbols</action>. If this menu option isn't available the callstacks
did not successfully capture in the logfile.</para>
<para>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.</para>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="PDB locate prompt">Prompt to locate a PDB that cannot be found.</caption>
<image xlink:href="NeedPDB"/>
</mediaLink>
<para>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.</para>
<para>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.</para>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToCaptureLog.aml
+88
View File
@@ -0,0 +1,88 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="0dd6fe0d-4130-46f4-b2ea-9565de13111d" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>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
<link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5" /> window.</para>
</introduction>
<section address="capturing">
<title>Capturing logs</title>
<content>
<para>The basic process of capturing logs is fairly straightforward.</para>
<para>Opening the capture window from the menus via File -&gt; Capture Log, the
typical capture setup simply requires you to enter the executable location.</para>
<para>By default the working directory remains empty and defaults to the directory
that contains the executable location.</para>
<mediaLink>
<caption placement="after" lead="Capturing">Capturing a logfile specifying its executable path and command line.</caption>
<image xlink:href="CapturePathCmdline"/>
</mediaLink>
<para>Likewise, the default options generally work well for most situations, however
there are a few common options to customise:</para>
<list class="bullet">
<listItem><para>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.</para></listItem>
<listItem><para>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.</para></listItem>
<listItem><para>Collect callstacks allows you to get callstacks at the site of each API. There are
more details available in <link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" />.</para></listItem>
</list>
</content>
</section>
<section address="attaching">
<title>Attaching to a Process</title>
<content>
<para>It is possible to attach to an already running process. By selecting the "Attach 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.</para>
<para>This can be useful if launching your application from a single exe is non-trivial and it's
easier to attach to the process after it has been launched.</para>
<mediaLink>
<caption placement="after" lead="Attaching">Attaching to a selected existing process.</caption>
<image xlink:href="Attaching"/>
</mediaLink>
<alert class="caution">
<para>The important thing to note about attaching is that RenderDoc can only attach to processes that
<legacyBold>have not initialised or used the target API</legacyBold>. 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.</para>
</alert>
<alert class="note">
<para>If RenderDoc is not running as administrator, it cannot attach to 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.</para>
</alert>
</content>
</section>
<section address="capfiles">
<title>Capture setting files</title>
<content>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
</content>
</section>
<relatedTopics>
<link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToCustomShader.aml
+169
View File
@@ -0,0 +1,169 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="a00964a1-733f-4288-a79e-c28238bc6018" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This page details how to set up a custom shader for visualisation. This can be used
in the <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" /> to unpack or decode complex
formats, or simply apply a custom complex transformation to the image beyond the default controls.</para>
</introduction>
<section address="intro">
<title>Introduction</title>
<content>
<para>The basic process of setting up the custom shader involves writing a .hlsl file that
will be compiled and used by RenderDoc.</para>
<para>There are several special global variables that can be specified and will
be filled in with values by RenderDoc.</para>
<para>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.</para>
<para>Multisampled textures will be resolved before being passed to your function.
Depth and stencil textures will be bound separately and passed as multisampled resources.</para>
<para>To set up your shader, it's recommended that you use the UI defined in the documentation for the
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />, but you can manually create a .hlsl file in
<codeInline>%APPDATA%\RenderDoc\</codeInline>. The file must contain an hlsl function 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.</para>
</content>
</section>
<section address="inputs">
<title>Predefined inputs</title>
<content>
<para>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.</para>
<alert class="caution">
<para>Type and capitalisation is important for these variables, so ensure you use the right
declaration!</para>
</alert>
<table>
<tableHeader>
<row>
<entry><para>Input</para></entry>
<entry><para>Explanation</para></entry>
</row>
</tableHeader>
<row>
<entry><para>UV co-ordinates</para></entry>
<entry>
<code language="hlsl">
float4 main(<markup><u>float4 pos : SV_Position</u></markup>, <markup><u>float4 uv : TEXCOORD0</u></markup>) : SV_Target0
{
return 1;
}
</code>
<para>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).</para>
<alert class="note">
<para>You must bind these parameters like this in this order to ensure the linkage with the
vertex shader matches.</para>
</alert>
</entry>
</row>
<row>
<entry><para>Texture dimensions</para></entry>
<entry>
<code language="hlsl">
uint4 RENDERDOC_TexDim;
</code>
<para>This variable will be filled out with the following values:</para>
<list class="bullet">
<listItem><para><codeInline>.x = </codeInline> Width</para></listItem>
<listItem><para><codeInline>.y = </codeInline> Height (if 2D or 3D)</para></listItem>
<listItem><para><codeInline>.z = </codeInline> Depth if 3D or array size if an array</para></listItem>
<listItem><para><codeInline>.w = </codeInline> Number of mip levels</para></listItem>
</list>
</entry>
</row>
<row>
<entry><para>Selected Mip level</para></entry>
<entry>
<code language="hlsl">
uint RENDERDOC_SelectedMip;
</code>
<para>This variable will be filled out with the selected mip level in the UI.</para></entry>
</row>
<row>
<entry><para>Current texture type</para></entry>
<entry>
<code language="hlsl">
uint RENDERDOC_TextureType;
</code>
<para>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.</para>
<list class="ordered">
<listItem><para>1D texture</para></listItem>
<listItem><para>2D texture</para></listItem>
<listItem><para>3D texture</para></listItem>
<listItem><para>Depth</para></listItem>
<listItem><para>Depth + Stencil</para></listItem>
<listItem><para>Depth (Multisampled)</para></listItem>
<listItem><para>Depth + Stencil (Multisampled)</para></listItem>
</list>
</entry>
</row>
<row>
<entry><para>Samplers</para></entry>
<entry>
<code language="hlsl">
SamplerState pointSampler : register(s0);
SamplerState linearSampler : register(s1);
</code>
<para>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.</para></entry>
</row>
<row>
<entry><para>Resources</para></entry>
<entry>
<code language="hlsl">
Texture1DArray&lt;float4&gt; texDisplayTex1DArray : register(t1);
Texture2DArray&lt;float4&gt; texDisplayTex2DArray : register(t2);
Texture3D&lt;float4&gt; texDisplayTex3D : register(t3);
Texture2DArray&lt;float2&gt; texDisplayTexDepthArray : register(t4);
Texture2DArray&lt;uint2&gt; texDisplayTexStencilArray : register(t5);
Texture2DMSArray&lt;float2&gt; texDisplayTexDepthMSArray : register(t6);
Texture2DMSArray&lt;uint2&gt; texDisplayTexStencilMSArray : register(t7);
Texture2DArray&lt;float4&gt; texDisplayTexCubeArray : register(t8);
Texture1DArray&lt;uint4&gt; texDisplayUIntTex1DArray : register(t11);
Texture2DArray&lt;uint4&gt; texDisplayUIntTex2DArray : register(t12);
Texture3D&lt;uint4&gt; texDisplayUIntTex3D : register(t13);
Texture1DArray&lt;int4&gt; texDisplayIntTex1DArray : register(t21);
Texture2DArray&lt;int4&gt; texDisplayIntTex2DArray : register(t22);
Texture3D&lt;int4&gt; texDisplayIntTex3D : register(t23);
</code>
<para>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.</para>
<para>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.</para>
<para>To determine which resource to sample from you can use the RENDERDOC_TexType variable
above.</para>
<para>Usually the float textures are used, but for unsigned and signed integer formats,
the relevant integer resources are used.</para>
<para>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.</para></entry>
</row>
</table>
</content>
</section>
<relatedTopics>
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToDebugShader.aml
+157
View File
@@ -0,0 +1,157 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>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.</para>
</introduction>
<section address="DebugInfo">
<title>Including debug info in shaders</title>
<content>
<para>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.</para>
</content>
</section>
<section address="vertex">
<title>Debugging a vertex</title>
<content>
<para>Vertex debugging is invoked from the mesh viewer. With the mesh viewer open you can
select the input vertex you wish to debug.</para>
<para>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.</para>
<para>Either right click and choose debug vertex
from the context menu, or click on the debug icon in the toolbar.</para>
<mediaLink>
<caption placement="after" lead="Vertex Debugging">Launching vertex debugging from the mesh viewer.</caption>
<image xlink:href="VertexDebug"/>
</mediaLink>
<para>From here the debugger will open with the vertex shader in the shader debugger.
The inputs are automatically filled in from the mesh data.</para>
<alert class="note">
<para>Geometry and tessellation shaders are not yet debuggable.</para>
</alert>
</content>
</section>
<section address="pixel">
<title>Debugging a Pixel</title>
<content>
<para>Pixel debugging is launched from the texture viewer. For more details on selecting
the pixel to debug see <link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501" />.</para>
<para>When a given pixel is selected you can either choose the debug icon on the
toolbar, <mediaLinkInline><image xlink:href="wrench"/></mediaLinkInline>
or click the debug button underneath the pixel context. Each of these will
launch the shader viewer with the selected pixel being debugged. The
inputs to the pixel will be automatically filled in.</para>
<para>There are currently several things to note while pixel debugging:</para>
<list class="bullet">
<listItem><para>There is no pixel history at the moment, so the drawcall that you wish to debug
must be selected as the current even when you attempt to debug the pixel.</para></listItem>
<listItem><para>If a drawcall overdraws the same pixel several times then the results of debugging
may not be accurate - RenderDoc attempts to pick the fragment that last passed the depth test but this
isn't guaranteed and may not be perfect. There's also no way to choose a different fragment in the case
of blending being used, or sample-frequency rendering.</para></listItem>
</list>
</content>
</section>
<section address="compute">
<title>Debugging a Compute thread</title>
<content>
<para>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.</para>
<para>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.</para>
<alert class="caution">
<para>This feature is <legacyBold>highly</legacyBold> experimental and is provided with no guarantees
yet! It may work on simple shaders which is why it is available.</para>
</alert>
</content>
</section>
<section address="debugging">
<title>Debugging Controls</title>
<content>
<para>When debugging, at the moment the controls are fairly basic.</para>
<mediaLink>
<caption placement="after" lead="Shader controls">Controls for stepping through shaders.</caption>
<image xlink:href="ShaderControls"/>
</mediaLink>
<para>The toolbar at the top gives controls for the program flow through the
shader. <mediaLinkInline><image xlink:href="runfwd"/></mediaLinkInline> Run and
<mediaLinkInline><image xlink:href="runback"/></mediaLinkInline> Run Backward simply
run from the current position all the way
through to the end or start of the program respectively.</para>
<para>The keyboard shortcuts for these controls are <command>F5</command> and
<command>Shift-F5</command> respectively.</para>
<para>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.</para>
<para>The other controls allow for single stepping and limited running.
<mediaLinkInline><image xlink:href="stepnext"/></mediaLinkInline> Step forward
will execute the current instruction and continue to the next - this includes following
any flow control statements such as jumps, loops, etc.</para>
<para><mediaLinkInline><image xlink:href="stepprev"/></mediaLinkInline> 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 <command>F10</command> and <command>Shift-F10</command></para>
<para>The final control is to
<mediaLinkInline><image xlink:href="runcursor"/></mediaLinkInline> 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.</para>
<alert class="note">
<para>The highlighted instruction at any given point indicates the <legacyItalic>next</legacyItalic>
instruction to be executed - not the instruction that was just executed.</para>
</alert>
<para>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.</para>
</content>
</section>
<section address="debugging">
<title>Debugging Displays</title>
<content>
<para>Currently there is only a very basic display when debugging shaders.</para>
<para>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).</para>
<mediaLink>
<caption placement="after" lead="Constants window">Constant, input and resource registers.</caption>
<image xlink:href="ShaderConsts"/>
</mediaLink>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Variable window">Variable registers - temporaries and outputs.</caption>
<image xlink:href="ShaderRegs"/>
</mediaLink>
<para>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.</para>
<para>Swizzles follow the standard hlsl rules - .[xyzw] or .[rgba] in any permutation or repetition
will show those channels.</para>
<para>The custom typecast can be any of ,x ,i ,d ,f ,u to display the register as hex, signed integer,
double, float or unsigned respectively.</para>
<mediaLink>
<caption placement="after" lead="Watch window">Watch window - custom register expressions evaluated.</caption>
<image xlink:href="ShaderWatch"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToEditShader.aml
+73
View File
@@ -0,0 +1,73 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="6d0b6532-6da2-485d-85cd-e83e8c9e0183" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>This page details how to edit shaders. This applies both to
<link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018">custom visualisation shaders</link> for the
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />, but can also be used to temporarily replace or
edit a shader used in the actual scene.</para>
</introduction>
<section address="EditCustom">
<title>How to edit a custom shader</title>
<content>
<para><link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018">Custom visualisation shaders</link> 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.</para>
<para>These shaders live as .hlsl files in <codeInline>%APPDATA%\RenderDoc\</codeInline>, 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.</para>
<para>To edit a shader inside RenderDoc simply click the edit button
<mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline> 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 file and compiled and reflected in the texture viewer as long as you have that custom shader
selected.</para>
</content>
</section>
<section address="EditLive">
<title>How to edit a scene shader</title>
<content>
<para>RenderDoc allows you to edit a shader used in the capture and make changes to it and see the effects in real-time.</para>
<para>To launch the shader editor, go to the pipeline stage you wish to change in the <link xlink:href="A44E2304-6C11-451D-89C4-0A7397F5D1C6" />
windows, and click on the edit button <mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline>
next to the shader.</para>
<para>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.</para>
<para>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.</para>
<alert class="caution">
<para>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.</para>
<para>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.</para>
</alert>
</content>
</section>
<section address="ShaderEditor">
<title>Using the built-in shader editor</title>
<content>
<para>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.</para>
<para>To compile the shader and apply your changes, either click the save button in the toolbar or press
Ctrl-S. This will compile the shader and apply it, any warnings and errors will be added to the box below
the main source.</para>
<para>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.</para>
<alert class="caution">
<para>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.</para>
</alert>
<para>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
<link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018" /></para>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToFindTexture.aml
+85
View File
@@ -0,0 +1,85 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>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.</para>
</introduction>
<section address="Annotation">
<title>Annotating resources with names</title>
<content>
<para>It is much easier to browse and debug frames when the resources are
given meaningful names - along with including
<link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629">debugging information in shaders</link> and
marking up the frame with
<link xlink:href="16D2B42E-65B0-40D1-AB91-AD2B156F5DA0">hierarchical user-defined regions</link>.</para>
<para>The way this is done varies by API. In D3D11 the resource is named in this way:</para>
<code language="cpp">
// Creating an example resource - a 2D Texture.
ID3D11Texture2D *tex2d = NULL;
d3dDevice->CreateTexture2D(&amp;descriptor, NULL, &amp;tex2d);
// Give the buffer a useful name
tex2d->SetPrivateData(WKPDID_D3DDebugObjectName, "Example Texture", sizeof("Example Texture"));
</code>
<para>When this texture is bound to the pipeline it will be listed like so:</para>
<mediaLink>
<caption placement="after" lead="Named Texture">The example texture bound with name displayed.</caption>
<image xlink:href="NamedTex"/>
</mediaLink>
<para>In a similar way any other resource can be named and this will be useful throughout
the rest of the analysis.</para>
</content>
</section>
<section address="TextureList">
<title>Texture list in Texture Viewer</title>
<content>
<para>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
<mediaLinkInline><image xlink:href="page_white_link"/></mediaLinkInline>. When clicked on
this will open a sidebar on the texture viewer that lists all textures.</para>
<mediaLink>
<caption placement="after" lead="Texture list">The sidebar showing the list of textures</caption>
<image xlink:href="TexList"/>
</mediaLink>
<para>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.</para>
<para>When selecting and opening one of the textures from here, a new tab is opened in
the texture viewer that follows that texture.</para>
</content>
</section>
<section address="LockedTexture">
<title>Locked tab of a Texture</title>
<content>
<para>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.</para>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Texture Tabs">Default tab following pipeline slot vs Locked tab.</caption>
<image xlink:href="CurrentVsLockedTab"/>
</mediaLink>
<para>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.</para>
<para>Opening a texture from the pipeline state viewer
(<link xlink:href="7A620DF5-332E-44CA-8FD5-9E47A9C4CC3E" />)
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.</para>
<mediaLink>
<caption placement="after" lead="Opening new Tab">Opening a new locked tab for a texture.</caption>
<image xlink:href="OpenLockedTab"/>
</mediaLink>
</content>
</section>
<relatedTopics>
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToInspectPixel.aml
+67
View File
@@ -0,0 +1,67 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="F1C1E449-55ED-46FE-BBFD-11D1A0511501" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>When in the texture viewer you can inspect the pixel values to obtain the exact
contents of any pixel in the texture.</para>
</introduction>
<section address="Subresource">
<title>Selecting appropriate subresource</title>
<content>
<para>More details can be found in the <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
page, but the first step is to select the appropriate subresource - array element, cubemap face
or mip slice.</para>
<para>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.</para>
</content>
</section>
<section address="PickPixel">
<title>Picking a Pixel Value</title>
<content>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Hover Status Bar">The status bar showing position and colour</caption>
<image xlink:href="HoverStatus"/>
</mediaLink>
<para>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 <link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" />.</para>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Picked Pixel">The value of a pixel that has been picked</caption>
<image xlink:href="RMBStatus"/>
</mediaLink>
<para>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.</para>
<para>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.</para>
</content>
</section>
<section address="PixelContext">
<title>Pixel Context Display</title>
<content>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Pixel Context">The zoomed in context around the pixel currently selected</caption>
<image xlink:href="PixelContext"/>
</mediaLink>
<para>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.</para>
<para>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: <link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629" />.</para>
</content>
</section>
<relatedTopics>
<link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/HowTo/HowToViewDetails.aml
+95
View File
@@ -0,0 +1,95 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="7A620DF5-332E-44CA-8FD5-9E47A9C4CC3E" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The pipeline state viewer allows you to view more details of given resources
that are bound to the pipeline. The go arrow
<mediaLinkInline><image xlink:href="GoArrow"/></mediaLinkInline> is a sign that more
details for this resource are available.</para>
</introduction>
<section address="shaders">
<title>Viewing Shaders</title>
<content>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Bound Shader">Box showing the currently used shader.</caption>
<image xlink:href="CurrentShader"/>
</mediaLink>
<para>Much of the information that is available from the shader is only available
when debugging information is made available.
<link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629">More details are available</link>
</para>
<para>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.</para>
<para>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.</para>
<para>When this shader reflection information is available it will be integrated into
the disassembly to make it easier to read.</para>
<para>Note from here you can also <link xlink:href="6d0b6532-6da2-485d-85cd-e83e8c9e0183">live-edit a shader</link> by clicking the edit button
<mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline>. If debug info
isn't available to provide HLSL, a basic stub function with the input &amp; output
signatures but no body will be created.</para>
</content>
</section>
<section address="textures">
<title>Viewing Textures</title>
<content>
<para>The <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" /> 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 <link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" />.</para>
<para>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
<mediaLinkInline><image xlink:href="GoArrow"/></mediaLinkInline> will indicate that a new
locked tab can be opened up in the texture viewer.</para>
<para>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
<link xlink:href="745E3EB5-EB29-4010-BBAB-B11282F4380C" /> page.</para>
</content>
</section>
<section address="buffers">
<title>Viewing Buffers</title>
<content>
<para>More details on this section are available on the <link xlink:href="C48DED3E-3303-4A82-8F58-3D39766C48E7" />
page.</para>
<para>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.</para>
<para>In the general case, buffers bound to the pipeline can be opened as a raw buffer viewer.</para>
<para>This will open up a view of the buffer similar to the mesh viewer, but with a completely
customisable buffer layout.</para>
<para>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.</para>
<para>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.</para>
<mediaLink>
<caption placement="after" lead="Custom Buffer Layout">Customising the layout of the buffer by defining a structure.</caption>
<image xlink:href="RawBuffer"/>
</mediaLink>
</content>
</section>
<section address="constants">
<title>Viewing Constant Buffers</title>
<content>
<para>Constant buffers can be viewed by clicking on their Go Arrow
<mediaLinkInline><image xlink:href="GoArrow"/></mediaLinkInline>. This will open up a new docked section
to the right of the pipeline state viewer that tracks that constant buffer slot.</para>
<para>Whenever this shader slot has a constant buffer in it,
both the constant names and types as well as values will be displayed.</para>
<mediaLink>
<caption placement="after" lead="Constant Buffer">An updating preview of the contents of this constant buffer.</caption>
<image xlink:href="CBuffer"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>