194 lines
7.7 KiB
Plaintext
194 lines
7.7 KiB
Plaintext
// This section is included inside the Debugging chapter (debugging.txt)
|
|
|
|
[[debugging-debug-report-callbacks]]
|
|
== Debug Report Callbacks
|
|
|
|
// refBegin vkCreateDebugReportCallbackEXT Create a debug report callback object
|
|
|
|
Debug report callbacks give more detailed feedback on the application's use
|
|
of Vulkan when events of interest occur.
|
|
|
|
To register a debug report callback, an application uses
|
|
flink:vkCreateDebugReportCallbackEXT.
|
|
|
|
include::../api/protos/vkCreateDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:instance the instance the callback will be logged on.
|
|
* pname:pCreateInfo points to a slink:VkDebugReportCallbackCreateInfoEXT
|
|
structure which defines the conditions under which this callback will be
|
|
called.
|
|
* pname:pCallback is a pointer to record the
|
|
sname:VkDebugReportCallbackEXT object created.
|
|
|
|
include::../validity/protos/vkCreateDebugReportCallbackEXT.txt[]
|
|
|
|
// refBegin VkDebugReportErrorEXT Unknown VK_EXT_debug_report enumeration type
|
|
|
|
include::../api/enums/VkDebugReportErrorEXT.txt[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The +VK_EXT_debug_report+ extension defines the elink:VkDebugReportErrorEXT
|
|
enumerant type, but does not currently explain what the enumeration is used
|
|
for.
|
|
It is included here for completeness.
|
|
====
|
|
|
|
// refBegin VkDebugReportCallbackCreateInfoEXT Structure specifying parameters of a newly created debug report callback
|
|
|
|
The definition of slink:VkDebugReportCallbackCreateInfoEXT is:
|
|
|
|
include::../api/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags indicate which event(s) will cause this callback to be
|
|
called.
|
|
Flags are interpreted as bitmasks and multiple may be set.
|
|
Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkDebugReportFlagBitsEXT Bitmask specifying events which cause a debug report callback
|
|
include::../api/enums/VkDebugReportFlagBitsEXT.txt[]
|
|
|
|
* ename:VK_DEBUG_REPORT_ERROR_BIT_EXT indicates an error that may cause
|
|
undefined results, including an application crash.
|
|
* ename:VK_DEBUG_REPORT_WARNING_BIT_EXT indicates use of Vulkan that may
|
|
expose an app 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 hasn't been filled.
|
|
In general if you see a warning but you know that the behavior is
|
|
intended/desired, then simply ignore the warning.
|
|
* ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a
|
|
potentially non-optimal use of Vulkan.
|
|
E.g. using flink:vkCmdClearColorImage when a RenderPass load_op would
|
|
have worked.
|
|
* ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT indicates an informational
|
|
message such as resource details that may be handy when debugging an
|
|
application.
|
|
* ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates diagnostic information
|
|
from the loader and layers.
|
|
--
|
|
+
|
|
* pname:pfnCallback is the application callback function to call.
|
|
* pname:pUserData is user data to be passed to the callback.
|
|
|
|
For each sname:VkDebugReportCallbackEXT that is created the flags determine
|
|
when that function is called.
|
|
A callback will be made for issues that match any bit set in its flags.
|
|
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 different way, log to system error log, etc.) An application may
|
|
receive multiple callbacks if multiple sname:VkDebugReportCallbackEXT
|
|
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).
|
|
|
|
include::../validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
|
|
|
|
// refBegin PFN_vkDebugReportCallbackEXT Application-defined debug report callback function
|
|
|
|
The prototype for the callback function implemented by the application is:
|
|
|
|
include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
|
|
this callback.
|
|
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
|
|
of object being used or created at the time the event was triggered.
|
|
* pname:object gives the object where the issue was detected.
|
|
pname:object may be ename:VK_NULL_OBJECT if there is no object
|
|
associated with the event.
|
|
* pname:location is a component (layer, driver, loader) defined value that
|
|
indicates the _location_ of the trigger.
|
|
This is an optional value.
|
|
* pname:messageCode is a layer-defined value indicating what test
|
|
triggered this callback.
|
|
* pname:pLayerPrefix is the abbreviation of the component making the
|
|
callback.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
* pname:pUserData is the user data given when the DebugReportCallback was
|
|
created.
|
|
|
|
The callback returns a basetype:VkBool32 that indicates to the calling layer
|
|
if the Vulkan call should: be aborted or not.
|
|
Applications should: always return ename:VK_FALSE so that they see the same
|
|
behavior with and without validation layers enabled.
|
|
|
|
If the application returns ename:VK_TRUE from its callback and the Vulkan
|
|
call being aborted returns a elink:VkResult, the layer will return
|
|
ename:VK_ERROR_VALIDATION_FAILED_EXT.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The primary expected use of ename:VK_ERROR_VALIDATION_FAILED_EXT is for
|
|
validation layer testing.
|
|
It is not expected that an application would see this error code during
|
|
normal use of the validation layers.
|
|
====
|
|
|
|
// refEnd PFN_vkDebugReportCallbackEXT
|
|
|
|
// vkDebugReportMessageEXT Inject a message into a debug stream
|
|
|
|
To inject its own messages into the debug stream, call:
|
|
|
|
include::../api/protos/vkDebugReportMessageEXT.txt[]
|
|
|
|
* pname:instance the instance the callback will be logged on.
|
|
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
|
|
this callback.
|
|
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
|
|
of object being used or created at the time the event was triggered.
|
|
* pname:object is object where the issue was detected.
|
|
pname:object may be ename:VK_NULL_OBJECT if there is no object
|
|
associated with the event.
|
|
* pname:location is a component (layer, driver, loader) defined value that
|
|
indicates the _location_ of the trigger.
|
|
This is an optional value.
|
|
* pname:messageCode is a layer-defined value indicating what test
|
|
triggered this callback.
|
|
* pname:pLayerPrefix is the abbreviation of the component making the
|
|
callback.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
|
|
The call will propagate through the layers and cause a callback to the
|
|
application.
|
|
The parameters are passed on to the callback in addition to the
|
|
pname:pUserData value that was defined at the time the callback was
|
|
registered.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:object may: be a Vulkan object
|
|
****
|
|
|
|
include::../validity/protos/vkDebugReportMessageEXT.txt[]
|
|
|
|
// refBegin vkDestroyDebugReportCallbackEXT Destroy a debug report callback object
|
|
|
|
To destroy a sname:VkDebugReportCallbackEXT object, call:
|
|
|
|
include::../api/protos/vkDestroyDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:instance the instance where the callback was created.
|
|
* pname:callback the sname:VkDebugReportCallbackEXT object to destroy.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* If no sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[]
|