baldurk/renderdoc

RenderDoc is a stand-alone graphics debugging tool.

RenderDoc is a frame-capture based graphics debugger, currently available for Vulkan, D3D11, D3D12, OpenGL, and OpenGL ES development on Windows, Linux, Android, and Nintendo Switch™. It is completely open-source under the MIT license.

RenderDoc is intended for debugging your own programs only. Any discussion of capturing programs that you did not create will not be allowed in any official public RenderDoc setting, including the issue tracker, discord, or via email. For example this includes capturing commercial games that you did not create, or capturing Google Maps or Google Earth. Note: Capturing projects you created that use a third party engine like Unreal or Unity, or open source and free projects is completely fine and supported.

If you have any questions, suggestions or problems or you can create an issue here on github, email me directly or come into IRC or Discord to discuss it.

To install on windows run the appropriate installer for your OS (64-bit | 32-bit) or download the portable zip from the builds page. The 64-bit windows build fully supports capturing from 32-bit programs. On linux only 64-bit x86 is supported - there is a precompiled binary tarball available, or your distribution may package it. If not you can build from source.

• Downloads: Stable and nightly builds: https://renderdoc.org/builds ( Symbol server )
• Documentation: HTML online, CHM in builds, Videos
• Contact: [email protected], #renderdoc on OFTC IRC, Discord server
• Code of Conduct: Contributor Covenant
• Information for contributors: All contribution information, Compilation instructions
• Community extensions: Extensions repository

Screenshots

API Support

	Windows	Linux	Android
Vulkan	✔️	✔️	✔️
OpenGL ES 2.0 - 3.2	✔️	✔️	✔️
OpenGL 3.2 - 4.6 Core	✔️	✔️	N/A
D3D11 & D3D12	✔️	N/A	N/A
OpenGL 1.0 - 2.0 Compat	✖️	✖️	N/A
D3D9 & 10	✖️	N/A	N/A
Metal	N/A	N/A	N/A

• Nintendo Switch™ support is distributed separately for authorized developers as part of the NintendoSDK. For more information, consult the Nintendo Developer Portal.

Downloads

There are binary releases available, built from the release targets. If you just want to use the program and you ended up here, this is what you want :).

It's recommended that if you're new you start with the stable builds. Nightly builds are available every day from the v1.x branch here if you need it, but correspondingly may be less stable.

Documentation

The text documentation is available online for the latest stable version, as well as in renderdoc.chm in any build. It's built from restructured text with sphinx.

As mentioned above there are some youtube videos showing the use of some basic features and an introduction/overview.

There is also a great presentation by @Icetigris which goes into some details of how RenderDoc can be used in real world situations: slides are up here.

License

RenderDoc is released under the MIT license, see LICENSE.md for full text as well as 3rd party library acknowledgements.

Compiling

Building RenderDoc is fairly straight forward on most platforms. See Compiling.md for more details.

Contributing & Development

I've added some notes on how to contribute, as well as where to get started looking through the code in Developing-Change.md. All contribution information is available under CONTRIBUTING.md.

renderdoc's Issues

Undocumented magic extra DWORD in some cases on OPCODE_LD

Typically dxbc opcodes have a length and then a defined set of extra DWORDs and operands that fill this length. In dxbc_disassemble.cpp line 1830 I check that the consumed DWORDS match the defined length.

I encountered one bug where OPCODE_SAMPLE_POS has one extra DWORD that's not documented, but in the below sample shader the first OPCODE_LD has another magic DWORD. I presume it's because it then matches the 24 other unrolled loads that have offsets defined, but that's just a guess as there is no documentation that suggests it should be there.

So I'll have to remove the length check for RELEASE, demote it to a warning, and in release just use the length as defined by the opcode and hope that I'm not incorrectly disassembling any opcode.

Texture2D<float> Tex;

float4 main(float4 pos : SV_Position) : SV_Target0
{
    float total = 0;

    [unroll]
    for ( int dy=0; dy<5; ++dy )
    {
        [unroll]
        for ( int dx=0; dx<5; ++dx )
        {
            total += Tex.Load( int3( pos.xy, 0 ), int2( dx, dy ) );
        }
    }

    return total.xxxx;
}

