blob: b09f551d6626c0ab9dffebe60c280af3d4e5d942 [file] [log] [blame]
Name Strings
Copyright 2010 Nokia. All rights reserved.
Robert Palmer
Sami Kyöstilä
Robert Palmer, Nokia (robert.palmer 'at'
Sami Kyöstilä, Nokia (sami.kyostila 'at'
Internally reviewed
2 - April 29, 2010
EGL Extension #23
Requires EGL 1.4
This extension is written against the wording of the EGL 1.4
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
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
New Procedures and Functions
EGLAPI EGLBoolean EGLAPIENTRY eglSwapBuffersRegion2NOK(
EGLDisplay dpy,
EGLSurface surface,
EGLint numRects,
const EGLint* rects);
New Types
New Tokens
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
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
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
Dependencies on OpenVG
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
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
3) How does eglSwapBuffersRegion2NOK interact with incremental
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.
restrict their rendering to a particular region (e.g. using scissor
rects) and then declare this region using eglSwapBuffersRegion2NOK.
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
- Disallowed usage with anything else than back buffered surfaces.
- Clarified some sentences.