Top Description Fields Constructors Methods
org.lwjgl.vulkan

public Class EXTDebugMarker

extends Object
Class Inheritance
Imports
org.lwjgl.system.*
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 =
    {
        .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 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 =
    {
        .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);
VK_EXT_debug_marker
Name String
VK_EXT_debug_marker
Extension Type
Device extension
Registered Extension Number
23
Revision
4
Extension and Version Dependencies
VK_EXT_debug_report
Deprecation state
Special Use
Contact
Other Extension Metadata
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

Modifier and TypeField and Description
public static final String
VK_EXT_DEBUG_MARKER_EXTENSION_NAME

The extension name.

public static final int
VK_EXT_DEBUG_MARKER_SPEC_VERSION

The extension specification version.

public static final int
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

Extends VkStructureType.

public static final int
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

Extends VkStructureType.

Constructor Summary

AccessConstructor and Description
protected
EXTDebugMarker()

Method Summary

Modifier and TypeMethod and Description
public static void
nvkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)

Unsafe version of: CmdDebugMarkerBeginEXT

public static void
nvkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)

Unsafe version of: CmdDebugMarkerInsertEXT

public static int
nvkDebugMarkerSetObjectNameEXT(VkDevice device, long pNameInfo)

Unsafe version of: DebugMarkerSetObjectNameEXT

public static int
nvkDebugMarkerSetObjectTagEXT(VkDevice device, long pTagInfo)

Unsafe version of: DebugMarkerSetObjectTagEXT

public static void
vkCmdDebugMarkerBeginEXT(VkCommandBuffer
the command buffer into which the command is recorded.
commandBuffer, VkDebugMarkerMarkerInfoEXT
a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.
pMarkerInfo)

Open a command buffer marker region.

public static void
vkCmdDebugMarkerEndEXT(VkCommandBuffer
the command buffer into which the command is recorded.
commandBuffer)

Close a command buffer marker region.

public static void
vkCmdDebugMarkerInsertEXT(VkCommandBuffer
the command buffer into which the command is recorded.
commandBuffer, VkDebugMarkerMarkerInfoEXT
a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.
pMarkerInfo)

Insert a marker label into a command buffer.

public static int
vkDebugMarkerSetObjectNameEXT(VkDevice
the device that created the object.
device, VkDebugMarkerObjectNameInfoEXT
a pointer to a VkDebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.
pNameInfo)

Give a user-friendly name to an object.

public static int
vkDebugMarkerSetObjectTagEXT(VkDevice
the device that created the object.
device, VkDebugMarkerObjectTagInfoEXT
a pointer to a VkDebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.
pTagInfo)

Attach arbitrary data to an object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

VK_EXT_DEBUG_MARKER_EXTENSION_NAMEback to summary
public static final String VK_EXT_DEBUG_MARKER_EXTENSION_NAME

The extension name.

VK_EXT_DEBUG_MARKER_SPEC_VERSIONback to summary
public static final int VK_EXT_DEBUG_MARKER_SPEC_VERSION

The extension specification version.

VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

Extends VkStructureType.

Enum values:
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXTback to summary
public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

Extends VkStructureType.

Enum values:

Constructor Detail

EXTDebugMarkerback to summary
protected EXTDebugMarker()

Method Detail

nvkCmdDebugMarkerBeginEXTback to summary
public static void nvkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)

Unsafe version of: CmdDebugMarkerBeginEXT

nvkCmdDebugMarkerInsertEXTback to summary
public static void nvkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)

Unsafe version of: CmdDebugMarkerInsertEXT

nvkDebugMarkerSetObjectNameEXTback to summary
public static int nvkDebugMarkerSetObjectNameEXT(VkDevice device, long pNameInfo)

Unsafe version of: DebugMarkerSetObjectNameEXT

nvkDebugMarkerSetObjectTagEXTback to summary
public static int nvkDebugMarkerSetObjectTagEXT(VkDevice device, long pTagInfo)

Unsafe version of: DebugMarkerSetObjectTagEXT

vkCmdDebugMarkerBeginEXTback to summary
public static void vkCmdDebugMarkerBeginEXT(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
  • This command must only be called outside of a video coding scope
Host Synchronization
  • Host access to commandBuffer must be externally synchronized
  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
Command Properties
Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBothOutsideGraphics ComputeAction
See Also

VkDebugMarkerMarkerInfoEXT

Parameters
commandBuffer:VkCommandBuffer

the command buffer into which the command is recorded.

pMarkerInfo:VkDebugMarkerMarkerInfoEXT

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

vkCmdDebugMarkerEndEXTback to summary
public static void vkCmdDebugMarkerEndEXT(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
  • This command must only be called outside of a video coding scope
Host Synchronization
  • Host access to commandBuffer must be externally synchronized
  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
Command Properties
Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBothOutsideGraphics ComputeAction
Parameters
commandBuffer:VkCommandBuffer

the command buffer into which the command is recorded.

vkCmdDebugMarkerInsertEXTback to summary
public static void vkCmdDebugMarkerInsertEXT(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
  • This command must only be called outside of a video coding scope
Host Synchronization
  • Host access to commandBuffer must be externally synchronized
  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
Command Properties
Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
Primary SecondaryBothOutsideGraphics ComputeAction
See Also

VkDebugMarkerMarkerInfoEXT

Parameters
commandBuffer:VkCommandBuffer

the command buffer into which the command is recorded.

pMarkerInfo:VkDebugMarkerMarkerInfoEXT

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

vkDebugMarkerSetObjectNameEXTback to summary
public static int vkDebugMarkerSetObjectNameEXT(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)
Host Synchronization
  • Host access to pNameInfo→object must be externally synchronized
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkDebugMarkerObjectNameInfoEXT

Parameters
device:VkDevice

the device that created the object.

pNameInfo:VkDebugMarkerObjectNameInfoEXT

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

Annotations
@NativeType:VkResult
vkDebugMarkerSetObjectTagEXTback to summary
public static int vkDebugMarkerSetObjectTagEXT(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)
Host Synchronization
  • Host access to pTagInfo→object must be externally synchronized
Return Codes
On success, this command returns
On failure, this command returns
See Also

VkDebugMarkerObjectTagInfoEXT

Parameters
device:VkDevice

the device that created the object.

pTagInfo:VkDebugMarkerObjectTagInfoEXT

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

Annotations
@NativeType:VkResult