mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-04 17:10:47 +00:00
baldurk
294 lines
14 KiB
XML
294 lines
14 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 only supports D3D11 (including the D3D11.1 extensions where available).
|
|
</para>
|
|
<para>
|
|
In future API support is planned for at least OpenGL and D3D9 as soon as time and scheduling
|
|
allows - OpenGL support is under development. Support for Mantle is currently under development
|
|
also.
|
|
</para>
|
|
<para>Other APIs could be supported as I've tried to structure
|
|
things such that different back-ends can be slotted in without significant code changes.
|
|
</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 only supports Feature Level 11.0 and above for D3D11. Lower levels
|
|
may capture successfully but if uou can't create a FL11.0 device they will not replay.
|
|
</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>
|
|
</developerConceptualDocument>
|
|
</topic>
|