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