1Name 2 3 KHR_gl_texture_2D_image 4 KHR_gl_texture_cubemap_image 5 KHR_gl_texture_3D_image 6 KHR_gl_renderbuffer_image 7 8Name Strings 9 10 EGL_KHR_gl_texture_2D_image 11 EGL_KHR_gl_texture_cubemap_image 12 EGL_KHR_gl_texture_3D_image 13 EGL_KHR_gl_renderbuffer_image 14 15Contributors 16 17 Aaftab Munshi 18 Barthold Lichtenbelt 19 Gary King 20 Jeff Juliano 21 Jon Leech 22 Jonathan Grant 23 Acorn Pooley 24 25Contacts 26 27 Gary King, NVIDIA Corporation (gking 'at' nvidia.com) 28 29Notice 30 31 Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at 32 http://www.khronos.org/registry/speccopyright.html 33 34Status 35 36 Complete. 37 Approved by the Khronos Board of Promoters on February 11, 2008. 38 39Version 40 41 Version 13, October 9, 2013 42 43Number 44 45 EGL Extension #5 46 47Dependencies 48 49 All extensions require EGL 1.2 and the EGL_KHR_image extension 50 51 These extensions are written against the wording of the EGL 1.2 52 Specification. 53 54 KHR_gl_texture_2D_image requires an OpenGL or OpenGL ES client API (any 55 version of either API). 56 57 KHR_gl_texture_cubemap_image requires an OpenGL or OpenGL ES client API 58 supporting texture cube maps, either in the core API or via extensions. 59 60 KHR_gl_texture_3D_image requires KHR_gl_texture_2D_image to be supported 61 by the EGL implementation. It also requires an OpenGL or OpenGL ES 62 client API supporting three-dimensional textures, either in the core API 63 or via extensions. 64 65 KHR_gl_renderbuffer_image requires KHR_gl_texture_2D_image to be 66 supported by the EGL implementation. It also requires an OpenGL or 67 OpenGL ES client API supporting renderbuffers, either in the core API or 68 via extensions. 69 70Overview 71 72 The extensions specified in this document provide a mechanism for 73 creating EGLImage objects from OpenGL and OpenGL ES (henceforth referred 74 to collectively as 'GL') API resources, including two- and three- 75 dimensional textures, cube maps and render buffers. For an overview of 76 EGLImage operation, please see the EGL_KHR_image specification. 77 78 Due to the number of available extensions for the OpenGL ES 1.1 and 79 OpenGL ES 2.0 APIs, this document is organized as 4 separate extensions, 80 described collectively. These extensions are separated based on the 81 required underlying GL functionality (described in the dependencies 82 section). 83 84New Types 85 86 None 87 88New Procedures and Functions 89 90 None 91 92New Tokens 93 94 Accepted in the <target> parameter of eglCreateImageKHR: 95 96 EGL_GL_TEXTURE_2D_KHR 0x30B1 97 98 Accepted as an attribute in the <attr_list> parameter of 99 eglCreateImageKHR: 100 101 EGL_GL_TEXTURE_LEVEL_KHR 0x30BC 102 103 Added by KHR_gl_texture_cubemap_image: 104 105 Accepted in the <target> parameter of eglCreateImageKHR: 106 107 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR 0x30B3 108 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR 0x30B4 109 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR 0x30B5 110 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR 0x30B6 111 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR 0x30B7 112 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR 0x30B8 113 114 Added by KHR_gl_texture_3D_image: 115 116 Accepted in the <target> parameter of eglCreateImageKHR: 117 118 EGL_GL_TEXTURE_3D_KHR 0x30B2 119 120 Accepted as an attribute in the <attr_list> parameter of 121 eglCreateImageKHR: 122 123 EGL_GL_TEXTURE_ZOFFSET_KHR 0x30BD 124 125 Added by KHR_gl_renderbuffer_image: 126 127 Accepted in the <target> parameter of eglCreateImageKHR: 128 129 EGL_GL_RENDERBUFFER_KHR 0x30B9 130 131 132Additions to the EGL Image (EGL_KHR_image) Specification: 133 134 Add the following to Table aaa (Legal values for eglCreateImageKHR 135 <target> parameter), Section 2.5.1 (EGLImage Specification) 136 137 +-------------------------------------+---------------------------------+ 138 | <target> | Notes | 139 +-------------------------------------+---------------------------------+ 140 | EGL_GL_TEXTURE_2D_KHR | Used for GL 2D texture images | 141 +-------------------------------------+---------------------------------+ 142 143 If KHR_gl_texture_cubemap_image is supported: 144 145 +-----------------------------------------+-----------------------------+ 146 | <target> | Notes | 147 +-----------------------------------------+-----------------------------+ 148 | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR | Used for the +X face of | 149 | | GL cubemap texture images | 150 +-----------------------------------------+-----------------------------+ 151 | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR | Used for the -X face of | 152 | | GL cubemap texture images | 153 +-----------------------------------------+-----------------------------+ 154 | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR | Used for the +Y face of | 155 | | GL cubemap texture images | 156 +-----------------------------------------+-----------------------------+ 157 | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR | Used for the -Y face of | 158 | | GL cubemap texture images | 159 +-----------------------------------------+-----------------------------+ 160 | EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR | Used for the +Z face of | 161 | | GL cubemap texture images | 162 +-----------------------------------------+-----------------------------+ 163 | EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR | Used for the -Z face of | 164 | | GL cubemap texture images | 165 +-----------------------------------------+-----------------------------+ 166 167 If KHR_gl_texture_3D_image is supported: 168 169 +-------------------------------------+---------------------------------+ 170 | <target> | Notes | 171 +-------------------------------------+---------------------------------+ 172 | EGL_GL_TEXTURE_3D_KHR | Used for GL 3D texture images | 173 +-------------------------------------+---------------------------------+ 174 175 If KHR_gl_renderbuffer_image is supported: 176 177 +-------------------------------------+---------------------------------+ 178 | <target> | Notes | 179 +-------------------------------------+---------------------------------+ 180 | EGL_GL_RENDERBUFFER_KHR | Used for GL renderbuffer images| 181 +-------------------------------------+---------------------------------+ 182 183 Add the following to Table bbb (Legal attributes for eglCreateImageKHR 184 <attr_list> parameter), Section 2.5.1 (EGLImage Specification) 185 186 +---------------------------+-------------------------------+----------------------------+---------+ 187 | | | Valid | Default | 188 | Attribute | Description | <target>s | Value | 189 +---------------------------+-------------------------------+----------------------------+---------+ 190 | EGL_GL_TEXTURE_LEVEL_KHR | Specifies the mipmap level | EGL_GL_TEXTURE_2D_KHR, | 0 | 191 | | used as the EGLImage source. | EGL_GL_TEXTURE_CUBE_MAP_*, | | 192 | | Must be part of the complete | EGL_GL_TEXTURE_3D_KHR | | 193 | | texture object <buffer> | | | 194 +---------------------------+-------------------------------+----------------------------+---------+ 195 196 If KHR_gl_texture_3D_image is supported: 197 198 +----------------------------+------------------------------+----------------------------+---------+ 199 | | | Valid | Default | 200 | Attribute | Description | <target>s | Value | 201 +----------------------------+------------------------------+----------------------------+---------+ 202 | EGL_GL_TEXTURE_ZOFFSET_KHR | Specifies the depth offset | EGL_GL_TEXTURE_3D_KHR | 0 | 203 | | of the image to use as the | | | 204 | | EGLImage source. Must be | | | 205 | | part of the complete texture| | | 206 | | object <buffer> | | | 207 +----------------------------+------------------------------+----------------------------+---------+ 208 209 210 Insert the following text after paragraph 3 ("If <target> is 211 NATIVE_PIXMAP_KHR...") of Section 2.5.1 (EGLImage Specification) 212 213 "If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_3D_KHR, 214 EGL_GL_RENDERBUFFER_KHR, 215 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR, 216 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR, 217 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR, 218 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR, 219 EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR, or 220 EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR, 221 <dpy> must be a valid EGLDisplay, 222 and <ctx> must be a valid GL API context on that display. 223 224 If <target> is EGL_GL_TEXTURE_2D_KHR, <buffer> must be the name of a 225 nonzero, GL_TEXTURE_2D target texture object, cast into 226 the type EGLClientBuffer. <attr_list> should specify the mipmap level 227 which will be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the 228 specified mipmap level must be part of <buffer>. If not specified, the 229 default value listed in Table bbb will be used, instead. Additional 230 values specified in <attr_list> are ignored. The texture must be complete 231 unless the mipmap level to be used is 0, the texture has mipmap level 0 232 specified, and no other mipmap levels are specified. 233 234 If <target> is one of the EGL_GL_TEXTURE_CUBE_MAP_* enumerants, <buffer> 235 must be the name of a cube-complete, nonzero, GL_TEXTURE_CUBE_MAP (or 236 equivalent in GL extensions) target texture object, cast into the type 237 EGLClientBuffer. <attr_list> should specify the mipmap level which will 238 be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the specified 239 mipmap level must be part of <buffer>. If not specified, the default 240 value listed in Table bbb will be used, instead. Additional values 241 specified in <attr_list> are ignored. The texture must be cube-complete 242 unless the mipmap level to be used is 0, the texture has mipmap level 0 243 specified for all faces, and no other mipmap levels are specified for any 244 faces. 245 246 If <target> is EGL_GL_TEXTURE_3D_KHR, <buffer> must be the name of a 247 complete, nonzero, GL_TEXTURE_3D (or equivalent in GL extensions) target 248 texture object, cast 249 into the type EGLClientBuffer. <attr_list> should specify the mipmap 250 level (EGL_GL_TEXTURE_LEVEL_KHR) and z-offset (EGL_GL_TEXTURE_ZOFFSET_KHR) 251 which will be used as the EGLImage source; the specified mipmap level must 252 be part of <buffer>, and the specified z-offset must be smaller than the 253 depth of the specified mipmap level. If a value is not specified, the 254 default value listed in Table bbb will be used, instead. Additional 255 values specified in <attr_list> are ignored. The texture must be 256 complete unless the mipmap level to be used is 0, the texture has mipmap 257 level 0 specified, and no other mipmap levels are specified. 258 259 If <target> is EGL_GL_RENDERBUFFER_KHR, <buffer> must be the name of a 260 complete, nonzero, non-multisampled GL_RENDERBUFFER (or equivalent in 261 extensions) target object, cast into the type EGLClientBuffer. Values 262 specified in <attr_list> are ignored." 263 264 Add the following errors to the end of the list in Section 2.5.1 (EGLImage 265 Specification): 266 267 " * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, 268 EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <dpy> is not a 269 valid EGLDisplay, the error EGL_BAD_DISPLAY is generated. 270 271 * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, 272 EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a 273 valid EGLContext, the error EGL_BAD_CONTEXT is generated. 274 275 * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, 276 EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a 277 valid GL context, or does not match the <dpy>, the error 278 EGL_BAD_MATCH is generated. 279 280 * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR 281 or EGL_GL_TEXTURE_3D_KHR and <buffer> is not the name of a 282 texture object of type <target>, the error EGL_BAD_PARAMETER 283 is generated. 284 285 * If <target> is EGL_GL_RENDERBUFFER_KHR and <buffer> is not the 286 name of a renderbuffer object, or if <buffer> is the name of a 287 multisampled renderbuffer object, the error EGL_BAD_PARAMETER is 288 generated. 289 290 * If EGL_GL_TEXTURE_LEVEL_KHR is nonzero, <target> is 291 EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or 292 EGL_GL_TEXTURE_3D_KHR, and <buffer> is not the name of a complete 293 GL texture object, the error EGL_BAD_PARAMETER is generated. 294 295 * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is 296 EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or 297 EGL_GL_TEXTURE_3D_KHR, <buffer> is the name of an incomplete GL 298 texture object, and any mipmap levels other than mipmap level 0 299 are specified, the error EGL_BAD_PARAMETER is generated. 300 301 * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is 302 EGL_GL_TEXTURE_2D_KHR or EGL_GL_TEXTURE_3D_KHR, <buffer> is not 303 the name of a complete GL texture object, and mipmap level 0 is 304 not specified, the error EGL_BAD_PARAMETER is generated. 305 306 * If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is 307 EGL_GL_TEXTURE_CUBE_MAP_*_KHR, <buffer> is not the name of a 308 complete GL texture object, and one or more faces do not have 309 mipmap level 0 specified, the error EGL_BAD_PARAMETER is 310 generated. 311 312 * If <target> is EGL_GL_TEXTURE_2D_KHR, 313 EGL_GL_TEXTURE_CUBE_MAP_*_KHR, EGL_GL_RENDERBUFFER_KHR or 314 EGL_GL_TEXTURE_3D_KHR and <buffer> refers to the default GL 315 texture object (0) for the corresponding GL target, the error 316 EGL_BAD_PARAMETER is generated. 317 318 * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR, 319 or EGL_GL_TEXTURE_3D_KHR, and the value specified in <attr_list> 320 for EGL_GL_TEXTURE_LEVEL_KHR is not a valid mipmap level for the 321 specified GL texture object <buffer>, the error EGL_BAD_MATCH is 322 generated. 323 324 * If <target> is EGL_GL_TEXTURE_3D_KHR, and the value specified in 325 <attr_list> for EGL_GL_TEXTURE_ZOFFSET_KHR exceeds the depth 326 of the specified mipmap level-of-detail in <buffer>, the error 327 EGL_BAD_PARAMETER is generated." 328 329 330Issues 331 332 1. What should happen if an application attempts to create an 333 EGLImage from a default OpenGL object (i.e., objects with 334 a name of 0)? 335 336 SUGGESTION: Disallow this operation, and generate an error. 337 338 2. What happens when one of 339 glTexImage2D 340 glCopyTexImage2D 341 glCompressedTexImage2D 342 glTexImage3D 343 glCopyTexImage3D 344 glCompressedTexImage3D 345 is called on a texture which has a mipmap level which is an EGLImage 346 sibling? 347 348 RESOLVED: the EGLImage sibling is orphaned. The mipmap level and the 349 EGLImage no longer have any connection. 350 351 3. What happens when one of 352 glTexSubImage2D 353 glCopyTexSubImage2D 354 glCompressedTexSubImage2D 355 glTexSubImage3D 356 glCopyTexSubImage3D 357 glCompressedTexSubImage3D 358 is called on a texture which has a mipmap level which is an EGLImage 359 sibling? 360 361 RESOLVED: the EGLImage sibling is NOT orphaned. The mipmap level 362 remains an EGLImage sibling. 363 364 4. What happens when glGenerateMipmaps is called on a texture which has a 365 mipmap level which is an EGLImage sibling? 366 367 RESOLVED: If the texture is already complete, then the EGLImage 368 sibling is not orphaned, and the mipmap level remains an EGLImage 369 sibling. However, if the texture was not complete then the 370 EGLImage sibling IS orphaned. This is because the implementation 371 will implicitly alter the structure of the mipmap levels. 372 373 5. What happens when the GL_GENERATE_MIPMAP bit causes a texture to be 374 respecified. 375 376 RESOLVED: If the texture is already complete, then the EGLImage 377 sibling is not orphaned, and the mipmap level remains an EGLImage 378 sibling. However, if the texture was not complete then the 379 EGLImage sibling IS orphaned. This is because the implementation 380 will implicitly alter the structure of the mipmap levels. 381 382 6. Can an EGLImage be created from a multisampled GL image? 383 384 RESOLVED: NO. Attempting to create an EGLImage from a multisampled 385 GL renderbuffer is now an error. Attempting to create from a 386 multisampled OpenGL texture image is not possible because none of 387 the multisampled <target>s are supported. 388 389 7. Are all types of two-dimensional GL images which might 390 be associated with EGLImages allowed? 391 392 Not yet. We could add new variants of these extensions to support 393 other image types such as rectangular and 2D array slice textures, 394 but haven't yet seen a need to do so. 395 396Revision History 397 398#13 (Jon Leech, October 9, 2013) - Define interactions with and support for 399 OpenGL and OpenGL ES 3.0, in addition to OpenGL ES 1/2. Add issue 7 (Bug 400 10728). 401#12 (Jon Leech, September 16, 2013) - Add error when specifying a 402 renderbuffer <target> and passing a multisampled renderbuffer object. 403 Add issue 6 describing lack of support for multisampled EGLImages (Bug 404 10728). 405#11 (Jon Leech, June 26, 2013) - Add error when specifying a renderbuffer 406 <target> and not passing a renderbuffer object (Bug 10384). 407#10 (Jon Leech, June 13, 2013) - Add a "Valid Targets" column to table bbb 408 for new attributes, matching proposed changes in EGL_KHR_image_base (Bug 409 10151). 410#9 (Jon Leech, March 28, 2012) 411 - Fix spelling of *CUBE_MAP* tokens (from CUBEMAP) to agree with 412 eglext.h. 413#8 (Jon Leech, February 4, 2009) 414 - Change "non-default ... texture object" to "nonzero". 415#7 (Bruce Merry, January 20, 2009) 416 - Minor wording improvements on issues 4 and 5. 417#6 (Acorn Pooley, January 13, 2009) 418 - Modify completion requirement so textures with only mipmap level 0 can 419 be EGLImage source siblings. Add issues 2-5. 420#5 (Jon Leech, October 8, 2008) 421 - Updated status (approved as part of OpenKODE 1.0) 422#4 (Jon Leech, April 7, 2007) 423 - Assigned enumerant values 424 - Added OpenKODE 1.0 Provisional disclaimer 425#3 (December 14, 2006) 426 - Changed requirement to egl 1.2 to include EGLClientBuffer type. 427 - formatting to keep within 80 columns 428 - added error condition descriptions for <dpy> and <ctx> 429 - changed error condition for EGL_GL_TEXTURE_ZOFFSET_KHR too big to 430 be EGL_BAD_PARAMETER 431#2 (November 27, 2006) 432 - Changed OES token to KHR 433