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 windows are tied to Symbian

    17 windows. To create an on-screen rendering surface, a Window Server window

    18 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>Buffer handling</b>. EGL window surfaces have

    22 two buffers, known as the front and back buffers. This means that the client

    23 application can draw to the back buffer, while the front buffer is being composed

    24 to the screen. The client must call <codeph>eglSwapBuffers()</codeph> to post

    25 the back buffer to the screen. </p><p>EGL 1.4 introduces a preserve buffer

    26 feature. When this is supported by the implementation, the content of the

    27 buffer can be preserved from one frame to the next. This means that the client

    28 can provide incremental drawing operations rather than the entire drawing

    29 operations for each frame. When the implementation supports this feature,

    30 it is usually off by default. This means that legacy applications that do

    31 not expect this feature are not slowed down by the unnecessary copying of

    32 the buffer contents.</p> <p><b>Window resizing</b>. A window can be resized

    33 using one 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>. When these APIs are called on a window that is bound to an EGL window surface,

    34 the EGL implementation is expected to handle the situation by adjusting its

    35 internal buffers. Applications need not do anything specific with regard to

    36 EGL APIs. Depending on the type of application, APIs may want to adjust their

    37 rendering operations—for example, clip or scale the contents. </p> <p>EGL

    38 handles the resize in the next call to <codeph>eglSwapBuffers()</codeph> by

    39 creating a new surface for the resized window. If the preserve buffer option

    40 is in use, this function also copies across all the pixels from the old surface

    41 that overlap the new surface, although the exact details depend

    42 on the implementation. A client application may therefore need to provide

    43 extra drawing operations, for example, if the window is made larger.</p> <p> <b>Screen

    44 rotation</b>. There is no specific EGL handling for screen rotation—instead

    45 screen rotation is handled in the same way as a change of screen resolution.

    46 Applications can detect screen rotation by listening to the Window Server

    47 event <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>. However, applications

    48 do not normally use the Window Server API directly, because they are built

    49 on top of the UI Framework layer. This layer provides a different mechanism

    50 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

    51 one of the these events is detected, the application may need to resize its

    52 windows and update its content accordingly. If the application wants to accept

    53 the system rotation, it does not need to rotate its content. However, some

    54 applications may want to maintain a fixed physical orientation. They would

    55 then need to rotate the window content in order to counteract the physical

    56 rotation. </p> </section>

    57 <section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian pixmap types</title> <p>An EGL implementation can

    58 support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer as an <codeph>EGLNativePixmapType</codeph>.

    59 This means that it is possible to create an <codeph>EGLSurface</codeph> to

    60 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

    61 are managed by the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font

    62 and Bitmap Server</xref>. The format is internal to Symbian, but the Image

    63 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

    64 has limitations with regard to hardware acceleration. </p> </section>

    65 <section id="GUID-44553B50-C48E-4E6B-AD9C-F3BC7D9D5347"><title>Display handling</title> <p>Most EGL calls include an <codeph>EGLDisplay</codeph> parameter.

    66 The EGL specification describes this as "the abstract display on which graphics

    67 are drawn". On some systems, this corresponds to a physical screen. However,

    68 the details are platform specific and on Symbian systems, it does <i>not</i> correspond

    69 to a physical screen. When working on the Symbian platform, it is generally

    70 more useful to think of an <codeph>EGLDisplay</codeph> as the EGL session. </p> <p>On

    71 Symbian systems, you usually use a single <codeph>EGLDisplay</codeph>. You

    72 get this by a call to <codeph>eglGetDisplay()</codeph> and passing <codeph>EGL_DEFAULT_DISPLAY</codeph> as

    73 the <codeph>&lt;display id&gt;</codeph> parameter. </p> <p>The physical screen

    74 on which the content is displayed is determined by the window's parent window

    75 group. In Symbian, every window (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>) has a parent

    76 window group (<xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>), as shown in the following

    77 diagram. When you create a window group, you can specify the screen on which

    78 it is to be shown. </p> <fig id="GUID-5D5F3C6A-4CFA-5307-8B2D-D2881799D664">

    79 <title>Each window has a parent window group which is associated with a screen</title>

    80 <image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e182376_href.png" placement="inline"/>

    81 </fig> <p>When you create a window surface in EGL using <codeph>eglCreateWindowSurface</codeph>,

    82 you pass in the <codeph>RWindow</codeph> as an argument. The window surface

    83 is then displayed on the screen associated with that window's parent window

    84 group. Currently a window can exist on only one screen. </p> </section>

    85 </conbody><related-links>

    86 <link href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita"><linktext>EGL Interface

    87 Component</linktext></link>

    88 <link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL Collection

    89 Overview</linktext></link>

    90 </related-links></concept>