Global Surface Updates

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.

Figure 1. 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.

Figure 2. 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.

Figure 3. 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);