1Name 2 3 EXT_debug_label 4 5Name Strings 6 7 GL_EXT_debug_label 8 9Contributors 10 11 Seth Sowerby 12 Benj Lipchak 13 Jean-François Roy 14 Charles Brissart 15 16Contact 17 18 Benj Lipchak, Apple (lipchak 'at' apple.com) 19 20Status 21 22 Complete 23 24Version 25 26 Date: October 7, 2013 27 Revision: 4 28 29Number 30 31 OpenGL Extension #439 32 OpenGL ES Extension #98 33 34Dependencies 35 36 Requires OpenGL ES 1.1. 37 38 Written based on the wording of the OpenGL ES 2.0.25 Full Specification 39 (November 2, 2010). 40 41 OpenGL ES 1.1 affects the definition of this extension. 42 43 OES_framebuffer_object affects the definition of this extension. 44 45 OES_vertex_array_object affects the definition of this extension. 46 47 EXT_occlusion_query_boolean affects the definition of this extension. 48 49 EXT_separate_shader_objects affects the definition of this extension. 50 51 OpenGL ES 3.0 affects the definition of this extension. 52 53 OpenGL 3.3+ and 4.0+ affect the definition of this extension. 54 55Overview 56 57 This extension defines a mechanism for OpenGL and OpenGL ES applications to 58 label their objects (textures, buffers, shaders, etc.) with a descriptive 59 string. 60 61 When profiling or debugging such an application within a debugger or 62 profiler it is difficult to identify resources from their object names. 63 Even when the resource itself is viewed it can be problematic to 64 differentiate between similar resources. Attaching a label to an object 65 helps obviate this difficulty. 66 67 The intended purpose of this is purely to improve the user experience 68 within OpenGL and OpenGL ES development tools. 69 70New Procedures and Functions 71 72 void LabelObjectEXT(enum type, uint object, sizei length, 73 const char *label); 74 void GetObjectLabelEXT(enum type, uint object, sizei bufSize, 75 sizei *length, char *label); 76 77New Tokens 78 79 Accepted by the <type> parameter of LabelObjectEXT and 80 GetObjectLabelEXT: 81 82 BUFFER_OBJECT_EXT 0x9151 83 SHADER_OBJECT_EXT 0x8B48 84 PROGRAM_OBJECT_EXT 0x8B40 85 VERTEX_ARRAY_OBJECT_EXT 0x9154 86 QUERY_OBJECT_EXT 0x9153 87 PROGRAM_PIPELINE_OBJECT_EXT 0x8A4F 88 89Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation) 90 91 None 92 93Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 94 95 None 96 97Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 98Operations and the Framebuffer) 99 100 None 101 102Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) 103 104 Add a new section titled Debug Labels 105 106 Debug labels provide a method for annotating an object (texture, buffer, 107 shader, etc.) with a descriptive text label. These labels may then be used 108 by a tool such as a debugger or profiler to describe labeled objects. 109 110 The command 111 112 void LabelObjectEXT(enum type, uint object, sizei length, 113 const char *label); 114 115 labels the object <object> of type <type> with the label <label>. <length> 116 specifies the length of the string passed in <label>. If <label> is a null- 117 terminated string then <length> should not include the terminator. If 118 <length> is 0 and <label> is non-null then <label> is assumed to be null- 119 terminated. If <label> is NULL, any debug label is effectively removed from 120 <object>. 121 122 If <object> is not an object of type <type>, an INVALID_OPERATION error is 123 generated. 124 125 A label is part of the state of the object to which it is associated. 126 The initial state of an object's label is NULL. Labels need not be unique. 127 128 Values supported for <type> are: TEXTURE, FRAMEBUFFER, RENDERBUFFER, 129 BUFFER_OBJECT_EXT, SHADER_OBJECT_EXT, PROGRAM_OBJECT_EXT, 130 VERTEX_ARRAY_OBJECT_EXT, QUERY_OBJECT_EXT, SAMPLER, TRANSFORM_FEEDBACK, and 131 PROGRAM_PIPELINE_OBJECT_EXT. 132 133Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State 134Requests) 135 136 Add a new section titled Debug Labels 137 138 The command 139 140 void GetObjectLabelEXT(enum type, uint object, sizei bufSize, 141 sizei *length, char *label); 142 143 returns in <label> the string labeling the object <object>. The 144 string <label> will be null terminated. The actual number of characters 145 written into <label>, excluding the null terminator, is returned in 146 <length>. If <length> is NULL, no length is returned. The maximum number 147 of characters that may be written into <label>, including the null 148 terminator, is specified by <bufSize>. If no debug label was specified for 149 the object <object> via LabelObjectEXT then <label> will contain an 150 empty string with null terminator and 0 will be returned in <length>. If 151 <label> is NULL and <length> is non-NULL then no string will be returned 152 and the length of the label will be returned in <length>. 153 154 If <object> is not an object of type <type>, an INVALID_OPERATION error is 155 generated. 156 157 Values supported for <type> are: TEXTURE, FRAMEBUFFER, RENDERBUFFER, 158 BUFFER_OBJECT_EXT, SHADER_OBJECT_EXT, PROGRAM_OBJECT_EXT, 159 VERTEX_ARRAY_OBJECT_EXT, QUERY_OBJECT_EXT, SAMPLER, TRANSFORM_FEEDBACK, and 160 PROGRAM_PIPELINE_OBJECT_EXT. 161 162Interactions with OpenGL ES 1.1 and OES_framebuffer_object 163 164 If the GL is OpenGL ES 1.1, mentions of SHADER_OBJECT_EXT and 165 PROGRAM_OBJECT_EXT as types accepted by LabelObjectEXT and 166 GetObjectLabelEXT are omitted. 167 168 If OES_framebuffer_object is supported, FRAMEBUFFER and 169 RENDERBUFFER should be replaced by FRAMEBUFFER_OES and RENDERBUFFER_OES, 170 respectively. Otherwise they should be omitted. 171 172Interactions with OpenGL ES 3.0 and OpenGL 173 174 If the GL is not OpenGL ES 3.0 or OpenGL 3.3+, mentions of 175 SAMPLER as a type accepted by LabelObjectEXT and GetObjectLabelEXT are 176 omitted. 177 178 If the GL is not OpenGL ES 3.0 or OpenGL 4.0+, mentions of 179 TRANSFORM_FEEDBACK as a type accepted by LabelObjectEXT and 180 GetObjectLabelEXT are omitted. 181 182Interactions with OES_vertex_array_object 183 184 If OES_vertex_array_object is not available, mentions of 185 VERTEX_ARRAY_OBJECT_EXT as a type accepted by LabelObjectEXT and 186 GetObjectLabelEXT is omitted. 187 188Interactions with EXT_occlusion_query_boolean 189 190 If EXT_occlusion_query_boolean is not available, mentions of 191 QUERY_OBJECT_EXT as a type accepted by LabelObjectEXT and GetObjectLabelEXT 192 is omitted. 193 194Interactions with EXT_separate_shader_objects 195 196 If EXT_separate_shader_objects is not available, mentions of 197 PROGRAM_PIPELINE_OBJECT_EXT as a type accepted by LabelObjectEXT and 198 GetObjectLabelEXT is omitted. 199 200Errors 201 202 INVALID_OPERATION is generated by LabelObjectEXT or GetObjectLabelEXT 203 if the type of <object> does not match <type>. 204 205 INVALID_ENUM error will be generated by LabelObjectEXT or 206 GetObjectLabelEXT if <type> is not one of the allowed object types. 207 208 INVALID_VALUE is generated by LabelObjectEXT if <length> is less than 209 zero. 210 211 INVALID_VALUE is generated by GetObjectLabelEXT if <bufSize> is less than 212 zero. 213 214New State 215 216 Add the following to Table 6.3 Buffer Object State: 217 218 Initial 219 Get Value Type Get Cmnd Value Description Sec 220 ----------------- ---- ----------------- ------- ----------- --- 221 BUFFER_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 222 223 Add the following to Table 6.8 Textures (state per texture object): 224 225 Initial 226 Get Value Type Get Cmnd Value Description Sec 227 --------- ---- ------------------- ------- ----------- --- 228 TEXTURE 0*xc GetObjectLabelEXT empty Debug label 5.X 229 230 Add the following to Table 6.14 Shader Object State: 231 232 Initial 233 Get Value Type Get Cmnd Value Description Sec 234 ----------------- ---- ----------------- ------- ----------- --- 235 SHADER_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 236 237 Add the following to Table 6.15 Program Object State: 238 239 Initial 240 Get Value Type Get Cmnd Value Description Sec 241 ------------------ ---- ----------------- ------- ----------- --- 242 PROGRAM_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 243 244 Add the following to Table 6.23 Renderbuffer State: 245 246 Initial 247 Get Value Type Get Cmnd Value Description Sec 248 ------------ ---- ------------------- ------- ----------- --- 249 RENDERBUFFER 0*xc GetObjectLabelEXT empty Debug label 5.X 250 251 Add the following to Table 6.24 Framebuffer State: 252 253 Initial 254 Get Value Type Get Cmnd Value Description Sec 255 ----------- ---- ------------------- ------- ----------- --- 256 FRAMEBUFFER 0*xc GetObjectLabelEXT empty Debug label 5.X 257 258 Add the following to Table 6.VAO Vertex Array Object State: 259 260 Initial 261 Get Value Type Get Cmnd Value Description Sec 262 ----------------------- ---- ----------------- ------- ----------- --- 263 VERTEX_ARRAY_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 264 265 Add the following to Table 6.QO Query State: 266 267 Initial 268 Get Value Type Get Cmnd Value Description Sec 269 ---------------- ---- ----------------- ------- ----------- --- 270 QUERY_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 271 272 Add the following to Table 6.PPO Program Pipeline State: 273 274 Init. 275 Get Value Type Get Cmnd Value Description Sec 276 --------------------------- ---- ----------------- ----- ----------- --- 277 PROGRAM_PIPELINE_OBJECT_EXT 0*xc GetObjectLabelEXT empty Debug label 5.X 278 279 Add the following to Table 6.24 Transform Feedback State: 280 281 Get Value Type Get Cmnd Value Description Sec 282 ----------------------- ---- ----------------- ------- ----------- --- 283 TRANSFORM_FEEDBACK 0*xc GetObjectLabelEXT empty Debug label 5.X 284 285 Add the following to the Table 6.1 Textures (state per sampler object): 286 287 Get Value Type Get Cmnd Value Description Sec 288 ----------------------- ---- ----------------- ------- ----------- --- 289 SAMPLER 0*xc GetObjectLabelEXT empty Debug label 5.X 290 291 292New Implementation Dependent State 293 294 None 295 296Issues 297 298 (1) Should labels apply to the currently bound object for the specified 299 type instead of requiring the object name to be specified? 300 301 Resolved: No. 302 303 This would require shaders to be attached to a program which was then 304 linked and bound. This may not occur at the time the shader is created 305 and/or compiled. It might require significant work for developers to label 306 their shaders at the point of creation. 307 308 (2) Should the extension accept FRAGMENT_SHADER & VERTEX_SHADER 309 instead of SHADER_OBJECT_EXT? ARRAY_BUFFER & ELEMENT_ARRAY_BUFFER instead 310 of BUFFER_OBJECT_EXT? 311 312 Resolved: No. 313 314 Specifying FRAGMENT_SHADER or VERTEX_SHADER to disambiguate the type of 315 shader would be necessary only if the resolution to issue #1 were yes, 316 in which case one would label a shader attached to the currently bound 317 program without explicitly specifying the shader's name. The same applies 318 to buffer objects bound to the current vertex attribute array target versus 319 the current element array target. 320 321 (3) Should the extension support printf-style formatting? 322 323 Resolved: No. 324 325 Providing printf-style formatting would impose a much greater burden on the 326 extension in terms of error checking the format string and arguments. 327 Likely all languages capable of calling OpenGL ES have convenient 328 capabilities for formatting strings so it is acceptable to rely on those. 329 330 (4) Should labeling a non-existent object effectively create the object? 331 332 Resolved: No, since some objects require more information (e.g. a texture 333 target) to be properly initialized. 334 335Revision History 336 337 Date 06/15/2011 338 Revision: 1 339 - draft proposal 340 341 Date 07/22/2011 342 Revision: 2 343 - rename APPLE to EXT, update token names and values 344 345 Date 10/18/2012 346 Revision: 3 347 - Add OpenGL ES 3.0 interactions: transform feedback and sampler objects 348 349 Date 10/07/2013 350 Revision: 4 351 - Add support for desktop OpenGL 352