Skip to content

GPU debugging

How to read validation messages and capture a frame of the Vulkan renderer.

Turning it on

Names and labels need VK_EXT_debug_utils, which the renderer enables with vulkan.debugging:

settings.set("vulkan.layers", std::vector<std::string>{"VK_LAYER_KHRONOS_validation"});
settings.set("vulkan.debugging", true);
settings.set("vulkan.minSeverity", "warning");

The same settings in a game's project.luau:

engine.settings.vulkan.layers = { "VK_LAYER_KHRONOS_validation" }
engine.settings.vulkan.debugging = true

Without vulkan.debugging, naming and labelling do nothing and cost nothing on the GPU.

On macOS, if the loader does not find the Homebrew layers, point it at them:

VK_ADD_LAYER_PATH=/opt/homebrew/share/vulkan/explicit_layer.d xmake run shader

A layer the machine does not have is not an error: the renderer writes [vulkan] warning: the layer ... is not installed: running without it on the error output and starts without it. So does a layer the loader lists but cannot open (its manifest is there, its library is not: [vulkan] warning: a layer could not be loaded), and synchronization validation or best practices the validation layer does not offer. A project can ask for the validation layer in debug builds without breaking the machines that do not have it.

Names

Every object the renderer creates has a name, shown in validation messages and captures instead of a hexadecimal handle: Sprite pipeline, Frame 1 uniforms, Texture 12, Swapchain image 2. The pipelines of a game shader are named after it: flash particle pipeline. The instance, the surface, the physical device and the queues have none.

To name a new object, call core::Device::setName() right after creating it:

device.setName(*buffer.getBuffer(), "Sprite instances");

Code that only holds an allocator gets the device from Allocator::getDevice().

core::DebugMessenger prints them under the message, with the labels being recorded:

[Vulkan67 Error] { Validation } vkCmdSetViewport(): pViewports[0].width (0.000000) is not greater than zero.
The Vulkan spec states: width must be greater than 0.0 (...)
  In: Sprites
  CommandBuffer: Frame 0 command buffer

Labels

A frame is recorded as these labelled groups, in order: Particle simulation, then Sprites and Particles, once per run of them, as they are drawn by layer, and Shapes. To label a new pass:

const command::CommandLabel label{device, commandBuffer, "My pass"};
myPass.record(commandBuffer);

Capturing a frame

Platform Tool How
Linux, Windows RenderDoc Launch the executable from RenderDoc, then press F12 or Print Screen in the game.
Linux, Windows (NVIDIA) Nsight Graphics Start a Frame Debugger activity on the executable.
macOS Xcode (Metal capture) See below. RenderDoc does not run on macOS.

Set the working directory to the project root, as xmake run does: the assets are loaded relative to it.

Xcode and MoltenVK

Vulkan runs on Metal through MoltenVK, so a capture shows Metal commands. Ask MoltenVK to capture, then open the file:

MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE=2 MVK_CONFIG_AUTO_GPU_CAPTURE_OUTPUT_FILE=/tmp/frame.gputrace \
    METAL_CAPTURE_ENABLED=1 build/macosx/arm64/release/shader
open /tmp/frame.gputrace

MVK_CONFIG_AUTO_GPU_CAPTURE_SCOPE=2 captures the first frame. The labels appear as debug groups.