Geometry shaders with multiple output streams not supported in mesh view

With or without streamout, geometry shaders that have multiple output streams will fail to fetch the mesh data for the mesh view and will just show up empty (although VS out data should be present).

Issues debugging shaders

Hi,

There are a couple of issues I encountered while having a first look at RenderDoc:

• Integer shader inputs seem to be only displayable as float (in the "Constants & Resources" window)
• Switch statements do not seem to work correctly when debugging shaders. It seems the first case is always taken, regardless of the switch value.

See attached image for examples of both issues - the v2.x here is (int) 3, so should take the 'default' path, but is instead taking the '0'th case.

Support row_major and matrices in raw buffer format specifier

buffer format specifier should support more hlsl-like syntax for more complex structures.

When auto-generating markers, group dispatches into 'Compute Pass'

When auto-generating markers for logfiles without any marker regions, don't mix compute dispatches + draws, and group multiple dispatches into a single 'Compute Pass'.

Crash with bad handling of edge case in log loading

Hard to describe the exact situation where this happens, but basically while initially scanning the log a window on the file is used - if the frame capture itself lies right on the border of a window things would go very badly wrong after loading and will almost certainly lead to a crash.

Fixed in v0.20

If you see messages like this in the diagnostic log, that's it:

serialiser.cpp( 304) - Error - Assertion failed: 'm_ReadFileHandle'
d3d11_device.cpp(2073) - Error - Assertion failed: 'header == CAPTURE_SCOPE'
serialiser.cpp( 731) - Error - Unexpected control byte: 1x
d3d11_context.cpp( 969) - Error - Assertion failed: 'header == CONTEXT_CAPTURE_HEADER'

resinfo instruction (GetDimensions on textures) diverges from the spec in several ways

This asm opcode was wrong in a bunch of ways:

• If only one dimension was used, it would be pulled from the first component of the swizzle instead of the correct mask. e.g. if it was resinfo r1.y, t0.zxwy then .z would be used instead of .x (matching the .y)
• UAVs weren't supported, the corresponding SRV slot would always be checked
• Likely crash if nothing was bound, instead of returning 0
• The base resource properties were used, not the view
• Although the spec says the value is undefined, it was returning 0 for cubemap array sizes. Technically valid, but it returns the number of cubes now.
• Out of bound mip levels were just clamped in dimensions rather than having 0 returned.
• the _rcpfloat specifier was applied to all components, not just width/height/depth as appropriate.

I went in looking for just one bug, and found all these! phew..

discard/clip operations should be more clear in the debugging

If you just hit "run" the final statement shown is at the end of the shader, but it would be better to show the discard statement itself.

In addition, the line highlight and icon should change to indicate that the shader has finished running, to make it clear what has happened.

Multiple blendstates with different but equivalent descriptors could cause crash

When creating blend states in D3D (as well as other states), passing in the same exact descriptor will return the same object back with an incremented refcount. RenderDoc handles this while capturing and aliases the objects and then only creates one when replaying.

However there's a flaw when states which vary only by blend parameters when blending is disabled (they are then essentially equivalent but return different objects). These states get saved as separate but with an identical descriptor and this causes problems on the replay side when objects that were considered unique now come back as aliased.

Fix will be in v0.20.

Better filenames for multiple frame captures

Currently subsequent frame captures after the first in a single execution of a program will get _ appended, so the 5th capture will be capturename_____.rdc.

This isn't such an issue if you manage the captures through the UI, but if you're moving the files around this could be better. e.g. appending the frame number.

Add the option to only time over perf events/markers

This should hopefully improve accuracy by ameliorating errors and also reduce load and likelihood of crashing from timing every drawcall.

Perhaps there should be a way in the UI to then drill down and time per-drawcall within a perf marker should you so wish?

Ideally I'd fix up the timing so it's accurate and reliable even per-drawcall though :).

SPDB line number mappings for instructions are bollocks

The SPDB chunk emitted by newer FXCs (post rolling into win8 sdk - 44 and above I think) is essentially just a PDB file.

Unfortunately, the line number mappings for the instructions are pretty worthless. They're accurate for lines within the entry point function, but any instructions in function calls from the entry point all get mapped to the single line where that function is called. This can lead to a 2000 instruction long shader with every instruction mapping to the same line (if the entry point only calls another function to do its work, which is quite plausible).

