|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F" xml:lang="en"><title>Global |
|
13 Surface Updates</title><shortdesc>Global surface updates are surface composition update commands |
|
14 that are submitted to all displays rather than to a single one. This causes |
|
15 the Surface Update Server to broadcast the update to all of the registered |
|
16 composition engine instances. Each of these then determines whether the surface |
|
17 is displayed on its associated screen and if so, forces an update. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
18 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target |
|
19 audience</b>: Device creators. </p> |
|
20 <p>To specify a global surface update, pass the <codeph>KAllScreens</codeph> constant |
|
21 as the first argument to the <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref> function. </p> |
|
22 <p>The use of global surface updates means that the client does not need to |
|
23 track which screen the surface is visible on and call <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita#GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06/GUID-2B032364-97A0-31A1-A08C-6D8E8ACC16E1"><apiname>RSurfaceUpdateSession::SubmitUpdate()</apiname></xref> for |
|
24 each one. The use of global surface updates is therefore recommended.</p> |
|
25 <p> <i>Note</i>: You must not mix global surface updates with |
|
26 updates for specific screens in the same session. </p> |
|
27 <p>The global surface update feature uses the concept of a surface's <b>master |
|
28 display</b>. When a surface is displayed on more than one screen, its master |
|
29 display is the one that has the highest priority number. The Surface Update |
|
30 Server keeps a list of the priorities of all of the displays. </p> |
|
31 <p>The list of priorities is set up at startup based on the priority assigned |
|
32 to the composition engine instances. (The priority of a display is defined |
|
33 as the priority of its associated composition engine instance.) </p> |
|
34 <section><title>Client notifications</title> <p>When global surface updates |
|
35 are in use, the Surface Update Server makes copies of all of the notification |
|
36 requests from the client and sends them on to each of the registered composition |
|
37 engine instances. The Surface Update Server collects the completed requests |
|
38 from the composition engine instance and forwards the completion status to |
|
39 the client as follows: </p> <ul> |
|
40 <li id="GUID-16591C0C-BB58-5D10-984F-32ED5E35F10A"><p>For all of the <codeph>NotifyWhen...()</codeph> notification |
|
41 types, each composition engine instance determines whether the surface is |
|
42 visible on its associated screen. If the surface is not visible, it returns <codeph>KErrNotVisible</codeph> to |
|
43 the Surface Update Server. If all of the composition engine instances return <codeph>KErrNotVisible</codeph>, |
|
44 the Surface Update Server returns <codeph>KErrNotVisible</codeph> to the client. </p> </li> |
|
45 <li id="GUID-4E6C7843-0C0E-568A-B1D5-0DD10D052FBC"><p> <codeph>NotifyWhenAvailable()</codeph>. |
|
46 For multi-buffered surfaces, the Surface Update Server sends the notification |
|
47 to the client when the buffer has been released by all of the displays on |
|
48 which it is visible. For single-buffered surfaces, the Surface Update Server |
|
49 sends the notification to the client when the composition engine instances |
|
50 that correspond to the displays on which it is visible have read the buffer |
|
51 once. </p> </li> |
|
52 <li id="GUID-043DE46C-130A-582C-9626-C123552A3400"><p> <codeph>NotifyWhenDisplayed()</codeph>. |
|
53 The Surface Update Server sends notification to the client when the master |
|
54 display has displayed the buffer. </p> </li> |
|
55 <li id="GUID-114CC0D5-2955-55AC-8D7A-427D2D1B3215"><p> <codeph>NotifyWhenDisplayedXTimes()</codeph>. |
|
56 The Surface Update Server sends notification to the client when the master |
|
57 display has displayed the buffer the specified number of times. If the master |
|
58 display becomes unavailable while the request is in progress, the Surface |
|
59 Update Server reassigns it to the visible display with the next highest priority. </p> </li> |
|
60 </ul> </section> |
|
61 <section><title>Sequence diagrams</title> <p>The following diagrams illustrate |
|
62 the sequence for global updates in a device that has two composition engine |
|
63 instances registered with the Surface Update Server. These diagrams make the |
|
64 following assumptions: </p> <ul> |
|
65 <li id="GUID-030B0A51-35F8-57AA-93B1-0226FE46C039"><p> <i>Composition Engine |
|
66 1</i> is associated with <i>Screen1</i> and <i>Composition Engine 2</i> is |
|
67 associated with <i>Screen2</i>. </p> </li> |
|
68 <li id="GUID-F6EDF2CF-DE85-55A2-907D-ECFA26576E7E"><p> <i>Composition Engine |
|
69 1</i>'s priority is higher than <i>Composition Engine 2</i>'s. </p> </li> |
|
70 </ul> <p>The first diagram shows the typical sequence when the surface is |
|
71 visible on <i>Screen2</i> only. <i>Composition Engine 1</i> responds first |
|
72 with <codeph>KErrNotVisible</codeph>. The Surface Update Server then considers <i>Screen2</i> to |
|
73 be the surface's master display and waits for it to complete before sending |
|
74 the notification to the client. </p> <fig id="GUID-14C89A10-7762-5836-AF7F-B187704510E5"> |
|
75 <title> The surface is visible on Screen2 only, |
|
76 Composition Engine 1 replies before Composition Engine 2 |
|
77 </title> |
|
78 <image href="GUID-5F9BEEF7-19BC-550F-BD97-60F70B55E906_d0e251994_href.png" placement="inline"/> |
|
79 </fig> <p>In the next diagram, the surface is still visible on <i>Screen2</i> only. |
|
80 This time, however, <i>Composition Engine 2</i> replies before <i>Composition |
|
81 Engine 1</i>. The Surface Update Server considers <i>Composition Engine 1</i> to |
|
82 be the master until it receives an error (<codeph>KErrNotVisible</codeph> in |
|
83 this example) from <i>Composition Engine 1</i>. It then considers <i>Backend2</i> to |
|
84 be the master. </p> <p>Notice that although <i>Screen2</i> has become the |
|
85 master, <codeph>RequestComplete()</codeph> goes to the client at the point |
|
86 that <i>Composition Engine 1</i> returns the error. This is because <i>Backend2</i> replied |
|
87 before <i>Backend1.</i> </p> <fig id="GUID-0708D124-F89D-5BCA-85B0-E28E4CCD26C7"> |
|
88 <title> The surface is visible on Screen2 only, |
|
89 Composition Engine 2 replies before Composition Engine 1 |
|
90 </title> |
|
91 <image href="GUID-B4653180-46EB-58A8-B2A8-0DD2C3D30FE7_d0e252044_href.png" placement="inline"/> |
|
92 </fig> <p>In this final diagram, the surface is visible on both screens. <i>Screen1</i> is |
|
93 considered the surface's master display and the client is notified when <i>Composition |
|
94 Engine 1</i> completes. When <i>Composition Engine 2</i> completes, the Surface |
|
95 Update Server discards its notification. </p> <fig id="GUID-FA4BE8A3-33A2-53E7-9124-53D404B0305A"> |
|
96 <title> The surface is visible on both screens. </title> |
|
97 <image href="GUID-467EF3F5-754B-550A-A9C7-246D68C91F0A_d0e252064_href.png" placement="inline"/> |
|
98 </fig> </section> |
|
99 <section><title>Example</title> <p>The following code snippet shows using |
|
100 the global surface update feature to request composition to all of the screens |
|
101 that are registered with the Surface Update Server. </p> <codeblock id="GUID-45C71218-12FC-58A9-877E-27D642F5E949" xml:space="preserve">TRequestStatus status; |
|
102 RRegion *region; |
|
103 |
|
104 // Signifies all screens. |
|
105 TInt screen = KAllScreens; |
|
106 |
|
107 // The current buffer for composition. |
|
108 TInt theBuffer = 0; |
|
109 |
|
110 TSurfaceId surfaceId; |
|
111 |
|
112 // Set surface ID. |
|
113 ... |
|
114 |
|
115 // Render to the surface. |
|
116 ... |
|
117 |
|
118 // Broadcast the request to all registered screens. |
|
119 surfaceUpdateSession.SubmitUpdate(screen, surfaceId, theBuffer, NULL); |
|
120 </codeblock> </section> |
|
121 </conbody><related-links> |
|
122 <link href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita"><linktext>Surface Update |
|
123 Component Overview</linktext></link> |
|
124 <link href="GUID-63CB6C7E-44EC-5D0B-A37D-FE78F7D76592.dita"><linktext>Graphics |
|
125 Composition Collection</linktext></link> |
|
126 <link href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita"><linktext>Graphics |
|
127 Composition Surfaces</linktext></link> |
|
128 </related-links></concept> |