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.

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.

+Each window has a parent window group which is associated with a screen + +

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.