diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt | 679 |
1 files changed, 679 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt new file mode 100644 index 0000000..f85935c --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_lock_surface3.txt @@ -0,0 +1,679 @@ +Name + + KHR_lock_surface3 + +Name Strings + + EGL_KHR_lock_surface3 + +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 + + Complete. + Approved by the EGL Working Group on December 4, 2013. + +Version + + Version 4, 2014/09/17 + +Number + + EGL Extension #64 + +Dependencies + + EGL 1.4 is required. + + This extension is based on the EGL_KHR_lock_surface2 extension and + almost all language is copied from that extension. However, it is + standalone extension. The specification language has been re-based + against the EGL 1.4 Specification. + + Khronos recommends obsoleting and replacing implementations of + EGL_KHR_lock_surface2 and EGL_KHR_lock_surface with this extension as + soon as possible. + +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. + + This extension is functionally identical to EGL_KHR_lock_surface2, but + is intended to replace that extension. It defines a new EGL type, + EGLAttribKHR, which is an integer type guaranteed to be large enough to + hold a pointer. A new surface query, eglQuerySurface64KHR, is defined to + query surface attributes which may not fit in than EGLint, such as a + mapped surface pointer. + + The changes over EGL_KHR_lock_surface2 include: + + * EGL_KHR_lock_surface3 defines the type EGLAttribKHR and the + command eglQuerySurface64KHR. + * eglQuerySurface64KHR must be used to query the + EGL_BITMAP_POINTER_KHR property of surfaces. + +New Types + + /* + * EGLAttribKHR is a integer type used to pass arrays of attribute + * name/value pairs which may include pointer and handle attribute + * values. + */ + #include <khrplatform.h> + typedef intptr_t EGLAttribKHR; + +New Procedures and Functions + + EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface, + const EGLint *attrib_list); + EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy, + EGLSurface surface); + EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + EGLAttribKHR *value); + +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 and + eglQuerySurface64KHR: + + 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 + + Accepted by the <attribute> parameter of eglQuerySurface64KHR: + EGL_BITMAP_POINTER_KHR 0x30C6 + + 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.4 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.4 Specification (EGL Functions and Errors) + + Add to the description of the EGL_BAD_ACCESS error in section 3.1: + + "... (for example, a context is bound in another thread, or a + surface is locked). Any command accessing ..." + + 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.5ls. 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 must include at least one of ``OpenGL'', + ``OpenGL_ES'', or OpenGL ES. If no client APIs are supported, then + the empty string is returned." + + Insert a new paragraph and table in section 3.4.1.1 "Querying + Configurations", following the description of + EGL_MATCH_NATIVE_PIXMAP on page 24: + + "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 25: + + 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. 26, 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 to the + second paragraph on p. 28 listing attributes that can be set in + attrib_list: + + "<attrib_list> specifies a list of attributes ... and + EGL_SWAP_BEHAVIOR." + + and add preceding the paragraph starting "EGL_VG_COLORSPACE specifies + ..." on p. 28: + + "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. + + "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.5ls 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 + the query commands in section 3.5.6. 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 + eglQuerySurface64KHR (see section 3.5.6) 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.6. + + 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, calling eglQuerySurface64KHR + 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.]" + + Modify table 3.5 ("Queryable surface attributes and types") + to add a new column "64-bit". Add new entries to table 3.5: + + Attribute Type Description 64-bit + --------- ------- -------------------------- --------- + EGL_BITMAP_POINTER_KHR pointer Address of a mapped color [checked] + 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_- integer Bit location of each color - + OFFSET_KHR buffer component within a + pixel in an MCB. + EGL_BITMAP_PIXEL_- integer Bits per pixel - + SIZE_KHR + + All previously existing entries in table 3.5 are given a "-" entry in + the new "64-bit" column. + + In the description of eglSurfaceAttrib properties that can be set in + section 3.5.6, add to the description of EGL_SWAP_BEHAVIOR: + + "It <attribute> is 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." + + And modify the paragraph descirbing the initial value of + EGL_SWAP_BEHAVIOR: + + "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). For a lockable window surface the default is + EGL_BUFFER_PRESERVED, but it may be overridden by specifying + EGL_SWAP_BEHAVIOR to eglCreateWindowSurface." + + Add the prototype of the new surface query function immediately + following the prototype for eglQuerySurface on p. 37: + + EGLBoolean eglQuerySurface64KHR(EGLDisplay dpy, + EGLSurface surface, + EGLint attribute, + EGLAttribKHR *value) + + Modify the following paragraph: + + "eglQuerySurface and eglQuerySurface64KHR return in <value> the + value of <attribute> for <surface>. <attribute> must be set to one + of the attributes in table 3.5. Attributes whose ``64-bit'' entry + is checked in table 3.5 may only be queried with + eglQuerySurface64KHR." + + Add to the description of eglQuerySurface properties on p. 38: + + "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.5ls). 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: + + "eglQuerySurface and eglQuerySurface64KHR return EGL_FALSE on + failure ... If <attribute> is one of the attributes whose + ``64-bit'' entry is checked in table 3.5, then an + EGL_BAD_ATTRIBUTE error is generated if eglQuerySurface is called; + only eglQuerySurface64KHR is allowed for such attributes. 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 53, append to the first + paragraph: + + "<surface> must be bound to the calling thread's current context + ... 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.]" + + 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. + + Append following the prototype for eglSwapInterval: + + "specifies the minimum number of video frame periods ... The swap + interval has no effect on eglSwapBuffers for a surface not bound + to a current client API context." + + In 3.9.4 Posting Errors, change the first paragraph: + + "eglSwapBuffers and eglCopyBuffers return EGL_FALSE on failure. If + <surface> is not a valid EGL surface, an EGL_BAD_SURFACE error is + generated. If <surface> is bound to a current context in a thread + other than the calling thread, an EGL_BAD_SURFACE error is + generated." If <target> is not a valid native pixmap handle ..." + +Sample Code + + None + +Conformance Tests + + None yet + +Issues + + The issues lists of EGL_KHR_lock_surface and EGL_KHR_lock_surface2 also + apply to this extension. In addition, issues related only to the reason + for defining the EGLAttribKHR and interfaces using that type may be + found in issues 1-3 of the EGL_KHR_cl_event2 extension specification. + + 1) Is this extension backwards-compatible with EGL_KHR_lock_surface2? + + RESOLVED: No. Querying the bitmap pointer must be done with the new + command eglQuerySurface64KHR when using this extension, to guide + developers down the right path even when writing 32-bit code. + + However, if both lock_surface2 and this extension are supported, it is + possible to query the bitmap pointer using older calls, with the risk + that executing such code on a 64-bit platform will probably fail. + +Revision History + + Version 4, 2014/09/17 (Jon Leech) - Fix bogus return type for + eglQuerySurface64KHR in New Functions section. + + Version 3, 20130/12/04 (Jon Leech) - Minor cleanup for public release. + Change formal parameter names from 'display' to 'dpy' to match other EGL + APIs. + + Version 2, 20130/10/16 (Jon Leech) - add Dependencies and Overview text + noting that this extension obsoletes and should replace + EGL_KHR_lock_surface2 and EGL_KHR_lock_surface. + + Version 1, 2013/10/15 - Branched from approved EGL_KHR_lock_surface2. |