--- a/Symbian3/PDK/Source/GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,60 +1,60 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept xml:lang="en" id="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9"><title>Surface Update Component Overview</title><shortdesc>Each graphics composition surface has at least two interested stakeholders: the process responsible for drawing and maintaining the content and the composition engine, which uses the surface for creating the display. When one of the stakeholders does something to the surface, it usually means that another stakeholder needs to do something too. The Surface Update component provides a channel for the stakeholders to inform each other of changes. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target audience</b>: Device creators. </p> <section><title>Purpose</title> <p>The Surface Update component provides a communication channel interface for use by components that render graphics content to <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">composition surfaces</xref>. Examples of such components are <xref href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita">EGL</xref>, the <xref href="GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita">video renderer (DevVideo)</xref>, the <xref href="GUID-36C3A2FD-F4F9-5B8C-91B7-40C29B3D2224.dita">camera viewfinder (ECam)</xref> and <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">render stages</xref>. This is illustrated in the following diagram. </p> <fig id="GUID-4916D92E-A639-52FD-9688-181216E0BD9E"><title>
- Surface Update component use case model
- </title> <image href="GUID-C830420C-FBBD-5265-8746-7690C0ADCE81_d0e251323_href.png" placement="inline"/></fig> <p>The client renders the graphics content to a buffer within the surface and then sends a request for composition. The request includes the surface ID, the ID of the current buffer within the surface and optionally the following: </p> <ul><li id="GUID-A681DFDE-FC19-5200-B7A2-0F83170B4100"><p>The number of the screen on which the surface is to be displayed. Alternatively, the <codeph>KAllScreens</codeph> constant can be used to indicate that the request should be broadcast to all screens. This is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref> and its use is encouraged. It makes the client code simpler because it does not need to be concerned with which screen a surface is currently visible on. Note that you must not mix global updates with updates to specific screens within a single session. </p> </li> <li id="GUID-AE975674-48C9-54BB-B1F2-F246CF70DA62"><p>The region of the surface that has changed. This is sometimes referred to as the <b>dirty rectangle</b>. If the client does not specify this, the whole surface is recomposed. </p> </li> </ul> <p>The client can request notification of the following composition-related events: </p> <ul><li id="GUID-2BECDC59-1594-58B0-9F5C-7AD2D9150D4C"><p>The buffer has become available for rendering. </p> </li> <li id="GUID-2EA4C005-B42B-5DA4-8522-7F63E6DC7FD6"><p>The buffer has been displayed for the first time after the update was submitted. This notification is accompanied by timestamp information. </p> </li> <li id="GUID-FD042426-4B77-5421-809F-F554553E0F6C"><p>The buffer has been displayed a certain number of times. This can be used to ensure that each frame gets displayed for at least a given period of time. </p> </li> </ul> </section> <section><title>Architecture</title> <p>The Surface Update component is an adaptation component, which means that it can be replaced by device creators to suit the exact hardware. The reference implementation consists of the Surface Update Server and its client-side API. The Surface Update Server runs within the Window Server process along with the composition engine. The Surface Update Server uses the standard Symbian client/server model for Inter Process Communication (IPC) to communicate with clients and Inter Thread Communication (using active objects and semaphores) to communicate with the composition engine. </p> <p>The client sends requests for composition through the <b>command channel</b> and the composition engine sends notification messages through the <b>notification channel</b>. </p> <p>The following diagram shows communication between the client, Surface Update server and composition engine. The composition engine is shown as a single component, although it can be implemented as multiple components. For example, the <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF-C implementation</xref> consists of the OpenWF-C Support component and the OpenWF-C Engine component. The Surface Update Server in fact communicates with the OpenWF-C Support component, which in turn communicates with the OpenWF-C Engine. </p> <fig id="GUID-371C3037-3D9B-5647-A77B-B7624DFD66E8"><title>
- The Surface Update Server, showing IPC and ITC
- </title> <image href="GUID-26354520-8E9C-58B8-81E7-001EDE9AB77F_d0e251396_href.png" placement="inline"/></fig> <p>Some key points to note include: </p> <ul><li id="GUID-7054554A-9788-55F0-B8E5-9DF2C2B87FDC"><p>The composition engine is a device-specific adaptation that may delegate some of its functionality (such as composing hardware-rendered surfaces) to a GPU or display controller. </p> </li> <li id="GUID-38CC81F2-A85D-50E3-B450-F205618AB533"><p>There is a composition engine instance for each internal screen and external screen connection point on the device. Each composition engine must be registered with the Surface Update Server at startup. </p> </li> <li id="GUID-E08F7A3A-46BB-51FF-B9F2-5060DBB115E4"><p>Each composition engine instance has a unique 32-bit priority number, which represents the relative priority of its associated screen. The higher the number, the higher the priority of the screen. The composition engine instance passes this to the Surface Update Server at registration. The Surface Update Server adds the priority value to its priority list. After it is set up, the priority list is fixed and does not change when a screen becomes unavailable—for example, because it is put on standby or an external screen is disconnected. </p> </li> <li id="GUID-51786E9E-36DC-5459-BEF9-B3A59B8A58E0"><p>Each composition engine instance incorporates its own thread within the Window Server process. However, the external interface is accessed directly from the thread that makes the call. This means that <xref href="GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD.dita#GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD/GUID-64037182-167B-360C-B210-65B0861D4300"><apiname>MCompositionSurfaceUpdate::ContentUpdated()</apiname></xref> is called from the Surface Update Server thread. </p> </li> <li id="GUID-60224A78-8433-579C-9075-B8AFCD9D1924"><p>The Window Server's main thread is a client of the Surface Update Server. Although it is running in the same process as the Surface Update Server, it uses <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref> in exactly the same way as a client in a separate process. </p> </li> </ul> <p>The following diagram provides a more detailed view of the architecture. Notice that there is a composition engine thread for each screen. </p> <fig id="GUID-C3E32B28-5E21-52AD-9065-EE4861302882"><title>
- Surface Update Server class diagram
- </title> <image href="GUID-2FE3BDE7-8782-5026-9B90-D96B77197498_d0e251443_href.png" placement="inline"/></fig> <p>Do not confuse the Surface Update Server with the <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface Manager</xref>. The Surface Manager creates, deletes and manages access to the surface data, whereas the Surface Update Server is concerned with communicating the fact that surface data has changed. </p> </section> <section><title>The Surface Update client API</title> <p>Here is a simplified <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref> declaration showing only the key functions. </p> <codeblock id="GUID-AFEB594E-6C2A-55CF-8150-E2D14AB06AA3" xml:space="preserve">class RSurfaceUpdateSession : public RSessionBase
- {
-public:
- IMPORT_C RSurfaceUpdateSession();
-
- IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot);
-
- IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus);
-
- IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp);
-
- IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus& aStatus);
-
- IMPORT_C void CancelAllUpdateNotifications();
-
- IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer,
- const TRegion* aDirtyRegion = NULL);
-};</codeblock> <p>To use the API: </p> <ol id="GUID-0899998C-9C40-5C19-B3F7-C44DCF1ECA80"><li id="GUID-EEDF1B21-76B3-59E3-81BE-0E69EC0FFBA4"><p> <b>Connect to the Surface Update Server</b>. </p> </li> <li id="GUID-01857F39-49E9-5536-BD2A-7C0935B7034E"><p> <b>Set up one or more notification requests</b>. </p> <p>This part of the process is optional. You need to do it only if the client wants to know when the composition engine has used the data on the surface. To set up a request, call one of the <codeph>NotifyWhen...()</codeph> functions. </p> </li> <li id="GUID-C363F3D1-2618-539C-BB9F-18CB6D845932"><p> <b>Send notification that your surface data has been updated</b>. </p> <p>Call the <codeph>SubmitUpdate()</codeph> function to send a message to the Surface Update Server that there is new data on the specified surface. The message contains the surface ID, the buffer number and the number of the screen on which the surface is displayed or a constant that indicates that the request should be broadcast to all screens (this is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref>). The message can also specify the region of the surface that has changed. This allows the composition engine to ignore parts that have not changed. Before it sends the update, the function sends all of the notification requests that the client has set up. </p> </li> <li id="GUID-FB6BF6C6-6BDF-5DBF-96E9-7BB4E6D1D039"><p> <b>Wait for notifications from the Surface Update Server</b>. </p> <p>If the client requests notification(s), it must wait (<codeph>User::WaitForRequest()</codeph>) for the notification to arrive. However, clients normally use active objects and the Active Scheduler to handle the wait rather than calling <codeph>User::WaitForRequest()</codeph> directly. </p> </li> <li id="GUID-2014F9B1-29B2-570D-BB9A-C7EB42EFBFF6"><p> <b>Close the connection</b>. </p> <p>If your client is still waiting for a notification you must call <codeph>CancelAllUpdateNotifiations()</codeph> before closing the connection, otherwise the client thread panics. </p> </li> </ol> <p><b>Example </b> </p> <p>Here is a snippet of test code which illustrates the process of setting up notification requests before submitting an update. This piece of code results in four messages being sent to the Surface Update Server in <codeph>SubmitUpdate()</codeph>: </p> <codeblock id="GUID-ECFF2218-BF5D-54B2-84F1-BCC80AA5AE26" xml:space="preserve">TRequestStatus statusAvailable = KRequestPending ;
-TRequestStatus statusDisplayed = KRequestPending ;
-TRequestStatus statusDisplayedXTimes = KRequestPending ;
-
-TTimeStamp timeStamp ;
-
-session.NotifyWhenAvailable( statusAvailable ) ;
-session.NotifyWhenDisplayed( statusDisplayed, timeStamp ) ;
-session.NotifyWhenDisplayedXTimes( 10, statusDisplayedXTimes ) ;
-
-err = session.SubmitUpdate( screen, surface, buffer, &region ) ;
-
-User::WaitForRequest( statusAvailable ) ;
-User::WaitForRequest( statusDisplayed ) ;
-User::WaitForRequest( statusDisplayedXTimes ) ;
-</codeblock> <p> <i>Notes</i>: </p> <ul><li id="GUID-E992F13D-4628-561B-A7A4-D2723FA06482"><p>Because this is test code and to avoid complexity, this example calls <codeph>User::WaitForRequest()</codeph> directly rather than using active objects. </p> </li> <li id="GUID-7B0616B5-2978-5C0F-9DA8-1A4C2874E950"><p>In some hardware configurations where composition and display are fast, the buffer available and first displayed notifications may occur very close together for single-buffered surfaces. You should then use only one of these notifications at a time. </p> </li> </ul> </section> <section><title>Sequence diagrams</title> <p>These sequence diagrams primarily illustrate the protocol linking the sending of the buffers and notification. For simplicity some detail is omitted. For example, the client typically renders to the buffer before sending it to the composition engine. This is not shown. Similarly the diagrams omit detail from the composition engine and some omit the Surface Update Server altogether. In addition, they assume that a specific screen number is specified. When global surface updates are in use, the sequence is more complex and is described in <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">Global Surface Updates</xref>. </p> <p><b>Surface buffer availability: single-buffered surface </b> </p> <p>When using a single-buffered surface, the client typically does the following: </p> <ol id="GUID-369D1CE5-DCDA-5764-9D72-6BF28BAEA5A5"><li id="GUID-61EEC7A6-A561-50E0-8EB2-2D80944D1A4F"><p>Render the graphics content to the buffer. </p> </li> <li id="GUID-FF4A8850-3E85-5A21-B155-1F559F50240B"><p>Call <codeph>RSurfaceUpdateSession::NotifyWhenAvailable()</codeph>. </p> </li> <li id="GUID-4108376B-5F0E-5C22-8654-F74663D61B97"><p>Call <codeph>RSurfaceUpdateSession::SubmitUpdate()</codeph>. </p> </li> <li id="GUID-A7523952-6551-542D-B501-604764F16D30"><p>Wait for notification that the buffer is available before rendering further content to it and repeating the cycle for as long as necessary. </p> </li> </ol> <p>This is shown in the following diagram. </p> <fig id="GUID-6A62814B-0493-5E94-9D26-0AC2897B1E4E"><title>
- Single-buffered surface availability
- </title> <image href="GUID-28222243-1531-524F-81A7-070FF6E98C4C_d0e251630_href.png" placement="inline"/></fig> <p>Notice that the notification signal is issued to the client immediately after the buffer has been consumed by the composition engine. When single buffers are used, tearing artefacts are always a risk. Therefore double-buffered surfaces are often used. </p> <p><b>Surface buffer availability: double-buffered surface </b> </p> <p>When double-buffering is used, the client renders to one buffer (called <i>A</i> in this example) while the other buffer (<i>B</i>) is on the screen and vice versa. In order for this to work correctly and to be free of tearing artefacts, the client must use the following sequence: </p> <ol id="GUID-E45EC80D-1742-5699-9B84-E91D966718DA"><li id="GUID-DA98CD3A-77DB-5AB2-9DCF-F85516D493C1"><p>Render the graphics content to buffer <i>A</i>, and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>A</i>. </p> </li> <li id="GUID-1F750734-E797-5BD9-948D-392643F6F4B1"><p>Render the graphics content to buffer <i>B</i>, and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>B</i>. </p> </li> <li id="GUID-8C0526D0-A7D2-5E6C-964A-7BC1E67817D5"><p>Wait for notification that buffer <i>A</i> is available. When it becomes available, render further content to it and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>A.</i> </p> </li> <li id="GUID-60312FB1-9EF9-54B5-85F0-121F0E497CDC"><p>Wait for notification that buffer <i>B</i> is available. When it becomes available, render further content to it and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>B.</i> </p> </li> <li id="GUID-5CB0B8BB-AA69-5C35-9774-A158DDD93072"><p>Repeat steps 3 and 4 for as long as required. </p> </li> </ol> <p>This is shown in the next diagram. After sending the first two buffers to the composition engine, the client waits for notification before sending a further buffer. The composition engine always returns notification after receiving a new buffer even if an error condition is detected. </p> <fig id="GUID-9FE30A58-B4D4-5E0A-907E-63586E5D8529"><title>
- Double-buffered surface availability
- </title> <image href="GUID-9CDB7D27-B4C9-593B-8C67-0335A868BAC0_d0e251731_href.png" placement="inline"/></fig> <p> <i>Notes</i>: </p> <ul><li id="GUID-6C575BD0-C7B5-525B-AB28-05A6F9ADEE76"><p>The buffer that is on the screen is called the <b>front buffer</b> and the one that is being rendered into is called the <b>back buffer</b>. </p> </li> <li id="GUID-1608F782-3E20-5F42-84DA-24F1F0DB66A8"><p>Although double-buffering is shown, three or more buffers can be used. </p> </li> </ul> <p><b>Frame update </b> </p> <p>The following diagram shows the sequence when a client submits a request to be notified when the buffer has been displayed three times. However, the exact details depend on how the composition engine is implemented. If the composition engine knows the screen refresh rate, it can post the composed buffer to the Display Driver and wait for notification that the buffer is on the screen. It could then uses a timer to wait for three frames to be displayed, before it sends the notification. </p> <fig id="GUID-F73EEC1A-A2A0-5FF1-B0FC-F391EE67E782"><title>
- Frame update sequence
- </title> <image href="GUID-5BCB7325-1755-5A66-99B5-6F5AE003D207_d0e251769_href.png" placement="inline"/></fig> <p>If the client sends a new request for update while the previous one is still in progress, the previous request is cancelled with the <codeph>KErrOverflow</codeph> error code. This is illustrated in the next diagram. </p> <fig id="GUID-11496B17-B655-5CF7-ACD5-9F7F5D80266B"><title>
- A second request when the first is still in progress
- </title> <image href="GUID-3F3E8851-3770-5B58-A31E-B5FFCBDE7E55_d0e251781_href.png" placement="inline"/></fig> <p><b>Cancelling of all outstanding requests </b> </p> <p>If the client is waiting for a notification when you need to remove the active object that is handling the notification and close the thread, you must call <codeph>CancelAllUpdateNotifiations()</codeph> first—otherwise the client thread panics. </p> <p>However, <codeph>CancelAllUpdateNotifiations()</codeph> only cancels the notifications and not the associated command request. The notifications complete immediate with the <codeph>KErrCancel</codeph> error code. </p> <fig id="GUID-216C1A8A-24D9-58FF-9C64-EC0CB3A7A92F"><title>
- Cancel all notifications before closing the connection
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept xml:lang="en" id="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9"><title>Surface Update Component Overview</title><shortdesc>Each graphics composition surface has at least two interested stakeholders: the process responsible for drawing and maintaining the content and the composition engine, which uses the surface for creating the display. When one of the stakeholders does something to the surface, it usually means that another stakeholder needs to do something too. The Surface Update component provides a channel for the stakeholders to inform each other of changes. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target audience</b>: Device creators. </p> <section><title>Purpose</title> <p>The Surface Update component provides a communication channel interface for use by components that render graphics content to <xref href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">composition surfaces</xref>. Examples of such components are <xref href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita">EGL</xref>, the <xref href="GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita">video renderer (DevVideo)</xref>, the <xref href="GUID-36C3A2FD-F4F9-5B8C-91B7-40C29B3D2224.dita">camera viewfinder (ECam)</xref> and <xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">render stages</xref>. This is illustrated in the following diagram. </p> <fig id="GUID-4916D92E-A639-52FD-9688-181216E0BD9E"><title>
+ Surface Update component use case model
+ </title> <image href="GUID-C830420C-FBBD-5265-8746-7690C0ADCE81_d0e251323_href.png" placement="inline"/></fig> <p>The client renders the graphics content to a buffer within the surface and then sends a request for composition. The request includes the surface ID, the ID of the current buffer within the surface and optionally the following: </p> <ul><li id="GUID-A681DFDE-FC19-5200-B7A2-0F83170B4100"><p>The number of the screen on which the surface is to be displayed. Alternatively, the <codeph>KAllScreens</codeph> constant can be used to indicate that the request should be broadcast to all screens. This is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref> and its use is encouraged. It makes the client code simpler because it does not need to be concerned with which screen a surface is currently visible on. Note that you must not mix global updates with updates to specific screens within a single session. </p> </li> <li id="GUID-AE975674-48C9-54BB-B1F2-F246CF70DA62"><p>The region of the surface that has changed. This is sometimes referred to as the <b>dirty rectangle</b>. If the client does not specify this, the whole surface is recomposed. </p> </li> </ul> <p>The client can request notification of the following composition-related events: </p> <ul><li id="GUID-2BECDC59-1594-58B0-9F5C-7AD2D9150D4C"><p>The buffer has become available for rendering. </p> </li> <li id="GUID-2EA4C005-B42B-5DA4-8522-7F63E6DC7FD6"><p>The buffer has been displayed for the first time after the update was submitted. This notification is accompanied by timestamp information. </p> </li> <li id="GUID-FD042426-4B77-5421-809F-F554553E0F6C"><p>The buffer has been displayed a certain number of times. This can be used to ensure that each frame gets displayed for at least a given period of time. </p> </li> </ul> </section> <section><title>Architecture</title> <p>The Surface Update component is an adaptation component, which means that it can be replaced by device creators to suit the exact hardware. The reference implementation consists of the Surface Update Server and its client-side API. The Surface Update Server runs within the Window Server process along with the composition engine. The Surface Update Server uses the standard Symbian client/server model for Inter Process Communication (IPC) to communicate with clients and Inter Thread Communication (using active objects and semaphores) to communicate with the composition engine. </p> <p>The client sends requests for composition through the <b>command channel</b> and the composition engine sends notification messages through the <b>notification channel</b>. </p> <p>The following diagram shows communication between the client, Surface Update server and composition engine. The composition engine is shown as a single component, although it can be implemented as multiple components. For example, the <xref href="GUID-8FE41C9A-8171-58A2-A808-17B81E79B11F.dita">OpenWF-C implementation</xref> consists of the OpenWF-C Support component and the OpenWF-C Engine component. The Surface Update Server in fact communicates with the OpenWF-C Support component, which in turn communicates with the OpenWF-C Engine. </p> <fig id="GUID-371C3037-3D9B-5647-A77B-B7624DFD66E8"><title>
+ The Surface Update Server, showing IPC and ITC
+ </title> <image href="GUID-26354520-8E9C-58B8-81E7-001EDE9AB77F_d0e251396_href.png" placement="inline"/></fig> <p>Some key points to note include: </p> <ul><li id="GUID-7054554A-9788-55F0-B8E5-9DF2C2B87FDC"><p>The composition engine is a device-specific adaptation that may delegate some of its functionality (such as composing hardware-rendered surfaces) to a GPU or display controller. </p> </li> <li id="GUID-38CC81F2-A85D-50E3-B450-F205618AB533"><p>There is a composition engine instance for each internal screen and external screen connection point on the device. Each composition engine must be registered with the Surface Update Server at startup. </p> </li> <li id="GUID-E08F7A3A-46BB-51FF-B9F2-5060DBB115E4"><p>Each composition engine instance has a unique 32-bit priority number, which represents the relative priority of its associated screen. The higher the number, the higher the priority of the screen. The composition engine instance passes this to the Surface Update Server at registration. The Surface Update Server adds the priority value to its priority list. After it is set up, the priority list is fixed and does not change when a screen becomes unavailable—for example, because it is put on standby or an external screen is disconnected. </p> </li> <li id="GUID-51786E9E-36DC-5459-BEF9-B3A59B8A58E0"><p>Each composition engine instance incorporates its own thread within the Window Server process. However, the external interface is accessed directly from the thread that makes the call. This means that <xref href="GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD.dita#GUID-229099A4-EE8A-3EA7-8AA3-74ACE34ED1CD/GUID-64037182-167B-360C-B210-65B0861D4300"><apiname>MCompositionSurfaceUpdate::ContentUpdated()</apiname></xref> is called from the Surface Update Server thread. </p> </li> <li id="GUID-60224A78-8433-579C-9075-B8AFCD9D1924"><p>The Window Server's main thread is a client of the Surface Update Server. Although it is running in the same process as the Surface Update Server, it uses <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref> in exactly the same way as a client in a separate process. </p> </li> </ul> <p>The following diagram provides a more detailed view of the architecture. Notice that there is a composition engine thread for each screen. </p> <fig id="GUID-C3E32B28-5E21-52AD-9065-EE4861302882"><title>
+ Surface Update Server class diagram
+ </title> <image href="GUID-2FE3BDE7-8782-5026-9B90-D96B77197498_d0e251443_href.png" placement="inline"/></fig> <p>Do not confuse the Surface Update Server with the <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface Manager</xref>. The Surface Manager creates, deletes and manages access to the surface data, whereas the Surface Update Server is concerned with communicating the fact that surface data has changed. </p> </section> <section><title>The Surface Update client API</title> <p>Here is a simplified <xref href="GUID-FAFD23EB-90EF-3F0C-BAB3-74FEC8DF0E06.dita"><apiname>RSurfaceUpdateSession</apiname></xref> declaration showing only the key functions. </p> <codeblock id="GUID-AFEB594E-6C2A-55CF-8150-E2D14AB06AA3" xml:space="preserve">class RSurfaceUpdateSession : public RSessionBase
+ {
+public:
+ IMPORT_C RSurfaceUpdateSession();
+
+ IMPORT_C TInt Connect(TInt aMessageSlots = KDefaultMessageSlot);
+
+ IMPORT_C void NotifyWhenAvailable(TRequestStatus& aStatus);
+
+ IMPORT_C void NotifyWhenDisplayed(TRequestStatus& aStatus, TTimeStamp& aTimeStamp);
+
+ IMPORT_C void NotifyWhenDisplayedXTimes(TInt aCount, TRequestStatus& aStatus);
+
+ IMPORT_C void CancelAllUpdateNotifications();
+
+ IMPORT_C TInt SubmitUpdate(TInt aScreen, const TSurfaceId& aSurfaceId, TInt aBuffer,
+ const TRegion* aDirtyRegion = NULL);
+};</codeblock> <p>To use the API: </p> <ol id="GUID-0899998C-9C40-5C19-B3F7-C44DCF1ECA80"><li id="GUID-EEDF1B21-76B3-59E3-81BE-0E69EC0FFBA4"><p> <b>Connect to the Surface Update Server</b>. </p> </li> <li id="GUID-01857F39-49E9-5536-BD2A-7C0935B7034E"><p> <b>Set up one or more notification requests</b>. </p> <p>This part of the process is optional. You need to do it only if the client wants to know when the composition engine has used the data on the surface. To set up a request, call one of the <codeph>NotifyWhen...()</codeph> functions. </p> </li> <li id="GUID-C363F3D1-2618-539C-BB9F-18CB6D845932"><p> <b>Send notification that your surface data has been updated</b>. </p> <p>Call the <codeph>SubmitUpdate()</codeph> function to send a message to the Surface Update Server that there is new data on the specified surface. The message contains the surface ID, the buffer number and the number of the screen on which the surface is displayed or a constant that indicates that the request should be broadcast to all screens (this is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref>). The message can also specify the region of the surface that has changed. This allows the composition engine to ignore parts that have not changed. Before it sends the update, the function sends all of the notification requests that the client has set up. </p> </li> <li id="GUID-FB6BF6C6-6BDF-5DBF-96E9-7BB4E6D1D039"><p> <b>Wait for notifications from the Surface Update Server</b>. </p> <p>If the client requests notification(s), it must wait (<codeph>User::WaitForRequest()</codeph>) for the notification to arrive. However, clients normally use active objects and the Active Scheduler to handle the wait rather than calling <codeph>User::WaitForRequest()</codeph> directly. </p> </li> <li id="GUID-2014F9B1-29B2-570D-BB9A-C7EB42EFBFF6"><p> <b>Close the connection</b>. </p> <p>If your client is still waiting for a notification you must call <codeph>CancelAllUpdateNotifiations()</codeph> before closing the connection, otherwise the client thread panics. </p> </li> </ol> <p><b>Example </b> </p> <p>Here is a snippet of test code which illustrates the process of setting up notification requests before submitting an update. This piece of code results in four messages being sent to the Surface Update Server in <codeph>SubmitUpdate()</codeph>: </p> <codeblock id="GUID-ECFF2218-BF5D-54B2-84F1-BCC80AA5AE26" xml:space="preserve">TRequestStatus statusAvailable = KRequestPending ;
+TRequestStatus statusDisplayed = KRequestPending ;
+TRequestStatus statusDisplayedXTimes = KRequestPending ;
+
+TTimeStamp timeStamp ;
+
+session.NotifyWhenAvailable( statusAvailable ) ;
+session.NotifyWhenDisplayed( statusDisplayed, timeStamp ) ;
+session.NotifyWhenDisplayedXTimes( 10, statusDisplayedXTimes ) ;
+
+err = session.SubmitUpdate( screen, surface, buffer, &region ) ;
+
+User::WaitForRequest( statusAvailable ) ;
+User::WaitForRequest( statusDisplayed ) ;
+User::WaitForRequest( statusDisplayedXTimes ) ;
+</codeblock> <p> <i>Notes</i>: </p> <ul><li id="GUID-E992F13D-4628-561B-A7A4-D2723FA06482"><p>Because this is test code and to avoid complexity, this example calls <codeph>User::WaitForRequest()</codeph> directly rather than using active objects. </p> </li> <li id="GUID-7B0616B5-2978-5C0F-9DA8-1A4C2874E950"><p>In some hardware configurations where composition and display are fast, the buffer available and first displayed notifications may occur very close together for single-buffered surfaces. You should then use only one of these notifications at a time. </p> </li> </ul> </section> <section><title>Sequence diagrams</title> <p>These sequence diagrams primarily illustrate the protocol linking the sending of the buffers and notification. For simplicity some detail is omitted. For example, the client typically renders to the buffer before sending it to the composition engine. This is not shown. Similarly the diagrams omit detail from the composition engine and some omit the Surface Update Server altogether. In addition, they assume that a specific screen number is specified. When global surface updates are in use, the sequence is more complex and is described in <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">Global Surface Updates</xref>. </p> <p><b>Surface buffer availability: single-buffered surface </b> </p> <p>When using a single-buffered surface, the client typically does the following: </p> <ol id="GUID-369D1CE5-DCDA-5764-9D72-6BF28BAEA5A5"><li id="GUID-61EEC7A6-A561-50E0-8EB2-2D80944D1A4F"><p>Render the graphics content to the buffer. </p> </li> <li id="GUID-FF4A8850-3E85-5A21-B155-1F559F50240B"><p>Call <codeph>RSurfaceUpdateSession::NotifyWhenAvailable()</codeph>. </p> </li> <li id="GUID-4108376B-5F0E-5C22-8654-F74663D61B97"><p>Call <codeph>RSurfaceUpdateSession::SubmitUpdate()</codeph>. </p> </li> <li id="GUID-A7523952-6551-542D-B501-604764F16D30"><p>Wait for notification that the buffer is available before rendering further content to it and repeating the cycle for as long as necessary. </p> </li> </ol> <p>This is shown in the following diagram. </p> <fig id="GUID-6A62814B-0493-5E94-9D26-0AC2897B1E4E"><title>
+ Single-buffered surface availability
+ </title> <image href="GUID-28222243-1531-524F-81A7-070FF6E98C4C_d0e251630_href.png" placement="inline"/></fig> <p>Notice that the notification signal is issued to the client immediately after the buffer has been consumed by the composition engine. When single buffers are used, tearing artefacts are always a risk. Therefore double-buffered surfaces are often used. </p> <p><b>Surface buffer availability: double-buffered surface </b> </p> <p>When double-buffering is used, the client renders to one buffer (called <i>A</i> in this example) while the other buffer (<i>B</i>) is on the screen and vice versa. In order for this to work correctly and to be free of tearing artefacts, the client must use the following sequence: </p> <ol id="GUID-E45EC80D-1742-5699-9B84-E91D966718DA"><li id="GUID-DA98CD3A-77DB-5AB2-9DCF-F85516D493C1"><p>Render the graphics content to buffer <i>A</i>, and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>A</i>. </p> </li> <li id="GUID-1F750734-E797-5BD9-948D-392643F6F4B1"><p>Render the graphics content to buffer <i>B</i>, and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>B</i>. </p> </li> <li id="GUID-8C0526D0-A7D2-5E6C-964A-7BC1E67817D5"><p>Wait for notification that buffer <i>A</i> is available. When it becomes available, render further content to it and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>A.</i> </p> </li> <li id="GUID-60312FB1-9EF9-54B5-85F0-121F0E497CDC"><p>Wait for notification that buffer <i>B</i> is available. When it becomes available, render further content to it and call <codeph>NotifyWhenAvailable()</codeph> followed by <codeph>SubmitUpdate()</codeph> for buffer <i>B.</i> </p> </li> <li id="GUID-5CB0B8BB-AA69-5C35-9774-A158DDD93072"><p>Repeat steps 3 and 4 for as long as required. </p> </li> </ol> <p>This is shown in the next diagram. After sending the first two buffers to the composition engine, the client waits for notification before sending a further buffer. The composition engine always returns notification after receiving a new buffer even if an error condition is detected. </p> <fig id="GUID-9FE30A58-B4D4-5E0A-907E-63586E5D8529"><title>
+ Double-buffered surface availability
+ </title> <image href="GUID-9CDB7D27-B4C9-593B-8C67-0335A868BAC0_d0e251731_href.png" placement="inline"/></fig> <p> <i>Notes</i>: </p> <ul><li id="GUID-6C575BD0-C7B5-525B-AB28-05A6F9ADEE76"><p>The buffer that is on the screen is called the <b>front buffer</b> and the one that is being rendered into is called the <b>back buffer</b>. </p> </li> <li id="GUID-1608F782-3E20-5F42-84DA-24F1F0DB66A8"><p>Although double-buffering is shown, three or more buffers can be used. </p> </li> </ul> <p><b>Frame update </b> </p> <p>The following diagram shows the sequence when a client submits a request to be notified when the buffer has been displayed three times. However, the exact details depend on how the composition engine is implemented. If the composition engine knows the screen refresh rate, it can post the composed buffer to the Display Driver and wait for notification that the buffer is on the screen. It could then uses a timer to wait for three frames to be displayed, before it sends the notification. </p> <fig id="GUID-F73EEC1A-A2A0-5FF1-B0FC-F391EE67E782"><title>
+ Frame update sequence
+ </title> <image href="GUID-5BCB7325-1755-5A66-99B5-6F5AE003D207_d0e251769_href.png" placement="inline"/></fig> <p>If the client sends a new request for update while the previous one is still in progress, the previous request is cancelled with the <codeph>KErrOverflow</codeph> error code. This is illustrated in the next diagram. </p> <fig id="GUID-11496B17-B655-5CF7-ACD5-9F7F5D80266B"><title>
+ A second request when the first is still in progress
+ </title> <image href="GUID-3F3E8851-3770-5B58-A31E-B5FFCBDE7E55_d0e251781_href.png" placement="inline"/></fig> <p><b>Cancelling of all outstanding requests </b> </p> <p>If the client is waiting for a notification when you need to remove the active object that is handling the notification and close the thread, you must call <codeph>CancelAllUpdateNotifiations()</codeph> first—otherwise the client thread panics. </p> <p>However, <codeph>CancelAllUpdateNotifiations()</codeph> only cancels the notifications and not the associated command request. The notifications complete immediate with the <codeph>KErrCancel</codeph> error code. </p> <fig id="GUID-216C1A8A-24D9-58FF-9C64-EC0CB3A7A92F"><title>
+ Cancel all notifications before closing the connection
</title> <image href="GUID-A786DE92-B87E-5D8E-B61D-645BB42BC303_d0e251807_href.png" placement="inline"/></fig> </section> </conbody><related-links><link href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita"><linktext>Global Surface Updates</linktext> </link> <link href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita"><linktext>Graphics Composition Surfaces</linktext> </link> <link href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita"><linktext>Surface Manager Overview</linktext> </link> <link href="GUID-63CB6C7E-44EC-5D0B-A37D-FE78F7D76592.dita"><linktext>Graphics Composition Collection</linktext> </link> </related-links></concept>
\ No newline at end of file