| // Copyright 2018-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| // 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::{generated}/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::{generated}/api/protos/vkCreateDebugReportCallbackEXT.txt[] |
| |
| * pname:instance is the instance the callback will be logged on. |
| * pname:pCreateInfo is a pointer to a |
| slink:VkDebugReportCallbackCreateInfoEXT structure defining 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 a slink:VkDebugReportCallbackEXT handle |
| in which the created object is returned. |
| |
| include::{generated}/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::{generated}/api/structs/VkDebugReportCallbackCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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). |
| |
| include::{generated}/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::{generated}/api/enums/VkDebugReportFlagBitsEXT.txt[] |
| |
| * ename:VK_DEBUG_REPORT_ERROR_BIT_EXT specifies that the application has |
| violated a valid usage condition of the specification. |
| * 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='flags'] |
| -- |
| include::{generated}/api/flags/VkDebugReportFlagsEXT.txt[] |
| |
| tname:VkDebugReportFlagsEXT is a bitmask type for setting a mask of zero or |
| more elink: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::{generated}/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 |
| specifying 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 dlink:VK_NULL_HANDLE. |
| If pname:objectType is not ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT and |
| pname:object is not dlink: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::{generated}/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[] |
| 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::{generated}/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 is the object where the issue was detected. |
| pname:object can: be dlink: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 dlink: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 dlink: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::{generated}/validity/protos/vkDebugReportMessageEXT.txt[] |
| -- |
| |
| [open,refpage='vkDestroyDebugReportCallbackEXT',desc='Destroy a debug report callback object',type='protos'] |
| -- |
| To destroy a sname:VkDebugReportCallbackEXT object, call: |
| |
| include::{generated}/api/protos/vkDestroyDebugReportCallbackEXT.txt[] |
| |
| * pname:instance is the instance where the callback was created. |
| * pname:callback is 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::{generated}/validity/protos/vkDestroyDebugReportCallbackEXT.txt[] |
| -- |