Package org.lwjgl.vulkan

Class EXTDebugMarker

java.lang.Object
org.lwjgl.vulkan.EXTDebugMarker
public class EXTDebugMarker extends 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 =
     {
         .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);
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 Details

  • Method Details

    • 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)
      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 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 an application-defined name to an object.
      C Specification

      An object can be given an application-defined 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 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
      • 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 - 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
      • 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 - 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
      • 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 - the command buffer into which the command is recorded.
      pMarkerInfo - a pointer to a VkDebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.