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