| Name |
| |
| KHR_lock_surface2 |
| |
| Name Strings |
| |
| EGL_KHR_lock_surface2 |
| |
| Contributors |
| |
| Mark Callow |
| Gary King |
| Jon Leech |
| Marko Lukat |
| Alon Or-bach |
| 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 is obsolete and has been replaced by |
| EGL_KHR_lock_surface3. Khronos recommends implementers who support this |
| extension also implement lock_surface3, and begin transitioning |
| developers to using that extension. See issue 21 for the reason. |
| |
| Complete. Version 2 approved by the Khronos Board of Promoters on |
| May 28, 2010. |
| Implemented by Antix Labs. |
| |
| Version |
| |
| Version 3, December 4, 2013 |
| |
| Number |
| |
| EGL Extension #16 |
| |
| Dependencies |
| |
| Requires EGL 1.0 and EGL_KHR_lock_surface version 18. |
| |
| This extension is written against the wording of the EGL 1.3 |
| and EGL 1.4 Specifications. Unless otherwise specified, each change |
| applies to both specifications. Unless otherwise specified, a page |
| number refers to the EGL 1.3 specification. |
| |
| This extension is written against the wording of EGL_KHR_lock_surface |
| version 18. |
| |
| Overview |
| |
| This extension slightly modifies and clarifies some semantic aspects |
| of the EGL_KHR_lock_surface extension, in a way that is backwards |
| compatible for applications. |
| |
| The extension is presented here as the full text of the |
| EGL_KHR_lock_surface extension (minus the Status, Version, Number and |
| Dependencies sections at the start) as modified by the changes made by |
| this EGL_KHR_lock_surface2 extension. A diff utility can be used between |
| EGL_KHR_lock_surface version 18 and this EGL_KHR_lock_surface2 extension |
| to show the exact changes. |
| |
| An application which needs to tell whether the implementation supports |
| EGL_KHR_lock_surface2, or just the original EGL_KHR_lock_surface, can |
| use eglQueryString with EGL_EXTENSIONS to query the list of |
| implemented extensions. |
| |
| The changes over EGL_KHR_lock_surface can be summarized as follows: |
| |
| * EGL_KHR_lock_surface had the EGL_MAP_PRESERVE_PIXELS_KHR attribute on |
| eglLockSurfaceKHR, but failed to point out how the surface attribute |
| EGL_SWAP_BEHAVIOR would interact with lock surface rendering. |
| EGL_KHR_lock_surface2 specifies that the locked buffer contains the |
| back buffer pixels if EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED |
| _or_ if EGL_MAP_PRESERVE_PIXELS_KHR is EGL_TRUE, and provides a way to |
| set EGL_SWAP_BEHAVIOR on creation of a lockable window surface, |
| even if EGL_SWAP_BEHAVIOR is not otherwise modifiable. |
| EGL_SWAP_BEHAVIOR now defaults to EGL_BUFFER_PRESERVED for a |
| lockable surface. |
| |
| * EGL_KHR_lock_surface failed to specify its interaction with the |
| EGL requirement that a context be current at eglSwapBuffers; no |
| context is used for lock surface rendering. EGL_KHR_lock_surface2 |
| relaxes that requirement for a lockable window surface, in a way |
| that is anticipated to apply to all window surfaces in a future |
| version of EGL. |
| |
| * Wording in EGL_KHR_lock_surface could be read to imply that almost |
| all surface attributes are invariant for a lockable surface. |
| EGL_KHR_lock_surface2 clarifies the wording. |
| |
| * EGL_KHR_lock_surface2 clarifies what is returned when |
| the attribute EGL_MATCH_FORMAT_KHR is queried, especially when |
| one of the "inexact" formats was used to choose the config. |
| |
| * EGL_KHR_lock_surface did not specify when a surface could change size. |
| EGL_KHR_lock_surface2 specifies that a surface cannot change size |
| when it is locked. |
| |
| * EGL_KHR_lock_surface2 adds the config attribute |
| EGL_BITMAP_PIXEL_SIZE_KHR, to allow an application to dynamically |
| detect pixel layout for a format with a "hole", such as RGBU8888 |
| (where "U" means "unused"). |
| |
| New Tokens |
| |
| Accepted by the <attribute> parameter of eglQuerySurface: |
| |
| EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 |
| |
| Full text of EGL_KHR_lock_surface plus EGL_KHR_lock_surface2: |
| |
| 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. |
| |
| 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 <attrib_list> argument of |
| eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib: |
| |
| EGL_MATCH_FORMAT_KHR 0x3043 |
| |
| Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute |
| of eglChooseConfig, and defined as possible values of that attribute |
| when querying it: |
| |
| EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0 |
| EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2 |
| |
| Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute |
| of eglChooseConfig: |
| |
| EGL_FORMAT_RGB_565_KHR 0x30C1 |
| EGL_FORMAT_RGBA_8888_KHR 0x30C3 |
| |
| Accepted as attribute names in the <attrib_list> 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 <attribute> 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 |
| EGL_BITMAP_PIXEL_SIZE_KHR 0x3110 |
| |
| Returns in the *<value> parameter of eglQuerySurface when |
| <attribute> 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 <locked>, 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 <unlocked>, |
| 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 <support> 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, 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, 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 <attrib_list>, 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_<component>_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 paragraph to the end of section 3.4.3 "Querying Configuration |
| Attributes": |
| |
| "Querying the EGL_MATCH_FORMAT_KHR attribute results in EGL_NONE |
| for an EGLConfig that is not lockable, one of the "exact" formats |
| (EGL_FORMAT_RGB_565_EXACT_KHR, EGL_FORMAT_RGBA_8888_EXACT_KHR) |
| if the color buffer matches that format when mapped with |
| eglLockSurface, or for any other format a value that is not |
| EGL_NONE or EGL_DONT_CARE but is otherwise undefined. In particular, |
| the color buffer format matching one of the "inexact" formats |
| does not guarantee that that EGL_FORMAT_* value is returned." |
| |
| In section 3.5.1 "Creating On-Screen Rendering Surfaces", add the |
| following to the paragraph that lists the attributes that can be set |
| in attrib_list: |
| |
| "... and EGL_SWAP_BEHAVIOR." |
| |
| and add a new penultimate paragraph: |
| |
| "EGL_SWAP_BEHAVIOR specifies the initial value of the |
| EGL_SWAP_BEHAVIOR surface attribute (section 3.5.6), and is thus |
| either EGL_BUFFER_PRESERVED or EGL_BUFFER_DESTROYED. This setting |
| of EGL_SWAP_BEHAVIOR at surface creation time is supported only |
| for a lockable surface, i.e. where the EGLConfig has |
| EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE." |
| |
| In EGL 1.4, also add the following text to that same paragraph: |
| |
| "For such a lockable surface, whether it is possible to change |
| the EGL_SWAP_BEHAVIOR attribute after surface creation is |
| determined by EGL_SWAP_BEHAVIOR_PRESERVED_BIT in the |
| EGL_SURFACE_TYPE EGLConfig attribute." |
| |
| Add a new section following the current section 3.5.5: |
| |
| "3.5.6 Locking and Mapping Rendering Surfaces |
| |
| A rendering surface may be <locked> 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, a surface attribute may be queried using |
| eglQuerySurface. This includes the case of querying |
| EGL_BITMAP_POINTER_KHR, which causes the surface to be |
| <mapped> (if not already mapped) and gives |
| a pointer into client memory corresponding to the memory |
| of the mapped buffer. 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. |
| |
| While a surface is locked, its dimensions (the values of the EGL_WIDTH |
| and EGL_HEIGHT surface attributes) do not change. They may change |
| at any other time, therefore an application must query these |
| attributes <after> the call to eglLockSurfaceKHR to ensure that it has |
| the correct size of the mapped buffer. |
| |
| <attrib_list> 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 <attrib_list>, and possible values which may be specified for |
| them in <attrib_list>. |
| |
| 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: |
| |
| * <surface> was created with an EGLConfig whose |
| EGL_SURFACE_TYPE attribute does not contain |
| EGL_LOCK_SURFACE_BIT_KHR. |
| * <surface> is already locked. |
| * Any client API is current to <surface>. |
| |
| 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 <mapped> by calling |
| eglQuerySurface (see section 3.5.7) with <attribute> |
| EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a |
| buffer in client memory corresponding to the color buffer of |
| <surface>. 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 either the EGL_MAP_PRESERVE_PIXELS_KHR attribute of |
| eglLockSurfaceKHR is set to EGL_TRUE, or (for a window surface) |
| the EGL_SWAP_BEHAVIOR surface attribute is set to |
| EGL_BUFFER_PRESERVE, in which case the contents |
| of the buffer are taken from the contents of <surface>'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 or (for a window surface) EGL_SWAP_BEHAVIOR is |
| set to EGL_BUFFER_PRESERVE. 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). Such an application may lock-render-unlock |
| multiple times per frame (i.e. per eglSwapBuffers) by setting |
| EGL_MAP_PRESERVE_PIXELS_KHR to EGL_TRUE for the second and |
| subsequent locks. |
| |
| Note that EGL_SWAP_BEHAVIOR also controls whether the color |
| buffer contents are preserved over a call to eglSwapBuffers.] |
| |
| 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 (EGL_BITMAP_ORIGIN_KHR), and the bit location of each color |
| component within a pixel (EGL_BITMAP_PIXEL_x_OFFSET_KHR). 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 (listed in |
| the paragraph above) 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 |
| <attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL |
| error. |
| |
| Unlocking Surfaces |
| ------------------ |
| |
| A rendering surface may be <unlocked> by calling |
| |
| EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, |
| EGLSurface surface); |
| |
| Any mapped buffers of <surface> become unmapped following |
| eglUnlockSurfaceKHR. Any changes made to mapped buffers of |
| <surface> 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 <surface> 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 |
| <surface>, 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: |
| |
| * <surface> 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, <surface> will still be unlocked. |
| However, the contents of the previously mapped buffers of |
| <surface> 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. |
| EGL_BITMAP_PIXEL_SIZE_KHR integer Bits per pixel |
| |
| In EGL 1.4 only, in the description of eglSurfaceAttrib properties |
| that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, |
| add to the first paragraph describing EGL_SWAP_BEHAVIOR: |
| |
| "The value of EGL_SWAP_BEHAVIOR also affects the semantics of |
| eglLockSurfaceKHR for a lockable window surface. See section 3.5.6." |
| |
| In EGL 1.4 only, in the description of eglSurfaceAttrib properties |
| that can be set in section 3.5.6 (renumbered to 3.5.7), on page 35, |
| change the paragraph concerning the initial value of EGL_SWAP_BEHAVIOR |
| to: |
| |
| "The initial value of EGL_SWAP_BEHAVIOR is chosen by the |
| implementation, except for a lockable window surface (i.e. where the |
| EGLConfig has both EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in |
| EGL_SURFACE_TYPE), where the default is EGL_BUFFER_PRESERVED, but it |
| may be overridden by specifying EGL_SWAP_BEHAVIOR to |
| eglCreateWindowSurface." |
| |
| In EGL 1.3 only, in the description of eglQuerySurface properties |
| that can be queried in section 3.5.6 (renumbered to 3.5.7), on page 33, |
| add to the paragraph describing EGL_SWAP_BEHAVIOR: |
| |
| "The value of EGL_SWAP_BEHAVIOR also affects the semantics of |
| eglLockSurfaceKHR for a lockable window surface. See section 3.5.6. |
| For a lockable window surface (one whose EGLConfig has both |
| EGL_LOCK_SURFACE_BIT_KHR and EGL_WINDOW_BIT set in EGL_SURFACE_TYPE), |
| the value of this attribute may be set in the eglCreateWindowSurface |
| call, and if not set there defaults to EGL_BUFFER_PRESERVED. See |
| section 3.5.1. The default for a non-lockable surface is chosen by the |
| implementation." |
| |
| 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_<x>_OFFSET_KHR, which describes the bit |
| location of the least significant bit of each color |
| component of a pixel within a mapped buffer. <x> 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 n-bit |
| integer containing the pixel, where n is the number of bits |
| per pixel. If a color |
| component does not exist in the mapped buffer, then the bit |
| offset of that component is zero. If a color component |
| does exist but not in a single contiguous range of bits, |
| then the value of the attribute is EGL_UNKNOWN. |
| |
| * EGL_BITMAP_PIXEL_SIZE_KHR, which returns the number of bits |
| per pixel, assumed to be least significant leftmost if there |
| are multiple pixels per byte. The attribute takes the value |
| EGL_UNKNOWN if this assumption is not true, or if pixels are not |
| laid out left to right in memory (for example pairs of 16-bit |
| pixels are swapped in memory). |
| |
| 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_<x>_SIZE attribute of the EGLConfig used to |
| create the surface, where <x> is <x> is one of RED, GREEN, BLUE, |
| ALPHA, or LUMINANCE. |
| |
| Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only |
| allowed when <surface> 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 |
| (in the list above) are |
| invariant, and need be queried only once following surface |
| creation. If <surface> was created with an EGLConfig whose |
| EGL_SURFACE_TYPE attribute does not contain |
| EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR, |
| EGL_BITMAP_PIXEL_<x>_OFFSET_KHR and EGL_BITMAP_PIXEL_SIZE_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 <attribute> is either EGL_BITMAP_POINTER_KHR or |
| EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using |
| eglLockSurfaceKHR, or <surface> is locked but mapping fails, |
| then an EGL_BAD_ACCESS error is generated." |
| |
| In section 3.9.3 Posting Semantics on page 46, append to the first |
| paragraph: |
| |
| "This restriction does not apply to lockable surfaces; for such |
| a surface, eglSwapBuffers and eglCopyBuffers may be called for |
| a surface not bound to any client API context(fn). |
| |
| [fn: Normally this would only be done when using methods other |
| than client API rendering to specify the color buffer contents, |
| such as software rendering to a locked surface.]" |
| |
| and replace the second paragraph ("If <dpy> and <surface> ... not be |
| executed until posting is completed.") with: |
| |
| "If <surface> is bound to a current client API context for the calling |
| thread, eglSwapBuffers and eglCopyBuffers perform an implicit flush |
| operation on the context (glFlush for an OpenGL or OpenGL ES context, |
| vgFlush for an OpenVG context). Subsequent client API commands can be |
| issued immediately, but will not be executed until posting is |
| completed. |
| |
| If <surface> is current to a client API context in any thread other |
| than the calling thread, eglSwapBuffers and eglCopyBuffers will fail. |
| |
| and append the following sentence to the eglSwapInterval paragraph: |
| |
| "The swap interval has no effect on an eglSwapBuffers for a surface |
| not bound to a current client API context." |
| |
| In 3.9.4 Posting Errors, change the sentence "If <surface> is not bound |
| to the calling thread's current context, an EGL_BAD_SURFACE error is |
| generated." to: |
| |
| "If <surface> is bound to a current context in a thread other |
| than the calling thread, an EGL_BAD_SURFACE 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 <attrib_list> parameter of |
| eglLockSurfaceKHR supports this in the future. There is no <buffer> |
| 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 <buffer> |
| 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_<component>_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. |
| |
| For a config whose format matches one of the EGL_FORMAT_*_EXACT_KHR |
| definitions, that value is returned. |
| |
| For a config whose format does not match one of the |
| EGL_FORMAT_*_EXACT_KHR definitions, but it does match one of the |
| inexact definitions, we do not want to specify that it returns that |
| value, since that precludes it returning an exact format if one were |
| to be defined in a future extension, or a future version of this |
| extension. |
| |
| Therefore, for a config whose format does not match a defined |
| "exact" format, the attribute returns a value other than the defined |
| "exact" formats and EGL_NONE and EGL_DONT_CARE. |
| |
| 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) How does the application specify that it would like the pixels in the |
| mapped buffer to be preserved from the state at the last unlock? |
| [Bug 4410] |
| |
| There are actually two items that need to be configurable: |
| |
| a. Whether eglSwapBuffers preserves the color buffer. |
| |
| b. Whether eglLockSurfaceKHR puts the color buffer pixels into the |
| locked buffer. |
| |
| An implementation may use two different render paths depending on whether |
| the application is full frame rendering or incrementally rendering, where |
| the full frame rendering path may involve less copying than the |
| incrementally rendering path. The implementation needs to know in advance |
| which path to use; finding out from EGL_MAP_PRESERVE_PIXELS_KHR on |
| eglLockSurfaceKHR whether that lock should have the color buffer pixels |
| from the last eglUnlockSurfaceKHR in the last frame is too late. |
| |
| This need to know in advance only applies to (a). |
| |
| Note that the original EGL_KHR_lock_surface extension failed to state |
| that EGL_SWAP_BEHAVIOR needed to be set to EGL_BUFFER_PRESERVED for |
| incremental rendering. |
| |
| RESOLVED: EGL_MAP_PRESERVE_PIXELS_KHR continues to control (b), as in the |
| original EGL_KHR_lock_surface extension. EGL_SWAP_BEHAVIOR continues |
| to control (a), as in unextended EGL. It is possible to set |
| EGL_SWAP_BEHAVIOR in eglCreateWindowSurface, even on EGL versions |
| before 1.4, and even if the config does not have |
| EGL_SWAP_BEHAVIOR_PRESERVED_BIT set in EGL_SURFACE_TYPE. |
| |
| For a lockable window surface, EGL_SWAP_BEHAVIOR needs to default to |
| EGL_BUFFER_PRESERVED, and having EGL_SWAP_BEHAVIOR set to |
| EGL_BUFFER_PRESERVED needs to override EGL_MAP_PRESERVE_PIXELS_KHR. This is for |
| compatibility with version 1 of this extension, which had EGL_SWAP_BEHAVIOR |
| as the sole means of controlling (a) and (b). |
| |
| This resolution is backward compatible with the original |
| EGL_KHR_lock_surface extension as it now defaults to preserving pixels, |
| and thus has that default for an old application that does not know about |
| setting EGL_SWAP_BEHAVIOR=EGL_BUFFER_DESTROYED to optimize full frame |
| rendering. The downside is a possible performance reduction of an old |
| application that does not want pixels preserved, until it is appropriately |
| modified and recompiled. |
| |
| 18) When can a lockable surface change size? [Bug 4522] |
| |
| RESOLVED: The surface cannot change size while it is locked. For any |
| window size change during that time, EGL defers the corresponding |
| surface size change until some time after the unlock. |
| The implication is that an application must get the surface size |
| _after_locking, otherwise the size may have changed in between the |
| attribute query and the lock. |
| |
| As part of this change, using eglQuerySurface on any surface attribute |
| while the surface is locked has been allowed. |
| |
| 19) Should we provide for more than one pixel per byte, or a format with |
| a "hole", or a byte-swapped 16-bit format? [Bug 4513] |
| |
| For the use case where the application uses EGL_FORMAT_* to |
| determine the pixel format, this is not an issue. For the use case |
| where the application is written to cope with any format by reading |
| the EGL_BITMAP_* attributes and adjusting its rendering at runtime, |
| this is an issue. |
| |
| RESOLVED: We add a new attribute EGL_BITMAP_PIXEL_SIZE_KHR which gives |
| the pixel size in bits. |
| The use of this attribute assumes that multiple pixels packed into |
| a byte are arranged least significant on the left, and that pixels |
| are arranged leftmost first in memory. If either of these assumptions |
| is false, then EGL_BITMAP_PIXEL_SIZE_KHR is EGL_UNKNOWN to indicate |
| that an application attempting to use these attributes to adjust its |
| rendering code will not work. |
| |
| We also define that any of the EGL_BITMAP_PIXEL_x_OFFSET_KHR attributes |
| have a value of EGL_UNKNOWN if the corresponding color component is not |
| a contiguous bit range. |
| |
| 20) EGL states that surface must be bound to the thread's current context |
| when posting, but there is no current context when using lock surface. |
| eglSwapInterval is also related to the context. [Bug 5923] |
| |
| RESOLVED: The posting restrictions are relaxed, so it is allowed to |
| post for a surface not bound to any client API context. In this case |
| no eglSwapInterval setting affects an eglSwapBuffers. This relaxation |
| only applies to a lockable surface so that this extension continues |
| to be implementable as a middleware layer on top of a "real" EGL. |
| The relaxation applies to a surface that is both lockable and client |
| API renderable; the implicit flush in a post only occurs when the surface |
| is bound to a current API context. Posting a surface bound to a different |
| thread's current API context is still disallowed. |
| |
| 21) 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 3, 2013/12/04 - Add issue 21 explaining that the bitmap pointer |
| cannot be safely queried using this extension on 64-bit platforms, |
| and suggesting EGL_KHR_lock_surface3 instead. Change formal |
| parameter names from 'display' to 'dpy' to match other EGL APIs. |
| Version 2, 2010/03/10 |
| Allocated extension number 16. |
| [Bug 6089] Clarified that it is the back buffer of a back-buffered |
| surface that is mapped. |
| [Bug 4410] Issue 17: Reinstate EGL_MAP_PRESERVE_PIXELS_KHR attribute on |
| eglLockSurfaceKHR as the means of configuring whether a locked |
| buffer contains pixel data from the color buffer, as in |
| EGL_KHR_lock_surface, but, for a lockable window surface, |
| make EGL_SWAP_BEHAVIOR=EGL_BUFFER_PRESERVED override the effect |
| of that attribute. Tidy wording so that behavior, and that the |
| default of EGL_SWAP_BEHAVIOR must be EGL_BUFFER_PRESERVED, only |
| applies to lockable window surfaces, not lockable pbuffer or |
| pixmap surfaces. |
| [Bug 5923] Issue 20: A config that is lockable and renderable by |
| an EGL client API is now allowed. Posting restrictions are relaxed |
| to allow posting for a lockable surface not bound to any client |
| API context. |
| [Bug 5143] Fixed typos EGL_SURFACE_TYPE_KHR. Added summary of |
| changes over EGL_KHR_lock_surface. |
| Version 1, 2010/01/19 |
| [Bug 4410] Issue 17: Change to use EGL_SWAP_BEHAVIOR as the |
| primary means of determining whether the application wants pixels |
| preserved between lock/unlock cycles. |
| Allowed setting of EGL_SWAP_BEHAVIOR in |
| eglCreateWindowSurface for a lockable surface. Made the |
| default EGL_BUFFER_PRESERVED on a lockable surface to maintain |
| compatibility with the original lock surface extension. |
| [Bug 3192] Wording clarification to avoid accidentally suggesting |
| that almost all surface attributes are invariant. |
| [Bug 4518] Issue 14: Clarify the returned value when |
| EGL_MATCH_FORMAT_KHR is queried. |
| [Bug 4522] Issue 18: Clarify that a locked surface cannot change |
| size. |
| [Bug 4513] Issue 19: Added EGL_BITMAP_PIXEL_SIZE_KHR. |
| [Bug 5923] Issue 20: Must be no current context when posting |
| a lockable surface. In that case any eglSwapInterval setting |
| is ignored. Disallowed a config that is lockable and renderable |
| by an EGL client API. |
| |
| Revision History of original EGL_KHR_lock_surface extension |
| |
| Version 18, 2010/03/23 - Added introductory remark referring to the |
| EGL_KHR_lock_surface2 extension. |
| 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_<x>_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. |