1  // This section is included inside the Debugging chapter (debugging.txt)
  2  
  3  [[debugging-debug-markers]]
  4  == Debug Markers
  5  
  6  Debug markers provide a flexible way for debugging and validation layers to
  7  receive annotation and debug information.
  8  
  9  The <<debugging-object-annotation,Object Annotation>> section describes how
 10  to associate a name or binary data with a Vulkan object.
 11  
 12  The <<debugging-command-buffer-markers,Command Buffer Markers>> section
 13  describes how to associate logical elements of the scene with commands in
 14  the command buffer.
 15  
 16  
 17  [[debugging-object-annotation]]
 18  === Object Annotation
 19  
 20  The commands in this section allow application developers to associate
 21  user-defined information with Vulkan objects at will.
 22  
 23  [open,refpage='vkDebugMarkerSetObjectNameEXT',desc='Give a user-friendly name to an object',type='protos']
 24  --
 25  
 26  An object can be given a user-friendly name by calling:
 27  
 28  include::{generated}/api/protos/vkDebugMarkerSetObjectNameEXT.txt[]
 29  
 30    * pname:device is the device that created the object.
 31    * pname:pNameInfo is a pointer to an instance of the
 32      slink:VkDebugMarkerObjectNameInfoEXT structure specifying the parameters
 33      of the name to set on the object.
 34  
 35  include::{generated}/validity/protos/vkDebugMarkerSetObjectNameEXT.txt[]
 36  --
 37  
 38  [open,refpage='VkDebugMarkerObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs']
 39  --
 40  
 41  The sname:VkDebugMarkerObjectNameInfoEXT structure is defined as:
 42  
 43  include::{generated}/api/structs/VkDebugMarkerObjectNameInfoEXT.txt[]
 44  
 45    * pname:sType is the type of this structure.
 46    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 47    * pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
 48      type of the object to be named.
 49    * pname:object is the object to be named.
 50    * pname:pObjectName is a null-terminated UTF-8 string specifying the name
 51      to apply to pname:object.
 52  
 53  Applications may: change the name associated with an object simply by
 54  calling fname:vkDebugMarkerSetObjectNameEXT again with a new string.
 55  To remove a previously set name, pname:pObjectName should: be set to an
 56  empty string.
 57  
 58  .Valid Usage
 59  ****
 60    * [[VUID-VkDebugMarkerObjectNameInfoEXT-objectType-01490]]
 61      pname:objectType must: not be
 62      ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
 63    * [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01491]]
 64      pname:object must: not be dlink:VK_NULL_HANDLE
 65    * [[VUID-VkDebugMarkerObjectNameInfoEXT-object-01492]]
 66      pname:object must: be a Vulkan object of the type associated with
 67      pname:objectType as defined in <<debug-report-object-types>>.
 68  ****
 69  
 70  include::{generated}/validity/structs/VkDebugMarkerObjectNameInfoEXT.txt[]
 71  --
 72  
 73  [open,refpage='vkDebugMarkerSetObjectTagEXT',desc='Attach arbitrary data to an object',type='protos']
 74  --
 75  
 76  In addition to setting a name for an object, debugging and validation layers
 77  may have uses for additional binary data on a per-object basis that has no
 78  other place in the Vulkan API.
 79  For example, a sname:VkShaderModule could have additional debugging data
 80  attached to it to aid in offline shader tracing.
 81  To attach data to an object, call:
 82  
 83  include::{generated}/api/protos/vkDebugMarkerSetObjectTagEXT.txt[]
 84  
 85    * pname:device is the device that created the object.
 86    * pname:pTagInfo is a pointer to an instance of the
 87      slink:VkDebugMarkerObjectTagInfoEXT structure specifying the parameters
 88      of the tag to attach to the object.
 89  
 90  include::{generated}/validity/protos/vkDebugMarkerSetObjectTagEXT.txt[]
 91  --
 92  
 93  [open,refpage='VkDebugMarkerObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs']
 94  --
 95  
 96  The sname:VkDebugMarkerObjectTagInfoEXT structure is defined as:
 97  
 98  include::{generated}/api/structs/VkDebugMarkerObjectTagInfoEXT.txt[]
 99  