The DIA library is completely fooled and returns these incorrect line numbers, but fxc and visual studio graphics diagnostics at least do seem to map to the source correctly through function calls. Maybe this is by pulling extra undocumented data out of the SPDB chunk, or maybe they just cheat and recompile with fxc and poke with the internal data to get the true line mapping out.

Not sure how likely it will be to fix this, but it's a pretty serious issue and for a lot of shaders makes the in-line hlsl kind of worthless.

Crash releasing resource view (likely on shutdown)

It seems like there's a refcounting bug lurking somewhere that leads to a crash when releasing a resource view if it gets destroyed.

Crash in target process jumping into invalid memory

For reasons currently unknown, sometimes using CreateToolhelp32Snapshot to find the renderdoc dll in the target process can fail, leading to jumping into 0x0+RENDERDOC_SetLogFile instead of renderdoc.dll+RENDERDOC_SetLogFile.

I've put a change in that will be included in v0.19 that includes better logging, a speculative fix and slightly more graceful handling of this happening.

Expose option to verify Map() writes

It would be good as an option (not default for performance reasons) to verify all Map() writes that people do to ensure they don't accidentally overwrite the returned buffer, which could cause bugs by omission and depending on where the memory sits and how big the overwrite is, could cause a crash (with or without renderdoc).

This will likely be an opt-in capture option as it would introduce an extra copy on all Map()s and hit performance.

Clicking 'edit shader' in the pipeline state viewer on an unbound shader will crash

Crash in painting the timeline bar

Just creating a bug for tracking this corresponding to an auto crash report. There was a crash in the Paint method for the timeline bar - unclear what else can be said about it.

I've added some speculative fixes for cases that "shouldn't" happen. The code for it will probably also be rewritten soon.

Crash when saving initial contents of 3D texture, mips aren't accounted for

This will almost certainly cause a crash when the initial contents of any 3D texture are saved out to disk, as low mips are massively over-run on read because the top mip's dimensions are used.

Fixed in v0.19.

Loading layouts while a log is open will cause a crash

Show a separate marker for clears on timeline bar

Crash when deferred command list has marker as its first event

When loading a log that contains a deferred command list in which the first thing is a marker (as in SetMarker or BeginEvent) with no other API calls preceeding it, RenderDoc crashes on load trying to index into an empty array. This happens on either an empty marker label, or an event group that contains other events, drawcalls, dispatches.

Will be fixed in v0.20.

Experiment with running UI through mono for future linux/mac port

Running on linux or mac would probably be easiest to start with just capturing and replaying over the network and using the UI on windows, but we'd want a UI eventually.

I have a changelist that just needs some testing/optimising/tuning which removes the c++/cli interop dll (renderdocnet.dll) which isn't portable at all and switches to straight p/invoke from C#. This is the first step.

I've checked the UI with that change on the Mono migration app as that would be a good solution to get a UI running without having to make a second UI in Qt. The results seem promising, noting them here just so I remember and can keep track as I fix them.

ScintillaNET

P/Invoke into a few win32 libraries - LoadLibrary, GetProcAddress, a few region/DC/rect functions. Not sure how easy it will be to port this but Scintilla works on linux so it may be possible.

bool Control.get_CheckForIllegalCrossThreadCalls () which is [MonoTodo] stubbed
void PrintDialog.set_UseEXDialog (bool) which is [MonoTodo] not implemented but who will seriously try and print a shader. Honestly.

WinFormsUI

I've seen explicit code in here to check against mono so I presume there is at least some attempt at mono support.

It P/Invokes a few win32 functions for setting window parameters or positions and sending messages. Depending on what these do this could be dropped or reimplemented.

