1Name 2 3 KHR_lock_surface2 4 5Name Strings 6 7 EGL_KHR_lock_surface2 8 9Contributors 10 11 Mark Callow 12 Gary King 13 Jon Leech 14 Marko Lukat 15 Alon Or-bach 16 Tim Renouf 17 18Contacts 19 20 Jon Leech (jon 'at' alumni.caltech.edu) 21 22Notice 23 24 Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at 25 http://www.khronos.org/registry/speccopyright.html 26 27Status 28 29 This extension is obsolete and has been replaced by 30 EGL_KHR_lock_surface3. Khronos recommends implementers who support this 31 extension also implement lock_surface3, and begin transitioning 32 developers to using that extension. See issue 21 for the reason. 33 34 Complete. Version 2 approved by the Khronos Board of Promoters on 35 May 28, 2010. 36 Implemented by Antix Labs. 37 38Version 39 40 Version 3, December 4, 2013 41 42Number 43 44 EGL Extension #16 45 46Dependencies 47 48 Requires EGL 1.0 and EGL_KHR_lock_surface version 18. 49 50 This extension is written against the wording of the EGL 1.3 51 and EGL 1.4 Specifications. Unless otherwise specified, each change 52 applies to both specifications. Unless otherwise specified, a page 53 number refers to the EGL 1.3 specification. 54 55 This extension is written against the wording of EGL_KHR_lock_surface 56 version 18. 57 58Overview 59 60 This extension slightly modifies and clarifies some semantic aspects 61 of the EGL_KHR_lock_surface extension, in a way that is backwards 62 compatible for applications. 63 64 The extension is presented here as the full text of the 65 EGL_KHR_lock_surface extension (minus the Status, Version, Number and 66 Dependencies sections at the start) as modified by the changes made by 67 this EGL_KHR_lock_surface2 extension. A diff utility can be used between 68 EGL_KHR_lock_surface version 18 and this EGL_KHR_lock_surface2 extension 69 to show the exact changes. 70 71 An application which needs to tell whether the implementation supports 72 EGL_KHR_lock_surface2, or just the original EGL_KHR_lock_surface, can 73 use eglQueryString with EGL_EXTENSIONS to query the list of 74 implemented extensions. 75 76 The changes over EGL_KHR_lock_surface can be summarized as follows: 77 78 * EGL_KHR_lock_surface had the EGL_MAP_PRESERVE_PIXELS_KHR attribute on 79 eglLockSurfaceKHR, but failed to point out how the surface attribute 80 EGL_SWAP_BEHAVIOR would interact with lock surface rendering. 81 EGL_KHR_lock_surface2 specifies that the locked buffer contains the 82 back buffer pixels if EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED 83 _or_ if EGL_MAP_PRESERVE_PIXELS_KHR is EGL_TRUE, and provides a way to 84 set EGL_SWAP_BEHAVIOR on creation of a lockable window surface, 85 even if EGL_SWAP_BEHAVIOR is not otherwise modifiable. 86 EGL_SWAP_BEHAVIOR now defaults to EGL_BUFFER_PRESERVED for a 87 lockable surface. 88 89 * EGL_KHR_lock_surface failed to specify its interaction with the 90 EGL requirement that a context be current at eglSwapBuffers; no 91 context is used for lock surface rendering. EGL_KHR_lock_surface2 92 relaxes that requirement for a lockable window surface, in a way 93 that is anticipated to apply to all window surfaces in a future 94 version of EGL. 95 96 * Wording in EGL_KHR_lock_surface could be read to imply that almost 97 all surface attributes are invariant for a lockable surface. 98 EGL_KHR_lock_surface2 clarifies the wording. 99 100 * EGL_KHR_lock_surface2 clarifies what is returned when 101 the attribute EGL_MATCH_FORMAT_KHR is queried, especially when 102 one of the "inexact" formats was used to choose the config. 103 104 * EGL_KHR_lock_surface did not specify when a surface could change size. 105 EGL_KHR_lock_surface2 specifies that a surface cannot change size 106 when it is locked. 107 108 * EGL_KHR_lock_surface2 adds the config attribute 109 EGL_BITMAP_PIXEL_SIZE_KHR, to allow an application to dynamically 110 detect pixel layout for a format with a "hole", such as RGBU8888 111 (where "U" means "unused"). 112 113New Tokens 114 115 Accepted by the <attribute> parameter of eglQuerySurface: 116 117 EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 118 119Full text of EGL_KHR_lock_surface plus EGL_KHR_lock_surface2: 120 121Overview 122 123 This extension allows mapping color buffers of EGL surfaces into the 124 client address space. This is useful primarily for software 125 rendering on low-end devices which do not support EGL client 126 rendering APIs, although it may be implemented efficiently on more 127 capable devices as well. 128 129New Types 130 131 None 132 133New Procedures and Functions 134 135 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, 136 const EGLint *attrib_list); 137 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 138 EGLSurface surface); 139 140New Tokens 141 142 Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: 143 144 EGL_LOCK_SURFACE_BIT_KHR 0x0080 145 EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 146 147 Accepted as an attribute name in the <attrib_list> argument of 148 eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: 149 150 EGL_MATCH_FORMAT_KHR 0x3043 151 152 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute 153 of eglChooseConfig, and defined as possible values of that attribute 154 when querying it: 155 156 EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 157 EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 158 159 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute 160 of eglChooseConfig: 161 162 EGL_FORMAT_RGB_565_KHR 0x30C1 163 EGL_FORMAT_RGBA_8888_KHR 0x30C3 164 165 Accepted as attribute names in the <attrib_list> argument of 166 eglLockSurfaceKHR: 167 168 EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 169 EGL_LOCK_USAGE_HINT_KHR 0x30C5 170 171 Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute 172 of eglLockSurfaceKHR: 173 174 EGL_READ_SURFACE_BIT_KHR 0x0001 175 EGL_WRITE_SURFACE_BIT_KHR 0x0002 176 177 Accepted by the <attribute> parameter of eglQuerySurface: 178 179 EGL_BITMAP_POINTER_KHR 0x30C6 180 EGL_BITMAP_PITCH_KHR 0x30C7 181 EGL_BITMAP_ORIGIN_KHR 0x30C8 182 EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 183 EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA 184 EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB 185 EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC 186 EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD 187 EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 188 189 Returns in the *<value> parameter of eglQuerySurface when 190 <attribute> is EGL_BITMAP_ORIGIN_KHR: 191 192 EGL_LOWER_LEFT_KHR 0x30CE 193 EGL_UPPER_LEFT_KHR 0x30CF 194 195Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation) 196 197 Add to the end of section 2.2.2: 198 199 Finally, some surfaces may be <locked>, which allows the 200 implementation to map buffers of that surface into client memory 201 for use by software renderers(fn). Locked surfaces cannot be 202 used for any other purpose. When a locked surface is <unlocked>, 203 any changes to the mapped buffer(s) are reflected in the actual 204 graphics or system memory containing the surface. 205 206 [fn: on implementations not supporting mapping graphics 207 memory, or which do not wish to take the stability and 208 security risks that entail, mapping may be done using 209 copy-out and copy-in behavior.] 210 211Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors) 212 213 Add to the description of the EGL_BAD_ACCESS error in section 3.1: 214 215 "... or, a surface is locked)." 216 217 Add to table 3.2 ("Types of surfaces supported by an EGLConfig") 218 219 EGL Token Name Description 220 -------------------- ------------------------------------ 221 EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces 222 EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal 223 (preferred) when locking / mapping / 224 unlocking is being done. 225 226 Change the first paragraph under "Other EGLConfig Attribute 227 Descriptions" on p. 16: 228 229 "EGL_SURFACE_TYPE is a mask indicating both the surface types 230 that can be created by the corresponding EGLConfig (the config 231 is said to <support> those surface types), and the optional 232 behaviors such surfaces may allow. The valid bit settings are 233 shown in Table 3.2." 234 235 Add a new paragraph following the second paragraph of the same 236 section: 237 238 "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE, then 239 a surface created from the EGLConfig may be locked, mapped into 240 client memory, and unlocked. Locking is described in section 241 3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in 242 EGL_SURFACE_TYPE, then the surface is considered optimal (by 243 the implementation) from a performance standpoint when buffer 244 mapping is being done." 245 246 Replace the second paragraph of section 3.3 "EGL Versioning": 247 248 "The EGL_CLIENT_APIS string describes which client rendering APIs 249 are supported. It is zero-terminated and contains a 250 space-separated list of API names, which may include 251 ``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if 252 OpenVG is supported. If no client APIs are supported, then the 253 empty string is returned." 254 255 Insert a new paragraph and table in section 3.4.1 "Querying 256 Configurations", following the description of 257 EGL_MATCH_NATIVE_PIXMAP on page 21: 258 259 "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must 260 be followed by one of the attribute values EGL_DONT_CARE, 261 EGL_NONE, or one of the format tokens in table 262 [locksurf.format]. 263 264 When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs 265 which cannot be locked or mapped will match. Such configs must 266 not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. 267 268 When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is 269 ignored. 270 271 When EGL_MATCH_FORMAT_KHR has one of the values in table 272 [locksurf.format], only EGLConfigs describing surfaces whose 273 color buffers have the specified format, when mapped with 274 eglLockSurface, will match this attribute. In this case, the 275 EGL_<component>_SIZE attributes of resulting configs must agree 276 with the specific component sizes specified by the format." 277 278 Specific Format Name Description 279 -------------------- ----------- 280 EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer 281 EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer 282 EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory 283 EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer 284 ------------------------------------------------------------------------------------------------------ 285 Table [locksurf.format]: Specific formats for mapped pixels. 286 287 Add to table 3.4 ("Default values and match critera for EGLConfig 288 attributes") on page 22: 289 290 Attribute Default Selection Sort Sort 291 Criteria Order Priority 292 -------------------- ------------- --------- ----- -------- 293 EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - 294 295 Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on 296 p. 23, describing attributes not used for sorting EGLConfigs. 297 298 Add a new paragraph to the end of section 3.4.3 "Querying Configuration 299 Attributes": 300 301 "Querying the EGL_MATCH_FORMAT_KHR attribute results in EGL_NONE 302 for an EGLConfig that is not lockable, one of the "exact" formats 303 (EGL_FORMAT_RGB_565_EXACT_KHR, EGL_FORMAT_RGBA_8888_EXACT_KHR) 304 if the color buffer matches that format when mapped with 305 eglLockSurface, or for any other format a value that is not 306 EGL_NONE or EGL_DONT_CARE but is otherwise undefined. In particular, 307 the color buffer format matching one of the "inexact" formats 308 does not guarantee that that EGL_FORMAT_* value is returned." 309 310 In section 3.5.1 "Creating On-Screen Rendering Surfaces", add the 311 following to the paragraph that lists the attributes that can be set 312 in attrib_list: 313 314 "... and EGL_SWAP_BEHAVIOR." 315 316 and add a new penultimate paragraph: 317 318 "EGL_SWAP_BEHAVIOR specifies the initial value of the 319 EGL_SWAP_BEHAVIOR surface attribute (section 3.5.6), and is thus 320 either EGL_BUFFER_PRESERVED or EGL_BUFFER_DESTROYED. This setting 321 of EGL_SWAP_BEHAVIOR at surface creation time is supported only 322 for a lockable surface, i.e. where the EGLConfig has 323 EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE." 324 325 In EGL 1.4, also add the following text to that same paragraph: 326 327 "For such a lockable surface, whether it is possible to change 328 the EGL_SWAP_BEHAVIOR attribute after surface creation is 329 determined by EGL_SWAP_BEHAVIOR_PRESERVED_BIT in the 330 EGL_SURFACE_TYPE EGLConfig attribute." 331 332 Add a new section following the current section 3.5.5: 333 334 "3.5.6 Locking and Mapping Rendering Surfaces 335 336 A rendering surface may be <locked> by calling 337 338 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, 339 EGLSurface surface, 340 const EGLint *attrib_list); 341 342 While a surface is locked, only two operations can be performed 343 on it. First, a surface attribute may be queried using 344 eglQuerySurface. This includes the case of querying 345 EGL_BITMAP_POINTER_KHR, which causes the surface to be 346 <mapped> (if not already mapped) and gives 347 a pointer into client memory corresponding to the memory 348 of the mapped buffer. Second, the surface may be unlocked. Any 349 attempts to use a locked surface in other EGL APIs will fail and 350 generate an EGL_BAD_ACCESS error. 351 352 While a surface is locked, its dimensions (the values of the EGL_WIDTH 353 and EGL_HEIGHT surface attributes) do not change. They may change 354 at any other time, therefore an application must query these 355 attributes <after> the call to eglLockSurfaceKHR to ensure that it has 356 the correct size of the mapped buffer. 357 358 <attrib_list> specifies additional parameters affecting the locking 359 operation. The list has the same structure as described for 360 eglChooseConfig. Attributes that may be defined are shown in table 361 [locksurf.attr], together with their default values if not specified 362 in <attrib_list>, and possible values which may be specified for 363 them in <attrib_list>. 364 365 Attribute Name Type Default Value Possible Values 366 ----------------------- ------- ------------- ------------------------- 367 EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE 368 EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of 369 EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR 370 and EGL_WRITE_SURFACE_BIT_KHR 371 -------------------------------------------------------------- 372 Table [locksurf.attr]: eglLockSurfaceKHR attribute names, 373 default values, and possible values. 374 375 On failure, the surface is unaffected and eglLockSurfaceKHR 376 returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any 377 of these condition, are true: 378 379 * <surface> was created with an EGLConfig whose 380 EGL_SURFACE_TYPE attribute does not contain 381 EGL_LOCK_SURFACE_BIT_KHR. 382 * <surface> is already locked. 383 * Any client API is current to <surface>. 384 385 An EGL_BAD_ATTRIBUTE error is generated if an attribute or 386 attribute value not described in table [locksurf.attr] is 387 specified. 388 389 Mapping Buffers of a Locked Surface 390 ----------------------------------- 391 392 The color buffer of a locked surface can be <mapped> by calling 393 eglQuerySurface (see section 3.5.7) with <attribute> 394 EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a 395 buffer in client memory corresponding to the color buffer of 396 <surface>. In the case of a back-buffered surface, color buffer 397 refers to the back buffer. 398 399 [fn: "mapped" only means that the pointer returned is 400 intended to *correspond* to graphics memory. Implementation 401 are not required to return an actual pointer into graphics 402 memory, and often will not.] 403 404 405 The contents of the mapped buffer are initially undefined(fn) 406 unless either the EGL_MAP_PRESERVE_PIXELS_KHR attribute of 407 eglLockSurfaceKHR is set to EGL_TRUE, or (for a window surface) 408 the EGL_SWAP_BEHAVIOR surface attribute is set to 409 EGL_BUFFER_PRESERVE, in which case the contents 410 of the buffer are taken from the contents of <surface>'s color 411 buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is 412 EGL_FALSE. 413 414 [fn: In order to avoid pipeline stalls and readback delays on 415 accelerated implementations, we do not mandate that the 416 current contents of a color buffer appear when it's mapped 417 to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR 418 flag is set or (for a window surface) EGL_SWAP_BEHAVIOR is 419 set to EGL_BUFFER_PRESERVE. Applications using mapped 420 buffers which are not 421 preserved must write to every pixel of the buffer before 422 unlocking the surface. This constraint is considered 423 acceptable for the intended usage scenario (full-frame 424 software renderers). Such an application may lock-render-unlock 425 multiple times per frame (i.e. per eglSwapBuffers) by setting 426 EGL_MAP_PRESERVE_PIXELS_KHR to EGL_TRUE for the second and 427 subsequent locks. 428 429 Note that EGL_SWAP_BEHAVIOR also controls whether the color 430 buffer contents are preserved over a call to eglSwapBuffers.] 431 432 The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a 433 bitmask describing the intended use of the mapped buffer. If the 434 mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from 435 the mapped buffer. If the mask contains 436 EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped 437 buffer. Implementations must support both reading and writing to 438 a mapped buffer regardless of the value of 439 EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the 440 hint is consistent with the actual usage of the buffer. The 441 default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads 442 and writes to the mapped buffer will be done. 443 444 Other attributes of the mapped buffer describe the format of 445 pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), 446 origin (EGL_BITMAP_ORIGIN_KHR), and the bit location of each color 447 component within a pixel (EGL_BITMAP_PIXEL_x_OFFSET_KHR). These 448 attributes may be queried using eglQuerySurface, and are described 449 in more detail in section 3.5.7. 450 451 The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes 452 of a locked surface may change following successive calls to 453 eglLockSurfaceKHR(fn), so they must be queried each time a 454 buffer is mapped. Other attributes of a mapped buffer (listed in 455 the paragraph above) are invariant and need be queried only once 456 following surface creation. 457 458 [fn: The pointer and pitch of a mapped buffer may change due 459 to display mode changes, for example.] 460 461 Mapping will not suceed if client memory to map the surface into 462 cannot be allocated. In this case, querying eglQuerySurface with 463 <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL 464 error. 465 466 Unlocking Surfaces 467 ------------------ 468 469 A rendering surface may be <unlocked> by calling 470 471 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 472 EGLSurface surface); 473 474 Any mapped buffers of <surface> become unmapped following 475 eglUnlockSurfaceKHR. Any changes made to mapped buffers of 476 <surface> which it was locked are reflected in the surface after 477 unlocking(fn). 478 479 [fn: This language enables implementations to either map 480 video memory, or copy from a separate buffer in client 481 memory.] 482 483 If <surface> was created with an EGLConfig whose 484 EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, 485 then the surface is considered optimal (by the implementation) 486 from a performance standpoint when buffer mapping is being 487 done(fn). 488 489 [fn: This often means that the format of all mapped buffers 490 corresponds directly to the format of those buffers in 491 <surface>, so no format conversions are required during 492 unmapping. This results in a high-performance software 493 rendering path. But "optimal format" is really just a hint 494 from EGL that this config is preferred, whatever the actual 495 reason.] 496 497 On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An 498 EGL_BAD_ACCESS error is generated if any of these conditions are 499 true: 500 501 * <surface> is already unlocked. 502 * A display mode change occurred while the surface was locked, 503 and the implementation was unable to reflect mapped buffer 504 state(fn). In this case, <surface> will still be unlocked. 505 However, the contents of the previously mapped buffers of 506 <surface> become undefined, rather than reflecting changes 507 made in the mapped buffers in client memory. 508 509 [fn: Usually this may only occur with window surfaces which 510 have been mapped. EGL does not have an event mechanism to 511 indicate display mode changes. If such a mechanism exists 512 (using native platform events or the OpenKODE event system), 513 applications should respond to mode changes by regenerating 514 all visible window content, including re-doing any software 515 rendering overlapping the mode change.]" 516 517 Add to table 3.5 ("Queryable surface attributes and types") 518 519 Attribute Type Description 520 --------- ---- ----------- 521 EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB). 522 EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of 523 adjacent rows in an MCB. 524 EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction 525 EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer 526 component within a pixel in an MCB. 527 EGL_BITMAP_PIXEL_SIZE_KHR integer Bits per pixel 528 529 In EGL 1.4 only, in the description of eglSurfaceAttrib properties 530 that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, 531 add to the first paragraph describing EGL_SWAP_BEHAVIOR: 532 533 "The value of EGL_SWAP_BEHAVIOR also affects the semantics of 534 eglLockSurfaceKHR for a lockable window surface. See section 3.5.6." 535 536 In EGL 1.4 only, in the description of eglSurfaceAttrib properties 537 that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, 538 change the paragraph concerning the initial value of EGL_SWAP_BEHAVIOR 539 to: 540 541 "The initial value of EGL_SWAP_BEHAVIOR is chosen by the 542 implementation, except for a lockable window surface (i.e. where the 543 EGLConfig has both EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in 544 EGL_SURFACE_TYPE), where the default is EGL_BUFFER_PRESERVED, but it 545 may be overridden by specifying EGL_SWAP_BEHAVIOR to 546 eglCreateWindowSurface." 547 548 In EGL 1.3 only, in the description of eglQuerySurface properties 549 that can be queried in section 3.5.6 (renumbered to 3.5.7), on page 33, 550 add to the paragraph describing EGL_SWAP_BEHAVIOR: 551 552 "The value of EGL_SWAP_BEHAVIOR also affects the semantics of 553 eglLockSurfaceKHR for a lockable window surface. See section 3.5.6. 554 For a lockable window surface (one whose EGLConfig has both 555 EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in EGL_SURFACE_TYPE), 556 the value of this attribute may be set in the eglCreateWindowSurface 557 call, and if not set there defaults to EGL_BUFFER_PRESERVED. See 558 section 3.5.1. The default for a non-lockable surface is chosen by the 559 implementation." 560 561 Add to the description of eglQuerySurface properties in section 562 3.5.6 (renumbered to 3.5.7) on page 33: 563 564 "Properties of a bitmap surface which may be queried include: 565 * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a 566 locked surface and returns the address in client memory of 567 the mapped buffer. 568 * EGL_BITMAP_PITCH_KHR, which returns the number of bytes 569 between successive rows of a mapped buffer. 570 * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a 571 mapped color buffer is displayed on the screen. Possible 572 values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, 573 indicating that the first pixel of the mapped buffer 574 corresponds to the lower left or upper left of a visible 575 window, respectively. 576 * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit 577 location of the least significant bit of each color 578 component of a pixel within a mapped buffer. <x> is one of 579 RED, GREEN, BLUE, ALPHA, or LUMINANCE. 580 581 The offset for a color component should be treated as the 582 number of bits to left shift the component value to place it 583 within a n-bit 584 integer containing the pixel, where n is the number of bits 585 per pixel. If a color 586 component does not exist in the mapped buffer, then the bit 587 offset of that component is zero. If a color component 588 does exist but not in a single contiguous range of bits, 589 then the value of the attribute is EGL_UNKNOWN. 590 591 * EGL_BITMAP_PIXEL_SIZE_KHR, which returns the number of bits 592 per pixel, assumed to be least significant leftmost if there 593 are multiple pixels per byte. The attribute takes the value 594 EGL_UNKNOWN if this assumption is not true, or if pixels are not 595 laid out left to right in memory (for example pairs of 16-bit 596 pixels are swapped in memory). 597 598 In addition to these attributes, the number of bits for each 599 color component of a pixel within a mapped buffer is obtained by 600 querying the EGL_<x>_SIZE attribute of the EGLConfig used to 601 create the surface, where <x> is <x> is one of RED, GREEN, BLUE, 602 ALPHA, or LUMINANCE. 603 604 Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only 605 allowed when <surface> is mapped (see section 3.5.6). Querying 606 either of these attributes for the first time after calling 607 eglLockSurfaceKHR causes the color buffer of the locked surface 608 to be mapped. Querying them again before unlocking the surface 609 will return the same values as the first time. However, after 610 calling eglUnlockSurfaceKHR, these properties become undefined. 611 After a second call to eglLockSurfaceKHR, these properties may 612 again be queried, but their values may have changed. 613 614 Other properties of the mapped color buffer of a surface 615 (in the list above) are 616 invariant, and need be queried only once following surface 617 creation. If <surface> was created with an EGLConfig whose 618 EGL_SURFACE_TYPE attribute does not contain 619 EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR, 620 EGL_BITMAP_PIXEL_<x>_OFFSET_KHR and EGL_BITMAP_PIXEL_SIZE_KHR 621 return undefined values." 622 623 Add to the description of eglQuerySurface errors in the last 624 paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34: 625 626 "... If <attribute> is either EGL_BITMAP_POINTER_KHR or 627 EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using 628 eglLockSurfaceKHR, or <surface> is locked but mapping fails, 629 then an EGL_BAD_ACCESS error is generated." 630 631 In section 3.9.3 Posting Semantics on page 46, append to the first 632 paragraph: 633 634 "This restriction does not apply to lockable surfaces; for such 635 a surface, eglSwapBuffers and eglCopyBuffers may be called for 636 a surface not bound to any client API context(fn). 637 638 [fn: Normally this would only be done when using methods other 639 than client API rendering to specify the color buffer contents, 640 such as software rendering to a locked surface.]" 641 642 and replace the second paragraph ("If <dpy> and <surface> ... not be 643 executed until posting is completed.") with: 644 645 "If <surface> is bound to a current client API context for the calling 646 thread, eglSwapBuffers and eglCopyBuffers perform an implicit flush 647 operation on the context (glFlush for an OpenGL or OpenGL ES context, 648 vgFlush for an OpenVG context). Subsequent client API commands can be 649 issued immediately, but will not be executed until posting is 650 completed. 651 652 If <surface> is current to a client API context in any thread other 653 than the calling thread, eglSwapBuffers and eglCopyBuffers will fail. 654 655 and append the following sentence to the eglSwapInterval paragraph: 656 657 "The swap interval has no effect on an eglSwapBuffers for a surface 658 not bound to a current client API context." 659 660 In 3.9.4 Posting Errors, change the sentence "If <surface> is not bound 661 to the calling thread's current context, an EGL_BAD_SURFACE error is 662 generated." to: 663 664 "If <surface> is bound to a current context in a thread other 665 than the calling thread, an EGL_BAD_SURFACE error is generated." 666 667 668Issues 669 670 1) What is the rationale for this extension? 671 672 Software renderers on low-end implementations need an efficient way 673 to draw pixel data to the screen. High-end implementations must 674 support the same interface for compatibility, while not compromising 675 the accelerability of OpenGL ES and OpenVG client APIs using 676 dedicated graphics hardware and memory. 677 678 Using lock/unlock semantics enables low-end implementations to 679 expose pointers directly into display memory (as extremely dangerous 680 as that may be), while high-end implementations may choose to create 681 backing store in client memory when mapping a buffer, and copy it to 682 graphics memory when the surface is unlocked. Making the initial 683 contents of a mapped buffer undefined means that no readbacks from 684 graphics memory are required, avoiding pipeline stalls. 685 686 This extension is not intended to support mixed-mode (client API and 687 software) rendering. Since mapped buffer contents are undefined, 688 unless the buffer is explicitly preserved (which may be unacceptably 689 expensive on many implementations), applications doing software 690 rendering must touch every pixel of mapped buffers at least once 691 before unlocking the surface. 692 693 2) Do we need to know if locked surfaces are "fast" or "native"? 694 695 RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR 696 of EGL_SURFACE_TYPE. However, note that there is no way to guarantee 697 what "fast" or "no format conversions" really means; this is little 698 more than an implementation hint. 699 700 3) Should we be able to map buffers other than the color buffer? 701 702 RESOLVED: Not initially. However, the <attrib_list> parameter of 703 eglLockSurfaceKHR supports this in the future. There is no <buffer> 704 attribute to eglQuerySurface, so such a layered extension would have 705 to either create a new naming convention (such as 706 EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an 707 extended query eglQuerySurfaceBuffer() which takes a <buffer> 708 parameter. It would also be tricky to support interleaved depth / 709 stencil formats. But the attribute list offers some future-proofing 710 at low cost. 711 712 4) What properties of mapped buffers can be queried? 713 714 RESOLVED: A pointer to the buffer and its pitch, both of which may 715 change in successive lock/unlock cycles. These may be queried only 716 while the underlying surface is locked, and are undefined after 717 unlocking. The first query following locking is the point at which 718 actual buffer mapping must occur. 719 720 RESOLVED: Additionally, the pixel size, origin, and color component 721 bitfield size and offset for each component, which are invariant 722 and may be queried at any time. 723 724 5) How are mode changes indicated? What happens to the mapped 725 buffer during a mode change? 726 727 RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode 728 change occurred while the surface was locked (although the surface 729 still ends up in the unlocked state - this is necessary since 730 there's no way to clear the error!). If a mode change occurs while a 731 buffer is mapped, the implementation must still allow the 732 application to access mapped buffer memory, even though the contents 733 of the mapped buffer may not be reflected in the changed window 734 after unmapping. 735 736 Note: There's no convenient way to indicate mode changes while 737 a surface is unlocked, despite that being useful to tell apps they 738 have to redraw. The problem is that we don't have an event system, 739 and the power management functionality is overkill since the only 740 resources which are likely to be damaged by a mode change are 741 visible window contents. Fortunately, this problem is beyond the 742 scope of this extension. 743 744 6) Does locking a surface imply mapping its buffers? 745 746 RESOLVED: No. Locking simply places the surface in that state and 747 prevents it from being made current / swapped / etc. Buffers are 748 mapped only when their pointers or pitch are queried using 749 eglQuerySurface. 750 751 An interesting side effect of this resolution is that calling 752 eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES 753 NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped. 754 Likewise locking a surface, querying a buffer pointer or pitch, and 755 then unlocking it without changing the mapped buffer contents causes 756 the surface contents of the mapper buffer(s) to become undefined. 757 758 At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR 759 should immediately map the color buffer and return a pointer to it, 760 on the basis that this would make it harder for applications to 761 mistakenly use an old buffer pointer from a previous mapping cycle. 762 At the same time, people working on more powerful GPUs wanted the 763 lock operation to be lightweight. These are not consistent goals and 764 we have thus far chosen to separate the lightweight locking, and 765 more expensive mapping operations. 766 767 7) Can buffer contents be preserved in mapping? 768 769 RESOLVED: Yes. The default behavior is to discard / leave undefined 770 the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag 771 may be specified to eglLockSurfaceKHR. 772 773 8) Should usage hints be provided during mapping? 774 775 RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR 776 bitmask attribute to eglLockSurfaceKHR. Implementations are required 777 to behave correctly no matter the value of the flag vs. the 778 operations actually performed, so the hint may be ignored. 779 780 9) Should we be able to lock subrectangles of a surface? 781 782 RESOLVED: No. However, the attribute list parameter of 783 eglLockSurfaceKHR allows a layered extension to implement this 784 behavior by specifying an origin and size to map within the buffer. 785 78610) Should the BITMAP_PIXEL_<component>_OFFSET attributes belong to the 787 surface, or the config? 788 789 RESOLVED: Part of the surface. Configs supporting a specific format 790 are matched with config attribute EGL_MATCH_FORMAT_KHR, which 791 supports specific bit-exact formats such as 792 EGL_FORMAT_565_EXACT_KHR. 793 79411) Can the pixel size in a mapped buffer be derived from the 795 EGL_BUFFER_SIZE attribute of the config used to create it? 796 797 RESOLVED: Yes. In principle, hardware using padding bytes in its 798 framebuffer storage could be a problem, and a separate 799 BITMAP_PIXEL_SIZE surface attribute would be needed. However, we 800 don't think implementations are likely to waste graphics memory and 801 bandwidth in this fashion. 802 80312) How are color component locations within a pixel described? 804 805 RESOLVED: Each R, G, B, and A component has a queryable bit offset 806 within an integer. The size of the integer depends on the total size 807 of the pixel; for the 565 formats, the pixel is a 16-bit integer. 808 For the 8888 formats, the pixel is a 32-bit integer. 809 810 We cannot describe component locations with byte locations, since 811 the 565 formats have components straddling byte boundaries. However, 812 this means that offsets for the RGBA8888_EXACT format are different 813 between little- and big-endian CPUs, since the desired format is B, 814 G, R, A components laid out as bytes in increasing memory order. 815 81613) Can mapped buffer contents be affected by other EGL operations? 817 818 RESOLVED: No. A locked surface only allows two operations: 819 unlocking, and mapping. No other EGL operations can take place while 820 the surface is locked (if this were not the case, then 821 eglSwapBuffers might destroy the contents of a mapped buffer). 822 823 It is possible that operations outside the scope of EGL could affect 824 a mapped color buffer. For example, if a surface's color buffer were 825 made up of an EGLImage, one of the EGL client APIs could draw to 826 that image while it was mapped. Responsibility for avoiding this 827 situation is in the hands of the client. 828 82914) Can EGL_MATCH_FORMAT_KHR be queried for a config? 830 831 RESOLVED: Yes. Unlockable configs return EGL_NONE for this 832 attribute. 833 834 For a config whose format matches one of the EGL_FORMAT_*_EXACT_KHR 835 definitions, that value is returned. 836 837 For a config whose format does not match one of the 838 EGL_FORMAT_*_EXACT_KHR definitions, but it does match one of the 839 inexact definitions, we do not want to specify that it returns that 840 value, since that precludes it returning an exact format if one were 841 to be defined in a future extension, or a future version of this 842 extension. 843 844 Therefore, for a config whose format does not match a defined 845 "exact" format, the attribute returns a value other than the defined 846 "exact" formats and EGL_NONE and EGL_DONT_CARE. 847 84815) Is a goal of this extension to support "mixed-mode" rendering (both 849 software and EGL client API rendering to the same surface)? 850 851 RESOLVED: No. An implementation *can* choose to export configs 852 supporting creation of lockable surfaces which also support 853 rendering by OpenGL ES, OpenVG, or other client APIs (when the 854 surface is not locked). But there is nothing in the extension 855 requiring this, and the motivation for the extension is simply to 856 support software rendering. 857 85816) Can mapping a locked surface fail? 859 860 RESOLVED: Yes, if memory can't be allocated in the client. This is 861 indicated by queries of EGL_BITMAP_POINTER_KHR and 862 EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error. 863 86417) How does the application specify that it would like the pixels in the 865 mapped buffer to be preserved from the state at the last unlock? 866 [Bug 4410] 867 868 There are actually two items that need to be configurable: 869 870 a. Whether eglSwapBuffers preserves the color buffer. 871 872 b. Whether eglLockSurfaceKHR puts the color buffer pixels into the 873 locked buffer. 874 875 An implementation may use two different render paths depending on whether 876 the application is full frame rendering or incrementally rendering, where 877 the full frame rendering path may involve less copying than the 878 incrementally rendering path. The implementation needs to know in advance 879 which path to use; finding out from EGL_MAP_PRESERVE_PIXELS_KHR on 880 eglLockSurfaceKHR whether that lock should have the color buffer pixels 881 from the last eglUnlockSurfaceKHR in the last frame is too late. 882 883 This need to know in advance only applies to (a). 884 885 Note that the original EGL_KHR_lock_surface extension failed to state 886 that EGL_SWAP_BEHAVIOR needed to be set to EGL_BUFFER_PRESERVED for 887 incremental rendering. 888 889 RESOLVED: EGL_MAP_PRESERVE_PIXELS_KHR continues to control (b), as in the 890 original EGL_KHR_lock_surface extension. EGL_SWAP_BEHAVIOR continues 891 to control (a), as in unextended EGL. It is possible to set 892 EGL_SWAP_BEHAVIOR in eglCreateWindowSurface, even on EGL versions 893 before 1.4, and even if the config does not have 894 EGL_SWAP_BEHAVIOR_PRESERVED_BIT set in EGL_SURFACE_TYPE. 895 896 For a lockable window surface, EGL_SWAP_BEHAVIOR needs to default to 897 EGL_BUFFER_PRESERVED, and having EGL_SWAP_BEHAVIOR set to 898 EGL_BUFFER_PRESERVED needs to override EGL_MAP_PRESERVE_PIXELS_KHR. This is for 899 compatibility with version 1 of this extension, which had EGL_SWAP_BEHAVIOR 900 as the sole means of controlling (a) and (b). 901 902 This resolution is backward compatible with the original 903 EGL_KHR_lock_surface extension as it now defaults to preserving pixels, 904 and thus has that default for an old application that does not know about 905 setting EGL_SWAP_BEHAVIOR=EGL_BUFFER_DESTROYED to optimize full frame 906 rendering. The downside is a possible performance reduction of an old 907 application that does not want pixels preserved, until it is appropriately 908 modified and recompiled. 909 91018) When can a lockable surface change size? [Bug 4522] 911 912 RESOLVED: The surface cannot change size while it is locked. For any 913 window size change during that time, EGL defers the corresponding 914 surface size change until some time after the unlock. 915 The implication is that an application must get the surface size 916 _after_locking, otherwise the size may have changed in between the 917 attribute query and the lock. 918 919 As part of this change, using eglQuerySurface on any surface attribute 920 while the surface is locked has been allowed. 921 92219) Should we provide for more than one pixel per byte, or a format with 923 a "hole", or a byte-swapped 16-bit format? [Bug 4513] 924 925 For the use case where the application uses EGL_FORMAT_* to 926 determine the pixel format, this is not an issue. For the use case 927 where the application is written to cope with any format by reading 928 the EGL_BITMAP_* attributes and adjusting its rendering at runtime, 929 this is an issue. 930 931 RESOLVED: We add a new attribute EGL_BITMAP_PIXEL_SIZE_KHR which gives 932 the pixel size in bits. 933 The use of this attribute assumes that multiple pixels packed into 934 a byte are arranged least significant on the left, and that pixels 935 are arranged leftmost first in memory. If either of these assumptions 936 is false, then EGL_BITMAP_PIXEL_SIZE_KHR is EGL_UNKNOWN to indicate 937 that an application attempting to use these attributes to adjust its 938 rendering code will not work. 939 940 We also define that any of the EGL_BITMAP_PIXEL_x_OFFSET_KHR attributes 941 have a value of EGL_UNKNOWN if the corresponding color component is not 942 a contiguous bit range. 943 94420) EGL states that surface must be bound to the thread's current context 945 when posting, but there is no current context when using lock surface. 946 eglSwapInterval is also related to the context. [Bug 5923] 947 948 RESOLVED: The posting restrictions are relaxed, so it is allowed to 949 post for a surface not bound to any client API context. In this case 950 no eglSwapInterval setting affects an eglSwapBuffers. This relaxation 951 only applies to a lockable surface so that this extension continues 952 to be implementable as a middleware layer on top of a "real" EGL. 953 The relaxation applies to a surface that is both lockable and client 954 API renderable; the implicit flush in a post only occurs when the surface 955 is bound to a current API context. Posting a surface bound to a different 956 thread's current API context is still disallowed. 957 95821) Why has this extension been obsoleted and replaced by 959 EGL_KHR_lock_surface3? 960 961 RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint 962 is defined to be the same size as the native platform "int" type. Handle 963 and pointer attribute values *cannot* be represented in attribute lists 964 on platforms where sizeof(handle/pointer) > sizeof(int). Existing 965 extensions which assume this functionality are being replaced with new 966 extensions specifying new entry points to work around this issue. See 967 the latest EGL 1.4 Specification for more details. 968 969 970Revision History 971 972 Version 3, 2013/12/04 - Add issue 21 explaining that the bitmap pointer 973 cannot be safely queried using this extension on 64-bit platforms, 974 and suggesting EGL_KHR_lock_surface3 instead. Change formal 975 parameter names from 'display' to 'dpy' to match other EGL APIs. 976 Version 2, 2010/03/10 977 Allocated extension number 16. 978 [Bug 6089] Clarified that it is the back buffer of a back-buffered 979 surface that is mapped. 980 [Bug 4410] Issue 17: Reinstate EGL_MAP_PRESERVE_PIXELS_KHR attribute on 981 eglLockSurfaceKHR as the means of configuring whether a locked 982 buffer contains pixel data from the color buffer, as in 983 EGL_KHR_lock_surface, but, for a lockable window surface, 984 make EGL_SWAP_BEHAVIOR=EGL_BUFFER_PRESERVED override the effect 985 of that attribute. Tidy wording so that behavior, and that the 986 default of EGL_SWAP_BEHAVIOR must be EGL_BUFFER_PRESERVED, only 987 applies to lockable window surfaces, not lockable pbuffer or 988 pixmap surfaces. 989 [Bug 5923] Issue 20: A config that is lockable and renderable by 990 an EGL client API is now allowed. Posting restrictions are relaxed 991 to allow posting for a lockable surface not bound to any client 992 API context. 993 [Bug 5143] Fixed typos EGL_SURFACE_TYPE_KHR. Added summary of 994 changes over EGL_KHR_lock_surface. 995 Version 1, 2010/01/19 996 [Bug 4410] Issue 17: Change to use EGL_SWAP_BEHAVIOR as the 997 primary means of determining whether the application wants pixels 998 preserved between lock/unlock cycles. 999 Allowed setting of EGL_SWAP_BEHAVIOR in 1000 eglCreateWindowSurface for a lockable surface. Made the 1001 default EGL_BUFFER_PRESERVED on a lockable surface to maintain 1002 compatibility with the original lock surface extension. 1003 [Bug 3192] Wording clarification to avoid accidentally suggesting 1004 that almost all surface attributes are invariant. 1005 [Bug 4518] Issue 14: Clarify the returned value when 1006 EGL_MATCH_FORMAT_KHR is queried. 1007 [Bug 4522] Issue 18: Clarify that a locked surface cannot change 1008 size. 1009 [Bug 4513] Issue 19: Added EGL_BITMAP_PIXEL_SIZE_KHR. 1010 [Bug 5923] Issue 20: Must be no current context when posting 1011 a lockable surface. In that case any eglSwapInterval setting 1012 is ignored. Disallowed a config that is lockable and renderable 1013 by an EGL client API. 1014 1015Revision History of original EGL_KHR_lock_surface extension 1016 1017 Version 18, 2010/03/23 - Added introductory remark referring to the 1018 EGL_KHR_lock_surface2 extension. 1019 Version 17, 2008/10/08 - Updated status (approved as part of 1020 OpenKODE 1.0). 1021 Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail, 1022 and a corresponding new error condition for eglQuerySurface. 1023 Clean up the issues list. 1024 Version 15, 2008/01/09 - Add issue 15 noting that supporting 1025 mixed-mode rendering is not a goal or requirement of the 1026 extension. 1027 Version 14, 2007/11/07 - change ARGB_8888_EXACT back to 1028 RGBA_8888_EXACT, since the offsets are now dependent on the 1029 endianness of the CPU. Add issue 12 describing this, and clarify 1030 that offsets are within a 16- or 32-bit integer depending on the 1031 format. Added issue 13 clarifying that locked buffer contents 1032 are not affected by eglSwapBuffers, because eglSwapBuffers 1033 cannot be issued on a mapped surface. Allow querying 1034 EGL_MATCH_FORMAT_KHR for a config, and added related issue 14. 1035 Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT 1036 to match hardware layout. 1037 Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is 1038 EGL_DONT_CARE, it does not affect component size of selected 1039 configs. 1040 Version 11, 2007/04/05 - add missing KHR suffix to some tokens. 1041 Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0 1042 Provisional disclaimer. 1043 Version 9, 2007/03/26 - add format tokens to "New Tokens" 1044 section. Correct description of RGBA format tokens. 1045 Version 8, 2007/03/26 - add issue 11 noting theoretical possibility 1046 of EGL_BUFFER_SIZE not directly corresponding to the mapped 1047 pixel size. Add EGL_MATCH_FORMAT_KHR attribute to 1048 eglChooseConfig, and 565 / 8888 formats for it. 1049 Version 7, 2007/03/25 - note in issue 5 that access to a mapped 1050 buffer must continue to work even after a mode change. Add KHR 1051 suffix to new functions and tokens. Remove BITMAP_PIXEL_<x>_BITS 1052 and BITMAP_PIXEL_SIZE tokens, which duplicate information in the 1053 EGLConfig. Add issue 10 asking whether bitmap pixel offset 1054 attributes belong to the config, or to the surface. 1055 Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in 1056 implementations supporting only this extension. 1057 Version 5, 2007/02/05 - update contributor list. Changed bit offset 1058 queries to return LSB offset, rather than MSB offset. 1059 Version 4, 2007/02/02 - correct extension name. Change 1060 name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR. 1061 Replace buffer_mask parameter of eglLockSurfaceKHR with an 1062 attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and 1063 EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues 1064 7, 8, and 9 describing these attributes and how to support 1065 locking subrects in a layered extension, by extending the 1066 attribute list. 1067 Version 3, 2007/02/01 - the implementation once again controls the 1068 mapped buffer memory. There is no longer a separate bitmap 1069 surface type; any type surface may potentially be mapped, using 1070 lock/unlock semantics. 1071 Version 2, 2006/12/22 - simplify by only supporting drawing from 1072 client memory to EGL surface color buffers. Specify use of 1073 OpenGL DrawPixels terminology. Change name of the extension to 1074 EGL_KHR_draw_pixels, since there is no longer any "bitmap 1075 surface" involved. 1076 Version 1, 2006/12/14 - write up as formal spec language for 1077 external review. 1078