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
user-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
An object can be provided a user-defined name by calling
vkSetDebugUtilsObjectNameEXT as defined below.
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 must be 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 user-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.