## NVIDIA DRIVE OS Linux SDK API Reference

#### 5.1.6.0 Release

EGL_EXT_buffer_age
Name

EXT_buffer_age

Name Strings

EGL_EXT_buffer_age

Notice

IP Status

No known IP claims.

Contributors

Robert Bragg
Neil Roberts
Tapani Pälli
Kristian Høgsberg
Acorn Pooley
James Jones

Contacts

Robert Bragg, Intel (robert.bragg 'at' intel.com)

Status

Complete.

Version

12 - June 13, 2013

Number

EGL Extension #52

Dependencies

Requires EGL 1.4

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

Overview

The aim of this extension is to expose enough information to
applications about how the driver manages the set of front and
back buffers associated with a given surface to allow applications
to re-use the contents of old frames and minimize how much must be
redrawn for the next frame.

There are lots of different ways for a driver to manage these
buffers, from double buffering, different styles of triple
buffering and even n-buffering or simply single buffer rendering.
We also need to consider that power management events or memory
pressure events might also result in some of the buffers not
currently in-use being freed.

This extension lets applications query the age of the back buffer
contents for an EGL surface as the number of frames elapsed since
the contents were most recently defined. The back buffer can
either be reported as invalid (has an age of 0) or it may be
reported to contain the contents from n frames prior to the
current frame.

Once the application has queried the buffer age, the age of
contents remains valid until the end of the frame for all pixels
that continue to pass the pixel ownership test.

For many use-cases this extension can provide an efficient
alternative to using the EGL_BUFFER_PRESERVED swap behaviour. The
EGL_BUFFER_PRESERVED swap behaviour adds a direct dependency for
any frame n on frame n - 1 which can affect the pipelining of
multiple frames but also implies a costly copy-back of data to
initialize the back-buffer at the start of each frame.

For example if you consider a double buffered application drawing
a small spinning icon, but everything else in the scene is static.
If we know that 2 buffers are continuously being recycled each
time eglSwapBuffers is called then even though 100s of frames may
need to be drawn to animate the icon it can be seen that the two
buffers are remaining unchanged except within the bounds of the
icon. In this scenario ideally the application would simply
perform an incremental update of the old buffer instead of
redundantly redrawing all the static parts of the scene. The
problem up until now though has been that EGL doesn't report how
buffers may be recycled so it wasn't safe for applications to try
and reuse their contents. Now applications can keep track of all
the regions that have changed over the last n frames and by
knowing the age of the buffer they know how to efficiently repair
buffers that are re-cycled instead of redrawing the entire scene.

New Procedures and Functions

None

New Tokens

EGL_BUFFER_AGE_EXT    0x313D

Additions to Section 2.2 of the EGL 1.4 Specification (Rendering
Contexts and drawing surfaces)

Add the following text to a new subsection titled "Pixel
Ownership Test" after the subsection titled "Interaction With
Native Rendering":

A fragment produced by a client api through rasterization
with windows coordinates (x, y) only modifies the pixel in the
rendering surface at that location if it passes the pixel
ownership test defined by the native window system.

The pixel ownership test determines if the pixel at location
(x, y) in a rendering surface is currently owned by the client
api (more precisely, by this its context). If it is not, the
native window system decides the fate of the incoming
fragment. Possible results are that the fragment is discarded
or that some subset of the subsequent per-fragment operations
are applied to the fragment. This test allows the window
system to control the client api behavior, for instance, when
a window surface is obscured.

The pixel ownership test can only fail for window surfaces,
not for pixmap surfaces or pbuffer surfaces.

Most native window systems will be able to guarantee that no
fragment will ever fail the pixel ownership test, but a
notable exception to this is the X11 window system where,
depending on the driver, the pixel ownership test may fail
when portions of a window are obscured.

Additions to Section 3.5 of the EGL 1.4 Specification (Rendering Surfaces)

Add the following to the table of "Queryable surface attributes
and types":

+----------------------+---------+-----------------------------+
| Attribute            | Type    | Description                 |
+----------------------+---------+-----------------------------+
| EGL_BUFFER_AGE_EXT   | Integer | Age of back-buffer contents |
+----------------------+---------+-----------------------------+
Table aaa: Queryable surface attributes and types.

Add the following text to the subsection titled "Surface
Attributes" in the description for eglQuerySurface

Querying EGL_BUFFER_AGE_EXT returns the age of the color
contents of the current back-buffer as the number of frames
elapsed since it was most recently defined. Applications can,
under certain conditions described below, use this age to
safely rely on the contents of old back- buffers to
potentially reduce the amount of redrawing they do each frame.
A frame is the period between calls to any of the functions in
table 3.X, hereafter referred to as "frame boundaries."

Function name
--------------------
eglSwapBuffers

Table 3.X, Frame Boundary Functions

Buffers' ages are initialized to 0 at buffer creation time.
When a frame boundary is reached, the following occurs before
any exchanging or copying of color buffers:

* The current back buffer's age is set to 1.
* Any other color buffers' ages are incremented by 1 if
their age was previously greater than 0.

