1// Copyright 2015-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_EXT_debug_report.adoc[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2020-12-14 11*IP Status*:: 12 No known IP claims. 13*Contributors*:: 14 - Courtney Goeltzenleuchter, LunarG 15 - Dan Ginsburg, Valve 16 - Jon Ashburn, LunarG 17 - Mark Lobodzinski, LunarG 18 19=== Description 20 21Due to the nature of the Vulkan interface, there is very little error 22information available to the developer and application. 23By enabling optional validation layers and using the `VK_EXT_debug_report` 24extension, developers can: obtain much more detailed feedback on the 25application's use of Vulkan. 26This extension defines a way for layers and the implementation to call back 27to the application for events of interest to the application. 28 29include::{generated}/interfaces/VK_EXT_debug_report.adoc[] 30 31=== Examples 32 33`VK_EXT_debug_report` allows an application to register multiple callbacks 34with the validation layers. 35Some callbacks may log the information to a file, others may cause a debug 36break point or other application defined behavior. 37An application can: register callbacks even when no validation layers are 38enabled, but they will only be called for loader and, if implemented, driver 39events. 40 41To capture events that occur while creating or destroying an instance an 42application can: link a slink:VkDebugReportCallbackCreateInfoEXT structure 43to the pname:pNext element of the slink:VkInstanceCreateInfo structure given 44to flink:vkCreateInstance. 45 46Example uses: Create three callback objects. 47One will log errors and warnings to the debug console using Windows 48code:OutputDebugString. 49The second will cause the debugger to break at that callback when an error 50happens and the third will log warnings to stdout. 51 52[source,c++] 53---- 54 VkResult res; 55 VkDebugReportCallbackEXT cb1, cb2, cb3; 56 57 VkDebugReportCallbackCreateInfoEXT callback1 = { 58 .sType = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, 59 .pNext = NULL, 60 .flags = VK_DEBUG_REPORT_ERROR_BIT_EXT | 61 VK_DEBUG_REPORT_WARNING_BIT_EXT, 62 .pfnCallback = myOutputDebugString, 63 .pUserData = NULL 64 }; 65 res = vkCreateDebugReportCallbackEXT(instance, &callback1, &cb1); 66 if (res != VK_SUCCESS) 67 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 68 69 callback.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT; 70 callback.pfnCallback = myDebugBreak; 71 callback.pUserData = NULL; 72 res = vkCreateDebugReportCallbackEXT(instance, &callback, &cb2); 73 if (res != VK_SUCCESS) 74 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 75 76 VkDebugReportCallbackCreateInfoEXT callback3 = { 77 .sType = VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, 78 .pNext = NULL, 79 .flags = VK_DEBUG_REPORT_WARNING_BIT_EXT, 80 .pfnCallback = mystdOutLogger, 81 .pUserData = NULL 82 }; 83 res = vkCreateDebugReportCallbackEXT(instance, &callback3, &cb3); 84 if (res != VK_SUCCESS) 85 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 86 87 ... 88 89 /* remove callbacks when cleaning up */ 90 vkDestroyDebugReportCallbackEXT(instance, cb1); 91 vkDestroyDebugReportCallbackEXT(instance, cb2); 92 vkDestroyDebugReportCallbackEXT(instance, cb3); 93---- 94 95[NOTE] 96.Note 97==== 98In the initial release of the `VK_EXT_debug_report` extension, the token 99ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used. 100Starting in version 2 of the extension branch, 101ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT is used 102instead for consistency with Vulkan naming rules. 103The older enum is still available for backwards compatibility. 104==== 105 106[NOTE] 107.Note 108==== 109In the initial release of the `VK_EXT_debug_report` extension, the token 110ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used. 111Starting in version 8 of the extension branch, 112ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT is used 113instead for consistency with Vulkan naming rules. 114The older enum is still available for backwards compatibility. 115==== 116 117 118=== Issues 119 1201) What is the hierarchy / seriousness of the message flags? E.g. 121etext:ERROR > etext:WARN > etext:PERF_WARN ... 122 123*RESOLVED*: There is no specific hierarchy. 124Each bit is independent and should be checked via bitwise AND. 125For example: 126 127[source,c++] 128---- 129 if (localFlags & VK_DEBUG_REPORT_ERROR_BIT_EXT) { 130 process error message 131 } 132 if (localFlags & VK_DEBUG_REPORT_DEBUG_BIT_EXT) { 133 process debug message 134 } 135---- 136 137The validation layers do use them in a hierarchical way (etext:ERROR > 138etext:WARN > etext:PERF, etext:WARN > etext:DEBUG > etext:INFO) and they (at 139least at the time of this writing) only set one bit at a time. 140But it is not a requirement of this extension. 141 142It is possible that a layer may intercept and change, or augment the flags 143with extension values the application's debug report handler may not be 144familiar with, so it is important to treat each flag independently. 145 1462) Should there be a VU requiring 147slink:VkDebugReportCallbackCreateInfoEXT::pname:flags to be non-zero? 148 149*RESOLVED*: It may not be very useful, but we do not need VU statement 150requiring the sname:VkDebugReportCallbackCreateInfoEXT::pname:msgFlags at 151create-time to be non-zero. 152One can imagine that apps may prefer it as it allows them to set the mask as 153desired - including nothing - at runtime without having to check. 154 1553) What is the difference between ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT and 156ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT? 157 158*RESOLVED*: ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies information that 159could be useful debugging the Vulkan implementation itself. 160 1614) How do you compare handles returned by the debug_report callback to the 162application's handles? 163 164*RESOLVED*: Due to the different nature of dispatchable and nondispatchable 165handles there is no generic way (that we know of) that works for common 166compilers with 32bit, 64bit, C and C++. 167We recommend applications use the same cast that the validation layers use: 168+ 169[source,c++] 170---- 171reinterpret_cast<uint64_t &>(dispatchableHandle) 172(uint64_t)(nondispatchableHandle) 173---- 174+ 175This does require that the app treat dispatchable and nondispatchable 176handles differently. 177 178=== Version History 179 180 * Revision 1, 2015-05-20 (Courtney Goetzenleuchter) 181 ** Initial draft, based on LunarG KHR spec, other KHR specs 182 183 * Revision 2, 2016-02-16 (Courtney Goetzenleuchter) 184 ** Update usage, documentation 185 186 * Revision 3, 2016-06-14 (Courtney Goetzenleuchter) 187 ** Update VK_EXT_DEBUG_REPORT_SPEC_VERSION to indicate added support for 188 vkCreateInstance and vkDestroyInstance 189 190 * Revision 4, 2016-12-08 (Mark Lobodzinski) 191 ** Added Display_KHR, DisplayModeKHR extension objects 192 ** Added ObjectTable_NVX, IndirectCommandsLayout_NVX extension objects 193 ** Bumped spec revision 194 ** Retroactively added version history 195 196 * Revision 5, 2017-01-31 (Baldur Karlsson) 197 ** Moved definition of elink:VkDebugReportObjectTypeEXT from debug marker 198 chapter 199 200 * Revision 6, 2017-01-31 (Baldur Karlsson) 201 ** Added VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT 202 203 * Revision 7, 2017-04-20 (Courtney Goeltzenleuchter) 204 ** Clarify wording and address questions from developers. 205 206 * Revision 8, 2017-04-21 (Courtney Goeltzenleuchter) 207 ** Remove unused enum VkDebugReportErrorEXT 208 209 * Revision 9, 2017-09-12 (Tobias Hector) 210 ** Added interactions with Vulkan 1.1 211 212 * Revision 10, 2020-12-14 (Courtney Goetzenleuchter) 213 ** Add issue 4 discussing matching handles returned by the extension, 214 based on suggestion in public issue 368. 215