mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 01:20:42 +00:00
baldurk
410 lines
20 KiB
XML
410 lines
20 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<topic id="b97b19f8-2b97-4dca-8a7a-ed7026eb43fe" revisionNumber="1">
|
|
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<introduction>
|
|
<autoOutline />
|
|
<para>
|
|
Here is a list of commonly asked questions about RenderDoc.
|
|
Feel free to contact me if you have another question that isn't covered here
|
|
or in this document.
|
|
</para>
|
|
</introduction>
|
|
<section address="FAQ1">
|
|
<title>How do I do some particular task?</title>
|
|
<content>
|
|
<para>
|
|
Many specific tasks or functions are detailed in the "How Do I... ?" sections.
|
|
These sections each take a feature or element of a workflow and explain how it
|
|
fits into the program as a whole as well as any details of how it works.
|
|
</para>
|
|
<para>
|
|
If the task you have in mind isn't listed there you might find something similar,
|
|
or you might find a related feature which can be used to do what you want. If
|
|
the feature you want doesn't seem to exist at all you might want to check the
|
|
<link xlink:href="632271c3-3d72-4360-b4a0-dc570fcd541e" />
|
|
to see if it's coming soon - if it's not on that list please feel free to contact
|
|
me and request it! <token>Baldur Contact</token>. It has often been that simple features
|
|
are very quick to implement and the prioritisation and scheduling of features is fairly
|
|
fluid at this stage in development.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ2">
|
|
<title>Why did you make RenderDoc?</title>
|
|
<content>
|
|
<para>
|
|
Although several tools do already exist for graphics debugging, none of them quite
|
|
suited the functionality I desired and I would often find myself wishing for a feature of
|
|
one in another and vice versa.
|
|
</para>
|
|
<para>
|
|
In addition to this, although the functionality overlaps to some degree many of these
|
|
tools were primarily designed around the profiling of applications rather than debugging.
|
|
While being able to inspect the state and contents of resources does often suffice for
|
|
debugging, it's not necessarily the ideal workflow and often it can become cumbersome.
|
|
</para>
|
|
<para>
|
|
In principle I didn't see any reason why I couldn't write a home-brew graphics debugger
|
|
with some fairly simple operating principles. While there were a whole lot of caveats
|
|
and little stumbling blocks along the way, the original design has pretty much stayed
|
|
consistent since the project was started back in July 2012. If you're interested you might
|
|
want to read about <link xlink:href="f351fea6-d0ac-426b-9631-feec2408a7e2" />.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ3">
|
|
<title>Where did the name come from?</title>
|
|
<content>
|
|
<para>
|
|
All of the good names were taken :-(.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ4">
|
|
<title>Who can I contact about bugs, feature requests, other queries?</title>
|
|
<content>
|
|
<para>
|
|
At the moment there's just me at the wheel - feel free to contact me at
|
|
<token>Baldur Contact</token> if you have anything you'd like to ask or suggest.
|
|
I use a <externalLink>
|
|
<linkText>github repository</linkText>
|
|
<linkAlternateText>Issues on github</linkAlternateText>
|
|
<linkUri>https://github.com/baldurk/renderdoc/issues</linkUri>
|
|
</externalLink> for tracking bugs and feature requests so that's the best place to
|
|
file an issue.
|
|
</para>
|
|
<para>
|
|
I work on RenderDoc in my spare time but I am happy to help with anything and
|
|
work with you if you have any issues that need attention.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ5">
|
|
<title>How can I associate RenderDoc's file extensions with the program?</title>
|
|
<content>
|
|
<para>
|
|
If you installed RenderDoc via the installer package rather than the zip folder, the option
|
|
is available there to associate RenderDoc's file extensions with the program. Otherwise you
|
|
can set them up from the <link xlink:href="B1826EEE-2ED1-44E4-8202-37CD8B3FEEB5" />.
|
|
</para>
|
|
|
|
<alert class="note">
|
|
<para>RenderDoc will elevate itself to set up these file associations, but otherwise will not hold
|
|
on to administrator permissions.</para>
|
|
</alert>
|
|
<para>
|
|
RenderDoc associates .rdc and .cap with itself when desired. The .rdc files are the logfiles
|
|
output when you capture inside an application. .cap files describe the set up of a
|
|
particular capture, and can be used to quickly re-launch a capture preset.
|
|
</para>
|
|
<para>
|
|
If .rdc files are associated with RenderDoc a thumbnail handler is set up, so that in explorer
|
|
you'll get thumbnail previews for your captures.
|
|
</para>
|
|
<alert class="caution">
|
|
<para>
|
|
Note that if you move the directory that RenderDoc is you will need to re-configure the
|
|
file associations as the registry entries contain absolute paths.
|
|
</para>
|
|
</alert>
|
|
|
|
</content>
|
|
</section>
|
|
<section address="FAQ6">
|
|
<title>What APIs does RenderDoc support?</title>
|
|
<content>
|
|
<para>
|
|
Currently RenderDoc supports D3D11 (including the D3D11.1/11.2 extensions where available),
|
|
and core profile OpenGL. Note OpenGL is a complex sprawling API, so see the details of
|
|
what is supported in <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">its own page</link>.
|
|
</para>
|
|
<para>
|
|
In future API support is planned for at D3D9 when time and scheduling allows. Higher priority are
|
|
the new APIs coming - Vulkan and D3D12. Mantle support will likely not happen as the API is not
|
|
planned to be publically available anymore.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ7">
|
|
<title>How can I backup or restore my settings?</title>
|
|
<content>
|
|
<para>
|
|
Everything RenderDoc relies upon is stored in %APPDATA%\RenderDoc. You can back up and restore
|
|
this directory at will as nothing stored in there is machine specific aside from things like
|
|
recent file lists.
|
|
</para>
|
|
<para>
|
|
Deleting this folder will also reset RenderDoc to the defaults - if you uninstall RenderDoc this
|
|
folder will <legacyItalic>not</legacyItalic> be deleted.
|
|
</para>
|
|
<para>RenderDoc doesn't install any registry keys aside from those to set up file associations.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ8">
|
|
<title>Which network ports does RenderDoc use?</title>
|
|
<content>
|
|
<para>
|
|
RenderDoc uses TCP and UDP ports 38920-38927 consecutively for remote access and control (ie.
|
|
capturing remotely) for each new program that is opened on a machine. Note that even if you
|
|
initiate a capture locally these ports are still opened for listening. These are the ports
|
|
that are probed on a remote host to see if a connection exists.
|
|
</para>
|
|
<para>
|
|
RenderDoc also uses TCP and UDP ports 39920 for remote replay connections, for when a remote
|
|
host is used to replay and analyse the log.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ9">
|
|
<title>Where can I get the source to RenderDoc?</title>
|
|
<content>
|
|
<para>
|
|
RenderDoc is licensed under the MIT license and the source is available on
|
|
<externalLink>
|
|
<linkText>github.com</linkText>
|
|
<linkAlternateText>RenderDoc @ github</linkAlternateText>
|
|
<linkUri>https://github.com/baldurk/renderdoc</linkUri>
|
|
<linkTarget>_blank</linkTarget>
|
|
</externalLink>
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ10">
|
|
<title>What are the requirements for RenderDoc?</title>
|
|
<content>
|
|
<para>
|
|
Currently RenderDoc expects Feature Level 11.0 hardware and above for D3D11. Lower levels
|
|
will capture successfully, but on replay RenderDoc will fall back to WARP software emulation
|
|
which will run quite slowly.
|
|
</para>
|
|
<para>
|
|
For OpenGL RenderDoc will only capture core profile applications, in general, and expects
|
|
to be able to create a core 4.3 context which includes EXT_direct_state_access. For more
|
|
details see the <link xlink:href="11ea4311-b9ea-450a-8c80-b510ffc8b1a6">OpenGL</link> page.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ10">
|
|
<title>Why does my capture say "Failed to capture frame: Uncapped command list"?</title>
|
|
<content>
|
|
<para>
|
|
At the moment RenderDoc only begins capturing deferred command lists at the point that you
|
|
trigger a capture. If you replay command lists from before this, RenderDoc will fail to capture
|
|
the frame and try again next frame (and eventually give up after a few retries).
|
|
</para>
|
|
<para>
|
|
To change this behaviour, enable the <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">Capture
|
|
all cmd lists</link> option - see that page for more details. This will capture all command lists
|
|
from the start of the program, ready for when you decide to capture a frame. This currently has a
|
|
fair overhead but it's something I want to improve in future
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ11">
|
|
<title>Why does my capture say "Failed to capture frame: Uncapped Map()/Unmap()"?</title>
|
|
<content>
|
|
<para>
|
|
If you start a Map() before a Present() call then call Unmap() after the Present() during the frame
|
|
RenderDoc wants to capture, RenderDoc won't have intercepted this call and so will fail to capture
|
|
this frame and try again next time. This usually only invalidates the first frame you try to capture,
|
|
but if you Map() many resources, and Unmap() them one by one in subsequent frames, you could hit this
|
|
failed capture scenario many times in a row.
|
|
</para>
|
|
<para>
|
|
Currently the only solution to this is to change the pattern of Map()/Unmap() such that they are
|
|
contained within a frame.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ12">
|
|
<title>Gamma display of linear data, or "Why doesn't my texture look right?"</title>
|
|
<content>
|
|
<para>
|
|
Gamma/SRGB correctness is a rather painful subject. If we could all just agree to store everything
|
|
in 32bit float data we could probably do away with it. Until that time we have to worry about
|
|
displaying textures while making sure to respect SRGB.
|
|
</para>
|
|
<para>
|
|
For texture formats that explicitly specify that they contain SRGB data this isn't a problem and
|
|
everything works smoothly. Note that RenderDoc shows picked texel values in linear float format,
|
|
so if you pick a pixel that is 0.5, 0.5, 0.5, the actual bytes might be stored as say 186, 186, 186.
|
|
</para>
|
|
<para>
|
|
For other textures it's more difficult - for starters they may actually contain SRGB data but the
|
|
correction is handled by shaders so there's no markup. Or indeed the app may not be gamma-correct so the
|
|
data is SRGB but uncorrected. If we display these textures in a technically correct way, such that the
|
|
data is not over or under gamma-corrected, the result often looks 'wrong' or unintuitively different
|
|
from expected.
|
|
</para>
|
|
<para>
|
|
Nothing is actually wrong here except perhaps that when visualising linear data it is often more convenient
|
|
to "overcorrect" such that the data is <em>perceptually</em> linear. A good example to use is a normal map:
|
|
The classic deep blue of (127,127,255) flat normals is technically incorrect as everyone is used to
|
|
visualising these textures in programs that display the data as if it were SRGB (which is the convention for
|
|
normal images that do not represent vectors).
|
|
</para>
|
|
<para>
|
|
You can override this behaviour on any texture that isn't listed as explicitly SRGB with the gamma (γ)
|
|
button - toggle this off and the overcorrection will be disabled.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ12">
|
|
<title>RenderDoc makes my bug go away! Or causes new artifacts that weren't there</title>
|
|
<content>
|
|
<para>
|
|
For various tedious reasons RenderDoc's replay isn't (and in most cases <em>can't be</em>) a
|
|
perfect reproduction of what your code was executing in the application when captured, and it
|
|
can change the circumstances while running.
|
|
</para>
|
|
<para>
|
|
During capture the main impact of having RenderDoc enabled is that timings will change, and
|
|
more memory (sometimes much more) will be allocated. There are also slight differences to the
|
|
interception of Map() calls as they go through an intermediate buffer to be captured. Generally
|
|
the only problem this can expose is that when capturing a frame, if something is timing dependent
|
|
RenderDoc causes one or two <em>very</em> slow frames, and can cause the bug to disappear.
|
|
</para>
|
|
<para>
|
|
The two primary causes of differences between the captured program and the replayed log (for
|
|
better or for worse) are:
|
|
</para>
|
|
|
|
<list class="ordered">
|
|
<listItem>
|
|
<para>
|
|
Map()s that use DISCARD are filled with a marker value, so any values that aren't written
|
|
to the buffer will be different - in application you can get lucky and they can be previous
|
|
values that were uploaded, but in replay they will be 0xCCCCCCCC.
|
|
</para>
|
|
</listItem>
|
|
<listItem>
|
|
<para>
|
|
RenderDoc as an optimisation will not save or restore the contents of render targets at the
|
|
start of the frame if it believes they will be entirely overwritten in the frame. This
|
|
detection is typically accurate but means targets are cleared to black or full depth rather
|
|
than accumulating, even if that accumulation is not intentional it may be the cause of the bug.
|
|
</para>
|
|
<para>
|
|
This behaviour can be overridden by enabling 'Save all initials' in the
|
|
<link xlink:href="0dd6fe0d-4130-46f4-b2ea-9565de13111d">capture options</link>.
|
|
</para>
|
|
</listItem>
|
|
</list>
|
|
|
|
</content>
|
|
</section>
|
|
<section address="FAQ13">
|
|
<title>I can't launch my program for capture directly. Can I capture it anyway?</title>
|
|
<content>
|
|
<para>
|
|
There is an option for capturing programs using RenderDoc where you can't easily set
|
|
up a direct launch of the process.
|
|
</para>
|
|
<para>
|
|
More details can be found in the
|
|
<link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">capture options</link> page which
|
|
details how to use it, however you should take care to read the warnings! This option
|
|
isn't without its risks, so you need to be sure you know what you're doing before
|
|
using it. It should always be used as a last resort when there is no other option.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ14">
|
|
<title>I'd like to use RenderDoc's texture viewer for dds files, or other images. Can I?</title>
|
|
<content>
|
|
<para>
|
|
Yes you can!
|
|
</para>
|
|
<para>
|
|
Simply drag in an image file, or open it via file → open. RenderDoc will open the image
|
|
if it is supported, and display it as if there were a log open with only one texture.
|
|
</para>
|
|
<para>
|
|
RenderDoc supports these formats: .dds, .hdr, .exr, .bmp, .jpg, .png, .tga, .gif, .psd. For
|
|
dds files RenderDoc supports all DXGI formats, compressed formats, arrays and mips -
|
|
all of which will display as expected.
|
|
</para>
|
|
<para>
|
|
Any modifications to the image while open in RenderDoc will be refreshed in the viewer.
|
|
However if the image metadata changes (dimension, format, etc) then this will likely cause
|
|
artifacts.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ15">
|
|
<title>I think I might be overwriting Map() boundaries, can I check this?</title>
|
|
<content>
|
|
<para>
|
|
Yes RenderDoc can be configured to insert a boundary marker at the end of the memory returned
|
|
from a Map() call. If this marker gets overwritten during a captured frame then a message box
|
|
will pop up alerting you, and clicking Yes will break into the program in the debugger so that
|
|
you can investigate the callstack.
|
|
</para>
|
|
<para>
|
|
To enable this behaviour, select the 'Verify Map() Writes' option when <link xlink:href="D1612D25-C8BA-4349-9CE2-1E57D60F98C5">capturing</link>.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ16">
|
|
<title>RenderDoc is complaining about my OpenGL app in the overlay - what gives?</title>
|
|
<content>
|
|
<para>
|
|
The first thing to remember is that <legacyBold>RenderDoc only supports Core 3.2 and above OpenGL</legacyBold>.
|
|
If your app is using features from before 3.2 it almost certainly won't work as most functionality
|
|
is not supported. A couple of things like not creating a VAO (which are required in core profile) and
|
|
luminance textures (which don't exist in core profile) are allowed, but none of the fixed function
|
|
pipeline will work, etc etc.
|
|
</para>
|
|
<para>
|
|
If your app is not using the CreateContextAttribs API then RenderDoc will completely refuse to capture,
|
|
and will display overlay text to this effect using the simplest fixed-function pipeline code, so it will
|
|
run on any OpenGL app, even on a 1.4 context or similar.
|
|
</para>
|
|
<para>
|
|
If your app did use the CreateContextAttribs API, RenderDoc will allow you to capture, but compatibility
|
|
profiles will have a warning displayed in the overlay - this is because you could easily use old functionality
|
|
as it is all still available in the context.
|
|
</para>
|
|
</content>
|
|
</section>
|
|
<section address="FAQ17">
|
|
<title>Can I tell via the graphics APIs if RenderDoc is present at runtime?</title>
|
|
<content>
|
|
<para>
|
|
Yes indeed. Some APIs offer ways to do this already - D3DPERF_GetStatus(),
|
|
ID3DUserDefinedAnnotation::GetStatus() and ID3D11DeviceContext2::IsAnnotationEnabled().
|
|
</para>
|
|
<para>
|
|
In addition to those:
|
|
</para>
|
|
<para>
|
|
Querying an ID3D11Device for UUID {A7AA6116-9C8D-4BBA-9083-B4D816B71B78}
|
|
will return an IUnknown* and S_OK when RenderDoc is present.
|
|
</para>
|
|
<para>
|
|
<externalLink>
|
|
<linkText>GL_EXT_debug_tool</linkText>
|
|
<linkAlternateText>GL_EXT_debug_tool</linkAlternateText>
|
|
<linkUri>https://renderdoc.org/debug_tool.txt</linkUri>
|
|
<linkTarget>_blank</linkTarget>
|
|
</externalLink>
|
|
is implemented on RenderDoc, which is an extension I've proposed for this purpose
|
|
(identifying when and which tool is injected in your program). It allows you to query
|
|
for the presence name and type of a debug tool that's currently hooked. At the
|
|
time of writing only RenderDoc implements this as I've only just proposed the
|
|
extension publicly, but in future you can use the queries described in that spec.
|
|
<alert class="note">
|
|
<para>It's unlikely the extension will ever be 'made official', so these enumerants can be used:</para>
|
|
<code language="cpp">
|
|
#define GL_DEBUG_TOOL_EXT 0x6789
|
|
#define GL_DEBUG_TOOL_NAME_EXT 0x678A
|
|
#define GL_DEBUG_TOOL_PURPOSE_EXT 0x678B</code>
|
|
</alert>
|
|
|
|
</para>
|
|
</content>
|
|
</section>
|
|
</developerConceptualDocument>
|
|
</topic>
|