mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 06:54:14 +00:00
95dd2f34c5
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
161 lines
5.2 KiB
Plaintext
161 lines
5.2 KiB
Plaintext
[[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.
|
|
====
|