registry/vulkan/chapters/debugging.txt

// Copyright 2015-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

= Debugging

To aid developers in tracking down errors in the application's use of
Vulkan, particularly in combination with an external debugger or profiler,
_debugging extensions_ may be available.

[open,refpage='VkObjectType',desc='Specify an enumeration to track object handle types',type='enums']
--
The elink:VkObjectType enumeration defines values, each of which corresponds
to a specific Vulkan handle type.
These values can: be used to associate debug information with a particular
type of object through one or more extensions.

include::{generated}/api/enums/VkObjectType.txt[]

[[debugging-object-types]]
.`VkObjectType` and Vulkan Handle Relationship
[width="80%",cols="<35,<23",options="header"]
|====
| elink:VkObjectType                         | Vulkan Handle Type
| ename:VK_OBJECT_TYPE_UNKNOWN               | Unknown/Undefined Handle
| ename:VK_OBJECT_TYPE_INSTANCE              | slink:VkInstance
| ename:VK_OBJECT_TYPE_PHYSICAL_DEVICE       | slink:VkPhysicalDevice
| ename:VK_OBJECT_TYPE_DEVICE                | slink:VkDevice
| ename:VK_OBJECT_TYPE_QUEUE                 | slink:VkQueue
| ename:VK_OBJECT_TYPE_SEMAPHORE             | slink:VkSemaphore
| ename:VK_OBJECT_TYPE_COMMAND_BUFFER        | slink:VkCommandBuffer
| ename:VK_OBJECT_TYPE_FENCE                 | slink:VkFence
| ename:VK_OBJECT_TYPE_DEVICE_MEMORY         | slink:VkDeviceMemory
| ename:VK_OBJECT_TYPE_BUFFER                | slink:VkBuffer
| ename:VK_OBJECT_TYPE_IMAGE                 | slink:VkImage
| ename:VK_OBJECT_TYPE_EVENT                 | slink:VkEvent
| ename:VK_OBJECT_TYPE_QUERY_POOL            | slink:VkQueryPool
| ename:VK_OBJECT_TYPE_BUFFER_VIEW           | slink:VkBufferView
| ename:VK_OBJECT_TYPE_IMAGE_VIEW            | slink:VkImageView
| ename:VK_OBJECT_TYPE_SHADER_MODULE         | slink:VkShaderModule
| ename:VK_OBJECT_TYPE_PIPELINE_CACHE        | slink:VkPipelineCache
| ename:VK_OBJECT_TYPE_PIPELINE_LAYOUT       | slink:VkPipelineLayout
| ename:VK_OBJECT_TYPE_RENDER_PASS           | slink:VkRenderPass
| ename:VK_OBJECT_TYPE_PIPELINE              | slink:VkPipeline
| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT | slink:VkDescriptorSetLayout
| ename:VK_OBJECT_TYPE_SAMPLER               | slink:VkSampler
| ename:VK_OBJECT_TYPE_DESCRIPTOR_POOL       | slink:VkDescriptorPool
| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET        | slink:VkDescriptorSet
| ename:VK_OBJECT_TYPE_FRAMEBUFFER           | slink:VkFramebuffer
| ename:VK_OBJECT_TYPE_COMMAND_POOL          | slink:VkCommandPool
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
| ename:VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION | slink:VkSamplerYcbcrConversion
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
| ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE | slink:VkDescriptorUpdateTemplate
endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
ifdef::VK_KHR_surface[]
| ename:VK_OBJECT_TYPE_SURFACE_KHR           | slink:VkSurfaceKHR
endif::VK_KHR_surface[]
ifdef::VK_KHR_swapchain[]
| ename:VK_OBJECT_TYPE_SWAPCHAIN_KHR         | slink:VkSwapchainKHR
endif::VK_KHR_swapchain[]
ifdef::VK_KHR_display[]
| ename:VK_OBJECT_TYPE_DISPLAY_KHR           | slink:VkDisplayKHR
| ename:VK_OBJECT_TYPE_DISPLAY_MODE_KHR      | slink:VkDisplayModeKHR
endif::VK_KHR_display[]
ifdef::VK_EXT_debug_report[]
| ename:VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT | slink:VkDebugReportCallbackEXT
endif::VK_EXT_debug_report[]
ifdef::VK_NV_device_generated_commands[]
| ename:VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NV | slink:VkIndirectCommandsLayoutNV
endif::VK_NV_device_generated_commands[]
ifdef::VK_EXT_debug_utils[]
| ename:VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT | slink:VkDebugUtilsMessengerEXT
endif::VK_EXT_debug_utils[]
ifdef::VK_EXT_validation_cache[]
| ename:VK_OBJECT_TYPE_VALIDATION_CACHE_EXT | slink:VkValidationCacheEXT
endif::VK_EXT_validation_cache[]
ifdef::VK_NV_ray_tracing[]
| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV | slink:VkAccelerationStructureNV
endif::VK_NV_ray_tracing[]
ifdef::VK_KHR_acceleration_structure[]
| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR | slink:VkAccelerationStructureKHR
endif::VK_KHR_acceleration_structure[]
ifdef::VK_INTEL_performance_query[]
| ename:VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL | slink:VkPerformanceConfigurationINTEL
endif::VK_INTEL_performance_query[]
ifdef::VK_KHR_deferred_host_operations[]
| ename:VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR | slink:VkDeferredOperationKHR
endif::VK_KHR_deferred_host_operations[]
ifdef::VK_EXT_private_data[]
| ename:VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT | slink:VkPrivateDataSlotEXT
endif::VK_EXT_private_data[]
|====
--

If this Specification was generated with any such extensions included, they
will be described in the remainder of this chapter.

