xref: /third_party/EGL/extensions/NOK/EGL_NOK_swap_region2.txt

Name

    NOK_swap_region2

Name Strings

    EGL_NOK_swap_region2

Notice

    Copyright 2010 Nokia. All rights reserved.

Contributors

    Robert Palmer
    Sami Kyöstilä

Contacts

    Robert Palmer, Nokia (robert.palmer 'at' nokia.com)
    Sami Kyöstilä, Nokia (sami.kyostila 'at' nokia.com)

Status

    Internally reviewed

Version

    2 - April 29, 2010

Number

    EGL Extension #23

Dependencies

    Requires EGL 1.4

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

Overview

    This extension adds a new function which provides an alternative to
    eglSwapBuffers. eglSwapBuffersRegion2NOK accepts two new parameters
    in addition to those in eglSwapBuffers. The new parameters consist
    of a pointer to a list of 4-integer blocks defining rectangles
    (x, y, width, height) and an integer specifying the number of
    rectangles in the list.

    The new parameters allow users to declare the region of the surface
    that has been updated. The implementation uses this information to transfer
    the updated region to the front buffer. Only the pixels within the
    specified region are copied; any rendering outside that region will not
    become visible on the window surface. This in contrast with the
    EGL_NOK_swap_region extension which treats the modified region only as a
    hint.

    This functional change is aimed at further reducing the processing and
    bandwidth requirements of optimizations of applications whose graphics are
    commonly subjected to region-based changes. Specifically, this extension
    enables partial surface updates without requiring the use of preserved
    swaps.

New Procedures and Functions

    EGLAPI EGLBoolean EGLAPIENTRY eglSwapBuffersRegion2NOK(
              EGLDisplay dpy,
              EGLSurface surface,
              EGLint numRects,
              const EGLint* rects);

New Types

    None

New Tokens

    None

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

    Add the following text to the end of the first subsection in
    section 3.9.1 (prior to 'Native Window Resizing' subsection):

        "eglSwapBuffersRegion2NOK is an alternative to eglSwapBuffers
        that allows the client to provide the region of the surface
        which has been updated. This will allow processing and
        bandwidth optimizations for applications whose graphics are
        commonly subject to region-based changes.

        eglSwapBuffersRegion2NOK behaves in the same way as
        eglSwapBuffers with the following modification: the additional
        parameters <numRects> and <rects> provide specify a region which was
        rendered to by the application. The implementation uses this
        information to combine the modified backbuffer region with the previous
        frontbuffer to form the new frontbuffer. The implementation guarantees
        that all of the pixels within the modified region are posted for
        display and none of the pixels outside the region are sourced. Only
        back buffered surfaces can be used with eglSwapBuffersRegion2NOK.

        <rects> specifies a pointer to a list of 4-integer blocks
        defining rectangles. The area covered by the rectangles
        constitutes the region of the color buffer which has been
        updated by the client. <numRects> specifies the number of
        rectangles in the <rects> list. If <numRects> is set to zero
        the update region is set to the width and height of the
        surface.

        Each rectangle is specified as an integer 4-tuple in the form
        (x, y, width, height). The x and y values provided by the client
        must specify the bottom left corner of each rectangle as the
        origin of the coordinate system is bottom left. Rectangles are
        clipped (restricted) to the bounds of the EGLSurface. A
        rectangle with width or height less than or equal 0 is ignored.
        The region is defined by the union of all the specified
        rectangles. The rectangles as specified must be disjoint. If
        the rectangles are not disjoint or the user has rendered
        outside of the region declared, the rendering results are
        undefined."

    Insert "eglSwapBuffersRegion2NOK" appropriately after each instance
    of "eglSwapBuffers" in the first paragraph in section 3.9.4

    Add the following before the last sentence in the first
    paragraph in section 3.9.4

        "If eglSwapBuffersRegion2NOK is called and <numRects> is greater
        than zero and <rects> is NULL, an EGL_BAD_PARAMETER error is
        generated. If <numRects> is less than zero, an
        EGL_BAD_PARAMETER error is generated."

        "If eglSwapBuffersRegion2NOK is called with a single buffered
        <surface>, an EGL_BAD_MATCH error is generated."

Dependencies on OpenGL ES

    None

Dependencies on OpenVG

    None


Issues

    1) Is there a limit on the number of rectangles that can be used?
    Should there be a specified number which are guaranteed to be
    supported?

    RESOLVED: This is limited by the amount of resources available to the
    implementation. The implementation is free to fail with EGL_BAD_ALLOC if a
    given update region cannot be processed due to resource constraints.

    2) Are there any limitations on the location or size of rectangles?

    RESOLVED: The limitations placed on the validity of a rectangle is
    that the width and height must be greater than zero and should not
    overlap. Rectangles which have a width or height less than or equal
    to zero will be ignored. If rectangles overlap the rendering
    results are undefined. In addition all rectangles are clipped to
    the area of the surface. Rectangles which are partially or
    completely outside the boundary of the surface will not generate an
    error.

    3) How does eglSwapBuffersRegion2NOK interact with incremental
    rendering?

    RESOLVED: This extension does not affect the client's ability to
    perform incremental rendering.  The ability to perform incremental
    rendering is determined solely by the EGLSurface's
    EGL_SWAP_BEHAVIOR attribute.  The use of eglSwapBuffersRegion2NOK to
    describe changed regions can still assist window system composition
    optimizations even if the client is physically redrawing the entire
    surface on every frame.

    If EGL_SWAP_BEHAVIOR is EGL_BUFFER_PRESERVED, the client can
    restrict their rendering to a particular region (e.g. using scissor
    rects) and then declare this region using eglSwapBuffersRegion2NOK.

    If EGL_SWAP_BEHAVIOR is EGL_BUFFER_DESTROYED, the client can
    also restrict rendering to a particular region of the surface, but that
    region must be completely re-rendered because the previous frame contents
    are no longer available within that region. The application can then post
    this region with eglSwapBuffersRegion2NOK. Since the buffer posting is
    guaranteed to be limited to the declared region, the application does not
    need to re-render or otherwise ensure pixel data outside the updated region
    is valid.

    4) How is this extension an improvement over EGL_NOK_swap_region?

    RESOLVED: This extension builds on the previous EGL_NOK_swap_region
    extension by requiring that the implementation considers the update region
    provided by the application as a mandate rather than a hint. This allows
    for region-restricted rendering without requiring the use of preserved buffer
    swaps which may be relatively expensive for the implementation.

    Furthermore, whilst preserved swap behaviour is necessary for incremental
    rendering, many applications fully re-render modified surface regions and
    so don't require preserved swap behaviour. This extension provides a
    lighter weight surface update mechanism for such applications.

    5) How does this extension compare to MESA_copy_sub_buffer?

    RESOLVED: There are two main differences between MESA_copy_sub_buffer and
    this extension:

        1. This extension allows for arbitrary update regions instead of a
           single rectangle.

        2. eglSwapBuffersRegion2NOK is specified to be a frame swap, so the
           implementation is free to apply destructive swap behavior in
           conjunction with this function call. This may allow for a
           performance improvement.

Revision History

    Version 1, 2010/04/28 (Sami Kyöstilä)
      - First revision based on EGL_NOK_swap_region version 10.
    Version 2, 2010/04/29 (Sami Kyöstilä)
      - Specify operation in terms of copying from the back buffer into the
        front buffer instead of involving the the system composition or the
        display.
      - Disallowed usage with anything else than back buffered surfaces.
      - Clarified some sentences.