Debugging

To aid developers in tracking down errors in the application’s use of Vulkan, particularly in combination with an external debugger or profiler, debugging extensions may be available.

If this Specification was generated with any such extensions included, they will be described in the remainder of this chapter.

Debug Utilities

Vulkan provides flexible debugging utilities for debugging an application.

The Object Debug Annotation section describes how to associate either a name or binary data with a specific Vulkan object.

The Queue Labels section describes how to annotate and group the work submitted to a queue.

The Command Buffer Labels section describes how to associate logical elements of the scene with commands in a VkCommandBuffer.

The Debug Messengers section describes how to create debug messenger objects associated with an application supplied callback to capture debug messages from a variety of Vulkan components.

Object Debug Annotation

It can be useful for an application to provide its own content relative to a specific Vulkan object.

The following commands allow application developers to associate application-defined information with Vulkan objects. These commands are device-level commands but they may reference instance-level objects (such as VkInstance) and physical device-level objects (such as VkPhysicalDevice) with a few restrictions: * The data for the corresponding object may still be available after the VkDevice used in the corresponding API call to set it is destroyed, but access to this data is not guaranteed and should be avoided. * Subsequent calls to change the data of the same object across multiple VkDevice objects, may result in the data being changed to the most recent version for all VkDevice objects and not just the VkDevice used in the most recent API call.

Object Naming

Object Data Association

In addition to setting a name for an object, debugging and validation layers may have uses for additional binary data on a per-object basis that have no other place in the Vulkan API.

For example, a VkShaderModule could have additional debugging data attached to it to aid in offline shader tracing.

Additional data can be attached to an object by calling vkSetDebugUtilsObjectTagEXT as defined below.

Queue Labels

All Vulkan work is submitted using queues. It is possible for an application to use multiple queues, each containing multiple command buffers, when performing work. It can be useful to identify which queue, or even where in a queue, something has occurred.

To begin identifying a region using a debug label inside a queue, you may use the vkQueueBeginDebugUtilsLabelEXT command.

Then, when the region of interest has passed, you may end the label region using vkQueueEndDebugUtilsLabelEXT.

Additionally, a single debug label may be inserted at any time using vkQueueInsertDebugUtilsLabelEXT.

Command Buffer Labels

Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.

To identify the beginning of a debug label region in a command buffer, vkCmdBeginDebugUtilsLabelEXT can be used as defined below.

To indicate the end of a debug label region in a command buffer, vkCmdEndDebugUtilsLabelEXT can be used.

To insert a single command buffer debug label inside of a command buffer, vkCmdInsertDebugUtilsLabelEXT can be used as defined below.

Debug Messengers

Vulkan allows an application to register multiple callbacks with any Vulkan component wishing to report debug information. Some callbacks may log the information to a file, others may cause a debug break point or other application-defined behavior. A primary producer of callback messages are the validation layers. An application can register callbacks even when no validation layers are enabled, but they will only be called for the Vulkan loader and, if implemented, other layer and driver events.

Debug Markers

Debug markers provide a flexible way for debugging and validation layers to receive annotation and debug information.

The Object Annotation section describes how to associate a name or binary data with a Vulkan object.

The Command Buffer Markers section describes how to associate logical elements of the scene with commands in the command buffer.

Object Annotation

The commands in this section allow application developers to associate application-defined information with Vulkan objects at will.

Command Buffer Markers

Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer’s ability to navigate the commands viewed holistically.

The marker commands vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT define regions of a series of commands that are grouped together, and they can be nested to create a hierarchy. The vkCmdDebugMarkerInsertEXT command allows insertion of a single label within a command buffer.

Debug Report Callbacks

Device Loss Debugging

Device Diagnostic Checkpoints

Device execution progress can be tracked for the purposes of debugging a device loss by annotating the command stream with application-defined diagnostic checkpoints.

Note that pCheckpointMarker is treated as an opaque value. It does not need to be a valid pointer and will not be dereferenced by the implementation.

Device Fault Diagnosis

Vendor Binary Crash Dumps

Applications can store the vendor-specific binary crash dump data retrieved by calling vkGetDeviceFaultInfoEXT for later analysis using external tools.

However, the format of this data may depend on the vendor ID, device ID, driver version, and other details of the device. To enable external applications to identify the original device from which a crash dump was generated, the initial bytes written to VkDeviceFaultInfoEXT::pVendorBinaryData must begin with a valid crash dump header.

Active Tooling Information

Frame Boundary

Note that in the presence of timeline semaphores, the last queue submission might not be the last one to be submitted, as timeline semaphores allow for wait-before-signal submissions. In the context of frame boundary, the queue submission that should be done flagged as the last one is the one that is meant to be executed last, even if it may not be the last one to be submitted.