1// Copyright 2018-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5// This section is included inside the Debugging chapter (debugging.adoc) 6 7 8[[debugging-debug-report-callbacks]] 9== Debug Report Callbacks 10 11[open,refpage='VkDebugReportCallbackEXT',desc='Opaque handle to a debug report callback object',type='handles'] 12-- 13Debug report callbacks are represented by sname:VkDebugReportCallbackEXT 14handles: 15 16include::{generated}/api/handles/VkDebugReportCallbackEXT.adoc[] 17-- 18 19[open,refpage='vkCreateDebugReportCallbackEXT',desc='Create a debug report callback object',type='protos'] 20-- 21Debug report callbacks give more detailed feedback on the application's use 22of Vulkan when events of interest occur. 23 24To register a debug report callback, an application uses 25flink:vkCreateDebugReportCallbackEXT. 26 27include::{generated}/api/protos/vkCreateDebugReportCallbackEXT.adoc[] 28 29 * pname:instance is the instance the callback will be logged on. 30 * pname:pCreateInfo is a pointer to a 31 slink:VkDebugReportCallbackCreateInfoEXT structure defining the 32 conditions under which this callback will be called. 33 * pname:pAllocator controls host memory allocation as described in the 34 <<memory-allocation, Memory Allocation>> chapter. 35 * pname:pCallback is a pointer to a slink:VkDebugReportCallbackEXT handle 36 in which the created object is returned. 37 38include::{generated}/validity/protos/vkCreateDebugReportCallbackEXT.adoc[] 39-- 40 41[open,refpage='VkDebugReportCallbackCreateInfoEXT',desc='Structure specifying parameters of a newly created debug report callback',type='structs'] 42-- 43The definition of slink:VkDebugReportCallbackCreateInfoEXT is: 44 45include::{generated}/api/structs/VkDebugReportCallbackCreateInfoEXT.adoc[] 46 47 * pname:sType is the type of this structure. 48 * pname:pNext is `NULL` or a pointer to a structure extending this 49 structure. 50 * pname:flags is a bitmask of elink:VkDebugReportFlagBitsEXT specifying 51 which event(s) will cause this callback to be called. 52 * pname:pfnCallback is the application callback function to call. 53 * pname:pUserData is user data to be passed to the callback. 54 55For each sname:VkDebugReportCallbackEXT that is created the 56sname:VkDebugReportCallbackCreateInfoEXT::pname:flags determine when that 57sname:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback is called. 58When an event happens, the implementation will do a bitwise AND of the 59event's elink:VkDebugReportFlagBitsEXT flags to each 60sname:VkDebugReportCallbackEXT object's flags. 61For each non-zero result the corresponding callback will be called. 62The callback will come directly from the component that detected the event, 63unless some other layer intercepts the calls for its own purposes (filter 64them in a different way, log to a system error log, etc.). 65 66An application may: receive multiple callbacks if multiple 67sname:VkDebugReportCallbackEXT objects were created. 68A callback will always be executed in the same thread as the originating 69Vulkan call. 70 71A callback may be called from multiple threads simultaneously (if the 72application is making Vulkan calls from multiple threads). 73 74include::{generated}/validity/structs/VkDebugReportCallbackCreateInfoEXT.adoc[] 75-- 76 77[open,refpage='VkDebugReportFlagBitsEXT',desc='Bitmask specifying events which cause a debug report callback',type='enums'] 78-- 79Bits which can: be set in 80slink:VkDebugReportCallbackCreateInfoEXT::pname:flags, specifying events 81which cause a debug report, are: 82 83include::{generated}/api/enums/VkDebugReportFlagBitsEXT.adoc[] 84 85 * ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that the application has 86 violated a valid usage condition of the specification. 87 * ename:VK_DEBUG_REPORT_WARNING_BIT_EXT specifies use of Vulkan that may: 88 expose an app bug. 89 Such cases may not be immediately harmful, such as a fragment shader 90 outputting to a location with no attachment. 91 Other cases may: point to behavior that is almost certainly bad when 92 unintended such as using an image whose memory has not been filled. 93 In general if you see a warning but you know that the behavior is 94 intended/desired, then simply ignore the warning. 95 * ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT specifies a 96 potentially non-optimal use of Vulkan, e.g. using 97 flink:vkCmdClearColorImage when setting 98 slink:VkAttachmentDescription::pname:loadOp to 99 ename:VK_ATTACHMENT_LOAD_OP_CLEAR would have worked. 100 * ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT specifies an informational 101 message such as resource details that may be handy when debugging an 102 application. 103 * ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies diagnostic information 104 from the implementation and layers. 105-- 106 107[open,refpage='VkDebugReportFlagsEXT',desc='Bitmask of VkDebugReportFlagBitsEXT',type='flags'] 108-- 109include::{generated}/api/flags/VkDebugReportFlagsEXT.adoc[] 110 111tname:VkDebugReportFlagsEXT is a bitmask type for setting a mask of zero or 112more elink:VkDebugReportFlagBitsEXT. 113-- 114 115[open,refpage='PFN_vkDebugReportCallbackEXT',desc='Application-defined debug report callback function',type='funcpointers'] 116-- 117The prototype for the 118slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback function 119implemented by the application is: 120 121include::{generated}/api/funcpointers/PFN_vkDebugReportCallbackEXT.adoc[] 122 123 * pname:flags specifies the elink:VkDebugReportFlagBitsEXT that triggered 124 this callback. 125 * pname:objectType is a elink:VkDebugReportObjectTypeEXT value specifying 126 the type of object being used or created at the time the event was 127 triggered. 128 * pname:object is the object where the issue was detected. 129 If pname:objectType is ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, 130 pname:object is undefined:. 131 * pname:location is a component (layer, driver, loader) defined value 132 specifying the _location_ of the trigger. 133 This is an optional: value. 134 * pname:messageCode is a layer-defined value indicating what test 135 triggered this callback. 136 * pname:pLayerPrefix is a null-terminated string that is an abbreviation 137 of the name of the component making the callback. 138 pname:pLayerPrefix is only valid for the duration of the callback. 139 * pname:pMessage is a null-terminated string detailing the trigger 140 conditions. 141 pname:pMessage is only valid for the duration of the callback. 142 * pname:pUserData is the user data given when the 143 slink:VkDebugReportCallbackEXT was created. 144 145The callback must: not call fname:vkDestroyDebugReportCallbackEXT. 146 147The callback returns a basetype:VkBool32, which is interpreted in a 148layer-specified manner. 149The application should: always return ename:VK_FALSE. 150The ename:VK_TRUE value is reserved for use in layer development. 151 152pname:object must: be a Vulkan object or dlink:VK_NULL_HANDLE. 153If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT and 154pname:object is not dlink:VK_NULL_HANDLE, pname:object must: be a Vulkan 155object of the corresponding type associated with pname:objectType as defined 156in <<debug-report-object-types>>. 157-- 158 159[open,refpage='VkDebugReportObjectTypeEXT',desc='Specify the type of an object handle',type='enums'] 160-- 161Possible values passed to the pname:objectType parameter of the callback 162function specified by 163slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback, specifying the 164type of object handle being reported, are: 165 166include::{generated}/api/enums/VkDebugReportObjectTypeEXT.adoc[] 167 168[[debug-report-object-types]] 169.`VkDebugReportObjectTypeEXT` and Vulkan Handle Relationship 170[width="80%",cols="<35,<23",options="header"] 171|==== 172| elink:VkDebugReportObjectTypeEXT | Vulkan Handle Type 173| ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT | Unknown/Undefined Handle 174| ename:VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT | slink:VkInstance 175| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT | slink:VkPhysicalDevice 176| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT | slink:VkDevice 177| ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT | slink:VkQueue 178| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT | slink:VkSemaphore 179| ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT | slink:VkCommandBuffer 180| ename:VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT | slink:VkFence 181| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT | slink:VkDeviceMemory 182| ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT | slink:VkBuffer 183| ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT | slink:VkImage 184| ename:VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT | slink:VkEvent 185| ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT | slink:VkQueryPool 186| ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT | slink:VkBufferView 187| ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT | slink:VkImageView 188| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT | slink:VkShaderModule 189| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT | slink:VkPipelineCache 190| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT | slink:VkPipelineLayout 191| ename:VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT | slink:VkRenderPass 192| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT | slink:VkPipeline 193| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT | slink:VkDescriptorSetLayout 194| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT | slink:VkSampler 195| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT | slink:VkDescriptorPool 196| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT | slink:VkDescriptorSet 197| ename:VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT | slink:VkFramebuffer 198| ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT | slink:VkCommandPool 199ifdef::VK_KHR_surface[] 200| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT | slink:VkSurfaceKHR 201endif::VK_KHR_surface[] 202ifdef::VK_KHR_surface[] 203| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT | slink:VkSwapchainKHR 204endif::VK_KHR_surface[] 205| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT | slink:VkDebugReportCallbackEXT 206ifdef::VK_KHR_display[] 207| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT | slink:VkDisplayKHR 208| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT | slink:VkDisplayModeKHR 209endif::VK_KHR_display[] 210ifndef::VK_VERSION_1_1[] 211ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 212| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT | slink:VkDescriptorUpdateTemplate 213endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] 214endif::VK_VERSION_1_1[] 215ifdef::VK_VERSION_1_1[] 216| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT | slink:VkDescriptorUpdateTemplate 217endif::VK_VERSION_1_1[] 218|==== 219 220[NOTE] 221.Note 222==== 223The primary expected use of ename:VK_ERROR_VALIDATION_FAILED_EXT is for 224validation layer testing. 225It is not expected that an application would see this error code during 226normal use of the validation layers. 227==== 228-- 229 230[open,refpage='vkDebugReportMessageEXT',desc='Inject a message into a debug stream',type='protos'] 231-- 232To inject its own messages into the debug stream, call: 233 234include::{generated}/api/protos/vkDebugReportMessageEXT.adoc[] 235 236 * pname:instance is the debug stream's slink:VkInstance. 237 * pname:flags specifies the elink:VkDebugReportFlagBitsEXT classification 238 of this event/message. 239 * pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the 240 type of object being used or created at the time the event was 241 triggered. 242 * pname:object is the object where the issue was detected. 243 pname:object can: be dlink:VK_NULL_HANDLE if there is no object 244 associated with the event. 245 * pname:location is an application defined value. 246 * pname:messageCode is an application defined value. 247 * pname:pLayerPrefix is the abbreviation of the component making this 248 event/message. 249 * pname:pMessage is a null-terminated string detailing the trigger 250 conditions. 251 252The call will propagate through the layers and generate callback(s) as 253indicated by the message's flags. 254The parameters are passed on to the callback in addition to the 255pname:pUserData value that was defined at the time the callback was 256registered. 257 258.Valid Usage 259**** 260 * [[VUID-vkDebugReportMessageEXT-object-01241]] 261 pname:object must: be a Vulkan object or dlink:VK_NULL_HANDLE 262 * [[VUID-vkDebugReportMessageEXT-objectType-01498]] 263 If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT 264 and pname:object is not dlink:VK_NULL_HANDLE, pname:object must: be a 265 Vulkan object of the corresponding type associated with pname:objectType 266 as defined in <<debug-report-object-types>> 267**** 268 269include::{generated}/validity/protos/vkDebugReportMessageEXT.adoc[] 270-- 271 272[open,refpage='vkDestroyDebugReportCallbackEXT',desc='Destroy a debug report callback object',type='protos'] 273-- 274To destroy a sname:VkDebugReportCallbackEXT object, call: 275 276include::{generated}/api/protos/vkDestroyDebugReportCallbackEXT.adoc[] 277 278 * pname:instance is the instance where the callback was created. 279 * pname:callback is the slink:VkDebugReportCallbackEXT object to destroy. 280 pname:callback is an externally synchronized object and must: not be 281 used on more than one thread at a time. 282 This means that fname:vkDestroyDebugReportCallbackEXT must: not be 283 called when a callback is active. 284 * pname:pAllocator controls host memory allocation as described in the 285 <<memory-allocation, Memory Allocation>> chapter. 286 287.Valid Usage 288**** 289 * [[VUID-vkDestroyDebugReportCallbackEXT-instance-01242]] 290 If sname:VkAllocationCallbacks were provided when pname:callback was 291 created, a compatible set of callbacks must: be provided here 292 * [[VUID-vkDestroyDebugReportCallbackEXT-instance-01243]] 293 If no sname:VkAllocationCallbacks were provided when pname:callback was 294 created, pname:pAllocator must: be `NULL` 295**** 296 297include::{generated}/validity/protos/vkDestroyDebugReportCallbackEXT.adoc[] 298-- 299