xref: /third_party/EGL/extensions/NV/EGL_NV_post_sub_buffer.txt

Name

    NV_post_sub_buffer

Name Strings

    EGL_NV_post_sub_buffer

Contributors

    Arcady Goldmints-Orlov
    James Jones
    Daniel Kartch

Contact

    James Jones, NVIDIA Corporation (jajones 'at' nvidia.com)

Status

    Draft.

Version

    Version 3, November 5, 2010

Number

    EGL Extension #27

Dependencies

    Requires EGL 1.1

    This extension is written against the wording of the EGL 1.4
    Specification

Overview

    Many EGL client APIs do not support rendering to window surfaces
    directly, so there is no way to efficiently make small updates to
    window surfaces. Applications that need to perform many small updates
    must either use the back-buffer preservation flag which forces
    eglSwapBuffers to copy the entire back surface, or redraw the entire
    back buffer on every update and hope eglSwapBuffers is implemented
    using buffer-flipping. This extension provides a 3rd alternative: a
    function which posts a sub-rectangle of a window surface and
    preserves the back-buffer contents.

New Types

    None.

New Procedures and Functions

    EGLBoolean eglPostSubBufferNV(EGLDisplay dpy,
                                  EGLSurface surface,
                                  EGLint x, EGLint y,
                                  EGLint width, EGLint height);

New Tokens

    Accepted by the <attribute> parameter of eglQuerySurface and by the
    <attrib_list> parameter of eglCreateWindowSurface:

    EGL_POST_SUB_BUFFER_SUPPORTED_NV        0x30BE

Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)

    Modify the second paragraph of Section 3.5.1, page 27
    (Creating On-Screen Rendering Surfaces)

    "<attrib_list> specifies a list of attributes for the window. The list
    has the same structure as described for eglChooseConfig. Attributes
    that can be specified in <attrib_list> include EGL_POST_SUB_BUFFER_-
    SUPPORTED_NV, EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_-
    FORMAT."

    Add the following between paragraphs 4 and 5 of Section 3.5.1, page 27
    (Creating On-Screen Rendering Surfaces)

    "EGL_POST_SUB_BUFFER_SUPPORTED_NV specifies whether the application
    would perfer a surface that supports sub-buffer post operations, as
    described in section 3.9.1.  Its values can be EGL_TRUE, in which case
    the implementation will attempt to allocate a surface that supports
    sub-buffer posts, or EGL_FALSE, in which case the implementation will
    not take sub-buffer post capabilities into account.

    "Implementations may not be able to support sub-buffer post
    mechanisms, or may support them only on some native windows. Use
    eglQuerySurface to determine a surface's capabilities (see section
    3.5.6)."

    Add the following entry to Table 3.5, page 36
    (Queryable surface attributes and types)

    Attribute                        Type    Description
    -------------------------------- ------- ------------------------
    EGL_POST_SUB_BUFFER_SUPPORTED_NV boolean Surface can be used with
                                             eglPostSubBufferNV

    Add the following paragraph to Section 3.5.6, page 37
    (Surface Attributes)

    "Querying EGL_POST_SUB_BUFFER_SUPPORTED_NV returns EGL_TRUE if the
    surface can use eglPostSubBufferNV (See section 3.9.1) to post sub-
    rectangles of the back color buffer.  Otherwise, EGL_FALSE is
    returned."

    Replace all but the last paragraph of section Section 3.9.1, page 50
    (Posting to a Window)

    "To post the color buffer to a window, call

        EGLBoolean eglSwapBuffers(EGLDisplay dpy,
            EGLSurface surface);

    "To post a sub-rectangle of the color buffer to a window, call

        EGLBoolean eglPostSubBufferNV(EGLDisplay dpy,
            EGLSurface surface, EGLint x, EGLint y,
            EGLint width, EGLint height);

    "Where <x> and <y> are pixel offsets from the bottom-left corner of
    <surface>.

    "If <surface> is a back-buffered surface, then the requested portion
    of the color buffer is copied to the native window associated with
    that surface. If <surface> is a single-buffered window, pixmap, or
    pbuffer surface, eglSwapBuffers and eglPostSubBufferNV have no
    effect.

    "The contents of ancillary buffers are always undefined after calling
    eglSwapBuffers or eglPostSubBufferNV. The contents of the color
    buffer are unchanged if eglPostSubBufferNV is called, or if
    eglSwapBuffers is called and the value of the EGL_SWAP_BEHAVIOR
    attribute of <surface> is EGL_BUFFER_PRESERVED. The value of EGL_-
    SWAP_BEHAVIOR can be set for some surfaces using eglSurfaceAttrib, as
    described in section 3.5.6.

    "Native Window Resizing

    "If the native window corresponding to <surface> has been resized
    prior to the swap, <surface> must be resized to match. <surface> will
    normally be resized by the EGL implementation at the time the native
    window is resized. If the implementation cannot do this transparently
    to the client, then eglSwapBuffers and eglPostSubBufferNV must
    detect the change and resize <surface> prior to copying its pixels to
    the native window. The sub-rectangle defined by <x>, <y>, <width>, and
    <height> parameters to eglPostSubBufferNV will be clamped to the
    extents of <surface>. If, after clamping, the rectangle contains no
    pixels, eglPostSubBufferNV will have no effect."

    Modify the following sentences in Section 3.9.3, page 51 (Posting
    Semantics)

    Paragraph 2, first sentence:

    "If <dpy> and <surface> are the display and surface for the calling
    thread's current context, eglSwapBuffers, eglPostSubBufferNV, and
    eglCopyBuffers perform an implicit flush operation on the context
    (glFlush for OpenGL or OpenGL ES context, vgFlush for an OpenVG
    context)."

    Paragraph 3, first sentence:

    "The destination of a posting operation (a visible window, for
    eglSwapBuffers or eglPostSubBufferNV, or a native pixmap, for
    eglCopyBuffers) should have the same number of components and
    component sizes as the color buffer it's being copied from."

    Paragraph 6, first two sentences:

    "The function

        EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint
            interval);

    specifes the minimum number of video frame periods per color buffer
    post operation for the window associated with the current context. The
    interval takes effect when eglSwapBuffers or eglPostSubBufferNV is
    first called subsequent to the eglSwapInterval call."

    Modify the following sentences in Section 3.9.4, page 52 (Posting
    Errors)

    Paragraph 1, first sentence:

    "eglSwapBuffers, eglPostSubBufferNV, and eglCopyBuffers return
    EGL_FALSE on failure."

    Paragraph 1, seventh sentence:

    "If eglSwapBuffers or eglPostSubBufferNV are called and the native
    window associated with <surface> is no longer valid, an EGL_BAD_-
    NATIVE_WINDOW error is generated.  If eglPostSubBufferNV is called
    and <x>, <y>, <width>, or <height> are less than zero, EGL_BAD_-
    PARAMETER is generated."

