VK_EXT_debug_report(3)

# VK_EXT_debug_report(3) Manual Page

## Name

VK_EXT_debug_report - instance extension

Loading… please wait.

## Registered Extension Number

12

## Revision

10

## Extension and Version Dependencies

- Requires Vulkan 1.0

## Deprecation state

- Deprecated by `VK_EXT_debug_utils` extension

## Special Use

- Debugging tools

## Contact

- Courtney Goeltzenleuchter courtney-g

## 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.

## New Object Types

- VkDebugReportCallbackEXT

## New Commands

- vkCreateDebugReportCallbackEXT

- vkDebugReportMessageEXT

- vkDestroyDebugReportCallbackEXT

## New Structures

- Extending VkInstanceCreateInfo:

  - VkDebugReportCallbackCreateInfoEXT

## New Function Pointers

- PFN_vkDebugReportCallbackEXT

## New Enums

- VkDebugReportFlagBitsEXT

- VkDebugReportObjectTypeEXT

## New Bitmasks

- VkDebugReportFlagsEXT

## New Enum Constants

- `VK_EXT_DEBUG_REPORT_EXTENSION_NAME`

- `VK_EXT_DEBUG_REPORT_SPEC_VERSION`

- Extending VkObjectType:

  - `VK_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT`

- Extending VkResult:

  - `VK_ERROR_VALIDATION_FAILED_EXT`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT`

  - `VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT`

If Version 1.1 is supported:

- Extending VkDebugReportObjectTypeEXT:

  - `VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT`

  - `VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_YCBCR_CONVERSION_EXT`

## 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 VkDebugReportCallbackCreateInfoEXT structure to the `pNext` element of the VkInstanceCreateInfo structure given to vkCreateInstance.

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.

        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 In the initial release of the `VK_EXT_debug_report` extension, the token `VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT` was used. Starting in version 2 of the extension branch, `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 In the initial release of the `VK_EXT_debug_report` extension, the token `VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT` was used. Starting in version 8 of the extension branch, `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. `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.

2) Should there be a VU requiring VkDebugReportCallbackCreateInfoEXT::`flags` to be non-zero?

RESOLVED: It may not be very useful, but we do not need VU statement requiring the `VkDebugReportCallbackCreateInfoEXT`::`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 `VK_DEBUG_REPORT_DEBUG_BIT_EXT` and `VK_DEBUG_REPORT_INFORMATION_BIT_EXT`?

RESOLVED: `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:

+

    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 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.

## See Also

PFN_vkDebugReportCallbackEXT, VkDebugReportCallbackCreateInfoEXT, VkDebugReportCallbackEXT, VkDebugReportFlagBitsEXT, VkDebugReportFlagsEXT, VkDebugReportObjectTypeEXT, vkCreateDebugReportCallbackEXT, vkDebugReportMessageEXT, vkDestroyDebugReportCallbackEXT

## Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

## Copyright

Copyright 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0