mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-27 14:45:55 +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.
256 lines
11 KiB
Plaintext
256 lines
11 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 VkDebugReportFlagBitsEXT 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 use of Vulkan that may
|
|
expose an app bug.
|
|
Such cases may not be immediately harmful, such as a fragment shader
|
|
outputting to a location with no attachment.
|
|
Other cases may point to behavior that is almost certainly bad when
|
|
unintended such as using an image whose memory hasn't been filled.
|
|
In general if you see a warning but you know that the behavior is
|
|
intended/desired, then simply ignore the warning.
|
|
* 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:objectType 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_HANDLE 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.
|
|
|
|
// refBegin VkDebugReportObjectTypeEXT Specify the type of an object handle
|
|
|
|
The object types are:
|
|
|
|
include::../api/enums/VkDebugReportObjectTypeEXT.txt[]
|
|
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT is an unknown object.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT is a sname:VkInstance.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT is a
|
|
sname:VkPhysicalDevice.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT is a sname:VkDevice.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT is a sname:VkQueue.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT is a sname:VkSemaphore.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT is a
|
|
sname:VkCommandBuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT is a sname:VkFence.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT is a
|
|
sname:VkDeviceMemory.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT is a sname:VkBuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT is a sname:VkImage.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT is a sname:VkEvent.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT is a sname:VkQueryPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT is a
|
|
sname:VkBufferView.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT is a sname:VkImageView.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT is a
|
|
sname:VkShaderModule.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT is a
|
|
sname:VkPipelineCache.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT is a
|
|
sname:VkPipelineLayout.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT is a
|
|
sname:VkRenderPass.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT is a sname:VkPipeline.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT is a
|
|
sname:VkDescriptorSetLayout.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT is a sname:VkSampler.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT is a
|
|
sname:VkDescriptorPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT is a
|
|
sname:VkDescriptorSet.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT is a
|
|
sname:VkFramebuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT is a
|
|
sname:VkCommandPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT is a
|
|
sname:VkSurfaceKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT is a
|
|
sname:VkSwapchainKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT is a
|
|
sname:VkDebugReportCallbackEXT.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT is a
|
|
sname:VkDisplayKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT is a
|
|
sname:VkDisplayModeKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT is a
|
|
sname:VkObjectTableNVX.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT is a
|
|
sname:VkIndirectCommandsLayoutNVX.
|
|
|
|
[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:objectType 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_HANDLE 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:object must: be a Vulkan object or ename:VK_NULL_HANDLE
|
|
****
|
|
|
|
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[]
|