mirror of
https://github.com/baldurk/renderdoc.git
synced 2026-05-05 01:20:42 +00:00
baldurk
9460fbd970
* This allows you to hook into processes that are difficult to launch directly with the existing functionality in RenderDoc. * This is rather risky, as it modifies the AppInit_DLLs registry key to inject a small shim dll that checks for the desired process and injects the full renderdoc.dll. If that registry key got left, or if there was some incompatibility with the shim dll, you could have problems. It should only ever be used as a last resort if there's no other way to capture.
310 lines
15 KiB
XML
310 lines
15 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>
|
|
<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>
|
|
</developerConceptualDocument>
|
|
</topic>
|