<?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 id="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7" xml:lang="en"><title>External+
−
Surfaces Overview</title><shortdesc>This topic provides an introduction to displaying an external surface+
−
on a window. The surface is then known as a background surface. This feature+
−
is available in ScreenPlay only. </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>There are two main use cases for using external surfaces in this way. One+
−
is to display a video, in which case DevVideo renders the content. The other+
−
main use case is an OpenGL ES background surface, in which case the client+
−
issues OpenGL ES rendering commands. This topic covers how to get the surface+
−
onto the screen and not rendering the content to the surface. </p>+
−
<section><title> Key concepts</title> <p>The following diagram illustrates+
−
some of the key concepts that are used in the documentation of surfaces. </p> <fig id="GUID-F134C262-EC19-5925-A188-2C7C2CD5EEEA">+
−
<title>Composition of the UI surface and an external surface, showing the+
−
             viewport and extent</title>+
−
<image href="GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e248086_href.png" placement="inline"/>+
−
</fig> <dl>+
−
<dlentry>+
−
<dt>Graphics surface</dt>+
−
<dd><p>A graphics surface (usually simply called a <i>surface</i>) is a hardware-independent+
−
memory buffer for holding an image or part of a scene. A surface has a set+
−
of attributes, the most important of which is its ID (which is a <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>). </p> </dd>+
−
</dlentry>+
−
<dlentry>+
−
<dt>UI surface</dt>+
−
<dd><p>The UI surface is a special surface onto which the Window Server renders+
−
all of the UI content. It is created automatically during system start up+
−
and corresponds to the frame buffer in the non-ScreenPlay variant. The UI+
−
surface is semi-transparent and is always the topmost layer.</p> </dd>+
−
</dlentry>+
−
<dlentry>+
−
<dt>External surface</dt>+
−
<dd><p>An external surface is any surface other than the UI surface—for example,+
−
a surface that holds a video or to which OpenGL ES content is rendered. External+
−
surfaces are always opaque. When an external surface is attached to a window,+
−
the Window Server creates a transparent hole in the UI surface to reveal the+
−
external surface. </p> </dd>+
−
</dlentry>+
−
<dlentry>+
−
<dt>Viewport</dt>+
−
<dd><p>The viewport is a rectangular area of an external surface all or part+
−
of which is to be displayed. You can think of the viewport as the source. </p> </dd>+
−
</dlentry>+
−
<dlentry>+
−
<dt>Extent</dt>+
−
<dd><p>The extent is a rectangular area in the composition scene in which+
−
all or part of the viewport is placed. The content of the viewport can be+
−
scaled and rotated within the extent relative to its normal size and orientation.+
−
The extent is normally a window to which the external surface is attached. </p> </dd>+
−
</dlentry>+
−
</dl> <p>The following diagram provides a cross-section view through the surfaces+
−
shown in the previous figure. Notice that the UI surface is the topmost layer+
−
and that it contains a hole through which the external surface+
−
can be seen.</p> <fig id="GUID-4DB99814-988F-5D51-A1A7-E864B6DA6DFB">+
−
<title>              A cross section through the surfaces, showing the display+
−
output            </title>+
−
<image href="GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e248164_href.png" placement="inline"/>+
−
</fig> </section>+
−
<section id="GUID-F9D7659B-1325-5DC2-9D7A-9B6C0DFB8A62"><title>Supported Uses</title> <p>You+
−
can: </p> <ul>+
−
<li id="GUID-97CAD13E-1C70-59FF-B271-F3E77198086A"><p>Display an external+
−
surface (for example, video content or a viewfinder image) within a window. </p> </li>+
−
<li id="GUID-BD8FFB28-D56C-581B-9E1C-B2BD97FDAFBC"><p>Dynamically set or remove+
−
a background surface across multiple windows on the same screen without having+
−
to register and unregister the surface. This reduces resource churn and content+
−
transfer. </p> </li>+
−
<li id="GUID-0A3FD92E-7E99-5961-BC5A-3FBB970A7889"><p>Reconfigure the attributes+
−
of the surface such as its extent, viewport and orientation, after it is set+
−
as a background. </p> </li>+
−
<li id="GUID-6E962607-1E7D-516E-B855-15A1A67923B6"><p>Reposition the displayed+
−
surface on the window. </p> </li>+
−
<li id="GUID-26E561E7-92BB-5EBA-A3B9-F660507A258D"><p>Zoom in and out of the+
−
contents of the surface. </p> </li>+
−
<li id="GUID-287D3286-209B-5E01-B1C6-2373A2B07172"><p>Place the surface content+
−
in a specified window area rather than filling the entire window. </p> </li>+
−
<li id="GUID-6F2DCF0C-32D7-53CD-A2DD-4DBE662015B5"><p>Crop the surface content+
−
rather than using the entire surface. </p> </li>+
−
<li id="GUID-8E49A7FB-0709-5127-8C94-104C512EA6AC"><p>Rotate the contents+
−
of the background surface by quadrant angles. </p> </li>+
−
<li id="GUID-5631047A-A8AD-59DF-82FF-021964BA571D"><p>Flip the background+
−
surface from top to bottom and rotate it by 180° to achieve a mirroring effect. </p> </li>+
−
</ul> <p>The following diagrams shows some surface configuration use cases. </p> <fig id="GUID-FF25ED24-7A3D-5C4B-A711-D6AEA53E972F">+
−
<title>              Surface configuration use cases            </title>+
−
<image href="GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e248231_href.png" placement="inline"/>+
−
</fig> </section>+
−
<section id="GUID-7EAB8F5D-6290-5B63-B396-8A1FAE7D91A5"><title> Configuration</title> <p>There+
−
are a number of ways in which dynamically updated content can be configured+
−
to appear on a window. </p> <p><b>A single content surface filling the window </b> </p> <p>External+
−
content can be fitted onto a Window Server window. Each axis of the surface+
−
can be stretched independently of the other axis. The window must be a visible+
−
client window: <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> or <xref href="GUID-A5DFCFA7-7B2D-3872-B6D0-4526DF743630.dita"><apiname>RBlankWindow</apiname></xref>. </p> <p><b>Placement+
−
of a single surface on a selected area of the window </b> </p> <p>The position+
−
and display size for the external content can be specified as an area within+
−
the Window Server window, rather than filling the window. The window must+
−
be a visible client (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> or <xref href="GUID-A5DFCFA7-7B2D-3872-B6D0-4526DF743630.dita"><apiname>RBlankWindow</apiname></xref>)+
−
as before. You specify the area by using <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita#GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA/GUID-8984E1F8-2807-301D-B82B-A52CC4254B04"><apiname>TSurfaceConfiguration::SetExtent(const+
−
TRect&amp;           aExtent)</apiname></xref>. </p> <p>After the extent is specified,+
−
its size does not change if the window size changes but its position moves+
−
to maintain its relative position on the window. </p> <p><b>Clipping of a+
−
surface </b> </p> <p>Video sometimes needs to appear cropped, so that a sub-area+
−
of the video is displayed instead of the full image. The crop viewport is+
−
specified in surface co-ordinates. The cropped viewport fills the output extent+
−
(or the window when the extent is not specified). The content appears scaled+
−
if the size of the viewport does not match the size of the extent (or the+
−
window). </p> <p><b>Scaling </b> </p> <p>It is possible to arbitrarily scale+
−
a surface to user specifications using the extent and viewport features. Each+
−
axis is scaled independently. When the extent and viewport are coincident,+
−
no scaling occurs. Filtering can be applied by the implementation of stretching+
−
and shrinking. </p> <p><b>Rotation </b> </p> <p>The viewport can be displayed+
−
rotated relative to its normal orientation. For example, if there is a fixed+
−
camera on the front of a device and the device is rotated by 90°, the image+
−
captured by the camera needs to be rotated by 90° in the other direction to+
−
get the expected result. The orientation is always relative to the current+
−
device orientation. </p> <p><b>Flipping </b> </p> <p>An external surface can+
−
be flipped from top to bottom around the x axis. </p> <p><b>Atomic combination+
−
of these operations </b> </p> <p>All the above mentioned configurations can+
−
be specified and combined unambiguously for a particular content on a particular+
−
window. You can specify parameters for a combination of these configurations+
−
in a single operation. </p> <p><b>Changing surfaces </b> </p> <p>The surface+
−
assigned to a window can be changed. </p> <p><b>Reconfiguring </b> </p> <p>It+
−
is possible to change the configuration options applied to a surface without+
−
re-assigning the surface. </p> <p><b>Sharing surfaces </b> </p> <p>Content+
−
surfaces are transferable and sharable between windows. </p> <p>The initial+
−
registration step ensures that any resources allocated to the content surface+
−
are held while the surface is removed from one window and added to another.+
−
This reduces the likelihood of failure between operations. </p> </section>+
−
<section><title>API Summary</title> <p>This section provides a summary of+
−
the classes and functions that you use to manage surfaces: </p> <ul>+
−
<li id="GUID-D7C9343C-BFAB-5153-B3E6-E5EBA5859570"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-3E1EF2ED-7E9C-541F-A439-F2CBA5B6F211">RWindowBase</xref>  </p> </li>+
−
<li id="GUID-5AD3B9D5-60E8-5A2A-9C6B-4C914540FE9E"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-1DC9E4DF-248F-59A6-92A9-F756F73414B3">TSurfaceConfiguration</xref>  </p> </li>+
−
<li id="GUID-2627F547-B979-5682-A69A-97D89969F9B3"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-E2A62988-58F8-5021-BA44-25AE3C3D95B5">RWsSession</xref>  </p> </li>+
−
</ul> </section>+
−
<section id="GUID-3E1EF2ED-7E9C-541F-A439-F2CBA5B6F211"><title>RWindowBase </title> <ul>+
−
<li id="GUID-7A5D0A6F-C0B6-5D87-B0F4-99C92FA8227B"><p> <codeph>SetBackgroundSurface(const+
−
TSurfaceConfiguration                 &amp;,TBool)</codeph> sets the background+
−
of the window to be a given surface. The <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref> argument+
−
contains the surface ID and the configuration attributes. Another form of+
−
the function simply takes a surface ID as an argument, which provides less+
−
control and auto-stretches the surface to fill the window. </p> </li>+
−
<li id="GUID-C86F37F7-5017-56F3-9B14-E3B8E0EC0E8A"><p> <codeph>RemoveBackgroundSurface()</codeph> removes+
−
any background surface that has been set to the window. </p> </li>+
−
<li id="GUID-11ABFBDE-556F-5096-810E-6BBA2C81C4B1"><p> <codeph>GetBackgroundSurface()</codeph> retrieves+
−
a copy of the current configuration for the background surface attached to+
−
the window. </p> </li>+
−
</ul> <p>See <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>. </p> </section>+
−
<section id="GUID-1DC9E4DF-248F-59A6-92A9-F756F73414B3"><title> TSurfaceConfiguration</title> <p>This+
−
class encapsulates the surface configuration attributes that can be specified+
−
while setting the background surface of a window. If the values for the attributes+
−
are not set, the default values for the corresponding attribute are used. </p> <p>Symbian+
−
recommends that the client validates the surface configuration data before+
−
passing it on to the server. Invalid data that inadvertently slips through+
−
the client-side validation mechanism, or maliciously bypasses it, causes a+
−
panic. </p> <p>See <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref>. </p> </section>+
−
<section id="GUID-E2A62988-58F8-5021-BA44-25AE3C3D95B5"><title> RWsSession</title> <ul>+
−
<li id="GUID-B1A1CE19-6E12-5BA7-B79A-A6D7C44F5920"><p> <codeph>RegisterSurface()</codeph> registers+
−
a surface for use in composition on the screen associated with this device+
−
within this session. </p> </li>+
−
<li id="GUID-6678C53D-F0B5-5ADD-BCC7-43FC31E81FEE"><p> <codeph>UnregisterSurface()</codeph> removes+
−
the surface from the session’s register of surfaces that are used in composition+
−
on the screen associated with this device. </p> </li>+
−
<li id="GUID-9F5FF304-794C-5BC3-B16E-F036C859F1E2"><p> <codeph>PreferredSurfaceConfigurationSize()</codeph> returns+
−
the window server’s preferred size for the <codeph>TSurfaceConfiguration</codeph> object,+
−
used for <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-AC4FBD36-8CC7-3191-B266-1805DEDE6D50"><apiname>RWindow::SetBackgroundSurface()</apiname></xref>. </p> </li>+
−
</ul> <p>See <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. </p> </section>+
−
<section><title>Example</title> <p>This code snippet is provided for illustrative+
−
purposes only. A Window Server client application wants to run a 3D game full-screen+
−
at the native physical resolution of the display (either current or selected+
−
using a display controlling system application). This example assumes that+
−
the <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface has already been obtained,+
−
as shown in <xref href="GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita">Display+
−
Control and Mapping in the Window Server Client</xref>. </p> <codeblock id="GUID-DE5C6DB0-1096-5BA3-8BB7-78AE3B6619B1" xml:space="preserve">// Establish connection and get display mapping interface.+
−
RWindowGroup group = RWindowGroup(iSession);+
−
RWindow window(iSession);+
−
    +
