1// Copyright 2015-2021 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= Debugging 6 7To aid developers in tracking down errors in the application's use of 8Vulkan, particularly in combination with an external debugger or profiler, 9_debugging extensions_ may be available. 10 11[open,refpage='VkObjectType',desc='Specify an enumeration to track object handle types',type='enums'] 12-- 13The elink:VkObjectType enumeration defines values, each of which corresponds 14to a specific Vulkan handle type. 15These values can: be used to associate debug information with a particular 16type of object through one or more extensions. 17 18include::{generated}/api/enums/VkObjectType.txt[] 19 20[[debugging-object-types]] 21.`VkObjectType` and Vulkan Handle Relationship 22[width="80%",cols="<35,<23",options="header"] 23|==== 24| elink:VkObjectType | Vulkan Handle Type 25| ename:VK_OBJECT_TYPE_UNKNOWN | Unknown/Undefined Handle 26| ename:VK_OBJECT_TYPE_INSTANCE | slink:VkInstance 27| ename:VK_OBJECT_TYPE_PHYSICAL_DEVICE | slink:VkPhysicalDevice 28| ename:VK_OBJECT_TYPE_DEVICE | slink:VkDevice 29| ename:VK_OBJECT_TYPE_QUEUE | slink:VkQueue 30| ename:VK_OBJECT_TYPE_SEMAPHORE | slink:VkSemaphore 31| ename:VK_OBJECT_TYPE_COMMAND_BUFFER | slink:VkCommandBuffer 32| ename:VK_OBJECT_TYPE_FENCE | slink:VkFence 33| ename:VK_OBJECT_TYPE_DEVICE_MEMORY | slink:VkDeviceMemory 34| ename:VK_OBJECT_TYPE_BUFFER | slink:VkBuffer 35| ename:VK_OBJECT_TYPE_IMAGE | slink:VkImage 36| ename:VK_OBJECT_TYPE_EVENT | slink:VkEvent 37| ename:VK_OBJECT_TYPE_QUERY_POOL | slink:VkQueryPool 38| ename:VK_OBJECT_TYPE_BUFFER_VIEW | slink:VkBufferView 39| ename:VK_OBJECT_TYPE_IMAGE_VIEW | slink:VkImageView 40| ename:VK_OBJECT_TYPE_SHADER_MODULE | slink:VkShaderModule 41| ename:VK_OBJECT_TYPE_PIPELINE_CACHE | slink:VkPipelineCache 42| ename:VK_OBJECT_TYPE_PIPELINE_LAYOUT | slink:VkPipelineLayout 43| ename:VK_OBJECT_TYPE_RENDER_PASS | slink:VkRenderPass 44| ename:VK_OBJECT_TYPE_PIPELINE | slink:VkPipeline 45| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT | slink:VkDescriptorSetLayout 46| ename:VK_OBJECT_TYPE_SAMPLER | slink:VkSampler 47| ename:VK_OBJECT_TYPE_DESCRIPTOR_POOL | slink:VkDescriptorPool 48| ename:VK_OBJECT_TYPE_DESCRIPTOR_SET | slink:VkDescriptorSet 49| ename:VK_OBJECT_TYPE_FRAMEBUFFER | slink:VkFramebuffer 50| ename:VK_OBJECT_TYPE_COMMAND_POOL | slink:VkCommandPool 51ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 52| ename:VK_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION | slink:VkSamplerYcbcrConversion 53endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] 54ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 55| ename:VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE | slink:VkDescriptorUpdateTemplate 56endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 57ifdef::VK_KHR_surface[] 58| ename:VK_OBJECT_TYPE_SURFACE_KHR | slink:VkSurfaceKHR 59endif::VK_KHR_surface[] 60ifdef::VK_KHR_swapchain[] 61| ename:VK_OBJECT_TYPE_SWAPCHAIN_KHR | slink:VkSwapchainKHR 62endif::VK_KHR_swapchain[] 63ifdef::VK_KHR_display[] 64| ename:VK_OBJECT_TYPE_DISPLAY_KHR | slink:VkDisplayKHR 65| ename:VK_OBJECT_TYPE_DISPLAY_MODE_KHR | slink:VkDisplayModeKHR 66endif::VK_KHR_display[] 67ifdef::VK_EXT_debug_report[] 68| ename:VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT | slink:VkDebugReportCallbackEXT 69endif::VK_EXT_debug_report[] 70ifdef::VK_NV_device_generated_commands[] 71| ename:VK_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NV | slink:VkIndirectCommandsLayoutNV 72endif::VK_NV_device_generated_commands[] 73ifdef::VK_EXT_debug_utils[] 74| ename:VK_OBJECT_TYPE_DEBUG_UTILS_MESSENGER_EXT | slink:VkDebugUtilsMessengerEXT 75endif::VK_EXT_debug_utils[] 76ifdef::VK_EXT_validation_cache[] 77| ename:VK_OBJECT_TYPE_VALIDATION_CACHE_EXT | slink:VkValidationCacheEXT 78endif::VK_EXT_validation_cache[] 79ifdef::VK_NV_ray_tracing[] 80| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV | slink:VkAccelerationStructureNV 81endif::VK_NV_ray_tracing[] 82ifdef::VK_KHR_acceleration_structure[] 83| ename:VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR | slink:VkAccelerationStructureKHR 84endif::VK_KHR_acceleration_structure[] 85ifdef::VK_INTEL_performance_query[] 86| ename:VK_OBJECT_TYPE_PERFORMANCE_CONFIGURATION_INTEL | slink:VkPerformanceConfigurationINTEL 87endif::VK_INTEL_performance_query[] 88ifdef::VK_KHR_deferred_host_operations[] 89| ename:VK_OBJECT_TYPE_DEFERRED_OPERATION_KHR | slink:VkDeferredOperationKHR 90endif::VK_KHR_deferred_host_operations[] 91ifdef::VK_EXT_private_data[] 92| ename:VK_OBJECT_TYPE_PRIVATE_DATA_SLOT_EXT | slink:VkPrivateDataSlotEXT 93endif::VK_EXT_private_data[] 94|==== 95-- 96 97If this Specification was generated with any such extensions included, they 98will be described in the remainder of this chapter. 99 100ifdef::VK_EXT_debug_utils[] 101include::{chapters}/VK_EXT_debug_utils.txt[] 102endif::VK_EXT_debug_utils[] 103 104ifdef::VK_EXT_debug_marker[] 105include::{chapters}/VK_EXT_debug_marker.txt[] 106endif::VK_EXT_debug_marker[] 107 108ifdef::VK_EXT_debug_report[] 109include::{chapters}/VK_EXT_debug_report.txt[] 110endif::VK_EXT_debug_report[] 111 112ifdef::VK_NV_device_diagnostic_checkpoints[] 113include::{chapters}/VK_NV_device_diagnostic_checkpoints/device_diagnostic_checkpoints.txt[] 114endif::VK_NV_device_diagnostic_checkpoints[] 115 116 117ifdef::VK_EXT_tooling_info[] 118[[debugging-tooling-info]] 119== Active Tooling Information 120 121[open,refpage='vkGetPhysicalDeviceToolPropertiesEXT',desc='Reports properties of tools active on the specified physical device',type='protos'] 122-- 123Information about tools providing debugging, profiling, or similar services, 124active for a given physical device, can be obtained by calling: 125 126include::{generated}/api/protos/vkGetPhysicalDeviceToolPropertiesEXT.txt[] 127 128 * pname:physicalDevice is the handle to the physical device to query for 129 active tools. 130 * pname:pToolCount is a pointer to an integer describing the number of 131 tools active on pname:physicalDevice. 132 * pname:pToolProperties is either `NULL` or a pointer to an array of 133 slink:VkPhysicalDeviceToolPropertiesEXT structures. 134 135If pname:pToolProperties is `NULL`, then the number of tools currently 136active on pname:physicalDevice is returned in pname:pToolCount. 137Otherwise, pname:pToolCount must: point to a variable set by the user to the 138number of elements in the pname:pToolProperties array, and on return the 139variable is overwritten with the number of structures actually written to 140pname:pToolProperties. 141If pname:pToolCount is less than the number of currently active tools, at 142most pname:pToolCount structures will be written. 143 144The count and properties of active tools may: change in response to events 145outside the scope of the specification. 146An application should: assume these properties might change at any given 147time. 148 149include::{generated}/validity/protos/vkGetPhysicalDeviceToolPropertiesEXT.txt[] 150-- 151 152[open,refpage='VkPhysicalDeviceToolPropertiesEXT',desc='Structure providing information about an active tool',type='structs'] 153-- 154The slink:VkPhysicalDeviceToolPropertiesEXT structure is defined as: 155 156include::{generated}/api/structs/VkPhysicalDeviceToolPropertiesEXT.txt[] 157 158 * pname:sType is the type of this structure. 159 * pname:pNext is `NULL` or a pointer to a structure extending this 160 structure. 161 * pname:name is a null-terminated UTF-8 string containing the name of the 162 tool. 163 * pname:version is a null-terminated UTF-8 string containing the version 164 of the tool. 165 * pname:purposes is a bitmask of elink:VkToolPurposeFlagBitsEXT which is 166 populated with purposes supported by the tool. 167 * pname:description is a null-terminated UTF-8 string containing a 168 description of the tool. 169 * pname:layer is a null-terminated UTF-8 string containing the name of the 170 layer implementing the tool, if the tool is implemented in a layer - 171 otherwise it may: be an empty string. 172 173include::{generated}/validity/structs/VkPhysicalDeviceToolPropertiesEXT.txt[] 174-- 175 176[open,refpage='VkToolPurposeFlagBitsEXT',desc='Bitmask specifying the purposes of an active tool',type='enums'] 177-- 178Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:purposes 179specifying the purposes of an active tool are: 180 181include::{generated}/api/enums/VkToolPurposeFlagBitsEXT.txt[] 182 183 * ename:VK_TOOL_PURPOSE_VALIDATION_BIT_EXT specifies that the tool 184 provides validation of API usage. 185 * ename:VK_TOOL_PURPOSE_PROFILING_BIT_EXT specifies that the tool provides 186 profiling of API usage. 187 * ename:VK_TOOL_PURPOSE_TRACING_BIT_EXT specifies that the tool is 188 capturing data about the application's API usage, including anything 189 from simple logging to capturing data for later replay. 190 * ename:VK_TOOL_PURPOSE_ADDITIONAL_FEATURES_BIT_EXT specifies that the 191 tool provides additional API features/extensions on top of the 192 underlying implementation. 193 * ename:VK_TOOL_PURPOSE_MODIFYING_FEATURES_BIT_EXT specifies that the tool 194 modifies the API features/limits/extensions presented to the 195 application. 196ifdef::VK_EXT_debug_report,VK_EXT_debug_utils[] 197 * ename:VK_TOOL_PURPOSE_DEBUG_REPORTING_BIT_EXT specifies that the tool 198 reports additional information to the application via callbacks 199 specified by 200ifdef::VK_EXT_debug_report[] 201 flink:vkCreateDebugReportCallbackEXT 202endif::VK_EXT_debug_report[] 203ifdef::VK_EXT_debug_report+VK_EXT_debug_utils[] 204 or 205endif::VK_EXT_debug_report+VK_EXT_debug_utils[] 206ifdef::VK_EXT_debug_utils[] 207 flink:vkCreateDebugUtilsMessengerEXT 208endif::VK_EXT_debug_utils[] 209endif::VK_EXT_debug_report,VK_EXT_debug_utils[] 210ifdef::VK_EXT_debug_marker,VK_EXT_debug_utils[] 211 * ename:VK_TOOL_PURPOSE_DEBUG_MARKERS_BIT_EXT specifies that the tool 212 consumes 213ifdef::VK_EXT_debug_marker[] 214 <<debugging-debug-markers,debug markers>> 215endif::VK_EXT_debug_marker[] 216ifdef::VK_EXT_debug_marker+VK_EXT_debug_utils[] 217 or 218endif::VK_EXT_debug_marker+VK_EXT_debug_utils[] 219ifdef::VK_EXT_debug_utils[] 220 <<debugging-object-debug-annotation,object debug annotation>>, 221 <<debugging-queue-labels, queue labels>>, or 222 <<debugging-command-buffer-labels, command buffer labels>> 223endif::VK_EXT_debug_utils[] 224endif::VK_EXT_debug_marker,VK_EXT_debug_utils[] 225-- 226 227[open,refpage='VkToolPurposeFlagsEXT',desc='Bitmask of VkToolPurposeFlagBitsEXT',type='flags'] 228-- 229include::{generated}/api/flags/VkToolPurposeFlagsEXT.txt[] 230 231tlink:VkToolPurposeFlagsEXT is a bitmask type for setting a mask of zero or 232more elink:VkToolPurposeFlagBitsEXT. 233-- 234endif::VK_EXT_tooling_info[] 235