| // Copyright 2018-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[debugging-debug-utils]] |
| == Debug Utilities |
| |
| Vulkan provides flexible debugging utilities for debugging an application. |
| |
| The <<debugging-object-debug-annotation,Object Debug Annotation>> section |
| describes how to associate either a name or binary data with a specific |
| Vulkan object. |
| |
| The <<debugging-queue-labels,Queue Labels>> section describes how to |
| annotate and group the work submitted to a queue. |
| |
| The <<debugging-command-buffer-labels,Command Buffer Labels>> section |
| describes how to associate logical elements of the scene with commands in a |
| slink:VkCommandBuffer. |
| |
| The <<debugging-debug-messengers,Debug Messengers>> section describes how to |
| create debug messenger objects associated with an application supplied |
| callback to capture debug messages from a variety of Vulkan components. |
| |
| |
| [[debugging-object-debug-annotation]] |
| === Object Debug Annotation |
| |
| It can be useful for an application to provide its own content relative to a |
| specific Vulkan object. |
| The following commands allow application developers to associate |
| user-defined information with Vulkan objects. |
| |
| |
| [[debugging-object-naming]] |
| ==== Object Naming |
| |
| An object can be provided a user-defined name by calling |
| fname:vkSetDebugUtilsObjectNameEXT as defined below. |
| |
| [open,refpage='vkSetDebugUtilsObjectNameEXT',desc='Give a user-friendly name to an object',type='protos'] |
| -- |
| include::{generated}/api/protos/vkSetDebugUtilsObjectNameEXT.txt[] |
| |
| * pname:device is the device that created the object. |
| * pname:pNameInfo is a pointer to a slink:VkDebugUtilsObjectNameInfoEXT |
| structure specifying parameters of the name to set on the object. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkSetDebugUtilsObjectNameEXT-pNameInfo-02587]] |
| pname:pNameInfo->objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN |
| * [[VUID-vkSetDebugUtilsObjectNameEXT-pNameInfo-02588]] |
| pname:pNameInfo->objectHandle must: not be dlink:VK_NULL_HANDLE |
| **** |
| |
| include::{generated}/validity/protos/vkSetDebugUtilsObjectNameEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugUtilsObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs'] |
| -- |
| The sname:VkDebugUtilsObjectNameInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugUtilsObjectNameInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:objectType is a elink:VkObjectType specifying the type of the |
| object to be named. |
| * pname:objectHandle is the object to be named. |
| * pname:pObjectName is either `NULL` or a null-terminated UTF-8 string |
| specifying the name to apply to pname:objectHandle. |
| |
| Applications may: change the name associated with an object simply by |
| calling fname:vkSetDebugUtilsObjectNameEXT again with a new string. |
| If pname:pObjectName is either `NULL` or an empty string, then any |
| previously set name is removed. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDebugUtilsObjectNameInfoEXT-objectType-02589]] |
| If pname:objectType is ename:VK_OBJECT_TYPE_UNKNOWN, pname:objectHandle |
| must: not be dlink:VK_NULL_HANDLE |
| * [[VUID-VkDebugUtilsObjectNameInfoEXT-objectType-02590]] |
| If pname:objectType is not ename:VK_OBJECT_TYPE_UNKNOWN, |
| pname:objectHandle must: be dlink:VK_NULL_HANDLE or a valid Vulkan |
| handle of the type associated with pname:objectType as defined in the |
| <<debugging-object-types, `VkObjectType` and Vulkan Handle |
| Relationship>> table |
| **** |
| |
| include::{generated}/validity/structs/VkDebugUtilsObjectNameInfoEXT.txt[] |
| -- |
| |
| |
| [[debugging-object-data-association]] |
| ==== Object Data Association |
| |
| In addition to setting a name for an object, debugging and validation layers |
| may: have uses for additional binary data on a per-object basis that have no |
| other place in the Vulkan API. |
| |
| For example, a sname:VkShaderModule could have additional debugging data |
| attached to it to aid in offline shader tracing. |
| |
| Additional data can be attached to an object by calling |
| fname:vkSetDebugUtilsObjectTagEXT as defined below. |
| |
| [open,refpage='vkSetDebugUtilsObjectTagEXT',desc='Attach arbitrary data to an object',type='protos'] |
| -- |
| include::{generated}/api/protos/vkSetDebugUtilsObjectTagEXT.txt[] |
| |
| * pname:device is the device that created the object. |
| * pname:pTagInfo is a pointer to a slink:VkDebugUtilsObjectTagInfoEXT |
| structure specifying parameters of the tag to attach to the object. |
| |
| include::{generated}/validity/protos/vkSetDebugUtilsObjectTagEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugUtilsObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs'] |
| -- |
| The sname:VkDebugUtilsObjectTagInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugUtilsObjectTagInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:objectType is a elink:VkObjectType specifying the type of the |
| object to be named. |
| * pname:objectHandle is the object to be tagged. |
| * pname:tagName is a numerical identifier of the tag. |
| * pname:tagSize is the number of bytes of data to attach to the object. |
| * pname:pTag is a pointer to an array of pname:tagSize bytes containing |
| the data to be associated with the object. |
| |
| The pname:tagName parameter gives a name or identifier to the type of data |
| being tagged. |
| This can be used by debugging layers to easily filter for only data that can |
| be used by that implementation. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDebugUtilsObjectTagInfoEXT-objectType-01908]] |
| pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN |
| * [[VUID-VkDebugUtilsObjectTagInfoEXT-objectHandle-01910]] |
| pname:objectHandle must: be a valid Vulkan handle of the type associated |
| with pname:objectType as defined in the <<debugging-object-types, |
| `VkObjectType` and Vulkan Handle Relationship>> table |
| **** |
| |
| include::{generated}/validity/structs/VkDebugUtilsObjectTagInfoEXT.txt[] |
| -- |
| |
| |
| [[debugging-queue-labels]] |
| === Queue Labels |
| |
| All Vulkan work must be submitted using queues. |
| It is possible for an application to use multiple queues, each containing |
| multiple command buffers, when performing work. |
| It can be useful to identify which queue, or even where in a queue, |
| something has occurred. |
| |
| To begin identifying a region using a debug label inside a queue, you may |
| use the flink:vkQueueBeginDebugUtilsLabelEXT command. |
| |
| Then, when the region of interest has passed, you may end the label region |
| using flink:vkQueueEndDebugUtilsLabelEXT. |
| |
| Additionally, a single debug label may be inserted at any time using |
| flink:vkQueueInsertDebugUtilsLabelEXT. |
| |
| [open,refpage='vkQueueBeginDebugUtilsLabelEXT',desc='Open a queue debug label region',type='protos'] |
| -- |
| A queue debug label region is opened by calling: |
| |
| include::{generated}/api/protos/vkQueueBeginDebugUtilsLabelEXT.txt[] |
| |
| * pname:queue is the queue in which to start a debug label region. |
| * pname:pLabelInfo is a pointer to a slink:VkDebugUtilsLabelEXT structure |
| specifying parameters of the label region to open. |
| |
| include::{generated}/validity/protos/vkQueueBeginDebugUtilsLabelEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugUtilsLabelEXT',desc='Specify parameters of a label region',type='structs'] |
| -- |
| The sname:VkDebugUtilsLabelEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugUtilsLabelEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pLabelName is a pointer to a null-terminated UTF-8 string |
| containing the name of the label. |
| * pname:color is an optional RGBA color value that can be associated with |
| the label. |
| A particular implementation may: choose to ignore this color value. |
| The values contain RGBA values in order, in the range 0.0 to 1.0. |
| If all elements in pname:color are set to 0.0 then it is ignored. |
| |
| include::{generated}/validity/structs/VkDebugUtilsLabelEXT.txt[] |
| -- |
| |
| [open,refpage='vkQueueEndDebugUtilsLabelEXT',desc='Close a queue debug label region',type='protos'] |
| -- |
| A queue debug label region is closed by calling: |
| |
| include::{generated}/api/protos/vkQueueEndDebugUtilsLabelEXT.txt[] |
| |
| * pname:queue is the queue in which a debug label region should be closed. |
| |
| The calls to flink:vkQueueBeginDebugUtilsLabelEXT and |
| flink:vkQueueEndDebugUtilsLabelEXT must: be matched and balanced. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkQueueEndDebugUtilsLabelEXT-None-01911]] |
| There must: be an outstanding fname:vkQueueBeginDebugUtilsLabelEXT |
| command prior to the fname:vkQueueEndDebugUtilsLabelEXT on the queue |
| **** |
| |
| include::{generated}/validity/protos/vkQueueEndDebugUtilsLabelEXT.txt[] |
| -- |
| |
| [open,refpage='vkQueueInsertDebugUtilsLabelEXT',desc='Insert a label into a queue',type='protos'] |
| -- |
| A single label can be inserted into a queue by calling: |
| |
| include::{generated}/api/protos/vkQueueInsertDebugUtilsLabelEXT.txt[] |
| |
| * pname:queue is the queue into which a debug label will be inserted. |
| * pname:pLabelInfo is a pointer to a slink:VkDebugUtilsLabelEXT structure |
| specifying parameters of the label to insert. |
| |
| include::{generated}/validity/protos/vkQueueInsertDebugUtilsLabelEXT.txt[] |
| -- |
| |
| |
| [[debugging-command-buffer-labels]] |
| === Command Buffer Labels |
| |
| Typical Vulkan applications will submit many command buffers in each frame, |
| with each command buffer containing a large number of individual commands. |
| Being able to logically annotate regions of command buffers that belong |
| together as well as hierarchically subdivide the frame is important to a |
| developer's ability to navigate the commands viewed holistically. |
| |
| To identify the beginning of a debug label region in a command buffer, |
| flink:vkCmdBeginDebugUtilsLabelEXT can: be used as defined below. |
| |
| To indicate the end of a debug label region in a command buffer, |
| flink:vkCmdEndDebugUtilsLabelEXT can: be used. |
| |
| To insert a single command buffer debug label inside of a command buffer, |
| flink:vkCmdInsertDebugUtilsLabelEXT can: be used as defined below. |
| |
| [open,refpage='vkCmdBeginDebugUtilsLabelEXT',desc='Open a command buffer debug label region',type='protos'] |
| -- |
| A command buffer debug label region can be opened by calling: |
| |
| include::{generated}/api/protos/vkCmdBeginDebugUtilsLabelEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| * pname:pLabelInfo is a pointer to a slink:VkDebugUtilsLabelEXT structure |
| specifying parameters of the label region to open. |
| |
| include::{generated}/validity/protos/vkCmdBeginDebugUtilsLabelEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdEndDebugUtilsLabelEXT',desc='Close a command buffer label region',type='protos'] |
| -- |
| A command buffer label region can be closed by calling: |
| |
| include::{generated}/api/protos/vkCmdEndDebugUtilsLabelEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| |
| An application may: open a debug label region in one command buffer and |
| close it in another, or otherwise split debug label regions across multiple |
| command buffers or multiple queue submissions. |
| When viewed from the linear series of submissions to a single queue, the |
| calls to flink:vkCmdBeginDebugUtilsLabelEXT and |
| flink:vkCmdEndDebugUtilsLabelEXT must: be matched and balanced. |
| |
| There can: be problems reporting command buffer debug labels during the |
| recording process because command buffers may: be recorded out of sequence |
| with the resulting execution order. |
| Since the recording order may: be different, a solitary command buffer may: |
| have an inconsistent view of the debug label regions by itself. |
| Therefore, if an issue occurs during the recording of a command buffer, and |
| the environment requires returning debug labels, the implementation may: |
| return only those labels it is aware of. |
| This is true even if the implementation is aware of only the debug labels |
| within the command buffer being actively recorded. |
| |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01912]] |
| There must: be an outstanding fname:vkCmdBeginDebugUtilsLabelEXT command |
| prior to the fname:vkCmdEndDebugUtilsLabelEXT on the queue that |
| pname:commandBuffer is submitted to |
| * [[VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01913]] |
| If pname:commandBuffer is a secondary command buffer, there must: be an |
| outstanding fname:vkCmdBeginDebugUtilsLabelEXT command recorded to |
| pname:commandBuffer that has not previously been ended by a call to |
| fname:vkCmdEndDebugUtilsLabelEXT |
| **** |
| |
| include::{generated}/validity/protos/vkCmdEndDebugUtilsLabelEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdInsertDebugUtilsLabelEXT',desc='Insert a label into a command buffer',type='protos'] |
| -- |
| A single debug label can be inserted into a command buffer by calling: |
| |
| include::{generated}/api/protos/vkCmdInsertDebugUtilsLabelEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| * pname:pInfo is a pointer to a slink:VkDebugUtilsLabelEXT structure |
| specifying parameters of the label to insert. |
| |
| include::{generated}/validity/protos/vkCmdInsertDebugUtilsLabelEXT.txt[] |
| -- |
| |
| |
| [[debugging-debug-messengers]] |
| === Debug Messengers |
| |
| Vulkan allows an application to register multiple callbacks with any Vulkan |
| component wishing to report debug information. |
| Some callbacks may log the information to a file, others may cause a debug |
| break point or other application defined behavior. |
| A primary producer of callback messages are the validation layers. |
| An application can: register callbacks even when no validation layers are |
| enabled, but they will only be called for the Vulkan loader and, if |
| implemented, other layer and driver events. |
| |
| [open,refpage='VkDebugUtilsMessengerEXT',desc='Opaque handle to a debug messenger object',type='handles'] |
| -- |
| A sname:VkDebugUtilsMessengerEXT is a messenger object which handles passing |
| along debug messages to a provided debug callback. |
| |
| include::{generated}/api/handles/VkDebugUtilsMessengerEXT.txt[] |
| |
| The debug messenger will provide detailed feedback on the application's use |
| of Vulkan when events of interest occur. |
| When an event of interest does occur, the debug messenger will submit a |
| debug message to the debug callback that was provided during its creation. |
| Additionally, the debug messenger is responsible with filtering out debug |
| messages that the callback is not interested in and will only provide |
| desired debug messages. |
| -- |
| |
| [open,refpage='vkCreateDebugUtilsMessengerEXT',desc='Create a debug messenger object',type='protos'] |
| -- |
| A debug messenger triggers a debug callback with a debug message when an |
| event of interest occurs. |
| To create a debug messenger which will trigger a debug callback, call: |
| |
| include::{generated}/api/protos/vkCreateDebugUtilsMessengerEXT.txt[] |
| |
| * pname:instance is the instance the messenger will be used with. |
| * pname:pCreateInfo is a pointer to a |
| slink:VkDebugUtilsMessengerCreateInfoEXT structure containing the |
| callback pointer, as well as defining conditions under which this |
| messenger will trigger the callback. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pMessenger is a pointer to a slink:VkDebugUtilsMessengerEXT handle |
| in which the created object is returned. |
| |
| include::{generated}/validity/protos/vkCreateDebugUtilsMessengerEXT.txt[] |
| |
| The application must: ensure that flink:vkCreateDebugUtilsMessengerEXT is |
| not executed in parallel with any Vulkan command that is also called with |
| pname:instance or child of pname:instance as the dispatchable argument. |
| -- |
| |
| [open,refpage='VkDebugUtilsMessengerCreateInfoEXT',desc='Structure specifying parameters of a newly created debug messenger',type='structs'] |
| -- |
| The definition of sname:VkDebugUtilsMessengerCreateInfoEXT is: |
| |
| include::{generated}/api/structs/VkDebugUtilsMessengerCreateInfoEXT.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 `0` and is reserved for future use. |
| * pname:messageSeverity is a bitmask of |
| elink:VkDebugUtilsMessageSeverityFlagBitsEXT specifying which severity |
| of event(s) will cause this callback to be called. |
| * pname:messageType is a bitmask of |
| elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of |
| event(s) will cause this callback to be called. |
| * pname:pfnUserCallback is the application callback function to call. |
| * pname:pUserData is user data to be passed to the callback. |
| |
| For each sname:VkDebugUtilsMessengerEXT that is created the |
| sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity and |
| sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageType determine when |
| that sname:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback is |
| called. |
| The process to determine if the user's pname:pfnUserCallback is triggered |
| when an event occurs is as follows: |
| |
| . The implementation will perform a bitwise AND of the event's |
| elink:VkDebugUtilsMessageSeverityFlagBitsEXT with the |
| pname:messageSeverity provided during creation of the |
| slink:VkDebugUtilsMessengerEXT object. |
| .. If the value is 0, the message is skipped. |
| . The implementation will perform bitwise AND of the event's |
| elink:VkDebugUtilsMessageTypeFlagBitsEXT with the pname:messageType |
| provided during the creation of the slink:VkDebugUtilsMessengerEXT |
| object. |
| .. If the value is 0, the message is skipped. |
| . The callback will trigger a debug message for the current event |
| |
| 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 can: receive multiple callbacks if multiple |
| sname:VkDebugUtilsMessengerEXT objects are created. |
| A callback will always be executed in the same thread as the originating |
| Vulkan call. |
| |
| A callback can: be called from multiple threads simultaneously (if the |
| application is making Vulkan calls from multiple threads). |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDebugUtilsMessengerCreateInfoEXT-pfnUserCallback-01914]] |
| pname:pfnUserCallback must: be a valid |
| tlink:PFN_vkDebugUtilsMessengerCallbackEXT |
| **** |
| |
| include::{generated}/validity/structs/VkDebugUtilsMessengerCreateInfoEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugUtilsMessengerCreateFlagsEXT',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDebugUtilsMessengerCreateFlagsEXT.txt[] |
| |
| tname:VkDebugUtilsMessengerCreateFlagsEXT is a bitmask type for setting a |
| mask, but is currently reserved for future use. |
| -- |
| |
| [open,refpage='VkDebugUtilsMessageSeverityFlagBitsEXT',desc='Bitmask specifying which severities of events cause a debug messenger callback',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity, specifying |
| event severities which cause a debug messenger to call the callback, are: |
| |
| include::{generated}/api/enums/VkDebugUtilsMessageSeverityFlagBitsEXT.txt[] |
| |
| * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT specifies the most |
| verbose output indicating all diagnostic messages from the Vulkan |
| loader, layers, and drivers should be captured. |
| * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT specifies an |
| informational message such as resource details that may be handy when |
| debugging an application. |
| * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_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_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT specifies that the |
| application has violated a valid usage condition of the specification. |
| |
| [NOTE] |
| .Note |
| ==== |
| The values of elink:VkDebugUtilsMessageSeverityFlagBitsEXT are sorted based |
| on severity. |
| The higher the flag value, the more severe the message. |
| This allows for simple boolean operation comparisons when looking at |
| elink:VkDebugUtilsMessageSeverityFlagBitsEXT values. |
| |
| For example: |
| |
| [source,c++] |
| ~~~~ |
| if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) { |
| // Do something for warnings and errors |
| } |
| ~~~~ |
| |
| In addition, space has been left between the enums to allow for later |
| addition of new severities in between the existing values. |
| ==== |
| -- |
| |
| [open,refpage='VkDebugUtilsMessageSeverityFlagsEXT',desc='Bitmask of VkDebugUtilsMessageSeverityFlagBitsEXT',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDebugUtilsMessageSeverityFlagsEXT.txt[] |
| |
| tname:VkDebugUtilsMessageSeverityFlagsEXT is a bitmask type for setting a |
| mask of zero or more elink:VkDebugUtilsMessageSeverityFlagBitsEXT. |
| -- |
| |
| [open,refpage='VkDebugUtilsMessageTypeFlagBitsEXT',desc='Bitmask specifying which types of events cause a debug messenger callback',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageType, specifying |
| event types which cause a debug messenger to call the callback, are: |
| |
| include::{generated}/api/enums/VkDebugUtilsMessageTypeFlagBitsEXT.txt[] |
| |
| * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT specifies that some |
| general event has occurred. |
| This is typically a non-specification, non-performance event. |
| * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT specifies that |
| something has occurred during validation against the Vulkan |
| specification that may indicate invalid behavior. |
| * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_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. |
| -- |
| |
| [open,refpage='VkDebugUtilsMessageTypeFlagsEXT',desc='Bitmask of VkDebugUtilsMessageTypeFlagBitsEXT',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDebugUtilsMessageTypeFlagsEXT.txt[] |
| |
| tname:VkDebugUtilsMessageTypeFlagsEXT is a bitmask type for setting a mask |
| of zero or more elink:VkDebugUtilsMessageTypeFlagBitsEXT. |
| -- |
| |
| [open,refpage='PFN_vkDebugUtilsMessengerCallbackEXT',desc='Application-defined debug messenger callback function',type='funcpointers'] |
| -- |
| The prototype for the |
| slink:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback function |
| implemented by the application is: |
| |
| include::{generated}/api/funcpointers/PFN_vkDebugUtilsMessengerCallbackEXT.txt[] |
| |
| * pname:messageSeverity specifies the |
| elink:VkDebugUtilsMessageSeverityFlagBitsEXT that triggered this |
| callback. |
| * pname:messageTypes is a bitmask of |
| elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of |
| event(s) triggered this callback. |
| * pname:pCallbackData contains all the callback related data in the |
| slink:VkDebugUtilsMessengerCallbackDataEXT structure. |
| * pname:pUserData is the user data provided when the |
| slink:VkDebugUtilsMessengerEXT was created. |
| |
| 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-PFN_vkDebugUtilsMessengerCallbackEXT-None-04769]] |
| The callback must: not make calls to any Vulkan commands |
| **** |
| -- |
| |
| [open,refpage='VkDebugUtilsMessengerCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs'] |
| -- |
| The definition of sname:VkDebugUtilsMessengerCallbackDataEXT is: |
| |
| include::{generated}/api/structs/VkDebugUtilsMessengerCallbackDataEXT.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 `0` and is reserved for future use. |
| * pname:pMessageIdName is a null-terminated string that identifies the |
| particular message ID that is associated with the provided message. |
| If the message corresponds to a validation layer message, then this |
| string may contain the portion of the Vulkan specification that is |
| believed to have been violated. |
| * pname:messageIdNumber is the ID number of the triggering message. |
| If the message corresponds to a validation layer message, then this |
| number is related to the internal number associated with the message |
| being triggered. |
| * pname:pMessage is a null-terminated string detailing the trigger |
| conditions. |
| * pname:queueLabelCount is a count of items contained in the |
| pname:pQueueLabels array. |
| * pname:pQueueLabels is `NULL` or a pointer to an array of |
| slink:VkDebugUtilsLabelEXT active in the current sname:VkQueue at the |
| time the callback was triggered. |
| Refer to <<debugging-queue-labels,Queue Labels>> for more information. |
| * pname:cmdBufLabelCount is a count of items contained in the |
| pname:pCmdBufLabels array. |
| * pname:pCmdBufLabels is `NULL` or a pointer to an array of |
| slink:VkDebugUtilsLabelEXT active in the current sname:VkCommandBuffer |
| at the time the callback was triggered. |
| Refer to <<debugging-command-buffer-labels, Command Buffer Labels>> for |
| more information. |
| * pname:objectCount is a count of items contained in the pname:pObjects |
| array. |
| * pname:pObjects is a pointer to an array of |
| slink:VkDebugUtilsObjectNameInfoEXT objects related to the detected |
| issue. |
| The array is roughly in order or importance, but the 0th element is |
| always guaranteed to be the most important object for this message. |
| |
| [NOTE] |
| .Note |
| ==== |
| This structure should only be considered valid during the lifetime of the |
| triggered callback. |
| ==== |
| |
| Since adding queue and command buffer labels behaves like pushing and |
| popping onto a stack, the order of both pname:pQueueLabels and |
| pname:pCmdBufLabels is based on the order the labels were defined. |
| The result is that the first label in either pname:pQueueLabels or |
| pname:pCmdBufLabels will be the first defined (and therefore the oldest) |
| while the last label in each list will be the most recent. |
| |
| [NOTE] |
| .Note |
| ==== |
| pname:pQueueLabels will only be non-`NULL` if one of the objects in |
| pname:pObjects can be related directly to a defined sname:VkQueue which has |
| had one or more labels associated with it. |
| |
| Likewise, pname:pCmdBufLabels will only be non-`NULL` if one of the objects |
| in pname:pObjects can be related directly to a defined sname:VkCommandBuffer |
| which has had one or more labels associated with it. |
| Additionally, while command buffer labels allow for beginning and ending |
| across different command buffers, the debug messaging framework cannot: |
| guarantee that labels in pname:pCmdBufLables will contain those defined |
| outside of the associated command buffer. |
| This is partially due to the fact that the association of one command buffer |
| with another may not have been defined at the time the debug message is |
| triggered. |
| ==== |
| |
| include::{generated}/validity/structs/VkDebugUtilsMessengerCallbackDataEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugUtilsMessengerCallbackDataFlagsEXT',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDebugUtilsMessengerCallbackDataFlagsEXT.txt[] |
| |
| tname:VkDebugUtilsMessengerCallbackDataFlagsEXT is a bitmask type for |
| setting a mask, but is currently reserved for future use. |
| -- |
| |
| [open,refpage='vkSubmitDebugUtilsMessageEXT',desc='Inject a message into a debug stream',type='protos'] |
| -- |
| There may be times that a user wishes to intentionally submit a debug |
| message. |
| To do this, call: |
| |
| include::{generated}/api/protos/vkSubmitDebugUtilsMessageEXT.txt[] |
| |
| * pname:instance is the debug stream's slink:VkInstance. |
| * pname:messageSeverity is a elink:VkDebugUtilsMessageSeverityFlagBitsEXT |
| value specifying the severity of this event/message. |
| * pname:messageTypes is a bitmask of |
| elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of |
| event(s) to identify with this message. |
| * pname:pCallbackData contains all the callback related data in the |
| slink:VkDebugUtilsMessengerCallbackDataEXT structure. |
| |
| 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 messenger was |
| registered. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkSubmitDebugUtilsMessageEXT-objectType-02591]] |
| The pname:objectType member of each element of |
| pname:pCallbackData->pObjects must: not be ename:VK_OBJECT_TYPE_UNKNOWN |
| **** |
| |
| include::{generated}/validity/protos/vkSubmitDebugUtilsMessageEXT.txt[] |
| -- |
| |
| [open,refpage='vkDestroyDebugUtilsMessengerEXT',desc='Destroy a debug messenger object',type='protos'] |
| -- |
| To destroy a sname:VkDebugUtilsMessengerEXT object, call: |
| |
| include::{generated}/api/protos/vkDestroyDebugUtilsMessengerEXT.txt[] |
| |
| * pname:instance is the instance where the callback was created. |
| * pname:messenger is the slink:VkDebugUtilsMessengerEXT object to destroy. |
| pname:messenger is an externally synchronized object and must: not be |
| used on more than one thread at a time. |
| This means that fname:vkDestroyDebugUtilsMessengerEXT 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-vkDestroyDebugUtilsMessengerEXT-messenger-01915]] |
| If sname:VkAllocationCallbacks were provided when pname:messenger was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyDebugUtilsMessengerEXT-messenger-01916]] |
| If no sname:VkAllocationCallbacks were provided when pname:messenger was |
| created, pname:pAllocator must: be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyDebugUtilsMessengerEXT.txt[] |
| |
| The application must: ensure that flink:vkDestroyDebugUtilsMessengerEXT is |
| not executed in parallel with any Vulkan command that is also called with |
| pname:instance or child of pname:instance as the dispatchable argument. |
| -- |
| |