org.lwjgl.vulkan

Class EXTDebugMarker

java.lang.Object

org.lwjgl.vulkan.EXTDebugMarker

public class EXTDebugMarker
extends java.lang.Object

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.

Examples

Example 1

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 =
     {
         VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, // sType
         NULL,                                           // pNext
         VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT,          // objectType
         (uint64_t)image,                                // object
         "Brick Diffuse Texture",                        // pObjectName
     };
 
     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 visualisation 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 =
     {
         VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
         NULL,                                           // pNext
         "Brick House",                                  // pMarkerName
         { 1.0f, 0.0f, 0.0f, 1.0f },                     // color
     };
 
     // Start an annotated group of calls under the 'Brick House' name
     pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker);
     {
         // A mutable structure for each part being rendered
         VkDebugMarkerMarkerInfoEXT housePartMarker =
         {
             VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType
             NULL,                                           // pNext
             NULL,                                           // pMarkerName
             { 0.0f, 0.0f, 0.0f, 0.0f },                     // color
         };
 
         // 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);

Name String

VK_EXT_debug_marker

Extension Type

Device extension

Registered Extension Number

23

Revision

4

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_EXT_debug_report

Deprecation state

• Promoted to VK_EXT_debug_utils extension

Contact

• Baldur Karlsson baldurk

Last Modified Date

2017-01-31

IP Status

No known IP claims.

Contributors

• Baldur Karlsson
• Dan Ginsburg, Valve
• Jon Ashburn, LunarG
• Kyle Spagnoli, NVIDIA

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VK_EXT_DEBUG_MARKER_EXTENSION_NAME The extension name.
static int	VK_EXT_DEBUG_MARKER_SPEC_VERSION The extension specification version.
static int	VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT Extends VkStructureType.
static int	VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT Extends VkStructureType.
static int	VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static void	nvkCmdDebugMarkerBeginEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long pMarkerInfo) Unsafe version of: CmdDebugMarkerBeginEXT
static void	nvkCmdDebugMarkerInsertEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long pMarkerInfo) Unsafe version of: CmdDebugMarkerInsertEXT
static int	nvkDebugMarkerSetObjectNameEXT(org.lwjgl.vulkan.VkDevice device, long pNameInfo) Unsafe version of: DebugMarkerSetObjectNameEXT
static int	nvkDebugMarkerSetObjectTagEXT(org.lwjgl.vulkan.VkDevice device, long pTagInfo) Unsafe version of: DebugMarkerSetObjectTagEXT
static void	vkCmdDebugMarkerBeginEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, VkDebugMarkerMarkerInfoEXT pMarkerInfo) Open a command buffer marker region.
static void	vkCmdDebugMarkerEndEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer) Close a command buffer marker region.
static void	vkCmdDebugMarkerInsertEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, VkDebugMarkerMarkerInfoEXT pMarkerInfo) Insert a marker label into a command buffer.
static int	vkDebugMarkerSetObjectNameEXT(org.lwjgl.vulkan.VkDevice device, VkDebugMarkerObjectNameInfoEXT pNameInfo) Give a user-friendly name to an object.
static int	vkDebugMarkerSetObjectTagEXT(org.lwjgl.vulkan.VkDevice device, VkDebugMarkerObjectTagInfoEXT pTagInfo) Attach arbitrary data to an object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VK_EXT_DEBUG_MARKER_SPEC_VERSION

public static final int VK_EXT_DEBUG_MARKER_SPEC_VERSION

The extension specification version.

See Also:

Constant Field Values

VK_EXT_DEBUG_MARKER_EXTENSION_NAME

public static final java.lang.String VK_EXT_DEBUG_MARKER_EXTENSION_NAME

The extension name.

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

See Also:

Constant Field Values

VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

Extends VkStructureType.

Enum values:

• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT
• STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

See Also:

Constant Field Values

Method Detail

nvkDebugMarkerSetObjectTagEXT

public static int nvkDebugMarkerSetObjectTagEXT(org.lwjgl.vulkan.VkDevice device,
                                                long pTagInfo)

Unsafe version of: DebugMarkerSetObjectTagEXT

vkDebugMarkerSetObjectTagEXT

public static int vkDebugMarkerSetObjectTagEXT(org.lwjgl.vulkan.VkDevice device,
                                               VkDebugMarkerObjectTagInfoEXT pTagInfo)

