mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-20 01:58:06 +00:00
348990517c
* Bump API patch number and header version number to 29 for this update.
Github Issues:
* Remove redundant constraint on
slink:VkCommandBufferInheritanceInfo::pname:queryFlags (public issue
224).
* Fix typo and remove link in Note in the
<<extended-functionality-instance-extensions-and-devices, Instance
Extensions and Device Extensions>> section (public issue 359).
* Fix erroneous validation statement for the pname:layout member of
slink:VkComputePipelineCreateInfo (public issue 362).
Internal Issues:
* Restore long figure captions using asciidoc sidebar blocks, due to
restrictions of asciidoc syntax (internal issue 101).
* Replace most latexmath equations with comparable markup in straight
asciidoc, which significantly improves time required to fully load and
process the HTML forms of the Specification. There are known minor font
and alignment inconsistencies with MathJax and PDF rendering of
latexmath equations. Please do not file github issues about these. We
are aware of the inconsistencies and will make refinements over time,
while the performance improvements are compelling in at least some major
browsers (internal issue 313).
* Move handcoded validity statements from +vk.xml+ into the Specification
body, easing work in the single-branch model. Specify the distinction
between these explicit statements, and the implicit validity statements
inferred from vk.xml. Validity statements now appear in two blocks for
each command and structure - handcoded "Valid Usage" and the implicit
"Valid Usage (Implicit)" (internal issue 392).
* Add the +returnedonly="false"+ attribute to WSI output structures,
removing incorrectly generated implicit validity statements for
slink:VkDisplayPropertiesKHR, slink:VkDisplayPlanePropertiesKHR,
slink:VkDisplayModePropertiesKHR, slink:VkDisplayPlaneCapabilitiesKHR,
slink:VkSurfaceCapabilitiesKHR, and slink:VkSurfaceFormatKHR structures
(internal issue 486).
* Update slink:VkImageLayout to require the
ename:VK_IMAGE_USAGE_SAMPLED_BIT be set for sampled depth/stencil images
(internal issue 487).
* Use an explicit format specifier string for the date command invocation
in the +Makefile+ instead of the shorthand -R option, which doesn't work
on BSD and MaxOS X date commands (internal issue 500).
Other Issues:
* Use the terms ``allocation scope'' and ``extension scope'' instead of
just ``scope'', and add them to the glossary.
197 lines
7.9 KiB
Plaintext
197 lines
7.9 KiB
Plaintext
// This section is included inside the Debugging chapter (debugging.txt)
|
|
|
|
[[debugging-debug-report-callbacks]]
|
|
== Debug Report Callbacks
|
|
|
|
// refBegin vkCreateDebugReportCallbackEXT Create a debug report callback object
|
|
|
|
Debug report callbacks give more detailed feedback on the application's use
|
|
of Vulkan when events of interest occur.
|
|
|
|
To register a debug report callback, an application uses
|
|
flink:vkCreateDebugReportCallbackEXT.
|
|
|
|
include::../api/protos/vkCreateDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:instance the instance the callback will be logged on.
|
|
* pname:pCreateInfo points to a slink:VkDebugReportCallbackCreateInfoEXT
|
|
structure which defines the conditions under which this callback will be
|
|
called.
|
|
* pname:pCallback is a pointer to record the
|
|
sname:VkDebugReportCallbackEXT object created.
|
|
|
|
include::../validity/protos/vkCreateDebugReportCallbackEXT.txt[]
|
|
|
|
// refBegin VkDebugReportErrorEXT Unknown VK_EXT_debug_report enumeration type
|
|
|
|
include::../api/enums/VkDebugReportErrorEXT.txt[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The +VK_EXT_debug_report+ extension defines the elink:VkDebugReportErrorEXT
|
|
enumerant type, but does not currently explain what the enumeration is used
|
|
for.
|
|
It is included here for completeness.
|
|
====
|
|
|
|
// refBegin VkDebugReportCallbackCreateInfoEXT Structure specifying parameters of a newly created debug report callback
|
|
|
|
The definition of slink:VkDebugReportCallbackCreateInfoEXT is:
|
|
|
|
include::../api/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags indicate which event(s) will cause this callback to be
|
|
called.
|
|
Flags are interpreted as bitmasks and multiple may be set.
|
|
Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkDebugReportCallbackCreateInfoEXT Bitmask specifying events which cause a debug report callback
|
|
include::../api/enums/VkDebugReportFlagBitsEXT.txt[]
|
|
|
|
* ename:VK_DEBUG_REPORT_ERROR_BIT_EXT indicates an error that may cause
|
|
undefined results, including an application crash.
|
|
* ename:VK_DEBUG_REPORT_WARNING_BIT_EXT indicates an unexpected use.
|
|
E.g. Not destroying objects prior to destroying the containing object or
|
|
potential inconsistencies between descriptor set layout and the layout
|
|
in the corresponding shader, etc.
|
|
* ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a
|
|
potentially non-optimal use of Vulkan.
|
|
E.g. using flink:vkCmdClearColorImage when a RenderPass load_op would
|
|
have worked.
|
|
* ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT indicates an informational
|
|
message such as resource details that may be handy when debugging an
|
|
application.
|
|
* ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates diagnostic information
|
|
from the loader and layers.
|
|
|
|
* pname:pfnCallback is the application callback function to call.
|
|
* pname:pUserData is user data to be passed to the callback.
|
|
--
|
|
|
|
For each sname:VkDebugReportCallbackEXT that is created the flags determine
|
|
when that function is called.
|
|
A callback will be made for issues that match any bit set in its flags.
|
|
The callback will come directly from the component that detected the event,
|
|
unless some other layer intercepts the calls for its own purposes (filter
|
|
them in different way, log to system error log, etc.) An application may
|
|
receive multiple callbacks if multiple sname:VkDebugReportCallbackEXT
|
|
objects were created.
|
|
A callback will always be executed in the same thread as the originating
|
|
Vulkan call.
|
|
A callback may be called from multiple threads simultaneously (if the
|
|
application is making Vulkan calls from multiple threads).
|
|
|
|
include::../validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
|
|
|
|
// refBegin PFN_vkDebugReportCallbackEXT Application-defined debug report callback function
|
|
|
|
The prototype for the callback function implemented by the application is:
|
|
|
|
include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
|
|
this callback.
|
|
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
|
|
of object being used or created at the time the event was triggered.
|
|
* pname:object gives the object where the issue was detected.
|
|
pname:object may be ename:VK_NULL_OBJECT if there is no object
|
|
associated with the event.
|
|
* pname:location is a component (layer, driver, loader) defined value that
|
|
indicates the _location_ of the trigger.
|
|
This is an optional value.
|
|
* pname:messageCode is a layer-defined value indicating what test
|
|
triggered this callback.
|
|
* pname:pLayerPrefix is the abbreviation of the component making the
|
|
callback.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
* pname:pUserData is the user data given when the DebugReportCallback was
|
|
created.
|
|
|
|
The callback returns a basetype:VkBool32 that indicates to the calling layer
|
|
if the Vulkan call should: be aborted or not.
|
|
Applications should: always return ename:VK_FALSE so that they see the same
|
|
behavior with and without validation layers enabled.
|
|
|
|
If the application returns ename:VK_TRUE from its callback and the Vulkan
|
|
call being aborted returns a elink:VkResult, the layer will return
|
|
ename:VK_ERROR_VALIDATION_FAILED_EXT.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The primary expected use of ename:VK_ERROR_VALIDATION_FAILED_EXT is for
|
|
validation layer testing.
|
|
It is not expected that an application would see this error code during
|
|
normal use of the validation layers.
|
|
====
|
|
|
|
// refEnd PFN_vkDebugReportCallbackEXT
|
|
|
|
// vkDebugReportMessageEXT Inject a message into a debug stream
|
|
|
|
To inject its own messages into the debug stream, call:
|
|
|
|
include::../api/protos/vkDebugReportMessageEXT.txt[]
|
|
|
|
* pname:instance the instance the callback will be logged on.
|
|
* pname:flags indicates the ename:VkDebugReportFlagBitsEXT that triggered
|
|
this callback.
|
|
* pname:objType is a elink:VkDebugReportObjectTypeEXT specifying the type
|
|
of object being used or created at the time the event was triggered.
|
|
* pname:object is object where the issue was detected.
|
|
pname:object may be ename:VK_NULL_OBJECT if there is no object
|
|
associated with the event.
|
|
* pname:location is a component (layer, driver, loader) defined value that
|
|
indicates the _location_ of the trigger.
|
|
This is an optional value.
|
|
* pname:messageCode is a layer-defined value indicating what test
|
|
triggered this callback.
|
|
* pname:pLayerPrefix is the abbreviation of the component making the
|
|
callback.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
|
|
The call will propagate through the layers and cause a callback to the
|
|
application.
|
|
The parameters are passed on to the callback in addition to the
|
|
pname:pUserData value that was defined at the time the callback was
|
|
registered.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:instance must: be a valid sname:VkInstance handle
|
|
* pname:flags must: be a combination of one or more of
|
|
sname:VkDebugReportFlagBitsEXT
|
|
* pname:objType must: be one of sname:VkDebugReportObjectTypeEXT,
|
|
ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT if pname:object is `NULL`
|
|
* pname:object may: be a Vulkan object
|
|
* pname:pLayerPrefix must: be a `NULL` terminated string
|
|
* pname:pMsg must: be a `NULL` terminated string
|
|
****
|
|
|
|
include::../validity/protos/vkDebugReportMessageEXT.txt[]
|
|
|
|
// refBegin vkDestroyDebugReportCallbackEXT Destroy a debug report callback object
|
|
|
|
To destroy a sname:VkDebugReportCallbackEXT object, call:
|
|
|
|
include::../api/protos/vkDestroyDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:instance the instance where the callback was created.
|
|
* pname:callback the sname:VkDebugReportCallbackEXT object to destroy.
|
|
|
|
.Valid Usage
|
|
****
|
|
* If sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* If no sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[]
|