Package org.lwjgl.vulkan

Class EXTDebugUtils

java.lang.Object
org.lwjgl.vulkan.EXTDebugUtils
public class EXTDebugUtils extends Object
Due to the nature of the Vulkan interface, there is very little error information available to the developer and application. By using the VK_EXT_debug_utils extension, developers can obtain more information. When combined with validation layers, even more detailed feedback on the application’s use of Vulkan will be provided.

This extension provides the following capabilities:

  • The ability to create a debug messenger which will pass along debug messages to an application supplied callback.
  • The ability to identify specific Vulkan objects using a name or tag to improve tracking.
  • The ability to identify specific sections within a VkQueue or VkCommandBuffer using labels to aid organization and offline analysis in external tools.

The main difference between this extension and VK_EXT_debug_report and VK_EXT_debug_marker is that those extensions use VkDebugReportObjectTypeEXT to identify objects. This extension uses the core VkObjectType in place of VkDebugReportObjectTypeEXT. The primary reason for this move is that no future object type handle enumeration values will be added to VkDebugReportObjectTypeEXT since the creation of VkObjectType.

In addition, this extension combines the functionality of both VK_EXT_debug_report and VK_EXT_debug_marker by allowing object name and debug markers (now called labels) to be returned to the application’s callback function. This should assist in clarifying the details of a debug message including: what objects are involved and potentially which location within a VkQueue or VkCommandBuffer the message occurred.

Examples

Example 1

VK_EXT_debug_utils allows an application to register multiple callbacks with any Vulkan component wishing to report debug information. Some callbacks may log the information to a file, others may cause a debug break point or other application-defined behavior. An application can register callbacks even when no validation layers are enabled, but they will only be called for loader and, if implemented, driver events.

To capture events that occur while creating or destroying an instance an application can link a VkDebugUtilsMessengerCreateInfoEXT structure to the pNext element of the VkInstanceCreateInfo structure given to CreateInstance.

Example uses: Create three callback objects. One will log errors and warnings to the debug console using Windows OutputDebugString. The second will cause the debugger to break at that callback when an error happens and the third will log warnings to stdout.


     extern VkInstance instance;
     VkResult res;
     VkDebugUtilsMessengerEXT cb1, cb2, cb3;
 
     // Must call extension functions through a function pointer:
     PFN_vkCreateDebugUtilsMessengerEXT pfnCreateDebugUtilsMessengerEXT = (PFN_vkCreateDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkCreateDebugUtilsMessengerEXT");
     PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetInstanceProcAddr(instance, "vkDestroyDebugUtilsMessengerEXT");
 
     VkDebugUtilsMessengerCreateInfoEXT callback1 = {
         .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
         .pNext = NULL,
         .flags = 0,
         .messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT |
                            VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
         .messageType= VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
                       VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
         .pfnUserCallback = myOutputDebugString,
         .pUserData = NULL
     };
     res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb1);
     if (res != VK_SUCCESS) {
        // Do error handling for VK_ERROR_OUT_OF_MEMORY
     }
 
     callback1.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
     callback1.pfnUserCallback = myDebugBreak;
     callback1.pUserData = NULL;
     res = pfnCreateDebugUtilsMessengerEXT(instance, &callback1, NULL, &cb2);
     if (res != VK_SUCCESS) {
        // Do error handling for VK_ERROR_OUT_OF_MEMORY
     }
 
     VkDebugUtilsMessengerCreateInfoEXT callback3 = {
         .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,
         .pNext = NULL,
         .flags = 0,
         .messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
         .messageType = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |
                        VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
         .pfnUserCallback = mystdOutLogger,
         .pUserData = NULL
     };
     res = pfnCreateDebugUtilsMessengerEXT(instance, &callback3, NULL, &cb3);
     if (res != VK_SUCCESS) {
        // Do error handling for VK_ERROR_OUT_OF_MEMORY
     }
 
     ...
 
     // Remove callbacks when cleaning up
     pfnDestroyDebugUtilsMessengerEXT(instance, cb1, NULL);
     pfnDestroyDebugUtilsMessengerEXT(instance, cb2, NULL);
     pfnDestroyDebugUtilsMessengerEXT(instance, cb3, NULL);

