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