Global -Surface Updates

Global -Surface UpdatesGlobal surface updates are surface composition update commands -that are submitted to all displays rather than to a single one. This causes -the Surface Update Server to broadcast the update to all of the registered -composition engine instances. Each of these then determines whether the surface -is displayed on its associated screen and if so, forces an update. -

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); -

-Surface Update -Component Overview -Graphics -Composition Collection -Graphics -Composition Surfaces + + + + + +Global +Surface UpdatesGlobal surface updates are surface composition update commands +that are submitted to all displays rather than to a single one. This causes +the Surface Update Server to broadcast the update to all of the registered +composition engine instances. Each of these then determines whether the surface +is displayed on its associated screen and if so, forces an update. +

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); +

+Surface Update +Component Overview +Graphics +Composition Collection +Graphics +Composition Surfaces

\ No newline at end of file