renderdocui (that's me!)

Actually looks like the easiest of the three, potentially.

A few exception functions are unimplemented but they're only for crash handling anyway.

DataGridView virtualmode isn't implemented which is troubling, but potentially it would be worthwhile investing the time in making a custom control for the few uses of DataGridView that I have (mostly the buffer viewers).

Some type check/conversion functions in the TreeListView code. Should be fixable I think.

ToolStripItem RightToLeft is set but honestly I think that's only for positioning so I can find an alternate solution I'm sure.

A few P/Invokes for mouse wheel handling, mutexes to signal the main dll that we're running in the replay app (but we can do that other ways). Also for watching for file system changes - that can also be either dropped or reimplemented.

When declaring stream-out geometry shaders, signatures can have NULL semantics

I think this is to do with assigning specific output slots, leaving 'holes' that leave NULL semantics in the output signature that aren't handled.

Windows and displays in UI paint black

I've had a report where the windows and displays in the UI paint black instead of showing the texture, rendertarget etc. When moving or resizing a single frame can come through before black is drawn.

It sounds like some painting problem - I don't clear to black in the .Net layer before drawing over the top with D3D but something is going wrong.

Unfortunately I don't have enough information to fix this or investigate further - if this is happening to you please get in touch!

Submitted Crash - Failed to create RTV & many duplicate wrapped resources

I'm submitting these two symptoms together as I can't tell from the auto-submission if they're related or unrelated.

Two separate crash reports with almost the same problem (probably the same log opened twice) exhibited two different issues.

• First, a render target failed to create with 0x80070057 (E_INVALIDARG). It's not clear why this was, it's also not clear if the RTV in question was the backbuffer (which does some different things).
  This is what ultimately caused the crash, later on trying to do ClearRenderTargetView crashed as the RTV pointer was NULL.
• Quite a number of wrappers are overridden with messages like:
  RENDERDOC: [14:19:40] resource_manager.h( 980) - Error - Overriding wrapper for 0x0000000020942AE8 - to 0x000000001CC17888
  This is caused when we create a unique wrapper object expecting to map to a unique D3D object, but the D3D object is a duplicate of one we've already seen.
  This was seen when there was a bug with blend states causing unique wrappers to be produced for equivalent descriptors but that should be fixed, so I'm not sure what case this is hitting - it might be related to the RTV that failed to create, it's not clear.

Implement ID3D11Device::OpenSharedResource

This function isn't implemented, neither is querying for IDXGIResource.

Error message for feature level 11 device failing to create is unfriendly

The error message is just a generic 'failed to load logfile' and doesn't indicate what the real problem is.

Initial contents of typeless multisampled textures are not saved

Typeless textures, and multisampled textures declared with a type in the base resource, are both saved out when the initial contents are saved.

A multisampled texture that is declared as typeless in its base resource (and then typed in views) will not have the initial contents saved.

renderdoc crashes with std::bad_alloc when calling CreatePixelShader

When I compile shaders with debug information, I get a crash in CreatePixelShader, when launching my engine through renderdoc.

The callstack(the renderdoc part of it)

renderdoc.dll!000007fed6d418cb()    Unknown
renderdoc.dll!000007fed6e0f544()    Unknown
renderdoc.dll!000007fed6e1acdf()    Unknown
renderdoc.dll!000007fed6de0180()    Unknown

heres the module load information:
renderdoc.dll C:\Program Files\Crytek\RenderDoc\renderdoc.dll N/A N/A Cannot find or open the PDB file. 126 0.18.0.0 2/25/2014 4:53 PM 000007FED6D20000-000007FED6FBE000

Let me know if you need more information. I dont Think I can share the shader byte code unfortunately.

Stencil test overlay doesn't respect read and write masks properly

ID3D11Device::Create* must valid last parameter

Currently we get a crash if the last parameter (output) is NULL as it gets deferenced without checking.

http://www.crydev.net/viewtopic.php?f=379&t=121165

Add a global option to be able to hide empty marker regions

This should apply to both the event browser and timeline view.

FRAPS and other d3d-injecting programs have compatibility problems

With FRAPS active it seems that x64 builds only will crash when trying to capture through RenderDoc.

It's not clear if this can be fixed as ultimately you have two programs trying to do the same thing, but I should investigate finding a workaround to at the very minimum try and detect this problem and alert the user.

QueryInterface and other functions to get-by-guid can leak unwrapped resources leading to a crash

Several cases in QueryInterface implementations aren't handled, like ID3D11Texture2D querying for an ID3D11Resource will not work problem. Make sure all possible UUIDs are handled correctly.

Experiment with generating better stubs for shader editing without debug info

When debug info isn't present and you edit a shader, the stub generated only accounts for input & output signature for linkage with the other shaders in the pipeline, as this is all that's guaranteed to be present.

Experiment with including resources and constant buffers from reflection data (if present), or failing that just the resources from the definitions in the disassembly itself. See if I get get good results.

Crash if opening a new texture viewer window while log is open

Stupid little bug but it caused a crash if you open a texture viewer window - either from the menu or from something that will want to display a texture, like clicking a texture slot in the pipeline state view.

Will be fixed in v0.20.

Crash when using #line directive, or with symbols on the last line of a file

RenderDoc's disassembler doesn't correctly handle the #line directive, and if you end up with line numbers beyond the number of lines in the file (quite easy) it will crash indexing off the end of the file.

Otherwise, the line numbers are still wrong!

capture & replay glxgears over the network

The opengl backend is still really limited and although it can capture and replay whatever APIs I have implemented (not many so far), it can't actually analyse or show state/buffer contents or anything more than just blit a texture onto the window.

However, it'd be a nice proof of concept to capture glxgears from linux over the network and either replay locally by mapping glx calls to wgl calls or replay back on linux.

Crash when changing between mesh preview tabs with no capture loaded

Reported via the anonymous crash submission tool. When you don't have a capture loaded in the UI, changing between the mesh preview tabs crashes the application.

Do better to fetch shader source around #line directives

When using #line to specify a different filename rather than just a different line number there are things I can do better to fetch that source:

• If the filename is an absolute path try and fetch the file off disk. This is a bit fragile as it means the source is no longer self-contained in the capture and portable to any machine, but seems a reasonable default.
• Failing that, I should parse the files that I do have and preprocess them as far as analysing #line directives, to try and do the same as the compiler did and figure out which bits of code correspond to which 'virtual' lines.

Examine DXGI_FORMAT_R10G10B10A2_UINT support for buffers

loading, format checking, casting (e.g. try to DXGI_FORMAT_R32G32B32A32_UINT) and specifying 10:10:10:2 in the buffer format specifier.

In unknown cases, initial contents of buffers can be missing

Not much information available on this yet, I'll edit the bug to be more descriptive as I investigate, but just for tracking & awareness there seems to be a rare case where the initial contents of a buffer from previous frames can be undefined/invalid in the capture frame.

Request: Ability to capture specified frame

Hi,

One ability that would be really useful for me is to capture a specific frame within an app, rather than relying on a hitting F12. This is useful when debugging things like fixed frame timeloops.

Refcounts don't match what the app might expect

RenderDoc internally keeps references on resources where necessary (views will take references on textures, binding an object to the pipeline a reference will be held to it).

This means the refcounts don't match up to what the game or application might expect. This is valid but means that code which asserts on the refcount being 1 before resizing a swapchain or something will break, so I should probably change the behaviour to lie about the refcount to the user code.

UI is not high-DPI aware

As description :).

http://www.crydev.net/viewtopic.php?f=379&t=121165

Add an option to store temporary captures in a different place

Currently all temporary captures are saved to wherever %TEMP% is. It would be nice to have this be configurable and place the captures in a user-specified location.

Pure virtual function call on resources

I don't have much information about this, it came in as a crash report so I don't have a fix yet.

It seems like possibly a bound render target is being released somehow while a pointer remains to it, so when unsetting it from the pipeline in the OMSetRenderTargets call a pure virtual function call is made.

If you see this bug please get in touch :).

RenderDoc should return a stub ID3D11InfoQueue when requested

Rather than returning E_NOINTERFACE, return a wrapped interface that does nothing - to allow apps to continue on without code modification if they assume an infoqueue will be returned.

Timeline bar should have an option to scale markers + draws by GPU time

When GPU times are available for events, the timeline bar should have an option to scale the markers and sections by their duration rather than the best-fit-on-screen scaling as is currently available.

Also adding tooltips to the timeline bar with event name and GPU time would help visualisation.

View constant buffer using its actual layout

Hi,
This is an enhancement request. It would be nice to view the content of a constant buffer with the layout/declaration extracted from reflection data (when available) instead of a generic layout.
Btw, great work, looking forward for the release of the sourcecode!