−
group.Construct(1, iScreenDevice);+
−
window.Construct(group, 2);+
−
    +
−
TRect winExtent;+
−
iDisplayMapping.GetMaximumWindowExtent(winExtent);+
−
window.SetExtent(winExtent);+
−
    +
−
// Map window size to composition coordinates+
−
TRect surfaceExtent;+
−
iDisplayMapping.MapCoordinates(EApplicationSpace, winExtent,+
−
    ECompositionSpace, surfaceExtent);+
−
    +
−
RSurfaceManager::TSurfaceCreationAttributes attribs;+
−
attribs.iSize = surfaceExtent.Size();+
−
    +
−
// Set up other attributes and create surface+
−
    +
−
window.SetBackgroundSurface(surface);+
−
    +
−
window.Activate();+
−
</codeblock> <p>A similar approach can be used by other surface content providers,+
−
such as video. </p> </section>+
−
</conbody><related-links>+
−
<link href="GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita"><linktext>Graphics+
−
Composition</linktext></link>+
−
<link href="GUID-ADA8CECB-0E70-5B9C-8F36-0714AAF0CD13.dita">+
−
<linktext>Graphics Surfaces</linktext></link>+
−
<link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server+
−
Client-Side Library Concepts</linktext></link>+
−
<link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution+
−
Switching</linktext></link>+
−
<link href="GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita"><linktext>Flipping+
−
and Rotating an External  Surface</linktext></link>+
−
</related-links></concept>+
−