Example 2

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 VkInstance instance;
     extern VkDevice device;
     extern VkImage image;
 
     // Must call extension functions through a function pointer:
     PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetInstanceProcAddr(instance, "vkSetDebugUtilsObjectNameEXT");
 
     // Set a name on the image
     const VkDebugUtilsObjectNameInfoEXT imageNameInfo =
     {
         .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT,
         .pNext = NULL,
         .objectType = VK_OBJECT_TYPE_IMAGE,
         .objectHandle = (uint64_t)image,
         .pObjectName = "Brick Diffuse Texture",
     };
 
     pfnSetDebugUtilsObjectNameEXT(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 3

Annotating regions of a workload with naming information so that offline analysis tools can display a more usable visualization of the commands submitted.


     extern VkInstance instance;
     extern VkCommandBuffer commandBuffer;
 
     // Must call extension functions through a function pointer:
     PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueBeginDebugUtilsLabelEXT");
     PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkQueueEndDebugUtilsLabelEXT");
     PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdBeginDebugUtilsLabelEXT");
     PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdEndDebugUtilsLabelEXT");
     PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetInstanceProcAddr(instance, "vkCmdInsertDebugUtilsLabelEXT");
 
     // Describe the area being rendered
     const VkDebugUtilsLabelEXT houseLabel =
     {
         .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
         .pNext = NULL,
         .pLabelName = "Brick House",
         .color = { 1.0f, 0.0f, 0.0f, 1.0f },
     };
 
     // Start an annotated group of calls under the 'Brick House' name
     pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
     {
         // A mutable structure for each part being rendered
         VkDebugUtilsLabelEXT housePartLabel =
         {
             .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
             .pNext = NULL,
             .pLabelName = NULL,
             .color = { 0.0f, 0.0f, 0.0f, 0.0f },
         };
 
         // Set the name and insert the marker
         housePartLabel.pLabelName = "Walls";
         pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
 
         // Insert the drawcall for the walls
         vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0);
 
         // Insert a recursive region for two sets of windows
         housePartLabel.pLabelName = "Windows";
         pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
         {
             vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0);
             vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0);
         }
         pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
 
         housePartLabel.pLabelName = "Front Door";
         pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
 
         vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0);
 
         housePartLabel.pLabelName = "Roof";
         pfnCmdInsertDebugUtilsLabelEXT(commandBuffer, &housePartLabel);
 
         vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0);
     }
     // End the house annotation started above
     pfnCmdEndDebugUtilsLabelEXT(commandBuffer);
 
     // Do other work
 
     vkEndCommandBuffer(commandBuffer);
 
     // Describe the queue being used
     const VkDebugUtilsLabelEXT queueLabel =
     {
         .sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT,
         .pNext = NULL,
         .pLabelName = "Main Render Work",
         .color = { 0.0f, 1.0f, 0.0f, 1.0f },
     };
 
     // Identify the queue label region
     pfnQueueBeginDebugUtilsLabelEXT(queue, &queueLabel);
 
     // Submit the work for the main render thread
     const VkCommandBuffer cmd_bufs[] = {commandBuffer};
     VkSubmitInfo submit_info =
     {
         .sType = VK_STRUCTURE_TYPE_SUBMIT_INFO,
         .pNext = NULL,
         .waitSemaphoreCount = 0,
         .pWaitSemaphores = NULL,
         .pWaitDstStageMask = NULL,
         .commandBufferCount = 1,
         .pCommandBuffers = cmd_bufs,
         .signalSemaphoreCount = 0,
         .pSignalSemaphores = NULL
     };
     vkQueueSubmit(queue, 1, &submit_info, fence);
 
     // End the queue label region
     pfnQueueEndDebugUtilsLabelEXT(queue);
Name String
VK_EXT_debug_utils
Extension Type
Instance extension
Registered Extension Number
129
Revision
2
Special Use
Contact
Other Extension Metadata
Last Modified Date
2020-04-03
Revision
2
IP Status
No known IP claims.
Dependencies
  • This extension is written against version 1.0 of the Vulkan API.
  • Requires VkObjectType
