Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Name
VK_EXT_debug_marker - device extension
VK_EXT_debug_marker
- Name String
VK_EXT_debug_marker
- Extension Type
- Device extension
- Registered Extension Number
- 23
- Revision
- 4
- Ratification Status
- Not ratified
- Extension and Version Dependencies
- VK_EXT_debug_report
- Deprecation State
- Promoted to
VK_EXT_debug_utils
extension
- Promoted to
- Special Use
- Contact
Other Extension Metadata
- Last Modified Date
- 2017-01-31
- IP Status
- No known IP claims.
- Contributors
- Baldur Karlsson
- Dan Ginsburg, Valve
- Jon Ashburn, LunarG
- Kyle Spagnoli, NVIDIA
Description
The VK_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.
New Commands
New Structures
New Enums
New Enum Constants
EXT_DEBUG_MARKER_SPEC_VERSION
Extending
StructureType
:
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 = { .sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, .pNext = NULL, .objectType = VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT, .object = (uint64_t)image, .pObjectName = "Brick Diffuse Texture", }; 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 = { .sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, .pNext = NULL, .pMarkerName = "Brick House", .color = { 1.0f, 0.0f, 0.0f, 1.0f }, }; // Start an annotated group of calls under the 'Brick House' name pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker); { // A mutable structure for each part being rendered VkDebugMarkerMarkerInfoEXT housePartMarker = { .sType = VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, .pNext = NULL, .pMarkerName = NULL, .color = { 0.0f, 0.0f, 0.0f, 0.0f }, }; // 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);
Issues
1) Should the tag or name for an object be specified using the pNext
parameter in the object’s Vk*CreateInfo
structure?
RESOLVED: No. While this fits with other Vulkan patterns and would
allow more type safety and future proofing against future objects, it
has notable downsides. In particular passing the name at Vk*CreateInfo
time does not allow renaming, prevents late binding of naming
information, and does not allow naming of implicitly created objects
such as queues and swapchain images.
2) Should the command annotation functions cmdDebugMarkerBeginEXT
and
cmdDebugMarkerEndEXT
support the ability to specify a color?
RESOLVED: Yes. The functions have been expanded to take an optional color which can be used at will by implementations consuming the command buffer annotations in their visualisation.
3) Should the functions added in this extension accept an extensible structure as their parameter for a more flexible API, as opposed to direct function parameters? If so, which functions?
RESOLVED: Yes. All functions have been modified to take a structure
type with extensible pNext
pointer, to allow future extensions to add
additional annotation information in the same commands.
Version History
Revision 1, 2016-02-24 (Baldur Karlsson)
- Initial draft, based on LunarG marker spec
Revision 2, 2016-02-26 (Baldur Karlsson)
- Renamed Dbg to DebugMarker in function names
- Allow markers in secondary command buffers under certain circumstances
- Minor language tweaks and edits
Revision 3, 2016-04-23 (Baldur Karlsson)
- Reorganise spec layout to closer match desired organisation
- Added optional color to markers (both regions and inserted labels)
- Changed functions to take extensible structs instead of direct function parameters
Revision 4, 2017-01-31 (Baldur Karlsson)
- Added explicit dependency on VK_EXT_debug_report
- Moved definition of
DebugReportObjectTypeEXT
to debug report chapter. - Fixed typo in dates in revision history
See Also
DebugMarkerMarkerInfoEXT
, DebugMarkerObjectNameInfoEXT
,
DebugMarkerObjectTagInfoEXT
,
DebugReportObjectTypeEXT
,
cmdDebugMarkerBeginEXT
, cmdDebugMarkerEndEXT
,
cmdDebugMarkerInsertEXT
, debugMarkerSetObjectNameEXT
,
debugMarkerSetObjectTagEXT
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
- debugMarkerSetObjectNameEXT :: forall io. MonadIO io => Device -> DebugMarkerObjectNameInfoEXT -> io ()
- debugMarkerSetObjectTagEXT :: forall io. MonadIO io => Device -> DebugMarkerObjectTagInfoEXT -> io ()
- cmdDebugMarkerBeginEXT :: forall io. MonadIO io => CommandBuffer -> DebugMarkerMarkerInfoEXT -> io ()
- cmdDebugMarkerEndEXT :: forall io. MonadIO io => CommandBuffer -> io ()
- cmdDebugMarkerInsertEXT :: forall io. MonadIO io => CommandBuffer -> DebugMarkerMarkerInfoEXT -> io ()
- data DebugMarkerObjectNameInfoEXT = DebugMarkerObjectNameInfoEXT {}
- data DebugMarkerObjectTagInfoEXT = DebugMarkerObjectTagInfoEXT {
- objectType :: DebugReportObjectTypeEXT
- object :: Word64
- tagName :: Word64
- tagSize :: Word64
- tag :: Ptr ()
- data DebugMarkerMarkerInfoEXT = DebugMarkerMarkerInfoEXT {
- markerName :: ByteString
- color :: (Float, Float, Float, Float)
- type EXT_DEBUG_MARKER_SPEC_VERSION = 4
- pattern EXT_DEBUG_MARKER_SPEC_VERSION :: forall a. Integral a => a
- type EXT_DEBUG_MARKER_EXTENSION_NAME = "VK_EXT_debug_marker"
- pattern EXT_DEBUG_MARKER_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- newtype DebugReportObjectTypeEXT where
- DebugReportObjectTypeEXT Int32
- pattern DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_VALIDATION_CACHE_EXT_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_BUFFER_COLLECTION_FUCHSIA_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_CUDA_FUNCTION_NV :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_CUDA_MODULE_NV :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_CU_FUNCTION_NVX_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_CU_MODULE_NVX_EXT :: DebugReportObjectTypeEXT
- pattern DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT :: DebugReportObjectTypeEXT
Documentation
debugMarkerSetObjectNameEXT Source #
:: forall io. MonadIO io | |
=> Device |
|
-> DebugMarkerObjectNameInfoEXT |
|
-> io () |
vkDebugMarkerSetObjectNameEXT - Give a user-friendly name to an object
Valid Usage (Implicit)
-
device
must be a validDevice
handle
-
pNameInfo
must be a valid pointer to a validDebugMarkerObjectNameInfoEXT
structure
Host Synchronization
- Host access to
pNameInfo->object
must be externally synchronized
Return Codes
See Also
debugMarkerSetObjectTagEXT Source #
:: forall io. MonadIO io | |
=> Device |
|
-> DebugMarkerObjectTagInfoEXT |
|
-> io () |
vkDebugMarkerSetObjectTagEXT - Attach arbitrary data to an object
Valid Usage (Implicit)
-
device
must be a validDevice
handle
-
pTagInfo
must be a valid pointer to a validDebugMarkerObjectTagInfoEXT
structure
Host Synchronization
- Host access to
pTagInfo->object
must be externally synchronized
Return Codes
See Also
cmdDebugMarkerBeginEXT Source #
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> DebugMarkerMarkerInfoEXT |
|
-> io () |
vkCmdDebugMarkerBeginEXT - Open a command buffer marker region
Valid Usage (Implicit)
-
commandBuffer
must be a validCommandBuffer
handle
-
pMarkerInfo
must be a valid pointer to a validDebugMarkerMarkerInfoEXT
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
VK_EXT_debug_marker,
CommandBuffer
, DebugMarkerMarkerInfoEXT
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> io () |
vkCmdDebugMarkerEndEXT - Close a command buffer marker region
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
cmdDebugMarkerBeginEXT
and cmdDebugMarkerEndEXT
must be matched
and balanced.
Valid Usage
- There must be an
outstanding
cmdDebugMarkerBeginEXT
command prior to thecmdDebugMarkerEndEXT
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 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 |
See Also
cmdDebugMarkerInsertEXT Source #
:: forall io. MonadIO io | |
=> CommandBuffer |
|
-> DebugMarkerMarkerInfoEXT |
|
-> io () |
vkCmdDebugMarkerInsertEXT - Insert a marker label into a command buffer
Valid Usage (Implicit)
-
commandBuffer
must be a validCommandBuffer
handle
-
pMarkerInfo
must be a valid pointer to a validDebugMarkerMarkerInfoEXT
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
VK_EXT_debug_marker,
CommandBuffer
, DebugMarkerMarkerInfoEXT
data DebugMarkerObjectNameInfoEXT Source #
VkDebugMarkerObjectNameInfoEXT - Specify parameters of a name to give to an object
Description
Applications may change the name associated with an object simply by
calling debugMarkerSetObjectNameEXT
again with a new string. To remove
a previously set name, pObjectName
should be set to an empty string.
Valid Usage (Implicit)
See Also
VK_EXT_debug_marker,
DebugReportObjectTypeEXT
,
StructureType
,
debugMarkerSetObjectNameEXT
DebugMarkerObjectNameInfoEXT | |
|
Instances
Show DebugMarkerObjectNameInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_marker showsPrec :: Int -> DebugMarkerObjectNameInfoEXT -> ShowS # show :: DebugMarkerObjectNameInfoEXT -> String # showList :: [DebugMarkerObjectNameInfoEXT] -> ShowS # | |
FromCStruct DebugMarkerObjectNameInfoEXT Source # | |
ToCStruct DebugMarkerObjectNameInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_marker withCStruct :: DebugMarkerObjectNameInfoEXT -> (Ptr DebugMarkerObjectNameInfoEXT -> IO b) -> IO b Source # pokeCStruct :: Ptr DebugMarkerObjectNameInfoEXT -> DebugMarkerObjectNameInfoEXT -> IO b -> IO b Source # withZeroCStruct :: (Ptr DebugMarkerObjectNameInfoEXT -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr DebugMarkerObjectNameInfoEXT -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero DebugMarkerObjectNameInfoEXT Source # | |
data DebugMarkerObjectTagInfoEXT Source #
VkDebugMarkerObjectTagInfoEXT - 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_marker,
DebugReportObjectTypeEXT
,
StructureType
,
debugMarkerSetObjectTagEXT
DebugMarkerObjectTagInfoEXT | |
|
Instances
data DebugMarkerMarkerInfoEXT Source #
VkDebugMarkerMarkerInfoEXT - Specify parameters of a command buffer marker region
Valid Usage (Implicit)
See Also
VK_EXT_debug_marker,
StructureType
,
cmdDebugMarkerBeginEXT
, cmdDebugMarkerInsertEXT
DebugMarkerMarkerInfoEXT | |
|
Instances
Show DebugMarkerMarkerInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_marker showsPrec :: Int -> DebugMarkerMarkerInfoEXT -> ShowS # show :: DebugMarkerMarkerInfoEXT -> String # showList :: [DebugMarkerMarkerInfoEXT] -> ShowS # | |
FromCStruct DebugMarkerMarkerInfoEXT Source # | |
ToCStruct DebugMarkerMarkerInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_marker withCStruct :: DebugMarkerMarkerInfoEXT -> (Ptr DebugMarkerMarkerInfoEXT -> IO b) -> IO b Source # pokeCStruct :: Ptr DebugMarkerMarkerInfoEXT -> DebugMarkerMarkerInfoEXT -> IO b -> IO b Source # withZeroCStruct :: (Ptr DebugMarkerMarkerInfoEXT -> IO b) -> IO b Source # pokeZeroCStruct :: Ptr DebugMarkerMarkerInfoEXT -> IO b -> IO b Source # cStructSize :: Int Source # | |
Zero DebugMarkerMarkerInfoEXT Source # | |
Defined in Vulkan.Extensions.VK_EXT_debug_marker |
type EXT_DEBUG_MARKER_SPEC_VERSION = 4 Source #
pattern EXT_DEBUG_MARKER_SPEC_VERSION :: forall a. Integral a => a Source #
type EXT_DEBUG_MARKER_EXTENSION_NAME = "VK_EXT_debug_marker" Source #
pattern EXT_DEBUG_MARKER_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #
newtype DebugReportObjectTypeEXT Source #
VkDebugReportObjectTypeEXT - Specify the type of an object handle
Description
'
DebugReportObjectTypeEXT
and Vulkan Handle Relationship
Note
The primary expected use of
ERROR_VALIDATION_FAILED_EXT
is for
validation layer testing. It is not expected that an application would
see this error code during normal use of the validation layers.
See Also
VK_EXT_debug_marker,
VK_EXT_debug_report,
DebugMarkerObjectNameInfoEXT
,
DebugMarkerObjectTagInfoEXT
,
debugReportMessageEXT