Global +Surface Updates

Variant: ScreenPlay. Target +audience: Device creators.

To specify a global surface update, pass the KAllScreens constant +as the first argument to the RSurfaceUpdateSession::SubmitUpdate() function.

The use of global surface updates means that the client does not need to +track which screen the surface is visible on and call RSurfaceUpdateSession::SubmitUpdate() for +each one. The use of global surface updates is therefore recommended.

Note: You must not mix global surface updates with +updates for specific screens in the same session.

The global surface update feature uses the concept of a surface's master +display. When a surface is displayed on more than one screen, its master +display is the one that has the highest priority number. The Surface Update +Server keeps a list of the priorities of all of the displays.

The list of priorities is set up at startup based on the priority assigned +to the composition engine instances. (The priority of a display is defined +as the priority of its associated composition engine instance.)

Client notifications

When global surface updates +are in use, the Surface Update Server makes copies of all of the notification +requests from the client and sends them on to each of the registered composition +engine instances. The Surface Update Server collects the completed requests +from the composition engine instance and forwards the completion status to +the client as follows:

For all of the NotifyWhen...() notification +types, each composition engine instance determines whether the surface is +visible on its associated screen. If the surface is not visible, it returns KErrNotVisible to +the Surface Update Server. If all of the composition engine instances return KErrNotVisible, +the Surface Update Server returns KErrNotVisible to the client.
NotifyWhenAvailable(). +For multi-buffered surfaces, the Surface Update Server sends the notification +to the client when the buffer has been released by all of the displays on +which it is visible. For single-buffered surfaces, the Surface Update Server +sends the notification to the client when the composition engine instances +that correspond to the displays on which it is visible have read the buffer +once.
NotifyWhenDisplayed(). +The Surface Update Server sends notification to the client when the master +display has displayed the buffer.
NotifyWhenDisplayedXTimes(). +The Surface Update Server sends notification to the client when the master +display has displayed the buffer the specified number of times. If the master +display becomes unavailable while the request is in progress, the Surface +Update Server reassigns it to the visible display with the next highest priority.

Sequence diagrams

The following diagrams illustrate +the sequence for global updates in a device that has two composition engine +instances registered with the Surface Update Server. These diagrams make the +following assumptions:

Composition Engine +1 is associated with Screen1 and Composition Engine 2 is +associated with Screen2.
Composition Engine +1's priority is higher than Composition Engine 2's.

The first diagram shows the typical sequence when the surface is +visible on Screen2 only. Composition Engine 1 responds first +with KErrNotVisible. The Surface Update Server then considers Screen2 to +be the surface's master display and waits for it to complete before sending +the notification to the client.

+ The surface is visible on Screen2 only, +Composition Engine 1 replies before Composition Engine 2 + + +

In the next diagram, the surface is still visible on Screen2 only. +This time, however, Composition Engine 2 replies before Composition +Engine 1. The Surface Update Server considers Composition Engine 1 to +be the master until it receives an error (KErrNotVisible in +this example) from Composition Engine 1. It then considers Backend2 to +be the master.

Notice that although Screen2 has become the +master, RequestComplete() goes to the client at the point +that Composition Engine 1 returns the error. This is because Backend2 replied +before Backend1.

+ The surface is visible on Screen2 only, +Composition Engine 2 replies before Composition Engine 1 + + +

In this final diagram, the surface is visible on both screens. Screen1 is +considered the surface's master display and the client is notified when Composition +Engine 1 completes. When Composition Engine 2 completes, the Surface +Update Server discards its notification.

+ The surface is visible on both screens. + +

Example

The following code snippet shows using +the global surface update feature to request composition to all of the screens +that are registered with the Surface Update Server.

TRequestStatus status; +RRegion *region; + +// Signifies all screens. +TInt screen = KAllScreens; + +// The current buffer for composition. +TInt theBuffer = 0; + +TSurfaceId surfaceId; + +// Set surface ID. +... + +// Render to the surface. +... + +// Broadcast the request to all registered screens. +surfaceUpdateSession.SubmitUpdate(screen, surfaceId, theBuffer, NULL); +