Search Unity

Have you ever looked at some graphics issue in Unity, and thought “if only I could see how the final frame is rendered, step-by-step?”. I know I do want that, all the time.

You can achieve that with some external tools, especially if you’re on Windows. Build a standalone player, run it through Visual Studio graphics debugger, Intel GPA, RenderDoc, NVIDIA NSight or AMD GPU PerfStudio, then capture a frame of rendering, and step through the draw calls and other rendering events to see what’s going on.

The above is a very powerful approach, since these tools can provide you with a lot of information to really drill down. It’s also very involved; you need to build a player and launch external tool.

During one hack week we thought: “hey, can we build something really simple, but really quick to use in Unity?”… So we did.

Enter Frame Debugger

You select Frame Debugger from the Window menu and you see a list of draw calls made during that frame. Step through them and see what was rendered up to that point. Inspect shadow maps, temporary render textures, deferred g-buffer and whatnot.

Looking into deferred shading g-buffer here, as it is being rendered


The UI for the frame debugger is pretty simple. There’s a tree of draw calls and other interesting events on the right and details about selected event on the left. Most draw calls display a mesh preview and highlight object being drawn in the hierarchy.

Here we are stepping through the draw calls of depth texture creation, in glorious animated GIF form:


And later on in the frame, a light is rendering it’s shadow map:


Even later on, image post-processing effects start. You can see the bloom & flares effect downscaling the image, blurring it and adding it back, followed by a brief flash of a tonemapper:


Render target display options

For some effects, it is convenient to see individual channels of a render target. Here’s a screenspace buffer produced by Unity’s directional light shadows:


And here’s only the red channel displayed:


The range of colors displayed can be tweaked via a Levels slider in the toolbar. This is particularly useful for HDR rendering:



When rendering into multiple render targets at once you can select which one to display in the game view. Shown here are the diffuse, specular, normals and emission/lighting buffers in 5.0 deferred shading mode, respectively:

FrameDebugMRTDiffuse FrameDebugMRTSpec Looking into deferred shading g-buffer here, as it is being rendered FrameDebugMRTLight

Implementation notes

The current implementation of the Frame Debugger could be seen as a cute hack (we weren’t quite sure ourselves whether it would work at all). There’s no actual “frame capture” going on; pretty much all we do is stop rendering after some number of draw calls. So if you’re looking at a frame that would have 100 objects rendered and you’re looking at object #10 right now, then we just skip rendering the remaining 90. If at that point in time we happen to be rendering into a render texture, then we display it on the screen.

This means the implementation is simple; getting functionality working was only a few days of work (and then a few weeks iterating on the UI). The downsides of this approach is that it only works in the Editor. If actual rendering changes while you’re debugging the frame (e.g. you disable some objects, or resize game view), then you’ll suddenly start looking at a different list of draw calls. However, even with these limitations we think it can be a very useful tool for tracking down graphics issues in your games.

Happy frame debugging!



Subscribe to comments

