/ appendices / VK_EXT_debug_report.txt
VK_EXT_debug_report.txt
1 include::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 13 Due to the nature of the Vulkan interface, there is very little error 14 information available to the developer and application. 15 By enabling optional validation layers and using the `VK_EXT_debug_report` 16 extension, developers can: obtain much more detailed feedback on the 17 application's use of Vulkan. 18 This extension defines a way for layers and the implementation to call back 19 to 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 54 with the validation layers. 55 Some callbacks may log the information to a file, others may cause a debug 56 break point or other application defined behavior. 57 An application can: register callbacks even when no validation layers are 58 enabled, but they will only be called for loader and, if implemented, driver 59 events. 60 61 To capture events that occur while creating or destroying an instance an 62 application can: link a slink:VkDebugReportCallbackCreateInfoEXT structure 63 to the pname:pNext element of the slink:VkInstanceCreateInfo structure given 64 to flink:vkCreateInstance. 65 This callback is only valid for the duration of the flink:vkCreateInstance 66 and the flink:vkDestroyInstance call. 67 Use flink:vkCreateDebugReportCallbackEXT to create persistent callback 68 objects. 69 70 Example uses: Create three callback objects. 71 One will log errors and warnings to the debug console using Windows 72 code:OutputDebugString. 73 The second will cause the debugger to break at that callback when an error 74 happens 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 ==== 121 In the initial release of the `VK_EXT_debug_report` extension, the token 122 ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used. 123 Starting in version 2 of the extension branch, 124 ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT is used 125 instead for consistency with Vulkan naming rules. 126 The older enum is still available for backwards compatibility. 127 ==== 128 129 [NOTE] 130 .Note 131 ==== 132 In the initial release of the `VK_EXT_debug_report` extension, the token 133 ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used. 134 Starting in version 8 of the extension branch, 135 ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT is used 136 instead for consistency with Vulkan naming rules. 137 The older enum is still available for backwards compatibility. 138 ==== 139 140 141 === Issues 142 143 1) What is the hierarchy / seriousness of the message flags? E.g. 144 etext:ERROR > etext:WARN > etext:PERF_WARN ... 145 146 *RESOLVED*: There is no specific hierarchy. 147 Each bit is independent and should be checked via bitwise AND. 148 For 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 160 The validation layers do use them in a hierarchical way (etext:ERROR > 161 etext:WARN > etext:PERF, etext:WARN > etext:DEBUG > etext:INFO) and they (at 162 least at the time of this writing) only set one bit at a time. 163 But it is not a requirement of this extension. 164 165 It is possible that a layer may intercept and change, or augment the flags 166 with extension values the application's debug report handler may not be 167 familiar with, so it is important to treat each flag independently. 168 169 2) Should there be a VU requiring 170 slink:VkDebugReportCallbackCreateInfoEXT::pname:flags to be non-zero? 171 172 *RESOLVED*: It may not be very useful, but we do not need VU statement 173 requiring the sname:VkDebugReportCallbackCreateInfoEXT::pname:msgFlags at 174 create-time to be non-zero. 175 One can imagine that apps may prefer it as it allows them to set the mask as 176 desired - including nothing - at runtime without having to check. 177 178 3) What is the difference between ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT and 179 ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT? 180 181 *RESOLVED*: ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies information that 182 could 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