Issues

    1. Should all surfaces be required to support sub-buffer posts if
    this extension is supported?

    RESOLVED: No. Some implementations may support multiple types of
    native windows.  Support for sub-surface posting is therefore a
    per-surface property, so a surface query should be used to determine
    which surfaces support sub-surface posts.

    2. What should this extension be called?

    RESOLVED: Names considered EGL_NV_copy_sub_buffer, EGL_NV_present_sub-
    surface, EGL_NV_post_sub_buffer.  eglCopySubBuffer() sounded too
    similar to eglCopyBuffer(), which operates on different types of
    surfaces. EGL_present_sub_surface was originally chosen as it was
    sufficiently different than eglCopyBuffer(), but based on internal
    feedback, the term "Post" is preferable to "Present" because it is
    already used in the EGL spec to describe buffer presentation
    operations. "Buffer" was chosen over "surface" at this point as well,
    because it is more consistent with the eglSwapBuffers() and
    eglCopyBuffer() commands, and eglPostSubBuffer() is still
    differentiated enough from eglCopyBuffer() that the two won't be
    confused.
    
Revision History

#3  (James Jones, November 5, 2010)
    -Renamed from NV_present_sub_surface to NV_post_sub_buffer based on
    feedback from internal reviews.

    -Allowed EGL_POST_SUB_BUFFER_SUPPORTED_NV to be used as a hint when
    creating window surfaces.

    -Clarified that eglSwapInterval applies to all color-buffer post
    operations affecting on-screen surfaces, not just eglSwapBuffers.

#2  (James Jones, November 1, 2010)
    - Fixed a few typos.

#1  (James Jones, October 22, 2010)
    - Initial revision, based on GLX_MESA_copy_sub_buffer