mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 01:20:42 +00:00
baldurk
279 lines
16 KiB
XML
279 lines
16 KiB
XML
<?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 inject-into-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="injecting">
|
|
<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 inject into
|
|
and click Inject.</para>
|
|
<mediaLink>
|
|
<caption placement="after" lead="Injecting">Injecting into an already-running process via RenderDoc.</caption>
|
|
<image xlink:href="Injecting"/>
|
|
</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 inject 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. For OpenGL this means ARB_debug_output.
|
|
For Vulkan this option is unavailable due to RenderDoc being inserted as a layer and not able to activate
|
|
other layers (this would contradict the API's explicit nature).
|
|
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>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>
|
|
<para>See below for more information on handling of 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="note">
|
|
<para>This option has no effect on Vulkan - all command lists are implicitly captured.</para>
|
|
</alert>
|
|
|
|
<alert class="caution">
|
|
<para>This may have a significant performance hit.</para>
|
|
</alert>
|
|
</entry>
|
|
<entry><para>Disabled</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry><para>Verify Map() Writes</para></entry>
|
|
<entry><para>This option adds checking to any Map() calls that adds a boundary marker after any Map() pointer
|
|
returned during a captured frame. These markers are checked on Unmap() and if they have been modified a
|
|
message box will pop up alerting you to this, and you can click Yes to break in the debugger in the target
|
|
application and investigate the problem.</para></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>
|
|
<section address="childprocs">
|
|
<title>Child Processes</title>
|
|
<content>
|
|
<para>RenderDoc is able to automatically inject into any child processes started by the initial
|
|
process launched from the UI. To do this simply check "Hook into Children" in the options above.</para>
|
|
<para>RenderDoc has a particular handling of child processes to help you navigate to the process
|
|
of interest. Whenever a child process is launched, the UI is notified and a list of processes is
|
|
displayed in a box on the <link xlink:href="6f4dad92-3db3-448f-9f1a-79af65f74492" /> window.
|
|
You can double click on any of these entries to open up a new connection to that process,
|
|
in a new window.</para>
|
|
<para>If a process exits, instead of just closing the connection window if there have been no
|
|
captures, instead RenderDoc looks at the child processes - if there is only one child process,
|
|
it assume that process must be of interest and immediately switches to tracking that process.
|
|
If there are <legacyItalic>more</legacyItalic> than one child process open, the capture
|
|
connection window will stay open to give you a chance to double click on those child processes
|
|
to open a new connection window.</para>
|
|
</content>
|
|
</section>
|
|
<section address="globalhook">
|
|
<title>Global Process Hook</title>
|
|
<content>
|
|
<alert class="caution">
|
|
<para>This option is risky and should not be used lightly. Know what you're doing and
|
|
use it as a last resort.</para>
|
|
</alert>
|
|
<para>To expose this option you have to enable it in
|
|
<link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5">the settings</link>,
|
|
to prevent it being used accidentally.</para>
|
|
<para>When you've entered a path, or filename, in the executable text at the top
|
|
of the window, this option will then insert a global hook that causes <legacyBold>every</legacyBold> new
|
|
process created to load a very small shim dll.</para>
|
|
<para>The shim dll will load, create a thread that checks to see if the process
|
|
matches the path or filename specified, and then unload. If the process matches
|
|
it will also inject RenderDoc and capturing will continue as normal. At this
|
|
point you should <legacyItalic>first disable the global hook</legacyItalic>, then
|
|
you can use the 'Attach to running instance' menu option to continue as normal.</para>
|
|
<para>RenderDoc implements this behaviour by modifying the
|
|
<externalLink>
|
|
<linkText>AppInit_DLLs</linkText>
|
|
<linkAlternateText>AppInit_DLLs on MSDN</linkAlternateText>
|
|
<linkUri>http://support2.microsoft.com/kb/197571</linkUri>
|
|
</externalLink> registry key to reference RenderDoc's dlls. This is not a particularly safe
|
|
method but it's the only reliable method to do what we want. The shim dll is
|
|
deliberately made as small and thin as possible, referencing only kernel32.dll, to
|
|
minimise any risks.
|
|
</para>
|
|
<para>If RenderDoc crashes or something otherwise goes wrong while these registry
|
|
keys are modified, the shim dll will continue to be injected into every process which
|
|
is certainly not desireable. Should anything go wrong, RenderDoc writes a .reg
|
|
file that restores the registry to its previous state in %TEMP%.</para>
|
|
<para>Again, <legacyBold>this method should be a last resort</legacyBold>. Given
|
|
the risks you should always try to capture directly in some way before trying this.</para>
|
|
</content>
|
|
</section>
|
|
<relatedTopics>
|
|
<link xlink:href="f2f4fbfa-6127-4831-84e7-07309bd85908" />
|
|
<link xlink:href="14048aef-0053-4e38-98cd-541f4d15d12e" />
|
|
</relatedTopics>
|
|
</developerConceptualDocument>
|
|
</topic>
|