Attach arbitrary data to an object.

C Specification

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,
     const VkDebugMarkerObjectTagInfoEXT*        pTagInfo);

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pTagInfo must be a valid pointer to a valid VkDebugMarkerObjectTagInfoEXT structure

Host Synchronization

• Host access to pTagInfo.object must be externally synchronized

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDebugMarkerObjectTagInfoEXT

Parameters:

device - the device that created the object.

pTagInfo - a pointer to a VkDebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.

nvkDebugMarkerSetObjectNameEXT

public static int nvkDebugMarkerSetObjectNameEXT(org.lwjgl.vulkan.VkDevice device,
                                                 long pNameInfo)

Unsafe version of: DebugMarkerSetObjectNameEXT

vkDebugMarkerSetObjectNameEXT

public static int vkDebugMarkerSetObjectNameEXT(org.lwjgl.vulkan.VkDevice device,
                                                VkDebugMarkerObjectNameInfoEXT pNameInfo)

Give a user-friendly name to an object.

C Specification

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

 VkResult vkDebugMarkerSetObjectNameEXT(
     VkDevice                                    device,
     const VkDebugMarkerObjectNameInfoEXT*       pNameInfo);

Valid Usage (Implicit)

• device must be a valid VkDevice handle
• pNameInfo must be a valid pointer to a valid VkDebugMarkerObjectNameInfoEXT structure

Host Synchronization

• Host access to pNameInfo.object must be externally synchronized

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDebugMarkerObjectNameInfoEXT

Parameters:

device - the device that created the object.

pNameInfo - a pointer to a VkDebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

nvkCmdDebugMarkerBeginEXT

public static void nvkCmdDebugMarkerBeginEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                             long pMarkerInfo)

Unsafe version of: CmdDebugMarkerBeginEXT

vkCmdDebugMarkerBeginEXT

public static void vkCmdDebugMarkerBeginEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                            VkDebugMarkerMarkerInfoEXT pMarkerInfo)

Open a command buffer marker region.

C Specification

A marker region can be opened by calling:

 void vkCmdDebugMarkerBeginEXT(
     VkCommandBuffer                             commandBuffer,
     const VkDebugMarkerMarkerInfoEXT*           pMarkerInfo);

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• pMarkerInfo must be a valid pointer to a valid VkDebugMarkerMarkerInfoEXT structure
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

Host Synchronization

• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

VkDebugMarkerMarkerInfoEXT

Parameters:

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

pMarkerInfo - a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.

vkCmdDebugMarkerEndEXT

public static void vkCmdDebugMarkerEndEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer)

Close a command buffer marker region.

C Specification

A marker region can be closed by calling:

 void vkCmdDebugMarkerEndEXT(
     VkCommandBuffer                             commandBuffer);

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 vkCmdDebugMarkerBeginEXT and vkCmdDebugMarkerEndEXT must be matched and balanced.

Valid Usage

• There must be an outstanding CmdDebugMarkerBeginEXT command prior to the vkCmdDebugMarkerEndEXT on the queue that commandBuffer is submitted to
• 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.

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

Host Synchronization

• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

Parameters:

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

nvkCmdDebugMarkerInsertEXT

public static void nvkCmdDebugMarkerInsertEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                              long pMarkerInfo)

Unsafe version of: CmdDebugMarkerInsertEXT

vkCmdDebugMarkerInsertEXT

public static void vkCmdDebugMarkerInsertEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer,
                                             VkDebugMarkerMarkerInfoEXT pMarkerInfo)

Insert a marker label into a command buffer.

C Specification

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

 void vkCmdDebugMarkerInsertEXT(
     VkCommandBuffer                             commandBuffer,
     const VkDebugMarkerMarkerInfoEXT*           pMarkerInfo);

Valid Usage (Implicit)

• commandBuffer must be a valid VkCommandBuffer handle
• pMarkerInfo must be a valid pointer to a valid VkDebugMarkerMarkerInfoEXT structure
• commandBuffer must be in the recording state
• The VkCommandPool that commandBuffer was allocated from must support graphics, or compute operations

Host Synchronization

• Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

Command Buffer Levels	Render Pass Scope	Supported Queue Types	Pipeline Type
Primary Secondary	Both	Graphics Compute

See Also

VkDebugMarkerMarkerInfoEXT

Parameters:

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

pMarkerInfo - a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.