/ appendices / VK_EXT_debug_marker.txt
VK_EXT_debug_marker.txt
1 include::meta/VK_EXT_debug_marker.txt[] 2 3 *Last Modified Date*:: 4 2017-01-31 5 *IP Status*:: 6 No known IP claims. 7 *Contributors*:: 8 - Baldur Karlsson 9 - Dan Ginsburg, Valve 10 - Jon Ashburn, LunarG 11 - Kyle Spagnoli, NVIDIA 12 13 The `VK_EXT_debug_marker` extension is a device extension. 14 It introduces concepts of object naming and tagging, for better tracking of 15 Vulkan objects, as well as additional commands for recording annotations of 16 named sections of a workload to aid organization and offline analysis in 17 external tools. 18 19 === New Object Types 20 21 None 22 23 === New Enum Constants 24 25 * Extending elink:VkStructureType: 26 ** ename:VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT 27 ** ename:VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT 28 ** ename:VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT 29 30 === New Enums 31 32 None 33 34 === New Structures 35 36 * slink:VkDebugMarkerObjectNameInfoEXT 37 * slink:VkDebugMarkerObjectTagInfoEXT 38 * slink:VkDebugMarkerMarkerInfoEXT 39 40 === New Functions 41 42 * flink:vkDebugMarkerSetObjectTagEXT 43 * flink:vkDebugMarkerSetObjectNameEXT 44 * flink:vkCmdDebugMarkerBeginEXT 45 * flink:vkCmdDebugMarkerEndEXT 46 * flink:vkCmdDebugMarkerInsertEXT 47 48 === Examples 49 50 *Example 1* 51 52 Associate a name with an image, for easier debugging in external tools or 53 with validation layers that can print a friendly name when referring to 54 objects in error messages. 55 56 [source,c++] 57 ---------------------------------------- 58 extern VkDevice device; 59 extern VkImage image; 60 61 // Must call extension functions through a function pointer: 62 PFN_vkDebugMarkerSetObjectNameEXT pfnDebugMarkerSetObjectNameEXT = (PFN_vkDebugMarkerSetObjectNameEXT)vkGetDeviceProcAddr(device, "vkDebugMarkerSetObjectNameEXT"); 63 64 // Set a name on the image 65 const VkDebugMarkerObjectNameInfoEXT imageNameInfo = 66 { 67 VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT, // sType 68 NULL, // pNext 69 VK_DEBUG_REPORT_OBJECT_TYPE_IMAGE_EXT, // objectType 70 (uint64_t)image, // object 71 "Brick Diffuse Texture", // pObjectName 72 }; 73 74 pfnDebugMarkerSetObjectNameEXT(device, &imageNameInfo); 75 76 // A subsequent error might print: 77 // Image 'Brick Diffuse Texture' (0xc0dec0dedeadbeef) is used in a 78 // command buffer with no memory bound to it. 79 ---------------------------------------- 80 81 *Example 2* 82 83 Annotating regions of a workload with naming information so that offline 84 analysis tools can display a more usable visualisation of the commands 85 submitted. 86 87 [source,c++] 88 ---------------------------------------- 89 extern VkDevice device; 90 extern VkCommandBuffer commandBuffer; 91 92 // Must call extension functions through a function pointer: 93 PFN_vkCmdDebugMarkerBeginEXT pfnCmdDebugMarkerBeginEXT = (PFN_vkCmdDebugMarkerBeginEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerBeginEXT"); 94 PFN_vkCmdDebugMarkerEndEXT pfnCmdDebugMarkerEndEXT = (PFN_vkCmdDebugMarkerEndEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerEndEXT"); 95 PFN_vkCmdDebugMarkerInsertEXT pfnCmdDebugMarkerInsertEXT = (PFN_vkCmdDebugMarkerInsertEXT)vkGetDeviceProcAddr(device, "vkCmdDebugMarkerInsertEXT"); 96 97 // Describe the area being rendered 98 const VkDebugMarkerMarkerInfoEXT houseMarker = 99 { 100 VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType 101 NULL, // pNext 102 "Brick House", // pMarkerName 103 { 1.0f, 0.0f, 0.0f, 1.0f }, // color 104 }; 105 106 // Start an annotated group of calls under the 'Brick House' name 107 pfnCmdDebugMarkerBeginEXT(commandBuffer, &houseMarker); 108 { 109 // A mutable structure for each part being rendered 110 VkDebugMarkerMarkerInfoEXT housePartMarker = 111 { 112 VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT, // sType 113 NULL, // pNext 114 NULL, // pMarkerName 115 { 0.0f, 0.0f, 0.0f, 0.0f }, // color 116 }; 117 118 // Set the name and insert the marker 119 housePartMarker.pMarkerName = "Walls"; 120 pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker); 121 122 // Insert the drawcall for the walls 123 vkCmdDrawIndexed(commandBuffer, 1000, 1, 0, 0, 0); 124 125 // Insert a recursive region for two sets of windows 126 housePartMarker.pMarkerName = "Windows"; 127 pfnCmdDebugMarkerBeginEXT(commandBuffer, &housePartMarker); 128 { 129 vkCmdDrawIndexed(commandBuffer, 75, 6, 1000, 0, 0); 130 vkCmdDrawIndexed(commandBuffer, 100, 2, 1450, 0, 0); 131 } 132 pfnCmdDebugMarkerEndEXT(commandBuffer); 133 134 housePartMarker.pMarkerName = "Front Door"; 135 pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker); 136 137 vkCmdDrawIndexed(commandBuffer, 350, 1, 1650, 0, 0); 138 139 housePartMarker.pMarkerName = "Roof"; 140 pfnCmdDebugMarkerInsertEXT(commandBuffer, &housePartMarker); 141 142 vkCmdDrawIndexed(commandBuffer, 500, 1, 2000, 0, 0); 143 } 144 // End the house annotation started above 145 pfnCmdDebugMarkerEndEXT(commandBuffer); 146 ---------------------------------------- 147 148 === Issues 149 150 1) Should the tag or name for an object be specified using the pname:pNext 151 parameter in the object's stext:Vk*CreateInfo structure? 152 153 *RESOLVED*: No. 154 While this fits with other Vulkan patterns and would allow more type safety 155 and future proofing against future objects, it has notable downsides. 156 In particular passing the name at stext:Vk*CreateInfo time does not allow 157 renaming, prevents late binding of naming information, and does not allow 158 naming of implicitly created objects such as queues and swapchain images. 159 160 2) Should the command annotation functions flink:vkCmdDebugMarkerBeginEXT 161 and flink:vkCmdDebugMarkerEndEXT support the ability to specify a color? 162 163 *RESOLVED*: Yes. 164 The functions have been expanded to take an optional color which can be used 165 at will by implementations consuming the command buffer annotations in their 166 visualisation. 167 168 3) Should the functions added in this extension accept an extensible 169 structure as their parameter for a more flexible API, as opposed to direct 170 function parameters? If so, which functions? 171 172 *RESOLVED*: Yes. 173 All functions have been modified to take a structure type with extensible 174 pname:pNext pointer, to allow future extensions to add additional annotation 175 information in the same commands. 176 177 === Version History 178 179 * Revision 1, 2016-02-24 (Baldur Karlsson) 180 - Initial draft, based on LunarG marker spec 181 182 * Revision 2, 2016-02-26 (Baldur Karlsson) 183 - Renamed Dbg to DebugMarker in function names 184 - Allow markers in secondary command buffers under certain circumstances 185 - Minor language tweaks and edits 186 187 * Revision 3, 2016-04-23 (Baldur Karlsson) 188 - Reorganise spec layout to closer match desired organisation 189 - Added optional color to markers (both regions and inserted labels) 190 - Changed functions to take extensible structs instead of direct function 191 parameters 192 193 * Revision 4, 2017-01-31 (Baldur Karlsson) 194 - Added explicit dependency on VK_EXT_debug_report 195 - Moved definition of elink:VkDebugReportObjectTypeEXT to debug report 196 chapter. 197 - Fixed typo in dates in revision history