mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 15:04:10 +00:00
82e0f83d43
* Bump API patch number and header version number to 40 for this update.
* There is a major build change in this release. We are now using the
Ruby-based ``asciidoctor'' implementation, rather than the Python-based
``asciidoc'' implementation, to process the specification. While the
actual specification markup changes were minimal, this requires a new
set of build tools and a very different installation process, especially
because we now use an experimental direct-to-PDF backend for Asciidoctor
instead of Docbook->dblatex->PDF. It is no longer possible to build the
Specification using asciidoc. See doc/specs/vulkan/README.adoc
for some guidance on installing the new toolchain components.
* There are some minor rendering issues in the PDF output due to teething
problems with the asciidoctor toolchain, especially with mathematical
equations. We are aware of these and working on them.
Github Issues:
* Updated sample code for the <<sparsememory-examples-basic,sparse
resource binding example>> (public issue 97).
* Modify line and point clipping behavior in the
<<vertexpostproc-clipping, Primitive Clipping>> section to allow for
pop-free behavior. The ability to check for which behavior is
implemented may be added a future feature or extension (public issue
113).
* Unify the discussions of implicit ordering throughout the spec, in
particular in the new sections <<drawing-primitive-order, Primitive
Order>>, <<primrast-order, Rasterization Order>>, and
<<synchronization-implicit, Implicit Synchronization Guarantees>>; the
discussion of <<synchronization-submission-order, submission order>>;
and references elsewhere to these sections (public issue 133).
* Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
language and introduce the term ``identically defined'' (public issue
164).
* Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
reuse the object type enum from +VK_EXT_debug_report+, and moves the
definition of that enum into +VK_EXT_debug_report+ where it should be
(public issue 409).
* Remove redundant valid usage statement from slink:VkImageBlit (public
issue 421).
* Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
specialization constant (public issue 424).
* Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
426).
* Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
issue 447).
Internal Issues:
* Moved to asciidoctor for spec builds (internal issue 121).
* Update style guide to describe where to put new extensions-specific
asciidoc files, and what to name them (internal issue 626).
* Add src/spec/indexExt.py to autogenerate registry index entries linking
into the 1.0-extensions specification, instead of maintaining the index
manually. (internal issue 642).
* Autogenerate extension dependencies and lists of all extensions and all
KHR extensions from the "supported" attributes in +vk.xml+. Execute
+make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
extension is added to vk.xml, to regenerate the dependency script. The
consequence is that specifying a single extension to the +makeExt+
script will automatically enable all extensions it depends on as well,
and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
updated when a new extension is supported (internal issue 648).
* Put extension appendices all at the same asciidoc section level, so KHR
WSI extensions show up in the HTML index (internal issue 648).
Other Issues:
* Imbed images in the generated HTML specs instead of loading them from
the images/ directory.
* Fix missing EXT in extension name
(ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
* Add new +VK_EXT_SMPTE_2086_metadata+ extension.
* In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
+VK_KHR_xlib_surface+ specification, add language warning users that
they always need to call code:XinitThreads.
* Use the term "presentable image" (rather than "swapchain image")
consistently in +VK_KHR_swapchain+ and related extensions, and add a
glossary term defining it.
* Relocate the valid usage for samples of
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure.
175 lines
5.9 KiB
Plaintext
175 lines
5.9 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*::
|
|
2017-01-31
|
|
*Revision*::
|
|
5
|
|
*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 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: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
|
|
* 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 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.
|
|
====
|
|
|
|
|
|
=== Issues
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
There are no issues in the current spec.
|
|
We should probably add some.
|
|
====
|
|
|
|
=== 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
|