mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 17:40:39 +00:00
baldurk
c38affcded
* All renderdoc code up to this point was written by me, history is available by request
81 lines
4.5 KiB
XML
81 lines
4.5 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="14048aef-0053-4e38-98cd-541f4d15d12e" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<introduction>
|
|
<para>This page gives an overview of the callstack-capturing capability in RenderDoc,
|
|
with details and important information about how to enable this.</para>
|
|
</introduction>
|
|
<section address="Overview">
|
|
<title>Overview</title>
|
|
<content>
|
|
<para>It can be useful when tracking down problems to have an idea of where each
|
|
API call came from. In any non-trivial program it's not necessarily obvious where
|
|
every single call was made, and giving a code-side callstack up to the API entry
|
|
point can pinpoint errant calls that are causing problems.</para>
|
|
|
|
<alert class="caution">
|
|
<para>The callstack gathering uses dbghelp.dll. If you're using this
|
|
dll for some other debugging functionality in your app it is highly recommended that
|
|
you disable it, otherwise it can conflict and break RenderDoc's callstack capture.</para>
|
|
</alert>
|
|
|
|
<alert class="note">
|
|
<para>Callstack gathering has a reasonable overhead during capture and can slow things
|
|
down as well as cause more memory overhead. This can be mitigated with the 'only drawcall
|
|
callstacks' option that only lists callstacks for each drawcall event.</para>
|
|
</alert>
|
|
|
|
</content>
|
|
</section>
|
|
<section address="Capture">
|
|
<title>Launching Capture</title>
|
|
<content>
|
|
<para>When launching a capture (as in <link xlink:href="0dd6fe0d-4130-46f4-b2ea-9565de13111d" />)
|
|
you should enable 'collect callstacks'. This will set RenderDoc to collect callstacks at every
|
|
API entry point that will be serialised into the log.</para>
|
|
<mediaLink>
|
|
<caption placement="after" lead="Collect Callstacks">Option enabled on the capture dialog.</caption>
|
|
<image xlink:href="Callstacks"/>
|
|
</mediaLink>
|
|
<para>If you wish to save some time & overhead you can then enable 'Only drawcall stacks'.
|
|
This will only collect callstacks when a drawcall-type API call is made. This can be a good-enough
|
|
trade off that still gets you the information you need, at a lower cost. After this point you can
|
|
run the program and capture as usual.</para>
|
|
</content>
|
|
</section>
|
|
<section address="Replay">
|
|
<title>Replaying the capture</title>
|
|
<content>
|
|
<para>When the capture is loaded in RenderDoc the callstacks will be available in the API
|
|
inspector. The bottom section of the dialog is a panel that can be expanded to show the
|
|
callstack. Initially this section will indicate that symbols need to be resolved.</para>
|
|
<mediaLink>
|
|
<caption placement="after" lead="Callstack section">The callstack section expanded in API inspector.</caption>
|
|
<image xlink:href="NeedResolve"/>
|
|
</mediaLink>
|
|
<para>To resolve the symbols referenced in the capture, go to the <ui>Tools</ui> menu and
|
|
select <action>Resolve Symbols</action>. If this menu option isn't available the callstacks
|
|
did not successfully capture in the logfile.</para>
|
|
<para>The resolving symbols process may take some time the first few instances you use it,
|
|
as it may have to download symbols from the Microsoft symbol server. Each module that is loaded
|
|
in the application at the time of capture will be saved and its symbols searched for.</para>
|
|
<para>By default a symbol server will be used, as well as a few default locations such as the
|
|
location indicated in the PE metadata (i.e. the original build location). If a pdb cannot be found
|
|
you will be prompted for the location of the pdb, and this new location will then be remembered
|
|
for subsequent pdbs.</para>
|
|
<mediaLink>
|
|
<caption placement="after" lead="PDB locate prompt">Prompt to locate a PDB that cannot be found.</caption>
|
|
<image xlink:href="NeedPDB"/>
|
|
</mediaLink>
|
|
<para>If a PDB cannot be located then you have the option of permanently ignoring that PDB.
|
|
This can be useful for third party libraries for which no PDB will ever be available. If
|
|
you don't ignore the PDB you will be prompted to locate it the next time you open a log
|
|
that references it.</para>
|
|
<para>Once the symbols have been successfully resolved the callstack section of the API
|
|
inspector will contain any callstack that was collected for the given drawcall or API
|
|
call. You can select and copy any levels and paste them elsewhere if you wish.</para>
|
|
</content>
|
|
</section>
|
|
</developerConceptualDocument>
|
|
</topic>
|