Package org.lwjgl.vulkan

Class 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
    Deprecation state
    Contact
    Last Modified Date
    2017-01-31
    IP Status
    No known IP claims.
    Contributors
    • Baldur Karlsson
    • Dan Ginsburg, Valve
    • Jon Ashburn, LunarG
    • Kyle Spagnoli, NVIDIA

    • Method Detail

      • vkDebugMarkerSetObjectTagEXT

        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 - the device that created the object.
        pTagInfo - a pointer to an instance of the VkDebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.

      • vkDebugMarkerSetObjectNameEXT

        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 - the device that created the object.
        pNameInfo - a pointer to an instance of the VkDebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

      • vkCmdDebugMarkerBeginEXT

        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
        Host Synchronization
        • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
        Command Properties
        Command Buffer LevelsRender Pass ScopeSupported Queue TypesPipeline Type
        Primary SecondaryBothGraphics Compute
        See Also

        VkDebugMarkerMarkerInfoEXT

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

      • vkCmdDebugMarkerEndEXT

        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
        Host Synchronization
        • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
        Command Properties
        Command Buffer LevelsRender Pass ScopeSupported Queue TypesPipeline Type
        Primary SecondaryBothGraphics Compute
        Parameters:
        commandBuffer - the command buffer into which the command is recorded.

      • vkCmdDebugMarkerInsertEXT

        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
        Host Synchronization
        • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized
        Command Properties
        Command Buffer LevelsRender Pass ScopeSupported Queue TypesPipeline Type
        Primary SecondaryBothGraphics Compute
        See Also

        VkDebugMarkerMarkerInfoEXT

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