|
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-495EA1C8-E95F-54AE-B4D1-0F463003C2D7" xml:lang="en"><title>External |
|
13 Surfaces Overview</title><shortdesc>This topic provides an introduction to displaying an external surface |
|
14 on a window. The surface is then known as a background surface. This feature |
|
15 is available in ScreenPlay only. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target |
|
17 audience</b>: Device creators. </p> |
|
18 <p>There are two main use cases for using external surfaces in this way. One |
|
19 is to display a video, in which case DevVideo renders the content. The other |
|
20 main use case is an OpenGL ES background surface, in which case the client |
|
21 issues OpenGL ES rendering commands. This topic covers how to get the surface |
|
22 onto the screen and not rendering the content to the surface. </p> |
|
23 <section><title> Key concepts</title> <p>The following diagram illustrates |
|
24 some of the key concepts that are used in the documentation of surfaces. </p> <fig id="GUID-F134C262-EC19-5925-A188-2C7C2CD5EEEA"> |
|
25 <title>Composition of the UI surface and an external surface, showing the |
|
26 viewport and extent</title> |
|
27 <image href="GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e199962_href.png" placement="inline"/> |
|
28 </fig> <dl> |
|
29 <dlentry> |
|
30 <dt>Graphics surface</dt> |
|
31 <dd><p>A graphics surface (usually simply called a <i>surface</i>) is a hardware-independent |
|
32 memory buffer for holding an image or part of a scene. A surface has a set |
|
33 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> |
|
34 </dlentry> |
|
35 <dlentry> |
|
36 <dt>UI surface</dt> |
|
37 <dd><p>The UI surface is a special surface onto which the Window Server renders |
|
38 all of the UI content. It is created automatically during system start up |
|
39 and corresponds to the frame buffer in the non-ScreenPlay variant. The UI |
|
40 surface is semi-transparent and is always the topmost layer.</p> </dd> |
|
41 </dlentry> |
|
42 <dlentry> |
|
43 <dt>External surface</dt> |
|
44 <dd><p>An external surface is any surface other than the UI surface—for example, |
|
45 a surface that holds a video or to which OpenGL ES content is rendered. External |
|
46 surfaces are always opaque. When an external surface is attached to a window, |
|
47 the Window Server creates a transparent hole in the UI surface to reveal the |
|
48 external surface. </p> </dd> |
|
49 </dlentry> |
|
50 <dlentry> |
|
51 <dt>Viewport</dt> |
|
52 <dd><p>The viewport is a rectangular area of an external surface all or part |
|
53 of which is to be displayed. You can think of the viewport as the source. </p> </dd> |
|
54 </dlentry> |
|
55 <dlentry> |
|
56 <dt>Extent</dt> |
|
57 <dd><p>The extent is a rectangular area in the composition scene in which |
|
58 all or part of the viewport is placed. The content of the viewport can be |
|
59 scaled and rotated within the extent relative to its normal size and orientation. |
|
60 The extent is normally a window to which the external surface is attached. </p> </dd> |
|
61 </dlentry> |
|
62 </dl> <p>The following diagram provides a cross-section view through the surfaces |
|
63 shown in the previous figure. Notice that the UI surface is the topmost layer |
|
64 and that it contains a hole through which the external surface |
|
65 can be seen.</p> <fig id="GUID-4DB99814-988F-5D51-A1A7-E864B6DA6DFB"> |
|
66 <title> A cross section through the surfaces, showing the display |
|
67 output </title> |
|
68 <image href="GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e200040_href.png" placement="inline"/> |
|
69 </fig> </section> |
|
70 <section id="GUID-F9D7659B-1325-5DC2-9D7A-9B6C0DFB8A62"><title>Supported Uses</title> <p>You |
|
71 can: </p> <ul> |
|
72 <li id="GUID-97CAD13E-1C70-59FF-B271-F3E77198086A"><p>Display an external |
|
73 surface (for example, video content or a viewfinder image) within a window. </p> </li> |
|
74 <li id="GUID-BD8FFB28-D56C-581B-9E1C-B2BD97FDAFBC"><p>Dynamically set or remove |
|
75 a background surface across multiple windows on the same screen without having |
|
76 to register and unregister the surface. This reduces resource churn and content |
|
77 transfer. </p> </li> |
|
78 <li id="GUID-0A3FD92E-7E99-5961-BC5A-3FBB970A7889"><p>Reconfigure the attributes |
|
79 of the surface such as its extent, viewport and orientation, after it is set |
|
80 as a background. </p> </li> |
|
81 <li id="GUID-6E962607-1E7D-516E-B855-15A1A67923B6"><p>Reposition the displayed |
|
82 surface on the window. </p> </li> |
|
83 <li id="GUID-26E561E7-92BB-5EBA-A3B9-F660507A258D"><p>Zoom in and out of the |
|
84 contents of the surface. </p> </li> |
|
85 <li id="GUID-287D3286-209B-5E01-B1C6-2373A2B07172"><p>Place the surface content |
|
86 in a specified window area rather than filling the entire window. </p> </li> |
|
87 <li id="GUID-6F2DCF0C-32D7-53CD-A2DD-4DBE662015B5"><p>Crop the surface content |
|
88 rather than using the entire surface. </p> </li> |
|
89 <li id="GUID-8E49A7FB-0709-5127-8C94-104C512EA6AC"><p>Rotate the contents |
|
90 of the background surface by quadrant angles. </p> </li> |
|
91 <li id="GUID-5631047A-A8AD-59DF-82FF-021964BA571D"><p>Flip the background |
|
92 surface from top to bottom and rotate it by 180° to achieve a mirroring effect. </p> </li> |
|
93 </ul> <p>The following diagrams shows some surface configuration use cases. </p> <fig id="GUID-FF25ED24-7A3D-5C4B-A711-D6AEA53E972F"> |
|
94 <title> Surface configuration use cases </title> |
|
95 <image href="GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e200107_href.png" placement="inline"/> |
|
96 </fig> </section> |
|
97 <section id="GUID-7EAB8F5D-6290-5B63-B396-8A1FAE7D91A5"><title> Configuration</title> <p>There |
|
98 are a number of ways in which dynamically updated content can be configured |
|
99 to appear on a window. </p> <p><b>A single content surface filling the window </b> </p> <p>External |
|
100 content can be fitted onto a Window Server window. Each axis of the surface |
|
101 can be stretched independently of the other axis. The window must be a visible |
|
102 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 |
|
103 of a single surface on a selected area of the window </b> </p> <p>The position |
|
104 and display size for the external content can be specified as an area within |
|
105 the Window Server window, rather than filling the window. The window must |
|
106 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>) |
|
107 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 |
|
108 TRect& aExtent)</apiname></xref>. </p> <p>After the extent is specified, |
|
109 its size does not change if the window size changes but its position moves |
|
110 to maintain its relative position on the window. </p> <p><b>Clipping of a |
|
111 surface </b> </p> <p>Video sometimes needs to appear cropped, so that a sub-area |
|
112 of the video is displayed instead of the full image. The crop viewport is |
|
113 specified in surface co-ordinates. The cropped viewport fills the output extent |
|
114 (or the window when the extent is not specified). The content appears scaled |
|
115 if the size of the viewport does not match the size of the extent (or the |
|
116 window). </p> <p><b>Scaling </b> </p> <p>It is possible to arbitrarily scale |
|
117 a surface to user specifications using the extent and viewport features. Each |
|
118 axis is scaled independently. When the extent and viewport are coincident, |
|
119 no scaling occurs. Filtering can be applied by the implementation of stretching |
|
120 and shrinking. </p> <p><b>Rotation </b> </p> <p>The viewport can be displayed |
|
121 rotated relative to its normal orientation. For example, if there is a fixed |
|
122 camera on the front of a device and the device is rotated by 90°, the image |
|
123 captured by the camera needs to be rotated by 90° in the other direction to |
|
124 get the expected result. The orientation is always relative to the current |
|
125 device orientation. </p> <p><b>Flipping </b> </p> <p>An external surface can |
|
126 be flipped from top to bottom around the x axis. </p> <p><b>Atomic combination |
|
127 of these operations </b> </p> <p>All the above mentioned configurations can |
|
128 be specified and combined unambiguously for a particular content on a particular |
|
129 window. You can specify parameters for a combination of these configurations |
|
130 in a single operation. </p> <p><b>Changing surfaces </b> </p> <p>The surface |
|
131 assigned to a window can be changed. </p> <p><b>Reconfiguring </b> </p> <p>It |
|
132 is possible to change the configuration options applied to a surface without |
|
133 re-assigning the surface. </p> <p><b>Sharing surfaces </b> </p> <p>Content |
|
134 surfaces are transferable and sharable between windows. </p> <p>The initial |
|
135 registration step ensures that any resources allocated to the content surface |
|
136 are held while the surface is removed from one window and added to another. |
|
137 This reduces the likelihood of failure between operations. </p> </section> |
|
138 <section><title>API Summary</title> <p>This section provides a summary of |
|
139 the classes and functions that you use to manage surfaces: </p> <ul> |
|
140 <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> |
|
141 <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> |
|
142 <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> |
|
143 </ul> </section> |
|
144 <section id="GUID-3E1EF2ED-7E9C-541F-A439-F2CBA5B6F211"><title>RWindowBase </title> <ul> |
|
145 <li id="GUID-7A5D0A6F-C0B6-5D87-B0F4-99C92FA8227B"><p> <codeph>SetBackgroundSurface(const |
|
146 TSurfaceConfiguration &,TBool)</codeph> sets the background |
|
147 of the window to be a given surface. The <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref> argument |
|
148 contains the surface ID and the configuration attributes. Another form of |
|
149 the function simply takes a surface ID as an argument, which provides less |
|
150 control and auto-stretches the surface to fill the window. </p> </li> |
|
151 <li id="GUID-C86F37F7-5017-56F3-9B14-E3B8E0EC0E8A"><p> <codeph>RemoveBackgroundSurface()</codeph> removes |
|
152 any background surface that has been set to the window. </p> </li> |
|
153 <li id="GUID-11ABFBDE-556F-5096-810E-6BBA2C81C4B1"><p> <codeph>GetBackgroundSurface()</codeph> retrieves |
|
154 a copy of the current configuration for the background surface attached to |
|
155 the window. </p> </li> |
|
156 </ul> <p>See <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>. </p> </section> |
|
157 <section id="GUID-1DC9E4DF-248F-59A6-92A9-F756F73414B3"><title> TSurfaceConfiguration</title> <p>This |
|
158 class encapsulates the surface configuration attributes that can be specified |
|
159 while setting the background surface of a window. If the values for the attributes |
|
160 are not set, the default values for the corresponding attribute are used. </p> <p>Symbian |
|
161 recommends that the client validates the surface configuration data before |
|
162 passing it on to the server. Invalid data that inadvertently slips through |
|
163 the client-side validation mechanism, or maliciously bypasses it, causes a |
|
164 panic. </p> <p>See <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref>. </p> </section> |
|
165 <section id="GUID-E2A62988-58F8-5021-BA44-25AE3C3D95B5"><title> RWsSession</title> <ul> |
|
166 <li id="GUID-B1A1CE19-6E12-5BA7-B79A-A6D7C44F5920"><p> <codeph>RegisterSurface()</codeph> registers |
|
167 a surface for use in composition on the screen associated with this device |
|
168 within this session. </p> </li> |
|
169 <li id="GUID-6678C53D-F0B5-5ADD-BCC7-43FC31E81FEE"><p> <codeph>UnregisterSurface()</codeph> removes |
|
170 the surface from the session’s register of surfaces that are used in composition |
|
171 on the screen associated with this device. </p> </li> |
|
172 <li id="GUID-9F5FF304-794C-5BC3-B16E-F036C859F1E2"><p> <codeph>PreferredSurfaceConfigurationSize()</codeph> returns |
|
173 the window server’s preferred size for the <codeph>TSurfaceConfiguration</codeph> object, |
|
174 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> |
|
175 </ul> <p>See <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. </p> </section> |
|
176 <section><title>Example</title> <p>This code snippet is provided for illustrative |
|
177 purposes only. A Window Server client application wants to run a 3D game full-screen |
|
178 at the native physical resolution of the display (either current or selected |
|
179 using a display controlling system application). This example assumes that |
|
180 the <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface has already been obtained, |
|
181 as shown in <xref href="GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita">Display |
|
182 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. |
|
183 RWindowGroup group = RWindowGroup(iSession); |
|
184 RWindow window(iSession); |
|
185 |
|
186 group.Construct(1, iScreenDevice); |
|
187 window.Construct(group, 2); |
|
188 |
|
189 TRect winExtent; |
|
190 iDisplayMapping.GetMaximumWindowExtent(winExtent); |
|
191 window.SetExtent(winExtent); |
|
192 |
|
193 // Map window size to composition coordinates |
|
194 TRect surfaceExtent; |
|
195 iDisplayMapping.MapCoordinates(EApplicationSpace, winExtent, |
|
196 ECompositionSpace, surfaceExtent); |
|
197 |
|
198 RSurfaceManager::TSurfaceCreationAttributes attribs; |
|
199 attribs.iSize = surfaceExtent.Size(); |
|
200 |
|
201 // Set up other attributes and create surface |
|
202 |
|
203 window.SetBackgroundSurface(surface); |
|
204 |
|
205 window.Activate(); |
|
206 </codeblock> <p>A similar approach can be used by other surface content providers, |
|
207 such as video. </p> </section> |
|
208 </conbody><related-links> |
|
209 <link href="GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita"><linktext>Graphics |
|
210 Composition</linktext></link> |
|
211 |
|
212 <link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server |
|
213 Client-Side Library Concepts</linktext></link> |
|
214 <link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution |
|
215 Switching</linktext></link> |
|
216 <link href="GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita"><linktext>Flipping |
|
217 and Rotating an External Surface</linktext></link> |
|
218 </related-links></concept> |