Name KHR_lock_surface Name Strings EGL_KHR_lock_surface Contributors Gary King Jon Leech Marko Lukat Tim Renouf Contacts Jon Leech (jon 'at' alumni.caltech.edu) Notice Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status This extension, as well as the layered EGL_KHR_lock_surface2, are obsolete and have been replaced by EGL_KHR_lock_surface3. Khronos recommends implementers who support this extension and lock_surface2 also implement lock_surface3, and begin transitioning developers to using that extension. See issue 17 for the reason. Complete. Version 17 approved by the Khronos Board of Promoters on February 11, 2008. Version Version 19, October 15, 2013 Number EGL Extension #2 Dependencies Requires EGL 1.0 This extension is written against the wording of the EGL 1.3 Specification. Overview This extension allows mapping color buffers of EGL surfaces into the client address space. This is useful primarily for software rendering on low-end devices which do not support EGL client rendering APIs, although it may be implemented efficiently on more capable devices as well. There is a newer EGL_KHR_lock_surface2 extension which slightly modifies and clarifies the semantics of this extension. Vendors should refer to EGL_KHR_lock_surface2 before deciding to implement only EGL_KHR_lock_surface. New Types None New Procedures and Functions EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, const EGLint *attrib_list); EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, EGLSurface surface); New Tokens Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs: EGL_LOCK_SURFACE_BIT_KHR 0x0080 EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100 Accepted as an attribute name in the argument of eglChooseConfig, and the argument of eglGetConfigAttrib: EGL_MATCH_FORMAT_KHR 0x3043 Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute of eglChooseConfig: EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 EGL_FORMAT_RGB_565_KHR 0x30C1 EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 EGL_FORMAT_RGBA_8888_KHR 0x30C3 Accepted as attribute names in the argument of eglLockSurfaceKHR: EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4 EGL_LOCK_USAGE_HINT_KHR 0x30C5 Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute of eglLockSurfaceKHR: EGL_READ_SURFACE_BIT_KHR 0x0001 EGL_WRITE_SURFACE_BIT_KHR 0x0002 Accepted by the parameter of eglQuerySurface: EGL_BITMAP_POINTER_KHR 0x30C6 EGL_BITMAP_PITCH_KHR 0x30C7 EGL_BITMAP_ORIGIN_KHR 0x30C8 EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9 EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD Returns in the * parameter of eglQuerySurface when is EGL_BITMAP_ORIGIN_KHR: EGL_LOWER_LEFT_KHR 0x30CE EGL_UPPER_LEFT_KHR 0x30CF Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation) Add to the end of section 2.2.2: Finally, some surfaces may be , which allows the implementation to map buffers of that surface into client memory for use by software renderers(fn). Locked surfaces cannot be used for any other purpose. When a locked surface is , any changes to the mapped buffer(s) are reflected in the actual graphics or system memory containing the surface. [fn: on implementations not supporting mapping graphics memory, or which do not wish to take the stability and security risks that entail, mapping may be done using copy-out and copy-in behavior.] Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors) Add to the description of the EGL_BAD_ACCESS error in section 3.1: "... or, a surface is locked)." Add to table 3.2 ("Types of surfaces supported by an EGLConfig") EGL Token Name Description -------------------- ------------------------------------ EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal (preferred) when locking / mapping / unlocking is being done. Change the first paragraph under "Other EGLConfig Attribute Descriptions" on p. 16: "EGL_SURFACE_TYPE is a mask indicating both the surface types that can be created by the corresponding EGLConfig (the config is said to those surface types), and the optional behaviors such surfaces may allow. The valid bit settings are shown in Table 3.2." Add a new paragraph following the second paragraph of the same section: "If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE_KHR, then a surface created from the EGLConfig may be locked, mapped into client memory, and unlocked. Locking is described in section 3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in EGL_SURFACE_TYPE_KHR, then the surface is considered optimal (by the implementation) from a performance standpoint when buffer mapping is being done. Replace the second paragraph of section 3.3 "EGL Versioning": "The EGL_CLIENT_APIS string describes which client rendering APIs are supported. It is zero-terminated and contains a space-separated list of API names, which may include ``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if OpenVG is supported. If no client APIs are supported, then the empty string is returned." Insert a new paragraph and table in section 3.4.1 "Querying Configurations", following the description of EGL_MATCH_NATIVE_PIXMAP on page 21: "If EGL_MATCH_FORMAT_KHR is specified in , it must be followed by one of the attribute values EGL_DONT_CARE, EGL_NONE, or one of the format tokens in table [locksurf.format]. When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs which cannot be locked or mapped will match. Such configs must not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE. When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is ignored. When EGL_MATCH_FORMAT_KHR has one of the values in table [locksurf.format], only EGLConfigs describing surfaces whose color buffers have the specified format, when mapped with eglLockSurface, will match this attribute. In this case, the EGL__SIZE attributes of resulting configs must agree with the specific component sizes specified by the format." Specific Format Name Description -------------------- ----------- EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer ------------------------------------------------------------------------------------------------------ Table [locksurf.format]: Specific formats for mapped pixels. Add to table 3.4 ("Default values and match critera for EGLConfig attributes") on page 22: Attribute Default Selection Sort Sort Criteria Order Priority -------------------- ------------- --------- ----- -------- EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None - Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on p. 23, describing attributes not used for sorting EGLConfigs. Add a new section following the current section 3.5.5: "3.5.6 Locking and Mapping Rendering Surfaces A rendering surface may be by calling EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, const EGLint *attrib_list); While a surface is locked, only two operations can be performed on it. First, the color buffer of the surface may be , giving a pointer into client memory corresponding to the memory of the mapped buffer, and attributes describing mapped buffers may be queried. Second, the surface may be unlocked. Any attempts to use a locked surface in other EGL APIs will fail and generate an EGL_BAD_ACCESS error. specifies additional parameters affecting the locking operation. The list has the same structure as described for eglChooseConfig. Attributes that may be defined are shown in table [locksurf.attr], together with their default values if not specified in , and possible values which may be specified for them in . Attribute Name Type Default Value Possible Values ----------------------- ------- ------------- ------------------------- EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR and EGL_WRITE_SURFACE_BIT_KHR -------------------------------------------------------------- Table [locksurf.attr]: eglLockSurfaceKHR attribute names, default values, and possible values. On failure, the surface is unaffected and eglLockSurfaceKHR returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any of these condition, are true: * was created with an EGLConfig whose EGL_SURFACE_TYPE attribute does not contain EGL_LOCK_SURFACE_BIT_KHR. * is already locked. * Any client API is current to . An EGL_BAD_ATTRIBUTE error is generated if an attribute or attribute value not described in table [locksurf.attr] is specified. Mapping Buffers of a Locked Surface ----------------------------------- The color buffer of a locked surface can be by calling eglQuerySurface (see section 3.5.7) with EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a buffer in client memory corresponding to the color buffer of . In the case of a back-buffered surface, color buffer refers to the back buffer [fn: "mapped" only means that the pointer returned is intended to *correspond* to graphics memory. Implementation are not required to return an actual pointer into graphics memory, and often will not.] The contents of the mapped buffer are initially undefined(fn) unless the EGL_MAP_PRESERVE_PIXELS_KHR attribute of eglLockSurfaceKHR is set to EGL_TRUE, in which case the contents of the buffer are taken from the contents of 's color buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is EGL_FALSE. [fn: In order to avoid pipeline stalls and readback delays on accelerated implementations, we do not mandate that the current contents of a color buffer appear when it's mapped to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR flag is set. Applications using mapped buffers which are not preserved must write to every pixel of the buffer before unlocking the surface. This constraint is considered acceptable for the intended usage scenario (full-frame software renderers).] The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a bitmask describing the intended use of the mapped buffer. If the mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from the mapped buffer. If the mask contains EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped buffer. Implementations must support both reading and writing to a mapped buffer regardless of the value of EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the hint is consistent with the actual usage of the buffer. The default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads and writes to the mapped buffer will be done. Other attributes of the mapped buffer describe the format of pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR), origin, pixel size, and the bit width and location of each color component within a pixel. These attributes may be queried using eglQuerySurface, and are described in more detail in section 3.5.7. The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes of a locked surface may change following successive calls to eglLockSurfaceKHR(fn), so they must be queried each time a buffer is mapped. Other attributes of a mapped buffer are invariant and need be queried only once following surface creation. [fn: The pointer and pitch of a mapped buffer may change due to display mode changes, for example.] Mapping will not suceed if client memory to map the surface into cannot be allocated. In this case, querying eglQuerySurface with EGL_BITMAP_POINTER_KHR will fail and generate an EGL error. Unlocking Surfaces ------------------ A rendering surface may be by calling EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, EGLSurface surface); Any mapped buffers of become unmapped following eglUnlockSurfaceKHR. Any changes made to mapped buffers of which it was locked are reflected in the surface after unlocking(fn). [fn: This language enables implementations to either map video memory, or copy from a separate buffer in client memory.] If was created with an EGLConfig whose EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR, then the surface is considered optimal (by the implementation) from a performance standpoint when buffer mapping is being done(fn). [fn: This often means that the format of all mapped buffers corresponds directly to the format of those buffers in , so no format conversions are required during unmapping. This results in a high-performance software rendering path. But "optimal format" is really just a hint from EGL that this config is preferred, whatever the actual reason.] On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any of these conditions are true: * is already unlocked. * A display mode change occurred while the surface was locked, and the implementation was unable to reflect mapped buffer state(fn). In this case, will still be unlocked. However, the contents of the previously mapped buffers of become undefined, rather than reflecting changes made in the mapped buffers in client memory. [fn: Usually this may only occur with window surfaces which have been mapped. EGL does not have an event mechanism to indicate display mode changes. If such a mechanism exists (using native platform events or the OpenKODE event system), applications should respond to mode changes by regenerating all visible window content, including re-doing any software rendering overlapping the mode change.]" Add to table 3.5 ("Queryable surface attributes and types") Attribute Type Description --------- ---- ----------- EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB). EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of adjacent rows in an MCB. EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer component within a pixel in an MCB. Add to the description of eglQuerySurface properties in section 3.5.6 (renumbered to 3.5.7) on page 33: "Properties of a bitmap surface which may be queried include: * EGL_BITMAP_POINTER_KHR, which maps the color buffer of a locked surface and returns the address in client memory of the mapped buffer. * EGL_BITMAP_PITCH_KHR, which returns the number of bytes between successive rows of a mapped buffer. * EGL_BITMAP_ORIGIN_KHR, which describes the way in which a mapped color buffer is displayed on the screen. Possible values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR, indicating that the first pixel of the mapped buffer corresponds to the lower left or upper left of a visible window, respectively. * EGL_BITMAP_PIXEL__OFFSET_KHR, which describes the bit location of the least significant bit of each color component of a pixel within a mapped buffer. is one of RED, GREEN, BLUE, ALPHA, or LUMINANCE. The offset for a color component should be treated as the number of bits to left shift the component value to place it within a 16- (for RGB565 formats) or 32-bit (for RGBA8888 formats) integer containing the pixel(fn). If a color component does not exist in the mapped buffer, then the bit offset of that component is zero. In addition to these attributes, the number of bits for each color component of a pixel within a mapped buffer is obtained by querying the EGL__SIZE attribute of the EGLConfig used to create the surface, where is is one of RED, GREEN, BLUE, ALPHA, or LUMINANCE. The size of a pixel in the mapped buffer, in bytes, can be determined by querying the EGL_BUFFER_SIZE attribute of the EGLConfig, rounding up to the nearest multiple of 8, and converting from bits to bytes. Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only allowed when is mapped (see section 3.5.6). Querying either of these attributes for the first time after calling eglLockSurfaceKHR causes the color buffer of the locked surface to be mapped. Querying them again before unlocking the surface will return the same values as the first time. However, after calling eglUnlockSurfaceKHR, these properties become undefined. After a second call to eglLockSurfaceKHR, these properties may again be queried, but their values may have changed. Other properties of the mapped color buffer of a surface are invariant, and need be queried only once following surface creation. If was created with an EGLConfig whose EGL_SURFACE_TYPE attribute does not contain EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR and EGL_BITMAP_PIXEL__OFFSET_KHR return undefined values." Add to the description of eglQuerySurface errors in the last paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34: "... If is either EGL_BITMAP_POINTER_KHR or EGL_BITMAP_PITCH_KHR, and either is not locked using eglLockSurfaceKHR, or is locked but mapping fails, then an EGL_BAD_ACCESS error is generated." Issues 1) What is the rationale for this extension? Software renderers on low-end implementations need an efficient way to draw pixel data to the screen. High-end implementations must support the same interface for compatibility, while not compromising the accelerability of OpenGL ES and OpenVG client APIs using dedicated graphics hardware and memory. Using lock/unlock semantics enables low-end implementations to expose pointers directly into display memory (as extremely dangerous as that may be), while high-end implementations may choose to create backing store in client memory when mapping a buffer, and copy it to graphics memory when the surface is unlocked. Making the initial contents of a mapped buffer undefined means that no readbacks from graphics memory are required, avoiding pipeline stalls. This extension is not intended to support mixed-mode (client API and software) rendering. Since mapped buffer contents are undefined, unless the buffer is explicitly preserved (which may be unacceptably expensive on many implementations), applications doing software rendering must touch every pixel of mapped buffers at least once before unlocking the surface. 2) Do we need to know if locked surfaces are "fast" or "native"? RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR of EGL_SURFACE_TYPE. However, note that there is no way to guarantee what "fast" or "no format conversions" really means; this is little more than an implementation hint. 3) Should we be able to map buffers other than the color buffer? RESOLVED: Not initially. However, the parameter of eglLockSurfaceKHR supports this in the future. There is no attribute to eglQuerySurface, so such a layered extension would have to either create a new naming convention (such as EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an extended query eglQuerySurfaceBuffer() which takes a parameter. It would also be tricky to support interleaved depth / stencil formats. But the attribute list offers some future-proofing at low cost. 4) What properties of mapped buffers can be queried? RESOLVED: A pointer to the buffer and its pitch, both of which may change in successive lock/unlock cycles. These may be queried only while the underlying surface is locked, and are undefined after unlocking. The first query following locking is the point at which actual buffer mapping must occur. RESOLVED: Additionally, the pixel size, origin, and color component bitfield size and offset for each component, which are invariant and may be queried at any time. 5) How are mode changes indicated? What happens to the mapped buffer during a mode change? RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode change occurred while the surface was locked (although the surface still ends up in the unlocked state - this is necessary since there's no way to clear the error!). If a mode change occurs while a buffer is mapped, the implementation must still allow the application to access mapped buffer memory, even though the contents of the mapped buffer may not be reflected in the changed window after unmapping. Note: There's no convenient way to indicate mode changes while a surface is unlocked, despite that being useful to tell apps they have to redraw. The problem is that we don't have an event system, and the power management functionality is overkill since the only resources which are likely to be damaged by a mode change are visible window contents. Fortunately, this problem is beyond the scope of this extension. 6) Does locking a surface imply mapping its buffers? RESOLVED: No. Locking simply places the surface in that state and prevents it from being made current / swapped / etc. Buffers are mapped only when their pointers or pitch are queried using eglQuerySurface. An interesting side effect of this resolution is that calling eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped. Likewise locking a surface, querying a buffer pointer or pitch, and then unlocking it without changing the mapped buffer contents causes the surface contents of the mapper buffer(s) to become undefined. At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR should immediately map the color buffer and return a pointer to it, on the basis that this would make it harder for applications to mistakenly use an old buffer pointer from a previous mapping cycle. At the same time, people working on more powerful GPUs wanted the lock operation to be lightweight. These are not consistent goals and we have thus far chosen to separate the lightweight locking, and more expensive mapping operations. 7) Can buffer contents be preserved in mapping? RESOLVED: Yes. The default behavior is to discard / leave undefined the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag may be specified to eglLockSurfaceKHR. 8) Should usage hints be provided during mapping? RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute to eglLockSurfaceKHR. Implementations are required to behave correctly no matter the value of the flag vs. the operations actually performed, so the hint may be ignored. 9) Should we be able to lock subrectangles of a surface? RESOLVED: No. However, the attribute list parameter of eglLockSurfaceKHR allows a layered extension to implement this behavior by specifying an origin and size to map within the buffer. 10) Should the BITMAP_PIXEL__OFFSET attributes belong to the surface, or the config? RESOLVED: Part of the surface. Configs supporting a specific format are matched with config attribute EGL_MATCH_FORMAT_KHR, which supports specific bit-exact formats such as EGL_FORMAT_565_EXACT_KHR. 11) Can the pixel size in a mapped buffer be derived from the EGL_BUFFER_SIZE attribute of the config used to create it? RESOLVED: Yes. In principle, hardware using padding bytes in its framebuffer storage could be a problem, and a separate BITMAP_PIXEL_SIZE surface attribute would be needed. However, we don't think implementations are likely to waste graphics memory and bandwidth in this fashion. 12) How are color component locations within a pixel described? RESOLVED: Each R, G, B, and A component has a queryable bit offset within an integer. The size of the integer depends on the total size of the pixel; for the 565 formats, the pixel is a 16-bit integer. For the 8888 formats, the pixel is a 32-bit integer. We cannot describe component locations with byte locations, since the 565 formats have components straddling byte boundaries. However, this means that offsets for the RGBA8888_EXACT format are different between little- and big-endian CPUs, since the desired format is B, G, R, A components laid out as bytes in increasing memory order. 13) Can mapped buffer contents be affected by other EGL operations? RESOLVED: No. A locked surface only allows two operations: unlocking, and mapping. No other EGL operations can take place while the surface is locked (if this were not the case, then eglSwapBuffers might destroy the contents of a mapped buffer). It is possible that operations outside the scope of EGL could affect a mapped color buffer. For example, if a surface's color buffer were made up of an EGLImage, one of the EGL client APIs could draw to that image while it was mapped. Responsibility for avoiding this situation is in the hands of the client. 14) Can EGL_MATCH_FORMAT_KHR be queried for a config? RESOLVED: Yes. Unlockable configs return EGL_NONE for this attribute. 15) Is a goal of this extension to support "mixed-mode" rendering (both software and EGL client API rendering to the same surface)? RESOLVED: No. An implementation *can* choose to export configs supporting creation of lockable surfaces which also support rendering by OpenGL ES, OpenVG, or other client APIs (when the surface is not locked). But there is nothing in the extension requiring this, and the motivation for the extension is simply to support software rendering. 16) Can mapping a locked surface fail? RESOLVED: Yes, if memory can't be allocated in the client. This is indicated by queries of EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error. 17) Why has this extension been obsoleted and replaced by EGL_KHR_lock_surface3? RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint is defined to be the same size as the native platform "int" type. Handle and pointer attribute values *cannot* be represented in attribute lists on platforms where sizeof(handle/pointer) > sizeof(int). Existing extensions which assume this functionality are being replaced with new extensions specifying new entry points to work around this issue. See the latest EGL 1.4 Specification for more details. Revision History Version 19, 2013/10/15 - Add issue 17 explaining that the bitmap pointer cannot be safely queried using this extension on 64-bit platforms, and suggest EGL_KHR_lock_surface3 instead. Change formal parameter names from 'display' to 'dpy' to match other EGL APIs. Version 18, 2010/03/23 - Added introductory remark referring to the EGL_KHR_lock_surface2 extension. Clarified that it is the back buffer of a back-buffered surface that is mapped. Version 17, 2008/10/08 - Updated status (approved as part of OpenKODE 1.0). Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail, and a corresponding new error condition for eglQuerySurface. Clean up the issues list. Version 15, 2008/01/09 - Add issue 15 noting that supporting mixed-mode rendering is not a goal or requirement of the extension. Version 14, 2007/11/07 - change ARGB_8888_EXACT back to RGBA_8888_EXACT, since the offsets are now dependent on the endianness of the CPU. Add issue 12 describing this, and clarify that offsets are within a 16- or 32-bit integer depending on the format. Added issue 13 clarifying that locked buffer contents are not affected by eglSwapBuffers, because eglSwapBuffers cannot be issued on a mapped surface. Allow querying EGL_MATCH_FORMAT_KHR for a config, and added related issue 14. Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT to match hardware layout. Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is EGL_DONT_CARE, it does not affect component size of selected configs. Version 11, 2007/04/05 - add missing KHR suffix to some tokens. Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0 Provisional disclaimer. Version 9, 2007/03/26 - add format tokens to "New Tokens" section. Correct description of RGBA format tokens. Version 8, 2007/03/26 - add issue 11 noting theoretical possibility of EGL_BUFFER_SIZE not directly corresponding to the mapped pixel size. Add EGL_MATCH_FORMAT_KHR attribute to eglChooseConfig, and 565 / 8888 formats for it. Version 7, 2007/03/25 - note in issue 5 that access to a mapped buffer must continue to work even after a mode change. Add KHR suffix to new functions and tokens. Remove BITMAP_PIXEL__BITS and BITMAP_PIXEL_SIZE tokens, which duplicate information in the EGLConfig. Add issue 10 asking whether bitmap pixel offset attributes belong to the config, or to the surface. Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in implementations supporting only this extension. Version 5, 2007/02/05 - update contributor list. Changed bit offset queries to return LSB offset, rather than MSB offset. Version 4, 2007/02/02 - correct extension name. Change name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR. Replace buffer_mask parameter of eglLockSurfaceKHR with an attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues 7, 8, and 9 describing these attributes and how to support locking subrects in a layered extension, by extending the attribute list. Version 3, 2007/02/01 - the implementation once again controls the mapped buffer memory. There is no longer a separate bitmap surface type; any type surface may potentially be mapped, using lock/unlock semantics. Version 2, 2006/12/22 - simplify by only supporting drawing from client memory to EGL surface color buffers. Specify use of OpenGL DrawPixels terminology. Change name of the extension to EGL_KHR_draw_pixels, since there is no longer any "bitmap surface" involved. Version 1, 2006/12/14 - write up as formal spec language for external review.