|
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-894AB487-C127-532D-852B-37CB0DEA1440" xml:lang="en"><title>Symbian-Specific |
|
13 Behavior</title><shortdesc>This topic provides information about the points that the EGL specification |
|
14 explicitly states are platform-specific. This information is aimed at both |
|
15 users and implementers of EGL on the Symbian platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <section id="GUID-5F4317DF-EEDE-434C-906D-A354367AE38D"><title>Symbian windows</title> <p>EGL |
|
17 window surfaces are tied to Symbian windows. To create an on-screen rendering |
|
18 surface, a Window Server window with attributes corresponding to the desired <codeph>EGLConfig</codeph> must |
|
19 be created first. The <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> class is a handle to a server-side |
|
20 window that can be displayed and drawn to, and whose redraws are performed |
|
21 by the application. </p> <p><b>Threading</b>. Because of the limitations of |
|
22 the Window Server API, clients <b>must</b> create and use an EGL window surface |
|
23 in the thread in which its <codeph>RWindow</codeph> was created. This means |
|
24 that the following are <b>not</b> supported and will lead to undefined behavior:</p><ul> |
|
25 <li><p>Creating an EGL window surface in thread <i>B</i> using an <codeph>RWindow</codeph> that |
|
26 was created in thread <i>A</i>. </p></li> |
|
27 <li><p>Using an EGL window surface in thread <i>B</i> when that EGL window |
|
28 surface and its <codeph>RWindow</codeph> were created in thread <i>A</i>. </p></li> |
|
29 </ul><p>For example, in the second scenario, EGL in thread <i>B</i> may fail |
|
30 when it attempts to get the window size from the <codeph>RWindow</codeph> in |
|
31 thread <i>A</i>.</p><p><b>Buffer handling</b>. EGL window surfaces have two |
|
32 buffers, known as the front and back buffers. This means that the client application |
|
33 can draw to the back buffer, while the front buffer is being composed to the |
|
34 screen. The client must call <codeph>eglSwapBuffers()</codeph> to post the |
|
35 back buffer to the screen. </p><p>EGL 1.4 introduces a preserve buffer feature. |
|
36 When this is supported by the implementation, the content of the buffer can |
|
37 be preserved from one frame to the next. This means that the client can provide |
|
38 incremental drawing operations rather than the entire drawing operations for |
|
39 each frame. When the implementation supports this feature, it is usually off |
|
40 by default. This means that legacy applications that do not expect |
|
41 this feature are not slowed down by the unnecessary copying of the buffer |
|
42 contents.</p> <p><b>Window resizing</b>. A window can be resized using one |
|
43 of the Window Server or UI Framework APIs, such as <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-BCD76117-54A3-3CD5-8911-E867512BF85B"><apiname>RWindow::SetExtent()</apiname></xref> or <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-B680C675-2146-3162-AAAC-F3E88FA8B045"><apiname>CCoeControl::SetExtent()</apiname></xref>. |
|
44 When these APIs are called on a window that is bound to an EGL window surface, |
|
45 the EGL implementation is expected to handle the situation by adjusting its |
|
46 internal buffers. Applications need not do anything specific with regard to |
|
47 EGL APIs. Depending on the type of application, APIs may want to adjust their |
|
48 rendering operations—for example, clip or scale the contents. </p> <p>EGL |
|
49 handles the resize in the next call to <codeph>eglSwapBuffers()</codeph> by |
|
50 creating a new surface for the resized window. If the preserve buffer option |
|
51 is in use, this function also copies across all the pixels from the old surface |
|
52 that overlap the new surface, although the exact details depend on the implementation. |
|
53 A client application may therefore need to provide extra drawing operations, |
|
54 for example, if the window is made larger.</p> <p> <b>Screen rotation</b>. |
|
55 There is no specific EGL handling for screen rotation—instead screen rotation |
|
56 is handled in the same way as a change of screen resolution. Applications |
|
57 can detect screen rotation by listening to the Window Server event <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>. |
|
58 However, applications do not normally use the Window Server API directly, |
|
59 because they are built on top of the UI Framework layer. This layer provides |
|
60 a different mechanism to notify applications using—for example, <xref href="GUID-3AC2CDAC-0291-309F-A020-049BC9F2CF90.dita#GUID-3AC2CDAC-0291-309F-A020-049BC9F2CF90/GUID-5723655E-FC84-35F1-A0E1-FCE92CEBC196"><apiname>CCoeAppUi::HandleScreenDeviceChangedL()</apiname></xref>. </p> <p>When |
|
61 one of the these events is detected, the application may need to resize its |
|
62 windows and update its content accordingly. If the application wants to accept |
|
63 the system rotation, it does not need to rotate its content. However, some |
|
64 applications may want to maintain a fixed physical orientation. They would |
|
65 then need to rotate the window content in order to counteract the physical |
|
66 rotation. </p> </section> |
|
67 <section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian pixmap |
|
68 types</title> <p>An EGL implementation can support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer |
|
69 as an <codeph>EGLNativePixmapType</codeph>. This means that it is possible |
|
70 to create an <codeph>EGLSurface</codeph> to render to a <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref>. </p> <p> <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> bitmaps |
|
71 are managed by the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font |
|
72 and Bitmap Server</xref>. The format is internal to Symbian, but the Image |
|
73 Converter API can be used to convert them to standard formats. The <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> type |
|
74 has limitations with regard to hardware acceleration. </p> </section> |
|
75 <section id="GUID-44553B50-C48E-4E6B-AD9C-F3BC7D9D5347"><title>Display handling</title> <p>Most |
|
76 EGL calls include an <codeph>EGLDisplay</codeph> parameter. The EGL specification |
|
77 describes this as "the abstract display on which graphics are drawn". On some |
|
78 systems, this corresponds to a physical screen. However, the details are platform |
|
79 specific and on Symbian systems, it does <i>not</i> correspond to a physical |
|
80 screen. When working on the Symbian platform, it is generally more useful |
|
81 to think of an <codeph>EGLDisplay</codeph> as the EGL session. </p> <p>On |
|
82 Symbian systems, you usually use a single <codeph>EGLDisplay</codeph>. You |
|
83 get this by a call to <codeph>eglGetDisplay()</codeph> and passing <codeph>EGL_DEFAULT_DISPLAY</codeph> as |
|
84 the <codeph><display id></codeph> parameter. </p> <p>The physical screen |
|
85 on which the content is displayed is determined by the window's parent window |
|
86 group. In Symbian, every window (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>) has a parent |
|
87 window group (<xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>), as shown in the following |
|
88 diagram. When you create a window group, you can specify the screen on which |
|
89 it is to be shown. </p> <fig id="GUID-5D5F3C6A-4CFA-5307-8B2D-D2881799D664"> |
|
90 <title>Each window has a parent window group which is associated with a screen</title> |
|
91 <image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e211044_href.png" placement="inline"/> |
|
92 </fig> <p>When you create a window surface in EGL using <codeph>eglCreateWindowSurface</codeph>, |
|
93 you pass in the <codeph>RWindow</codeph> as an argument. The window surface |
|
94 is then displayed on the screen associated with that window's parent window |
|
95 group. Currently a window can exist on only one screen. </p> </section> |
|
96 </conbody><related-links> |
|
97 <link href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita"><linktext>EGL Interface |
|
98 Component</linktext></link> |
|
99 <link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL Collection |
|
100 Overview</linktext></link> |
|
101 </related-links></concept> |