Package org.lwjgl.vulkan

Class EXTDebugMarker


  • public class EXTDebugMarker
extends java.lang.Object
    This extension 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 organisation and offline analysis in external tools.

    The VK_EXT_debug_marker extension is a device extension.

    Given the complexity of Vulkan there is a strong need for verbose debugging information to aid the application developer in tracking down errors in the application's use of Vulkan, particularly in combination with an external debugger or profiler.

    Object Annotation allows the application to associate a name or binary data with a Vulkan object, while command buffer markers provide the developer with a way of associating logical elements of the scene with commands in the command buffer.

    • Field Detail

      • VK_EXT_DEBUG_MARKER_SPEC_VERSION

        public static final int VK_EXT_DEBUG_MARKER_SPEC_VERSION
        The extension specification version.
        See Also:
        Constant Field Values

      • VK_EXT_DEBUG_MARKER_EXTENSION_NAME

        public static final java.lang.String VK_EXT_DEBUG_MARKER_EXTENSION_NAME
        The extension name.
        See Also:
        Constant Field Values

      • VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT

        public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT
        VkStructureType
        See Also:
        Constant Field Values

      • VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT

        public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT
        VkStructureType
        See Also:
        Constant Field Values

      • VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT

        public static final int VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT
        VkStructureType
        See Also:
        Constant Field Values

    • Method Detail

      • vkDebugMarkerSetObjectNameEXT

        public static int vkDebugMarkerSetObjectNameEXT(VkDevice device,
                                                VkDebugMarkerObjectNameInfoEXT pNameInfo)
        Gives a user-friendly name to a Vulkan object.

        Applications may change the name associated with an object simply by calling vkDebugMarkerSetObjectNameEXT again with a new string. To remove a previously set name, pName should be set to an empty string.

        Valid Usage
        • device must be a valid VkDevice handle
        • pNameInfo must be a pointer to a VkDebugMarkerObjectNameInfoEXT structure
        • pNameInfo.object must be a Vulkan object
        Host Synchronization
        • Host access to pNameInfo.object must be externally synchronized
        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

      • vkDebugMarkerSetObjectTagEXT

        public static int vkDebugMarkerSetObjectTagEXT(VkDevice device,
                                               VkDebugMarkerObjectTagInfoEXT pTagInfo)
        Attaches arbitrary data to a Vulkan object.

        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.

        The tagName parameter gives a name or identifier to the type of data being tagged. This can be used by debugging layers to easily filter for only data that can be used by that implementation.

        Valid Usage
        • device must be a valid VkDevice handle
        • pTagInfo must be a pointer to a VkDebugMarkerObjectTagInfoEXT structure
        • pTagInfo.object must be a Vulkan object
        • pTagInfo.tagName must not be 0
        Host Synchronization
        • Host access to pTagInfo.object must be externally synchronized
        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

      • vkCmdDebugMarkerBeginEXT

        public static void vkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer,
                                            VkDebugMarkerMarkerInfoEXT pMarkerInfo)
        Opens a marker region.

        Typical Vulkan applications will submit many command buffers in each frame, with each command buffer containing a large number of individual commands. Being able to logically annotate regions of command buffers that belong together as well as hierarchically subdivide the frame is important to a developer's ability to navigate the commands viewed holistically.

        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 CmdDebugMarkerEndEXT must be matched and balanced.

        Any calls to vkCmdDebugMarkerBeginEXT within a secondary command buffer must have a matching CmdDebugMarkerEndEXT in that same command buffer, and marker regions begun outside of the secondary command buffer must not be ended inside it.

        Valid Usage
        • commandBuffer must be a valid VkCommandBuffer handle
        • pMarkerInfo must be a pointer to a VkDebugMarkerMarkerInfoEXT structure
        • commandBuffer must be in the recording state
        • The VkCommandPool that commandBuffer was allocated from must support graphics or compute operations
        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)
        Closes a marker region.
        Valid Usage
        • 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
        • There must be an outstanding CmdDebugMarkerBeginEXT command prior to the CmdDebugMarkerEndEXT on the queue that commandBuffer is submitted to.
        • If the matching CmdDebugMarkerBeginEXT command was in a secondary command buffer, the CmdDebugMarkerEndEXT must be in the same commandBuffer.
        Parameters:
        commandBuffer - the command buffer handle

      • vkCmdDebugMarkerInsertEXT

        public static void vkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer,
                                             VkDebugMarkerMarkerInfoEXT pMarkerInfo)
        Inserts a single marker label into a command buffer.
        Valid Usage
        • commandBuffer must be a valid VkCommandBuffer handle
        • pMarkerInfo must be a pointer to a VkDebugMarkerMarkerInfoEXT structure
        • commandBuffer must be in the recording state
        • The VkCommandPool that commandBuffer was allocated from must support graphics or compute operations
        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