<?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 history or debugger, as

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>

</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>

<para>The <mediaLinkInline><image xlink:href="asterisk_orange"/></mediaLinkInline> bookmark button will

allow you to bookmark an event, the shortcut key is <command>CTRL-B</command>.</para>

<para>A list of bookmarked events will show up on a toolbar at the top of the event browser, they and

the shortcut keys <command>CTRL-1</command> to <command>CTRL-0</command> will jump to the

respective bookmarked EID. These shortcuts will work anywhere in the application.</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 secondary shading, which lets you right click on any column to select it as

colour data to render on the mesh.</para>

<para>You can hold or click the right mouse button on the mesh preview to select the vertex in

the mesh data tables.</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>