100    * pname:sType is the type of this structure.
101    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
102    * pname:objectType is a elink:VkDebugReportObjectTypeEXT specifying the
103      type of the object to be named.
104    * pname:object is the object to be tagged.
105    * pname:tagName is a numerical identifier of the tag.
106    * pname:tagSize is the number of bytes of data to attach to the object.
107    * pname:pTag is an array of pname:tagSize bytes containing the data to be
108      associated with the object.
109  
110  The pname:tagName parameter gives a name or identifier to the type of data
111  being tagged.
112  This can be used by debugging layers to easily filter for only data that can
113  be used by that implementation.
114  
115  .Valid Usage
116  ****
117    * [[VUID-VkDebugMarkerObjectTagInfoEXT-objectType-01493]]
118      pname:objectType must: not be
119      ename:VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT
120    * [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01494]]
121      pname:object must: not be dlink:VK_NULL_HANDLE
122    * [[VUID-VkDebugMarkerObjectTagInfoEXT-object-01495]]
123      pname:object must: be a Vulkan object of the type associated with
124      pname:objectType as defined in <<debug-report-object-types>>.
125  ****
126  
127  include::{generated}/validity/structs/VkDebugMarkerObjectTagInfoEXT.txt[]
128  --
129  
130  [[debugging-command-buffer-markers]]
131  === Command Buffer Markers
132  
133  Typical Vulkan applications will submit many command buffers in each frame,
134  with each command buffer containing a large number of individual commands.
135  Being able to logically annotate regions of command buffers that belong
136  together as well as hierarchically subdivide the frame is important to a
137  developer's ability to navigate the commands viewed holistically.
138  
139  The marker commands fname:vkCmdDebugMarkerBeginEXT and
140  fname:vkCmdDebugMarkerEndEXT define regions of a series of commands that are
141  grouped together, and they can be nested to create a hierarchy.
142  The fname:vkCmdDebugMarkerInsertEXT command allows insertion of a single
143  label within a command buffer.
144  
145  [open,refpage='vkCmdDebugMarkerBeginEXT',desc='Open a command buffer marker region',type='protos']
146  --
147  
148  A marker region can be opened by calling:
149  
150  include::{generated}/api/protos/vkCmdDebugMarkerBeginEXT.txt[]
151  
152    * pname:commandBuffer is the command buffer into which the command is
153      recorded.
154    * pname:pMarkerInfo is a pointer to an instance of the
155      slink:VkDebugMarkerMarkerInfoEXT structure specifying the parameters of
156      the marker region to open.
157  
158  include::{generated}/validity/protos/vkCmdDebugMarkerBeginEXT.txt[]
159  --
160  
161  [open,refpage='VkDebugMarkerMarkerInfoEXT',desc='Specify parameters of a command buffer marker region',type='structs']
162  --
163  
164  The sname:VkDebugMarkerMarkerInfoEXT structure is defined as:
165  
166  include::{generated}/api/structs/VkDebugMarkerMarkerInfoEXT.txt[]
167  
168    * pname:sType is the type of this structure.
169    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
170    * pname:pMarkerName is a pointer to a null-terminated UTF-8 string that
171      contains the name of the marker.
172    * pname:color is an optional: RGBA color value that can be associated with
173      the marker.
174      A particular implementation may: choose to ignore this color value.
175      The values contain RGBA values in order, in the range 0.0 to 1.0.
176      If all elements in pname:color are set to 0.0 then it is ignored.
177  
178  include::{generated}/validity/structs/VkDebugMarkerMarkerInfoEXT.txt[]
179  --
180  
181  [open,refpage='vkCmdDebugMarkerEndEXT',desc='Close a command buffer marker region',type='protos']
182  --
183  
184  A marker region can be closed by calling:
185  
186  include::{generated}/api/protos/vkCmdDebugMarkerEndEXT.txt[]
187  
188    * pname:commandBuffer is the command buffer into which the command is
189      recorded.
190  
191  An application may: open a marker region in one command buffer and close it
192  in another, or otherwise split marker regions across multiple command
193  buffers or multiple queue submissions.
194  When viewed from the linear series of submissions to a single queue, the
195  calls to fname:vkCmdDebugMarkerBeginEXT and fname:vkCmdDebugMarkerEndEXT
196  must: be matched and balanced.
197  
198  .Valid Usage
199  ****
200    * [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01239]]
201      There must: be an outstanding flink:vkCmdDebugMarkerBeginEXT command
202      prior to the fname:vkCmdDebugMarkerEndEXT on the queue that
203      pname:commandBuffer is submitted to
204    * [[VUID-vkCmdDebugMarkerEndEXT-commandBuffer-01240]]
205      If pname:commandBuffer is a secondary command buffer, there must: be an
206      outstanding flink:vkCmdDebugMarkerBeginEXT command recorded to
207      pname:commandBuffer that has not previously been ended by a call to
208      flink:vkCmdDebugMarkerEndEXT.
209  ****
210  
211  include::{generated}/validity/protos/vkCmdDebugMarkerEndEXT.txt[]
212  --
213  
214  [open,refpage='vkCmdDebugMarkerInsertEXT',desc='Insert a marker label into a command buffer',type='protos']
215  --
216  
217  A single marker label can be inserted into a command buffer by calling:
218  
219  include::{generated}/api/protos/vkCmdDebugMarkerInsertEXT.txt[]
220  
221    * pname:commandBuffer is the command buffer into which the command is
222      recorded.
223    * pname:pMarkerInfo is a pointer to an instance of the
224      slink:VkDebugMarkerMarkerInfoEXT structure specifying the parameters of
225      the marker to insert.
226  
227  include::{generated}/validity/protos/vkCmdDebugMarkerInsertEXT.txt[]
228  --