|
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-0B2421FD-8431-5DDA-9FE3-046734AE495E" xml:lang="en"><title>Window |
|
13 Surface Implementation</title><shortdesc>This topic provides an introduction to implementing EGL window |
|
14 surfaces on the Symbian platform. These are used for onscreen rendering into |
|
15 windows that are provided by the Symbian platform (rather than EGL). The details |
|
16 of how to implement window surfaces depend on whether the ScreenPlay variant |
|
17 is in use. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
18 <p> <b>Target audience</b>: Device creators. </p> |
|
19 <section><title>Symbian windows</title> <p>Window surfaces are created by |
|
20 the <codeph>eglCreateWindowSurface()</codeph> function, to which is passed |
|
21 a handle to a window provided by the Symbian <xref href="GUID-2C443E6F-BC3D-5252-8098-9F850AA88A35.dita">Window |
|
22 Server</xref>. Key Window Server classes include the following: </p> <ul> |
|
23 <li id="GUID-CE332026-A8BC-57D8-B845-F0C41CCBA4C2"> <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>, |
|
24 which is a handle to a standard window. </li> |
|
25 <li id="GUID-DFC36F32-71B2-5502-B4A9-B95C6548751D"><xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>, |
|
26 which is the Window Server session class. This is required to create Window |
|
27 Server objects. </li> |
|
28 <li id="GUID-B17680DB-00AD-5B8C-8199-5E03B9CB71E8"> <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref>, |
|
29 which is a Window Server client-side object representing the screen. </li> |
|
30 </ul> </section> |
|
31 <section><title> Non-ScreenPlay </title> <p>In the non-ScreenPlay variant |
|
32 there is no composition engine and both Symbian API drawing (for example, |
|
33 through <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>) and EGL client API drawing are rendered |
|
34 to a single display. The EGL implementation can achieve this in a number of |
|
35 ways, including: </p> <ul> |
|
36 <li id="GUID-332CAE78-9EBD-5DAF-A640-FEE2CBC48B73"><p>Using Direct Screen |
|
37 Access (DSA) to render the EGL client API drawing directly to the screen. |
|
38 This is done in cooperation with the Window Server, which provides clipping |
|
39 instructions. This approach is particularly suitable when graphics acceleration |
|
40 hardware is available. </p> </li> |
|
41 <li id="GUID-646EE6E5-6194-5862-8225-9D756EA55ACC"><p>Rendering the EGL client |
|
42 API drawing to an offscreen <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> and then calling |
|
43 a Window Server API to blit the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> onto the screen, |
|
44 with any necessary clipping. </p> </li> |
|
45 </ul> </section> |
|
46 <section><title>ScreenPlay</title> <p>ScreenPlay has introduced the <xref href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita">Graphics Composition Collection</xref>, |
|
47 which enables a number of <b>surfaces</b> to be arranged in layers and to |
|
48 be composed together to produce the final output on the display. In this section, |
|
49 these surfaces are called <b>composition surfaces</b> in order to distinguish |
|
50 them from EGL surfaces. Each composition surface is mapped to memory, which |
|
51 can be specialized graphics memory for faster performance. </p> <p>All |
|
52 Window Server drawing (such as the application UI) is rendered to a composition |
|
53 surface called the <b>UI surface</b>, which is usually the topmost layer and |
|
54 can be semi-transparent. </p><p>When the EGL implementation creates an EGL |
|
55 window surface for a Symbian window (represented by <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>), |
|
56 the EGL implementation must do the following: </p><ul> |
|
57 <li id="GUID-ECAF9CD5-0770-5D51-827B-9E30A1A14478"><p>Create a new composition |
|
58 surface with the same width and height as the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> </li> |
|
59 <li id="GUID-69D40D06-D691-5DC4-8AB8-7C93F74EDAE4"><p>Position the composition |
|
60 surface in a layer below the UI layer, directly below the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>. </p> </li> |
|
61 <li id="GUID-19391759-8C65-5D17-96C7-A9155303442E"><p>Make the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> transparent |
|
62 in order for the composition surface to show through. </p> </li> |
|
63 </ul><p/><p>All of the EGL client API drawing to the EGL window surface |
|
64 is then rendered to the composition surface and the application's UI appears |
|
65 as a semi-transparent layer above it. </p><p>When a window is resized, a new |
|
66 composition surface needs to be created with the new width and height, and |
|
67 positioned as a layer below the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> in place of the |
|
68 previous composition surface. </p><p>A composition surface can have more than |
|
69 one pixel buffer associated with it (each buffer has the same dimensions). |
|
70 For an EGL window surface, the composition surface should have two buffers |
|
71 for double-buffered drawing. This means, for example, that OpenVG commands |
|
72 can draw to the <b>back buffer</b>, while the <b>front buffer</b> is being |
|
73 composed to the screen. </p> </section> |
|
74 </conbody><related-links> |
|
75 <link href="GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita"><linktext>EGL Porting |
|
76 Guide</linktext></link> |
|
77 <link href="GUID-0DC3E5AA-1706-5255-ACD6-E7AB732E1095.dita"><linktext>Graphics |
|
78 Composition Collection Overview</linktext></link> |
|
79 <link href="GUID-599C9890-3AC8-46D3-A8C3-34CAAB5A61CF.dita"><linktext>Implementing |
|
80 eglCreateWindowSurface</linktext></link> |
|
81 <link href="GUID-42984078-3DEB-41C7-AC76-C769F7CDB4D0.dita"><linktext>Implementing |
|
82 eglSwapBuffers</linktext></link> |
|
83 </related-links></concept> |