--- a/Symbian3/PDK/Source/GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita	Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita	Thu Mar 11 18:02:22 2010 +0000
@@ -1,13 +1,13 @@
-<?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-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13"><title>Surfaces</title><shortdesc>This topic provides an introduction to <b>graphics composition surfaces</b>, which are usually simply called <b>surfaces</b>. Surfaces are pixel buffers that have associated metadata describing the width, height, stride and pixel format and are used as input to the composition components. Surfaces can be multi-buffered and are identified by a 128-bit identifier (called the surface ID). </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> <p>Surfaces that are used as input to the composition engine are shared between at least two processes: the Window Server process (in which the composition engine runs) and a <b>renderer</b>, which is responsible for rendering the content to the surface. The camera viewfinder, the video renderer and EGL are examples of renderers. Each process needs to access the surface to read or write (draw) data. Other processes may also need one or both types of access. Each of these processes uses the surface ID to gain access to the surface or its properties. </p> <p>The <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update component</xref> provides a two-way communication channel between the composition engine and the renderers. This allows a renderer to notify the composition engine when the content of a buffer within the surface has been updated and a scene composition is required. Similarly, the Surface Update Server allows the composition engine to notify the renderer of the composition status. </p> <section id="GUID-AD75C13E-389E-5A06-83D7-A49079B5052B"><title> The surface ID </title> <p>The surface ID is a 128-bit number used to identify a surface. It is represented by the <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>TSurfaceId</apiname></xref> class which comprises four 32-bit integers. One byte is used to store a number representing the <b>surface type</b>. Symbian defines the following surface types: </p> <ul><li id="GUID-83FAB870-74E2-535E-9D2D-A40E90FF69BB"><p>An invalid surface (<codeph>EInvalidSurface</codeph>, type 0), </p> </li> <li id="GUID-887582F5-D235-5B2F-930C-C706A2FE4186"><p>A screen surface (<codeph>EScreenSurface</codeph>, type 1) </p> </li> <li id="GUID-9ED41171-5EBF-5103-A198-1E9BBB9D69F6"><p>A Surface Manager surface (<codeph>ESurfaceManagerSurface</codeph>, type 33). </p> </li> </ul> <p>In addition types 34 to 255 are available for device creators to define their own types of rendered surfaces. Screen surface types are enumerated in <filepath>Surface.h</filepath>. Rendered surface types are enumerated in <filepath>SurfaceTypes.h</filepath>. </p> <p>The other 120 bits uniquely identify the surface and are used according to the surface type. Surface Manager IDs are generated automatically by the <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface Manager</xref> when new surfaces are created. The reference implementation generates them randomly in order to minimize the possibility of the IDs being guessed. </p> </section> <section id="GUID-67176ED3-D91F-5FDB-9D6A-F32DD7403F75"><title> A typical life cycle </title> <p><b>Creating a surface </b> </p> <p>Surfaces can be created by using the Surface Manager API. To do this, you first create an instance of the client-side class <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref>. This encapsulates the complexities of device driver communication, memory management and thread safety. To create a surface, you must specify the number of buffers and low-level properties, such as pixel format, stride and memory contiguity. See <xref href="GUID-E238B1FE-BBD8-5C6D-AE04-258188EFF9FF.dita">Creating a Graphics Surface Tutorial</xref> for more information. </p> <p><b>Binding the surface to a window </b> </p> <p>You bind a surface to a window by calling <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWindowBase::SetBackgroundSurface()</apiname></xref>. You can apply a number of <b>configuration</b> settings to the surface, such as viewport, rotation and extent. These crop, scale and rotate the surface content. If the configuration is not set, the entire surface is mapped to the window extent with normal orientation. See <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External Surfaces Overview</xref> for more information. </p> <p><b>Rendering content to the surface and composition </b> </p> <p>The renderer renders the graphics content directly to a buffer within the surface. The renderer then sends a request to the composition engine through the <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update component</xref> to indicate that the surface is ready for composition. The renderer specifies the surface ID, the ID of the current buffer within the surface and optionally the dirty rectangle and the screen on which the surface is to be displayed. Alternatively the request can be broadcast to all screens (this is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref>). </p> <p>The composition engine then includes the surface in the next composition cycle. Because this can take some time, the composition engine carries out the composition asynchronously. The composition engine can notify the client when the buffer is available for rendering into again, in order to prevent tearing or artefacts. The composition engine can also notify the client when the buffer has been displayed a specified number of times, in order to ensure that each frame gets displayed for at least a given period of time. For more information, see <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update Component Overview</xref>. </p> <p> <i>Note</i>: In graphics, the term <b>artefact</b> is used to refer to an error that occurs when displaying or drawing an image on the screen. <b>Tearing</b> is a particular type of error in which part of the current frame and part of the previous frame are seen on the screen at the same time. This makes the image appear torn. Tearing is considered a serious error. </p> <p><b>Removing the surface from window </b> </p> <p>You remove a surface from a window by calling <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWindowBase::RemoveBackgroundSurface()</apiname></xref>. This removes the surface and redraws the window. </p> <p><b>Registering the surface for use on a screen </b> </p> <p>You can optionally register a surface as a separate step before adding it as a background to a window. This enables the client to send a surface update to set up the first buffer that will be displayed when the surface is attached to a window. You register a surface by using <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWsSession::RegisterSurface()</apiname></xref>. </p> <p>A given surface can be registered in multiple sessions and on multiple screens. However, you must not call <codeph>RWsSession::RegisterSurface()</codeph> more than once per session for a given combination of surface and screen, without explicitly unregistering the surface first. </p> <p>Explicitly registered surfaces can be unregistered in two ways: </p> <ul><li id="GUID-66C7BAC5-5973-5630-BC36-71B2D8A39CCE"><p>A call to <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWsSession::UnregisterSurface()</apiname></xref>. </p> </li> <li id="GUID-4280F80D-E226-5AD5-BE3A-74802C6ABA5F"><p>Closing the session. </p> </li> </ul> <p>When the session is closed, all of the surfaces explicitly registered with that session are unregistered. Closing a session also closes any windows associated with that session. Any surfaces directly assigned to those windows are also unregistered. </p> </section> </conbody><related-links><link href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita"><linktext>Graphics Composition Collection Overview</linktext> </link> <link href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita"><linktext>Surface Manager Overview</linktext> </link> <link href="GUID-E238B1FE-BBD8-5C6D-AE04-258188EFF9FF.dita"><linktext>Creating a Graphics
+<?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-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13"><title>Surfaces</title><shortdesc>This topic provides an introduction to <b>graphics composition surfaces</b>, which are usually simply called <b>surfaces</b>. Surfaces are pixel buffers that have associated metadata describing the width, height, stride and pixel format and are used as input to the composition components. Surfaces can be multi-buffered and are identified by a 128-bit identifier (called the surface ID). </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> <p>Surfaces that are used as input to the composition engine are shared between at least two processes: the Window Server process (in which the composition engine runs) and a <b>renderer</b>, which is responsible for rendering the content to the surface. The camera viewfinder, the video renderer and EGL are examples of renderers. Each process needs to access the surface to read or write (draw) data. Other processes may also need one or both types of access. Each of these processes uses the surface ID to gain access to the surface or its properties. </p> <p>The <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update component</xref> provides a two-way communication channel between the composition engine and the renderers. This allows a renderer to notify the composition engine when the content of a buffer within the surface has been updated and a scene composition is required. Similarly, the Surface Update Server allows the composition engine to notify the renderer of the composition status. </p> <section id="GUID-AD75C13E-389E-5A06-83D7-A49079B5052B"><title> The surface ID </title> <p>The surface ID is a 128-bit number used to identify a surface. It is represented by the <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>TSurfaceId</apiname></xref> class which comprises four 32-bit integers. One byte is used to store a number representing the <b>surface type</b>. Symbian defines the following surface types: </p> <ul><li id="GUID-83FAB870-74E2-535E-9D2D-A40E90FF69BB"><p>An invalid surface (<codeph>EInvalidSurface</codeph>, type 0), </p> </li> <li id="GUID-887582F5-D235-5B2F-930C-C706A2FE4186"><p>A screen surface (<codeph>EScreenSurface</codeph>, type 1) </p> </li> <li id="GUID-9ED41171-5EBF-5103-A198-1E9BBB9D69F6"><p>A Surface Manager surface (<codeph>ESurfaceManagerSurface</codeph>, type 33). </p> </li> </ul> <p>In addition types 34 to 255 are available for device creators to define their own types of rendered surfaces. Screen surface types are enumerated in <filepath>Surface.h</filepath>. Rendered surface types are enumerated in <filepath>SurfaceTypes.h</filepath>. </p> <p>The other 120 bits uniquely identify the surface and are used according to the surface type. Surface Manager IDs are generated automatically by the <xref href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita">Surface Manager</xref> when new surfaces are created. The reference implementation generates them randomly in order to minimize the possibility of the IDs being guessed. </p> </section> <section id="GUID-67176ED3-D91F-5FDB-9D6A-F32DD7403F75"><title> A typical life cycle </title> <p><b>Creating a surface </b> </p> <p>Surfaces can be created by using the Surface Manager API. To do this, you first create an instance of the client-side class <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RSurfaceManager</apiname></xref>. This encapsulates the complexities of device driver communication, memory management and thread safety. To create a surface, you must specify the number of buffers and low-level properties, such as pixel format, stride and memory contiguity. See <xref href="GUID-E238B1FE-BBD8-5C6D-AE04-258188EFF9FF.dita">Creating a Graphics Surface Tutorial</xref> for more information. </p> <p><b>Binding the surface to a window </b> </p> <p>You bind a surface to a window by calling <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWindowBase::SetBackgroundSurface()</apiname></xref>. You can apply a number of <b>configuration</b> settings to the surface, such as viewport, rotation and extent. These crop, scale and rotate the surface content. If the configuration is not set, the entire surface is mapped to the window extent with normal orientation. See <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External Surfaces Overview</xref> for more information. </p> <p><b>Rendering content to the surface and composition </b> </p> <p>The renderer renders the graphics content directly to a buffer within the surface. The renderer then sends a request to the composition engine through the <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update component</xref> to indicate that the surface is ready for composition. The renderer specifies the surface ID, the ID of the current buffer within the surface and optionally the dirty rectangle and the screen on which the surface is to be displayed. Alternatively the request can be broadcast to all screens (this is called a <xref href="GUID-D2ECF215-B53C-5659-BA86-5B658C0C2D2F.dita">global surface update</xref>). </p> <p>The composition engine then includes the surface in the next composition cycle. Because this can take some time, the composition engine carries out the composition asynchronously. The composition engine can notify the client when the buffer is available for rendering into again, in order to prevent tearing or artefacts. The composition engine can also notify the client when the buffer has been displayed a specified number of times, in order to ensure that each frame gets displayed for at least a given period of time. For more information, see <xref href="GUID-8E8FE99A-5F4D-5B0F-87AB-A58EB4BEB6E9.dita">Surface Update Component Overview</xref>. </p> <p> <i>Note</i>: In graphics, the term <b>artefact</b> is used to refer to an error that occurs when displaying or drawing an image on the screen. <b>Tearing</b> is a particular type of error in which part of the current frame and part of the previous frame are seen on the screen at the same time. This makes the image appear torn. Tearing is considered a serious error. </p> <p><b>Removing the surface from window </b> </p> <p>You remove a surface from a window by calling <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWindowBase::RemoveBackgroundSurface()</apiname></xref>. This removes the surface and redraws the window. </p> <p><b>Registering the surface for use on a screen </b> </p> <p>You can optionally register a surface as a separate step before adding it as a background to a window. This enables the client to send a surface update to set up the first buffer that will be displayed when the surface is attached to a window. You register a surface by using <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWsSession::RegisterSurface()</apiname></xref>. </p> <p>A given surface can be registered in multiple sessions and on multiple screens. However, you must not call <codeph>RWsSession::RegisterSurface()</codeph> more than once per session for a given combination of surface and screen, without explicitly unregistering the surface first. </p> <p>Explicitly registered surfaces can be unregistered in two ways: </p> <ul><li id="GUID-66C7BAC5-5973-5630-BC36-71B2D8A39CCE"><p>A call to <xref href="GUID-733B8BFA-7BC2-3A6D-A66F-F788413D25A9.dita"><apiname>RWsSession::UnregisterSurface()</apiname></xref>. </p> </li> <li id="GUID-4280F80D-E226-5AD5-BE3A-74802C6ABA5F"><p>Closing the session. </p> </li> </ul> <p>When the session is closed, all of the surfaces explicitly registered with that session are unregistered. Closing a session also closes any windows associated with that session. Any surfaces directly assigned to those windows are also unregistered. </p> </section> </conbody><related-links><link href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita"><linktext>Graphics Composition Collection Overview</linktext> </link> <link href="GUID-55EF3CEB-AF3E-5A32-96F3-F146D1A06C8F.dita"><linktext>Surface Manager Overview</linktext> </link> <link href="GUID-E238B1FE-BBD8-5C6D-AE04-258188EFF9FF.dita"><linktext>Creating a Graphics
                 Surface Tutorial</linktext> </link> </related-links></concept>
\ No newline at end of file