Class EXTDebugUtils
- java.lang.Object
-
- org.lwjgl.vulkan.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 theVK_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
orVkCommandBuffer
using labels to aid organization and offline analysis in external tools.
The main difference between this extension and
VK_EXT_debug_report
andVK_EXT_debug_marker
is that those extensions useVkDebugReportObjectTypeEXT
to identify objects. This extension uses the coreVkObjectType
in place ofVkDebugReportObjectTypeEXT
. The primary reason for this move is that no future object type handle enumeration values will be added toVkDebugReportObjectTypeEXT
since the creation ofVkObjectType
.In addition, this extension combines the functionality of both
VK_EXT_debug_report
andVK_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 thepNext
element of theVkInstanceCreateInfo
structure given toCreateInstance
. This callback is only valid for the duration of theCreateInstance
and theDestroyInstance
call. UseCreateDebugUtilsMessengerEXT
to create persistent callback objects.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)vkGetDeviceProcAddr(device, "vkCreateDebugUtilsMessengerEXT"); PFN_vkDestroyDebugUtilsMessengerEXT pfnDestroyDebugUtilsMessengerEXT = (PFN_vkDestroyDebugUtilsMessengerEXT)vkGetDeviceProcAddr(device, "vkDestroyDebugUtilsMessengerEXT"); VkDebugUtilsMessengeCreateInfoEXT 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.pfnCallback = 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 VkDevice device; extern VkImage image; // Must call extension functions through a function pointer: PFN_vkSetDebugUtilsObjectNameEXT pfnSetDebugUtilsObjectNameEXT = (PFN_vkSetDebugUtilsObjectNameEXT)vkGetDeviceProcAddr(device, "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, // object "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 VkDevice device; extern VkCommandBuffer commandBuffer; // Must call extension functions through a function pointer: PFN_vkQueueBeginDebugUtilsLabelEXT pfnQueueBeginDebugUtilsLabelEXT = (PFN_vkQueueBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueBeginDebugUtilsLabelEXT"); PFN_vkQueueEndDebugUtilsLabelEXT pfnQueueEndDebugUtilsLabelEXT = (PFN_vkQueueEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkQueueEndDebugUtilsLabelEXT"); PFN_vkCmdBeginDebugUtilsLabelEXT pfnCmdBeginDebugUtilsLabelEXT = (PFN_vkCmdBeginDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdBeginDebugUtilsLabelEXT"); PFN_vkCmdEndDebugUtilsLabelEXT pfnCmdEndDebugUtilsLabelEXT = (PFN_vkCmdEndDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "vkCmdEndDebugUtilsLabelEXT"); PFN_vkCmdInsertDebugUtilsLabelEXT pfnCmdInsertDebugUtilsLabelEXT = (PFN_vkCmdInsertDebugUtilsLabelEXT)vkGetDeviceProcAddr(device, "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);
- Name String
VK_EXT_debug_utils
- Extension Type
- Instance extension
- Registered Extension Number
- 129
- Revision
- 1
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Contact
- Mark Young marky-lunarg
- Last Modified Date
- 2017-09-14
- Revision
- 1
- 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
-
-
Field Summary
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
nvkCmdBeginDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, long pLabelInfo)
Unsafe version of:CmdBeginDebugUtilsLabelEXT
static void
nvkCmdInsertDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, long pLabelInfo)
Unsafe version of:CmdInsertDebugUtilsLabelEXT
static int
nvkCreateDebugUtilsMessengerEXT(VkInstance instance, long pCreateInfo, long pAllocator, long pMessenger)
Unsafe version of:CreateDebugUtilsMessengerEXT
static void
nvkDestroyDebugUtilsMessengerEXT(VkInstance instance, long messenger, long pAllocator)
Unsafe version of:DestroyDebugUtilsMessengerEXT
static void
nvkQueueBeginDebugUtilsLabelEXT(VkQueue queue, long pLabelInfo)
Unsafe version of:QueueBeginDebugUtilsLabelEXT
static void
nvkQueueInsertDebugUtilsLabelEXT(VkQueue queue, long pLabelInfo)
Unsafe version of:QueueInsertDebugUtilsLabelEXT
static int
nvkSetDebugUtilsObjectNameEXT(VkDevice device, long pNameInfo)
Unsafe version of:SetDebugUtilsObjectNameEXT
static int
nvkSetDebugUtilsObjectTagEXT(VkDevice device, long pTagInfo)
Unsafe version of:SetDebugUtilsObjectTagEXT
static void
nvkSubmitDebugUtilsMessageEXT(VkInstance instance, int messageSeverity, int messageTypes, long pCallbackData)
Unsafe version of:SubmitDebugUtilsMessageEXT
static void
vkCmdBeginDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, VkDebugUtilsLabelEXT pLabelInfo)
Open a command buffer debug label region.static void
vkCmdEndDebugUtilsLabelEXT(VkCommandBuffer commandBuffer)
Close a command buffer label region.static void
vkCmdInsertDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, VkDebugUtilsLabelEXT pLabelInfo)
Insert a label into a command buffer.static int
vkCreateDebugUtilsMessengerEXT(VkInstance instance, VkDebugUtilsMessengerCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, long[] pMessenger)
Array version of:CreateDebugUtilsMessengerEXT
static int
vkCreateDebugUtilsMessengerEXT(VkInstance instance, VkDebugUtilsMessengerCreateInfoEXT pCreateInfo, VkAllocationCallbacks pAllocator, java.nio.LongBuffer pMessenger)
Create a debug messenger object.static void
vkDestroyDebugUtilsMessengerEXT(VkInstance instance, long messenger, VkAllocationCallbacks pAllocator)
Destroy a debug messenger object.static void
vkQueueBeginDebugUtilsLabelEXT(VkQueue queue, VkDebugUtilsLabelEXT pLabelInfo)
Open a queue debug label region.static void
vkQueueEndDebugUtilsLabelEXT(VkQueue queue)
Close a queue debug label region.static void
vkQueueInsertDebugUtilsLabelEXT(VkQueue queue, VkDebugUtilsLabelEXT pLabelInfo)
Insert a label into a queue.static int
vkSetDebugUtilsObjectNameEXT(VkDevice device, VkDebugUtilsObjectNameInfoEXT pNameInfo)
Give a user-friendly name to an object.static int
vkSetDebugUtilsObjectTagEXT(VkDevice device, VkDebugUtilsObjectTagInfoEXT pTagInfo)
Attach arbitrary data to an object.static void
vkSubmitDebugUtilsMessageEXT(VkInstance instance, int messageSeverity, int messageTypes, VkDebugUtilsMessengerCallbackDataEXT pCallbackData)
Inject a message into a debug stream.
-
-
-
Field Detail
-
VK_EXT_DEBUG_UTILS_SPEC_VERSION
The extension specification version.
-
VK_EXT_DEBUG_UTILS_EXTENSION_NAME
The extension name.
-
VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT, VK_STRUCTURE_TYPE_DEBUG_UTILS_OBJECT_TAG_INFO_EXT, VK_STRUCTURE_TYPE_DEBUG_UTILS_LABEL_EXT, VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT, VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
-
VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT
ExtendsVkObjectType
.
-
VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT, VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT, VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT, VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT
VkDebugUtilsMessageSeverityFlagBitsEXT - Bitmask specifying which severities of events cause a debug messenger callbackDescription
DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT
specifies the most verbose output indicating all diagnostic messages from the Vulkan loader, layers, and drivers should be captured.DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT
specifies an informational message such as resource details that may be handy when debugging an application.DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT
specifies use of Vulkan that may expose an app bug. Such cases may not be immediately harmful, such as a fragment shader outputting to a location with no attachment. Other cases may point to behavior that is almost certainly bad when unintended such as using an image whose memory has not been filled. In general if you see a warning but you know that the behavior is intended/desired, then simply ignore the warning.DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT
specifies that the application has violated a valid usage condition of the specification.
See Also
VkDebugUtilsMessageSeverityFlagsEXT
,SubmitDebugUtilsMessageEXT
-
VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT, VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT, VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
VkDebugUtilsMessageTypeFlagBitsEXT - Bitmask specifying which types of events cause a debug messenger callbackDescription
DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT
specifies that some general event has occurred. This is typically a non-specification, non-performance event.DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
specifies that something has occurred during validation against the Vulkan specification that may indicate invalid behavior.DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
specifies a potentially non-optimal use of Vulkan, e.g. usingCmdClearColorImage
when settingVkAttachmentDescription
::loadOp
toATTACHMENT_LOAD_OP_CLEAR
would have worked.
See Also
VkDebugUtilsMessageTypeFlagsEXT
-
-
Method Detail
-
nvkSetDebugUtilsObjectNameEXT
public static int nvkSetDebugUtilsObjectNameEXT(VkDevice device, long pNameInfo)
Unsafe version of:SetDebugUtilsObjectNameEXT
-
vkSetDebugUtilsObjectNameEXT
public static int vkSetDebugUtilsObjectNameEXT(VkDevice device, VkDebugUtilsObjectNameInfoEXT pNameInfo)
Give a user-friendly name to an object.C Specification
VkResult vkSetDebugUtilsObjectNameEXT( VkDevice device, const VkDebugUtilsObjectNameInfoEXT* pNameInfo);
Valid Usage
pNameInfo
->objectType
must not beOBJECT_TYPE_UNKNOWN
pNameInfo
->objectHandle
must not beNULL_HANDLE
Valid Usage (Implicit)
device
must be a validVkDevice
handlepNameInfo
must be a valid pointer to a validVkDebugUtilsObjectNameInfoEXT
structure
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
- Parameters:
device
- the device that created the object.pNameInfo
- a pointer to an instance of theVkDebugUtilsObjectNameInfoEXT
structure specifying the parameters of the name to set on the object.
-
nvkSetDebugUtilsObjectTagEXT
public static int nvkSetDebugUtilsObjectTagEXT(VkDevice device, long pTagInfo)
Unsafe version of:SetDebugUtilsObjectTagEXT
-
vkSetDebugUtilsObjectTagEXT
public static int vkSetDebugUtilsObjectTagEXT(VkDevice device, VkDebugUtilsObjectTagInfoEXT pTagInfo)
Attach arbitrary data to an object.C Specification
VkResult vkSetDebugUtilsObjectTagEXT( VkDevice device, const VkDebugUtilsObjectTagInfoEXT* pTagInfo);
Valid Usage (Implicit)
device
must be a validVkDevice
handlepTagInfo
must be a valid pointer to a validVkDebugUtilsObjectTagInfoEXT
structure
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
- Parameters:
device
- the device that created the object.pTagInfo
- a pointer to an instance of theVkDebugUtilsObjectTagInfoEXT
structure specifying the parameters of the tag to attach to the object.
-
nvkQueueBeginDebugUtilsLabelEXT
public static void nvkQueueBeginDebugUtilsLabelEXT(VkQueue queue, long pLabelInfo)
Unsafe version of:QueueBeginDebugUtilsLabelEXT
-
vkQueueBeginDebugUtilsLabelEXT
public static void vkQueueBeginDebugUtilsLabelEXT(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 validVkQueue
handlepLabelInfo
must be a valid pointer to a validVkDebugUtilsLabelEXT
structure
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type - - Any - See Also
- Parameters:
queue
- the queue in which to start a debug label region.pLabelInfo
- a pointer to an instance of theVkDebugUtilsLabelEXT
structure specifying the parameters of the label region to open.
-
vkQueueEndDebugUtilsLabelEXT
public static void vkQueueEndDebugUtilsLabelEXT(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
andQueueEndDebugUtilsLabelEXT
must be matched and balanced.Valid Usage
- There must be an outstanding
vkQueueBeginDebugUtilsLabelEXT
command prior to thevkQueueEndDebugUtilsLabelEXT
on the queue
Valid Usage (Implicit)
queue
must be a validVkQueue
handle
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type - - Any - - Parameters:
queue
- the queue in which a debug label region should be closed.
- There must be an outstanding
-
nvkQueueInsertDebugUtilsLabelEXT
public static void nvkQueueInsertDebugUtilsLabelEXT(VkQueue queue, long pLabelInfo)
Unsafe version of:QueueInsertDebugUtilsLabelEXT
-
vkQueueInsertDebugUtilsLabelEXT
public static void vkQueueInsertDebugUtilsLabelEXT(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 validVkQueue
handlepLabelInfo
must be a valid pointer to a validVkDebugUtilsLabelEXT
structure
Command Properties
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type - - Any - See Also
- Parameters:
queue
- the queue into which a debug label will be inserted.pLabelInfo
- a pointer to an instance of theVkDebugUtilsLabelEXT
structure specifying the parameters of the label to insert.
-
nvkCmdBeginDebugUtilsLabelEXT
public static void nvkCmdBeginDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, long pLabelInfo)
Unsafe version of:CmdBeginDebugUtilsLabelEXT
-
vkCmdBeginDebugUtilsLabelEXT
public static void vkCmdBeginDebugUtilsLabelEXT(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 validVkCommandBuffer
handlepLabelInfo
must be a valid pointer to a validVkDebugUtilsLabelEXT
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.pLabelInfo
- a pointer to an instance of theVkDebugUtilsLabelEXT
structure specifying the parameters of the label region to open.
-
vkCmdEndDebugUtilsLabelEXT
public static void vkCmdEndDebugUtilsLabelEXT(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
andCmdEndDebugUtilsLabelEXT
must be matched and balanced.Valid Usage
- There must be an outstanding
vkCmdBeginDebugUtilsLabelEXT
command prior to thevkCmdEndDebugUtilsLabelEXT
on the queue thatcommandBuffer
is submitted to - If
commandBuffer
is a secondary command buffer, there must be an outstandingvkCmdBeginDebugUtilsLabelEXT
command recorded tocommandBuffer
that has not previously been ended by a call tovkCmdEndDebugUtilsLabelEXT
.
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
-
nvkCmdInsertDebugUtilsLabelEXT
public static void nvkCmdInsertDebugUtilsLabelEXT(VkCommandBuffer commandBuffer, long pLabelInfo)
Unsafe version of:CmdInsertDebugUtilsLabelEXT
-
vkCmdInsertDebugUtilsLabelEXT
public static void vkCmdInsertDebugUtilsLabelEXT(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 validVkCommandBuffer
handlepLabelInfo
must be a valid pointer to a validVkDebugUtilsLabelEXT
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.
-
nvkCreateDebugUtilsMessengerEXT
public static int nvkCreateDebugUtilsMessengerEXT(VkInstance instance, long pCreateInfo, long pAllocator, long pMessenger)
Unsafe version of:CreateDebugUtilsMessengerEXT
-
vkCreateDebugUtilsMessengerEXT
public static int vkCreateDebugUtilsMessengerEXT(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 validVkInstance
handlepCreateInfo
must be a valid pointer to a validVkDebugUtilsMessengerCreateInfoEXT
structure- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure pMessenger
must be a valid pointer to aVkDebugUtilsMessengerEXT
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 withinstance
or child ofinstance
as the dispatchable argument.See Also
- Parameters:
instance
- the instance the messenger will be used with.pCreateInfo
- points to aVkDebugUtilsMessengerCreateInfoEXT
structure which contains the callback pointer as well as defines the 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 record theVkDebugUtilsMessengerEXT
object created.
-
nvkDestroyDebugUtilsMessengerEXT
public static void nvkDestroyDebugUtilsMessengerEXT(VkInstance instance, long messenger, long pAllocator)
Unsafe version of:DestroyDebugUtilsMessengerEXT
-
vkDestroyDebugUtilsMessengerEXT
public static void vkDestroyDebugUtilsMessengerEXT(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 whenmessenger
was created, a compatible set of callbacks must be provided here - If no
VkAllocationCallbacks
were provided whenmessenger
was created,pAllocator
must beNULL
Valid Usage (Implicit)
instance
must be a validVkInstance
handlemessenger
must be a validVkDebugUtilsMessengerEXT
handle- If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validVkAllocationCallbacks
structure messenger
must have been created, allocated, or retrieved frominstance
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 withinstance
or child ofinstance
as the dispatchable argument.See Also
- Parameters:
instance
- the instance where the callback was created.messenger
- theVkDebugUtilsMessengerEXT
object to destroy.messenger
is an externally synchronized object and must not be used on more than one thread at a time. This means thatvkDestroyDebugUtilsMessengerEXT
must not be called when a callback is active.pAllocator
- controls host memory allocation as described in the Memory Allocation chapter.
- If
-
nvkSubmitDebugUtilsMessageEXT
public static void nvkSubmitDebugUtilsMessageEXT(VkInstance instance, int messageSeverity, int messageTypes, long pCallbackData)
Unsafe version of:SubmitDebugUtilsMessageEXT
-
vkSubmitDebugUtilsMessageEXT
public static void vkSubmitDebugUtilsMessageEXT(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
objectType
member of each element ofpCallbackData
->pObjects
must not beOBJECT_TYPE_UNKNOWN
Valid Usage (Implicit)
instance
must be a validVkInstance
handlemessageSeverity
must be a validVkDebugUtilsMessageSeverityFlagBitsEXT
valuemessageTypes
must be a valid combination ofVkDebugUtilsMessageTypeFlagBitsEXT
valuesmessageTypes
must not be 0pCallbackData
must be a valid pointer to a validVkDebugUtilsMessengerCallbackDataEXT
structure
See Also
- Parameters:
instance
- the debug stream’sVkInstance
.messageSeverity
- theVkDebugUtilsMessageSeverityFlagBitsEXT
severity of this event/message.messageTypes
- a bitmask ofVkDebugUtilsMessageTypeFlagBitsEXT
specifying which type of event(s) to identify with this message.pCallbackData
- contains all the callback related data in theVkDebugUtilsMessengerCallbackDataEXT
structure.
-
vkCreateDebugUtilsMessengerEXT
public static int vkCreateDebugUtilsMessengerEXT(VkInstance instance, VkDebugUtilsMessengerCreateInfoEXT pCreateInfo, @Nullable VkAllocationCallbacks pAllocator, long[] pMessenger)
Array version of:CreateDebugUtilsMessengerEXT
-
-