The VK_EXT_debug_marker extension is a device extension. It introduces
concepts of object naming and tagging, for better tracking of Vulkan
objects, as well as additional commands for recording annotations of
named sections of a workload to aid organization and offline analysis in
external tools.
Associate a name with an image, for easier debugging in external tools
or with validation layers that can print a friendly name when referring
to objects in error messages.
extern VkDevice device;
extern VkImage image;
// Must call extension functions through a function pointer:
PFN_vkDebugMarkerSetObjectNameEXT pfnDebugMarkerSetObjectNameEXT = (PFN_vkDebugMarkerSetObjectNameEXT)vkGetDeviceProcAddr(device, "vkDebugMarkerSetObjectNameEXT");
// Set a name on the image
const VkDebugMarkerObjectNameInfoEXT imageNameInfo =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT,
.pNext = NULL,
.objectType = VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT,
.object = (uint64_t)image,
.pObjectName = "Brick Diffuse Texture",
};
pfnDebugMarkerSetObjectNameEXT(device, &imageNameInfo);
// A subsequent error might print:
// Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a
// command buffer with no memory bound to it.
Example 2
Annotating regions of a workload with naming information so that offline
analysis tools can display a more usable visualization of the commands
submitted.
extern VkDevice device;
extern VkCommandBuffer commandBuffer;
// Must call extension functions through a function pointer:
PFN_vkCmdDebugMarkerBeginEXT pfnCmdDebugMarkerBeginEXT = (PFN_vkCmdDebugMarkerBeginEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerBeginEXT");
PFN_vkCmdDebugMarkerEndEXT pfnCmdDebugMarkerEndEXT = (PFN_vkCmdDebugMarkerEndEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerEndEXT");
PFN_vkCmdDebugMarkerInsertEXT pfnCmdDebugMarkerInsertEXT = (PFN_vkCmdDebugMarkerInsertEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerInsertEXT");
// Describe the area being rendered
const VkDebugMarkerMarkerInfoEXT houseMarker =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT,
.pNext = NULL,
.pMarkerName = "Brick House",
.color = { 1.0f, 0.0f, 0.0f, 1.0f },
};
// Start an annotated group of calls under the 'Brick House' name
pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker);
{
// A mutable structure for each part being rendered
VkDebugMarkerMarkerInfoEXT housePartMarker =
{
.sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT,
.pNext = NULL,
.pMarkerName = NULL,
.color = { 0.0f, 0.0f, 0.0f, 0.0f },
};
// Set the name and insert the marker
housePartMarker.pMarkerName = "Walls";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
// Insert the drawcall for the walls
vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
// Insert a recursive region for two sets of windows
housePartMarker.pMarkerName = "Windows";
pfnCmdDebugMarkerBeginEXT(commandBuffer, &housePartMarker);
{
vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
}
pfnCmdDebugMarkerEndEXT(commandBuffer);
housePartMarker.pMarkerName = "Front Door";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
housePartMarker.pMarkerName = "Roof";
pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker);
vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
}
// End the house annotation started above
pfnCmdDebugMarkerEndEXT(commandBuffer);
Issues
1) Should the tag or name for an object be specified using the pNext
parameter in the object’s Vk*CreateInfo structure?
RESOLVED: No. While this fits with other Vulkan patterns and would
allow more type safety and future proofing against future objects, it
has notable downsides. In particular passing the name at Vk*CreateInfo
time does not allow renaming, prevents late binding of naming
information, and does not allow naming of implicitly created objects
such as queues and swapchain images.
RESOLVED: Yes. The functions have been expanded to take an optional
color which can be used at will by implementations consuming the command
buffer annotations in their visualization.
3) Should the functions added in this extension accept an extensible
structure as their parameter for a more flexible API, as opposed to
direct function parameters? If so, which functions?
RESOLVED: Yes. All functions have been modified to take a structure
type with extensible pNext pointer, to allow future extensions to add
additional annotation information in the same commands.
Version History
Revision 1, 2016-02-24 (Baldur Karlsson)
Initial draft, based on LunarG marker spec
Revision 2, 2016-02-26 (Baldur Karlsson)
Renamed Dbg to DebugMarker in function names
Allow markers in secondary command buffers under certain
circumstances
Minor language tweaks and edits
Revision 3, 2016-04-23 (Baldur Karlsson)
Reorganize spec layout to closer match desired organization
Added optional color to markers (both regions and inserted
labels)
Changed functions to take extensible structs instead of direct
function parameters
vkCmdDebugMarkerEndEXT - Close a command buffer marker region
Description
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
cmdDebugMarkerBeginEXT and cmdDebugMarkerEndEXTmust be matched
and balanced.
If commandBuffer
is a secondary command buffer, there must be an outstanding
cmdDebugMarkerBeginEXT command recorded to commandBuffer that
has not previously been ended by a call to cmdDebugMarkerEndEXT
VkDebugMarkerObjectNameInfoEXT - Specify parameters of a name to give to
an object
Description
Applications may change the name associated with an object simply by
calling debugMarkerSetObjectNameEXT again with a new string. To remove
a previously set name, pObjectNameshould be an empty string.
VkDebugMarkerObjectTagInfoEXT - Specify parameters of a tag to attach to
an object
Description
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.
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 0.0, then it is ignored.
The primary expected use of ERROR_VALIDATION_FAILED_EXT is for
validation layer testing to prevent invalid commands from reaching the
ICD. It is not expected that an application would see this error code
during normal use of the validation layers. If an application returns
TRUE in
DebugUtilsMessengerCallbackDataEXT,
the validation layers will return this error code instead of passing the
command down the dispatch chain.