vulkan-3.8.1: Bindings to the Vulkan graphics API.
Safe HaskellNone
LanguageHaskell2010

Vulkan.Extensions.VK_EXT_debug_marker

Description

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
Extension and Version Dependencies
  • Requires Vulkan 1.0
  • Requires VK_EXT_debug_report
Deprecation state
  • Promoted to VK_EXT_debug_utils extension
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

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);

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

Documentation

debugMarkerSetObjectNameEXT Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device that created the object.

-> DebugMarkerObjectNameInfoEXT

pNameInfo is a pointer to a DebugMarkerObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

-> io () 

vkDebugMarkerSetObjectNameEXT - Give a user-friendly name to an object

Valid Usage (Implicit)

  • device must be a valid Device handle

Host Synchronization

  • Host access to pNameInfo->object must be externally synchronized

Return Codes

Success
Failure

See Also

DebugMarkerObjectNameInfoEXT, Device

debugMarkerSetObjectTagEXT Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device that created the object.

-> DebugMarkerObjectTagInfoEXT

pTagInfo is a pointer to a DebugMarkerObjectTagInfoEXT structure specifying the parameters of the tag to attach to the object.

-> io () 

vkDebugMarkerSetObjectTagEXT - Attach arbitrary data to an object

Valid Usage (Implicit)

  • device must be a valid Device handle

Host Synchronization

  • Host access to pTagInfo->object must be externally synchronized

Return Codes

Success
Failure

See Also

DebugMarkerObjectTagInfoEXT, Device

cmdDebugMarkerBeginEXT Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> DebugMarkerMarkerInfoEXT

pMarkerInfo is a pointer to a DebugMarkerMarkerInfoEXT structure specifying the parameters of the marker region to open.

-> io () 

vkCmdDebugMarkerBeginEXT - Open a command buffer marker region

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized
  • Host access to the CommandPool that commandBuffer 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

CommandBuffer, DebugMarkerMarkerInfoEXT

cmdDebugMarkerEndEXT Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> 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

Valid Usage (Implicit)

  • commandBuffer must be in the recording state
  • The CommandPool that commandBuffer was allocated from must support graphics, or compute operations

Host Synchronization

  • Host access to commandBuffer must be externally synchronized
  • Host access to the CommandPool that commandBuffer 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

CommandBuffer

cmdDebugMarkerInsertEXT Source #

Arguments

:: forall io. MonadIO io 
=> CommandBuffer

commandBuffer is the command buffer into which the command is recorded.

-> DebugMarkerMarkerInfoEXT

pMarkerInfo is a pointer to a DebugMarkerMarkerInfoEXT structure specifying the parameters of the marker to insert.

-> io () 

vkCmdDebugMarkerInsertEXT - Insert a marker label into a command buffer

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized
  • Host access to the CommandPool that commandBuffer 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

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

DebugReportObjectTypeEXT, StructureType, debugMarkerSetObjectNameEXT

Constructors

DebugMarkerObjectNameInfoEXT 

Fields

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

DebugReportObjectTypeEXT, StructureType, debugMarkerSetObjectTagEXT

Constructors

DebugMarkerObjectTagInfoEXT 

Fields

Instances

Instances details
Show DebugMarkerObjectTagInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_marker

Storable DebugMarkerObjectTagInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_marker

FromCStruct DebugMarkerObjectTagInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_marker

ToCStruct DebugMarkerObjectTagInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_marker

Zero DebugMarkerObjectTagInfoEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_marker

data DebugMarkerMarkerInfoEXT Source #

VkDebugMarkerMarkerInfoEXT - Specify parameters of a command buffer marker region

Valid Usage (Implicit)

See Also

StructureType, cmdDebugMarkerBeginEXT, cmdDebugMarkerInsertEXT

Constructors

DebugMarkerMarkerInfoEXT 

Fields

  • markerName :: ByteString

    pMarkerName is a pointer to a null-terminated UTF-8 string containing the name of the marker.

    pMarkerName must be a null-terminated UTF-8 string

  • color :: (Float, Float, Float, Float)

    color is an optional RGBA color value that can be associated with the marker. A particular implementation may choose to ignore this color value. The values contain RGBA values in order, in the range 0.0 to 1.0. If all elements in color are set to 0.0 then it is ignored.

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 Vulkan Handle Type
DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT Unknown/Undefined Handle
DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT Instance
DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT PhysicalDevice
DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT Device
DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT Queue
DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT Semaphore
DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT CommandBuffer
DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT Fence
DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT DeviceMemory
DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT Buffer
DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT Image
DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT Event
DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT QueryPool
DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT BufferView
DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT ImageView
DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT ShaderModule
DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT PipelineCache
DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT PipelineLayout
DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT RenderPass
DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT Pipeline
DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT DescriptorSetLayout
DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT Sampler
DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT DescriptorPool
DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT DescriptorSet
DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT Framebuffer
DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT CommandPool
DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT SurfaceKHR
DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT SwapchainKHR
DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT DebugReportCallbackEXT
DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT DisplayKHR
DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT DisplayModeKHR
DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT DescriptorUpdateTemplate

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

DebugMarkerObjectNameInfoEXT, DebugMarkerObjectTagInfoEXT, debugReportMessageEXT

Bundled Patterns

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_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_DESCRIPTOR_UPDATE_TEMPLATE_EXT :: DebugReportObjectTypeEXT 

Instances

Instances details
Eq DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report

Ord DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report

Read DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report

Show DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report

Storable DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report

Zero DebugReportObjectTypeEXT Source # 
Instance details

Defined in Vulkan.Extensions.VK_EXT_debug_report