1  [[debugging-debug-utils]]
  2  == Debug Utilities
  3  
  4  Vulkan provides flexible debugging utilities for debugging an application.
  5  
  6  The <<debugging-object-debug-annotation,Object Debug Annotation>> section
  7  describes how to associate either a name or binary data with a specific
  8  Vulkan object.
  9  
 10  The <<debugging-queue-labels,Queue Labels>> section describes how to
 11  annotate and group the work submitted to a queue.
 12  
 13  The <<debugging-command-buffer-labels,Command Buffer Labels>> section
 14  describes how to associate logical elements of the scene with commands in a
 15  slink:VkCommandBuffer.
 16  
 17  The <<debugging-debug-messengers,Debug Messengers>> section describes how to
 18  create debug messenger objects associated with an application supplied
 19  callback to capture debug messages from a variety of Vulkan components.
 20  
 21  [[debugging-object-debug-annotation]]
 22  === Object Debug Annotation
 23  
 24  It can be useful for an application to provide its own content relative to a
 25  specific Vulkan object.
 26  The following commands allow application developers to associate
 27  user-defined information with Vulkan objects.
 28  
 29  [[debugging-object-naming]]
 30  ==== Object Naming
 31  
 32  An object can be provided a user-defined name by calling
 33  fname:vkSetDebugUtilsObjectNameEXT as defined below.
 34  
 35  [open,refpage='vkSetDebugUtilsObjectNameEXT',desc='Give a user-friendly name to an object',type='protos']
 36  --
 37  
 38  include::{generated}/api/protos/vkSetDebugUtilsObjectNameEXT.txt[]
 39  
 40    * pname:device is the device that created the object.
 41    * pname:pNameInfo is a pointer to an instance of the
 42      slink:VkDebugUtilsObjectNameInfoEXT structure specifying the parameters
 43      of the name to set on the object.
 44  
 45  .Valid Usage
 46  ****
 47    * [[VUID-vkSetDebugUtilsObjectNameEXT-pNameInfo-02587]]
 48      pname:pNameInfo\->pname:objectType must: not be
 49      ename:VK_OBJECT_TYPE_UNKNOWN
 50    * [[VUID-vkSetDebugUtilsObjectNameEXT-pNameInfo-02588]]
 51      pname:pNameInfo\->pname:objectHandle must: not be dlink:VK_NULL_HANDLE
 52  ****
 53  
 54  include::{generated}/validity/protos/vkSetDebugUtilsObjectNameEXT.txt[]
 55  
 56  --
 57  
 58  [open,refpage='VkDebugUtilsObjectNameInfoEXT',desc='Specify parameters of a name to give to an object',type='structs']
 59  --
 60  
 61  The sname:VkDebugUtilsObjectNameInfoEXT structure is defined as:
 62  
 63  include::{generated}/api/structs/VkDebugUtilsObjectNameInfoEXT.txt[]
 64  
 65    * pname:sType is the type of this structure.
 66    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
 67    * pname:objectType is a elink:VkObjectType specifying the type of the
 68      object to be named.
 69    * pname:objectHandle is the object to be named.
 70    * pname:pObjectName is a null-terminated UTF-8 string specifying the name
 71      to apply to pname:objectHandle.
 72  
 73  Applications may: change the name associated with an object simply by
 74  calling fname:vkSetDebugUtilsObjectNameEXT again with a new string.
 75  If pname:pObjectName is an empty string, then any previously set name is
 76  removed.
 77  
 78  .Valid Usage
 79  ****
 80    * [[VUID-VkDebugUtilsObjectNameInfoEXT-objectType-02589]]
 81      If pname:objectType is ename:VK_OBJECT_TYPE_UNKNOWN, pname:objectHandle
 82      must: not be dlink:VK_NULL_HANDLE
 83    * [[VUID-VkDebugUtilsObjectNameInfoEXT-objectType-02590]]
 84      If pname:objectType is not ename:VK_OBJECT_TYPE_UNKNOWN,
 85      pname:objectHandle must: be dlink:VK_NULL_HANDLE or a valid Vulkan
 86      handle of the type associated with pname:objectType as defined in the
 87      <<debugging-object-types, VkObjectType and Vulkan Handle Relationship>>
 88      table
 89  ****
 90  
 91  include::{generated}/validity/structs/VkDebugUtilsObjectNameInfoEXT.txt[]
 92  
 93  --
 94  
 95  [[debugging-object-data-association]]
 96  ==== Object Data Association
 97  
 98  In addition to setting a name for an object, debugging and validation layers
 99  may: have uses for additional binary data on a per-object basis that have no
