1Name 2 3 KHR_lock_surface 4 5Name Strings 6 7 EGL_KHR_lock_surface 8 9Contributors 10 11 Gary King 12 Jon Leech 13 Marko Lukat 14 Tim Renouf 15 16Contacts 17 18 Jon Leech (jon 'at' alumni.caltech.edu) 19 20Notice 21 22 Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Status 26 27 This extension, as well as the layered EGL_KHR_lock_surface2, are 28 obsolete and have been replaced by EGL_KHR_lock_surface3. Khronos 29 recommends implementers who support this extension and lock_surface2 30 also implement lock_surface3, and begin transitioning developers to 31 using that extension. See issue 17 for the reason. 32 33 Complete. 34 Version 17 approved by the Khronos Board of Promoters on 35 February 11, 2008. 36 37Version 38 39 Version 19, October 15, 2013 40 41Number 42 43 EGL Extension #2 44 45Dependencies 46 47 Requires EGL 1.0 48 49 This extension is written against the wording of the EGL 1.3 50 Specification. 51 52Overview 53 54 This extension allows mapping color buffers of EGL surfaces into the 55 client address space. This is useful primarily for software 56 rendering on low-end devices which do not support EGL client 57 rendering APIs, although it may be implemented efficiently on more 58 capable devices as well. 59 60 There is a newer EGL_KHR_lock_surface2 extension which slightly 61 modifies and clarifies the semantics of this extension. Vendors 62 should refer to EGL_KHR_lock_surface2 before deciding to implement 63 only EGL_KHR_lock_surface. 64 65New Types 66 67 None 68 69New Procedures and Functions 70 71 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, 72 const EGLint *attrib_list); 73 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 74 EGLSurface surface); 75 76New Tokens 77 78 Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: 79 80 EGL_LOCK_SURFACE_BIT_KHR 0x0080 81 EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 82 83 Accepted as an attribute name in the <attrib_list> argument of 84 eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: 85 86 EGL_MATCH_FORMAT_KHR 0x3043 87 88 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute 89 of eglChooseConfig: 90 91 EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 92 EGL_FORMAT_RGB_565_KHR 0x30C1 93 EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 94 EGL_FORMAT_RGBA_8888_KHR 0x30C3 95 96 Accepted as attribute names in the <attrib_list> argument of 97 eglLockSurfaceKHR: 98 99 EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 100 EGL_LOCK_USAGE_HINT_KHR 0x30C5 101 102 Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute 103 of eglLockSurfaceKHR: 104 105 EGL_READ_SURFACE_BIT_KHR 0x0001 106 EGL_WRITE_SURFACE_BIT_KHR 0x0002 107 108 Accepted by the <attribute> parameter of eglQuerySurface: 109 110 EGL_BITMAP_POINTER_KHR 0x30C6 111 EGL_BITMAP_PITCH_KHR 0x30C7 112 EGL_BITMAP_ORIGIN_KHR 0x30C8 113 EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 114 EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA 115 EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB 116 EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC 117 EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD 118 119 Returns in the *<value> parameter of eglQuerySurface when 120 <attribute> is EGL_BITMAP_ORIGIN_KHR: 121 122 EGL_LOWER_LEFT_KHR 0x30CE 123 EGL_UPPER_LEFT_KHR 0x30CF 124 125Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation) 126 127 Add to the end of section 2.2.2: 128 129 Finally, some surfaces may be <locked>, which allows the 130 implementation to map buffers of that surface into client memory 131 for use by software renderers(fn). Locked surfaces cannot be 132 used for any other purpose. When a locked surface is <unlocked>, 133 any changes to the mapped buffer(s) are reflected in the actual 134 graphics or system memory containing the surface. 135 136 [fn: on implementations not supporting mapping graphics 137 memory, or which do not wish to take the stability and 138 security risks that entail, mapping may be done using 139 copy-out and copy-in behavior.] 140 141Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors) 142 143 Add to the description of the EGL_BAD_ACCESS error in section 3.1: 144 145 "... or, a surface is locked)." 146 147 Add to table 3.2 ("Types of surfaces supported by an EGLConfig") 148 149 EGL Token Name Description 150 -------------------- ------------------------------------ 151 EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces 152 EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal 153 (preferred) when locking / mapping / 154 unlocking is being done. 155 156 Change the first paragraph under "Other EGLConfig Attribute 157 Descriptions" on p. 16: 158 159 "EGL_SURFACE_TYPE is a mask indicating both the surface types 160 that can be created by the corresponding EGLConfig (the config 161 is said to <support> those surface types), and the optional 162 behaviors such surfaces may allow. The valid bit settings are 163 shown in Table 3.2." 164 165 Add a new paragraph following the second paragraph of the same 166 section: 167 168 "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE_KHR, then 169 a surface created from the EGLConfig may be locked, mapped into 170 client memory, and unlocked. Locking is described in section 171 3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in 172 EGL_SURFACE_TYPE_KHR, then the surface is considered optimal (by 173 the implementation) from a performance standpoint when buffer 174 mapping is being done. 175 176 Replace the second paragraph of section 3.3 "EGL Versioning": 177 178 "The EGL_CLIENT_APIS string describes which client rendering APIs 179 are supported. It is zero-terminated and contains a 180 space-separated list of API names, which may include 181 ``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if 182 OpenVG is supported. If no client APIs are supported, then the 183 empty string is returned." 184 185 Insert a new paragraph and table in section 3.4.1 "Querying 186 Configurations", following the description of 187 EGL_MATCH_NATIVE_PIXMAP on page 21: 188 189 "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must 190 be followed by one of the attribute values EGL_DONT_CARE, 191 EGL_NONE, or one of the format tokens in table 192 [locksurf.format]. 193 194 When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs 195 which cannot be locked or mapped will match. Such configs must 196 not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. 197 198 When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is 199 ignored. 200 201 When EGL_MATCH_FORMAT_KHR has one of the values in table 202 [locksurf.format], only EGLConfigs describing surfaces whose 203 color buffers have the specified format, when mapped with 204 eglLockSurface, will match this attribute. In this case, the 205 EGL_<component>_SIZE attributes of resulting configs must agree 206 with the specific component sizes specified by the format." 207 208 Specific Format Name Description 209 -------------------- ----------- 210 EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer 211 EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer 212 EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory 213 EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer 214 ------------------------------------------------------------------------------------------------------ 215 Table [locksurf.format]: Specific formats for mapped pixels. 216 217 Add to table 3.4 ("Default values and match critera for EGLConfig 218 attributes") on page 22: 219 220 Attribute Default Selection Sort Sort 221 Criteria Order Priority 222 -------------------- ------------- --------- ----- -------- 223 EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - 224 225 Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on 226 p. 23, describing attributes not used for sorting EGLConfigs. 227 228 229 Add a new section following the current section 3.5.5: 230 231 "3.5.6 Locking and Mapping Rendering Surfaces 232 233 A rendering surface may be <locked> by calling 234 235 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, 236 EGLSurface surface, 237 const EGLint *attrib_list); 238 239 While a surface is locked, only two operations can be performed 240 on it. First, the color buffer of the surface may be <mapped>, 241 giving a pointer into client memory corresponding to the memory 242 of the mapped buffer, and attributes describing mapped buffers 243 may be queried. Second, the surface may be unlocked. Any 244 attempts to use a locked surface in other EGL APIs will fail and 245 generate an EGL_BAD_ACCESS error. 246 247 <attrib_list> specifies additional parameters affecting the locking 248 operation. The list has the same structure as described for 249 eglChooseConfig. Attributes that may be defined are shown in table 250 [locksurf.attr], together with their default values if not specified 251 in <attrib_list>, and possible values which may be specified for 252 them in <attrib_list>. 253 254 Attribute Name Type Default Value Possible Values 255 ----------------------- ------- ------------- ------------------------- 256 EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE 257 EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of 258 EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR 259 and EGL_WRITE_SURFACE_BIT_KHR 260 -------------------------------------------------------------- 261 Table [locksurf.attr]: eglLockSurfaceKHR attribute names, 262 default values, and possible values. 263 264 On failure, the surface is unaffected and eglLockSurfaceKHR 265 returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any 266 of these condition, are true: 267 268 * <surface> was created with an EGLConfig whose 269 EGL_SURFACE_TYPE attribute does not contain 270 EGL_LOCK_SURFACE_BIT_KHR. 271 * <surface> is already locked. 272 * Any client API is current to <surface>. 273 274 An EGL_BAD_ATTRIBUTE error is generated if an attribute or 275 attribute value not described in table [locksurf.attr] is 276 specified. 277 278 Mapping Buffers of a Locked Surface 279 ----------------------------------- 280 281 The color buffer of a locked surface can be <mapped> by calling 282 eglQuerySurface (see section 3.5.7) with <attribute> 283 EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a 284 buffer in client memory corresponding to the color buffer of 285 <surface>. In the case of a back-buffered surface, color buffer 286 refers to the back buffer 287 288 [fn: "mapped" only means that the pointer returned is 289 intended to *correspond* to graphics memory. Implementation 290 are not required to return an actual pointer into graphics 291 memory, and often will not.] 292 293 The contents of the mapped buffer are initially undefined(fn) 294 unless the EGL_MAP_PRESERVE_PIXELS_KHR attribute of 295 eglLockSurfaceKHR is set to EGL_TRUE, in which case the contents 296 of the buffer are taken from the contents of <surface>'s color 297 buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is 298 EGL_FALSE. 299 300 [fn: In order to avoid pipeline stalls and readback delays on 301 accelerated implementations, we do not mandate that the 302 current contents of a color buffer appear when it's mapped 303 to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR 304 flag is set. Applications using mapped buffers which are not 305 preserved must write to every pixel of the buffer before 306 unlocking the surface. This constraint is considered 307 acceptable for the intended usage scenario (full-frame 308 software renderers).] 309 310 The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a 311 bitmask describing the intended use of the mapped buffer. If the 312 mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from 313 the mapped buffer. If the mask contains 314 EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped 315 buffer. Implementations must support both reading and writing to 316 a mapped buffer regardless of the value of 317 EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the 318 hint is consistent with the actual usage of the buffer. The 319 default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads 320 and writes to the mapped buffer will be done. 321 322 Other attributes of the mapped buffer describe the format of 323 pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), 324 origin, pixel size, and the bit width and location of each color 325 component within a pixel. These attributes may be queried using 326 eglQuerySurface, and are described in more detail in section 327 3.5.7. 328 329 The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes 330 of a locked surface may change following successive calls to 331 eglLockSurfaceKHR(fn), so they must be queried each time a 332 buffer is mapped. Other attributes of a mapped buffer are 333 invariant and need be queried only once following surface 334 creation. 335 336 [fn: The pointer and pitch of a mapped buffer may change due 337 to display mode changes, for example.] 338 339 Mapping will not suceed if client memory to map the surface into 340 cannot be allocated. In this case, querying eglQuerySurface with 341 <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL 342 error. 343 344 Unlocking Surfaces 345 ------------------ 346 347 A rendering surface may be <unlocked> by calling 348 349 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 350 EGLSurface surface); 351 352 Any mapped buffers of <surface> become unmapped following 353 eglUnlockSurfaceKHR. Any changes made to mapped buffers of 354 <surface> which it was locked are reflected in the surface after 355 unlocking(fn). 356 357 [fn: This language enables implementations to either map 358 video memory, or copy from a separate buffer in client 359 memory.] 360 361 If <surface> was created with an EGLConfig whose 362 EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, 363 then the surface is considered optimal (by the implementation) 364 from a performance standpoint when buffer mapping is being 365 done(fn). 366 367 [fn: This often means that the format of all mapped buffers 368 corresponds directly to the format of those buffers in 369 <surface>, so no format conversions are required during 370 unmapping. This results in a high-performance software 371 rendering path. But "optimal format" is really just a hint 372 from EGL that this config is preferred, whatever the actual 373 reason.] 374 375 On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An 376 EGL_BAD_ACCESS error is generated if any of these conditions are 377 true: 378 379 * <surface> is already unlocked. 380 * A display mode change occurred while the surface was locked, 381 and the implementation was unable to reflect mapped buffer 382 state(fn). In this case, <surface> will still be unlocked. 383 However, the contents of the previously mapped buffers of 384 <surface> become undefined, rather than reflecting changes 385 made in the mapped buffers in client memory. 386 387 [fn: Usually this may only occur with window surfaces which 388 have been mapped. EGL does not have an event mechanism to 389 indicate display mode changes. If such a mechanism exists 390 (using native platform events or the OpenKODE event system), 391 applications should respond to mode changes by regenerating 392 all visible window content, including re-doing any software 393 rendering overlapping the mode change.]" 394 395 Add to table 3.5 ("Queryable surface attributes and types") 396 397 Attribute Type Description 398 --------- ---- ----------- 399 EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB). 400 EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of 401 adjacent rows in an MCB. 402 EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction 403 EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer 404 component within a pixel in an MCB. 405 406 Add to the description of eglQuerySurface properties in section 407 3.5.6 (renumbered to 3.5.7) on page 33: 408 409 "Properties of a bitmap surface which may be queried include: 410 * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a 411 locked surface and returns the address in client memory of 412 the mapped buffer. 413 * EGL_BITMAP_PITCH_KHR, which returns the number of bytes 414 between successive rows of a mapped buffer. 415 * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a 416 mapped color buffer is displayed on the screen. Possible 417 values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, 418 indicating that the first pixel of the mapped buffer 419 corresponds to the lower left or upper left of a visible 420 window, respectively. 421 * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit 422 location of the least significant bit of each color 423 component of a pixel within a mapped buffer. <x> is one of 424 RED, GREEN, BLUE, ALPHA, or LUMINANCE. 425 426 The offset for a color component should be treated as the 427 number of bits to left shift the component value to place it 428 within a 16- (for RGB565 formats) or 32-bit (for RGBA8888 429 formats) integer containing the pixel(fn). If a color 430 component does not exist in the mapped buffer, then the bit 431 offset of that component is zero. 432 433 In addition to these attributes, the number of bits for each 434 color component of a pixel within a mapped buffer is obtained by 435 querying the EGL_<x>_SIZE attribute of the EGLConfig used to 436 create the surface, where <x> is <x> is one of RED, GREEN, BLUE, 437 ALPHA, or LUMINANCE. The size of a pixel in the mapped buffer, 438 in bytes, can be determined by querying the EGL_BUFFER_SIZE 439 attribute of the EGLConfig, rounding up to the nearest multiple 440 of 8, and converting from bits to bytes. 441 442 Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only 443 allowed when <surface> is mapped (see section 3.5.6). Querying 444 either of these attributes for the first time after calling 445 eglLockSurfaceKHR causes the color buffer of the locked surface 446 to be mapped. Querying them again before unlocking the surface 447 will return the same values as the first time. However, after 448 calling eglUnlockSurfaceKHR, these properties become undefined. 449 After a second call to eglLockSurfaceKHR, these properties may 450 again be queried, but their values may have changed. 451 452 Other properties of the mapped color buffer of a surface are 453 invariant, and need be queried only once following surface 454 creation. If <surface> was created with an EGLConfig whose 455 EGL_SURFACE_TYPE attribute does not contain 456 EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR and 457 EGL_BITMAP_PIXEL_<x>_OFFSET_KHR return undefined values." 458 459 Add to the description of eglQuerySurface errors in the last 460 paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34: 461 462 "... If <attribute> is either EGL_BITMAP_POINTER_KHR or 463 EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using 464 eglLockSurfaceKHR, or <surface> is locked but mapping fails, 465 then an EGL_BAD_ACCESS error is generated." 466 467Issues 468 469 1) What is the rationale for this extension? 470 471 Software renderers on low-end implementations need an efficient way 472 to draw pixel data to the screen. High-end implementations must 473 support the same interface for compatibility, while not compromising 474 the accelerability of OpenGL ES and OpenVG client APIs using 475 dedicated graphics hardware and memory. 476 477 Using lock/unlock semantics enables low-end implementations to 478 expose pointers directly into display memory (as extremely dangerous 479 as that may be), while high-end implementations may choose to create 480 backing store in client memory when mapping a buffer, and copy it to 481 graphics memory when the surface is unlocked. Making the initial 482 contents of a mapped buffer undefined means that no readbacks from 483 graphics memory are required, avoiding pipeline stalls. 484 485 This extension is not intended to support mixed-mode (client API and 486 software) rendering. Since mapped buffer contents are undefined, 487 unless the buffer is explicitly preserved (which may be unacceptably 488 expensive on many implementations), applications doing software 489 rendering must touch every pixel of mapped buffers at least once 490 before unlocking the surface. 491 492 2) Do we need to know if locked surfaces are "fast" or "native"? 493 494 RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR 495 of EGL_SURFACE_TYPE. However, note that there is no way to guarantee 496 what "fast" or "no format conversions" really means; this is little 497 more than an implementation hint. 498 499 3) Should we be able to map buffers other than the color buffer? 500 501 RESOLVED: Not initially. However, the <attrib_list> parameter of 502 eglLockSurfaceKHR supports this in the future. There is no <buffer> 503 attribute to eglQuerySurface, so such a layered extension would have 504 to either create a new naming convention (such as 505 EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an 506 extended query eglQuerySurfaceBuffer() which takes a <buffer> 507 parameter. It would also be tricky to support interleaved depth / 508 stencil formats. But the attribute list offers some future-proofing 509 at low cost. 510 511 4) What properties of mapped buffers can be queried? 512 513 RESOLVED: A pointer to the buffer and its pitch, both of which may 514 change in successive lock/unlock cycles. These may be queried only 515 while the underlying surface is locked, and are undefined after 516 unlocking. The first query following locking is the point at which 517 actual buffer mapping must occur. 518 519 RESOLVED: Additionally, the pixel size, origin, and color component 520 bitfield size and offset for each component, which are invariant 521 and may be queried at any time. 522 523 5) How are mode changes indicated? What happens to the mapped 524 buffer during a mode change? 525 526 RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode 527 change occurred while the surface was locked (although the surface 528 still ends up in the unlocked state - this is necessary since 529 there's no way to clear the error!). If a mode change occurs while a 530 buffer is mapped, the implementation must still allow the 531 application to access mapped buffer memory, even though the contents 532 of the mapped buffer may not be reflected in the changed window 533 after unmapping. 534 535 Note: There's no convenient way to indicate mode changes while 536 a surface is unlocked, despite that being useful to tell apps they 537 have to redraw. The problem is that we don't have an event system, 538 and the power management functionality is overkill since the only 539 resources which are likely to be damaged by a mode change are 540 visible window contents. Fortunately, this problem is beyond the 541 scope of this extension. 542 543 6) Does locking a surface imply mapping its buffers? 544 545 RESOLVED: No. Locking simply places the surface in that state and 546 prevents it from being made current / swapped / etc. Buffers are 547 mapped only when their pointers or pitch are queried using 548 eglQuerySurface. 549 550 An interesting side effect of this resolution is that calling 551 eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES 552 NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped. 553 Likewise locking a surface, querying a buffer pointer or pitch, and 554 then unlocking it without changing the mapped buffer contents causes 555 the surface contents of the mapper buffer(s) to become undefined. 556 557 At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR 558 should immediately map the color buffer and return a pointer to it, 559 on the basis that this would make it harder for applications to 560 mistakenly use an old buffer pointer from a previous mapping cycle. 561 At the same time, people working on more powerful GPUs wanted the 562 lock operation to be lightweight. These are not consistent goals and 563 we have thus far chosen to separate the lightweight locking, and 564 more expensive mapping operations. 565 566 7) Can buffer contents be preserved in mapping? 567 568 RESOLVED: Yes. The default behavior is to discard / leave undefined 569 the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag 570 may be specified to eglLockSurfaceKHR. 571 572 8) Should usage hints be provided during mapping? 573 574 RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR 575 bitmask attribute to eglLockSurfaceKHR. Implementations are required 576 to behave correctly no matter the value of the flag vs. the 577 operations actually performed, so the hint may be ignored. 578 579 9) Should we be able to lock subrectangles of a surface? 580 581 RESOLVED: No. However, the attribute list parameter of 582 eglLockSurfaceKHR allows a layered extension to implement this 583 behavior by specifying an origin and size to map within the buffer. 584 58510) Should the BITMAP_PIXEL_<component>_OFFSET attributes belong to the 586 surface, or the config? 587 588 RESOLVED: Part of the surface. Configs supporting a specific format 589 are matched with config attribute EGL_MATCH_FORMAT_KHR, which 590 supports specific bit-exact formats such as 591 EGL_FORMAT_565_EXACT_KHR. 592 59311) Can the pixel size in a mapped buffer be derived from the 594 EGL_BUFFER_SIZE attribute of the config used to create it? 595 596 RESOLVED: Yes. In principle, hardware using padding bytes in its 597 framebuffer storage could be a problem, and a separate 598 BITMAP_PIXEL_SIZE surface attribute would be needed. However, we 599 don't think implementations are likely to waste graphics memory and 600 bandwidth in this fashion. 601 60212) How are color component locations within a pixel described? 603 604 RESOLVED: Each R, G, B, and A component has a queryable bit offset 605 within an integer. The size of the integer depends on the total size 606 of the pixel; for the 565 formats, the pixel is a 16-bit integer. 607 For the 8888 formats, the pixel is a 32-bit integer. 608 609 We cannot describe component locations with byte locations, since 610 the 565 formats have components straddling byte boundaries. However, 611 this means that offsets for the RGBA8888_EXACT format are different 612 between little- and big-endian CPUs, since the desired format is B, 613 G, R, A components laid out as bytes in increasing memory order. 614 61513) Can mapped buffer contents be affected by other EGL operations? 616 617 RESOLVED: No. A locked surface only allows two operations: 618 unlocking, and mapping. No other EGL operations can take place while 619 the surface is locked (if this were not the case, then 620 eglSwapBuffers might destroy the contents of a mapped buffer). 621 622 It is possible that operations outside the scope of EGL could affect 623 a mapped color buffer. For example, if a surface's color buffer were 624 made up of an EGLImage, one of the EGL client APIs could draw to 625 that image while it was mapped. Responsibility for avoiding this 626 situation is in the hands of the client. 627 62814) Can EGL_MATCH_FORMAT_KHR be queried for a config? 629 630 RESOLVED: Yes. Unlockable configs return EGL_NONE for this 631 attribute. 632 63315) Is a goal of this extension to support "mixed-mode" rendering (both 634 software and EGL client API rendering to the same surface)? 635 636 RESOLVED: No. An implementation *can* choose to export configs 637 supporting creation of lockable surfaces which also support 638 rendering by OpenGL ES, OpenVG, or other client APIs (when the 639 surface is not locked). But there is nothing in the extension 640 requiring this, and the motivation for the extension is simply to 641 support software rendering. 642 64316) Can mapping a locked surface fail? 644 645 RESOLVED: Yes, if memory can't be allocated in the client. This is 646 indicated by queries of EGL_BITMAP_POINTER_KHR and 647 EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error. 648 64917) Why has this extension been obsoleted and replaced by 650 EGL_KHR_lock_surface3? 651 652 RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint 653 is defined to be the same size as the native platform "int" type. Handle 654 and pointer attribute values *cannot* be represented in attribute lists 655 on platforms where sizeof(handle/pointer) > sizeof(int). Existing 656 extensions which assume this functionality are being replaced with new 657 extensions specifying new entry points to work around this issue. See 658 the latest EGL 1.4 Specification for more details. 659 660Revision History 661 662 Version 19, 2013/10/15 - Add issue 17 explaining that the bitmap pointer 663 cannot be safely queried using this extension on 64-bit platforms, 664 and suggest EGL_KHR_lock_surface3 instead. Change formal parameter 665 names from 'display' to 'dpy' to match other EGL APIs. 666 Version 18, 2010/03/23 - Added introductory remark referring to the 667 EGL_KHR_lock_surface2 extension. Clarified that it is the back 668 buffer of a back-buffered surface that is mapped. 669 Version 17, 2008/10/08 - Updated status (approved as part of 670 OpenKODE 1.0). 671 Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail, 672 and a corresponding new error condition for eglQuerySurface. 673 Clean up the issues list. 674 Version 15, 2008/01/09 - Add issue 15 noting that supporting 675 mixed-mode rendering is not a goal or requirement of the 676 extension. 677 Version 14, 2007/11/07 - change ARGB_8888_EXACT back to 678 RGBA_8888_EXACT, since the offsets are now dependent on the 679 endianness of the CPU. Add issue 12 describing this, and clarify 680 that offsets are within a 16- or 32-bit integer depending on the 681 format. Added issue 13 clarifying that locked buffer contents 682 are not affected by eglSwapBuffers, because eglSwapBuffers 683 cannot be issued on a mapped surface. Allow querying 684 EGL_MATCH_FORMAT_KHR for a config, and added related issue 14. 685 Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT 686 to match hardware layout. 687 Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is 688 EGL_DONT_CARE, it does not affect component size of selected 689 configs. 690 Version 11, 2007/04/05 - add missing KHR suffix to some tokens. 691 Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0 692 Provisional disclaimer. 693 Version 9, 2007/03/26 - add format tokens to "New Tokens" 694 section. Correct description of RGBA format tokens. 695 Version 8, 2007/03/26 - add issue 11 noting theoretical possibility 696 of EGL_BUFFER_SIZE not directly corresponding to the mapped 697 pixel size. Add EGL_MATCH_FORMAT_KHR attribute to 698 eglChooseConfig, and 565 / 8888 formats for it. 699 Version 7, 2007/03/25 - note in issue 5 that access to a mapped 700 buffer must continue to work even after a mode change. Add KHR 701 suffix to new functions and tokens. Remove BITMAP_PIXEL_<x>_BITS 702 and BITMAP_PIXEL_SIZE tokens, which duplicate information in the 703 EGLConfig. Add issue 10 asking whether bitmap pixel offset 704 attributes belong to the config, or to the surface. 705 Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in 706 implementations supporting only this extension. 707 Version 5, 2007/02/05 - update contributor list. Changed bit offset 708 queries to return LSB offset, rather than MSB offset. 709 Version 4, 2007/02/02 - correct extension name. Change 710 name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR. 711 Replace buffer_mask parameter of eglLockSurfaceKHR with an 712 attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and 713 EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues 714 7, 8, and 9 describing these attributes and how to support 715 locking subrects in a layered extension, by extending the 716 attribute list. 717 Version 3, 2007/02/01 - the implementation once again controls the 718 mapped buffer memory. There is no longer a separate bitmap 719 surface type; any type surface may potentially be mapped, using 720 lock/unlock semantics. 721 Version 2, 2006/12/22 - simplify by only supporting drawing from 722 client memory to EGL surface color buffers. Specify use of 723 OpenGL DrawPixels terminology. Change name of the extension to 724 EGL_KHR_draw_pixels, since there is no longer any "bitmap 725 surface" involved. 726 Version 1, 2006/12/14 - write up as formal spec language for 727 external review. 728