11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-894AB487-C127-532D-852B-37CB0DEA1440" xml:lang="en"><title>Symbian-Specific |
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 |
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 |
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> |
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 |
16 <section id="GUID-5F4317DF-EEDE-434C-906D-A354367AE38D"><title>Symbian windows</title> <p>EGL |
17 windows. To create an on-screen rendering surface, a Window Server window |
17 window surfaces are tied to Symbian windows. To create an on-screen rendering |
18 with attributes corresponding to the desired <codeph>EGLConfig</codeph> must |
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 |
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 |
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 |
21 by the application. </p> <p><b>Threading</b>. Because of the limitations of |
22 two buffers, known as the front and back buffers. This means that the client |
22 the Window Server API, clients <b>must</b> create and use an EGL window surface |
23 application can draw to the back buffer, while the front buffer is being composed |
23 in the thread in which its <codeph>RWindow</codeph> was created. This means |
24 to the screen. The client must call <codeph>eglSwapBuffers()</codeph> to post |
24 that the following are <b>not</b> supported and will lead to undefined behavior:</p><ul> |
25 the back buffer to the screen. </p><p>EGL 1.4 introduces a preserve buffer |
25 <li><p>Creating an EGL window surface in thread <i>B</i> using an <codeph>RWindow</codeph> that |
26 feature. When this is supported by the implementation, the content of the |
26 was created in thread <i>A</i>. </p></li> |
27 buffer can be preserved from one frame to the next. This means that the client |
27 <li><p>Using an EGL window surface in thread <i>B</i> when that EGL window |
28 can provide incremental drawing operations rather than the entire drawing |
28 surface and its <codeph>RWindow</codeph> were created in thread <i>A</i>. </p></li> |
29 operations for each frame. When the implementation supports this feature, |
29 </ul><p>For example, in the second scenario, EGL in thread <i>B</i> may fail |
30 it is usually off by default. This means that legacy applications that do |
30 when it attempts to get the window size from the <codeph>RWindow</codeph> in |
31 not expect this feature are not slowed down by the unnecessary copying of |
31 thread <i>A</i>.</p><p><b>Buffer handling</b>. EGL window surfaces have two |
32 the buffer contents.</p> <p><b>Window resizing</b>. A window can be resized |
32 buffers, known as the front and back buffers. This means that the client application |
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, |
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, |
34 the EGL implementation is expected to handle the situation by adjusting its |
45 the EGL implementation is expected to handle the situation by adjusting its |
35 internal buffers. Applications need not do anything specific with regard to |
46 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 |
47 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 |
48 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 |
49 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 |
50 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 |
51 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 |
52 that overlap the new surface, although the exact details depend on the implementation. |
42 on the implementation. A client application may therefore need to provide |
53 A client application may therefore need to provide extra drawing operations, |
43 extra drawing operations, for example, if the window is made larger.</p> <p> <b>Screen |
54 for example, if the window is made larger.</p> <p> <b>Screen rotation</b>. |
44 rotation</b>. There is no specific EGL handling for screen rotation—instead |
55 There is no specific EGL handling for screen rotation—instead screen rotation |
45 screen rotation is handled in the same way as a change of screen resolution. |
56 is handled in the same way as a change of screen resolution. Applications |
46 Applications can detect screen rotation by listening to the Window Server |
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>. |
47 event <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>. However, applications |
58 However, applications do not normally use the Window Server API directly, |
48 do not normally use the Window Server API directly, because they are built |
59 because they are built on top of the UI Framework layer. This layer provides |
49 on top of the UI Framework layer. This layer provides a different mechanism |
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 |
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 |
61 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 |
62 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 |
63 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 |
64 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 |
65 then need to rotate the window content in order to counteract the physical |
56 rotation. </p> </section> |
66 rotation. </p> </section> |
57 <section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian pixmap types</title> <p>An EGL implementation can |
67 <section id="GUID-9BC770D9-3736-495E-8485-19D71700C50D"><title>Symbian pixmap |
58 support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer as an <codeph>EGLNativePixmapType</codeph>. |
68 types</title> <p>An EGL implementation can support the <xref href="GUID-683A1D42-2764-3EB7-BD19-9E12559199AB.dita"><apiname>CFbsBitmap</apiname></xref> pointer |
59 This means that it is possible to create an <codeph>EGLSurface</codeph> to |
69 as an <codeph>EGLNativePixmapType</codeph>. This means that it is possible |
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 |
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 |
61 are managed by the <xref href="GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita">Font |
71 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 |
72 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 |
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 |
64 has limitations with regard to hardware acceleration. </p> </section> |
74 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. |
75 <section id="GUID-44553B50-C48E-4E6B-AD9C-F3BC7D9D5347"><title>Display handling</title> <p>Most |
66 The EGL specification describes this as "the abstract display on which graphics |
76 EGL calls include an <codeph>EGLDisplay</codeph> parameter. The EGL specification |
67 are drawn". On some systems, this corresponds to a physical screen. However, |
77 describes this as "the abstract display on which graphics are drawn". On some |
68 the details are platform specific and on Symbian systems, it does <i>not</i> correspond |
78 systems, this corresponds to a physical screen. However, the details are platform |
69 to a physical screen. When working on the Symbian platform, it is generally |
79 specific and on Symbian systems, it does <i>not</i> correspond to a physical |
70 more useful to think of an <codeph>EGLDisplay</codeph> as the EGL session. </p> <p>On |
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 |
71 Symbian systems, you usually use a single <codeph>EGLDisplay</codeph>. You |
82 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 |
83 get this by a call to <codeph>eglGetDisplay()</codeph> and passing <codeph>EGL_DEFAULT_DISPLAY</codeph> as |
73 the <codeph><display id></codeph> parameter. </p> <p>The physical screen |
84 the <codeph><display id></codeph> parameter. </p> <p>The physical screen |
74 on which the content is displayed is determined by the window's parent window |
85 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 |
86 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 |
87 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 |
88 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"> |
89 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> |
90 <title>Each window has a parent window group which is associated with a screen</title> |
80 <image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e243967_href.png" placement="inline"/> |
91 <image href="GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e271870_href.png" placement="inline"/> |
81 </fig> <p>When you create a window surface in EGL using <codeph>eglCreateWindowSurface</codeph>, |
92 </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 |
93 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 |
94 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> |
95 group. Currently a window can exist on only one screen. </p> </section> |
85 </conbody><related-links> |
96 </conbody><related-links> |