1Name 2 3 OES_EGL_image 4 5Name Strings 6 7 GL_OES_EGL_image 8 9Contributors 10 11 Gary King 12 Acorn Pooley 13 Jon Leech 14 15Contacts 16 17 Gary King, NVIDIA Corporation (gking 'at' nvidia.com) 18 19Notice 20 21 Copyright (c) 2006-2014 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Approved by the Khronos OpenKODE Working Group in January, 2007 37 as part of OpenKODE 1.0 Provisional. 38 39Version 40 41 April 23, 2015 (version 8) 42 43Number 44 45 OpenGL ES Extension #23 46 47Dependencies 48 49 Requires OpenGL-ES 1.1 or OpenGL-ES 2.0. 50 51 Requires EGL 1.2 and either the EGL_OES_image or EGL_OES_image_base 52 extensions. 53 54 The EGL_KHR_gl_texture_2D_image, EGL_KHR_gl_texture_cubemap_image, 55 EGL_KHR_gl_texture_3D_image, EGL_KHR_gl_renderbuffer_image, and 56 EGL_KHR_vg_parent_image extensions provide additional functionality 57 layered on EGL_OES_image_base and related to this extension 58 59 OES_framebuffer_object affects the wording of this specification 60 61 This extension is written based on the wording of the OpenGL 2.0 62 Specification and the EXT_framebuffer_object extension. 63 64Overview 65 66 This extension provides a mechanism for creating texture and 67 renderbuffer objects sharing storage with specified EGLImage objects 68 (such objects are referred to as "EGLImage targets"). 69 70 The companion EGL_KHR_image_base and EGL_KHR_image extensions 71 provide the definition and rationale for EGLImage objects. 72 73 Other EGL extensions, such as EGL_KHR_gl_texture_2D_image, 74 EGL_KHR_gl_texture_cubemap_image, EGL_KHR_gl_texture_3D_image, 75 EGL_KHR_gl_renderbuffer_image, and EGL_KHR_vg_parent_image, define 76 the related functionality of creating EGLImage objects from 77 "EGLImage sources" such as OpenGL ES texture or renderbuffers or 78 OpenVG VGImage objects. 79 80 EGL extension specifications are located in the EGL Registry at 81 82 http://www.khronos.org/registry/egl/ 83 84Glossary 85 86 Please see the EGL_KHR_image specification for a list of terms 87 used by this specification. 88 89New Types 90 91 /* 92 * GLeglImageOES is an opaque handle to an EGLImage 93 */ 94 typedef void* GLeglImageOES; 95 96 97New Procedures and Functions 98 99 void EGLImageTargetTexture2DOES(enum target, eglImageOES image) 100 101 void EGLImageTargetRenderbufferStorageOES(enum target, 102 eglImageOES image) 103 104New Tokens 105 106 None. 107 108Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 109 110 - (3.8.2, p. 160) Insert the following text after the end of the 111 first paragraph (before the discussion of {Copy}TexSubImage): 112 113 "Another way of specifying two-dimensional texture images is to 114 reference them from existing EGLImage objects. Images specified 115 this way will be EGLImage siblings with the original EGLImage 116 source and any other EGLImage targets. 117 118 The command 119 120 void EGLImageTargetTexture2DOES(enum target, eglImageOES image); 121 122 defines an entire two-dimensional texture array. All properties 123 of the texture images (including width, height, format, border, mipmap 124 levels of detail, and image data) are taken from the specified 125 eglImageOES <image>, rather than from the client or the framebuffer. 126 Any existing image arrays associated with any mipmap levels in the texture 127 object are freed (as if TexImage was called for each, with an image of 128 zero size). As a result of this referencing operation, all of the pixel 129 data in the <buffer> used as the EGLImage source resource (i.e., the 130 <buffer> parameter passed to the CreateImageOES command that returned 131 <image>) will become undefined. 132 133 Currently, <target> must be TEXTURE_2D. <image> must be the 134 handle of a valid EGLImage resource, cast into the type eglImageOES. 135 Assuming no errors are generated in EGLImageTargetTexture2DOES, the 136 newly specified texture object will be an EGLImage target of the 137 specified eglImageOES. If an application later respecifies any image 138 array in the texture object (through mechanisms such as calls to 139 TexImage2D and/or GenerateMipmapOES, or setting the 140 SGIS_GENERATE_MIPMAP parameter to TRUE), implementations should allocate 141 additional space for all specified (and respecified) image arrays, 142 and copy any existing image data to the newly (re)specified texture 143 object (as if TexImage was called for every level-of-detail in the 144 texture object). The respecified texture object will not be an 145 EGLImage target. 146 147 If the GL is unable to specify a texture object using the supplied 148 eglImageOES <image> (if, for example, <image> refers to a multisampled 149 eglImageOES), the error INVALID_OPERATION is generated. 150 151 If <image> does not refer to a valid eglImageOES object, the error 152 INVALID_VALUE is generated. 153 154 If <target> is not TEXTURE_2D, the error INVALID_ENUM is generated. 155 156Additions to the EXT_framebuffer_object extension 157 158 - (4.4.2.1) Add the following text at the end of section 4.4.2.1 159 (Renderbuffer Objects) 160 161 The command 162 163 void EGLImageTargetRenderbufferStorageOES(enum target, 164 eglImageOES image) 165 166 establishes the data storage, format, and dimensions of a 167 renderbuffer object's image, using the parameters and storage 168 associated with the eglImageOES <image>. Assuming no errors 169 are generated in this process, the resulting renderbuffer 170 will be an EGLImage target of the specifed eglImageOES <image>. 171 The renderbuffer will remain an EGLImage target until it is 172 deleted or respecified by a call to 173 {Reference}RenderbufferStorageOES. As a result of this referencing 174 operation, all of the pixel data in the <buffer> used as the 175 EGLImage source resource (i.e., the <buffer> parameter passed to 176 the CreateImageOES command that returned <image>) will become 177 undefined. 178 179 <target> must be RENDERBUFFER_OES, and <image> must be the 180 handle of a valid EGLImage resource, cast into the type 181 eglImageOES. 182 183 If the GL is unable to create a renderbuffer using the specified 184 eglImageOES, the error INVALID_OPERATION is generated. If <image> 185 does not refer to a valid eglImageOES object, the error 186 INVALID_VALUE is generated. 187 188Issues 189 190 1. What happens if an application tries to specify a new mipmap 191 level (or respecify an existing mipmap level) for a texture 192 object that was originally specified using 193 EGLImageTargetTexture2D (e.g., by subsequent calls to 194 {Copy}TexImage, GenerateMipmapOES, and/or setting the 195 texture's GENERATE_MIPMAP_SGIS parameter to TRUE) ? 196 197 RESOLVED: If the application respecifies any properties of 198 an EGLImage target texture, the GL should allocate additional 199 memory for the respecified object, copying any data from 200 previously-specified levels (including those in the EGLImage 201 source). The respecified texture object will not be an 202 EGLImage target, potentially orphaning the EGLImage. 203 204 2. What happens if multiple texture or renderbuffer objects, which 205 are each EGLImage siblings, are attached to multiple attachment 206 points of a framebuffer object? 207 208 RESOLVED: There are several possibilities for handling this 209 situation, listed below. The primary goal for any solution 210 should be minimizing the required run-time error checking & 211 validation, since determining that two objects refer to the same 212 parent resource is a complex operation. 213 214 i. Generate an error if a context share group attempts to create 215 two EGLImage siblings (either source or target) . 216 217 This limits error checking to just EGLImageTargetTexture / 218 EGLImageTargetRenderbufferStorage, which should be infrequent 219 calls, particularly during run-time. However, some potentially 220 valuable use cases are restricted with this approach, such 221 as referencing 2D texture objects from cube map EGLImage sources 222 in the same context share group. 223 224 ii. Add a new clause to the framebuffer completeness test that 225 disallows multiple EGLImage siblings being attached to the 226 same framebuffer object. 227 228 This would be in the spirit of the OES_framebuffer_object 229 extension and does not limit any valuable use cases; however, 230 it has the potential to significantly increase runtime 231 overhead, given the complexity of this completeness check 232 and the potential frequency that framebuffer completeness 233 may need to be checked. 234 235 iii. Leave the rendering results undefined, but require that 236 behavior be limited to undefined rendering results (i.e., 237 the application and/or system may not crash as a result 238 of this operation). 239 240 This solution allows implementations the opportunity to have 241 virtually no additional run-time validation overhead, nor 242 are any valuable use cases restricted. Implementations 243 may consider framebuffer objects which contain multiple 244 EGLImage siblings as incomplete framebuffers if necessary to 245 ensure application & system stability. 246 247 SUGGESTION: Solution (iii). The only reasonable well-defined 248 behavior for this type of API usage is an error; however, given 249 the potential for the error check to noticeably increase validation 250 overhead, leaving this behavior undefined seems like the best 251 choice. 252 253 3. What about portability problems introduced by allowing implementation- 254 dependent failures? 255 256 UNRESOLVED: This is the same issue described in Issue 14 of the 257 EGL_KHR_image_base specification. Like the resolution for that 258 issue, this specification should include some minimum 259 requirements, but leave the larger portability problem 260 unresolved at the moment. 261 262 4. Should EGLImageTargetTexture2DOES and 263 EGLImageTargetRenderBufferStorageOES result in undefined pixel data, 264 as with calls to eglCreateImageOES? 265 266 UNRESOLVED: One of the problems with allowing the referencing 267 functions to result in undefined pixel data is that the EGLImage 268 source object may be part of a larger image structure (such as 269 an array of mipmap levels-of-detail, or cube map faces). While we 270 can specify that the pixel data in the EGLImage become undefined 271 quite easily, specifying that the pixel data in other images become 272 undefined is more difficult. So, with that discussion, the following 273 options were considered: 274 275 i. Specify that the pixel data in the EGLImage, and other image 276 arrays associated with the EGLImage source, become undefined 277 as a result of referencing. 278 279 ii. Specify that only the pixel data in the EGLImage becomes 280 undefined; any data in other image arrays associated with the 281 EGLImage source must not be affected by the referencing 282 operation. 283 284 iii. Specify that the pixel data in the EGLImage is unaffected as 285 a result of the referencing operation. 286 287 Option (i) gives the greatest flexibility (and potentially ease- 288 of implementation) to implementers, which should may result in 289 implementations exporting a larger number of compatible configurations 290 than the other, stricter options. Additionally, for well-behaved 291 applications (i.e., applications which perform all resource creation 292 and referencing prior to use), making the image data undefined will 293 not have any adverse side effects. 294 295 Option (ii) provides option (i)'s benefits if the EGLImage source 296 is a trivial image (i.e., no additional mipmap levels-of-detail, 297 3D texture slices, etc.); however, some implementations may be 298 required to implement potentially-expensive copy operations to support 299 complex EGLImage source images. 300 301 Option (iii) is the strictest, and may significantly impede 302 implementers' ability to expose compatible configurations. 303 304 Weighing the benefits (increased configuration compatibility and ease- 305 / performance- of implementation) versus the costs (specification 306 ugliness), the specification has currently selected option (i), 307 favoring compatibility and performance. 308 309 310 5. What should the entry point for referencing 2D textures be named? 311 312 UNRESOLVED: Unfortunately, OpenGL is not particularly consistent 313 with texture naming conventions. However, most texture function 314 names have followed the convention of using a verb- or adjective- 315 specifier followed by the object type, e.g. : CopyTexImage, 316 CompressedTexImage, DrawPixels, etc. 317 318 Therefore, this issue can be broken into two sub-issues: naming 319 the verb or adjective and naming the object type. 320 321 The following options were considered for the verb or adjective: 322 a1) Reference / Referenced 323 a2) EGLImageTarget 324 325 Reference (a1) is the verb for creating EGLImage targets from 326 EGLImages (defined in the EGL_OES_image specification), but 327 "Reference<blah>" might confuse some developers, since the 328 direction of the verb sounds backwards. 329 330 Therefore, option (a2) has been selected, since the newly- 331 specified texture object will be an EGLImage target. 332 333 And the following options were considered for the object type: 334 b1) TexImage 335 b2) Texture 336 b3) TextureObject 337 338 (b1) follows the convention used by other texture specification 339 functions; however, unlike {Copy,Compressed}TexImage, which 340 specify only a single mipmap level-of-detail, the referencing 341 entry point respecifies all image arrays in the texture object. 342 343 (b2) and (b3) address the issues with (b1). The OpenGL 344 specification interchangeably uses "texture" and "texture object" 345 to refer to the entire collection of image arrays, so either 346 choice seems reasonable. For brevity, (b2) has been used 347 in this specification. 348 349 Note, though, that eglBindTexImage also respecifies all image 350 arrays in the texture object, but it does not change the 351 TexImage suffix. 352 353 Another option would be to treat the referencing function as an 354 attachment, rather than a specification, in which case a more 355 appropriate name would follow the convention used in the 356 OES_framebuffer_object extension, such as Texture2DeglImageOES. 357 358 6. What should the entry point for referencing renderbuffers be named? 359 360 UNRESOLVED: There are far fewer conventions for renderbuffer 361 function names than there are for textures, so the naming for 362 this function should use whichever convention is selected 363 to resolve Issue 5. Given the current selections in that issue, 364 EGLImageTargetRenderbufferStorage is being used. 365 366Dependencies on EGL_KHR_image, EGL_KHR_image_base, and EGL 1.2 367 368 If EGL 1.2 is not supported, or if neither the EGL_OES_image nor 369 EGL_OES_image_base extensions is supported, all discussion of 370 EGLImages should be ignored, and any calls to either 371 EGLImageTargetTexture2DOES or EGLImageTargetRenderbufferStorageOES 372 should generate the error INVALID_OPERATION. 373 374Dependencies on OES_framebuffer_object 375 376 If the OES_framebuffer_object extension is not supported, all 377 discussion of renderbuffers should be ignored, and all calls to 378 EGLImageTargetRenderbufferStorageOES should generate the error 379 INVALID_OPERATION. 380 381Revision History 382 383 #8 (April 23, 2015, Jon Leech) 384 - Fix typo EGLImageTargetTexImage2DOES -> EGLImageTargetTexture2DOES 385 (Bug 8114). 386 387 #7 (April 17, 2014, Jon Leech) 388 - Add missing error for invalid <image> parameter to 389 EGLImageTargetTexture2DOES (Bug 5164). 390 391 #6 (April 1, 2009, Acorn Pooley, Jon Leech) 392 - Fix dependancy typo. Mention EGL_KHR_image_base. Correct 393 spelling of EGL_KHR_image and refer to alternate 394 EGL_KHR_image_base. Correct dependency on EGL from 1.1 to 1.2. 395 Change filename in the registry to correspond to capitalization 396 of the extension string. Don't update the version number 397 further until all internal edits are completed. 398 399 #5 (April 1, 2009, Jon Leech) 400 - Added more overview pointing to companion EGL extensions. 401 402 #4 (April 22, 2007, Jon Leech) 403 - Added updated 'Status' to reflect OpenKODE 1.0 Provisional. 404 405 #3 (December 14, 2006) 406 - Changed requirement to egl 1.2 to include EGLClientBuffer type. 407 408 #2 (October 20, 2006) 409 - Reworded phrasing describing undefined pixel data as a 410 result of EGLImageTarget* commands 411 412 #1 - Original Release 413