diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt | 727 |
1 files changed, 727 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt new file mode 100644 index 0000000..2cab89e --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface.txt @@ -0,0 +1,727 @@ +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 <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: + + 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 <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 + + 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_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 <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 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, the color buffer of the surface may be <mapped>, + 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. + + <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 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 <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. 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 + <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. + + 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 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_<x>_SIZE attribute of the EGLConfig used to + create the surface, where <x> is <x> 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 <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 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 and + EGL_BITMAP_PIXEL_<x>_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 <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." + +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. + +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_<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. |