Contributors
  • Mark Young, LunarG
  • Baldur Karlsson
  • Ian Elliott, Google
  • Courtney Goeltzenleuchter, Google
  • Karl Schultz, LunarG
  • Mark Lobodzinski, LunarG
  • Mike Schuchardt, LunarG
  • Jaakko Konttinen, AMD
  • Dan Ginsburg, Valve Software
  • Rolando Olivares, Epic Games
  • Dan Baker, Oxide Games
  • Kyle Spagnoli, NVIDIA
  • Jon Ashburn, LunarG
  • Piers Daniell, NVIDIA

  • Field Details

  • Method Details

    • nvkSetDebugUtilsObjectNameEXT

      public static int nvkSetDebugUtilsObjectNameEXT(org.lwjgl.vulkan.VkDevice device, long pNameInfo)
      Unsafe version of: SetDebugUtilsObjectNameEXT

    • vkSetDebugUtilsObjectNameEXT

      public static int vkSetDebugUtilsObjectNameEXT(org.lwjgl.vulkan.VkDevice device, VkDebugUtilsObjectNameInfoEXT pNameInfo)
      Give an application-defined name to an object.
      C Specification

      An object can be given an application-defined name by calling:

      
 VkResult vkSetDebugUtilsObjectNameEXT(
     VkDevice                                    device,
     const VkDebugUtilsObjectNameInfoEXT*        pNameInfo);
      Valid Usage
      • pNameInfo→objectType must not be OBJECT_TYPE_UNKNOWN
      • pNameInfo→objectHandle must not be NULL_HANDLE
      • If pNameInfo→objectHandle is the valid handle of an instance-level object, the VkDevice identified by device must be a descendent of the same VkInstance as the object identified by pNameInfo→objectHandle
      • If pNameInfo→objectHandle is the valid handle of a physical-device-level object, the VkDevice identified by device must be a descendant of the same VkPhysicalDevice as the object identified by pNameInfo→objectHandle
      • If pNameInfo→objectHandle is the valid handle of a device-level object, that object must be a descendent of the VkDevice identified by device
      Valid Usage (Implicit)
      Host Synchronization
      • Host access to pNameInfo→objectHandle must be externally synchronized
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkDebugUtilsObjectNameInfoEXT

      Parameters:
      device - the device that is associated with the named object passed in via objectHandle.
      pNameInfo - a pointer to a VkDebugUtilsObjectNameInfoEXT structure specifying parameters of the name to set on the object.

    • nvkSetDebugUtilsObjectTagEXT

      public static int nvkSetDebugUtilsObjectTagEXT(org.lwjgl.vulkan.VkDevice device, long pTagInfo)
      Unsafe version of: SetDebugUtilsObjectTagEXT

    • vkSetDebugUtilsObjectTagEXT

      public static int vkSetDebugUtilsObjectTagEXT(org.lwjgl.vulkan.VkDevice device, VkDebugUtilsObjectTagInfoEXT pTagInfo)
      Attach arbitrary data to an object.
      C Specification
      
 VkResult vkSetDebugUtilsObjectTagEXT(
     VkDevice                                    device,
     const VkDebugUtilsObjectTagInfoEXT*         pTagInfo);
      Valid Usage
      • If pNameInfo→objectHandle is the valid handle of an instance-level object, the VkDevice identified by device must be a descendent of the same VkInstance as the object identified by pNameInfo→objectHandle
      • If pNameInfo→objectHandle is the valid handle of a physical-device-level object, the VkDevice identified by device must be a descendant of the same VkPhysicalDevice as the object identified by pNameInfo→objectHandle
      • If pNameInfo→objectHandle is the valid handle of a device-level object, that object must be a descendent of the VkDevice identified by device
      Valid Usage (Implicit)
      Host Synchronization
      • Host access to pTagInfo→objectHandle must be externally synchronized
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkDebugUtilsObjectTagInfoEXT

      Parameters:
      device - the device that created the object.
      pTagInfo - a pointer to a VkDebugUtilsObjectTagInfoEXT structure specifying parameters of the tag to attach to the object.

    • nvkQueueBeginDebugUtilsLabelEXT

      public static void nvkQueueBeginDebugUtilsLabelEXT(org.lwjgl.vulkan.VkQueue queue, long pLabelInfo)
      Unsafe version of: QueueBeginDebugUtilsLabelEXT

    • vkQueueBeginDebugUtilsLabelEXT

      public static void vkQueueBeginDebugUtilsLabelEXT(org.lwjgl.vulkan.VkQueue queue, VkDebugUtilsLabelEXT pLabelInfo)
      Open a queue debug label region.
      C Specification

      A queue debug label region is opened by calling:

      
 void vkQueueBeginDebugUtilsLabelEXT(
     VkQueue                                     queue,
     const VkDebugUtilsLabelEXT*                 pLabelInfo);
      Valid Usage (Implicit)
      • queue must be a valid VkQueue handle
      • pLabelInfo must be a valid pointer to a valid VkDebugUtilsLabelEXT structure
      Command Properties
      Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
      ---Any-
      See Also

      VkDebugUtilsLabelEXT

      Parameters:
      queue - the queue in which to start a debug label region.
      pLabelInfo - a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label region to open.

    • vkQueueEndDebugUtilsLabelEXT

      public static void vkQueueEndDebugUtilsLabelEXT(org.lwjgl.vulkan.VkQueue queue)
      Close a queue debug label region.
      C Specification

      A queue debug label region is closed by calling:

      
 void vkQueueEndDebugUtilsLabelEXT(
     VkQueue                                     queue);
      Description

      The calls to QueueBeginDebugUtilsLabelEXT and QueueEndDebugUtilsLabelEXT must be matched and balanced.

      Valid Usage
      • There must be an outstanding vkQueueBeginDebugUtilsLabelEXT command prior to the vkQueueEndDebugUtilsLabelEXT on the queue
      Valid Usage (Implicit)
      • queue must be a valid VkQueue handle
      Command Properties
      Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
      ---Any-
      Parameters:
      queue - the queue in which a debug label region should be closed.

    • nvkQueueInsertDebugUtilsLabelEXT

      public static void nvkQueueInsertDebugUtilsLabelEXT(org.lwjgl.vulkan.VkQueue queue, long pLabelInfo)
      Unsafe version of: QueueInsertDebugUtilsLabelEXT

    • vkQueueInsertDebugUtilsLabelEXT

      public static void vkQueueInsertDebugUtilsLabelEXT(org.lwjgl.vulkan.VkQueue queue, VkDebugUtilsLabelEXT pLabelInfo)
      Insert a label into a queue.
      C Specification

      A single label can be inserted into a queue by calling:

      
 void vkQueueInsertDebugUtilsLabelEXT(
     VkQueue                                     queue,
     const VkDebugUtilsLabelEXT*                 pLabelInfo);
      Valid Usage (Implicit)
      • queue must be a valid VkQueue handle
      • pLabelInfo must be a valid pointer to a valid VkDebugUtilsLabelEXT structure
      Command Properties
      Command Buffer LevelsRender Pass ScopeVideo Coding ScopeSupported Queue TypesCommand Type
      ---Any-
      See Also

      VkDebugUtilsLabelEXT

      Parameters:
      queue - the queue into which a debug label will be inserted.
      pLabelInfo - a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label to insert.

    • nvkCmdBeginDebugUtilsLabelEXT

      public static void nvkCmdBeginDebugUtilsLabelEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long pLabelInfo)
      Unsafe version of: CmdBeginDebugUtilsLabelEXT

    • vkCmdBeginDebugUtilsLabelEXT

      public static void vkCmdBeginDebugUtilsLabelEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, VkDebugUtilsLabelEXT pLabelInfo)
      Open a command buffer debug label region.
      C Specification

      A command buffer debug label region can be opened by calling:

      
 void vkCmdBeginDebugUtilsLabelEXT(
     VkCommandBuffer                             commandBuffer,
     const VkDebugUtilsLabelEXT*                 pLabelInfo);
      Valid Usage (Implicit)
      • commandBuffer must be a valid VkCommandBuffer handle
      • pLabelInfo must be a valid pointer to a valid VkDebugUtilsLabelEXT 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 State
      See Also

      VkDebugUtilsLabelEXT

      Parameters:
      commandBuffer - the command buffer into which the command is recorded.
      pLabelInfo - a pointer to a VkDebugUtilsLabelEXT structure specifying parameters of the label region to open.

    • vkCmdEndDebugUtilsLabelEXT

      public static void vkCmdEndDebugUtilsLabelEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer)
      Close a command buffer label region.
      C Specification

      A command buffer label region can be closed by calling:

      
 void vkCmdEndDebugUtilsLabelEXT(
     VkCommandBuffer                             commandBuffer);
      Description

      An application may open a debug label region in one command buffer and close it in another, or otherwise split debug label regions across multiple command buffers or multiple queue submissions. When viewed from the linear series of submissions to a single queue, the calls to CmdBeginDebugUtilsLabelEXT and CmdEndDebugUtilsLabelEXT must be matched and balanced.

      There can be problems reporting command buffer debug labels during the recording process because command buffers may be recorded out of sequence with the resulting execution order. Since the recording order may be different, a solitary command buffer may have an inconsistent view of the debug label regions by itself. Therefore, if an issue occurs during the recording of a command buffer, and the environment requires returning debug labels, the implementation may return only those labels it is aware of. This is true even if the implementation is aware of only the debug labels within the command buffer being actively recorded.

      Valid Usage
      • There must be an outstanding vkCmdBeginDebugUtilsLabelEXT command prior to the vkCmdEndDebugUtilsLabelEXT on the queue that commandBuffer is submitted to
      • If commandBuffer is a secondary command buffer, there must be an outstanding vkCmdBeginDebugUtilsLabelEXT command recorded to commandBuffer that has not previously been ended by a call to vkCmdEndDebugUtilsLabelEXT
      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 State
      Parameters:
      commandBuffer - the command buffer into which the command is recorded.

    • nvkCmdInsertDebugUtilsLabelEXT

      public static void nvkCmdInsertDebugUtilsLabelEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, long pLabelInfo)
      Unsafe version of: CmdInsertDebugUtilsLabelEXT

    • vkCmdInsertDebugUtilsLabelEXT

      public static void vkCmdInsertDebugUtilsLabelEXT(org.lwjgl.vulkan.VkCommandBuffer commandBuffer, VkDebugUtilsLabelEXT pLabelInfo)
      Insert a label into a command buffer.
      C Specification

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

      
 void vkCmdInsertDebugUtilsLabelEXT(
     VkCommandBuffer                             commandBuffer,
     const VkDebugUtilsLabelEXT*                 pLabelInfo);
      Valid Usage (Implicit)
      • commandBuffer must be a valid VkCommandBuffer handle
      • pLabelInfo must be a valid pointer to a valid VkDebugUtilsLabelEXT 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

      VkDebugUtilsLabelEXT

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

    • nvkCreateDebugUtilsMessengerEXT

      public static int nvkCreateDebugUtilsMessengerEXT(org.lwjgl.vulkan.VkInstance instance, long pCreateInfo, long pAllocator, long pMessenger)
      Unsafe version of: CreateDebugUtilsMessengerEXT

    • vkCreateDebugUtilsMessengerEXT

      public static int vkCreateDebugUtilsMessengerEXT(org.lwjgl.vulkan.VkInstance instance, VkDebugUtilsMessengerCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, LongBuffer pMessenger)
      Create a debug messenger object.
      C Specification

      A debug messenger triggers a debug callback with a debug message when an event of interest occurs. To create a debug messenger which will trigger a debug callback, call:

      
 VkResult vkCreateDebugUtilsMessengerEXT(
     VkInstance                                  instance,
     const VkDebugUtilsMessengerCreateInfoEXT*   pCreateInfo,
     const VkAllocationCallbacks*                pAllocator,
     VkDebugUtilsMessengerEXT*                   pMessenger);
      Valid Usage (Implicit)
      • instance must be a valid VkInstance handle
      • pCreateInfo must be a valid pointer to a valid VkDebugUtilsMessengerCreateInfoEXT structure
      • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
      • pMessenger must be a valid pointer to a VkDebugUtilsMessengerEXT handle
      Return Codes
      On success, this command returns
      On failure, this command returns

      The application must ensure that CreateDebugUtilsMessengerEXT is not executed in parallel with any Vulkan command that is also called with instance or child of instance as the dispatchable argument.

      See Also

      VkAllocationCallbacks, VkDebugUtilsMessengerCreateInfoEXT

      Parameters:
      instance - the instance the messenger will be used with.
      pCreateInfo - a pointer to a VkDebugUtilsMessengerCreateInfoEXT structure containing the callback pointer, as well as defining conditions under which this messenger will trigger the callback.
      pAllocator - controls host memory allocation as described in the Memory Allocation chapter.
      pMessenger - a pointer to a VkDebugUtilsMessengerEXT handle in which the created object is returned.

    • nvkDestroyDebugUtilsMessengerEXT

      public static void nvkDestroyDebugUtilsMessengerEXT(org.lwjgl.vulkan.VkInstance instance, long messenger, long pAllocator)
      Unsafe version of: DestroyDebugUtilsMessengerEXT

    • vkDestroyDebugUtilsMessengerEXT

      public static void vkDestroyDebugUtilsMessengerEXT(org.lwjgl.vulkan.VkInstance instance, long messenger, @Nullable VkAllocationCallbacks pAllocator)
      Destroy a debug messenger object.
      C Specification

      To destroy a VkDebugUtilsMessengerEXT object, call:

      
 void vkDestroyDebugUtilsMessengerEXT(
     VkInstance                                  instance,
     VkDebugUtilsMessengerEXT                    messenger,
     const VkAllocationCallbacks*                pAllocator);
      Valid Usage
      • If VkAllocationCallbacks were provided when messenger was created, a compatible set of callbacks must be provided here
      • If no VkAllocationCallbacks were provided when messenger was created, pAllocator must be NULL
      Valid Usage (Implicit)
      • instance must be a valid VkInstance handle
      • If messenger is not NULL_HANDLE, messenger must be a valid VkDebugUtilsMessengerEXT handle
      • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
      • If messenger is a valid handle, it must have been created, allocated, or retrieved from instance
      Host Synchronization
      • Host access to messenger must be externally synchronized

      The application must ensure that DestroyDebugUtilsMessengerEXT is not executed in parallel with any Vulkan command that is also called with instance or child of instance as the dispatchable argument.

      See Also

      VkAllocationCallbacks

      Parameters:
      instance - the instance where the callback was created.
      messenger - the VkDebugUtilsMessengerEXT object to destroy. messenger is an externally synchronized object and must not be used on more than one thread at a time. This means that vkDestroyDebugUtilsMessengerEXT must not be called when a callback is active.
      pAllocator - controls host memory allocation as described in the Memory Allocation chapter.

    • nvkSubmitDebugUtilsMessageEXT

      public static void nvkSubmitDebugUtilsMessageEXT(org.lwjgl.vulkan.VkInstance instance, int messageSeverity, int messageTypes, long pCallbackData)
      Unsafe version of: SubmitDebugUtilsMessageEXT

    • vkSubmitDebugUtilsMessageEXT

      public static void vkSubmitDebugUtilsMessageEXT(org.lwjgl.vulkan.VkInstance instance, int messageSeverity, int messageTypes, VkDebugUtilsMessengerCallbackDataEXT pCallbackData)
      Inject a message into a debug stream.
      C Specification

      To intentionally submit a debug message, call:

      
 void vkSubmitDebugUtilsMessageEXT(
     VkInstance                                  instance,
     VkDebugUtilsMessageSeverityFlagBitsEXT      messageSeverity,
     VkDebugUtilsMessageTypeFlagsEXT             messageTypes,
     const VkDebugUtilsMessengerCallbackDataEXT* pCallbackData);
      Description

      The call will propagate through the layers and generate callback(s) as indicated by the message’s flags. The parameters are passed on to the callback in addition to the pUserData value that was defined at the time the messenger was registered.

      Valid Usage
      • The objectType member of each element of pCallbackData→pObjects must not be OBJECT_TYPE_UNKNOWN
      Valid Usage (Implicit)
      • instance must be a valid VkInstance handle
      • messageSeverity must be a valid VkDebugUtilsMessageSeverityFlagBitsEXT value
      • messageTypes must be a valid combination of VkDebugUtilsMessageTypeFlagBitsEXT values
      • messageTypes must not be 0
      • pCallbackData must be a valid pointer to a valid VkDebugUtilsMessengerCallbackDataEXT structure
      See Also

      VkDebugUtilsMessengerCallbackDataEXT

      Parameters:
      instance - the debug stream’s VkInstance.
      messageSeverity - a VkDebugUtilsMessageSeverityFlagBitsEXT value specifying the severity of this event/message.
      messageTypes - a bitmask of VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of event(s) to identify with this message.
      pCallbackData - contains all the callback related data in the VkDebugUtilsMessengerCallbackDataEXT structure.

    • vkCreateDebugUtilsMessengerEXT

      public static int vkCreateDebugUtilsMessengerEXT(org.lwjgl.vulkan.VkInstance instance, VkDebugUtilsMessengerCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, long[] pMessenger)
      Array version of: CreateDebugUtilsMessengerEXT