ifdef::VK_EXT_debug_utils[]
include::VK_EXT_debug_utils.txt[]
endif::VK_EXT_debug_utils[]

ifdef::VK_EXT_debug_marker[]
include::VK_EXT_debug_marker.txt[]
endif::VK_EXT_debug_marker[]

ifdef::VK_EXT_debug_report[]
include::VK_EXT_debug_report.txt[]
endif::VK_EXT_debug_report[]

ifdef::VK_NV_device_diagnostic_checkpoints[]
include::VK_NV_device_diagnostic_checkpoints/device_diagnostic_checkpoints.txt[]
endif::VK_NV_device_diagnostic_checkpoints[]


ifdef::VK_EXT_tooling_info[]
[[debugging-tooling-info]]
== Active Tooling Information

[open,refpage='vkGetPhysicalDeviceToolPropertiesEXT',desc='Reports properties of tools active on the specified physical device',type='protos']
--
Information about tools providing debugging, profiling, or similar services,
active for a given physical device, can be obtained by calling:

include::{generated}/api/protos/vkGetPhysicalDeviceToolPropertiesEXT.txt[]

  * pname:physicalDevice is the handle to the physical device to query for
    active tools.
  * pname:pToolCount is a pointer to an integer describing the number of
    tools active on pname:physicalDevice.
  * pname:pToolProperties is either `NULL` or a pointer to an array of
    slink:VkPhysicalDeviceToolPropertiesEXT structures.

If pname:pToolProperties is `NULL`, then the number of tools currently
active on pname:physicalDevice is returned in pname:pToolCount.
Otherwise, pname:pToolCount must: point to a variable set by the user to the
number of elements in the pname:pToolProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pToolProperties.
If pname:pToolCount is less than the number of currently active tools, at
most pname:pToolCount structures will be written.

The count and properties of active tools may: change in response to events
outside the scope of the specification.
An application should: assume these properties might change at any given
time.

include::{generated}/validity/protos/vkGetPhysicalDeviceToolPropertiesEXT.txt[]
--

[open,refpage='VkPhysicalDeviceToolPropertiesEXT',desc='Structure providing information about an active tool',type='structs']
--
The slink:VkPhysicalDeviceToolPropertiesEXT structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceToolPropertiesEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:name is a null-terminated UTF-8 string containing the name of the
    tool.
  * pname:version is a null-terminated UTF-8 string containing the version
    of the tool.
  * pname:purposes is a bitmask of elink:VkToolPurposeFlagBitsEXT which is
    populated with purposes supported by the tool.
  * pname:description is a null-terminated UTF-8 string containing a
    description of the tool.
  * pname:layer is a null-terminated UTF-8 string that contains the name of
    the layer implementing the tool, if the tool is implemented in a layer -
    otherwise it may: be an empty string.

include::{generated}/validity/structs/VkPhysicalDeviceToolPropertiesEXT.txt[]
--

[open,refpage='VkToolPurposeFlagBitsEXT',desc='Bitmask specifying the purposes of an active tool',type='enums']
--
Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:purposes
specifying the purposes of an active tool are:

include::{generated}/api/enums/VkToolPurposeFlagBitsEXT.txt[]

  * ename:VK_TOOL_PURPOSE_VALIDATION_BIT_EXT specifies that the tool
    provides validation of API usage.
  * ename:VK_TOOL_PURPOSE_PROFILING_BIT_EXT specifies that the tool provides
    profiling of API usage.
  * ename:VK_TOOL_PURPOSE_TRACING_BIT_EXT specifies that the tool is
    capturing data about the application's API usage, including anything
    from simple logging to capturing data for later replay.
  * ename:VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT specifies that the
    tool provides additional API features/extensions on top of the
    underlying implementation.
  * ename:VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT_EXT specifies that the tool
    modifies the API features/limits/extensions presented to the
    application.
ifdef::VK_EXT_debug_report,VK_EXT_debug_utils[]
  * ename:VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT specifies that the tool
    reports additional information to the application via callbacks
    specified by
ifdef::VK_EXT_debug_report[]
    flink:vkCreateDebugReportCallbackEXT
endif::VK_EXT_debug_report[]
ifdef::VK_EXT_debug_report+VK_EXT_debug_utils[]
    or
endif::VK_EXT_debug_report+VK_EXT_debug_utils[]
ifdef::VK_EXT_debug_utils[]
    flink:vkCreateDebugUtilsMessengerEXT
endif::VK_EXT_debug_utils[]
endif::VK_EXT_debug_report,VK_EXT_debug_utils[]
ifdef::VK_EXT_debug_marker,VK_EXT_debug_utils[]
  * ename:VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT specifies that the tool
    consumes
ifdef::VK_EXT_debug_marker[]
    <<debugging-debug-markers,debug markers>>
endif::VK_EXT_debug_marker[]
ifdef::VK_EXT_debug_marker+VK_EXT_debug_utils[]
    or
endif::VK_EXT_debug_marker+VK_EXT_debug_utils[]
ifdef::VK_EXT_debug_utils[]
    <<debugging-object-debug-annotation,object debug annotation>>,
    <<debugging-queue-labels, queue labels>>, or
    <<debugging-command-buffer-labels, command buffer labels>>
endif::VK_EXT_debug_utils[]
endif::VK_EXT_debug_marker,VK_EXT_debug_utils[]
--

[open,refpage='VkToolPurposeFlagsEXT',desc='Bitmask of VkToolPurposeFlagBitsEXT',type='flags']
--
include::{generated}/api/flags/VkToolPurposeFlagsEXT.txt[]

tlink:VkToolPurposeFlagsEXT is a bitmask type for setting a mask of zero or
more elink:VkToolPurposeFlagBitsEXT.
--
endif::VK_EXT_tooling_info[]