Collapse all Symbian^3 Product Developer Library

Implementing eglCreateWindowSurface

This topic explains how to implement eglCreateWindowSurface() on the Symbian platform.

The steps are as follows:

Use RSurfaceManager and typically RChunk to create a composition surface. The details vary depending on the type of memory that is to be used for the composition surface's buffers. For example, the details are different when specialized graphics memory is used rather than standard CPU memory.
Assign the composition surface to an RWindow by calling:

TInt SetBackgroundSurface(const TSurfaceConfiguration& aConfiguration, TBool aTriggerRedraw);

Ensure that both the extent and viewport of the TSurfaceConfiguration are set to the full extent of the surface.

The following table provides a summary of the key APIs.

API	Description
RSurfaceManager	The client-side API of the Surface Manager. This provides methods to create, open and close composition surfaces and to map a composition surface to an actual memory address. Use this API to create the composition surface.
RSurfaceUpdateSession	The client-side API of the Surface Update Server. This provides a channel for a surface's stakeholders to inform each other of changes. Use this as follows: To post a buffer for composition. To wait for the composition of a buffer to complete.
RWindowBase::SetBackgroundSurface()	Part of the Window Server client-side API, this function sets the background of a window to be a given composition surface (called an external surface in the Window Server documentation). This means that when an RWindow is moved, Window Server automatically moves its associated background surface. This function does the following: Positions the composition surface in a layer below the UI layer, positioned directly below the RWindow. Sets the background color of the RWindow to transparent. This allows the composition surface to show through. Any existing CWindowGc drawing to the RWindow is retained in the foreground. There are two forms of this function: One simply takes the surface ID as an argument. This auto-stretches the background surface to fit the window and causes temporary distortion of the EGL window surface between a resize occurring and the next call to `eglSwapBuffers()`. The other has two arguments—a TSurfaceConfiguration and a `TBool`. You can set the extent and viewport in the `TSurfaceConfiguration` to match the full extent of the surface. This avoids the auto-stretching of the surface. See External Surfaces Overview for an introduction to some of the key concepts.

API

Description

The client-side API of the Surface Manager. This provides methods to create, open and close composition surfaces and to map a composition surface to an actual memory address.

Use this API to create the composition surface.

RSurfaceUpdateSession

The client-side API of the Surface Update Server. This provides a channel for a surface's stakeholders to inform each other of changes.

Use this as follows:

To post a buffer for composition.
To wait for the composition of a buffer to complete.

RWindowBase::SetBackgroundSurface()

Part of the Window Server client-side API, this function sets the background of a window to be a given composition surface (called an external surface in the Window Server documentation). This means that when an RWindow is moved, Window Server automatically moves its associated background surface.

This function does the following:

Positions the composition surface in a layer below the UI layer, positioned directly below the RWindow.
Sets the background color of the RWindow to transparent. This allows the composition surface to show through. Any existing CWindowGc drawing to the RWindow is retained in the foreground.

There are two forms of this function:

One simply takes the surface ID as an argument. This auto-stretches the background surface to fit the window and causes temporary distortion of the EGL window surface between a resize occurring and the next call to eglSwapBuffers().
The other has two arguments—a TSurfaceConfiguration and a TBool. You can set the extent and viewport in the TSurfaceConfiguration to match the full extent of the surface. This avoids the auto-stretching of the surface.

See External Surfaces Overview for an introduction to some of the key concepts.

Parent topic: Window Surface Implementation

Related concepts

Window Surface Implementation Overview

Implementing eglSwapBuffers