270 lines
11 KiB
Plaintext
270 lines
11 KiB
Plaintext
// This section is included inside the Debugging chapter (debugging.txt)
|
|
|
|
[[debugging-debug-report-callbacks]]
|
|
== Debug Report Callbacks
|
|
|
|
// refBegin VkDebugReportCallbackEXT Opaque handle to a debug report callback object
|
|
|
|
Debug report callbacks are represented by sname:VkDebugReportCallbackEXT
|
|
handles:
|
|
|
|
include::../api/handles/VkDebugReportCallbackEXT.txt[]
|
|
|
|
// refEnd VkDebugReportCallbackEXT
|
|
|
|
// 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 has not 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:pLayerPrefix is only valid for the duration of the callback.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
pname:pMessage is only valid for the duration of the callback.
|
|
* 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.
|
|
ifdef::VK_KHR_descriptor_update_template[]
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT is
|
|
a sname:VkDescriptorUpdateTemplateKHR.
|
|
endif::VK_KHR_descriptor_update_template[]
|
|
|
|
[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
|
|
****
|
|
* [[VUID-vkDebugReportMessageEXT-object-01241]] 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
|
|
****
|
|
* [[VUID-vkDestroyDebugReportCallbackEXT-instance-01242]] If sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyDebugReportCallbackEXT-instance-01243]] If no sname:VkAllocationCallbacks were provided when pname:instance was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[]
|