32.1. 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.

32.1.1. Object Annotation

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

An object can be given a user-friendly name by calling:

 

VkResult vkDebugMarkerSetObjectNameEXT(
    VkDevice                                    device,
    VkDebugMarkerObjectNameInfoEXT*             pNameInfo);

  • device is the device that created the object.
  • pNameInfo is a pointer to an instance of the VkDebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

The VkDebugMarkerObjectNameInfoEXT structure is defined as:

 

typedef struct VkDebugMarkerObjectNameInfoEXT {
    VkStructureType               sType;
    const void*                   pNext;
    VkDebugReportObjectTypeEXT    objectType;
    uint64_t                      object;
    const char*                   pObjectName;
} VkDebugMarkerObjectNameInfoEXT;

  • sType is the type of this structure.
  • pNext is NULL or a pointer to an extension-specific structure.
  • objectType is a VkDebugReportObjectTypeEXT specifying the type of the object to be named.
  • object is the object to be named.
  • pObjectName is a null-terminated UTF-8 string specifying the name to apply to object.

Applications may change the name associated with an object simply by calling vkDebugMarkerSetObjectNameEXT again with a new string. To remove a previously set name, pName should be set to an empty string.

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 has 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. To attach data to an object, call:

 

VkResult vkDebugMarkerSetObjectTagEXT(
    VkDevice                                    device,
    VkDebugMarkerObjectTagInfoEXT*              pTagInfo);

  • device is the device that created the object.
  • pTagInfo is a pointer to an instance of the VkDebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.

The VkDebugMarkerObjectTagInfoEXT structure is defined as:

 

typedef struct VkDebugMarkerObjectTagInfoEXT {
    VkStructureType               sType;
    const void*                   pNext;
    VkDebugReportObjectTypeEXT    objectType;
    uint64_t                      object;
    uint64_t                      tagName;
    size_t                        tagSize;
    const void*                   pTag;
} VkDebugMarkerObjectTagInfoEXT;

  • sType is the type of this structure.
  • pNext is NULL or a pointer to an extension-specific structure.
  • objectType is a VkDebugReportObjectTypeEXT specifying the type of the object to be named.
  • object is the object to be tagged.
  • tagName is a numerical identifier of the tag.
  • tagSize is the number of bytes of data to attach to the object.
  • pTag is an array of tagSize bytes containing the data to be associated with the object.

The tagName parameter gives a name or identifier to the type of data being tagged. This can be used by debugging layers to easily filter for only data that can be used by that implementation.

VkDebugReportObjectTypeEXT specifies the type of an object passed to the VkDebugMarkerObjectNameInfoEXT and VkDebugMarkerObjectTagInfoEXT commands.

 

typedef enum VkDebugReportObjectTypeEXT {
    VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT = 0,
    VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT = 1,
    VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT = 2,
    VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT = 3,
    VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT = 4,
    VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT = 5,
    VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT = 6,
    VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT = 7,
    VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT = 8,
    VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT = 9,
    VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT = 10,
    VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT = 11,
    VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT = 12,
    VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT = 13,
    VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT = 14,
    VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT = 15,
    VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT = 16,
    VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT = 17,
    VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT = 18,
    VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT = 19,
    VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT = 20,
    VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT = 21,
    VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT = 22,
    VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT = 23,
    VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT = 24,
    VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT = 25,
    VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT = 26,
    VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT = 27,
    VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT = 28,
} VkDebugReportObjectTypeEXT;

The possible values are:

  • VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT is an unknown object.
  • VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT is a VkInstance.
  • VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT is a VkPhysicalDevice.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT is a VkDevice.
  • VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT is a VkQueue.
  • VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT is a VkSemaphore.
  • VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT is a VkCommandBuffer.
  • VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT is a VkFence.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT is a VkDeviceMemory.
  • VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT is a VkBuffer.
  • VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT is a VkImage.
  • VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT is a VkEvent.
  • VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT is a VkQueryPool.
  • VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT is a VkBufferView.
  • VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT is a VkImageView.
  • VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT is a VkShaderModule.
  • VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT is a VkPipelineCache.
  • VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT is a VkPipelineLayout.
  • VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT is a VkRenderPass.
  • VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT is a VkPipeline.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT is a VkDescriptorSetLayout.
  • VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT is a VkSampler.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT is a VkDescriptorPool.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT is a VkDescriptorSet.
  • VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT is a VkFramebuffer.
  • VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT is a VkCommandPool.
  • VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT is a VkSurfaceKHR.
  • VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT is a VkSwapchainKHR.
  • VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT is a VkDebugReportCallbackEXT.

32.1.2. 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.

A marker region can be opened by calling:

 

void vkCmdDebugMarkerBeginEXT(
    VkCommandBuffer                             commandBuffer,
    VkDebugMarkerMarkerInfoEXT*                 pMarkerInfo);

  • commandBuffer is the command buffer into which the command is recorded.
  • pMarkerInfo is a pointer to an instance of the VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.

The VkDebugMarkerMarkerInfoEXT structure is defined as:

 

typedef struct VkDebugMarkerMarkerInfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    const char*        pMarkerName;
    float              color[4];
} VkDebugMarkerMarkerInfoEXT;

  • sType is the type of this structure.
  • pNext is NULL or a pointer to an extension-specific structure.
  • pMarkerName is a pointer to a null-terminated UTF-8 string that contains the name of the marker.
  • color is an optional RGBA color value that can be associated with the marker. A particular implementation may choose to ignore this color value. The values contain RGBA values in order, in the range 0.0 to 1.0. If all elements in color are set to 0.0 then it is ignored.

A marker region can be closed by calling:

 

void vkCmdDebugMarkerEndEXT(
    VkCommandBuffer                             commandBuffer);

  • commandBuffer is the command buffer into which the command is recorded.

An application may open a marker region in one command buffer and close it in another, or otherwise split marker regions across multiple command buffers or multiple queue submissions. When viewed from the linear series of submissions to a single queue, the calls to vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT must be matched and balanced.

Any calls to vkCmdDebugMarkerBeginEXT within a secondary command buffer must have a matching vkCmdDebugMarkerEndEXT in that same command buffer, and marker regions begun outside of the secondary command buffer must not be ended inside it.

A single marker label can be inserted into a command buffer by calling:

 

void vkCmdDebugMarkerInsertEXT(
    VkCommandBuffer                             commandBuffer,
    VkDebugMarkerMarkerInfoEXT*                 pMarkerInfo);

  • commandBuffer is the command buffer into which the command is recorded.
  • pMarkerInfo is a pointer to an instance of the VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.