Package org.lwjgl.vulkan

Class EXTDebugUtils

  • public class EXTDebugUtils
extends java.lang.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 = {
             VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,  // sType
             NULL,                                                     // pNext
             0,                                                        // flags
             VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT |           // messageSeverity
             VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,
             VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |             // messageType
             VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
             myOutputDebugString,                                      // pfnUserCallback
             NULL                                                      // pUserData
     };
     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 = {
             VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT,  // sType
             NULL,                                                     // pNext
             0,                                                        // flags
             VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT,          // messageSeverity
             VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT |             // messageType
             VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT,
             mystdOutLogger,                                           // pfnUserCallback
             NULL                                                      // pUserData
     };
     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 =
     {
         VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, // sType
         NULL,                                               // pNext
         VK_OBJECT_TYPE_IMAGE,                               // objectType
         (uint64_t)image,                                    // objectHandle
         "Brick Diffuse Texture",                            // pObjectName
     };
 
     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 =
     {
         VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
         NULL,                                    // pNext
         "Brick House",                           // pLabelName
         { 1.0f, 0.0f, 0.0f, 1.0f },              // color
     };
 
     // Start an annotated group of calls under the 'Brick House' name
     pfnCmdBeginDebugUtilsLabelEXT(commandBuffer, &houseLabel);
     {
         // A mutable structure for each part being rendered
         VkDebugUtilsLabelEXT housePartLabel =
         {
             VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
             NULL,                                    // pNext
             NULL,                                    // pLabelName
             { 0.0f, 0.0f, 0.0f, 0.0f },              // color
         };
 
         // 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 =
     {
         VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, // sType
         NULL,                                    // pNext
         "Main Render Work",                      // pLabelName
         { 0.0f, 1.0f, 0.0f, 1.0f },              // color
     };
 
     // 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);
    VK_EXT_debug_utils
    Name String
    VK_EXT_debug_utils
    Extension Type
    Instance extension
    Registered Extension Number
    129
    Revision
    2
    Extension and Version Dependencies
    • Requires Vulkan 1.0
    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

    • Method Detail

      • 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 a user-friendly name to an object.
        C Specification
        
 VkResult vkSetDebugUtilsObjectNameEXT(
     VkDevice                                    device,
     const VkDebugUtilsObjectNameInfoEXT*        pNameInfo);
        Valid Usage
        Valid Usage (Implicit)
        Host Synchronization
        • Host access to pNameInfo\u2192objectHandle must be externally synchronized
        Return Codes
        On success, this command returns
        On failure, this command returns
        See Also

        VkDebugUtilsObjectNameInfoEXT

        Parameters:
        device - the device that created the object.
        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 (Implicit)
        Host Synchronization
        • Host access to pTagInfo\u2192objectHandle 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 ScopeSupported Queue Types
        --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 ScopeSupported Queue Types
        --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 ScopeSupported Queue Types
        --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
        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 ScopeSupported Queue Types
        Primary SecondaryBothGraphics Compute
        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
        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 ScopeSupported Queue Types
        Primary SecondaryBothGraphics Compute
        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
        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 ScopeSupported Queue Types
        Primary SecondaryBothGraphics Compute
        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,
                                                 java.nio.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

        There may be times that a user wishes to intentionally submit a debug message. To do this, 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\u2192pObjects 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.