314 lines
14 KiB
Plaintext
314 lines
14 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='VkDebugReportFlagsEXT',desc='Bitmask of VkDebugReportFlagBitsEXT',type='enums']
|
|
--
|
|
include::../api/flags/VkDebugReportFlagsEXT.txt[]
|
|
|
|
sname:VkDebugReportFlagsEXT is a bitmask type for setting a mask of zero or
|
|
more slink:VkDebugReportFlagBitsEXT.
|
|
--
|
|
|
|
[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 specifies 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
|
|
specifies 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, which is interpreted in a
|
|
layer-specified manner.
|
|
The application should: always return ename:VK_FALSE.
|
|
The ename:VK_TRUE value is reserved for use in layer development.
|
|
|
|
pname:object must: be a Vulkan object or ename:VK_NULL_HANDLE.
|
|
If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT and
|
|
pname:object is not ename:VK_NULL_HANDLE, pname:object must: be a Vulkan
|
|
object of the corresponding type associated with pname:objectType as defined
|
|
in <<debug-report-object-types>>.
|
|
--
|
|
|
|
[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[]
|
|
|
|
[[debug-report-object-types]]
|
|
.VkDebugReportObjectTypeEXT and Vulkan Handle Relationship
|
|
[width="80%",cols="<35,<23",options="header"]
|
|
|====
|
|
| elink:VkDebugReportObjectTypeEXT | Vulkan Handle Type
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT | Unknown/Undefined Handle
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_INSTANCE_EXT | slink:VkInstance
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PHYSICAL_DEVICE_EXT | slink:VkPhysicalDevice
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_EXT | slink:VkDevice
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUEUE_EXT | slink:VkQueue
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SEMAPHORE_EXT | slink:VkSemaphore
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_BUFFER_EXT | slink:VkCommandBuffer
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_FENCE_EXT | slink:VkFence
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEVICE_MEMORY_EXT | slink:VkDeviceMemory
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_EXT | slink:VkBuffer
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT | slink:VkImage
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_EVENT_EXT | slink:VkEvent
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_QUERY_POOL_EXT | slink:VkQueryPool
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_BUFFER_VIEW_EXT | slink:VkBufferView
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_VIEW_EXT | slink:VkImageView
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SHADER_MODULE_EXT | slink:VkShaderModule
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_CACHE_EXT | slink:VkPipelineCache
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_LAYOUT_EXT | slink:VkPipelineLayout
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_RENDER_PASS_EXT | slink:VkRenderPass
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_PIPELINE_EXT | slink:VkPipeline
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_LAYOUT_EXT | slink:VkDescriptorSetLayout
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SAMPLER_EXT | slink:VkSampler
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_POOL_EXT | slink:VkDescriptorPool
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_SET_EXT | slink:VkDescriptorSet
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_FRAMEBUFFER_EXT | slink:VkFramebuffer
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_COMMAND_POOL_EXT | slink:VkCommandPool
|
|
ifdef::VK_KHR_surface[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SURFACE_KHR_EXT | slink:VkSurfaceKHR
|
|
endif::VK_KHR_surface[]
|
|
ifdef::VK_KHR_surface[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_SWAPCHAIN_KHR_EXT | slink:VkSwapchainKHR
|
|
endif::VK_KHR_surface[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_CALLBACK_EXT_EXT | slink:VkDebugReportCallbackEXT
|
|
ifdef::VK_KHR_display[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT | slink:VkDisplayKHR
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT | slink:VkDisplayModeKHR
|
|
endif::VK_KHR_display[]
|
|
ifdef::VK_NVX_device_generated_commands[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_OBJECT_TABLE_NVX_EXT | slink:VkObjectTableNVX
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_INDIRECT_COMMANDS_LAYOUT_NVX_EXT | slink:VkIndirectCommandsLayoutNVX
|
|
endif::VK_NVX_device_generated_commands[]
|
|
ifndef::VK_VERSION_1_1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR_EXT | slink:VkDescriptorUpdateTemplate
|
|
endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[]
|
|
endif::VK_VERSION_1_1[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_EXT | slink:VkDescriptorUpdateTemplate
|
|
endif::VK_VERSION_1_1[]
|
|
|====
|
|
|
|
[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 slink:VkInstance.
|
|
* pname:flags specifies 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
|
|
* [[VUID-vkDebugReportMessageEXT-objectType-01498]]
|
|
If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
|
|
and pname:object is not ename:VK_NULL_HANDLE, pname:object must: be a
|
|
Vulkan object of the corresponding type associated with pname:objectType
|
|
as defined in <<debug-report-object-types>>.
|
|
****
|
|
|
|
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 slink: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[]
|
|
--
|