[[VK_EXT_debug_report]]
== VK_EXT_debug_report

*Name String*::
    VK_EXT_debug_report
*Extension Type*::
    Instance
*Registered Extension Number*::
    12
*Last Modified Date*::
    2016-09-17
*Revision*::
    3
*IP Status*::
    No known IP claims.
*Dependencies*::
  - This extension is written against version 1.0.27 of the Vulkan API.
*Contributors*::
  - Courtney Goeltzenleuchter, LunarG
  - Dan Ginsburg, Valve
  - Jon Ashburn, LunarG
*Contacts*::
  - Courtney Goeltzenleuchter

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 define a way for layers and the implementation to call back
to the application for events of interest to the application.

=== New Object Types

  * slink:VkDebugReportCallbackCreateInfoEXT

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT
  * Extending elink:VkResult:
  ** ename:VK_ERROR_VALIDATION_FAILED_EXT

=== New Enums

  * elink:VkDebugReportFlagBitsEXT
  * elink:VkDebugReportObjectTypeEXT
  * elink:VkDebugReportErrorEXT

=== New Structures

  * slink:VkDebugReportCallbackCreateInfoEXT

=== New Functions

  * flink:vkCreateDebugReportCallbackEXT
  * flink:vkDestroyDebugReportCallbackEXT
  * flink:vkDebugReportMessageEXT

=== New Function Pointers

  * tlink:PFN_vkDebugReportCallbackEXT


=== 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 issues found while creating or destroying an instance an
application can link a sname:VkDebugReportCallbackCreateInfoEXT structure to
the pname:pNext element of the sname:VkInstanceCreateInfo structure given to
fname:vkCreateInstance.
This callback is only valid for the duration of the fname:vkCreateInstance
and the fname:vkDestroyInstance call.
Use flink:vkCreateDebugReportCallbackEXT to create persistent callback
objects.

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.
[source,{basebackend@docbook:c++:cpp}]
------------------------------------------------------------------------------
    VkResult res;
    VkDebugReportCallbackEXT cb1, cb2, cb3;

    VkDebugReportCallbackCreateInfoEXT callback1 = {
            VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,    // sType
            NULL,                                                       // pNext
            VK_DEBUG_REPORT_ERROR_BIT_EXT |                             // flags
            VK_DEBUG_REPORT_WARNING_BIT_EXT,
            myOutputDebugString,                                        // pfnCallback
            NULL                                                        // pUserData
    };
    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 = {
            VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT,    // sType
            NULL,                                                       // pNext
            VK_DEBUG_REPORT_WARNING_BIT_EXT,                            // flags
            mystdOutLogger,                                             // pfnCallback
            NULL                                                        // pUserData
    };
    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.
====


=== Issues

[NOTE]
.Note
====
There are no issues in the current spec.
We should probably add some.
====

=== Version History

[NOTE]
.Note
====
There is no revision history in the current spec.
We should probably add some.
====