xref: /third_party/EGL/extensions/KHR/EGL_KHR_lock_surface3.txt

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.