--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,90 @@
+<?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-894AB487-C127-532D-852B-37CB0DEA1440" xml:lang="en"><title>Symbian-Specific
+Behavior</title><shortdesc>This topic provides information about the points that the EGL specification
+explicitly states are platform-specific. This information is aimed at both
+users and implementers of EGL on the Symbian platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-5F4317DF-EEDE-434C-906D-A354367AE38D"><title>Symbian windows</title> <p>EGL windows are tied to Symbian
+windows. To create an on-screen rendering surface, a Window Server window
+with attributes corresponding to the desired <codeph>EGLConfig</codeph> must
+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
+window that can be displayed and drawn to, and whose redraws are performed
+by the application. </p> <p><b>Buffer handling</b>. EGL window surfaces have
+two buffers, known as the front and back buffers. This means that the client
+application can draw to the back buffer, while the front buffer is being composed
+to the screen. The client must call <codeph>eglSwapBuffers()</codeph> to post
+the back buffer to the screen. </p><p>EGL 1.4 introduces a preserve buffer
+feature. When this is supported by the implementation, the content of the
+buffer can be preserved from one frame to the next. This means that the client
+can provide incremental drawing operations rather than the entire drawing
+operations for each frame. When the implementation supports this feature,
+it is usually off by default. This means that legacy applications that do
+not expect this feature are not slowed down by the unnecessary copying of
+the buffer contents.</p> <p><b>Window resizing</b>. A window can be resized
+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,
+the EGL implementation is expected to handle the situation by adjusting its
+internal buffers. Applications need not do anything specific with regard to
+EGL APIs. Depending on the type of application, APIs may want to adjust their
+rendering operations—for example, clip or scale the contents. </p> <p>EGL
+handles the resize in the next call to <codeph>eglSwapBuffers()</codeph> by
+creating a new surface for the resized window. If the preserve buffer option
+is in use, this function also copies across all the pixels from the old surface
+that overlap the new surface, although the exact details depend
+on the implementation. A client application may therefore need to provide
+extra drawing operations, for example, if the window is made larger.</p> <p> <b>Screen
+rotation</b>. There is no specific EGL handling for screen rotation—instead
+screen rotation is handled in the same way as a change of screen resolution.
+Applications can detect screen rotation by listening to the Window Server
+event <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>. However, applications
+do not normally use the Window Server API directly, because they are built
+on top of the UI Framework layer. This layer provides 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
+one of the these events is detected, the application may need to resize its
+windows and update its content accordingly. If the application wants to accept
+the system rotation, it does not need to rotate its content. However, some
+applications may want to maintain a fixed physical orientation. They would
+then need to rotate the window content in order to counteract the physical
+rotation. </p> </section>
+<section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian pixmap types</title> <p>An EGL implementation can
+support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer as an <codeph>EGLNativePixmapType</codeph>.
+This means that it is possible 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
+are managed by the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font
+and Bitmap Server</xref>. The format is internal to Symbian, but the Image
+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
+has limitations with regard to hardware acceleration. </p> </section>
+<section id="GUID-44553B50-C48E-4E6B-AD9C-F3BC7D9D5347"><title>Display handling</title> <p>Most EGL calls include an <codeph>EGLDisplay</codeph> parameter.
+The EGL specification describes this as "the abstract display on which graphics
+are drawn". On some systems, this corresponds to a physical screen. However,
+the details are platform specific and on Symbian systems, it does <i>not</i> correspond
+to a physical screen. When working on the Symbian platform, it is generally
+more useful to think of an <codeph>EGLDisplay</codeph> as the EGL session. </p> <p>On
+Symbian systems, you usually use a single <codeph>EGLDisplay</codeph>. You
+get this by a call to <codeph>eglGetDisplay()</codeph> and passing <codeph>EGL_DEFAULT_DISPLAY</codeph> as
+the <codeph><display id></codeph> parameter. </p> <p>The physical screen
+on which the content is displayed is determined by the window's parent window
+group. In Symbian, every window (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref>) has a parent
+window group (<xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref>), as shown in the following
+diagram. When you create a window group, you can specify the screen on which
+it is to be shown. </p> <fig id="GUID-5D5F3C6A-4CFA-5307-8B2D-D2881799D664">
+<title>Each window has a parent window group which is associated with a screen</title>
+<image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e182376_href.png" placement="inline"/>
+</fig> <p>When you create a window surface in EGL using <codeph>eglCreateWindowSurface</codeph>,
+you pass in the <codeph>RWindow</codeph> as an argument. The window surface
+is then displayed on the screen associated with that window's parent window
+group. Currently a window can exist on only one screen. </p> </section>
+</conbody><related-links>
+<link href="GUID-D252E75C-C8CA-5C51-8DA3-95B937A1295C.dita"><linktext>EGL Interface
+Component</linktext></link>
+<link href="GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita"><linktext>EGL Collection
+Overview</linktext></link>
+</related-links></concept>
\ No newline at end of file