Implementing +eglSwapBuffers

Promoting buffers to the screen

EGL +composition surfaces have two buffers, known as the front and back buffers. +Call RSurfaceUpdateSession::SubmitUpdate() to initiate +the composing of a specified buffer of a composition surface to the screen. +This is an asynchronous operation. If you want to be notified when it has +finished, call RSurfaceUpdateSession::NotifyWhenAvailable() immediately +before you call SubmitUpdate().

RSurfaceUpdateSession::NotifyWhenAvailable() takes +a TRequestStatus, which you can wait on in the usual way—for +example, by using an active object or User::WaitForRequest().

If +a TRequestStatus is waiting for the first buffer to complete +composition, you need to submit the second buffer before the first buffer's TRequestStatus is +signaled (unless there is an error). This means that there is interleaving +between the two buffers.

Synchronization and threads

First +let us consider a scenario that illustrates how eglSwapBuffers() works. +The front buffer (Buffer 0) is in the process of being displayed and +the back buffer (Buffer 1) is receiving drawing commands for the next +animation frame. The client calls eglSwapBuffers() when all +of the drawing commands for the next frame have been issued.

eglSwapBuffers() can +promote Buffer 1 to the screen by calling RSurfaceUpdateSession::SubmitUpdate(), +passing in its index. This makes Buffer 1 the front buffer and Buffer +0 should become the new back buffer and all drawing commands should be +directed to it.

However, suppose the application runs faster than +the composition engine. Buffer 0 cannot become the new back buffer +until its composition is complete. You therefore need to wait for Buffer +0 to complete composition before allowing eglSwapBuffers() to +return. This means that after you submit Buffer 1 for composition, +you must wait for Buffer 0 (not Buffer 1) to complete composition +before returning.

In practice it may not be possible to use active +objects to do the waiting because eglSwapBuffers() must block +on the TRequestStatus supplied to RSurfaceUpdateSession::SubmitUpdate(). +Using a nested CActiveScheduler is not recommended because +it can cause re-entrant issues. A call to User::WaitForRequest() may +therefore be required. However, doing this from within a thread that has an +active scheduler can cause stray signal panics (because each buffer has a TRequestStatus but +we only wait for one of these at a time). EGL has no control over whether +the thread has an active scheduler because the thread is owned by the application.

A +possible solution is to create a separate worker thread that is owned by the +EGL implementation and has no active scheduler. This thread calls RSurfaceUpdateSession::NotifyWhenAvailable() and RSurfaceUpdateSession::SubmitUpdate(). It can safely call User::WaitForRequest() to wait for +each TRequestStatus to be signaled, because the thread +is guaranteed not to have an active scheduler. Signaling based on semaphores +can be used to control interaction between the thread that calls eglSwapBuffers() and +the worker thread that owns the RSurfaceUpdateSession.

Handling a window resize event

A +change in the size of an RWindow can be detected in eglSwapBuffers(), +by calling RWindow::Size() and comparing the result with +the previously recorded size. If the values differ, a resize has occurred. +A typical approach on a resize is as follows (and is illustrated in the following +diagram):

Promote the current +back buffer to the front buffer for display as usual.
Create a new composition +surface with the new dimensions and with one of its buffers designated as +the back buffer to receive the next set of drawing commands.
On the next call to eglSwapBuffers(), +register the new composition surface as the window's background surface and +promote its back buffer to the front buffer for display. (This step is marked +with the number 3 in the following diagram)
Close the previous composition +surface.

+The buffers in the typical approach to handling a window resize event + +

Handling +preserve buffers

When the preserve buffer option is in use, +a typical implementation promotes the current back buffer to the front buffer +for display as usual, and copies the back buffer content to the new back buffer. +The client application then provides incremental drawing operations on the +new back buffer. On the next call to eglSwapBuffers(), the +back buffer is again promoted for display and the content is preserved.

The +following diagram shows the scenario of a client application drawing A and +later B on a surface with the preserve buffers enabled. Notice that eglSwapBuffers() promotes +the back buffer to the front buffer and then immediately copies the contents +of the newly promoted buffer to the new back buffer.

+Handling preserve buffers + +

Handling a window resize event with the preserve buffer option

If +there is a window resize event when the preserve buffer option is in use, eglSwapBuffers() creates +a new surface and typically copies into it any pixels that overlap the previous +surface. To illustrate how this works, consider the following scenario:

A window is a wide rectangle +showing an A.
The application draws +a B so that the window shows AB.
The user resizes the +window to a tall thin rectangle which can only show A.
After calling eglSwapBuffers(), +the application draws a C below the A.

The following diagram illustrates a typical implementation. There +are more details below the diagram.

+Handling a window resize with the preserve buffer option + +

The first eglSwapBuffers() call (marked X in the +diagram above) does the following:

Promotes the current +back buffer (showing AB) to the front buffer for display as usual.
Copies the back buffer +content to the new back buffer (showing AB).
Creates a new surface + with the new dimensions.
Designates one of the +new buffers as the back buffer and copies the overlapping pixels into it. +The new back buffer is then ready to receive new drawing operations.

The Window Server continues to use the old surface s1 until the next +call to eglSwapBuffers().

The second eglSwapBuffers() call +(marked Y in the diagram above) does the following:

Promotes the back buffer +(showing A and C) to the front buffer for display as usual.
Copies the back buffer +content to the new back buffer (showing A and C).
Destroys the old surface +s1.

The Window Server now uses the new surface s2.