status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-01-26 14:20:33 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/appendices/VK_EXT_debug_report.txt
Jon Leech cebb71d062 Change log for May 20, 2017 Vulkan 1.0.50 spec update: 
* Bump API patch number and header version number to 50 for this update.

Github Issues:

  * Fix numerous minor issues with the VK_EXT_debug_report extension (public
    issues 478, 483, 486, 489, 490).

Internal Issues:

  * Update flink:vkAllocateDescriptorSets to specify conditions under which
    to return ename:VK_ERROR_FRAGMENTED_POOL or
    ename:VK_ERROR_OUT_OF_POOL_MEMORY instead of
    out-of-host/out-of-device-memory, and improve the
    <<fundamentals-errorcodes, description of those errors (internal issue
    654).
  * Add a NOTE documenting that flink:vkAcquireNextImageKHR can only signal
    a single semaphore, and how to deal with that when multiple physical
    devices in a logical device need to wait on it (internal issue 730).
  * Improve description of pname:pNext chains of
    slink:VkPhysicalDeviceImageFormatInfo2KHR and
    slink:VkImageFormatProperties2KHR (internal issue 814).
  * Clean up math markup issues in the <<textures, Image Operations>>
    chapter (internal issue 818).
  * Update validusage target to use more robust code for preprocessing, by
    making direct use of Asciidoctor's preprocessor. Added uniqueItems check
    to JSON vu schema and add clean_validusage target (internal issue 826).
  * Update style guide to prohibit writing non-self-contained (on a single
    bullet point) Valid Usage statements, and modify offending Valid Usage
    statements in the Specification to match, to assist with automatic
    extraction for the validation layers (internal issue 828).
  * Add ename:VK_VALIDATION_CHECK_SHADERS_EXT to elink:VkValidationCheckEXT
    of the `VK_EXT_validation_flags` extension, to selectively disable
    shader validation.
  * Remove duplicate valid usage statement for slink:VkImageMemoryBarrier.
  * Modify reflow.py script to place VUID tag anchors standalone on a line
    following their corresponding bullet point, and reflow the spec text
    accordingly (this had been pending since the initial tag deployment).

New Extensions:

  * `VK_AMD_texture_gather_bias_lod`
2017-05-20 17:00:50 -07:00

228 lines
8.0 KiB
Plaintext
Raw Blame History

[[VK_EXT_debug_report]]
== VK_EXT_debug_report
*Name String*::
+VK_EXT_debug_report+
*Extension Type*::
Instance
*Registered Extension Number*::
12
*Last Modified Date*::
2017-04-27
*Revision*::
8
*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
- Mark Lobodzinski, 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 defines a way for layers and the implementation to call back
to the application for events of interest to the application.
=== New Object Types
* slink:VkDebugReportCallbackEXT
=== 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
=== 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 events that occur while creating or destroying an instance an
application can: link a slink:VkDebugReportCallbackCreateInfoEXT structure
to the pname:pNext element of the slink:VkInstanceCreateInfo structure given
to flink:vkCreateInstance.
This callback is only valid for the duration of the flink:vkCreateInstance
and the flink: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
code: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,c++]
------------------------------------------------------------------------------
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.
====
[NOTE]
.Note
====
In the initial release of the +VK_EXT_debug_report+ extension, the token
ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used.
Starting in version 8 of the extension branch,
ename: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:
[source,c++]
----------------------------------------
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
sname:VkDebugReportCallbackCreateInfoEXT::pname:flags to be non-zero?
**RESOLVED**: It may not be very useful, but we do not need VU statement
requiring the sname:VkDebugReportCallbackCreateInfoEXT::pname:msgFlags at
create-time 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 ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT and
ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT?
**RESOLVED**: ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates information that
could be useful debugging the Vulkan implementation itself.
=== 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 ename: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
Reference in New Issue View Git Blame Copy Permalink