1// Copyright 2015-2021 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_EXT_debug_report.txt[] 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.txt[] 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[source,c++] 52------------------------------------------------------------------------------ 53 VkResult res; 54 VkDebugReportCallbackEXT cb1, cb2, cb3; 55 56 VkDebugReportCallbackCreateInfoEXT callback1 = { 57 VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType 58 NULL, // pNext 59 VK_DEBUG_REPORT_ERROR_BIT_EXT | // flags 60 VK_DEBUG_REPORT_WARNING_BIT_EXT, 61 myOutputDebugString, // pfnCallback 62 NULL // pUserData 63 }; 64 res = vkCreateDebugReportCallbackEXT(instance, &callback1, &cb1); 65 if (res != VK_SUCCESS) 66 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 67 68 callback.flags = VK_DEBUG_REPORT_ERROR_BIT_EXT; 69 callback.pfnCallback = myDebugBreak; 70 callback.pUserData = NULL; 71 res = vkCreateDebugReportCallbackEXT(instance, &callback, &cb2); 72 if (res != VK_SUCCESS) 73 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 74 75 VkDebugReportCallbackCreateInfoEXT callback3 = { 76 VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT, // sType 77 NULL, // pNext 78 VK_DEBUG_REPORT_WARNING_BIT_EXT, // flags 79 mystdOutLogger, // pfnCallback 80 NULL // pUserData 81 }; 82 res = vkCreateDebugReportCallbackEXT(instance, &callback3, &cb3); 83 if (res != VK_SUCCESS) 84 /* Do error handling for VK_ERROR_OUT_OF_MEMORY */ 85 86 ... 87 88 /* remove callbacks when cleaning up */ 89 vkDestroyDebugReportCallbackEXT(instance, cb1); 90 vkDestroyDebugReportCallbackEXT(instance, cb2); 91 vkDestroyDebugReportCallbackEXT(instance, cb3); 92------------------------------------------------------------------------------ 93 94[NOTE] 95.Note 96==== 97In the initial release of the `VK_EXT_debug_report` extension, the token 98ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used. 99Starting in version 2 of the extension branch, 100ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT is used 101instead for consistency with Vulkan naming rules. 102The older enum is still available for backwards compatibility. 103==== 104 105[NOTE] 106.Note 107==== 108In the initial release of the `VK_EXT_debug_report` extension, the token 109ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used. 110Starting in version 8 of the extension branch, 111ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT is used 112instead for consistency with Vulkan naming rules. 113The older enum is still available for backwards compatibility. 114==== 115 116 117=== Issues 118 1191) What is the hierarchy / seriousness of the message flags? E.g. 120etext:ERROR > etext:WARN > etext:PERF_WARN ... 121 122*RESOLVED*: There is no specific hierarchy. 123Each bit is independent and should be checked via bitwise AND. 124For example: 125 126[source,c++] 127---------------------------------------- 128 if (localFlags & VK_DEBUG_REPORT_ERROR_BIT_EXT) { 129 process error message 130 } 131 if (localFlags & VK_DEBUG_REPORT_DEBUG_BIT_EXT) { 132 process debug message 133 } 134---------------------------------------- 135 136The validation layers do use them in a hierarchical way (etext:ERROR > 137etext:WARN > etext:PERF, etext:WARN > etext:DEBUG > etext:INFO) and they (at 138least at the time of this writing) only set one bit at a time. 139But it is not a requirement of this extension. 140 141It is possible that a layer may intercept and change, or augment the flags 142with extension values the application's debug report handler may not be 143familiar with, so it is important to treat each flag independently. 144 1452) Should there be a VU requiring 146slink:VkDebugReportCallbackCreateInfoEXT::pname:flags to be non-zero? 147 148*RESOLVED*: It may not be very useful, but we do not need VU statement 149requiring the sname:VkDebugReportCallbackCreateInfoEXT::pname:msgFlags at 150create-time to be non-zero. 151One can imagine that apps may prefer it as it allows them to set the mask as 152desired - including nothing - at runtime without having to check. 153 1543) What is the difference between ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT and 155ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT? 156 157*RESOLVED*: ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies information that 158could be useful debugging the Vulkan implementation itself. 159 1604) How do you compare handles returned by the debug_report callback to the 161application's handles? 162 163*RESOLVED*: Due to the different nature of dispatchable and nondispatchable 164handles there is no generic way (that we know of) that works for common 165compilers with 32bit, 64bit, C and C++. 166We recommend applications use the same cast that the validation layers use: 167+ 168[source,c++] 169---- 170reinterpret_cast<uint64_t &>(dispatchableHandle) 171(uint64_t)(nondispatchableHandle) 172---- 173+ 174This does require that the app treat dispatchable and nondispatchable 175handles differently. 176 177=== Version History 178 179 * Revision 1, 2015-05-20 (Courtney Goetzenleuchter) 180 - Initial draft, based on LunarG KHR spec, other KHR specs 181 182 * Revision 2, 2016-02-16 (Courtney Goetzenleuchter) 183 - Update usage, documentation 184 185 * Revision 3, 2016-06-14 (Courtney Goetzenleuchter) 186 - Update VK_EXT_DEBUG_REPORT_SPEC_VERSION to indicate added support for 187 vkCreateInstance and vkDestroyInstance 188 189 * Revision 4, 2016-12-08 (Mark Lobodzinski) 190 - Added Display_KHR, DisplayModeKHR extension objects 191 - Added ObjectTable_NVX, IndirectCommandsLayout_NVX extension objects 192 - Bumped spec revision 193 - Retroactively added version history 194 195 * Revision 5, 2017-01-31 (Baldur Karlsson) 196 - Moved definition of elink:VkDebugReportObjectTypeEXT from debug marker 197 chapter 198 199 * Revision 6, 2017-01-31 (Baldur Karlsson) 200 - Added VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT 201 202 * Revision 7, 2017-04-20 (Courtney Goeltzenleuchter) 203 - Clarify wording and address questions from developers. 204 205 * Revision 8, 2017-04-21 (Courtney Goeltzenleuchter) 206 - Remove unused enum VkDebugReportErrorEXT 207 208 * Revision 9, 2017-09-12 (Tobias Hector) 209 - Added interactions with Vulkan 1.1 210 211 * Revision 10, 2020-12-14 (Courtney Goetzenleuchter) 212 - Add issue 4 discussing matching handles returned by the extension, 213 based on suggestion in public issue 368. 214