| // 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-markers]] |
| == Debug Markers |
| |
| Debug markers provide a flexible way for debugging and validation layers to |
| receive annotation and debug information. |
| |
| The <<debugging-object-annotation,Object Annotation>> section describes how |
| to associate a name or binary data with a Vulkan object. |
| |
| The <<debugging-command-buffer-markers,Command Buffer Markers>> section |
| describes how to associate logical elements of the scene with commands in |
| the command buffer. |
| |
| |
| [[debugging-object-annotation]] |
| === Object Annotation |
| |
| The commands in this section allow application developers to associate |
| user-defined information with Vulkan objects at will. |
| |
| [open,refpage='vkDebugMarkerSetObjectNameEXT',desc='Give a user-friendly name to an object',type='protos'] |
| -- |
| An object can be given a user-friendly name by calling: |
| |
| include::{generated}/api/protos/vkDebugMarkerSetObjectNameEXT.txt[] |
| |
| * pname:device is the device that created the object. |
| * pname:pNameInfo is a pointer to a slink:VkDebugMarkerObjectNameInfoEXT |
| structure specifying the parameters of the name to set on the object. |
| |
| include::{generated}/validity/protos/vkDebugMarkerSetObjectNameEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugMarkerObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs'] |
| -- |
| The sname:VkDebugMarkerObjectNameInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugMarkerObjectNameInfoEXT.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:VkDebugReportObjectTypeEXT specifying the |
| type of the object to be named. |
| * pname:object is the object to be named. |
| * pname:pObjectName is a null-terminated UTF-8 string specifying the name |
| to apply to pname:object. |
| |
| Applications may: change the name associated with an object simply by |
| calling fname:vkDebugMarkerSetObjectNameEXT again with a new string. |
| To remove a previously set name, pname:pObjectName should: be set to an |
| empty string. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDebugMarkerObjectNameInfoEXT-objectType-01490]] |
| pname:objectType must: not be |
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT |
| * [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01491]] |
| pname:object must: not be dlink:VK_NULL_HANDLE |
| * [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01492]] |
| pname:object must: be a Vulkan object of the type associated with |
| pname:objectType as defined in <<debug-report-object-types>> |
| **** |
| |
| include::{generated}/validity/structs/VkDebugMarkerObjectNameInfoEXT.txt[] |
| -- |
| |
| [open,refpage='vkDebugMarkerSetObjectTagEXT',desc='Attach arbitrary data to an object',type='protos'] |
| -- |
| 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 has 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. |
| To attach data to an object, call: |
| |
| include::{generated}/api/protos/vkDebugMarkerSetObjectTagEXT.txt[] |
| |
| * pname:device is the device that created the object. |
| * pname:pTagInfo is a pointer to a slink:VkDebugMarkerObjectTagInfoEXT |
| structure specifying the parameters of the tag to attach to the object. |
| |
| include::{generated}/validity/protos/vkDebugMarkerSetObjectTagEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugMarkerObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs'] |
| -- |
| The sname:VkDebugMarkerObjectTagInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugMarkerObjectTagInfoEXT.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:VkDebugReportObjectTypeEXT specifying the |
| type of the object to be named. |
| * pname:object 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-VkDebugMarkerObjectTagInfoEXT-objectType-01493]] |
| pname:objectType must: not be |
| ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT |
| * [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01494]] |
| pname:object must: not be dlink:VK_NULL_HANDLE |
| * [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01495]] |
| pname:object must: be a Vulkan object of the type associated with |
| pname:objectType as defined in <<debug-report-object-types>> |
| **** |
| |
| include::{generated}/validity/structs/VkDebugMarkerObjectTagInfoEXT.txt[] |
| -- |
| |
| |
| [[debugging-command-buffer-markers]] |
| === Command Buffer Markers |
| |
| 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. |
| |
| The marker commands fname:vkCmdDebugMarkerBeginEXT and |
| fname:vkCmdDebugMarkerEndEXT define regions of a series of commands that are |
| grouped together, and they can be nested to create a hierarchy. |
| The fname:vkCmdDebugMarkerInsertEXT command allows insertion of a single |
| label within a command buffer. |
| |
| [open,refpage='vkCmdDebugMarkerBeginEXT',desc='Open a command buffer marker region',type='protos'] |
| -- |
| A marker region can be opened by calling: |
| |
| include::{generated}/api/protos/vkCmdDebugMarkerBeginEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| * pname:pMarkerInfo is a pointer to a slink:VkDebugMarkerMarkerInfoEXT |
| structure specifying the parameters of the marker region to open. |
| |
| include::{generated}/validity/protos/vkCmdDebugMarkerBeginEXT.txt[] |
| -- |
| |
| [open,refpage='VkDebugMarkerMarkerInfoEXT',desc='Specify parameters of a command buffer marker region',type='structs'] |
| -- |
| The sname:VkDebugMarkerMarkerInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkDebugMarkerMarkerInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pMarkerName is a pointer to a null-terminated UTF-8 string |
| containing the name of the marker. |
| * pname:color is an optional: RGBA color value that can be associated with |
| the marker. |
| 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/VkDebugMarkerMarkerInfoEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdDebugMarkerEndEXT',desc='Close a command buffer marker region',type='protos'] |
| -- |
| A marker region can be closed by calling: |
| |
| include::{generated}/api/protos/vkCmdDebugMarkerEndEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| |
| An application may: open a marker region in one command buffer and close it |
| in another, or otherwise split marker regions across multiple command |
| buffers or multiple queue submissions. |
| When viewed from the linear series of submissions to a single queue, the |
| calls to fname:vkCmdDebugMarkerBeginEXT and fname:vkCmdDebugMarkerEndEXT |
| must: be matched and balanced. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01239]] |
| There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command |
| prior to the fname:vkCmdDebugMarkerEndEXT on the queue that |
| pname:commandBuffer is submitted to |
| * [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01240]] |
| If pname:commandBuffer is a secondary command buffer, there must: be an |
| outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to |
| pname:commandBuffer that has not previously been ended by a call to |
| flink:vkCmdDebugMarkerEndEXT |
| **** |
| |
| include::{generated}/validity/protos/vkCmdDebugMarkerEndEXT.txt[] |
| -- |
| |
| [open,refpage='vkCmdDebugMarkerInsertEXT',desc='Insert a marker label into a command buffer',type='protos'] |
| -- |
| A single marker label can be inserted into a command buffer by calling: |
| |
| include::{generated}/api/protos/vkCmdDebugMarkerInsertEXT.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command is |
| recorded. |
| * pname:pMarkerInfo is a pointer to a slink:VkDebugMarkerMarkerInfoEXT |
| structure specifying the parameters of the marker to insert. |
| |
| include::{generated}/validity/protos/vkCmdDebugMarkerInsertEXT.txt[] |
| -- |
