<Prev | Content | Next>

07. GPU Frame Capture: pt.4 Debugging

GPU code is often complex, and to debug it you usually either run it on the CPU (a good idea for testing) or use tricks to output values to the screen or into output textures. Use GPU debugging when outputs look wrong but your CPU-side setup seems fine, or when a single thread/fragment shows unexpected values. Fortunately, Xcode provides tools that let you debug GPU code almost like normal code.

Before you start debugging, you first need to capture GPU frames (see previous episodes) - debug is a part of the tool. Then select the draw/compute call you want to debug and tap the bug button next to the capture button.

NOTE:

  • You can only debug functions that were compiled with debug info, otherwise values may be optimized out.
  • Also you don't have access to system calls like MPS (but can see them) or SwiftUI (they are invisible).

Compute Kernels

Let's start with compute kernels. To start debugging, select a GPU call you want to inspect and tap the bug button.

For compute encoders, Xcode shows a popup where you can select a thread position (thread index) you want to debug and, optionally, which functions to debug.

  • On the left you can see the queue of your operations, including the hierarchy of calls and loop iterations.
  • In the middle is your code (and loop markers).
  • On the right are the values of variables.

You can expand structures/values in the right panel to see all fields. The image previews show values for the same variable on the same line of code, but across different thread/vertex/fragment (depending on which function you debug).

NOTE: To exit debugging, tap the bug button again.

Vertex Shaders

To start debugging a vertex function, either tap the bug button (1) to get a popup that lets you choose vertex or fragment, or select a vertex and tap the Debug button (2).

You can change your code (in any debugged function, but I show the example here) and tap the round arrow button. Results will be re-evaluated and shown immediately. In the image below you can see that the image was flipped:

Fragment Shaders

To start debugging a fragment function, select a fragment in the attachment window and tap the bug button.

Values here have an image preview that represents this value in surrounding fragments. You can navigate between them by tapping the one you are interested in.

Conclusion

Xcode provides integrated tools for debugging GPU functions:

  • easily select where to debug your function,
  • see values in neighboring threads/pixels/vertices,
  • change code on the fly and see results immediately.

<Prev | Content | Next>