Debugging and Performance Measurement Techniques

Debugging failures and reverse engineering an implementation, as well as measuring the performance of a system once it has been authored, are as important as writing new code. Vulkan is a vast and complicated API and, more than ever, knowing how to debug it is paramount. In this chapter, we will explore several recipes on how to debug and inspect your implementation. We will also demonstrate how to measure the performance of your implementation once you can display an image onscreen. After all, graphics programming is all about extracting the last drop of performance from the hardware and Vulkan was designed to help you do just that.

In this chapter, we’re going to cover the following main topics:

• Frame debugging
• Naming Vulkan objects for easy debugging
• Printing values from shaders in Vulkan
• Intercepting validation layer messages
• Retrieving debug information from shaders
• Measuring performance in...

Technical requirements

For this chapter, you will need to make sure you have VS 2022 installed along with the Vulkan SDK. Please revisit Chapter 1, Vulkan Core Concepts, under the Technical requirements section for details on setting up. Additionally, you will need RenderDoc and Tracy for this chapter. The steps to download and install these tools will be provided in the corresponding recipes within this chapter.

Frame debugging

Capturing and replaying a frame is very important for debugging graphics applications. Different than a live capture, in which results are captured and displayed as your application is running, capturing means recording all the commands sent to the GPU along with their data. This includes all the draw calls, shaders, textures, buffers, and other resources used to render the frame. Replaying a frame means executing those recorded commands again. Frame replay is a powerful feature for debugging because it allows developers to closely examine the rendering process, step by step, and see exactly what’s happening at each stage. If a bug or graphical glitch occurs, frame replay can help pin down exactly where and why it’s happening. There are multiple tools for frame debugging, such as RenderDoc, PIX, NVIDIA’s Nsight Graphics, and AMD Radeon GPU Profiler.

In this recipe, we will focus on how to use RenderDoc since it is open source, cross-platform...

Naming Vulkan objects for easy debugging

Using Vulkan means you need to create and manage many Vulkan objects. By default, those objects are identified by their handle, a numerical ID. Although numerical IDs are easy to maintain from an application perspective, they are meaningless to humans. Consider the following error message, provided by the validation layer:

VUID-VkImageViewCreateInfo-imageViewType-04974 ] Object 0: handle = 0xcb3ee80000000007, type = VK_OBJECT_TYPE_IMAGE; | MessageID = 0xc120e150 | vkCreateImageView(): Using pCreateInfo->viewType VK_IMAGE_VIEW_TYPE_2D and the subresourceRange.layerCount VK_REMAINING_ARRAY_LAYERS=(2) and must 1 (try looking into VK_IMAGE_VIEW_TYPE_*_ARRAY). The Vulkan spec states: If viewType is VK_IMAGE_VIEW_TYPE_1D, VK_IMAGE_VIEW_TYPE_2D, or VK_IMAGE_VIEW_TYPE_3D; and subresourceRange.layerCount is VK_REMAINING_ARRAY_LAYERS, then the remaining number of layers must be 1

The preceding message is useful, but finding which image has been...

Printing values from shaders in Vulkan

As graphics programmers, we must all agree that debugging shaders is one of the most frustrating aspects of our jobs. Even though some frame capture software provides shader debugging, it may still be difficult to find the exact pixel you would like to debug, or you may need another piece of information about a set of pixels instead of just inspecting them one by one.

Thankfully, Vulkan provides a way to print values directly from shaders. The information can be inspected directly on RenderDoc, for example, or retrieved from the validation error messages (please refer to the Retrieving debugging information from shaders recipe for more details on how to do this).

In this recipe, you will learn how to print values from your shader code using a simple function that is like printf.

Getting ready

To utilize the functionality of printing values from shaders, it’s a prerequisite to enable the VK_KHR_shader_non_semantic_info device...

Intercepting validation layer messages

In some circumstances, validation errors are so plentiful that it becomes impossible to know where the cause of the problem is. For that reason, it would be ideal to interrupt the execution of your program as soon as an error is detected, especially when debugging your application. The debug utility extension (VK_EXT_debug_utils) allows you to install a callback function that is invoked whenever an error is detected.

In this recipe, you will learn how to install a debug callback to intercept error messages emitted by the validation layer and make your debugging sessions more productive.

Getting ready

To be able to set a callback whenever an error occurs, you need to enable the VK_EXT_debug_utils extension. Please refer to the Getting ready section of the Naming Vulkan objects for easier debugging recipe to learn how to enable this extension when creating a Vulkan instance.

How to do it…

Before installing and using the callback...

Retrieving debug information from shaders

One of the most difficult tasks in graphics programming is writing tests. Be those smoke, integration, end-to-end, or unit tests, how do you ensure that the output of your engine is really what you would expect? Except for simple tests, screenshot-like types of tests are prone to several problems. One particularly difficult problem is testing shader code – since you don’t usually have access to the hardware, testing shader code is very painful.

Thankfully, Vulkan has a mechanism that allows you to capture the value output from shaders with the debugPrintfEXT function directly from the validation layer. This mechanism isn’t new and could be enabled using the Vulkan Configurator. But, introduced with the Vulkan SDK 1.3.275, the VK_EXT_layer_settings instance extension allows you to enable this mechanism directly from your application without manually having to edit any other configuration.

In this recipe, you will learn...

Measuring performance in Vulkan with timestamp queries

Measuring the performance of CPU and GPU workloads side by side is invaluable. The Tracy profiler allows you to do just that in a cross-platform way with minimal intrusion. And it’s easy to use, all within a small C++ library.

In this recipe, you will learn how to integrate Tracy Profiler into your app and instrument it to collect GPU performance information.

Getting ready

The first thing to do is to download Tracy from https://github.com/wolfpld/tracy and include it in your project. You should also download the Tracy client/server to collect and inspect the data.

How to do it…

Instrumenting your code to use with Tracy is easy and requires only a few steps. To be able to collect data about the GPU performance, you will need a Tracy/Vulkan context along with a dedicated command buffer for it to calibrate the timestamps. After that, instrumenting your code is straightforward:

1. First, include the...