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