Class EXTDebugMarker
- java.lang.Object
-
- org.lwjgl.vulkan.EXTDebugMarker
-
public class EXTDebugMarker extends java.lang.Object
TheVK_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
- Requires Vulkan 1.0
- Requires
VK_EXT_debug_report
- Deprecation state
- Promoted to VK_EXT_debug_utils extension
- Contact
- Baldur Karlsson baldurk
- 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 Summary
Fields Modifier and Type Field Description static java.lang.String
VK_EXT_DEBUG_MARKER_EXTENSION_NAME
The extension name.static int
VK_EXT_DEBUG_MARKER_SPEC_VERSION
The extension specification version.static int
VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXTExtendsVkStructureType
.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
nvkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)
Unsafe version of:CmdDebugMarkerBeginEXT
static void
nvkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)
Unsafe version of:CmdDebugMarkerInsertEXT
static int
nvkDebugMarkerSetObjectNameEXT(VkDevice device, long pNameInfo)
Unsafe version of:DebugMarkerSetObjectNameEXT
static int
nvkDebugMarkerSetObjectTagEXT(VkDevice device, long pTagInfo)
Unsafe version of:DebugMarkerSetObjectTagEXT
static void
vkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer, VkDebugMarkerMarkerInfoEXT pMarkerInfo)
Open a command buffer marker region.static void
vkCmdDebugMarkerEndEXT(VkCommandBuffer commandBuffer)
Close a command buffer marker region.static void
vkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer, VkDebugMarkerMarkerInfoEXT pMarkerInfo)
Insert a marker label into a command buffer.static int
vkDebugMarkerSetObjectNameEXT(VkDevice device, VkDebugMarkerObjectNameInfoEXT pNameInfo)
Give a user-friendly name to an object.static int
vkDebugMarkerSetObjectTagEXT(VkDevice device, VkDebugMarkerObjectTagInfoEXT pTagInfo)
Attach arbitrary data to an object.
-
-
-
Field Detail
-
VK_EXT_DEBUG_MARKER_SPEC_VERSION
The extension specification version.
-
VK_EXT_DEBUG_MARKER_EXTENSION_NAME
The extension name.
-
VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT, VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT
ExtendsVkStructureType
.Enum values:
-
-
Method Detail
-
nvkDebugMarkerSetObjectTagEXT
public static int nvkDebugMarkerSetObjectTagEXT(VkDevice device, long pTagInfo)
Unsafe version of:DebugMarkerSetObjectTagEXT
-
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)
device
must be a validVkDevice
handlepTagInfo
must be a valid pointer to a validVkDebugMarkerObjectTagInfoEXT
structure
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
- Parameters:
device
- the device that created the object.pTagInfo
- a pointer to an instance of theVkDebugMarkerObjectTagInfoEXT
structure specifying the parameters of the tag to attach to the object.
-
nvkDebugMarkerSetObjectNameEXT
public static int nvkDebugMarkerSetObjectNameEXT(VkDevice device, long pNameInfo)
Unsafe version of:DebugMarkerSetObjectNameEXT
-
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)
device
must be a validVkDevice
handlepNameInfo
must be a valid pointer to a validVkDebugMarkerObjectNameInfoEXT
structure
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
- Parameters:
device
- the device that created the object.pNameInfo
- a pointer to an instance of theVkDebugMarkerObjectNameInfoEXT
structure specifying the parameters of the name to set on the object.
-
nvkCmdDebugMarkerBeginEXT
public static void nvkCmdDebugMarkerBeginEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)
Unsafe version of:CmdDebugMarkerBeginEXT
-
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 validVkCommandBuffer
handlepMarkerInfo
must be a valid pointer to a validVkDebugMarkerMarkerInfoEXT
structurecommandBuffer
must be in the recording state- The
VkCommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations
Host Synchronization
- Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type Primary Secondary Both Graphics Compute See Also
- Parameters:
commandBuffer
- the command buffer into which the command is recorded.pMarkerInfo
- a pointer to an instance of theVkDebugMarkerMarkerInfoEXT
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
andvkCmdDebugMarkerEndEXT
must be matched and balanced.Valid Usage
- There must be an outstanding
CmdDebugMarkerBeginEXT
command prior to thevkCmdDebugMarkerEndEXT
on the queue thatcommandBuffer
is submitted to - If
commandBuffer
is a secondary command buffer, there must be an outstandingCmdDebugMarkerBeginEXT
command recorded tocommandBuffer
that has not previously been ended by a call toCmdDebugMarkerEndEXT
.
Valid Usage (Implicit)
commandBuffer
must be a validVkCommandBuffer
handlecommandBuffer
must be in the recording state- The
VkCommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations
Host Synchronization
- Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type Primary Secondary Both Graphics Compute - Parameters:
commandBuffer
- the command buffer into which the command is recorded.
- There must be an outstanding
-
nvkCmdDebugMarkerInsertEXT
public static void nvkCmdDebugMarkerInsertEXT(VkCommandBuffer commandBuffer, long pMarkerInfo)
Unsafe version of:CmdDebugMarkerInsertEXT
-
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 validVkCommandBuffer
handlepMarkerInfo
must be a valid pointer to a validVkDebugMarkerMarkerInfoEXT
structurecommandBuffer
must be in the recording state- The
VkCommandPool
thatcommandBuffer
was allocated from must support graphics, or compute operations
Host Synchronization
- Host access to the
VkCommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type Primary Secondary Both Graphics Compute See Also
- Parameters:
commandBuffer
- the command buffer into which the command is recorded.pMarkerInfo
- a pointer to an instance of theVkDebugMarkerMarkerInfoEXT
structure specifying the parameters of the marker to insert.
-
-