Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Name
VK_EXT_debug_utils - instance extension
VK_EXT_debug_utils
- Name String
VK_EXT_debug_utils
- Extension Type
- Instance extension
- Registered Extension Number
- 129
- Revision
- 2
- Ratification Status
- Not ratified
- Extension and Version Dependencies; 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
ObjectType
- 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
Description
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
Queue
orCommandBuffer
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
DebugReportObjectTypeEXT
to
identify objects. This extension uses the core
ObjectType
in place of
DebugReportObjectTypeEXT
. The
primary reason for this move is that no future object type handle
enumeration values will be added to
DebugReportObjectTypeEXT
since
the creation of ObjectType
.
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 Queue
or
CommandBuffer
the message occurred.
New Object Types
New Commands
cmdEndDebugUtilsLabelEXT
cmdInsertDebugUtilsLabelEXT
createDebugUtilsMessengerEXT
destroyDebugUtilsMessengerEXT
queueBeginDebugUtilsLabelEXT
queueEndDebugUtilsLabelEXT
queueInsertDebugUtilsLabelEXT
setDebugUtilsObjectNameEXT
setDebugUtilsObjectTagEXT
submitDebugUtilsMessageEXT
New Structures
DebugUtilsMessengerCallbackDataEXT
DebugUtilsObjectTagInfoEXT
Extending
InstanceCreateInfo
:Extending
PipelineShaderStageCreateInfo
:
New Function Pointers
New Enums
New Bitmasks
DebugUtilsMessageTypeFlagsEXT
DebugUtilsMessengerCallbackDataFlagsEXT
DebugUtilsMessengerCreateFlagsEXT
New Enum Constants
EXT_DEBUG_UTILS_SPEC_VERSION
Extending
ObjectType
:Extending
StructureType
:
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 DebugUtilsMessengerCreateInfoEXT
structure to
the pNext
element of the
InstanceCreateInfo
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);
Issues
1) Should we just name this extension VK_EXT_debug_report2
RESOLVED: No. There is enough additional changes to the structures to break backwards compatibility. So, a new name was decided that would not indicate any interaction with the previous extension.
2) Will validation layers immediately support all the new features.
RESOLVED: Not immediately. As one can imagine, there is a lot of
work involved with converting the validation layer logging over to the
new functionality. Basic logging, as seen in the origin
VK_EXT_debug_report
extension will be made available immediately.
However, adding the labels and object names will take time. Since the
priority for Khronos at this time is to continue focusing on Valid Usage
statements, it may take a while before the new functionality is fully
exposed.
3) If the validation layers will not expose the new functionality immediately, then what is the point of this extension?
RESOLVED: We needed a replacement for VK_EXT_debug_report
because
the DebugReportObjectTypeEXT
enumeration will no longer be updated and any new objects will need to
be debugged using the new functionality provided by this extension.
4) Should this extension be split into two separate parts (1 extension that is an instance extension providing the callback functionality, and another device extension providing the general debug marker and annotation functionality)?
RESOLVED: No, the functionality for this extension is too closely
related. If we did split up the extension, where would the structures
and enums live, and how would you define that the device behavior in the
instance extension is really only valid if the device extension is
enabled, and the functionality is passed in. It is cleaner to just
define this all as an instance extension, plus it allows the application
to enable all debug functionality provided with one enable string during
createInstance
.
Version History
Revision 1, 2017-09-14 (Mark Young and all listed Contributors)
- Initial draft, based on
VK_EXT_debug_report
andVK_EXT_debug_marker
in addition to previous feedback supplied from various companies including Valve, Epic, and Oxide games.
- Initial draft, based on
Revision 2, 2020-04-03 (Mark Young and Piers Daniell)
- Updated to allow either
NULL
or an empty string to be passed in forpObjectName
inDebugUtilsObjectNameInfoEXT
, because the loader and various drivers supportNULL
already.
- Updated to allow either
See Also
PFN_vkDebugUtilsMessengerCallbackEXT
, DebugUtilsLabelEXT
,
DebugUtilsMessageSeverityFlagBitsEXT
,
DebugUtilsMessageSeverityFlagsEXT
, DebugUtilsMessageTypeFlagBitsEXT
,
DebugUtilsMessageTypeFlagsEXT
, DebugUtilsMessengerCallbackDataEXT
,
DebugUtilsMessengerCallbackDataFlagsEXT
,
DebugUtilsMessengerCreateFlagsEXT
, DebugUtilsMessengerCreateInfoEXT
,
DebugUtilsMessengerEXT
,
DebugUtilsObjectNameInfoEXT
, DebugUtilsObjectTagInfoEXT
,
cmdBeginDebugUtilsLabelEXT
, cmdEndDebugUtilsLabelEXT
,
cmdInsertDebugUtilsLabelEXT
, createDebugUtilsMessengerEXT
,
destroyDebugUtilsMessengerEXT
, queueBeginDebugUtilsLabelEXT
,
queueEndDebugUtilsLabelEXT
, queueInsertDebugUtilsLabelEXT
,
setDebugUtilsObjectNameEXT
, setDebugUtilsObjectTagEXT
,
submitDebugUtilsMessageEXT
Document Notes
For more information, see the Vulkan Specification
This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.
Synopsis
- setDebugUtilsObjectNameEXT :: forall io. MonadIO io => Device -> DebugUtilsObjectNameInfoEXT -> io ()
- setDebugUtilsObjectTagEXT :: forall io. MonadIO io => Device -> DebugUtilsObjectTagInfoEXT -> io ()
- queueBeginDebugUtilsLabelEXT :: forall io. MonadIO io => Queue -> ("labelInfo" ::: DebugUtilsLabelEXT) -> io ()
- queueEndDebugUtilsLabelEXT :: forall io. MonadIO io => Queue -> io ()
- queueInsertDebugUtilsLabelEXT :: forall io. MonadIO io => Queue -> ("labelInfo" ::: DebugUtilsLabelEXT) -> io ()
- cmdBeginDebugUtilsLabelEXT :: forall io. MonadIO io => CommandBuffer -> ("labelInfo" ::: DebugUtilsLabelEXT) -> io ()
- cmdUseDebugUtilsLabelEXT :: forall io r. MonadIO io => CommandBuffer -> DebugUtilsLabelEXT -> io r -> io r
- cmdEndDebugUtilsLabelEXT :: forall io. MonadIO io => CommandBuffer -> io ()
- cmdInsertDebugUtilsLabelEXT :: forall io. MonadIO io => CommandBuffer -> ("labelInfo" ::: DebugUtilsLabelEXT) -> io ()
- createDebugUtilsMessengerEXT :: forall io. MonadIO io => Instance -> DebugUtilsMessengerCreateInfoEXT -> ("allocator" ::: Maybe AllocationCallbacks) -> io DebugUtilsMessengerEXT
- withDebugUtilsMessengerEXT :: forall io r. MonadIO io => Instance -> DebugUtilsMessengerCreateInfoEXT -> Maybe AllocationCallbacks -> (io DebugUtilsMessengerEXT -> (DebugUtilsMessengerEXT -> io ()) -> r) -> r
- destroyDebugUtilsMessengerEXT :: forall io. MonadIO io => Instance -> DebugUtilsMessengerEXT -> ("allocator" ::: Maybe AllocationCallbacks) -> io ()
- submitDebugUtilsMessageEXT :: forall a io. (Extendss DebugUtilsMessengerCallbackDataEXT a, PokeChain a, MonadIO io) => Instance -> DebugUtilsMessageSeverityFlagBitsEXT -> ("messageTypes" ::: DebugUtilsMessageTypeFlagsEXT) -> DebugUtilsMessengerCallbackDataEXT a -> io ()
- data DebugUtilsObjectNameInfoEXT = DebugUtilsObjectNameInfoEXT {}
- data DebugUtilsObjectTagInfoEXT = DebugUtilsObjectTagInfoEXT {
- objectType :: ObjectType
- objectHandle :: Word64
- tagName :: Word64
- tagSize :: Word64
- tag :: Ptr ()
- data DebugUtilsLabelEXT = DebugUtilsLabelEXT {}
- data DebugUtilsMessengerCreateInfoEXT = DebugUtilsMessengerCreateInfoEXT {}
- data DebugUtilsMessengerCallbackDataEXT (es :: [Type]) = DebugUtilsMessengerCallbackDataEXT {}
- newtype DebugUtilsMessengerCreateFlagsEXT = DebugUtilsMessengerCreateFlagsEXT Flags
- newtype DebugUtilsMessengerCallbackDataFlagsEXT = DebugUtilsMessengerCallbackDataFlagsEXT Flags
- type DebugUtilsMessageSeverityFlagsEXT = DebugUtilsMessageSeverityFlagBitsEXT
- newtype DebugUtilsMessageSeverityFlagBitsEXT where
- DebugUtilsMessageSeverityFlagBitsEXT Flags
- pattern DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT
- type DebugUtilsMessageTypeFlagsEXT = DebugUtilsMessageTypeFlagBitsEXT
- newtype DebugUtilsMessageTypeFlagBitsEXT where
- DebugUtilsMessageTypeFlagBitsEXT Flags
- pattern DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT :: DebugUtilsMessageTypeFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT :: DebugUtilsMessageTypeFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT :: DebugUtilsMessageTypeFlagBitsEXT
- pattern DEBUG_UTILS_MESSAGE_TYPE_DEVICE_ADDRESS_BINDING_BIT_EXT :: DebugUtilsMessageTypeFlagBitsEXT
- type PFN_vkDebugUtilsMessengerCallbackEXT = FunPtr FN_vkDebugUtilsMessengerCallbackEXT
- type FN_vkDebugUtilsMessengerCallbackEXT = DebugUtilsMessageSeverityFlagBitsEXT -> ("messageTypes" ::: DebugUtilsMessageTypeFlagsEXT) -> ("pCallbackData" ::: Ptr (SomeStruct DebugUtilsMessengerCallbackDataEXT)) -> ("pUserData" ::: Ptr ()) -> IO Bool32
- type EXT_DEBUG_UTILS_SPEC_VERSION = 2
- pattern EXT_DEBUG_UTILS_SPEC_VERSION :: forall a. Integral a => a
- type EXT_DEBUG_UTILS_EXTENSION_NAME = "VK_EXT_debug_utils"
- pattern EXT_DEBUG_UTILS_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- newtype DebugUtilsMessengerEXT = DebugUtilsMessengerEXT Word64
Documentation
setDebugUtilsObjectNameEXT Source #
:: forall io. MonadIO io | |
=> Device |
|
-> DebugUtilsObjectNameInfoEXT |
|
-> io () |
vkSetDebugUtilsObjectNameEXT - Give a user-friendly name to an object
Valid Usage
-
pNameInfo->objectType
must not beOBJECT_TYPE_UNKNOWN
-
pNameInfo->objectHandle
must not beNULL_HANDLE
- If
pNameInfo->objectHandle
is the valid handle of an instance-level object, theDevice
identified bydevice
must be a descendent of the sameInstance
as the object identified bypNameInfo->objectHandle
- If
pNameInfo->objectHandle
is the valid handle of a physical-device-level object, theDevice
identified bydevice
must be a descendant of the samePhysicalDevice
as the object identified bypNameInfo->objectHandle
- If
pNameInfo->objectHandle
is the valid handle of a device-level object, that object must be a descendent of theDevice
identified bydevice
Valid Usage (Implicit)
-
device
must be a validDevice
handle
-
pNameInfo
must be a valid pointer to a validDebugUtilsObjectNameInfoEXT
structure
Host Synchronization
- Host access to
pNameInfo->objectHandle
must be externally synchronized
Return Codes
See Also
setDebugUtilsObjectTagEXT Source #
:: forall io. MonadIO io | |
=> Device |
|
-> DebugUtilsObjectTagInfoEXT |
|
-> io () |
vkSetDebugUtilsObjectTagEXT - Attach arbitrary data to an object
Valid Usage
- If
pNameInfo->objectHandle
is the valid handle of an instance-level object, theDevice
identified bydevice
must be a descendent of the sameInstance
as the object identified bypNameInfo->objectHandle
- If
pNameInfo->objectHandle
is the valid handle of a physical-device-level object, theDevice
identified bydevice
must be a descendant of the samePhysicalDevice
as the object identified bypNameInfo->objectHandle
- If
pNameInfo->objectHandle
is the valid handle of a device-level object, that object must be a descendent of theDevice
identified bydevice
Valid Usage (Implicit)
-
device
must be a validDevice
handle
-
pTagInfo
must be a valid pointer to a validDebugUtilsObjectTagInfoEXT
structure
Host Synchronization
- Host access to
pTagInfo->objectHandle
must be externally synchronized
Return Codes
See Also
queueBeginDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> Queue |
|
-> ("labelInfo" ::: DebugUtilsLabelEXT) |
|
-> io () |
vkQueueBeginDebugUtilsLabelEXT - Open a queue debug label region
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
- | - | - | Any | - |
See Also
queueEndDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> Queue |
|
-> io () |
vkQueueEndDebugUtilsLabelEXT - Close a queue debug label region
Description
The calls to queueBeginDebugUtilsLabelEXT
and
queueEndDebugUtilsLabelEXT
must be matched and balanced.
Valid Usage
- There must be an
outstanding
queueBeginDebugUtilsLabelEXT
command prior to thequeueEndDebugUtilsLabelEXT
on the queue
Valid Usage (Implicit)
-
queue
must be a validQueue
handle
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
- | - | - | Any | - |
See Also
queueInsertDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> Queue |
|
-> ("labelInfo" ::: DebugUtilsLabelEXT) |
|
-> io () |
vkQueueInsertDebugUtilsLabelEXT - Insert a label into a queue
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
- | - | - | Any | - |
See Also
cmdBeginDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("labelInfo" ::: DebugUtilsLabelEXT) |
|
-> io () |
vkCmdBeginDebugUtilsLabelEXT - Open a command buffer debug label region
Valid Usage (Implicit)
-
commandBuffer
must be a validCommandBuffer
handle
-
pLabelInfo
must be a valid pointer to a validDebugUtilsLabelEXT
structure -
commandBuffer
must be in the recording state - The
CommandPool
thatcommandBuffer
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
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary Secondary | Both | Outside | Graphics Compute | Action State |
See Also
cmdUseDebugUtilsLabelEXT :: forall io r. MonadIO io => CommandBuffer -> DebugUtilsLabelEXT -> io r -> io r Source #
This function will call the supplied action between calls to
cmdBeginDebugUtilsLabelEXT
and cmdEndDebugUtilsLabelEXT
Note that cmdEndDebugUtilsLabelEXT
is *not* called if an exception is
thrown by the inner action.
cmdEndDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> io () |
vkCmdEndDebugUtilsLabelEXT - Close a command buffer label region
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
cmdBeginDebugUtilsLabelEXT
command prior to thecmdEndDebugUtilsLabelEXT
on the queue thatcommandBuffer
is submitted to
- If
commandBuffer
is a secondary command buffer, there must be an outstandingcmdBeginDebugUtilsLabelEXT
command recorded tocommandBuffer
that has not previously been ended by a call tocmdEndDebugUtilsLabelEXT
Valid Usage (Implicit)
-
commandBuffer
must be a validCommandBuffer
handle
-
commandBuffer
must be in the recording state - The
CommandPool
thatcommandBuffer
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
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary Secondary | Both | Outside | Graphics Compute | Action State |
See Also
cmdInsertDebugUtilsLabelEXT Source #
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> ("labelInfo" ::: DebugUtilsLabelEXT) | |
-> io () |
vkCmdInsertDebugUtilsLabelEXT - Insert a label into a command buffer
Valid Usage (Implicit)
-
commandBuffer
must be a validCommandBuffer
handle
-
pLabelInfo
must be a valid pointer to a validDebugUtilsLabelEXT
structure -
commandBuffer
must be in the recording state - The
CommandPool
thatcommandBuffer
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
CommandPool
thatcommandBuffer
was allocated from must be externally synchronized
Command Properties
'
Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type |
---|---|---|---|---|
Primary Secondary | Both | Outside | Graphics Compute | Action |
See Also
createDebugUtilsMessengerEXT Source #
:: forall io. MonadIO io | |
=> Instance |
|
-> DebugUtilsMessengerCreateInfoEXT |
|
-> ("allocator" ::: Maybe AllocationCallbacks) |
|
-> io DebugUtilsMessengerEXT |
vkCreateDebugUtilsMessengerEXT - Create a debug messenger object
Valid Usage (Implicit)
-
instance
must be a validInstance
handle
-
pCreateInfo
must be a valid pointer to a validDebugUtilsMessengerCreateInfoEXT
structure - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validAllocationCallbacks
structure -
pMessenger
must be a valid pointer to aDebugUtilsMessengerEXT
handle
Return Codes
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
VK_EXT_debug_utils,
AllocationCallbacks
,
DebugUtilsMessengerCreateInfoEXT
,
DebugUtilsMessengerEXT
,
Instance
withDebugUtilsMessengerEXT :: forall io r. MonadIO io => Instance -> DebugUtilsMessengerCreateInfoEXT -> Maybe AllocationCallbacks -> (io DebugUtilsMessengerEXT -> (DebugUtilsMessengerEXT -> io ()) -> r) -> r Source #
A convenience wrapper to make a compatible pair of calls to
createDebugUtilsMessengerEXT
and destroyDebugUtilsMessengerEXT
To ensure that destroyDebugUtilsMessengerEXT
is always called: pass
bracket
(or the allocate function from your
favourite resource management library) as the last argument.
To just extract the pair pass (,)
as the last argument.
destroyDebugUtilsMessengerEXT Source #
:: forall io. MonadIO io | |
=> Instance |
|
-> DebugUtilsMessengerEXT |
|
-> ("allocator" ::: Maybe AllocationCallbacks) |
|
-> io () |
vkDestroyDebugUtilsMessengerEXT - Destroy a debug messenger object
Valid Usage
- If
AllocationCallbacks
were provided whenmessenger
was created, a compatible set of callbacks must be provided here
- If no
AllocationCallbacks
were provided whenmessenger
was created,pAllocator
must beNULL
Valid Usage (Implicit)
-
instance
must be a validInstance
handle
- If
messenger
is notNULL_HANDLE
,messenger
must be a validDebugUtilsMessengerEXT
handle - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validAllocationCallbacks
structure - If
messenger
is a valid handle, it 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
with instance
or child of instance
as the dispatchable argument.
See Also
VK_EXT_debug_utils,
AllocationCallbacks
,
DebugUtilsMessengerEXT
,
Instance
submitDebugUtilsMessageEXT Source #
:: forall a io. (Extendss DebugUtilsMessengerCallbackDataEXT a, PokeChain a, MonadIO io) | |
=> Instance |
|
-> DebugUtilsMessageSeverityFlagBitsEXT |
|
-> ("messageTypes" ::: DebugUtilsMessageTypeFlagsEXT) |
|
-> DebugUtilsMessengerCallbackDataEXT a |
|
-> io () |
vkSubmitDebugUtilsMessageEXT - Inject a message into a debug stream
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 ofpCallbackData->pObjects
must not beOBJECT_TYPE_UNKNOWN
Valid Usage (Implicit)
-
instance
must be a validInstance
handle
-
messageSeverity
must be a validDebugUtilsMessageSeverityFlagBitsEXT
value -
messageTypes
must be a valid combination ofDebugUtilsMessageTypeFlagBitsEXT
values -
messageTypes
must not be0
-
pCallbackData
must be a valid pointer to a validDebugUtilsMessengerCallbackDataEXT
structure
See Also
VK_EXT_debug_utils,
DebugUtilsMessageSeverityFlagBitsEXT
, DebugUtilsMessageTypeFlagsEXT
,
DebugUtilsMessengerCallbackDataEXT
, Instance
data DebugUtilsObjectNameInfoEXT Source #
VkDebugUtilsObjectNameInfoEXT - Specify parameters of a name to give to an object
Description
Applications may change the name associated with an object simply by
calling setDebugUtilsObjectNameEXT
again with a new string. If
pObjectName
is either NULL
or an empty string, then any previously
set name is removed.
The
graphicsPipelineLibrary
feature allows the specification of pipelines without the creation of
ShaderModule
objects beforehand. In order to
continue to allow naming these shaders independently,
DebugUtilsObjectNameInfoEXT
can be included in the pNext
chain of
PipelineShaderStageCreateInfo
, which associates
a static name with that particular shader.
Valid Usage
- If
objectType
isOBJECT_TYPE_UNKNOWN
,objectHandle
must not beNULL_HANDLE
- If
objectType
is notOBJECT_TYPE_UNKNOWN
,objectHandle
must beNULL_HANDLE
or a valid Vulkan handle of the type associated withobjectType
as defined in the and Vulkan Handle Relationship table
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
-
objectType
must be a validObjectType
value - If
pObjectName
is notNULL
,pObjectName
must be a null-terminated UTF-8 string
See Also
VK_EXT_debug_utils,
DebugUtilsMessengerCallbackDataEXT
,
ObjectType
,
StructureType
,
setDebugUtilsObjectNameEXT
DebugUtilsObjectNameInfoEXT | |
|
Instances
Show DebugUtilsObjectNameInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils showsPrec :: Int -> DebugUtilsObjectNameInfoEXT -> ShowS # show :: DebugUtilsObjectNameInfoEXT -> String # showList :: [DebugUtilsObjectNameInfoEXT] -> ShowS # | |
FromCStruct DebugUtilsObjectNameInfoEXT Source # | |
ToCStruct DebugUtilsObjectNameInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils withCStruct :: DebugUtilsObjectNameInfoEXT -> (Ptr DebugUtilsObjectNameInfoEXT -> IO b) -> IO b Source # pokeCStruct :: Ptr DebugUtilsObjectNameInfoEXT -> DebugUtilsObjectNameInfoEXT -> IO b -> IO b Source # withZeroCStruct :: (Ptr DebugUtilsObjectNameInfoEXT -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr DebugUtilsObjectNameInfoEXT -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero DebugUtilsObjectNameInfoEXT Source # | |
data DebugUtilsObjectTagInfoEXT Source #
VkDebugUtilsObjectTagInfoEXT - Specify parameters of a tag to attach to an object
Description
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 (Implicit)
See Also
VK_EXT_debug_utils,
ObjectType
,
StructureType
,
setDebugUtilsObjectTagEXT
DebugUtilsObjectTagInfoEXT | |
|
Instances
data DebugUtilsLabelEXT Source #
VkDebugUtilsLabelEXT - Specify parameters of a label region
Valid Usage (Implicit)
See Also
VK_EXT_debug_utils,
DebugUtilsMessengerCallbackDataEXT
,
StructureType
,
cmdBeginDebugUtilsLabelEXT
, cmdInsertDebugUtilsLabelEXT
,
queueBeginDebugUtilsLabelEXT
, queueInsertDebugUtilsLabelEXT
DebugUtilsLabelEXT | |
|
Instances
Show DebugUtilsLabelEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils showsPrec :: Int -> DebugUtilsLabelEXT -> ShowS # show :: DebugUtilsLabelEXT -> String # showList :: [DebugUtilsLabelEXT] -> ShowS # | |
FromCStruct DebugUtilsLabelEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils | |
ToCStruct DebugUtilsLabelEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils withCStruct :: DebugUtilsLabelEXT -> (Ptr DebugUtilsLabelEXT -> IO b) -> IO b Source # pokeCStruct :: Ptr DebugUtilsLabelEXT -> DebugUtilsLabelEXT -> IO b -> IO b Source # withZeroCStruct :: (Ptr DebugUtilsLabelEXT -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr DebugUtilsLabelEXT -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero DebugUtilsLabelEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_utils |
data DebugUtilsMessengerCreateInfoEXT Source #
VkDebugUtilsMessengerCreateInfoEXT - Structure specifying parameters of a newly created debug messenger
Description
For each DebugUtilsMessengerEXT
that is
created the DebugUtilsMessengerCreateInfoEXT
::messageSeverity
and
DebugUtilsMessengerCreateInfoEXT
::messageType
determine when that
DebugUtilsMessengerCreateInfoEXT
::pfnUserCallback
is called. The
process to determine if the user’s pfnUserCallback
is triggered when
an event occurs is as follows:
The implementation will perform a bitwise AND of the event’s
DebugUtilsMessageSeverityFlagBitsEXT
with themessageSeverity
provided during creation of theDebugUtilsMessengerEXT
object.- If the value is 0, the message is skipped.
The implementation will perform bitwise AND of the event’s
DebugUtilsMessageTypeFlagBitsEXT
with themessageType
provided during the creation of theDebugUtilsMessengerEXT
object.- If the value is 0, the message is skipped.
- The callback will trigger a debug message for the current event
The callback will come directly from the component that detected the event, unless some other layer intercepts the calls for its own purposes (filter them in a different way, log to a system error log, etc.).
An application can receive multiple callbacks if multiple
DebugUtilsMessengerEXT
objects are created.
A callback will always be executed in the same thread as the originating
Vulkan call.
A callback can be called from multiple threads simultaneously (if the application is making Vulkan calls from multiple threads).
Valid Usage (Implicit)
See Also
PFN_vkDebugUtilsMessengerCallbackEXT
,
VK_EXT_debug_utils,
DebugUtilsMessageSeverityFlagsEXT
, DebugUtilsMessageTypeFlagsEXT
,
DebugUtilsMessengerCreateFlagsEXT
,
StructureType
,
createDebugUtilsMessengerEXT
DebugUtilsMessengerCreateInfoEXT | |
|
Instances
data DebugUtilsMessengerCallbackDataEXT (es :: [Type]) Source #
VkDebugUtilsMessengerCallbackDataEXT - Structure specifying parameters returned to the callback
Description
Note
This structure should only be considered valid during the lifetime of the triggered callback.
Since adding queue and command buffer labels behaves like pushing and
popping onto a stack, the order of both pQueueLabels
and
pCmdBufLabels
is based on the order the labels were defined. The
result is that the first label in either pQueueLabels
or
pCmdBufLabels
will be the first defined (and therefore the oldest)
while the last label in each list will be the most recent.
Note
pQueueLabels
will only be non-NULL
if one of the objects in
pObjects
can be related directly to a defined
Queue
which has had one or more labels
associated with it.
Likewise, pCmdBufLabels
will only be non-NULL
if one of the objects
in pObjects
can be related directly to a defined
CommandBuffer
which has had one or more labels
associated with it. Additionally, while command buffer labels allow for
beginning and ending across different command buffers, the debug
messaging framework cannot guarantee that labels in pCmdBufLables
will contain those defined outside of the associated command buffer.
This is partially due to the fact that the association of one command
buffer with another may not have been defined at the time the debug
message is triggered.
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
-
pNext
must beNULL
or a pointer to a valid instance ofDeviceAddressBindingCallbackDataEXT
- The
sType
value of each struct in thepNext
chain must be unique -
flags
must be0
-
If
pMessageIdName
is notNULL
,pMessageIdName
must be a null-terminated UTF-8 string -
pMessage
must be a null-terminated UTF-8 string -
If
queueLabelCount
is not0
,pQueueLabels
must be a valid pointer to an array ofqueueLabelCount
validDebugUtilsLabelEXT
structures -
If
cmdBufLabelCount
is not0
,pCmdBufLabels
must be a valid pointer to an array ofcmdBufLabelCount
validDebugUtilsLabelEXT
structures - If
objectCount
is not0
,pObjects
must be a valid pointer to an array ofobjectCount
validDebugUtilsObjectNameInfoEXT
structures
See Also
VK_EXT_debug_utils,
DebugUtilsLabelEXT
, DebugUtilsMessengerCallbackDataFlagsEXT
,
DebugUtilsObjectNameInfoEXT
,
StructureType
,
submitDebugUtilsMessageEXT
DebugUtilsMessengerCallbackDataEXT | |
|
Instances
newtype DebugUtilsMessengerCreateFlagsEXT Source #
VkDebugUtilsMessengerCreateFlagsEXT - Reserved for future use
Description
DebugUtilsMessengerCreateFlagsEXT
is a bitmask type for setting a
mask, but is currently reserved for future use.
See Also
Instances
newtype DebugUtilsMessengerCallbackDataFlagsEXT Source #
VkDebugUtilsMessengerCallbackDataFlagsEXT - Reserved for future use
Description
DebugUtilsMessengerCallbackDataFlagsEXT
is a bitmask type for setting
a mask, but is currently reserved for future use.
See Also
Instances
newtype DebugUtilsMessageSeverityFlagBitsEXT Source #
VkDebugUtilsMessageSeverityFlagBitsEXT - Bitmask specifying which severities of events cause a debug messenger callback
Description
Note
The values of DebugUtilsMessageSeverityFlagBitsEXT
are sorted based on
severity. The higher the flag value, the more severe the message. This
allows for simple boolean operation comparisons when looking at
DebugUtilsMessageSeverityFlagBitsEXT
values.
For example:
if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) { // Do something for warnings and errors }
In addition, space has been left between the enums to allow for later addition of new severities in between the existing values.
See Also
VK_EXT_debug_utils,
DebugUtilsMessageSeverityFlagsEXT
, submitDebugUtilsMessageEXT
pattern DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT |
|
pattern DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT |
|
pattern DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT |
|
pattern DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT :: DebugUtilsMessageSeverityFlagBitsEXT |
|
Instances
newtype DebugUtilsMessageTypeFlagBitsEXT Source #
VkDebugUtilsMessageTypeFlagBitsEXT - Bitmask specifying which types of events cause a debug messenger callback
See Also
Instances
type PFN_vkDebugUtilsMessengerCallbackEXT = FunPtr FN_vkDebugUtilsMessengerCallbackEXT Source #
PFN_vkDebugUtilsMessengerCallbackEXT - Application-defined debug messenger callback function
Description
The callback returns a Bool32
, which is
interpreted in a layer-specified manner. The application should always
return FALSE
. The
TRUE
value is reserved for use in layer
development.
Valid Usage
See Also
type FN_vkDebugUtilsMessengerCallbackEXT = DebugUtilsMessageSeverityFlagBitsEXT -> ("messageTypes" ::: DebugUtilsMessageTypeFlagsEXT) -> ("pCallbackData" ::: Ptr (SomeStruct DebugUtilsMessengerCallbackDataEXT)) -> ("pUserData" ::: Ptr ()) -> IO Bool32 Source #
type EXT_DEBUG_UTILS_SPEC_VERSION = 2 Source #
pattern EXT_DEBUG_UTILS_SPEC_VERSION :: forall a. Integral a => a Source #
type EXT_DEBUG_UTILS_EXTENSION_NAME = "VK_EXT_debug_utils" Source #
pattern EXT_DEBUG_UTILS_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #
newtype DebugUtilsMessengerEXT Source #
VkDebugUtilsMessengerEXT - Opaque handle to a debug messenger object
Description
The debug messenger will provide detailed feedback on the application’s use of Vulkan when events of interest occur. When an event of interest does occur, the debug messenger will submit a debug message to the debug callback that was provided during its creation. Additionally, the debug messenger is responsible with filtering out debug messages that the callback is not interested in and will only provide desired debug messages.
See Also
VK_EXT_debug_utils,
createDebugUtilsMessengerEXT
,
destroyDebugUtilsMessengerEXT