lee/renderdoc
1
0
Fork 0
mirror of https://github.com/baldurk/renderdoc.git synced 2026-05-29 21:30:53 +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/Windows/APIInspector.aml
+55
View File
@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="D78CE10E-0206-4DFC-B5CA-29F98D448235" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>Although not the most complex part of the RenderDoc's UI, this page details
the features and functionality of the API Inspector.</para>
</introduction>
<section address="elems">
<title>UI Elements</title>
<content>
<para>The API Inspector is divided into two sections - the top section is the most common,
detailing all of the API calls leading up to and including the current drawcall.
The special case for this is the end of the frame where there may not be a final drawcall
but the API Inspector lists the API calls that preceded the final flip of the backbuffer
that marks the end of RenderDoc's captured frame.</para>
<para>The bottom section is less common but shows the callstack from user code into the
API entry point, if such a callstack is available and the symbols are resolved. For more
information check out the page on <link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" />.</para>
</content>
</section>
<section address="api">
<title>API Calls</title>
<content>
<para>This section lists the series of API calls made between the preceding drawcall
and the currently selected drawcall. The current drawcall is always the last element
in this list and is highlighted in bold. By default it is also the selected element.</para>
<para>Each API call can be expanded to see the parameters that were passed to it, in the
form that they were serialised out to the log file.</para>
<mediaLink>
<caption placement="after" lead="API Calls">A list of API calls made up to the current draw.</caption>
<image xlink:href="APIList"/>
</mediaLink>
</content>
</section>
<section address="callstack">
<title>Callstack</title>
<content>
<para>The callstack section can be expanded by double clicking on the separator and
collapsed in the same way. Once open its size can be adjusted by clicking and dragging
on the separator.</para>
<para>This section will either show "No callstack available" or "Need to resolve symbols"
as appropriate when the callstacks aren't ready for display.</para>
<para>The callstack follows the currently selected API call in the other section, and will
update both as that selected call change and as the current event changes (as this implicitly
changes the API call selected to whichever the current drawcall is).</para>
<para>For more information see <link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" /></para>
<mediaLink>
<caption placement="after" lead="Callstack">The callstack in user code where this API call was made.</caption>
<image xlink:href="CallstackPanel"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/BufferViewer.aml
+122
View File
@@ -0,0 +1,122 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="C48DED3E-3303-4A82-8F58-3D39766C48E7" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>The buffer viewer has two reasonably distinct modes - the first rather
specialised to show meshes and mesh data as it passes through the pipeline.
The other shows a raw arbitrary buffer with a custom (and arbitrary) formatting.</para>
</introduction>
<section address="mesh">
<title>Mesh Viewer</title>
<content>
<para>The Mesh Viewer shows both the mesh data as well as a visual representation
of the mesh at different stages - pre VS, post VS, etc.</para>
<para>Each distinct point has a display that shows the mesh data, the format of which
is pulled from the relevant stage of the pipeline - shader input or output, or input
layout. You can choose to sync these views <mediaLinkInline><image xlink:href="arrow_join"/></mediaLinkInline>
as well as specify an offset which will stay consistent, so that you can see the same
row as you move between different events.</para>
<para>Below this is a 3D view which will show one stage at any given time, and can be
switched with the tabs above it. There are two control schemes for viewing the 3D mesh -
Arcball which is the default for pre-transform (VS in), and WASD controls which is the
default for post-transform (VS out). You can switch between these at any time with
the dropdown on the toolbar above the mesh view.</para>
<alert class="note">
<para>When tessellation is active, VS out behaves similarly to VS in as they are both
considered input data (rather than post-transform data).</para>
</alert>
<para>You can reset the camera to its default location with the reset button
<mediaLinkInline><image xlink:href="arrow_undo"/></mediaLinkInline>. For VS Input this
resets to an arcball at some radius from the object. For VS Output this resets to a view
from the projected eye.</para>
<para>You can also auto-fit the camera to the mesh for the VS Input mesh. The auto-fit
button <mediaLinkInline><image xlink:href="wand"/></mediaLinkInline> will fit the
camera to the axis-aligned bounding box of the mesh.</para>
<para>To be able to view the post-transform mesh in view-space, RenderDoc attempts to
guess the projection matrix and unprojects the output data.</para>
<para>By default the projection matrix is guessed as a standard perspective matrix.
Using the post-projection w and z values and the aspect ratio of the output targets
a reasonable approximation can be estimated. The FOV must be specified though - the
default is 90 but this can be refined by opening the options.</para>
<para>Opening the options <mediaLinkInline><image xlink:href="cog"/></mediaLinkInline>
you can specify the FOV used in the projection matrix. If you used an orthographic
matrix instead you can specify this - although this requires manual tuning of the
matrix parameters.</para>
<mediaLink>
<caption placement="after" lead="Options">The options pop-out of the buffer viewer.</caption>
<image xlink:href="BufferOptions"/>
</mediaLink>
<para>Also available in the options is a simple speed multiplier for the WASD controls,
to fine-tune how fast it moves to the dimensions of the mesh.</para>
<para>In the vertex input preview, you have the option to display the mesh with some solid
shading modes, not just as a wireframe mesh. When solid shading you can toggle the wireframe
on and off.</para>
<list class="bullet">
<listItem><para>Solid Colour simply displays a solid colour for each triangle.</para></listItem>
<listItem><para>Flat Shaded will perform basic flat lighting calculations based on triangle normals to give a better idea of the topology of the mesh.</para></listItem>
<listItem><para>TEXCOORD0 and COLOR0 will display the relevant input element, if detected in the mesh.</para></listItem>
</list>
<mediaLink>
<caption placement="after" lead="Preview">Previewing the uv co-ordinates as colour on the mesh.</caption>
<image xlink:href="SolidPreview"/>
</mediaLink>
</content>
</section>
<section address="buff">
<title>Raw Buffer Viewer</title>
<content>
<para>When opening a buffer as a raw display, sometimes a default layout will be specified
e.g. if available from shader reflection data. If not, the layout will default to 4
32bit unsigned integers.</para>
<para>This format can be refined and customised by entering a structure-like definition
into the text box at the bottom of the window. The given types are listed below, and
can be combined in hlsl-like fashion specifying n-wide vector elements.</para>
<para>In addition to this, you can specify a row offset which is useful in remaining
at the same row while watching the change in a buffer between different events, as well
as a byte offset to shift the data along from the start of the buffer (e.g. if what you
are interested in starts only part-way through the buffer but is not aligned along the
data stride you enter).</para>
<mediaLink>
<caption placement="after" lead="Buffer specification">Specifying a custom buffer format.</caption>
<image xlink:href="RawBuffer"/>
</mediaLink>
<para>Below are listed the basic types. You can append a number to each of these to make an N-wide
vector (e.g. ushort4 or float3). You can also specify matrices as float3x4. By default matrices
are column major, but you can change this by prepending row_major as you would in hlsl.</para>
<list class="bullet">
<listItem><para>uint - unsigned 32bit integer</para></listItem>
<listItem><para>bool - unsigned 32bit integer (this is the format for hlsl bools)</para></listItem>
<listItem><para>int - signed 32bit integer</para></listItem>
<listItem><para>ushort - unsigned 16bit integer</para></listItem>
<listItem><para>short - signed 16bit integer</para></listItem>
<listItem><para>ubyte - unsigned 8bit integer</para></listItem>
<listItem><para>byte - signed 8bit integer</para></listItem>
<listItem><para>double - 64bit floating point</para></listItem>
<listItem><para>float - 32bit floating point</para></listItem>
<listItem><para>half - 16bit floating point</para></listItem>
</list>
<para>There are also some non-hlsl types for displaying other formats which don't have a corresponding native
hlsl type</para>
<list class="bullet">
<listItem><para>unormb - 8bit unsigned normalised value</para></listItem>
<listItem><para>unormh - 16bit unsigned normalised value</para></listItem>
<listItem><para>unormf - 32bit unsigned normalised value</para></listItem>
<listItem><para>snormb - 8bit signed normalised value</para></listItem>
<listItem><para>snormh - 16bit signed normalised value</para></listItem>
<listItem><para>snormf - 32bit signed normalised value</para></listItem>
<listItem><para>uintten - 4 component unsigned integer format, packed as 10:10:10:2</para></listItem>
<listItem><para>unormten - 4 component unsigned normalised format, packed as 10:10:10:2</para></listItem>
</list>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/CaptureDialog.aml
+219
View File
@@ -0,0 +1,219 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="D1612D25-C8BA-4349-9CE2-1E57D60F98C5" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The Capture Dialog (which doubles as the attach-to-process dialog) is the
single point where programs are launched and logfiles are captured to disk.</para>
<para>After launching a capture a connection dialog will open to allow you to manage
and open any captures you take. See <link xlink:href="6f4dad92-3db3-448f-9f1a-79af65f74492" /> for more details.</para>
<alert class="note">
<para>NOTE: The Load Settings and Save Settings buttons on this dialog refer to loading and saving the set
of settings and options configured on this dialog. They do <legacyItalic>not</legacyItalic> refer to loading
and saving the logs produced from capturing - that is done from the File menu.</para>
</alert>
</introduction>
<section address="capturing">
<title>Capturing</title>
<content>
<para>To capture a program you simply need to provide the details of the application
to be launched.</para>
<para>The Program section of the dialog prompts for the executable to be launched,
the working directory, and any command-line arguments to be passed to the program.</para>
<mediaLink>
<caption placement="after" lead="Program Capture">Configuring and launching an exe directly from RenderDoc.</caption>
<image xlink:href="CapturePathCmdline"/>
</mediaLink>
<para>The "..." buttons next to the executable path and working directory can be used to
browse through the file system. By default if the working directory box is left empty
then the directory containing the executable will be used as the working directory.</para>
<para>When you are ready to capture simply click the <command>Capture</command> button in the bottom right.</para>
<para>If you wish to save these particular settings you can click <command>Save</command> to save them to a .cap file.
This .cap file can either be loaded in manually, accessed through the <command>Recent Captures</command> menu.
The .cap file can be associated with RenderDoc, and if so launching RenderDoc from this file will automatically load
the capture settings. If "Auto start" is checked then double clicking on the .cap file will immediately trigger
a capture with the given settings.</para>
<alert class="note">
<para>The process will be launched with the same permissions and by the same user as RenderDoc was launched.
If your process requires specific permissions (such as administrator permissions) you will need to
launch RenderDoc with these permissions.</para>
</alert>
</content>
</section>
<section address="attaching">
<title>Inject into Process</title>
<content>
<para>When invoked through <command>Inject into Process</command> the capture dialog modifies itself
to give a list of processes running on the target system.</para>
<para>A list of processes is fetched once when the dialog is opened, but this can be refreshed
by clicking on the refresh button below the list. Select the process you would like to attach to
and click Attach.</para>
<mediaLink>
<caption placement="after" lead="Attaching">Attaching to an already-running process via RenderDoc.</caption>
<image xlink:href="Attaching"/>
</mediaLink>
<alert class="caution">
<para>The process <legacyBold>must not</legacyBold> have invoked or initialised the API to be used,
as this will be too late for RenderDoc to hook and capture it. At best RenderDoc will not capture, at worst
it may cause crashes or undefined behaviour. Only attach to processes you can guarantee are early
enough in their initialisation that they have not used the graphics API.</para>
</alert>
</content>
</section>
<section address="options">
<title>Capture Options</title>
<content>
<para>Several capture options are available to configure how RenderDoc works while injected into
the target application, as well as affecting the resultant captures. Most of these will work
fine with the defaults, but some may need to be configured to your tastes.</para>
<para>Some of these options are API-specific and will not apply when using other APIs than
they are intended, although most are generic in some fashion - the exact implementation may
vary by API.</para>
<table>
<tableHeader>
<row>
<entry><para>Name</para></entry>
<entry><para>Explanation</para></entry>
<entry><para>Default Setting</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Allow Fullscreen</para></entry>
<entry><para>Allow Fullscreen simply means that RenderDoc will not interfere with any attempt
by the application to switch into an exclusive fullscreen video mode. While debugging sometimes
this can be awkward as you may wish to quickly switch to your debugger or another program.</para>
<para>If this option is unchecked, RenderDoc will attempt to modify any such attempt to an equivalent
windowed mode.</para></entry>
<entry><para>Enabled</para></entry>
</row>
<row>
<entry><para>Allow VSync</para></entry>
<entry><para>Allow VSync functions very similarly to Allow Fullscreen. When disabled, RenderDoc
will prevent any attempt to VSync by the application. This can be useful given that there is a
certain degree of inevitable overhead from running with RenderDoc and VSync can amplify that.</para></entry>
<entry><para>Enabled</para></entry>
</row>
<row>
<entry><para>Seconds Delay</para></entry>
<entry><para>This option causes RenderDoc to stall for a defined number of seconds immediately after
launching the process. Most commonly this is used so that you can launch a program in RenderDoc
and immediately attach a traditional debugger before any significant code is executed.</para>
<para>This can be useful e.g. when early initialisation needs to be debugged.</para></entry>
<entry><para>0 Seconds (Disabled)</para></entry>
</row>
<row>
<entry><para>Collect Callstacks</para></entry>
<entry><para>This option will cause RenderDoc to save a callstack from user code into the API at every
API call during the frame being captured. This can then be resolved later and used to determine where
the application is calling each API call. More details can be found in:
<link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" />.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Only Drawcall Callstacks</para></entry>
<entry><para>This option modifies the above capturing of callstacks to only be saved for drawcall-type
API calls. This can reduce the CPU load, as well as file-size and memory overhead of capturing callstacks
for every API call which may not be desired. Only valid if Collect Callstacks is enabled.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Create Debug Device</para></entry>
<entry><para>Create Debug Device causes RenderDoc to enable the API's built-in debugging, and where
possible serialise this out and include it in the logfile for later inspection. e.g. on D3D11 this will
activate the D3D debug layer and save out any messages, which can later be viewed in the
<link xlink:href="1f098896-0e60-485a-b879-900a4a320b80" /> window.
The overhead from enabling this option is largely the same as the overhead of enabling the
debug device without RenderDoc involved.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Cache State Objects</para></entry>
<entry><para>In D3D11 creating a state object with the same descriptor as one that already exists
will simply return a pointer to the existing state object, with a reference count added. Given that
creation and destruction in RenderDoc has a certain overhead, when this option is enabled RenderDoc will
hold onto a reference to freed state objects in case they are likely to be re-allocated soon after.</para>
<para>This will reduce churn and overhead with minimal impact to the application, and it's recommended to
leave this enabled unless you have specific problems or want to remove this optimisation.</para></entry>
<entry><para>Enabled</para></entry>
</row>
<row>
<entry><para>Hook into Children</para></entry>
<entry><para>This option causes RenderDoc to hook into CreateProcess and intercept any calls to it from
the target application. When this option is enabled those child processes will be injected with RenderDoc
in the same way as the parent - which can be useful if you must launch your program through a launcher
or level of indirection and still wish to use RenderDoc with one of the child processes.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Save All Initials</para></entry>
<entry><para>RenderDoc will attempt to save overhead and particularly logfile size by omitting the initial
contents of 2D textures that it believes will be unnecessary. Typically these textures are render targets
or depth buffers that will be written to and fully covered in the course of the frame before they are
ever read, and so saving their initial contents is unnecessary.</para>
<para>In some cases this detection will be wrong, such as targets that are partially written such as pools,
or if a target is accumulated to via blend modes. When this is the case, enabling Save All Initials will
force RenderDoc to save these textures regardless of any auto-detection.</para>
<alert class="note">
<para>Multisampled textures will not have their initial contents saved regardless of the value of
this option.</para>
</alert>
</entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Ref All Resources</para></entry>
<entry><para>One method RenderDoc uses to keep logfile sizes down is to only include the referenced
dependencies of a frame within a capture. This means that even if 100 textures are allocated and present,
if 50 of them are never bound to the pipeline or otherwise referenced then they will not be included
in the logfile. Enabling this option will cause RenderDoc to include all live resources at the time of
capture regardless of whether they are used or not.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Capture All Cmd Lists</para></entry>
<entry><para>By default RenderDoc only begins capturing when you hit the capture key - any commands issued
before this point are not available and so if a deferred command list was created before you hit capture
and replayed after, it would not be available and RenderDoc would have to fall back and capture again in the
hopes that next frame everything will be available.</para>
<para>If the application creates a command list early and replays it indefinitely without recreating it,
RenderDoc will essentially have missed its chance to capture it by the time you hit the capture key. Enabling
this option will cause RenderDoc to pre-emptively capture all command lists just in case they are used.</para>
<alert class="caution">
<para>This may have a significant performance hit.</para>
</alert>
</entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Auto start</para></entry>
<entry><para>This option is slightly different from the others in that it doesn't change anything for an
immediate capture. When a .cap settings file is saved with the details of a particular capture, if this
option is enabled then loading a .cap file from the command line (i.e. most commonly from a file association)
will trigger a capture as soon as RenderDoc loads. This is useful for saving a common capture setting and
running it with just one click.</para></entry>
<entry><para>Disabled</para></entry>
</row>
<row>
<entry><para>Queue Capture of Frame</para></entry>
<entry><para>This option allows you to queue up a precise capture of a given frame number after the program has started.</para></entry>
<entry><para>Disabled</para></entry>
</row>
</table>
</content>
</section>
<relatedTopics>
<link xlink:href="f2f4fbfa-6127-4831-84e7-07309bd85908" />
<link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/Windows/DebugMessages.aml
+28
View File
@@ -0,0 +1,28 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="1f098896-0e60-485a-b879-900a4a320b80" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>The Debug Messages window shows messages from the API including warnings about performance
issues or concerns about potential hazards, as well as errors on invalid use of the API.</para>
</introduction>
<section address="capture">
<title>Capturing with debug messages included</title>
<content>
<para>To include these debug messages in a log, check on the "Create Debug Device" option in
the capture options. For more information see <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5" />.</para>
</content>
</section>
<section address="window">
<title>Debug Messages</title>
<content>
<para>This window is fairly simple. Each message retrieved from the api will be listed on
its own row showing the event ID that triggered the message, along with a severity and category.</para>
<para>Double clicking on any row will take you to the corresponding event ID in the event browser.</para>
<mediaLink>
<caption placement="after" lead="Debug Messages">The Debug Messages window showing some API messages.</caption>
<image xlink:href="DebugMessages"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/EventBrowser.aml
+129
View File
@@ -0,0 +1,129 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="16D2B42E-65B0-40D1-AB91-AD2B156F5DA0" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>The Event Browser is the primary method of browsing the frame and selecting
different drawcalls. It displays the user-annotated hierarchical display of
sections.</para>
</introduction>
<section address="annotation">
<title>Annotating your frame</title>
<content>
<para>The Event Browser becomes most useful when the application has user-defined
annotations of sections and subsections of the frames, to allow for a more logical
and ordered browsing of the frame.</para>
<para>Doing this is API and platform specific. Example code for D3D11 is included
below, using the D3DPERF library that is defined in d3d9.lib, which can still be used
in D3D11. (The newer ID3DUserDefinedAnnotation API is also supported).</para>
<code language="cpp">
D3DPERF_BeginEvent(0xffffffff, L"Start of example");
D3DPERF_BeginEvent(0xff00ff00, L"Sub section");
// events inside the subsection
D3DPERF_EndEvent();
// events outside the subsection
D3DPERF_EndEvent();
</code>
<para>This will generate a section of the frame with a subsection that includes some events,
and then some further events that are siblings of the subsection.</para>
</content>
</section>
<section address="columns">
<title>Selecting available columns</title>
<content>
<para>By default, the columns in the event browser are EID and Name. Name cannot be removed as
it contains the tree, but otherwise the columns can be customised both to hide/display or
reorder and resize.</para>
<para>To select which columns should be visible, right click the header or click the
<mediaLinkInline><image xlink:href="timeline_marker"/></mediaLinkInline> select columns button.</para>
<para>To rearrange the columns simply click and drag on the header.</para>
<alert class="note">
<para>Note that when timing drawcalls the duration column will automatically be added to display the data.</para>
</alert>
</content>
</section>
<section address="columns">
<title>Timing drawcalls</title>
<content>
<para>To time the GPU duration of each drawcall, click the timer button <mediaLinkInline><image xlink:href="time"/></mediaLinkInline></para>
<para>This will automatically run a process to get the time of each drawcall and display it in the duration column,
which will be added if necessary.</para>
<para>You can configure which time unit is used for the duration column on the fly in the
<link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" /></para>
</content>
</section>
<section address="browsing">
<title>Browsing the frame</title>
<content>
<para>The event browser is primarily intended as a tool to browse through the frame. Events
are listed as entries in the browser and the hierarchical labels mentioned above become
tree nodes.</para>
<para>The currently selected event is highlighted and indicated with a green flag
<mediaLinkInline><image xlink:href="GreenFlag"/></mediaLinkInline>. This is the event
that RenderDoc is inspecting and is reflected in all the other windows of the UI.</para>
<mediaLink>
<caption placement="after" lead="Current Event">The Event browser showing several sections and the current event.</caption>
<image xlink:href="QuickStart4"/>
</mediaLink>
<para>The EID column indicates the event ID of the drawcall listed. Event IDs are
assigned starting from 1 and increase every time an API call is made - for this
reason drawcall EIDs are not necessarily contiguous.</para>
<para>Simply clicking on a different event will select it as current, and selecting
a parent node with some child events will act as if the final child is selected -
in other words selecting a node with several children will show the results of all
children having happened.</para>
<para>You can also use keyboard shortcuts to browse through the frame. Pressing up or
down arrow key will move up and down through the visible elements, skipping over any
sections which are collapsed. These keys will move into and out of a sub-section into
the next sibling afterwards - essentially going straight up and down as if there is
not a tree and it is a straight list.</para>
<para>The left and right arrows go into and out of hierarchy levels. When within a level
pressing left will jump to the parent node of the current level. Pressing left again
will collapse that node, and so on. Pressing right will (if on a node with children)
expand that node.</para>
</content>
</section>
<section address="searching">
<title>Searching and Jumping</title>
<content>
<para>There are two other controls available in the Event Browser to aid in navigating
the frame.</para>
<para>Pressing <command>Ctrl-F</command> will open the find-event toolbar
<mediaLinkInline><image xlink:href="find"/></mediaLinkInline>. This toolbar
allows you to type in a partial text filter that will be matched against both labels
and drawcall events. The find will be executed when you press enter, although you can then
adjust the text and re-search if you wish.</para>
<para>If the event found lies inside an unexpanded section, the sections will be
expanded until the matching event is visible.</para>
<para>Matching events will be highlighted with a find icon
<mediaLinkInline><image xlink:href="find"/></mediaLinkInline>, and pressing
enter repeatedly will jump between matching events.</para>
<para>The find toolbar isn't dismissed until you press escape in the text box, or click the close button
<mediaLinkInline><image xlink:href="cross"/></mediaLinkInline>.</para>
<para>You can also jump up and down between find results with the
previous <mediaLinkInline><image xlink:href="stepprev"/></mediaLinkInline>
and next <mediaLinkInline><image xlink:href="stepnext"/></mediaLinkInline>
buttons.</para>
<mediaLink>
<caption placement="after" lead="Highlighted Results">The results of a find are highlighted with an icon.</caption>
<image xlink:href="FindResults"/>
</mediaLink>
<para>Pressing <command>Ctrl-G</command> will open the jump to EID toolbar. This allows
you to type in an EID and jump straight there, expanding nodes as necessary. If the EID
typed doesn't exist in the list of drawcalls, the closest matching EID will be jumped
to.</para>
<para>When you hit enter to jump to an EID, the toolbar closes and if you wish to jump again
you must press <command>Ctrl-G</command> again</para>
<mediaLink>
<caption placement="after" lead="Jumping around">The jump-to-EID toolbar prompting for an event.</caption>
<image xlink:href="JumpEID"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/LiveCapture.aml
+108
View File
@@ -0,0 +1,108 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="6f4dad92-3db3-448f-9f1a-79af65f74492" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The Live capture window opens up when you launch a capture of a program, as well as when
you attach to an existing program.</para>
</introduction>
<section address="attaching">
<title>Attaching to an existing instance</title>
<content>
<para>
After you've launched a program through RenderDoc and its hooks are added you can freely disconnect
(by closing the live capture window) or close the main UI. You can then connect to this again later,
either from the same computer or another computer connecting over the network.
</para>
<para>
To connect to an existing hooked program, select Attach to Running Instance from the File menu. This opens up
the attach window that allows you to select a remote host to connect to. By default localhost is already
in the list, but you can add and remove other hosts.
</para>
<alert class="caution">
<para>Please note that none of the connections RenderDoc makes or uses are encrypted or protected, so if this is a
concern you should look into securing the connections by hand.</para>
</alert>
<mediaLink>
<caption placement="after" lead="Remote Hosts">Attaching to a running instance either locally or remotely.</caption>
<image xlink:href="AttachInstance"/>
</mediaLink>
<para>
When the window opens, when you add a new host or when you click refresh then the hosts will be queried
across the network to see if a connection exists. While this is in progress the host will be listed in
italics and with a busy icon.
</para>
<para>
Once a host has been scanned, if any instances are found then that host can be expanded to see the list, and
details are listed about each instance. The name is OS-dependent but is usually the executable name. The API
name is listed, as well as the username of any user that is already connected.
</para>
<para>
When you click connect, a live capture window will be opened up - just the same as the window that is automatically
opened when you start a program. Any captures that have already been made before you connect will then populate.
</para>
<alert class="note">
<para>If you connect to a running instance, any existing user will be kicked off. Just seeing the instances running on
a host will not.</para>
</alert>
</content>
</section>
<section address="multicap">
<title>Capture Connection window</title>
<content>
<para>
When a capture is launched (or attached to) the connection window is opened in the main UI. If you
end up only taking one capture and closing the program afterwards the connection window will automatically
close - likewise if you take no captures at all. These cases don't need the management options the connection
window provides.
</para>
<para>
In addition to managing captures that have been taken, you can also trigger a capture (optionally with a
countdown timer).
</para>
<mediaLink>
<caption placement="after" lead="Connection Window">Viewing multiple captures taken in a program.</caption>
<image xlink:href="MultipleCaptures"/>
</mediaLink>
<para>
In this example we have a connection window open to the CascadedShadowMaps11 sample from the DirectX SDK.
Two captures have been made and we can see their thumbnails to help distinguish between them. This is visible
at any point, regardless of whether you have close the program or not - you can simply switch back to RenderDoc
while it's running.
</para>
<alert class="note">
<para>Note, if you have remotely connected you will need to wait while the captures copy across the network
to your PC, after which point everything behaves the same as a local capture.</para>
</alert>
<para>
From here you can save these captures out - as currently they are only temporary copies that will be
cleaned up on close. You can also manually delete any capture you wish to discard.
</para>
<para>
Double clicking on any capture will close any current open capture in the RenderDoc UI, and open up that
capture for inspection. You may also right click or use the drop-down menu on the open button to
launch a new instance of RenderDoc for viewing the log. This is mostly useful if you want to compare two
captures side-by-side easily.
</para>
<mediaLink>
<caption placement="after" lead="New instance">Launch new RenderDoc instance to open this capture.</caption>
<image xlink:href="OpenCapNewInstance"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/Options.aml
+173
View File
@@ -0,0 +1,173 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The options window contains various advanced or niche settings that configure
the analysis UI.</para>
</introduction>
<section address="options">
<title>Options</title>
<content>
<para>Below each tab of the options window is detailed with explanations of the
given settings.</para>
<para>Some settings may not be saved until the application is closed, although
most will come into immediate effect.</para>
<para>The settings are contained in <codeInline>%APPDATA%\RenderDoc\UI.config</codeInline> if you wish to
back up or reset these settings.</para>
</content>
</section>
<section address="general">
<title>General options</title>
<content>
<table>
<tableHeader>
<row>
<entry><para>Name</para></entry>
<entry><para>Explanation</para></entry>
<entry><para>Default Setting</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Associate .rdc with RenderDoc</para></entry>
<entry><para>This button will elevate RenderDoc to administrator privileges temporarily, and
associate the .rdc file extension with RenderDoc. After doing this double clicking any .rdc file
will open it in a new instance of RenderDoc.</para></entry>
<entry><para></para></entry>
</row>
<row>
<entry><para>Associate .cap with RenderDoc</para></entry>
<entry><para>This button will elevate RenderDoc to administrator privileges temporarily, and
associate the .cap file extension with RenderDoc. After doing this double clicking any .cap file
will open a new instance of RenderDoc and show the capture dialog with the settings contained inside.</para>
<para>If the setting "Auto Start" is enabled, RenderDoc will then immediately trigger a capture of
the target executable.</para></entry>
<entry><para></para></entry>
</row>
<row>
<entry><para>Minimum decimal places on float values</para></entry>
<entry><para>Defines the smallest number of decimal places to display on a float, padding with
0s.</para>
<para>Examples:</para>
<para>With a value of 2, <codeInline>0.1234f</codeInline> will be displayed as <math>0.1234</math></para>
<para>With a value of 2, <codeInline>1.0f</codeInline> will be displayed as <math>1.00</math></para>
<para>With a value of 6, <codeInline>0.1234f</codeInline> will be displayed as <math>0.123400</math></para>
<para>With a value of 6, <codeInline>1.0f</codeInline> will be displayed as <math>1.000000</math></para></entry>
<entry><para>2</para></entry>
</row>
<row>
<entry><para>Maximum significant figures on decimals</para></entry>
<entry><para>Defines the most significant figures to display after the decimal place on
floating point numbers.</para>
<para>Examples:</para>
<para>With a value of 5, <codeInline>0.123456789f</codeInline> will be displayed as <math>0.12345</math></para>
<para>With a value of 5, <codeInline>1.0f</codeInline> will be displayed as <math>1.00</math></para>
<para>With a value of 10, <codeInline>0.123456789f</codeInline> will be displayed as <math>0.123456789</math></para>
<para>With a value of 10, <codeInline>1.0f</codeInline> will be displayed as <math>1.00</math></para></entry>
<entry><para>5</para></entry>
</row>
<row>
<entry><para>Negative exponential cutoff value</para></entry>
<entry><para>Any floating point numbers that are below <math>E-v</math> for this value <math>v</math>
will be displayed in scientific notation rather than as a fixed point decimal.</para>
<para>Examples:</para>
<para>With a value of 5, <codeInline>0.1234f</codeInline> will be displayed as <math>0.1234</math></para>
<para>With a value of 5, <codeInline>0.000001f</codeInline> will be displayed as <math>1.0E-6</math></para>
<para>With a value of 10, <codeInline>0.1234f</codeInline> will be displayed as <math>0.1234</math></para>
<para>With a value of 10, <codeInline>0.000001f</codeInline> will be displayed as <math>0.000001</math></para></entry>
<entry><para>5</para></entry>
</row>
<row>
<entry><para>Positive exponential cutoff value</para></entry>
<entry><para>Any floating point numbers that are larger than <math>E+v</math> for this value <math>v</math>
will be displayed in scientific notation rather than as a fixed point decimal.</para>
<para>Examples:</para>
<para>With a value of 7, <codeInline>8000.5f</codeInline> will be displayed as <math>8005.5</math></para>
<para>With a value of 7, <codeInline>123456789.0f</codeInline> will be displayed as <math>1.2345E8</math></para>
<para>With a value of 2, <codeInline>8000.5f</codeInline> will be displayed as <math>8.0055E3</math></para>
<para>With a value of 2, <codeInline>123456789.0f</codeInline> will be displayed as <math>1.2345E8</math></para></entry>
<entry><para>7</para></entry>
</row>
<row>
<entry><para>Allow periodic anonymous update checks</para></entry>
<entry><para>Every couple of days RenderDoc will send a single web request to a server to see if a new version
is available and let you know about it. The only information transmitted is the version of RenderDoc that is running.</para>
<para>If you would prefer RenderDoc does not ever contact an external server, disable this checkbox. If you do this it's
recommended that you manually check for updates as new versions will be made available regularly with bugfixes.</para></entry>
<entry><para>Enabled</para></entry>
</row>
</table>
</content>
</section>
<section address="texture">
<title>Texture Viewer options</title>
<content>
<table>
<tableHeader>
<row>
<entry><para>Name</para></entry>
<entry><para>Explanation</para></entry>
<entry><para>Default Setting</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Reset Range on changing selection</para></entry>
<entry><para>When changing texture from one to another, when this option is enabled the range
control will reset itself to [0, 1]. This will happen between any two textures, and going back
and forth between two textures will also reset the range.</para></entry>
<entry><para>Disabled</para></entry>
</row>
</table>
</content>
</section>
<section address="shader">
<title>Shader Viewer options</title>
<content>
<table>
<tableHeader>
<row>
<entry><para>Name</para></entry>
<entry><para>Explanation</para></entry>
<entry><para>Default Setting</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Rename disassembly registers</para></entry>
<entry><para>This option tries to make the disassembly of shaders easier to read by substituting
variable names where available in for constant register names.</para></entry>
<entry><para>Enabled</para></entry>
</row>
</table>
</content>
</section>
<section address="shader">
<title>Event Browser options</title>
<content>
<table>
<tableHeader>
<row>
<entry><para>Name</para></entry>
<entry><para>Explanation</para></entry>
<entry><para>Default Setting</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Time unit used for event browser timings</para></entry>
<entry><para>This option allows you to select the unit that will be shown in the duration column
in the event browser when you time individual drawcalls.</para>
<para>Seconds through to nanoseconds are supported.</para></entry>
<entry><para>Enabled</para></entry>
</row>
<row>
<entry><para>Hide empty marker sections</para></entry>
<entry><para>Marker sections that contain no API calls or drawcalls will be completely removed.
This also applies to the Timeline Bar.</para>
<para>This option only applies itself the next time you load a log.</para></entry>
<entry><para>Disabled</para></entry>
</row>
</table>
</content>
</section>
</developerConceptualDocument>
</topic>
docs/Windows/PipelineState.aml
+55
View File
@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="A44E2304-6C11-451D-89C4-0A7397F5D1C6" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>The Pipeline Viewer is an information dense but simple window
in RenderDoc. It shows all of the stateful settings of the graphics pipeline, including
bound resources, rasterizer settings, etc.</para>
</introduction>
<section address="pipeline">
<title>Pipeline flowchart</title>
<content>
<para>At the top of the Pipeline Viewer is the pipeline flowchart - this shows the
high-level block level diagram of the graphics pipeline.</para>
<para>Each block is a separate page which contains the relevant state and contents
for that piece of the graphics pipeline, with specific details varying by API
and the type of data to be displayed.</para>
<para>The currently selected block is outlined with red, and the page in view reflects
the contents of that section of the pipeline. Light grey parts of the pipeline are
those which are currently active and participating in this drawcall. Dark grey parts
of the pipeline are not present and can be considered pass-through/do-nothing.</para>
<mediaLink>
<caption placement="after" lead="Pipeline">Pictured here, the high-level parts of the D3D11 Pipeline.</caption>
<image xlink:href="PipelineBar"/>
</mediaLink>
<alert class="note">
<para>In D3D11, the Stream-Out stage is available under the Geometry Shader block, with the buffers
being used for stream-out shown.</para>
</alert>
</content>
</section>
<section address="display">
<title>Pipeline Section Display</title>
<content>
<para>The pipeline state viewer always displays the state of the pipeline after the execution of the
drawcall, as with the other viewers in RenderDoc.</para>
<para>Any resources that are bound to the pipeline can be opened in more detailed viewers, such as
vertex buffers, constant buffers and textures. More details of this process can be found in the page
<link xlink:href="7A620DF5-332E-44CA-8FD5-9E47A9C4CC3E" />.</para>
<para>The pipeline view attempts to only show what is relevant, and not all possible stateful data.
To do this (when available) it uses shader reflection data to only display slots which are actually
in use by the shaders, and omit any that are unused. This can be overridden with the Show Disabled
Items <mediaLinkInline><image xlink:href="page_white_delete"/></mediaLinkInline> button.</para>
<para>Likewise it will omit any slots which are completely empty (and also unused), and this behaviour
can be overridden with the Show Empty Items <mediaLinkInline><image xlink:href="page_white_database"/></mediaLinkInline> button.</para>
<para>When showing disabled or empty entries, they will either be in <legacyItalic>italics</legacyItalic>
or on a dark red background respectively.</para>
</content>
</section>
<relatedTopics>
<link xlink:href="7A620DF5-332E-44CA-8FD5-9E47A9C4CC3E" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/Windows/TextureViewer.aml
+337
View File
@@ -0,0 +1,337 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="2c540574-0b81-4a40-8119-ba0283fddf41" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The texture viewer is likely the most intuitive window in RenderDoc and commonly
the most regularly used. It displays the contents of any texture in its current state
at the given event, as well as providing controls to adjust and inspect it in different
ways.</para>
</introduction>
<section address="overview">
<title>Overview</title>
<content>
<para>The texture viewer consists of a couple of different sections, which will be
outlined here.</para>
<para>Several specific techniques or features used within the texture viewer have their
own separate pages that go into more detail. You might find more useful information there
if they cover what you are looking for:
<link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" />,
<link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501" />,
<link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018" />
</para>
<mediaLink>
<caption placement="after" lead="Texture Viewer">A labelled diagram showing the different parts of the texture viewer.</caption>
<image xlink:href="LabelledTexViewer"/>
</mediaLink>
</content>
</section>
<section address="main">
<title>Main Texture Display</title>
<content>
<para>The main texture display takes up the largest portion of the window, and is simply a container for the
textures to display.</para>
<para>It is a tabbed control and although one tab is always present showing the currently followed texture
bound to the pipeline, other locked tabs can be opened up showing a single resource. More details are available
on the page <link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" />.</para>
<para>The mouse wheel can be used to zoom in and out of the texture. When zoomed in, holding the left mouse
button and dragging will pan the image from side to side.</para>
<para>While over the image the status bar will show the current pixel that the mouse
is over. Clicking or holding the right mouse button will pick this pixel and show its information in the status
bar. More information is available on the page <link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501" />.</para>
</content>
</section>
<section address="status">
<title>Information Status Bar</title>
<content>
<para>The status bar below the main texture display contains information on the currently visible texture.</para>
<list class="bullet">
<listItem><para>The name (if available - if not a default name will be used).</para></listItem>
<listItem><para>Dimensions - Width, height, depth and array size as applicable.</para></listItem>
<listItem><para>Mip Count.</para></listItem>
<listItem><para>MSAA sample count and quality, if applicable.</para></listItem>
<listItem><para>Format - e.g. RGB8. The exact phrasing of this will vary by API.</para></listItem>
</list>
<para>After this information there are a few displays that are pixel-based. The pixel that is under the cursor
is displayed as a colour swatch, followed by its co-ordinates. Then any
<link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501">picked pixel</link> is displayed afterwards with its
numeric value displayed.</para>
<mediaLink>
<caption placement="after" lead="Picked Pixels">Detailed information about the current pixel.</caption>
<image xlink:href="RMBStatus"/>
</mediaLink>
</content>
</section>
<section address="thumbs">
<title>Thumbnail Strips</title>
<content>
<para>There are several thumbnail strip panels available, by default they are docked in the same
location such that they are tabbed together, but they can be displayed side by side.</para>
<para>These strips display thumbnails of the resources bound to their respective parts of the
pipeline, to give some context and allow quick preview without having to switch the main
display between these textures.</para>
<para>The texture that the following tab is currently displaying is highlighted in red, and
each thumbnail shows both the slot number and the name of the texture bound at that point.
To follow a given slot simply left click on it.
If the currently followed texture slot is empty (i.e. it was following a texture and then
that slot was unbound) it will show up simply named "Unbound" and with no name or slot number.</para>
<para>Each thumbnail has a context menu available via right click. This menu allows you to open
a locked tab (<link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4">More information</link>),
as well as containing a list of all the uses of this texture - as read-only resource and writable
output. This is similar to the resource display strip on the <link xlink:href="745E3EB5-EB29-4010-BBAB-B11282F4380C" />.
Clicking on any of these entries will jump to the first of the events in the event range listed.</para>
<mediaLink>
<caption placement="after" lead="Thumbnail Menu">Thumbnail context menu with several options.</caption>
<image xlink:href="OpenLockedTab"/>
</mediaLink>
<para>There are also two general options - show disabled and show empty. These behave the same as the
options in the <link xlink:href="A44E2304-6C11-451D-89C4-0A7397F5D1C6" /> window - temporarily overriding
the default behaviour in RenderDoc to only show texture slots that are referenced in the shader.</para>
</content>
</section>
<section address="context">
<title>Pixel Context Display</title>
<content>
<para>The Pixel context display is a small panel by default in the bottom right of the texture viewer.</para>
<para>Whenever a pixel is picked small area of the texture around it is rendered at maximum zoom to this
panel. This gives you some context for the pixels nearby to the one you're picking and allows fine refinement
without needing to zoom in and lose your place in the overall image.</para>
<mediaLink>
<caption placement="after" lead="Pixel context">Pixel context displaying the surrounds of the picked pixel.</caption>
<image xlink:href="PixelContext"/>
</mediaLink>
</content>
</section>
<section address="range">
<title>Visible Range Control</title>
<content>
<para>The visible range or range adaption control is very useful in easing display and inspection of
images with a very narrow range of values, and is necessary for viewing any HDR images as it can be
used to map a larger range down to LDR for display.</para>
<mediaLink>
<caption placement="after" lead="Range control">The range control narrowing the visible range mapped to [0,1] on output.</caption>
<image xlink:href="RangeControl"/>
</mediaLink>
<para>The primary controls are the black point and white point. These are shown in two text boxes at
either side of the main range control. These are the current absolute black and white values - these values
in the input texture are mapped to 0 and 1 respectively on output.</para>
<para>The range control itself has a black point and a white point that can be adjusted simply by clicking and
dragging. These allow finer and more interactive adjustments. These handle only allow you to adjust the extremes
within the range defined by the absolute black and white points in the text box.</para>
<para>There are four other buttons available for control of the range:</para>
<list class="bullet">
<listItem><para><mediaLinkInline><image xlink:href="zoom"/></mediaLinkInline> <ui>Zoom in</ui> -
This button will zoom the extreme values in to whichever fine values have been selected by the draggable handles.</para>
<para>This is primarily useful when starting from some large range and using the handles to drag down to a more reasonable
range, you can click zoom to then reduce the range down to just the one selected, so you can again get fine control.</para>
<mediaLink>
<caption placement="after" lead="Before">The range control before zooming.</caption>
<image xlink:href="BeforeRangeZoom"/>
</mediaLink>
<mediaLink>
<caption placement="after" lead="After">The range control after zooming.</caption>
<image xlink:href="AfterRangeZoom"/>
</mediaLink>
</listItem>
<listItem><para><mediaLinkInline><image xlink:href="wand"/></mediaLinkInline> <ui>Autofit</ui> -
This button automatically fits the range control to the min and max values in any visible channels in the texture.
Oftentimes this is a good starting point for a range, although with some extreme textures it may adjust badly.</para>
<para>Right clicking on this button will cause it to always auto-fit until you disable this. ie. when you move
to another event or another texture, the range will be auto-fit again. This is useful if jumping between events
or textures where the visible ranges are very different.</para></listItem>
<listItem><para><mediaLinkInline><image xlink:href="UndoArrow"/></mediaLinkInline> <ui>Reset</ui> -
Simply resets the range back to the default of [0, 1] - useful for resetting after changing to a new texture where the
range settings aren't applicable.</para></listItem>
<listItem><para><mediaLinkInline><image xlink:href="chart_curve"/></mediaLinkInline> <ui>Histogram</ui> -
This is a toggle switch. When enabled it will change the thin bar of the range control into a thicker bar
that contains a range-value histogram, showing the distribution of values.</para>
<para>The histogram is based on the straight numerical mean of all visible channels, and will update as the
white and black points move.</para>
<mediaLink>
<caption placement="after" lead="Values Histogram">A histogram showing the range distribution of values in the image.</caption>
<image xlink:href="RangeHistogram"/>
</mediaLink></listItem>
</list>
</content>
</section>
<section address="toolbar">
<title>Toolbar</title>
<content>
<para>The toolbar contains most of the tools for selecting which mip, slice, face of
a texture to view as well as how to display it and if any transformations or overlays
should be applied.</para>
<alert class="note">
<para>The visible range/range adaption control is detailed in the section above and will not be covered here.</para>
</alert>
<table>
<tableHeader>
<row>
<entry><para>Control</para></entry>
<entry><para>Explanation</para></entry>
</row>
</tableHeader>
<row>
<entry>
<para><mediaLinkInline><image xlink:href="RGBAChannels"/></mediaLinkInline> Channels selector</para>
<para><mediaLinkInline><image xlink:href="RGBMChannels"/></mediaLinkInline> RGBM mode</para>
<para>
<mediaLinkInline><image xlink:href="CustomDisplay"/></mediaLinkInline>
<mediaLinkInline><image xlink:href="add"/></mediaLinkInline>
<mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline>
<mediaLinkInline><image xlink:href="delete"/></mediaLinkInline>
<link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018">Custom Shader</link></para>
</entry>
<entry><para>This selector switches between displaying standard RGBA channels, RGBM encoding with a custom
multiplier and using a custom visualiser shader.</para>
<para>When in <ui>RGBA</ui> mode, by default only the RGB channels are displayed and alpha is forced to fully opaque.
Each of the channels can be toggled off independently and any combination can be used. Any RGB channel which
is disabled is forced to fully black in the output. When Alpha is enabled, the background will be rendered
with a solid colour or checkerboard pattern to indicate semi-transparent areas.</para>
<para>Also note that when a single channel is displayed solo, the image is rendered as grayscale in that channel
rather than displaying a monochromatic coloured image.</para>
<alert class="tip">
<para>Right clicking on one of the channel buttons in the texture viewer
(R, G, B, A) will either select only that channel, or if it's already the only one
selected it will select all of the others. This is useful e.g. to toggle between viewing
RGB and alpha, or for looking at individual channels in a packed texture or render target.</para>
</alert>
<para>When <ui>RGBM</ui> is selected, the RGB value will be multiplied by the specified multiplier and then by
the alpha value. This is a common encoding used to pack a larger range into an 8-bit RGB image.</para>
<para>With <ui>Custom</ui> selected a dropdown will be populated with any .hlsl files in the
<codeInline>%APPDATA%\renderdoc</codeInline> folder. When choosing a custom shader the raw image will be
passed through this shader before being displayed with the usual controls on the main display.</para>
<para>You can create a new custom shader with the <mediaLinkInline><image xlink:href="add"/></mediaLinkInline> button,
edit a shader with the <mediaLinkInline><image xlink:href="page_white_edit"/></mediaLinkInline> button,
and delete an one with the <mediaLinkInline><image xlink:href="delete"/></mediaLinkInline> button.</para>
</entry>
</row>
<row>
<entry>
<para><mediaLinkInline><image xlink:href="color_wheel"/></mediaLinkInline>
<mediaLinkInline><image xlink:href="crosshatch"/></mediaLinkInline>
Alpha Background
</para>
</entry>
<entry><para>When displaying a texture with alpha channel, the background of the main display changes to make
the semi-transparent sections more obvious. With these two controls you can either choose a checkerboard pattern
<mediaLinkInline><image xlink:href="crosshatch"/></mediaLinkInline> or open a colour picker to choose a solid
colour <mediaLinkInline><image xlink:href="color_wheel"/></mediaLinkInline>.</para>
</entry>
<para>The currently enabled mode will be highlighted.</para>
</row>
<row>
<entry>
<para>Subresource selection <mediaLinkInline><image xlink:href="SubresourceSelect"/></mediaLinkInline></para>
</entry>
<entry><para>The main display of the texture viewer can only display at most a single 2D image at once.</para>
<para>For textures with mip-maps this control allows you to select the mip level to display - the overall size
of the image will remain the same but will be point sampled from the given mip level.</para>
<para>For 3D textures and 2D arrays you can select the slice to display here from the drop-down, and for cubemaps
you can select the face. For cubemap arrays these two controls are combined to show a list of the faces for the first
cubemap, then the second, etc.</para>
</entry>
</row>
<row>
<entry>
<para><mediaLinkInline><image xlink:href="save"/></mediaLinkInline> Save Texture</para>
</entry>
<entry><para>This allows you to save the currently visible texture. Currently only .dds format is supported, and
there are some limitations in the formats that can be saved - e.g. there is no standard way to support multisampled
dds files, so this will fail. Most common formats can be saved to disk in this way.</para>
</entry>
</row>
<row>
<entry>
<para><mediaLinkInline><image xlink:href="wrench"/></mediaLinkInline> Debug a Pixel</para>
</entry>
<entry><para>This button is only enabled after a
<link xlink:href="8a7568ca-6b2c-4873-b8eb-d1ad2aff9629">pixel has been picked</link>.</para>
<para>This will do exactly the same as the button underneath the pixel context display - it will
launch a pixel debugger for the currently picked pixel.</para>
</entry>
</row>
<row>
<entry>
<para><mediaLinkInline><image xlink:href="page_white_link"/></mediaLinkInline> Open Texture List</para>
</entry>
<entry><para>This button opens the texture list of all textures present in the capture. More details can
be seen in <link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" /></para>
</entry>
</row>
<row>
<entry>
<para>Zoom controls <mediaLinkInline><image xlink:href="ZoomControls"/></mediaLinkInline></para>
</entry>
<entry><para>The zoom controls are fairly self explanatory - a pre-existing zoom value can be chosen
from the drop down or a custom value (clamped to the minimum and maximum zoom) can be entered as a
percentage.</para>
<para>To automatically fit the texture to the space available in the window, regardless of its
dimensions, you can click the <mediaLinkInline><image xlink:href="fit_window"/></mediaLinkInline> Fit
button.</para>
<alert class="note">
<para>As noted above, the mouse scroll wheel in the main display also changes the zoom level.</para>
</alert>
</entry>
</row>
<row>
<entry>
<para>Render Overlay <mediaLinkInline><image xlink:href="OverlaySelect"/></mediaLinkInline></para>
</entry>
<entry><para>This is a powerful tool for quickly diagnosing issues and can be very useful for locating
what you're looking for. Several overlays are available that can be rendered over any texture, although
most of them are only meaningful for currently bound render targets.</para>
<list class="bullet">
<listItem><para><command>Highlight Drawcall</command> will do pretty much as it says. It darkens everything except
the current drawcall which is highlighted in flat colour. This makes whatever is being drawn stand out and can be useful
for seeing where the current object is on screen, especially if rapidly browsing through the frame.</para></listItem>
<listItem><para><command>Wireframe Mesh</command> will render a wireframe mesh of the current drawcall
over the top of the image.</para></listItem>
<listItem><para><command>Depth Test</command> will render an overlay over the drawcall, with red sections covering
any part of the drawcall that never passed the depth test, and green sections covering areas that did pass the
depth test. Note that if the drawcall overdraws itself then as long as at least one pass over a pixel passes the depth test
then that pixel will be green.</para></listItem>
<listItem><para><command>Stencil Test</command> performs similarly to the depth test, but for the stencil test.</para></listItem>
<listItem><para><command>Viewport/Scissor</command> shows a coloured overlay on the image that corresponds to the viewport
and scissor regions.</para></listItem>
<listItem><para><command>NaN/Inf/-ve display</command> will render the image in grayscale (using the typical luminance
calculation - <codeInline>dot(col.xyz, float3(0.2126, 0.7152, 0.0722)).xxx</codeInline>) with red pixels highlighting any
NaNs found, green pixels highlighting any infinities, and blue pixels for any negative values. Note that in any case
where only one or some channels in a multi-channel texture pass, that pixel will still be highlighted (so
<codeInline>{0.5, -1.0, 0.0}</codeInline> would highlight blue).</para></listItem>
<listItem><para><command>Clipping</command> will simply highlight in red any values that are below the current
black point (as defined by the range control - see above), and in green any values above the white point. This can
be useful in identifying invalid ranges if the range control is adjusted correctly, or in combination with a custom
shader visualiser.</para></listItem>
</list>
<alert class="note">
<para>These overlays are all rendered after most image controls are applied. For this reason the range control,
channel controls and custom shaders do not affect the overlays.</para>
</alert>
</entry>
</row>
</table>
</content>
</section>
<relatedTopics>
<link xlink:href="32C47E20-0FA2-4F52-B33A-4440EBCCBCE4" />
<link xlink:href="F1C1E449-55ED-46FE-BBFD-11D1A0511501" />
<link xlink:href="a00964a1-733f-4288-a79e-c28238bc6018" />
</relatedTopics>
</developerConceptualDocument>
</topic>
docs/Windows/TimelineBar.aml
+81
View File
@@ -0,0 +1,81 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="745E3EB5-EB29-4010-BBAB-B11282F4380C" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline />
<para>The timeline bar shows an alternate view of the scene to the
<link xlink:href="16D2B42E-65B0-40D1-AB91-AD2B156F5DA0" />. Displaying the scene with
time running as the horizontal axis, although it does not show each section in size
relative to its timing.</para>
</introduction>
<section address="intro">
<title>Introduction</title>
<content>
<para>The timeline bar shows the scene horizontally with the hierarchical frame
markers being expandable from top to bottom.</para>
<para>This alternate view can be a useful way to get an overview of the whole frame,
allowing you to jump around very different parts of the frame.</para>
<para>Given that the timeline bar shows the whole frame it also provides a secondary
function of showing dependencies in a global way. For whichever texture is currently
selected in the texture viewer, the timeline bar shows reads and writes to that texture
throughout the frame. This can be especially useful for render targets that are used
in both ways, as well as simply to see where a given texture is used in a frame
without laboriously searching.</para>
<mediaLink>
<caption placement="after" lead="Timeline Bar">The timeline bar showing a birds-eye view of a typical application.</caption>
<image xlink:href="TimelineBar"/>
</mediaLink>
</content>
</section>
<section address="display">
<title>Timeline Display</title>
<content>
<para>By default the timeline bar views the whole frame, but with the mouse wheel
you can zoom in and out. When zoomed in, you can scroll through the frame with
the horizontal scroll bar.</para>
<para>The timeline bar sizes the sections that it contains to try and make the
frame markers as visible as possible. This attempts to keep the frame browsable
for as long as possible, such that small sections (in time or number of events)
are still visible rather than being crushed to tiny bars.</para>
<para>For this reason the timeline can resize itself when bars are expanded,
as this can reveal new sections which must be allocated enough room. When there
is slack space to be allocated it is given to the sections which have more events
than others.</para>
<para>Underneath expanded sections, a blue pip is rendered for each drawcall-type
event. The currently selected event is shown as a green pip, as well as there being
a light grey vertical line to indicate the current position, such that this is visible
even when the relevant section is not expanded.</para>
<para>Clicking on any section will toggle it between expanded and unexpanded, and
any sections underneath a section which is collapsed will remain in their previous state
but will not be visible.</para>
<para>Left clicking on the timeline will jump to the event underneath that point
on the horizontal display.</para>
</content>
</section>
<section address="usage">
<title>Resource usage Display</title>
<content>
<para>The timeline bar also shows the usage of the currently displayed texture.</para>
<para>Whichever texture is currently displayed in the <link xlink:href="2c540574-0b81-4a40-8119-ba0283fddf41" />
(whether that be a currently bound texture, or a locked tab) will have its usage
laid out across the frame on the timeline bar.</para>
<para>If your textures have their names annotated you will see which texture is being
inspected in the label for the usage bar.</para>
<para>A green arrow will be drawn under each pip that reads from the texture. If the pips
are too close together to resolve the arrow, the arrows will stay distinct and lose the
1:1 association with event pips.</para>
<para>Similarly, a purple arrow will be drawn under pips where the event writes to the
texture. In the case that a resource is bound such that it can be read or written,
the arrow will be half-green, half-purple.</para>
<para>Clear calls will be shown with a light grey.</para>
<para>In cases where the arrows are too close together to show distinctly, they
will not all draw. To see exactly what usage is happening you can zoom into the context
around that area of the frame.</para>
<mediaLink>
<caption placement="after" lead="Resource Usage">The usage bar showing reads and writes to a texture.</caption>
<image xlink:href="ResourceUsage"/>
</mediaLink>
</content>
</section>
</developerConceptualDocument>
</topic>