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