mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 01:20:42 +00:00
baldurk
c38affcded
* All renderdoc code up to this point was written by me, history is available by request
255 lines
18 KiB
XML
255 lines
18 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="f2f4fbfa-6127-4831-84e7-07309bd85908" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<introduction>
|
|
<autoOutline />
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
For this tutorial we will be using a slightly modified version of the CascadedShadowMaps
|
|
sample from the Microsoft DirectX SDK (June 2010).
|
|
</para>
|
|
</introduction>
|
|
<section address="Capture">
|
|
<title>Capturing a log</title>
|
|
<content>
|
|
<para>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.</para>
|
|
<mediaLink><image xlink:href="QuickStart1"/></mediaLink>
|
|
<para>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.</para>
|
|
<para>More details of the specific options and their functionality can be found in
|
|
the details page for the <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">Capture Window</link>.</para>
|
|
|
|
<alert class="note">
|
|
<para>It's best to choose the edition of RenderDoc to match your OS - 64-bit for Windows x64 and vice-versa</para>
|
|
<para>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.</para>
|
|
</alert>
|
|
</content>
|
|
</section>
|
|
<section address="Overlay">
|
|
<title>RenderDoc in-app</title>
|
|
<content>
|
|
<para>
|
|
RenderDoc has a fairly minimal in-app overlay, just to indicate that RenderDoc has successfully
|
|
loaded and is ready to capture a frame.
|
|
</para>
|
|
<para>
|
|
When ready, press the Capture Key (<command>F12</command> or <command>Print Screen</command>)
|
|
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.
|
|
</para>
|
|
<para><mediaLink><image xlink:href="QuickStart2"/></mediaLink></para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 <link xlink:href="6f4dad92-3db3-448f-9f1a-79af65f74492" /> for more information on taking
|
|
multiple frame captures. Note however that for the simple use-case, you don't need to worry about this!
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="Layout">
|
|
<title>RenderDoc layout</title>
|
|
<content>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<sections>
|
|
<section address="TextureViewer">
|
|
<title>Texture Viewer</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart3"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" /> page.</para>
|
|
<para>The texture viewer does pretty much what you'd expect - it allows you to inspect textures
|
|
and render targets in your application.</para>
|
|
<para>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:</para>
|
|
|
|
<list class="bullet">
|
|
<listItem><para>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.</para>
|
|
<para>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 <legacyItalic>Unbound</legacyItalic> listed under their thumbnail.</para>
|
|
<para>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
|
|
<link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4">open it by name</link></para></listItem>
|
|
|
|
<listItem><para>The format and dimensions of the texture are displayed on the status bar just below the texture
|
|
display itself.</para>
|
|
<para>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.</para></listItem>
|
|
|
|
<listItem><para>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 debugger, with the provisos
|
|
detailed in <link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629" />.</para></listItem>
|
|
|
|
<listItem><para>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 <math>[0, 1]</math>.</para>
|
|
<para>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 <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" /> page.</para>
|
|
<mediaLink>
|
|
<image xlink:href="QuickStart9"/>
|
|
</mediaLink></listItem>
|
|
</list>
|
|
|
|
</content>
|
|
</section>
|
|
|
|
<section address="EventBrowser">
|
|
<title>Event Browser</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart4"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="16D2B42E-65B0-40D1-AB91-AD2B156F5DA0" /> page.</para>
|
|
<para>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).</para>
|
|
<para>The columns can be customised and reordered, the
|
|
<mediaLinkInline><image xlink:href="timeline_marker"/></mediaLinkInline> select columns button (or right-click)
|
|
will allow you to choose which columns are displayed.</para>
|
|
<para>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.</para>
|
|
<para>The 'current' event - i.e. the event at which we are inspecting the graphics state - is highlighted
|
|
with a green Flag <mediaLinkInline><image xlink:href="GreenFlag"/></mediaLinkInline> and the row is highlighted.
|
|
As any row is selected it immediately becomes the new current event.</para>
|
|
<para>While the Event Browser is selected, you can press the shortcut keys <command>CTRL-F</command> or
|
|
<command>CTRL-G</command> to find <mediaLinkInline><image xlink:href="find"/></mediaLinkInline>
|
|
or jump to a given EID <mediaLinkInline><image xlink:href="GreenFlag"/></mediaLinkInline>
|
|
respectively.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="APIInspector">
|
|
<title>API Inspector</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart5"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="D78CE10E-0206-4DFC-B5CA-29F98D448235" /> page.</para>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>In order to view these callstacks you must first resolve the symbols recorded with the log.
|
|
To do this click on <command>Resolve Symbols</command> under the <command>Tools</command> menu. More
|
|
details on this process can be found in the guide: <link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" /></para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="TimelineBar">
|
|
<title>Timeline Bar</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart6"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="745E3EB5-EB29-4010-BBAB-B11282F4380C" /> page.</para>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="PipelineState">
|
|
<title>Pipeline State</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart7"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="A44E2304-6C11-451D-89C4-0A7397F5D1C6" /> page.</para>
|
|
<para>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.</para>
|
|
<para>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 <command>Show Disabled Items</command> and
|
|
<command>Show Empty Items</command> 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.</para>
|
|
<para>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
|
|
<mediaLinkInline><image xlink:href="GoArrow"/></mediaLinkInline> 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.
|
|
</para>
|
|
<para>For more details, check out the how-to: <link xlink:href="7A620DF5-332E-44CA-8FD5-9E47A9C4CC3E" /></para>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="MeshOutput">
|
|
<title>Mesh Output</title>
|
|
<content>
|
|
<mediaLink><image xlink:href="QuickStart8"/></mediaLink>
|
|
<para>More details can be found on the <link xlink:href="C48DED3E-3303-4A82-8F58-3D39766C48E7" /> page.</para>
|
|
<para>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.</para>
|
|
<para>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 UV Co-ordinate/Colour shading, which can be useful for visually inspecting
|
|
the geometry data.</para>
|
|
<para>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 <mediaLinkInline><image xlink:href="UndoArrow"/></mediaLinkInline>) 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
|
|
<mediaLinkInline><image xlink:href="cog"/></mediaLinkInline> and entering more accurate or corrected values.</para>
|
|
</content>
|
|
</section>
|
|
</sections>
|
|
</content>
|
|
</section>
|
|
|
|
<section address="Closing">
|
|
<title>Closing Notes</title>
|
|
<content>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
It is probably a good idea to check out the <link xlink:href="e2878f27-34d3-458a-9077-d0fb32c16829" />
|
|
page which lists several useful notes that aren't obvious but might save you a lot of time.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
</developerConceptualDocument>
|
|
</topic>
|