Symbian-Specific Behavior

Symbian windows

EGL window surfaces are tied to Symbian windows. To create an on-screen rendering surface, a Window Server window with attributes corresponding to the desired EGLConfig must be created first. The RWindow class is a handle to a server-side window that can be displayed and drawn to, and whose redraws are performed by the application.

Threading. Because of the limitations of the Window Server API, clients must create and use an EGL window surface in the thread in which its RWindow was created. This means that the following are not supported and will lead to undefined behavior:

• Creating an EGL window surface in thread B using an RWindow that was created in thread A.

• Using an EGL window surface in thread B when that EGL window surface and its RWindow were created in thread A.

For example, in the second scenario, EGL in thread B may fail when it attempts to get the window size from the RWindow in thread A.

Buffer handling. EGL window surfaces have two buffers, known as the front and back buffers. This means that the client application can draw to the back buffer, while the front buffer is being composed to the screen. The client must call eglSwapBuffers() to post the back buffer to the screen.

EGL 1.4 introduces a preserve buffer feature. When this is supported by the implementation, the content of the buffer can be preserved from one frame to the next. This means that the client can provide incremental drawing operations rather than the entire drawing operations for each frame. When the implementation supports this feature, it is usually off by default. This means that legacy applications that do not expect this feature are not slowed down by the unnecessary copying of the buffer contents.

Window resizing. A window can be resized using one of the Window Server or UI Framework APIs, such as RWindow::SetExtent() or CCoeControl::SetExtent(). When these APIs are called on a window that is bound to an EGL window surface, the EGL implementation is expected to handle the situation by adjusting its internal buffers. Applications need not do anything specific with regard to EGL APIs. Depending on the type of application, APIs may want to adjust their rendering operations—for example, clip or scale the contents.

EGL handles the resize in the next call to eglSwapBuffers() by creating a new surface for the resized window. If the preserve buffer option is in use, this function also copies across all the pixels from the old surface that overlap the new surface, although the exact details depend on the implementation. A client application may therefore need to provide extra drawing operations, for example, if the window is made larger.

Screen rotation. There is no specific EGL handling for screen rotation—instead screen rotation is handled in the same way as a change of screen resolution. Applications can detect screen rotation by listening to the Window Server event EEventScreenDeviceChanged. However, applications do not normally use the Window Server API directly, because they are built on top of the UI Framework layer. This layer provides a different mechanism to notify applications using—for example, CCoeAppUi::HandleScreenDeviceChangedL().

When one of the these events is detected, the application may need to resize its windows and update its content accordingly. If the application wants to accept the system rotation, it does not need to rotate its content. However, some applications may want to maintain a fixed physical orientation. They would then need to rotate the window content in order to counteract the physical rotation.

Symbian pixmap types

An EGL implementation can support the CFbsBitmap pointer as an EGLNativePixmapType. This means that it is possible to create an EGLSurface to render to a CFbsBitmap.

CFbsBitmap bitmaps are managed by the Font and Bitmap Server. The format is internal to Symbian, but the Image Converter API can be used to convert them to standard formats. The CFbsBitmap type has limitations with regard to hardware acceleration.

Display handling

Most EGL calls include an EGLDisplay parameter. The EGL specification describes this as "the abstract display on which graphics are drawn". On some systems, this corresponds to a physical screen. However, the details are platform specific and on Symbian systems, it does not correspond to a physical screen. When working on the Symbian platform, it is generally more useful to think of an EGLDisplay as the EGL session.

On Symbian systems, you usually use a single EGLDisplay. You get this by a call to eglGetDisplay() and passing EGL_DEFAULT_DISPLAY as the <display id> parameter.

The physical screen on which the content is displayed is determined by the window's parent window group. In Symbian, every window (RWindow) has a parent window group (RWindowGroup), as shown in the following diagram. When you create a window group, you can specify the screen on which it is to be shown.

When you create a window surface in EGL using eglCreateWindowSurface, you pass in the RWindow as an argument. The window surface is then displayed on the screen associated with that window's parent window group. Currently a window can exist on only one screen.