1Name 2 3 KHR_lock_surface3 4 5Name Strings 6 7 EGL_KHR_lock_surface3 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 Complete. 30 Approved by the EGL Working Group on December 4, 2013. 31 32Version 33 34 Version 4, 2014/09/17 35 36Number 37 38 EGL Extension #64 39 40Dependencies 41 42 EGL 1.4 is required. 43 44 This extension is based on the EGL_KHR_lock_surface2 extension and 45 almost all language is copied from that extension. However, it is 46 standalone extension. The specification language has been re-based 47 against the EGL 1.4 Specification. 48 49 Khronos recommends obsoleting and replacing implementations of 50 EGL_KHR_lock_surface2 and EGL_KHR_lock_surface with this extension as 51 soon as possible. 52 53Overview 54 55 This extension allows mapping color buffers of EGL surfaces into the 56 client address space. This is useful primarily for software 57 rendering on low-end devices which do not support EGL client 58 rendering APIs, although it may be implemented efficiently on more 59 capable devices as well. 60 61 This extension is functionally identical to EGL_KHR_lock_surface2, but 62 is intended to replace that extension. It defines a new EGL type, 63 EGLAttribKHR, which is an integer type guaranteed to be large enough to 64 hold a pointer. A new surface query, eglQuerySurface64KHR, is defined to 65 query surface attributes which may not fit in than EGLint, such as a 66 mapped surface pointer. 67 68 The changes over EGL_KHR_lock_surface2 include: 69 70 * EGL_KHR_lock_surface3 defines the type EGLAttribKHR and the 71 command eglQuerySurface64KHR. 72 * eglQuerySurface64KHR must be used to query the 73 EGL_BITMAP_POINTER_KHR property of surfaces. 74 75New Types 76 77 /* 78 * EGLAttribKHR is a integer type used to pass arrays of attribute 79 * name/value pairs which may include pointer and handle attribute 80 * values. 81 */ 82 #include <khrplatform.h> 83 typedef intptr_t EGLAttribKHR; 84 85New Procedures and Functions 86 87 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, 88 const EGLint *attrib_list); 89 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 90 EGLSurface surface); 91 EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, 92 EGLSurface surface, 93 EGLint attribute, 94 EGLAttribKHR *value); 95 96New Tokens 97 98 Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: 99 100 EGL_LOCK_SURFACE_BIT_KHR 0x0080 101 EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 102 103 Accepted as an attribute name in the <attrib_list> argument of 104 eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: 105 106 EGL_MATCH_FORMAT_KHR 0x3043 107 108 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute 109 of eglChooseConfig, and defined as possible values of that attribute 110 when querying it: 111 112 EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 113 EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 114 115 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute 116 of eglChooseConfig: 117 118 EGL_FORMAT_RGB_565_KHR 0x30C1 119 EGL_FORMAT_RGBA_8888_KHR 0x30C3 120 121 Accepted as attribute names in the <attrib_list> argument of 122 eglLockSurfaceKHR: 123 124 EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 125 EGL_LOCK_USAGE_HINT_KHR 0x30C5 126 127 Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute 128 of eglLockSurfaceKHR: 129 130 EGL_READ_SURFACE_BIT_KHR 0x0001 131 EGL_WRITE_SURFACE_BIT_KHR 0x0002 132 133 Accepted by the <attribute> parameter of eglQuerySurface and 134 eglQuerySurface64KHR: 135 136 EGL_BITMAP_PITCH_KHR 0x30C7 137 EGL_BITMAP_ORIGIN_KHR 0x30C8 138 EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 139 EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA 140 EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB 141 EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC 142 EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD 143 EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 144 145 Accepted by the <attribute> parameter of eglQuerySurface64KHR: 146 EGL_BITMAP_POINTER_KHR 0x30C6 147 148 Returns in the *<value> parameter of eglQuerySurface when 149 <attribute> is EGL_BITMAP_ORIGIN_KHR: 150 151 EGL_LOWER_LEFT_KHR 0x30CE 152 EGL_UPPER_LEFT_KHR 0x30CF 153 154Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) 155 156 Add to the end of section 2.2.2: 157 158 Finally, some surfaces may be <locked>, which allows the 159 implementation to map buffers of that surface into client memory 160 for use by software renderers(fn). Locked surfaces cannot be 161 used for any other purpose. When a locked surface is <unlocked>, 162 any changes to the mapped buffer(s) are reflected in the actual 163 graphics or system memory containing the surface. 164 165 [fn: on implementations not supporting mapping graphics 166 memory, or which do not wish to take the stability and 167 security risks that entail, mapping may be done using 168 copy-out and copy-in behavior.] 169 170Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) 171 172 Add to the description of the EGL_BAD_ACCESS error in section 3.1: 173 174 "... (for example, a context is bound in another thread, or a 175 surface is locked). Any command accessing ..." 176 177 Add to table 3.2 ("Types of surfaces supported by an EGLConfig") 178 179 EGL Token Name Description 180 -------------------- ------------------------------------ 181 EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces 182 EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal 183 (preferred) when locking / mapping / 184 unlocking is being done. 185 186 Change the first paragraph under "Other EGLConfig Attribute 187 Descriptions" on p. 16: 188 189 "EGL_SURFACE_TYPE is a mask indicating both the surface types 190 that can be created by the corresponding EGLConfig (the config 191 is said to <support> those surface types), and the optional 192 behaviors such surfaces may allow. The valid bit settings are 193 shown in Table 3.2." 194 195 Add a new paragraph following the second paragraph of the same 196 section: 197 198 "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE, then 199 a surface created from the EGLConfig may be locked, mapped into 200 client memory, and unlocked. Locking is described in section 201 3.5.5ls. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in 202 EGL_SURFACE_TYPE, then the surface is considered optimal (by 203 the implementation) from a performance standpoint when buffer 204 mapping is being done." 205 206 Replace the second paragraph of section 3.3 "EGL Versioning": 207 208 "The EGL_CLIENT_APIS string describes which client rendering APIs are 209 supported. It is zero-terminated and contains a space-separated list 210 of API names, which must include at least one of ``OpenGL'', 211 ``OpenGL_ES'', or OpenGL ES. If no client APIs are supported, then 212 the empty string is returned." 213 214 Insert a new paragraph and table in section 3.4.1.1 "Querying 215 Configurations", following the description of 216 EGL_MATCH_NATIVE_PIXMAP on page 24: 217 218 "If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must 219 be followed by one of the attribute values EGL_DONT_CARE, 220 EGL_NONE, or one of the format tokens in table 221 [locksurf.format]. 222 223 When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs 224 which cannot be locked or mapped will match. Such configs must 225 not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. 226 227 When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is 228 ignored. 229 230 When EGL_MATCH_FORMAT_KHR has one of the values in table 231 [locksurf.format], only EGLConfigs describing surfaces whose 232 color buffers have the specified format, when mapped with 233 eglLockSurface, will match this attribute. In this case, the 234 EGL_<component>_SIZE attributes of resulting configs must agree 235 with the specific component sizes specified by the format." 236 237 Specific Format Name Description 238 -------------------- ----------- 239 EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer 240 EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer 241 EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory 242 EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer 243 ------------------------------------------------------------------------------------------------------ 244 Table [locksurf.format]: Specific formats for mapped pixels. 245 246 Add to table 3.4 ("Default values and match critera for EGLConfig 247 attributes") on page 25: 248 249 Attribute Default Selection Sort Sort 250 Criteria Order Priority 251 -------------------- ------------- --------- ----- -------- 252 EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - 253 254 Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on 255 p. 26, describing attributes not used for sorting EGLConfigs. 256 257 Add a new paragraph to the end of section 3.4.3 "Querying Configuration 258 Attributes": 259 260 "Querying the EGL_MATCH_FORMAT_KHR attribute results in EGL_NONE 261 for an EGLConfig that is not lockable, one of the "exact" formats 262 (EGL_FORMAT_RGB_565_EXACT_KHR, EGL_FORMAT_RGBA_8888_EXACT_KHR) 263 if the color buffer matches that format when mapped with 264 eglLockSurface, or for any other format a value that is not 265 EGL_NONE or EGL_DONT_CARE but is otherwise undefined. In particular, 266 the color buffer format matching one of the "inexact" formats 267 does not guarantee that that EGL_FORMAT_* value is returned." 268 269 In section 3.5.1 "Creating On-Screen Rendering Surfaces", add to the 270 second paragraph on p. 28 listing attributes that can be set in 271 attrib_list: 272 273 "<attrib_list> specifies a list of attributes ... and 274 EGL_SWAP_BEHAVIOR." 275 276 and add preceding the paragraph starting "EGL_VG_COLORSPACE specifies 277 ..." on p. 28: 278 279 "EGL_SWAP_BEHAVIOR specifies the initial value of the 280 EGL_SWAP_BEHAVIOR surface attribute (section 3.5.6), and is thus 281 either EGL_BUFFER_PRESERVED or EGL_BUFFER_DESTROYED. This setting 282 of EGL_SWAP_BEHAVIOR at surface creation time is supported only 283 for a lockable surface, i.e. where the EGLConfig has 284 EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. 285 286 "For such a lockable surface, whether it is possible to change 287 the EGL_SWAP_BEHAVIOR attribute after surface creation is 288 determined by EGL_SWAP_BEHAVIOR_PRESERVED_BIT in the 289 EGL_SURFACE_TYPE EGLConfig attribute." 290 291 Add a new section following the current section 3.5.5: 292 293 "3.5.5ls Locking and Mapping Rendering Surfaces 294 295 A rendering surface may be <locked> by calling 296 297 EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, 298 EGLSurface surface, 299 const EGLint *attrib_list); 300 301 While a surface is locked, only two operations can be performed 302 on it. First, a surface attribute may be queried using 303 the query commands in section 3.5.6. This includes the case of 304 querying EGL_BITMAP_POINTER_KHR, which causes the surface to be 305 <mapped> (if not already mapped) and gives a pointer into client 306 memory corresponding to the memory of the mapped buffer. Second, 307 the surface may be unlocked. Any attempts to use a locked surface 308 in other EGL APIs will fail and generate an EGL_BAD_ACCESS error. 309 310 While a surface is locked, its dimensions (the values of the EGL_WIDTH 311 and EGL_HEIGHT surface attributes) do not change. They may change 312 at any other time, therefore an application must query these 313 attributes <after> the call to eglLockSurfaceKHR to ensure that it has 314 the correct size of the mapped buffer. 315 316 <attrib_list> specifies additional parameters affecting the locking 317 operation. The list has the same structure as described for 318 eglChooseConfig. Attributes that may be defined are shown in table 319 [locksurf.attr], together with their default values if not specified 320 in <attrib_list>, and possible values which may be specified for 321 them in <attrib_list>. 322 323 Attribute Name Type Default Value Possible Values 324 ----------------------- ------- ------------- ------------------------- 325 EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE 326 EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of 327 EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR 328 and EGL_WRITE_SURFACE_BIT_KHR 329 -------------------------------------------------------------- 330 Table [locksurf.attr]: eglLockSurfaceKHR attribute names, 331 default values, and possible values. 332 333 On failure, the surface is unaffected and eglLockSurfaceKHR 334 returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any 335 of these condition, are true: 336 337 * <surface> was created with an EGLConfig whose 338 EGL_SURFACE_TYPE attribute does not contain 339 EGL_LOCK_SURFACE_BIT_KHR. 340 * <surface> is already locked. 341 * Any client API is current to <surface>. 342 343 An EGL_BAD_ATTRIBUTE error is generated if an attribute or 344 attribute value not described in table [locksurf.attr] is 345 specified. 346 347 Mapping Buffers of a Locked Surface 348 ----------------------------------- 349 350 The color buffer of a locked surface can be <mapped> by calling 351 eglQuerySurface64KHR (see section 3.5.6) with <attribute> 352 EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a 353 buffer in client memory corresponding to the color buffer of 354 <surface>. In the case of a back-buffered surface, color buffer 355 refers to the back buffer. 356 357 [fn: "mapped" only means that the pointer returned is 358 intended to *correspond* to graphics memory. Implementation 359 are not required to return an actual pointer into graphics 360 memory, and often will not.] 361 362 363 The contents of the mapped buffer are initially undefined(fn) 364 unless either the EGL_MAP_PRESERVE_PIXELS_KHR attribute of 365 eglLockSurfaceKHR is set to EGL_TRUE, or (for a window surface) 366 the EGL_SWAP_BEHAVIOR surface attribute is set to 367 EGL_BUFFER_PRESERVE, in which case the contents 368 of the buffer are taken from the contents of <surface>'s color 369 buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is 370 EGL_FALSE. 371 372 [fn: In order to avoid pipeline stalls and readback delays on 373 accelerated implementations, we do not mandate that the 374 current contents of a color buffer appear when it's mapped 375 to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR 376 flag is set or (for a window surface) EGL_SWAP_BEHAVIOR is 377 set to EGL_BUFFER_PRESERVE. Applications using mapped 378 buffers which are not 379 preserved must write to every pixel of the buffer before 380 unlocking the surface. This constraint is considered 381 acceptable for the intended usage scenario (full-frame 382 software renderers). Such an application may lock-render-unlock 383 multiple times per frame (i.e. per eglSwapBuffers) by setting 384 EGL_MAP_PRESERVE_PIXELS_KHR to EGL_TRUE for the second and 385 subsequent locks. 386 387 Note that EGL_SWAP_BEHAVIOR also controls whether the color 388 buffer contents are preserved over a call to eglSwapBuffers.] 389 390 The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a 391 bitmask describing the intended use of the mapped buffer. If the 392 mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from 393 the mapped buffer. If the mask contains 394 EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped 395 buffer. Implementations must support both reading and writing to 396 a mapped buffer regardless of the value of 397 EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the 398 hint is consistent with the actual usage of the buffer. The 399 default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads 400 and writes to the mapped buffer will be done. 401 402 Other attributes of the mapped buffer describe the format of 403 pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), 404 origin (EGL_BITMAP_ORIGIN_KHR), and the bit location of each color 405 component within a pixel (EGL_BITMAP_PIXEL_x_OFFSET_KHR). These 406 attributes may be queried using eglQuerySurface, and are described 407 in more detail in section 3.5.6. 408 409 The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes 410 of a locked surface may change following successive calls to 411 eglLockSurfaceKHR(fn), so they must be queried each time a 412 buffer is mapped. Other attributes of a mapped buffer (listed in 413 the paragraph above) are invariant and need be queried only once 414 following surface creation. 415 416 [fn: The pointer and pitch of a mapped buffer may change due 417 to display mode changes, for example.] 418 419 Mapping will not suceed if client memory to map the surface into 420 cannot be allocated. In this case, calling eglQuerySurface64KHR 421 with <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an 422 EGL error. 423 424 Unlocking Surfaces 425 ------------------ 426 427 A rendering surface may be <unlocked> by calling 428 429 EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, 430 EGLSurface surface); 431 432 Any mapped buffers of <surface> become unmapped following 433 eglUnlockSurfaceKHR. Any changes made to mapped buffers of 434 <surface> which it was locked are reflected in the surface after 435 unlocking(fn). 436 437 [fn: This language enables implementations to either map 438 video memory, or copy from a separate buffer in client 439 memory.] 440 441 If <surface> was created with an EGLConfig whose 442 EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, 443 then the surface is considered optimal (by the implementation) 444 from a performance standpoint when buffer mapping is being 445 done(fn). 446 447 [fn: This often means that the format of all mapped buffers 448 corresponds directly to the format of those buffers in 449 <surface>, so no format conversions are required during 450 unmapping. This results in a high-performance software 451 rendering path. But "optimal format" is really just a hint 452 from EGL that this config is preferred, whatever the actual 453 reason.] 454 455 On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An 456 EGL_BAD_ACCESS error is generated if any of these conditions are 457 true: 458 459 * <surface> is already unlocked. 460 * A display mode change occurred while the surface was locked, 461 and the implementation was unable to reflect mapped buffer 462 state(fn). In this case, <surface> will still be unlocked. 463 However, the contents of the previously mapped buffers of 464 <surface> become undefined, rather than reflecting changes 465 made in the mapped buffers in client memory. 466 467 [fn: Usually this may only occur with window surfaces which 468 have been mapped. EGL does not have an event mechanism to 469 indicate display mode changes. If such a mechanism exists 470 (using native platform events or the OpenKODE event system), 471 applications should respond to mode changes by regenerating 472 all visible window content, including re-doing any software 473 rendering overlapping the mode change.]" 474 475 Modify table 3.5 ("Queryable surface attributes and types") 476 to add a new column "64-bit". Add new entries to table 3.5: 477 478 Attribute Type Description 64-bit 479 --------- ------- -------------------------- --------- 480 EGL_BITMAP_POINTER_KHR pointer Address of a mapped color [checked] 481 buffer (MCB). 482 EGL_BITMAP_PITCH_KHR integer Number of bytes between - 483 the start of adjacent rows 484 in an MCB. 485 EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction - 486 EGL_BITMAP_PIXEL_x_- integer Bit location of each color - 487 OFFSET_KHR buffer component within a 488 pixel in an MCB. 489 EGL_BITMAP_PIXEL_- integer Bits per pixel - 490 SIZE_KHR 491 492 All previously existing entries in table 3.5 are given a "-" entry in 493 the new "64-bit" column. 494 495 In the description of eglSurfaceAttrib properties that can be set in 496 section 3.5.6, add to the description of EGL_SWAP_BEHAVIOR: 497 498 "It <attribute> is EGL_SWAP_BEHAVIOR ... The value of 499 EGL_SWAP_BEHAVIOR also affects the semantics of eglLockSurfaceKHR 500 for a lockable window surface. See section 3.5.6." 501 502 And modify the paragraph descirbing the initial value of 503 EGL_SWAP_BEHAVIOR: 504 505 "The initial value of EGL_SWAP_BEHAVIOR is chosen by the 506 implementation, except for a lockable window surface (i.e. where the 507 EGLConfig has both EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in 508 EGL_SURFACE_TYPE). For a lockable window surface the default is 509 EGL_BUFFER_PRESERVED, but it may be overridden by specifying 510 EGL_SWAP_BEHAVIOR to eglCreateWindowSurface." 511 512 Add the prototype of the new surface query function immediately 513 following the prototype for eglQuerySurface on p. 37: 514 515 EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, 516 EGLSurface surface, 517 EGLint attribute, 518 EGLAttribKHR *value) 519 520 Modify the following paragraph: 521 522 "eglQuerySurface and eglQuerySurface64KHR return in <value> the 523 value of <attribute> for <surface>. <attribute> must be set to one 524 of the attributes in table 3.5. Attributes whose ``64-bit'' entry 525 is checked in table 3.5 may only be queried with 526 eglQuerySurface64KHR." 527 528 Add to the description of eglQuerySurface properties on p. 38: 529 530 "Properties of a bitmap surface which may be queried include: 531 * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a 532 locked surface and returns the address in client memory of 533 the mapped buffer. 534 * EGL_BITMAP_PITCH_KHR, which returns the number of bytes 535 between successive rows of a mapped buffer. 536 * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a 537 mapped color buffer is displayed on the screen. Possible 538 values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, 539 indicating that the first pixel of the mapped buffer 540 corresponds to the lower left or upper left of a visible 541 window, respectively. 542 * EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit 543 location of the least significant bit of each color 544 component of a pixel within a mapped buffer. <x> is one of 545 RED, GREEN, BLUE, ALPHA, or LUMINANCE. 546 547 The offset for a color component should be treated as the 548 number of bits to left shift the component value to place it 549 within a n-bit 550 integer containing the pixel, where n is the number of bits 551 per pixel. If a color 552 component does not exist in the mapped buffer, then the bit 553 offset of that component is zero. If a color component 554 does exist but not in a single contiguous range of bits, 555 then the value of the attribute is EGL_UNKNOWN. 556 557 * EGL_BITMAP_PIXEL_SIZE_KHR, which returns the number of bits 558 per pixel, assumed to be least significant leftmost if there 559 are multiple pixels per byte. The attribute takes the value 560 EGL_UNKNOWN if this assumption is not true, or if pixels are not 561 laid out left to right in memory (for example pairs of 16-bit 562 pixels are swapped in memory). 563 564 In addition to these attributes, the number of bits for each 565 color component of a pixel within a mapped buffer is obtained by 566 querying the EGL_<x>_SIZE attribute of the EGLConfig used to 567 create the surface, where <x> is <x> is one of RED, GREEN, BLUE, 568 ALPHA, or LUMINANCE. 569 570 Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only 571 allowed when <surface> is mapped (see section 3.5.5ls). Querying 572 either of these attributes for the first time after calling 573 eglLockSurfaceKHR causes the color buffer of the locked surface 574 to be mapped. Querying them again before unlocking the surface 575 will return the same values as the first time. However, after 576 calling eglUnlockSurfaceKHR, these properties become undefined. 577 After a second call to eglLockSurfaceKHR, these properties may 578 again be queried, but their values may have changed. 579 580 Other properties of the mapped color buffer of a surface 581 (in the list above) are 582 invariant, and need be queried only once following surface 583 creation. If <surface> was created with an EGLConfig whose 584 EGL_SURFACE_TYPE attribute does not contain 585 EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR, 586 EGL_BITMAP_PIXEL_<x>_OFFSET_KHR and EGL_BITMAP_PIXEL_SIZE_KHR 587 return undefined values." 588 589 Add to the description of eglQuerySurface errors in the last 590 paragraph of section 3.5.6: 591 592 "eglQuerySurface and eglQuerySurface64KHR return EGL_FALSE on 593 failure ... If <attribute> is one of the attributes whose 594 ``64-bit'' entry is checked in table 3.5, then an 595 EGL_BAD_ATTRIBUTE error is generated if eglQuerySurface is called; 596 only eglQuerySurface64KHR is allowed for such attributes. If 597 <attribute> is either EGL_BITMAP_POINTER_KHR or 598 EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using 599 eglLockSurfaceKHR, or <surface> is locked but mapping fails, then 600 an EGL_BAD_ACCESS error is generated. " 601 602 In section 3.9.3 Posting Semantics on page 53, append to the first 603 paragraph: 604 605 "<surface> must be bound to the calling thread's current context 606 ... This restriction does not apply to lockable surfaces; for such 607 a surface, eglSwapBuffers and eglCopyBuffers may be called for a 608 surface not bound to any client API context(fn). 609 610 [fn: Normally this would only be done when using methods other 611 than client API rendering to specify the color buffer contents, 612 such as software rendering to a locked surface.]" 613 614 Replace the second paragraph ("If <dpy> and <surface> ... not be 615 executed until posting is completed.") with: 616 617 "If <surface> is bound to a current client API context for the calling 618 thread, eglSwapBuffers and eglCopyBuffers perform an implicit flush 619 operation on the context (glFlush for an OpenGL or OpenGL ES context, 620 vgFlush for an OpenVG context). Subsequent client API commands can be 621 issued immediately, but will not be executed until posting is 622 completed. 623 624 If <surface> is current to a client API context in any thread other 625 than the calling thread, eglSwapBuffers and eglCopyBuffers will fail. 626 627 Append following the prototype for eglSwapInterval: 628 629 "specifies the minimum number of video frame periods ... The swap 630 interval has no effect on eglSwapBuffers for a surface not bound 631 to a current client API context." 632 633 In 3.9.4 Posting Errors, change the first paragraph: 634 635 "eglSwapBuffers and eglCopyBuffers return EGL_FALSE on failure. If 636 <surface> is not a valid EGL surface, an EGL_BAD_SURFACE error is 637 generated. If <surface> is bound to a current context in a thread 638 other than the calling thread, an EGL_BAD_SURFACE error is 639 generated." If <target> is not a valid native pixmap handle ..." 640 641Sample Code 642 643 None 644 645Conformance Tests 646 647 None yet 648 649Issues 650 651 The issues lists of EGL_KHR_lock_surface and EGL_KHR_lock_surface2 also 652 apply to this extension. In addition, issues related only to the reason 653 for defining the EGLAttribKHR and interfaces using that type may be 654 found in issues 1-3 of the EGL_KHR_cl_event2 extension specification. 655 656 1) Is this extension backwards-compatible with EGL_KHR_lock_surface2? 657 658 RESOLVED: No. Querying the bitmap pointer must be done with the new 659 command eglQuerySurface64KHR when using this extension, to guide 660 developers down the right path even when writing 32-bit code. 661 662 However, if both lock_surface2 and this extension are supported, it is 663 possible to query the bitmap pointer using older calls, with the risk 664 that executing such code on a 64-bit platform will probably fail. 665 666Revision History 667 668 Version 4, 2014/09/17 (Jon Leech) - Fix bogus return type for 669 eglQuerySurface64KHR in New Functions section. 670 671 Version 3, 20130/12/04 (Jon Leech) - Minor cleanup for public release. 672 Change formal parameter names from 'display' to 'dpy' to match other EGL 673 APIs. 674 675 Version 2, 20130/10/16 (Jon Leech) - add Dependencies and Overview text 676 noting that this extension obsoletes and should replace 677 EGL_KHR_lock_surface2 and EGL_KHR_lock_surface. 678 679 Version 1, 2013/10/15 - Branched from approved EGL_KHR_lock_surface2. 680