Comments are closed.

  1. THOUGHTSSQUARED: PIX, Visual Studio graphics diagnostics, PerfStudio, NSight, GPA, also gDEBugger all have this.

    You can learn a lot about Unity by cruising the frame.

  2. thoughtssquared

    July 31, 2014 at 3:49 am

    This is very cool! A few weeks ago I was thinking how it’d be nice to view my scene’s normal information just to get a different view. I could’ve written a script but this works much nicer!

    Not super necessary – but is there a way to output a screenshot of the framebuffer at different moments in the scene? Hypothetically could you make a pseudo-timelapse gif of it which would be fun. If anything, it’d be nice to be able to push out a screenshot of the final game scene and this seems like it could be a good place for it.

  3. Aras Pranckevičius

    July 30, 2014 at 8:21 pm

    @santokes: the object that contributed to the draw call is highlighted. Say you have a cube, and it contributes 5 draw calls in total (two for shadow maps, one in deferred prepass, one in deferred final pass, one extra time in some effect). In all these cases, since it was that particular cube that was rendered, it will be highlighted in hierarchy (“look it’s this cube rendering right now”).

    In terrain’s case, what is rendered is “terrain”, but you can scrub through the draw calls and see how it is being rendered step by step.

  4. Cool cool Aras

    >> for each draw call it highlights object that is rendered in the hierarchy view.

    What happens with draw calls for internal Unity things? For example Unity doesn’t give any control over the shadow pass. So if the user clicks a draw event in the shadow pass…. what get highlighted in the editor?

    Another example: Unity terrain, my bête noire. This is represented as one object in the editor but it renders in hundreds of pieces, each with 575-627 indexes. Does the whole terrain get highlighted if you click one event?

  5. I feel like that would make it release later.

  6. @Aras Pranckevičius
    What about throwing in some hookers and vodka?

  7. Aras Pranckevičius

    July 30, 2014 at 11:41 am

    @kyr: GUI team is working as fast as they can. And no, throwing in more programmers on it won’t make it release sooner.

  8. Would you stop feeding us stories about how great 5.0 is and release 4.6 already? Hundreds of projects are delayed because people wait for new GUI system.

  9. Aras Pranckevičius

    July 30, 2014 at 6:38 am

    @rainsing: as a single draw call, explicitly labeled as “draw static batch” or “draw dynamic batch”. So this can be useful to see what exactly gets batched, and what is not.

  10. Will batched objects be listed as a single draw call or as individual ones?

  11. Aras Pranckevičius

    July 30, 2014 at 5:50 am

    @santokes: Right now this does not have timing information (hence “debugger”, not “profiler”).

    And yes, you can achieve the same (and much more) with VS/GPA/NSight/RenderDoc/etc. Advantages of frame debugger: it’s really just a couple clicks away, for when you want to investigate something really fast.

    It can also show more information, e.g. for each draw call it highlights object that is rendered in the hierarchy view.

  12. Then you speak for me too, Brandon: I shipped a Unity iOS game last year.

    Actually… you convinced me–let’s see those draw calls

    That said, if you’re developing for iOS, you really want to be deploying all the time to get real performance metrics–that part shouldn’t stop. The emulator is not the device, so you aren’t getting real measurements.

  13. Brandon Catcho

    July 30, 2014 at 2:40 am

    @santokes I know that the VS Graphics Debugger is very powerful but have never used it myself. However I will speak for all those developing for OSX and iOS and say that it will be nice to debug draw calls (however limited) and rendering issues without having to build/deploy-to-device/tweak/repeat.

  14. thank you for this ‘another’ amazing feature, looking forward toUnity 5.

  15. Will event times be reported?

  16. What are some advantages over the Visual Studio Graphics Debugger?

  17. I’m currently using Visual Studios’ integrated graphics debugger so I can traverse the pipeline to get feedback on specific SM levels, draw calls and other things.

    These features will be helpful, but I still think one will need to be able to do this with the physically tested devices…

  18. Brandon Catcho

    July 29, 2014 at 8:06 pm

    Good to know. I look forward to it!

  19. Aras Pranckevičius

    July 29, 2014 at 7:25 pm

    @Haim: right now it’s Pro-only, just like Profiler. Whether it will stay that way… we’ll see.

    @Brandon: it does display all the draw calls that the Game View is displaying. So not, it’s not a perfect emulation of a on-device rendering. But if you want to investigate anything that you can see in the game view, then frame debugger should be useful.

  20. Brandon Catcho

    July 29, 2014 at 7:22 pm

    This was unexpected and awesome. Does the current target platform emulation change the draw calls?

  21. ImaginaryHuman

    July 29, 2014 at 5:22 pm

    This looks like a really useful tool, no more guesswork and temporary outputs trying to figure out what’s going on

  22. will be available in unity 5 free as well? or this is pro only feature?

  23. Very cool! Unity 5 looks to be worth the upgrade with all these great new features.

  24. The tool looks very cool! Was dreaming about something like this for a long time already. We usually used Visual Studio graphics debugger, but being able to do all things in one sfot – Unity is pricelss. Hate having many tools working all at once, plus they slow the pc work. HOpe the tool is just as great as it looks

  25. Amazing Tool :)

    Please add display of all 4 channels side by side and 4 RenderTargets side by side and all of this in one picture 4 RT and inside each 4 channel textures -> 16 textures side by side.

    Additionally save some sort of drawcall id (mesh id, state, parent call tree that you display, maybe something else) and allow to select particular DrawCall, hit play and see how it looks like.

    Also add multiselect of drawcalls to see result only from those DrawCalls. :)

  26. it looks as if i will love it, great!

  27. That is really cool tool. Nice work!