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.
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.
Example uses: Create three callback objects. One will log errors and
warnings to the debug console using Windows OutputDebugString. The
second will cause the debugger to break at that callback when an error
happens and the third will log warnings to stdout.
1) What is the hierarchy / seriousness of the message flags? E.g.
ERROR > WARN > PERF_WARN …
RESOLVED: There is no specific hierarchy. Each bit is independent
and should be checked via bitwise AND. For example:
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 (ERROR >
WARN > PERF, WARN > DEBUG > 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.
RESOLVED: It may not be very useful, but we do not need VU statement
requiring the DebugReportCallbackCreateInfoEXT::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.
RESOLVED: 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 C and C++ compilers in both 32-bit and 64-bit ABIs. We
recommend applications use the same cast that the validation layers use:
To ensure that destroyDebugReportCallbackEXT is always called: pass
bracket (or the allocate function from your
favourite resource management library) as the last argument.
To just extract the pair pass (,) as the last argument.
callback is the DebugReportCallbackEXT
object to destroy. callback is an externally synchronized object and
must not be used on more than one thread at a time. This means that
destroyDebugReportCallbackEXTmust not be called when a callback is
active.
vkDebugReportMessageEXT - Inject a message into a debug stream
Description
The call will propagate through the layers and generate callback(s) as
indicated by the message’s flags. The parameters are passed on to the
callback in addition to the pUserData value that was defined at the
time the callback was registered.
VkDebugReportCallbackCreateInfoEXT - Structure specifying parameters of
a newly created debug report callback
Description
For each DebugReportCallbackEXT that is
created the DebugReportCallbackCreateInfoEXT::flags determine when
that DebugReportCallbackCreateInfoEXT::pfnCallback is called. When
an event happens, the implementation will do a bitwise AND of the
event’s DebugReportFlagBitsEXT flags to each
DebugReportCallbackEXT object’s flags. For
each non-zero result the corresponding callback will be called. The
callback will come directly from the component that detected the event,
unless some other layer intercepts the calls for its own purposes
(filter them in a different way, log to a system error log, etc.).
An application may receive multiple callbacks if multiple
DebugReportCallbackEXT objects were created.
A callback will always be executed in the same thread as the originating
Vulkan call.
A callback may be called from multiple threads simultaneously (if the
application is making Vulkan calls from multiple threads).
VkDebugReportFlagBitsEXT - Bitmask specifying events which cause a debug
report callback
Description
DEBUG_REPORT_ERROR_BIT_EXT specifies that the application has
violated a valid usage condition of the specification.
DEBUG_REPORT_WARNING_BIT_EXT specifies use of Vulkan that may
expose an application bug. Such cases may not be immediately
harmful, such as a fragment shader outputting to a location with no
attachment. Other cases may point to behavior that is almost
certainly bad when unintended such as using an image whose memory
has not been filled. In general if you see a warning but you know
that the behavior is intended/desired, then simply ignore the
warning.
The primary expected use of ERROR_VALIDATION_FAILED_EXT is for
validation layer testing to prevent invalid commands from reaching the
ICD. It is not expected that an application would see this error code
during normal use of the validation layers. If an application returns
TRUE in
DebugUtilsMessengerCallbackDataEXT,
the validation layers will return this error code instead of passing the
command down the dispatch chain.
The callback returns a Bool32, which is
interpreted in a layer-specified manner. The application should always
return FALSE. The
TRUE value is reserved for use in layer
development.