No announcement yet.

[New plugin] Shader debugging made easy with RenderDoc for UE4.

  • Filter
  • Time
  • Show
Clear All
new posts

  • [New plugin] Shader debugging made easy with RenderDoc for UE4.

    Hello everyone!

    I thought I'd share what I've been working on for the last couple of weeks.
    One thing I learned from my tag buffer adventure was that debugging certain parts of UE4 can really be a pain, and one notable area is the rendering pipeline and shaders.
    All tools I tried either I could not get to work (RenderDoc) or they just crashed (nSight & VS GPU debugging tools). As a pleasant surprise though, the main developer of
    RenderDoc, BaldurK ( BIG PROPS to this guy!!) contacted me, curious of why I couldn't get it to work. With his help, I managed to sort out what was wrong and made a wiki entry to explain how others could get it to work
    using the same techniques. I'm a big fan of renderdoc, especially since it went open source, and as it was kind of awkward setting it up with UE4, plus there were some things that didn't mesh
    that well with the editor, I decided to try to make it easy for everyone by making a set of plugins that integrates renderdoc with UE4 in a more user friendly manner.

    I say a set of plugins since it is actually two of them. The first one is simply a loader that injects the proper DLL as early as possible to be able to catch device creation etc.
    This would not have been needed if the same plugin could get callbacks for all different load stages, but this is currently, as far as I know, not supported.

    The plugin has a few features:
    * It detects your current installation of renderdoc, so you are not bound to the version I use, and can update at will as long as the API is compatible.
    If you don't have an installation, and have just downloaded a zip, built it yourself etc. It will prompt for a path. Or you could set the path yourself in your project game.ini under [RenderDoc] BinaryPath=PATHGOESHERE

    * It adds capture buttons to all viewports of the editor. This means you no longer have to cycle swap chains to get to the element you want. When you press the capture button (or its hotkey) it will capture the window the viewport
    is attached to, and then launch renderdoc with that capture as argument. It also opens a connection to renderdoc so you can perform subsequent captures etc.

    Click image for larger version

Name:	UIInfo1.png
Views:	1
Size:	307.4 KB
ID:	1138653

    Click image for larger version

Name:	UIInfo2.png
Views:	1
Size:	396.4 KB
ID:	1138655

    * I've added a small options menu button next to the capture button. This small window lets you set several properties that control how the plugin operates:

    The settings are:
    # Capture callstacks
    Save the call stack for every draw event in addition to the event itself. This is useful when you need additional information to solve your particular problem.

    # Capture all resources:
    Capture all resources, including those that are not referenced by the current frame.

    # Save all initial states
    Save the initial status of all resources, even if we think that they will be overwritten in this frame.

    In addition, when UE4 compiles it's shaders, it strips them of all of their symbols and other meta-data, presumably to make them more compact.
    This makes them very hard to debug though as you can no longer see the variable names, attributes etc.
    I'm working on a pull request that adds support to optionally not strip the data by sending a flag to the compiler. I don't want to make this the default behavior though as that might break some peoples project (deploy) that is why it will default to off, but I highly recommend using this when debugging.

    I am not currently done with this feature, but you can follow my progress on the AutoCompileShaders branch of the repository.

    After a capture is complete, the plugin simply launches the RenderDoc UI. After this point, it is just like any other RenderDoc debugging session. If you are new to RenderDoc, I would suggest checking out these video tutorials:

    To install the plugin, simply clone this git-repo to your project/plugins/ folder:

    You can also add the plugin as an engine plugin by adding it to your engine plugin folder, although I recommend using the project plugin route as I feel it is cleaner.

    The plugin also requires recent code from RenderDoc's github ( which isn't in the latest stable release.
    You can find a beta release here: or build it yourself from source if you prefer.
    Attached Files
    Last edited by Temaran; 09-18-2014, 08:12 PM. Reason: syntax
    Some of my projects related to UE4: (Forked from Tobii. It was moved there from my github though )

  • #2
    I completed the feature that prevents shader meta-data stripping.
    I put it on a branch in the main repo:

    I made a pull request for it here:

    But until then if you'd like to try it you can get the fork/branch here:

    I hope someone other than me finds this useful

    Best regards,
    Some of my projects related to UE4: (Forked from Tobii. It was moved there from my github though )


    • #3
      Excellent work, Temaran!

      Having a graphics debugger such as RenderDoc semi-attached to the UE4 Editor is a life-saver for anyone trying to hack/mod the core of the rendering subsystem.

      I would just like to add that RenderDoc 0.21 beta (or any of the more recent nightly builds) are necessary for the plugin to work properly.
      The current stable version (v0.20) won't work since it exports a different API (e.g., there is no 'RENDERDOC_GetAPIVersion').

      Once again, kudos to you!
      Fantastic job.


      • #4
        Actually, forget my previous remark; I just read it through your initial post more carefully and noticed that you already pointed the necessity for the beta/versioned build. =)


        • #5
          Thats insanely helpful! Thanks a lot man
          Check out UNREAL 4 Lighting Academy


          • #6
            Awesome to hear that other people think it's useful too

            Some of my projects related to UE4:

   (Forked from Tobii. It was moved there from my github though )


            • #7
              Hey man,

              we just integrated your Plugin into our Build and it works like a charm. However, we found a bug caused by the Plugin.
              When you start and uncoocked game, the plugin crashes the Slate UI, so you cant start a game anymore.

              We fixed it which looks like this:
              Click image for larger version

Name:	RenderDoc_Plugin.JPG
Views:	1
Size:	214.1 KB
ID:	1060674

              I also have a .diff file for you with the changes. Would be cool if you can update your Plugin on GitHub
              Attached Files
              Last edited by Daedalus51; 11-06-2014, 09:25 AM.
              Check out UNREAL 4 Lighting Academy


              • #8
                This looks brilliant! Good idea.


                • #9
                  Hello everyone!

                  I noticed that 4.6 is out, so I updated the code to work with the new version
                  The changes are in the r/UE4.6_v0.1.

                  Special thanks to Daedalus51 for noticing the bug! I've included those changes into the new branch as well.

                  Best regards,
                  Some of my projects related to UE4:

         (Forked from Tobii. It was moved there from my github though )


                  • #10
                    Hi Temaran,

                    Did you made renderdoc works with usf shader?
                    How did you made renderdoc display wireframe mesh just like explained on RenderDoc video tutorial?

                    I couldn't seem to make renderdoc works like the video, it only displays the final texture without information of the vertices, only attributes, not position and normals, is this expected?

                    I'm using UE 4.5 with renderdoc plugin from r/0.1 and renderdoc 0.21

                    Click image for larger version

Name:	Capture.PNG
Views:	1
Size:	453.6 KB
ID:	1061851

                    Click image for larger version

Name:	Shader.PNG
Views:	1
Size:	56.4 KB
ID:	1061852

                    Thanks for the plugin anyway!
                    Attached Files


                    • #11
                      Click image for larger version

Name:	QQ截图20160906142836.png
Views:	1
Size:	345.4 KB
ID:	1114646

                      My trouble is that there are assemble codes but .usf code or hlsl code.Are there someone know how to get debug info form ue4.sln and tools?