1Name 2 3 KHR_image_base 4 5Name Strings 6 7 EGL_KHR_image_base 8 9Contributors 10 11 Jeff Juliano 12 Gary King 13 Jon Leech 14 Jonathan Grant 15 Barthold Lichtenbelt 16 Aaftab Munshi 17 Acorn Pooley 18 Chris Wynn 19 20Contacts 21 22 Jon Leech (jon 'at' alumni.caltech.edu) 23 Gary King, NVIDIA Corporation (gking 'at' nvidia.com) 24 25Notice 26 27 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 28 http://www.khronos.org/registry/speccopyright.html 29 30Status 31 32 Complete. Functionality approved (as part of KHR_image) by the 33 Khronos Board of Promoters on February 11, 2008. 34 35 Split into KHR_image_base and KHR_image_pixmap approved by the 36 Khronos Technical Working Group on November 19, 2008. Update to 37 version 5 approved on December 10, 2008. 38 39Version 40 41 Version 8, August 27, 2014 42 43Number 44 45 EGL Extension #8 46 47Dependencies 48 49 EGL 1.2 is required. 50 51 An EGL client API, such as OpenGL ES or OpenVG, is required. 52 53 This extension is written against the wording of the EGL 1.2 54 Specification. 55 56Overview 57 58 This extension defines a new EGL resource type that is suitable for 59 sharing 2D arrays of image data between client APIs, the EGLImage. 60 Although the intended purpose is sharing 2D image data, the 61 underlying interface makes no assumptions about the format or 62 purpose of the resource being shared, leaving those decisions to 63 the application and associated client APIs. 64 65Glossary 66 67 EGLImage: An opaque handle to a shared resource created by EGL 68 client APIs, presumably a 2D array of image data 69 70 EGLImage source: An object or sub-object originally created in 71 a client API (such as a mipmap level of a texture object 72 in OpenGL-ES, or a VGImage in OpenVG) which is used as 73 the <buffer> parameter in a call to eglCreateImageKHR. 74 75 EGLImage target: An object created in a client API (such as a 76 texture object in OpenGL-ES or a VGImage in OpenVG) 77 from a previously-created EGLImage 78 79 EGLImage sibling: The set of all EGLImage targets (in all 80 client API contexts) which are created from the 81 same EGLImage object, and the EGLImage source resouce 82 which was used to create that EGLImage. 83 84 Orphaning: The process of respecifying and/or deleting an EGLImage 85 sibling resource (inside a client API context) which 86 does not result in deallocation of the memory associated 87 with the EGLImage or affect rendering results using other 88 EGLImage siblings. 89 90 Referencing: The process of creating an EGLImage target resource 91 (inside a client API context) from an EGLImage. 92 93 Respecification: When the size, format, or other attributes of an 94 EGLImage sibling are changed via client API calls such as 95 gl*TexImage*. Respecification usually will result in 96 orphaning the sibling. Note that changing the pixel values of 97 the sibling (e.g. by rendering to it or by calling 98 gl*TexSubImage*) does not constitute respecification. 99 100New Types 101 102 /* 103 * EGLImageKHR is an object which can be used to create EGLImage 104 * target resources (inside client APIs). 105 */ 106 typedef void* EGLImageKHR; 107 108New Procedures and Functions 109 110 EGLImageKHR eglCreateImageKHR( 111 EGLDisplay dpy, 112 EGLContext ctx, 113 EGLenum target, 114 EGLClientBuffer buffer, 115 const EGLint *attrib_list) 116 117 EGLBoolean eglDestroyImageKHR( 118 EGLDisplay dpy, 119 EGLImageKHR image) 120 121New Tokens 122 123 Returned by eglCreateImageKHR: 124 125 EGL_NO_IMAGE_KHR ((EGLImageKHR)0) 126 127 Accepted as an attribute in the <attrib_list> parameter of 128 eglCreateImageKHR: 129 130 EGL_IMAGE_PRESERVED_KHR 0x30D2 131 132Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation) 133 134 Add a new section "EGLImages" after section 2.4: 135 136 "2.5 EGLImages 137 138 As described in section 2.4, EGL allows contexts of the same client 139 API type to share significant amounts of state (such as OpenGL-ES 140 texture objects and OpenVG paths); however, in some cases it may 141 be desirable to share state between client APIs - an example would be 142 using a previously-rendered OpenVG image as an OpenGL-ES texture 143 object. 144 145 In order to facilitate these more complicated use-cases, EGL is capable 146 of creating EGL resources that can be shared between contexts of 147 different client APIs (called "EGLImages") from client API resources 148 such as texel arrays in OpenGL-ES texture objects or OpenVG VGImages 149 (collectively, the resources that are used to create EGLImages are 150 referred to as "EGLImage sources"). 151 152 The EGL client APIs each provide mechanisms for creating appropriate 153 resource types (such as complete texture arrays or OpenVG VGImages) from 154 EGLImages through a API-specific mechanisms. Collectively, resources 155 which are created from EGLImages within client APIs are referred to as 156 "EGLImage targets." Each EGLImage may have multiple associated EGLImage 157 targets. Collectively, the EGLImage source and EGLImage targets 158 associated with an EGLImage object are referred to as "EGLImage 159 siblings." 160 161 2.5.1 EGLImage Specification 162 163 The command 164 165 EGLImageKHR eglCreateImageKHR( 166 EGLDisplay dpy, 167 EGLContext ctx, 168 EGLenum target, 169 EGLClientBuffer buffer, 170 const EGLint *attrib_list) 171 172 is used to create an EGLImage from an existing image resource <buffer>. 173 <dpy> specifies the EGL display used for this operation. 174 <ctx> specifies the EGL client API context 175 used for this operation, or EGL_NO_CONTEXT if a client API context is not 176 required. <target> specifies the type of resource being used as the 177 EGLImage source (examples include two-dimensional textures in OpenGL ES 178 contexts and VGImage objects in OpenVG contexts). <buffer> is the name 179 (or handle) of a resource to be used as the EGLImage source, cast into the 180 type EGLClientBuffer. <attrib_list> is an list of attribute-value pairs 181 which is used to select sub-sections of <buffer> for use as the EGLImage 182 source, such as mipmap levels for OpenGL ES texture map resources, as well as 183 behavioral options, such as whether to preserve pixel data during creation. If 184 <attrib_list> is non-NULL, the last attribute specified in the list must 185 be EGL_NONE. 186 187 The resource specified by <dpy>, <ctx>, <target>, <buffer>, and 188 <attrib_list> must not itself be an EGLImage sibling, or bound to an EGL 189 PBuffer resource (eglBindTexImage, eglCreatePbufferFromClientBuffer). 190 191 Values accepted for <target> are listed in Table aaa, below(fn1). 192 (fn1) No values are defined by this extension. All functionality 193 to create EGLImages from other types of resources, such as 194 native pixmaps, GL textures, and VGImages, is layered in other 195 extensions. 196 197 +-------------------------+--------------------------------------------+ 198 | <target> | Notes | 199 +-------------------------+--------------------------------------------+ 200 +-------------------------+--------------------------------------------+ 201 Table aaa. Legal values for eglCreateImageKHR <target> parameter 202 203 Attribute names accepted in <attrib_list> are shown in Table bbb, 204 together with the <target> for which each attribute name is valid, and 205 the default value used for each attribute if it is not included in 206 <attrib_list>. 207 208 +-------------------------+----------------------+-----------+---------------+ 209 | Attribute | Description | Valid | Default Value | 210 | | | <target>s | | 211 +-------------------------+----------------------+-----------+---------------+ 212 | EGL_NONE | Marks the end of the | All | N/A | 213 | | attribute-value list | | | 214 | EGL_IMAGE_PRESERVED_KHR | Whether to preserve | All | EGL_FALSE | 215 | | pixel data | | | 216 +-------------------------+----------------------+-----------+---------------+ 217 Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter 218 219 This command returns an EGLImageKHR object corresponding to the image 220 data specified by <dpy>, <ctx>, <target>, <buffer> and <attrib_list> which 221 may be referenced by client API operations, or EGL_NO_IMAGE_KHR in the 222 event of an error. 223 224 If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_FALSE (the 225 default), then all pixel data values associated with <buffer> will be 226 undefined after eglCreateImageKHR returns. 227 228 If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_TRUE, then all 229 pixel data values associated with <buffer> are preserved. 230 231 Errors 232 233 If eglCreateImageKHR fails, EGL_NO_IMAGE_KHR will be returned, the 234 contents of <buffer> will be unaffected, and one of the following 235 errors will be generated: 236 237 * If <dpy> is not the handle of a valid EGLDisplay object, the error 238 EGL_BAD_DISPLAY is generated. 239 240 * If <ctx> is neither the handle of a valid EGLContext object on 241 <dpy> nor EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is 242 generated. 243 244 * If <target> is not one of the values in Table aaa, the error 245 EGL_BAD_PARAMETER is generated. 246 247 * If an attribute specified in <attrib_list> is not one of the 248 attributes listed in Table bbb, the error EGL_BAD_PARAMETER is 249 generated. 250 251 * If an attribute specified in <attrib_list> is not a valid attribute 252 for <target>, as shown in Table bbb, the error EGL_BAD_MATCH is 253 generated. 254 255 * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and 256 <attrib_list> has an off-screen buffer bound to it (e.g., by a 257 previous call to eglBindTexImage), the error EGL_BAD_ACCESS is 258 generated. 259 260 * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and 261 <attrib_list> is bound to an off-screen buffer (e.g., by a previous 262 call to eglCreatePbufferFromClientBuffer), the error 263 EGL_BAD_ACCESS is generated. 264 265 * If the resource specified by <dpy>, <ctx>, <target>, <buffer> and 266 <attrib_list> is itself an EGLImage sibling, the error 267 EGL_BAD_ACCESS is generated. 268 269 * If insufficient memory is available to complete the specified 270 operation, the error EGL_BAD_ALLOC is generated. 271 272 * If the call to eglCreateImageKHR fails for multiple reasons, the 273 generated error must be appropriate for one of the reasons, 274 although the specific error returned is undefined. 275 276 * If the value specified in <attrib_list> for EGL_IMAGE_PRESERVED_KHR 277 is EGL_TRUE, and an EGLImageKHR handle cannot be created from the 278 specified resource such that the pixel data values in <buffer> are 279 preserved, the error EGL_BAD_ACCESS is generated. 280 281 Note that the success or failure of eglCreateImageKHR should not affect 282 the ability to use <buffer> in its original API context (or context 283 share group) (although the pixel data values will be undefined if 284 EGL_IMAGE_PRESERVED_KHR is not EGL_TRUE). 285 286 2.5.2 Lifetime and Usage of EGLImages 287 288 Once an EGLImage is created from an EGLImage source, the memory associated 289 with the EGLImage source will remain allocated (and all EGLImage siblings 290 in all client API contexts will be useable) as long as either of the 291 following conditions is true: 292 A) Any EGLImage siblings exist in any client API context 293 B) The EGLImage object exists inside EGL 294 295 The semantics for specifying, deleting and using EGLImage siblings are 296 client API-specific, and are described in the appropriate API 297 specifications. 298 299 If an application specifies an EGLImage sibling as the destination for 300 rendering and/or pixel download operations (e.g., as an OpenGL-ES 301 framebuffer object, glTexSubImage2D, etc.), the modified image results 302 will be observed by all EGLImage siblings in all client API contexts. 303 If multiple client API contexts access EGLImage sibling resources 304 simultaneously, with one or more context modifying the image data, 305 rendering results in all contexts accessing EGLImage siblings are 306 undefined. 307 308 Respecification and/or deletion of any EGLImage sibling (i.e., both 309 EGLImage source and EGLImage target resources) inside a client API 310 context (e.g., by issuing a subsequent call to 311 gl{Copy,Compressed}TexImage, glDeleteTextures, with the EGLImage 312 sibling resource as the target of the operation) affects only that 313 client API context and other contexts within its share group. The 314 specific semantics for this behavior are defined by each client API, 315 and generally results in orphaning of the EGLImage, and may also 316 include allocation of additional memory for the respecified resource 317 and/or copying of the EGLImage pixel data. 318 319 Operations inside EGL or any client API context which may affect the 320 lifetime of an EGLImage (or the memory allocated for the EGLImage), 321 such as respecifying and/or deleting an EGLImage sibling inside a 322 client API context, must be atomic. 323 324 Applications may create client API resources from an EGLImageKHR using 325 client API extensions outside the scope of this document (such as 326 GL_OES_EGL_image, which creates OpenGL ES texture and renderbuffer 327 objects). If the EGLImageKHR used to create the client resource was 328 created with the EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, then 329 the pixel data values associated with the image will be preserved after 330 creating the client resource; otherwise, the pixel data values will be 331 undefined. If the EGLImageKHR was created with the 332 EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, and EGL is unable to 333 create the client resource without modifying the pixel values, then 334 creation will fail and the pixel data values will be preserved. 335 336 The command 337 338 EGLBoolean eglDestroyImageKHR( 339 EGLDisplay dpy, 340 EGLImageKHR image) 341 342 is used to destroy the specified EGLImageKHR object <image>. Once 343 destroyed, <image> may not be used to create any additional EGLImage 344 target resources within any client API contexts, although existing 345 EGLImage siblings may continue to be used. EGL_TRUE is returned 346 if DestroyImageKHR succeeds, EGL_FALSE indicates failure. 347 348 * If <dpy> is not the handle of a valid EGLDisplay object, the error 349 EGL_BAD_DISPLAY is generated. 350 351 * If <image> is not a valid EGLImageKHR object created with respect 352 to <dpy>, the error EGL_BAD_PARAMETER is generated." 353 354 Add a new error to the list at the bottom of Section 3.5.3 (Binding 355 Off-Screen Rendering Surfaces to Client Buffers): 356 357 "* If the buffers contained in <buffer> consist of any EGLImage 358 siblings, an EGL_BAD_ACCESS error is generated." 359 360Issues 361 362 1. What resource types should be supported by this extension? 363 364 RESOLVED: This specification is designed to support the 365 sharing of two-dimensional image resources between client APIs, 366 as these resources are a fundamental component of all modern 367 graphics APIs. 368 369 Other resources types (e.g., buffer objects) will not be directly 370 supported by this specification, due to a variety of reasons: 371 372 a. An absense of use cases for this functionality 373 b. Handling the semantics for some of these resources 374 (e.g., glMapBuffer) would significantly complicate 375 and delay this specification. 376 c. A desire to address the image-sharing use cases 377 as quickly as possible. 378 379 Should additional resource-sharing functionality be desired 380 in the future, the framework provided by this specification 381 should be extendable to handle more general resource 382 sharing. 383 384 2. Should this specification address client API-specific resources 385 (OpenGL texture maps, OpenVG VGImages), or should that 386 functionality be provided by layered extensions? 387 388 SUGGESTION: Use layered extensions, even for for sharing image 389 data with native rendering APIs (the EGL_KHR_image_pixmap 390 extension). 391 392 There are two major arguments for using layered extensions: 393 394 1. The two client APIs which are defined at the time of this 395 specification (OpenVG, OpenGL ES) may not always be 396 deployed on a device; many devices may choose to implement 397 just one of these two APIs. However, even single-API 398 devices may benefit from the ability to share image data 399 with native rendering APIs (provided in this specification) 400 or with the OpenMAX API. 401 402 2. OpenGL ES defines a number of optional resource types 403 (cubemaps, renderbuffers, volumetric textures) which this 404 framework should support; however, implementations may not. 405 By layering each of these resource types in individual 406 extensions, implementations which are limited to just the 407 core OpenGL ES 1.1 (or OpenGL ES 2.0) features will not 408 need to add EGLImage enumerant support for unsupported 409 resource types. 410 411 The original EGL_KHR_image extension included native pixmap 412 functionality. We have now split the abstract base functionality 413 (the egl{Create,Destroy}ImageKHR APIs) from the native pixmap 414 functionality, and redefined EGL_KHR_image as the combination of 415 EGL_KHR_image_base and EGL_KHR_image_pixmap. 416 417 3. Should attributes (width, height, format, etc.) for EGLImages 418 be queriable? 419 420 SUGGESTION: No. Given the wealth of attributes that we would 421 need to specify all possible EGLImages (and possible 422 memory layout optimizations performed by implementations), we 423 can dramatically simplify the API without loss of key 424 functionality by making EGLImages opaque and allowing 425 implementations to make the correct decisions internally. 426 427 4. Should this specification allow the creation of EGLImages from 428 client API resources which are themselves EGLImage targets? 429 430 RESOLVED: No. This can make memory garbage collection and 431 reference counting more difficult, with no practical benefit. 432 Instead, generate an error if an application attempts to 433 create an EGLImage from an EGLImage target resource. 434 435 5. Should this specification allow multiple EGLImages to be created 436 from the same EGLImage source resource? 437 438 RESOLVED: No. The resource <buffer> specified to 439 eglCreateImageKHR may include multiple sub-objects; examples are 440 mipmapped images and cubemaps in the OpenGL-ES API. However, the 441 EGLImage source is defined as the specific sub-object that is defined 442 by: <ctx>, <target>, <buffer>, and <attrib_list>. This sub-object must 443 not be an EGLImage sibling (either EGLImage source or EGLImage target) 444 when eglCreateImageKHR is called; however, other sub-objects in 445 <buffer> may be EGLImage siblings. This allows applications to share 446 individual cubemap faces, or individual mipmap levels of detail across 447 all of the supported APIs. 448 449 Note that the EGLImage source and any EGLImage target resources 450 will still be EGLImage siblings, even if the EGLImage object 451 is destroyed by a call to DestroyImageKHR. 452 453 6. If an EGLImage sibling is respecified (or deleted), what 454 should happen to the EGLImage and any other EGLImage 455 siblings? 456 457 RESOLVED: The principle of least surprise would dictate that 458 respecification and/or deletion of a resource in one client API 459 should not adversely affect operation in other client APIs 460 (such as introducing errors). 461 462 Applying this to EGLImages, respecification and/or deletion 463 of one EGLImage sibling should not respecify/delete other 464 EGLImage siblings. Each client API will be responsible for 465 defining appropriate semantics to meet this restriction; 466 however, example behaviors may include one or more of: 467 allocating additional memory for the respecified resource, 468 deleting the EGLImage sibling resource without deallocating 469 the associated memory ("orphaning") and/or copying the 470 existing EGLImage pixel data to an alternate memory location. 471 472 The memory associated with EGLImage objects should remain 473 allocated as long as any EGLImage sibling resources exist 474 in any client API context. 475 476 7. Should this specification address synchronization issues 477 when multiple client API contexts simultaneously access EGLImage 478 sibling resources? 479 480 RESOLVED: No. Including error-producing lock and synchronization 481 semantics would introduce additional (undesirable) validation 482 overhead in numerous common operations (e.g., glBindTexture, 483 glDrawArrays, etc.). Rather than burdening implementations (and 484 applications) with this overhead, a separate synchronization 485 mechanism should be exposed to applications. 486 487 8. Should eglCreatePbufferFromClientBuffer accept buffer parameters 488 which are EGLImage siblings? 489 490 RESOLVED: No. Allowing this behavior creates very complex 491 circular dependency possibilities (CreateImage / DeriveImage / 492 CreatePbufferFromClientBuffer / BindTexImage / 493 CreateImage / ...) with no practical benefit. Therefore, 494 attempting to create a Pbuffer from a client buffer which 495 is an EGLImage sibling should generate an error. 496 497 9. Should CreateImage accept client buffers which are bound to 498 Pbuffers (through eglBindTexImage)? 499 500 RESOLVED: No, for the same reasons listed in Issue 8. 501 502 10. Should implementations be allowed to modify the pixel data in the 503 EGLImage source buffers specified to eglCreateImageKHR? 504 505 SUGGESTION: By allowing previously-existing image data to become 506 undefined after calls to eglCreateImageKHR, implementations are able 507 to perform any necessary reallocations required for cross-API 508 buffer compatibility (and/or performance), without requiring 509 copy-aside functionality. Because applications are able to 510 respecify the pixel data through mechanisms such as vgSubImage 511 and glTexSubImage, no use-cases are restricted by this. 512 513 Therefore, the current suggestion is to allow implementations 514 to leave pixel data undefined after calls to eglCreateImageKHR 515 functions. The current spec revision has been written in 516 this way. 517 518 11. What is the correct mechanism for specifying the EGLImage source 519 resources used to create an EGLImage object? 520 521 RESOLVED: Three different mechanisms were discussed while 522 defining this extension: 523 524 A) Providing resource-specific creation functions, such as 525 eglCreateImage2DKHR, eglCreateImage3DKHR, etc. 526 527 B) Providing a single creation function which returns a 528 "NULL" EGLImage object, and requiring client APIs to 529 define additional functions which would allow client API 530 resources to be "bound" to the EGLImage object. 531 532 C) Provide a single resource creation function, and use 533 an attribute-value list with attributes specific to the 534 "target" image resource. 535 536 Initial specifications were written using Option (A); however, 537 it was believed that this structure would result in an increase 538 in the number of entry points over time as additional client APIs 539 and client API resource targets were added. Furthermore, reuse 540 of these functions was resulting in cases where parameters were 541 required to have modal behavior: a 2D image creation function 542 was required to have a mipmap level of detail parameter for 543 OpenGL ES texture maps, but this same parameter would need to be 544 0 for OpenVG. 545 546 Option (B) provided some nice characteristics: as client APIs 547 continue to evolve, any extensions needed to allow EGLImage 548 creation could be isolated in the individual client API, rather 549 than necessitating an EGL extension. However, the creation of 550 "NULL" images created additional semantic complexity and error 551 conditions (e.g., attempting to derive an EGLImage target from a 552 "NULL" image), and every client API would need to provide a 553 function for every unique resource type; instead of one common 554 API function for pixmap, OpenGL 2D textures, and OpenVG VGImages, 555 three would be required. 556 557 This specification is written using Option (C). There is a 558 single CreateImage function, with a <target> parameter defining 559 the EGLImage source type, and an attribute-value list allowing 560 for additional selection of resource sub-sections. This 561 maximizes entry-point reuse, and minimizes the number of 562 redundant parameters an application may be required to send. 563 This framework allows for layered extensions to be easily 564 written, so little churn is expected as client APIs evolve. 565 566 12. Should a context be explicitly provided to eglCreateImageKHR, 567 or should the context be deduced from the current thread's 568 bound API? 569 570 SUGGESTION: For clarity (both in usage and spec language), the 571 context containing the EGLImage source should be provided by the 572 application, rather than inferring the context from EGL state. 573 574 13. Why does this extension define a new EGL object type, rather 575 than using the existing EGLSurface objects? 576 577 RESOLVED: Although controversial, the creation of a new, 578 opaque image object type removes several fundamental problems 579 with the EGLSurface (and Pbuffer) API: 580 581 1) The tight compatibility requirements of EGLSurfaces 582 and EGLConfigs necessitated applications creating 583 (and calling MakeCurrent) for every unique pixel 584 format used during rendering. This has already caused 585 noticeable performance problems in OpenGL-ES (and 586 desktop OpenGL), and is the primary reason that 587 framebuffer objects were created. 588 589 2) Application use-cases are centered around sharing of 590 color image data, although unique "sundry" buffers 591 (such as depth, stencil and alpha mask) may be used 592 in each client API. 593 594 3) Extending the CreatePbuffer interface to support fully- 595 specifying all possible buffer attributes in all client 596 APIs will become unwieldy, particularly as new EGL 597 client APIs and pixel formats are introduced. 598 599 The EGLImage proposal addresses all three of these restrictions: 600 601 1) is addressed by placing the burden of framebuffer management 602 inside the client API, and allowing EGLImages to be accessed 603 inside client APIs using an appropriate resource type (such 604 as OpenGL-ES renderbuffers). This follows the example provided 605 by the GL_OES_framebuffer_object specification. 606 607 2) is addressed by defining EGLImages to be "trivial" two- 608 dimensional arrays of pixel data. Implementations may choose 609 to support creation of EGLImages from any type of pixel data, 610 and the association of multiple EGLImages and/or sundry 611 buffers into a single framebuffer is the responsibility of the 612 application and client API, using a mechanism such as 613 GL_OES_framebuffer_object. 614 615 3) is addressed by defining EGLImages as opaque and 616 non-queriable. Although this introduces potential portability 617 problems (addressed separately in issue 15), it avoids the 618 ever-expanding problem of defining buffer compatibility as the 619 cartesian product of all possible buffer attributes. 620 621 14. Since referencing EGLImages is the responsibility of the client 622 API, and may fail for implementation-dependent reasons, 623 doesn't this result in a potential portability problem? 624 625 UNRESOLVED: Yes, this portability problem (where referencing 626 succeeds on one platform but generates errors on a different 627 one) is very similar to the implementation-dependent 628 failure introduced in the EXT_framebuffer_object specification, 629 discussed (at length) in Issues (12), (37), (46), (48) and (61) 630 of that specification. Similar to that specification, this 631 specification should include some "minimum requirements" 632 language for EGLImage creation and referencing. 633 634 Since there are numerous references to an upcoming 635 "format restriction" API in the EXT_framebuffer_object 636 specification, it may be valuable to wait until that API is 637 defined before attempting to define a similar API for 638 EGLImages. 639 640 15. Should creation of an EGLImage from an EGLImage source 641 introduce the possibility for errors in the EGLImage source's 642 owning context? 643 644 RESOLVED: No; although image data may be undefined (issue 11), 645 the (successful or unsuccessful) creation of an EGLImage should 646 not introduce additional error conditions in the EGLImage 647 source's owning context. Text added to the end of section 648 2.5.1 describing this. 649 650 16. Is it reasonable to require that when a preserved EGLImage is 651 used by layered extensions to create client API siblings of that 652 image, pixel data values are preserved? 653 654 UNRESOLVED: There are at least two extensions that reference 655 EGLImages to create EGLImage targets, VG_KHR_EGL_image and 656 GL_OES_EGL_image. 657 658 Each of these extensions makes provision for failing the creation of 659 the EGLImage target due to "an implementation-dependent reason". 660 This could include that the pixel data has been marked as preserved, 661 and that the implementation is not able to create the EGLImage 662 target without causing the pixel data of the original EGLImage 663 source <buffer> to become undefined. 664 665 Issue 14 of EGL_KHR_image also discusses the consequences of failure 666 for implementation-dependent reasons. This implies that all 667 extensions for referencing an EGLImage need to make provision for 668 implementation-dependent failure. 669 670 PROPOSED: Yes, this is reasonable. We should add "EGL_KHR_image_base 671 affects the behavior of this extension" sections to the ES and VG 672 extensions. Implementations can continue to export EGL_KHR_image if 673 they are unable to support preserved image functionality. 674 675 17. Do EGLImage Target creation extensions such as VG_KHR_EGL_image and 676 GL_OES_EGL_image also need to be extended? 677 678 UNRESOLVED: The problem here is that both these extensions 679 explicitly state that pixel data becomes undefined when they 680 reference an EGLImage to create an EGLImage target. 681 682 One solution would be to allow this extension to do the defining on 683 behalf of these extensions. For example, the VG_KHR_EGL_image 684 extension on its own leaves the status of the pixel data undefined, 685 but when VG_KHR_EGL_image is combined with this extension, then the 686 status becomes defined (by this extension). 687 688 When combined with the reasons given in Issue 1, this means it is 689 possible to leave EGLImage Target creation extensions unchanged. 690 691 PROPOSED: Yes, augment these extensions as described in issue 16. 692 693 18. Is it reasonable for developers to want to preserve pixel data upon 694 creation of EGLImage and EGLImage targets? 695 696 RESOLVED: Yes. This is necessary for composition implementations 697 using EGLImages as an encapsulation mechanism for moving data 698 between producer application, composition API, and composition 699 implementation(s). 700 701 19. Should we really change the default value of EGL_IMAGE_PRESERVED_KHR 702 when EGL_KHR_image is supported? 703 704 RESOLVED: No. This is a subtle and hard to diagnose source of 705 errors, and the only way to write a portable app would still be 706 to explicitly specify the attribute value. By making the default 707 value FALSE no matter which of the two extension(s) are 708 supported, compatibility with EGL_KHR_image is preserved, and 709 apps must explicitly ask for preservation if they need it. 710 711 20. Why is EGL_NO_DISPLAY not supported as the <dpy> argument for 712 creating and destroying images, unlike the original version of the 713 EGL_KHR_image specification? 714 715 RESOLVED: There are no defined use cases for this at present, so 716 there is no way to legally pass in EGL_NO_DISPLAY. If in the future, 717 a layered extension allows creation of images not associated with 718 any display, this behavior can be reintroduced. 719 720 721Revision History 722 723#8 (Jon Leech, August 27, 2014) 724 - Remove leftover comment saying that inapplicable attributes are 725 ignored (Bug 12585). 726 727#7 (Jon Leech, June 12, 2013) 728 - Add a column to table bbb specifying which <target>s attributes are 729 valid for, and a generic error if an attribute doesn't match <target> 730 (Bug 10151). 731 732#6 (Jon Leech, December 1, 2010) 733 - Clarify wording of EGL_BAD_CONTEXT error. 734 735#5 (Jon Leech, December 10, 2008) 736 - Change definition of EGL_NO_IMAGE_KHR to 0 (appropriately cast) 737 instead of a reference to an extern implementation-defined 738 variable. 739 740#4 (Jon Leech, November 25, 2008) 741 - Simplify error conditions for eglDestroyImage. 742 743#3 (Jon Leech, November 12, 2008) 744 - Added glossary entry for Respecification, updated description of 745 behavior with preserved images per suggestions from Acorn, and added 746 issue 20 regarding removal of EGL_NO_DISPLAY as a valid <dpy>. 747 748#2 (Jon Leech, October 22, 2008) 749 - Change default value of EGL_IMAGE_PRESERVED_KHR to EGL_FALSE. 750 Update issue 19. 751 752#1 (Jon Leech, October 21, 2008) 753 - Split abstract functionality from EGL_KHR_image into this extension, 754 and merged preserved image functionality from 755 EGL_SYMBIAN_image_preserved. 756