Vulkan-Docs/doc/specs/vulkan/chapters/VK_EXT_debug_report.txt

// 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 an unexpected use.
    E.g. Not destroying objects prior to destroying the containing object or
    potential inconsistencies between descriptor set layout and the layout
    in the corresponding shader, etc.
  * 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
  * pname:pLayerPrefix must: be a `NULL` terminated string
  * pname:pMessage must: be a `NULL` terminated string
****

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[]