312 lines
13 KiB
Plaintext
312 lines
13 KiB
Plaintext
// This section is included inside the Debugging chapter (debugging.txt)
|
|
|
|
[[debugging-debug-report-callbacks]]
|
|
== Debug Report Callbacks
|
|
|
|
[open,refpage='VkDebugReportCallbackEXT',desc='Opaque handle to a debug report callback object',type='handles']
|
|
--
|
|
|
|
Debug report callbacks are represented by sname:VkDebugReportCallbackEXT
|
|
handles:
|
|
|
|
include::../api/handles/VkDebugReportCallbackEXT.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateDebugReportCallbackEXT',desc='Create a debug report callback object',type='protos']
|
|
--
|
|
|
|
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:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pCallback is a pointer to record the
|
|
sname:VkDebugReportCallbackEXT object created.
|
|
|
|
include::../validity/protos/vkCreateDebugReportCallbackEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDebugReportCallbackCreateInfoEXT',desc='Structure specifying parameters of a newly created debug report callback',type='structs']
|
|
--
|
|
|
|
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 is a bitmask of elink:VkDebugReportFlagBitsEXT specifying
|
|
which event(s) will cause this callback to be called.
|
|
* 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
|
|
sname:VkDebugReportCallbackCreateInfoEXT::pname:flags determine when that
|
|
sname:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback is called.
|
|
When an event happens, the implementation will do a bitwise AND of the
|
|
event's elink:VkDebugReportFlagBitsEXT flags to each
|
|
sname:VkDebugReportCallbackEXT object's flags.
|
|
For each non-zero result the corresponding callback will be called.
|
|
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 a different way, log to a 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).
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDebugReportCallbackCreateInfoEXT-pfnCallback-01385]]
|
|
pname:pfnCallback must: be a valid tlink:PFN_vkDebugReportCallbackEXT
|
|
****
|
|
|
|
include::../validity/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDebugReportFlagBitsEXT',desc='Bitmask specifying events which cause a debug report callback',type='enums']
|
|
--
|
|
|
|
Bits which can: be set in
|
|
slink:VkDebugReportCallbackCreateInfoEXT::pname:flags, specifying events
|
|
which cause a debug report, are:
|
|
|
|
include::../api/enums/VkDebugReportFlagBitsEXT.txt[]
|
|
|
|
* ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that an error that may
|
|
cause undefined results, including an application crash.
|
|
* ename:VK_DEBUG_REPORT_WARNING_BIT_EXT specifies 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 specifies a
|
|
potentially non-optimal use of Vulkan, e.g. using
|
|
flink:vkCmdClearColorImage when setting
|
|
slink:VkAttachmentDescription::pname:loadOp to
|
|
ename:VK_ATTACHMENT_LOAD_OP_CLEAR would have worked.
|
|
* ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT specifies an informational
|
|
message such as resource details that may be handy when debugging an
|
|
application.
|
|
* ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT specifies diagnostic information
|
|
from the implementation and layers.
|
|
|
|
--
|
|
|
|
[open,refpage='PFN_vkDebugReportCallbackEXT',desc='Application-defined debug report callback function',type='funcpointers']
|
|
--
|
|
|
|
The prototype for the
|
|
slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback function
|
|
implemented by the application is:
|
|
|
|
include::../api/funcpointers/PFN_vkDebugReportCallbackEXT.txt[]
|
|
|
|
* pname:flags indicates the elink:VkDebugReportFlagBitsEXT that triggered
|
|
this callback.
|
|
* pname:objectType is a elink:VkDebugReportObjectTypeEXT value specifying
|
|
the type of object being used or created at the time the event was
|
|
triggered.
|
|
* pname:object is the object where the issue was detected.
|
|
If pname:objectType is ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT,
|
|
pname:object is undefined.
|
|
* 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 a null-terminated string that is an abbreviation
|
|
of the name 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
|
|
slink:VkDebugReportCallbackEXT was created.
|
|
|
|
The callback must: not call fname:vkDestroyDebugReportCallbackEXT.
|
|
|
|
The callback returns a basetype:VkBool32 that indicates to the calling layer
|
|
the application's desire to abort the call.
|
|
A value of ename:VK_TRUE indicates that the application wants to abort this
|
|
call.
|
|
If the application returns ename:VK_FALSE, the command must: not be aborted.
|
|
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.
|
|
|
|
--
|
|
|
|
[open,refpage='VkDebugReportObjectTypeEXT',desc='Specify the type of an object handle',type='enums']
|
|
--
|
|
|
|
Possible values passed to the pname:objectType parameter of the callback
|
|
function specified by
|
|
slink:VkDebugReportCallbackCreateInfoEXT::pname:pfnCallback, specifying the
|
|
type of object handle being reported, are:
|
|
|
|
include::../api/enums/VkDebugReportObjectTypeEXT.txt[]
|
|
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT specifies an unknown
|
|
object.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT specifies a
|
|
slink:VkInstance.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT specifies a
|
|
slink:VkPhysicalDevice.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT specifies a slink:VkDevice.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT specifies a slink:VkQueue.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT specifies a
|
|
slink:VkSemaphore.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT specifies a
|
|
slink:VkCommandBuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT specifies a slink:VkFence.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT specifies a
|
|
slink:VkDeviceMemory.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT specifies a slink:VkBuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT specifies a slink:VkImage.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT specifies a slink:VkEvent.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT specifies a
|
|
slink:VkQueryPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT specifies a
|
|
slink:VkBufferView.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT specifies a
|
|
slink:VkImageView.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT specifies a
|
|
slink:VkShaderModule.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT specifies a
|
|
slink:VkPipelineCache.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT specifies a
|
|
slink:VkPipelineLayout.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT specifies a
|
|
slink:VkRenderPass.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT specifies a
|
|
slink:VkPipeline.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT specifies a
|
|
slink:VkDescriptorSetLayout.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT specifies a
|
|
slink:VkSampler.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT specifies a
|
|
slink:VkDescriptorPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT specifies a
|
|
slink:VkDescriptorSet.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT specifies a
|
|
slink:VkFramebuffer.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT specifies a
|
|
slink:VkCommandPool.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT specifies a
|
|
slink:VkSurfaceKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT specifies a
|
|
slink:VkSwapchainKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT
|
|
specifies a slink:VkDebugReportCallbackEXT.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT specifies a
|
|
slink:VkDisplayKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT specifies a
|
|
slink:VkDisplayModeKHR.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT specifies a
|
|
slink:VkObjectTableNVX.
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT
|
|
specifies a slink:VkIndirectCommandsLayoutNVX.
|
|
ifdef::VK_KHR_descriptor_update_template[]
|
|
* ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT
|
|
specifies a slink: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.
|
|
====
|
|
|
|
--
|
|
|
|
[open,refpage='vkDebugReportMessageEXT',desc='Inject a message into a debug stream',type='protos']
|
|
--
|
|
|
|
To inject its own messages into the debug stream, call:
|
|
|
|
include::../api/protos/vkDebugReportMessageEXT.txt[]
|
|
|
|
* pname:instance is the debug stream's sname:VkInstance.
|
|
* pname:flags indicates the elink:VkDebugReportFlagBitsEXT classification
|
|
of this event/message.
|
|
* pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
|
|
type of object being used or created at the time the event was
|
|
triggered.
|
|
* pname:object this is the object where the issue was detected.
|
|
pname:object can: be ename:VK_NULL_HANDLE if there is no object
|
|
associated with the event.
|
|
* pname:location is an application defined value.
|
|
* pname:messageCode is an application defined value.
|
|
* pname:pLayerPrefix is the abbreviation of the component making this
|
|
event/message.
|
|
* pname:pMessage is a null-terminated string detailing the trigger
|
|
conditions.
|
|
|
|
The call will propagate through the layers and generate callback(s) as
|
|
indicated by the message's flags.
|
|
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[]
|
|
--
|
|
|
|
[open,refpage='vkDestroyDebugReportCallbackEXT',desc='Destroy a debug report callback object',type='protos']
|
|
--
|
|
|
|
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.
|
|
pname:callback is an externally synchronized object and must: not be used
|
|
on more than one thread at a time.
|
|
This means that fname:vkDestroyDebugReportCallbackEXT must: not be called
|
|
when a callback is active.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyDebugReportCallbackEXT-instance-01242]]
|
|
If sname:VkAllocationCallbacks were provided when pname:callback was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyDebugReportCallbackEXT-instance-01243]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:callback was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyDebugReportCallbackEXT.txt[]
|
|
--
|