For the purposes of buffer age tracking, a buffer's content
is considered defined when its age is a value greater than 0.

For example, with a double buffered surface and an
implementation that swaps via buffer exchanges, the age would
usually be 2. With a triple buffered surface the age would
usually be 3. An age of 1 means the previous swap was
implemented as a copy. An age of 0 means the buffer has only
just been initialized and the contents are undefined. Single
buffered surfaces have no frame boundaries and therefore
always have an age of 0.

Frame boundaries are the only events that can set a buffer's
age to a positive value. Once EGL_BACK_BUFFER_AGE_EXT has been
queried then it can be assumed that the age will remain valid
until the next frame boundary. EGL implementations are
permitted, but not required, to reset the buffer age in
response to pixel ownership test changes for any pixels within
the drawable, or if new pixels are added to or removed from
the drawable, i.e., the drawable is resized. A reset of this
nature does not affect the age of content for pixels that pass
the pixel ownership test before and after the event that
caused the reset.  In other words, applications can assume
that no event will invalidate the content of pixels that
continuously pass the pixel ownership test between when the
buffer age was queried and the following frame boundary.

It is up to applications to track pixel ownership using data
collected from relevant window system events, such as
configuration and expose events on X11.

If the EGL implementation decides to free un-used back-buffers
when the system is under memory pressure or in response to
power-management events then EGL will return an age of 0 when
it allocates a new buffer at the start of a new frame.

If the EGL_BUFFER_PRESERVED swap behaviour is in use then
it can be assumed that the age will always be 1. It is
recommended where possible though that the
EGL_BUFFER_PRESERVED swap behaviour not be used since it can
have severe performance consequences. Keeping track of the
buffer age and the regions that have changed over the last 2
or 3 frames instead can often replace the need for using
EGL_BUFFER_PRESERVED.

EGL_BUFFER_AGE_EXT state is a property of the EGL surface that
owns the buffers and lives in the address space of the
application.  That is, if an EGL surface has been created from
a native window or pixmap that may be shared between
processes, the buffer age is not guaranteed to be synchronized
across the processes. Binding and unbinding a surface to and
from one or more contexts in the same address space will not
affect the ages of any buffers in that surface.

Add the following text to last paragraph of the subsection titled
"Surface Attributes" in the description for eglQuerySurface
errors.

If querying EGL_BUFFER_AGE_EXT and <surface> is not bound as
the draw surface to the calling threads current context

Dependencies on OpenGL ES

None

Dependencies on OpenVG

None

Issues

1) What are the semantics if EGL_BUFFER_PRESERVED is in use

RESOLVED: The age will always be 1 in this case. More
recommendation to use the buffer age to reuse buffers instead
of EGL_BUFFER_PRESERVED when possible to avoid the
in-efficiencies of introducing a dependency for each frame on
the previous frame.

2) How can an application know that all pixels of a re-usable
buffer were originally owned by the current context?

RESOLVED: It is up to the application to track pixel ownership
using existing window system specific events, such as X11
expose or configure notify events.

3) What are the semantics if the buffer age attribute is queried for
a surface that isn't bound to the calling thread's context as the
draw surface?

RESOLVED: we report an EGL_BAD_SURFACE error as is similarly
done when calling eglSwapBuffers for such a surface.

4) What is the buffer age of a single buffered surface?

RESOLVED: 0.  This falls out implicitly from the buffer age
calculations, which dictate that a buffer's age starts at 0,
and is only incremented by frame boundaries.  Since frame
boundary functions do not affect single buffered surfaces,
their age will always be 0.

5) What guarantees are provided after querying the buffer age?

RESOLVED: The buffer age of pixels which continue to pass the
pixel ownership test must remain valid until the next frame
boundary otherwise applications can't be absolutely sure of
the consistency of their rendered content.  Implementations
may reset the queryable age of the buffer when pixel ownership
changes occur.  This is further clarified in section 3.5

Revision History

Version 1, 25/07/2011
- First draft
Version 2, 03/08/2011
- Clarified semantics for using EGL_BUFFER_PRESERVED
Version 3, 01/09/2011
- Fixed a prototype inconsistency
Version 4, 03/11/2011
- Split out the buffer age parts from EGL_INTEL_start_frame
Version 5, 20/03/2012
- Document that once the age is queried it remains valid until
the end of the frame so we can remove the need for a separate
EGL_EXT_start_frame extension.
Version 6, 20/03/2012
- Clarify that only buffers who's contents were fully owned by
the context are tracked.
Version 7, 20/03/2012
- Document that an error will be generated if querying the age
for a surface not bound to the current context.
Version 8, 25/08/2012
- Update in line with changes made to the GLX_EXT_buffer_age draft spec
including more relaxed pixel ownership requirements and explicit
clarification of the buffer age calculation.
Version 9 20/09/2012
- Update in line with changes made to the EGL_EXT_buffer age
draft space
Version 10 29/11/2012
- Add pixel ownership test section and other minor
clarifications
Version 11 13/12/2012
- Allocated enumerant and marked complete.