100  other place in the Vulkan API.
101  
102  For example, a sname:VkShaderModule could have additional debugging data
103  attached to it to aid in offline shader tracing.
104  
105  Additional data can be attached to an object by calling
106  fname:vkSetDebugUtilsObjectTagEXT as defined below.
107  
108  [open,refpage='vkSetDebugUtilsObjectTagEXT',desc='Attach arbitrary data to an object',type='protos']
109  --
110  
111  include::{generated}/api/protos/vkSetDebugUtilsObjectTagEXT.txt[]
112  
113    * pname:device is the device that created the object.
114    * pname:pTagInfo is a pointer to an instance of the
115      slink:VkDebugUtilsObjectTagInfoEXT structure specifying the parameters
116      of the tag to attach to the object.
117  
118  include::{generated}/validity/protos/vkSetDebugUtilsObjectTagEXT.txt[]
119  
120  --
121  
122  [open,refpage='VkDebugUtilsObjectTagInfoEXT',desc='Specify parameters of a tag to attach to an object',type='structs']
123  --
124  
125  The sname:VkDebugUtilsObjectTagInfoEXT structure is defined as:
126  
127  include::{generated}/api/structs/VkDebugUtilsObjectTagInfoEXT.txt[]
128  
129    * pname:sType is the type of this structure.
130    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
131    * pname:objectType is a elink:VkObjectType specifying the type of the
132      object to be named.
133    * pname:objectHandle is the object to be tagged.
134    * pname:tagName is a numerical identifier of the tag.
135    * pname:tagSize is the number of bytes of data to attach to the object.
136    * pname:pTag is an array of pname:tagSize bytes containing the data to be
137      associated with the object.
138  
139  The pname:tagName parameter gives a name or identifier to the type of data
140  being tagged.
141  This can be used by debugging layers to easily filter for only data that can
142  be used by that implementation.
143  
144  .Valid Usage
145  ****
146    * [[VUID-VkDebugUtilsObjectTagInfoEXT-objectType-01908]]
147      pname:objectType must: not be ename:VK_OBJECT_TYPE_UNKNOWN
148    * [[VUID-VkDebugUtilsObjectTagInfoEXT-objectHandle-01910]]
149      pname:objectHandle must: be a valid Vulkan handle of the type associated
150      with pname:objectType as defined in the <<debugging-object-types,
151      VkObjectType and Vulkan Handle Relationship>> table
152  ****
153  
154  include::{generated}/validity/structs/VkDebugUtilsObjectTagInfoEXT.txt[]
155  
156  --
157  
158  
159  [[debugging-queue-labels]]
160  === Queue Labels
161  
162  All Vulkan work must be submitted using queues.
163  It is possible for an application to use multiple queues, each containing
164  multiple command buffers, when performing work.
165  It can be useful to identify which queue, or even where in a queue,
166  something has occurred.
167  
168  To begin identifying a region using a debug label inside a queue, you may
169  use the flink:vkQueueBeginDebugUtilsLabelEXT command.
170  
171  Then, when the region of interest has passed, you may end the label region
172  using flink:vkQueueEndDebugUtilsLabelEXT.
173  
174  Additionally, a single debug label may be inserted at any time using
175  flink:vkQueueInsertDebugUtilsLabelEXT.
176  
177  [open,refpage='vkQueueBeginDebugUtilsLabelEXT',desc='Open a queue debug label region',type='protos']
178  --
179  
180  A queue debug label region is opened by calling:
181  
182  include::{generated}/api/protos/vkQueueBeginDebugUtilsLabelEXT.txt[]
183  
184    * pname:queue is the queue in which to start a debug label region.
185    * pname:pLabelInfo is a pointer to an instance of the
186      slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
187      label region to open.
188  
189  include::{generated}/validity/protos/vkQueueBeginDebugUtilsLabelEXT.txt[]
190  
191  --
192  
193  [open,refpage='VkDebugUtilsLabelEXT',desc='Specify parameters of a label region',type='structs']
194  --
195  
196  The sname:VkDebugUtilsLabelEXT structure is defined as:
197  
198  include::{generated}/api/structs/VkDebugUtilsLabelEXT.txt[]
199  
200    * pname:sType is the type of this structure.
201    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
202    * pname:pLabelName is a pointer to a null-terminated UTF-8 string that
203      contains the name of the label.
204    * pname:color is an optional RGBA color value that can be associated with
205      the label.
206      A particular implementation may: choose to ignore this color value.
207      The values contain RGBA values in order, in the range 0.0 to 1.0.
208      If all elements in pname:color are set to 0.0 then it is ignored.
209  
210  include::{generated}/validity/structs/VkDebugUtilsLabelEXT.txt[]
211  
212  --
213  
214  [open,refpage='vkQueueEndDebugUtilsLabelEXT',desc='Close a queue debug label region',type='protos']
215  --
216  
217  A queue debug label region is closed by calling:
218  
219  include::{generated}/api/protos/vkQueueEndDebugUtilsLabelEXT.txt[]
220  
221    * pname:queue is the queue in which a debug label region should be closed.
222  
223  The calls to flink:vkQueueBeginDebugUtilsLabelEXT and
224  flink:vkQueueEndDebugUtilsLabelEXT must: be matched and balanced.
225  
226  .Valid Usage
227  ****
228    * [[VUID-vkQueueEndDebugUtilsLabelEXT-None-01911]]
229      There must: be an outstanding fname:vkQueueBeginDebugUtilsLabelEXT
230      command prior to the fname:vkQueueEndDebugUtilsLabelEXT on the queue
231  ****
232  
233  include::{generated}/validity/protos/vkQueueEndDebugUtilsLabelEXT.txt[]
234  
235  --
236  
237  [open,refpage='vkQueueInsertDebugUtilsLabelEXT',desc='Insert a label into a queue',type='protos']
238  --
239  
240  A single label can be inserted into a queue by calling:
241  
242  include::{generated}/api/protos/vkQueueInsertDebugUtilsLabelEXT.txt[]
243  
244    * pname:queue is the queue into which a debug label will be inserted.
245    * pname:pLabelInfo is a pointer to an instance of the
246      slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
247      label to insert.
248  
249  include::{generated}/validity/protos/vkQueueInsertDebugUtilsLabelEXT.txt[]
250  
251  --
252  
253  
254  [[debugging-command-buffer-labels]]
255  === Command Buffer Labels
256  
257  Typical Vulkan applications will submit many command buffers in each frame,
258  with each command buffer containing a large number of individual commands.
259  Being able to logically annotate regions of command buffers that belong
260  together as well as hierarchically subdivide the frame is important to a
261  developer's ability to navigate the commands viewed holistically.
262  
263  To identify the beginning of a debug label region in a command buffer,
264  flink:vkCmdBeginDebugUtilsLabelEXT can: be used as defined below.
265  
266  To indicate the end of a debug label region in a command buffer,
267  flink:vkCmdEndDebugUtilsLabelEXT can: be used.
268  
269  To insert a single command buffer debug label inside of a command buffer,
270  flink:vkCmdInsertDebugUtilsLabelEXT can: be used as defined below.
271  
272  [open,refpage='vkCmdBeginDebugUtilsLabelEXT',desc='Open a command buffer debug label region',type='protos']
273  --
274  
275  A command buffer debug label region can be opened by calling:
276  
277  include::{generated}/api/protos/vkCmdBeginDebugUtilsLabelEXT.txt[]
278  
279    * pname:commandBuffer is the command buffer into which the command is
280      recorded.
281    * pname:pLabelInfo is a pointer to an instance of the
282      slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
283      label region to open.
284  
285  include::{generated}/validity/protos/vkCmdBeginDebugUtilsLabelEXT.txt[]
286  
287  --
288  
289  [open,refpage='vkCmdEndDebugUtilsLabelEXT',desc='Close a command buffer label region',type='protos']
290  --
291  
292  A command buffer label region can be closed by calling:
293  
294  include::{generated}/api/protos/vkCmdEndDebugUtilsLabelEXT.txt[]
295  
296    * pname:commandBuffer is the command buffer into which the command is
297      recorded.
298  
299  An application may: open a debug label region in one command buffer and
300  close it in another, or otherwise split debug label regions across multiple
301  command buffers or multiple queue submissions.
302  When viewed from the linear series of submissions to a single queue, the
303  calls to flink:vkCmdBeginDebugUtilsLabelEXT and
304  flink:vkCmdEndDebugUtilsLabelEXT must: be matched and balanced.
305  
306  .Valid Usage
307  ****
308    * [[VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01912]]
309      There must: be an outstanding fname:vkCmdBeginDebugUtilsLabelEXT command
310      prior to the fname:vkCmdEndDebugUtilsLabelEXT on the queue that
311      pname:commandBuffer is submitted to
312    * [[VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01913]]
313      If pname:commandBuffer is a secondary command buffer, there must: be an
314      outstanding fname:vkCmdBeginDebugUtilsLabelEXT command recorded to
315      pname:commandBuffer that has not previously been ended by a call to
316      fname:vkCmdEndDebugUtilsLabelEXT.
317  ****
318  
319  include::{generated}/validity/protos/vkCmdEndDebugUtilsLabelEXT.txt[]
320  
321  --
322  
323  [open,refpage='vkCmdInsertDebugUtilsLabelEXT',desc='Insert a label into a command buffer',type='protos']
324  --
325  
326  A single debug label can be inserted into a command buffer by calling:
327  
328  include::{generated}/api/protos/vkCmdInsertDebugUtilsLabelEXT.txt[]
329  
330    * pname:commandBuffer is the command buffer into which the command is
331      recorded.
332    * pname:pInfo is a pointer to an instance of the
333      slink:VkDebugUtilsLabelEXT structure specifying the parameters of the
334      label to insert.
335  
336  include::{generated}/validity/protos/vkCmdInsertDebugUtilsLabelEXT.txt[]
337  
338  --
339  
340  
341  [[debugging-debug-messengers]]
342  === Debug Messengers
343  
344  Vulkan allows an application to register multiple callbacks with any Vulkan
345  component wishing to report debug information.
346  Some callbacks may log the information to a file, others may cause a debug
347  break point or other application defined behavior.
348  A primary producer of callback messages are the validation layers.
349  An application can: register callbacks even when no validation layers are
350  enabled, but they will only be called for the Vulkan loader and, if
351  implemented, other layer and driver events.
352  
353  [open,refpage='VkDebugUtilsMessengerEXT',desc='Opaque handle to a debug messenger object',type='handles']
354  --
355  
356  A sname:VkDebugUtilsMessengerEXT is a messenger object which handles passing
357  along debug messages to a provided debug callback.
358  
359  include::{generated}/api/handles/VkDebugUtilsMessengerEXT.txt[]
360  
361  The debug messenger will provide detailed feedback on the application's use
362  of Vulkan when events of interest occur.
363  When an event of interest does occur, the debug messenger will submit a
364  debug message to the debug callback that was provided during its creation.
365  Additionally, the debug messenger is responsible with filtering out debug
366  messages that the callback is not interested in and will only provide
367  desired debug messages.
368  
369  --
370  
371  [open,refpage='vkCreateDebugUtilsMessengerEXT',desc='Create a debug messenger object',type='protos']
372  --
373  
374  A debug messenger triggers a debug callback with a debug message when an
375  event of interest occurs.
376  To create a debug messenger which will trigger a debug callback, call:
377  
378  include::{generated}/api/protos/vkCreateDebugUtilsMessengerEXT.txt[]
379  
380    * pname:instance the instance the messenger will be used with.
381    * pname:pCreateInfo points to a slink:VkDebugUtilsMessengerCreateInfoEXT
382      structure which contains the callback pointer as well as defines the
383      conditions under which this messenger will trigger the callback.
384    * pname:pAllocator controls host memory allocation as described in the
385      <<memory-allocation, Memory Allocation>> chapter.
386    * pname:pMessenger is a pointer to record the
387      sname:VkDebugUtilsMessengerEXT object created.
388  
389  include::{generated}/validity/protos/vkCreateDebugUtilsMessengerEXT.txt[]
390  
391  The application must: ensure that flink:vkCreateDebugUtilsMessengerEXT is
392  not executed in parallel with any Vulkan command that is also called with
393  pname:instance or child of pname:instance as the dispatchable argument.
394  
395  --
396  
397  [open,refpage='VkDebugUtilsMessengerCreateInfoEXT',desc='Structure specifying parameters of a newly created debug messenger',type='structs']
398  --
399  
400  The definition of sname:VkDebugUtilsMessengerCreateInfoEXT is:
401  
402  include::{generated}/api/structs/VkDebugUtilsMessengerCreateInfoEXT.txt[]
403  
404    * pname:sType is the type of this structure.
405    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
406    * pname:flags is 0 and reserved for future use.
407    * pname:messageSeverity is a bitmask of
408      elink:VkDebugUtilsMessageSeverityFlagBitsEXT specifying which severity
409      of event(s) will cause this callback to be called.
410    * pname:messageType is a bitmask of
411      elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of
412      event(s) will cause this callback to be called.
413    * pname:pfnUserCallback is the application callback function to call.
414    * pname:pUserData is user data to be passed to the callback.
415  
416  For each sname:VkDebugUtilsMessengerEXT that is created the
417  sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity and
418  sname:VkDebugUtilsMessengerCreateInfoEXT::pname:messageType determine when
419  that sname:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback is
420  called.
421  The process to determine if the user's pname:pfnUserCallback is triggered
422  when an event occurs is as follows:
423  
424   . The implementation will perform a bitwise AND of the event's
425     elink:VkDebugUtilsMessageSeverityFlagBitsEXT with the
426     pname:messageSeverity provided during creation of the
427     slink:VkDebugUtilsMessengerEXT object.
428   .. If the value is 0, the message is skipped.
429   . The implementation will perform bitwise AND of the event's
430     elink:VkDebugUtilsMessageTypeFlagBitsEXT with the pname:messageType
431     provided during the creation of the slink:VkDebugUtilsMessengerEXT
432     object.
433   .. If the value is 0, the message is skipped.
434   . The callback will trigger a debug message for the current event
435  
436  The callback will come directly from the component that detected the event,
437  unless some other layer intercepts the calls for its own purposes (filter
438  them in a different way, log to a system error log, etc.).
439  
440  An application can: receive multiple callbacks if multiple
441  sname:VkDebugUtilsMessengerEXT objects are created.
442  A callback will always be executed in the same thread as the originating
443  Vulkan call.
444  
445  A callback can: be called from multiple threads simultaneously (if the
446  application is making Vulkan calls from multiple threads).
447  
448  .Valid Usage
449  ****
450    * [[VUID-VkDebugUtilsMessengerCreateInfoEXT-pfnUserCallback-01914]]
451      pname:pfnUserCallback must: be a valid
452      tlink:PFN_vkDebugUtilsMessengerCallbackEXT
453  ****
454  
455  include::{generated}/validity/structs/VkDebugUtilsMessengerCreateInfoEXT.txt[]
456  
457  --
458  
459  [open,refpage='VkDebugUtilsMessageSeverityFlagBitsEXT',desc='Bitmask specifying which severities of events cause a debug messenger callback',type='enums']
460  --
461  
462  Bits which can: be set in
463  slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageSeverity, specifying
464  event severities which cause a debug messenger to call the callback, are:
465  
466  include::{generated}/api/enums/VkDebugUtilsMessageSeverityFlagBitsEXT.txt[]
467  
468    * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT specifies the most
469      verbose output indicating all diagnostic messages from the Vulkan
470      loader, layers, and drivers should be captured.
471    * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT specifies an
472      informational message such as resource details that may be handy when
473      debugging an application.
474    * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT specifies use of
475      Vulkan that may: expose an app bug.
476      Such cases may not be immediately harmful, such as a fragment shader
477      outputting to a location with no attachment.
478      Other cases may: point to behavior that is almost certainly bad when
479      unintended such as using an image whose memory has not been filled.
480      In general if you see a warning but you know that the behavior is
481      intended/desired, then simply ignore the warning.
482    * ename:VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT specifies that the
483      application has violated a valid usage condition of the specification.
484  
485  --
486  
487  [NOTE]
488  .Note
489  ====
490  The values of elink:VkDebugUtilsMessageSeverityFlagBitsEXT are sorted based
491  on severity.
492  The higher the flag value, the more severe the message.
493  This allows for simple boolean operation comparisons when looking at
494  elink:VkDebugUtilsMessageSeverityFlagBitsEXT values.
495  
496  For example:
497  
498  [source,c++]
499  ----------------------------------------
500      if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) {
501          // Do something for warnings and errors
502      }
503  ----------------------------------------
504  
505  In addition, space has been left between the enums to allow for later
506  addition of new severities in between the existing values.
507  ====
508  
509  [open,refpage='VkDebugUtilsMessageSeverityFlagsEXT',desc='Bitmask of VkDebugUtilsMessageSeverityFlagBitsEXT',type='flags']
510  --
511  include::{generated}/api/flags/VkDebugUtilsMessageSeverityFlagsEXT.txt[]
512  
513  tname:VkDebugUtilsMessageSeverityFlagsEXT is a bitmask type for setting a
514  mask of zero or more elink:VkDebugUtilsMessageSeverityFlagBitsEXT.
515  --
516  
517  [open,refpage='VkDebugUtilsMessageTypeFlagBitsEXT',desc='Bitmask specifying which types of events cause a debug messenger callback',type='enums']
518  --
519  
520  Bits which can: be set in
521  slink:VkDebugUtilsMessengerCreateInfoEXT::pname:messageType, specifying
522  event types which cause a debug messenger to call the callback, are:
523  
524  include::{generated}/api/enums/VkDebugUtilsMessageTypeFlagBitsEXT.txt[]
525  
526    * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT specifies that some
527      general event has occurred.
528      This is typically a non-specification, non-performance event.
529    * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT specifies that
530      something has occurred during validation against the Vulkan
531      specification that may indicate invalid behavior.
532    * ename:VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT specifies a
533      potentially non-optimal use of Vulkan, e.g. using
534      flink:vkCmdClearColorImage when setting
535      slink:VkAttachmentDescription::pname:loadOp to
536      ename:VK_ATTACHMENT_LOAD_OP_CLEAR would have worked.
537  
538  --
539  
540  [open,refpage='VkDebugUtilsMessageTypeFlagsEXT',desc='Bitmask of VkDebugUtilsMessageTypeFlagBitsEXT',type='flags']
541  --
542  include::{generated}/api/flags/VkDebugUtilsMessageTypeFlagsEXT.txt[]
543  
544  tname:VkDebugUtilsMessageTypeFlagsEXT is a bitmask type for setting a mask
545  of zero or more elink:VkDebugUtilsMessageTypeFlagBitsEXT.
546  --
547  
548  [open,refpage='PFN_vkDebugUtilsMessengerCallbackEXT',desc='Application-defined debug messenger callback function',type='funcpointers']
549  --
550  
551  The prototype for the
552  slink:VkDebugUtilsMessengerCreateInfoEXT::pname:pfnUserCallback function
553  implemented by the application is:
554  
555  include::{generated}/api/funcpointers/PFN_vkDebugUtilsMessengerCallbackEXT.txt[]
556  
557    * pname:messageSeverity specifies the
558      elink:VkDebugUtilsMessageSeverityFlagBitsEXT that triggered this
559      callback.
560    * pname:messageTypes is a bitmask of
561      elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of
562      event(s) triggered this callback.
563    * pname:pCallbackData contains all the callback related data in the
564      slink:VkDebugUtilsMessengerCallbackDataEXT structure.
565    * pname:pUserData is the user data provided when the
566      slink:VkDebugUtilsMessengerEXT was created.
567  
568  The callback must: not call flink:vkDestroyDebugUtilsMessengerEXT.
569  
570  The callback returns a basetype:VkBool32, which is interpreted in a
571  layer-specified manner.
572  The application should: always return ename:VK_FALSE.
573  The ename:VK_TRUE value is reserved for use in layer development.
574  
575  --
576  
577  [open,refpage='VkDebugUtilsMessengerCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs']
578  --
579  
580  The definition of sname:VkDebugUtilsMessengerCallbackDataEXT is:
581  
582  include::{generated}/api/structs/VkDebugUtilsMessengerCallbackDataEXT.txt[]
583  
584    * pname:sType is the type of this structure.
585    * pname:pNext is `NULL` or a pointer to an extension-specific structure.
586    * pname:flags is 0 and reserved for future use.
587    * pname:pMessageIdName is a null-terminated string that identifies the
588      particular message ID that is associated with the provided message.
589      If the message corresponds to a validation layer message, then this
590      string may contain the portion of the Vulkan specification that is
591      believed to have been violated.
592    * pname:messageIdNumber is the ID number of the triggering message.
593      If the message corresponds to a validation layer message, then this
594      number is related to the internal number associated with the message
595      being triggered.
596    * pname:pMessage is a null-terminated string detailing the trigger
597      conditions.
598    * pname:queueLabelCount is a count of items contained in the
599      pname:pQueueLabels array.
600    * pname:pQueueLabels is NULL or a pointer to an array of
601      slink:VkDebugUtilsLabelEXT active in the current sname:VkQueue at the
602      time the callback was triggered.
603      Refer to <<debugging-queue-labels,Queue Labels>> for more information.
604    * pname:cmdBufLabelCount is a count of items contained in the
605      pname:pCmdBufLabels array.
606    * pname:pCmdBufLabels is NULL or a pointer to an array of
607      slink:VkDebugUtilsLabelEXT active in the current sname:VkCommandBuffer
608      at the time the callback was triggered.
609      Refer to <<debugging-command-buffer-labels, Command Buffer Labels>> for
610      more information.
611    * pname:objectCount is a count of items contained in the pname:pObjects
612      array.
613    * pname:pObjects is a pointer to an array of
614      slink:VkDebugUtilsObjectNameInfoEXT objects related to the detected
615      issue.
616      The array is roughly in order or importance, but the 0th element is
617      always guaranteed to be the most important object for this message.
618  
619  [NOTE]
620  .Note
621  ====
622  This structure should only be considered valid during the lifetime of the
623  triggered callback.
624  ====
625  
626  Since adding queue and command buffer labels behaves like pushing and
627  popping onto a stack, the order of both pname:pQueueLabels and
628  pname:pCmdBufLabels is based on the order the labels were defined.
629  The result is that the first label in either pname:pQueueLabels or
630  pname:pCmdBufLabels will be the first defined (and therefore the oldest)
631  while the last label in each list will be the most recent.
632  
633  [NOTE]
634  .Note
635  ====
636  pname:pQueueLabels will only be non-NULL if one of the objects in
637  pname:pObjects can be related directly to a defined sname:VkQueue which has
638  had one or more labels associated with it.
639  
640  Likewise, pname:pCmdBufLabels will only be non-NULL if one of the objects in
641  pname:pObjects can be related directly to a defined sname:VkCommandBuffer
642  which has had one or more labels associated with it.
643  Additionally, while command buffer labels allow for beginning and ending
644  across different command buffers, the debug messaging framework cannot:
645  guarantee that labels in pname:pCmdBufLables will contain those defined
646  outside of the associated command buffer.
647  This is partially due to the fact that the association of one command buffer
648  with another may not have been defined at the time the debug message is
649  triggered.
650  ====
651  
652  include::{generated}/validity/structs/VkDebugUtilsMessengerCallbackDataEXT.txt[]
653  
654  --
655  
656  [open,refpage='vkSubmitDebugUtilsMessageEXT',desc='Inject a message into a debug stream',type='protos']
657  --
658  
659  There may be times that a user wishes to intentionally submit a debug
660  message.
661  To do this, call:
662  
663  include::{generated}/api/protos/vkSubmitDebugUtilsMessageEXT.txt[]
664  
665    * pname:instance is the debug stream's slink:VkInstance.
666    * pname:messageSeverity is the
667      elink:VkDebugUtilsMessageSeverityFlagBitsEXT severity of this
668      event/message.
669    * pname:messageTypes is a bitmask of
670      elink:VkDebugUtilsMessageTypeFlagBitsEXT specifying which type of
671      event(s) to identify with this message.
672    * pname:pCallbackData contains all the callback related data in the
673      slink:VkDebugUtilsMessengerCallbackDataEXT structure.
674  
675  The call will propagate through the layers and generate callback(s) as
676  indicated by the message's flags.
677  The parameters are passed on to the callback in addition to the
678  pname:pUserData value that was defined at the time the messenger was
679  registered.
680  
681  .Valid Usage
682  ****
683    * [[VUID-vkSubmitDebugUtilsMessageEXT-objectType-02591]]
684      pname:objectType member of each element of
685      pname:pCallbackData\->pname:pObjects must: not be
686      ename:VK_OBJECT_TYPE_UNKNOWN
687  ****
688  
689  include::{generated}/validity/protos/vkSubmitDebugUtilsMessageEXT.txt[]
690  
691  
692  --
693  
694  [open,refpage='vkDestroyDebugUtilsMessengerEXT',desc='Destroy a debug messenger object',type='protos']
695  --
696  
697  To destroy a sname:VkDebugUtilsMessengerEXT object, call:
698  
699  include::{generated}/api/protos/vkDestroyDebugUtilsMessengerEXT.txt[]
700  
701    * pname:instance the instance where the callback was created.
702    * pname:messenger the slink:VkDebugUtilsMessengerEXT object to destroy.
703      pname:messenger is an externally synchronized object and must: not be
704      used on more than one thread at a time.
705      This means that fname:vkDestroyDebugUtilsMessengerEXT must: not be
706      called when a callback is active.
707    * pname:pAllocator controls host memory allocation as described in the
708      <<memory-allocation, Memory Allocation>> chapter.
709  
710  .Valid Usage
711  ****
712    * [[VUID-vkDestroyDebugUtilsMessengerEXT-messenger-01915]]
713      If sname:VkAllocationCallbacks were provided when pname:messenger was
714      created, a compatible set of callbacks must: be provided here
715    * [[VUID-vkDestroyDebugUtilsMessengerEXT-messenger-01916]]
716      If no sname:VkAllocationCallbacks were provided when pname:messenger was
717      created, pname:pAllocator must: be `NULL`
718  ****
719  
720  include::{generated}/validity/protos/vkDestroyDebugUtilsMessengerEXT.txt[]
721  
722  The application must: ensure that flink:vkDestroyDebugUtilsMessengerEXT is
723  not executed in parallel with any Vulkan command that is also called with
724  pname:instance or child of pname:instance as the dispatchable argument.
725  
726  --
727