|
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-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8" xml:lang="en"><title>Display |
|
13 Control and Mapping in the Window Server Client</title><shortdesc>ScreenPlay provides support for externally connected displays, |
|
14 such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant |
|
15 consider the size of each display to be fixed, assuming it to be built into |
|
16 the phone. However, for High-Definition Multimedia Interface (HDMI) and composite |
|
17 video connectors, there is a range of resolutions that can change dynamically. |
|
18 ScreenPlay provides an optional feature that supports switching between resolutions |
|
19 at runtime and notifies Window Server clients when there are changes to the |
|
20 resolution and connectedness. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
21 <p>This topic builds on the introduction in <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic |
|
22 Resolution Switching</xref>. </p> |
|
23 <p>The <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> Window Server client-side API has |
|
24 a <codeph>GetInterface()</codeph> function, which you can use to return pointers |
|
25 to the <codeph>MDisplayControl</codeph> and <codeph>MDisplayMapping</codeph> interfaces |
|
26 or null if the interface is not supported. For example: </p> |
|
27 <codeblock id="GUID-1F87BCBD-F4FB-5C20-8B94-01088F79CD73" xml:space="preserve">// Establish connection and get display control interface. |
|
28 class CWindowClient : public CBase |
|
29 { |
|
30 ... |
|
31 RWsSession iSession; |
|
32 CWsScreenDevice* iScreenDevice; |
|
33 MDisplayControl* iDisplayControl; |
|
34 MDisplayMapping* iDisplayMapping; |
|
35 TWsDisplayChangedEvent iLastEvent; |
|
36 } |
|
37 |
|
38 void CWindowClient::ConstructL(TInt aDisplayNumber) |
|
39 { |
|
40 User::LeaveIfError(iSession.Connect()); |
|
41 iScreenDevice = new(ELeave) CWsScreenDevice(iSession); |
|
42 User::LeaveIfError(iScreenDevice->Construct(aDisplayNumber)); |
|
43 iDisplayControl = iScreenDevice->GetInterface(EDisplayControl); |
|
44 User::LeaveIfNull(iDisplayControl); |
|
45 iDisplayMapping = iScreenDevice->GetInterface(EDisplayMapping); |
|
46 User::LeaveIfNull(iDisplayMapping); |
|
47 }</codeblock> |
|
48 <p>In addition, <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> provides the <codeph>IsCurrentModeDynamic()</codeph> and <codeph>IsModeDynamic()</codeph> functions |
|
49 for querying whether the current screen mode and a given screen mode are dynamic. |
|
50 If a screen mode is dynamic, the application extent always fills the full |
|
51 UI space and the area returned by <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-8E1B5729-FD1C-3D4A-AC73-C6364E7D5BBF"><apiname>CWsScreenDevice::SizeInPixels()</apiname></xref> always |
|
52 matches the actual resolution that is in use. However, the <codeph>MDisplayMapping</codeph> interface |
|
53 also provides features that enable you to draw outside the application UI |
|
54 extent. </p> |
|
55 <section id="GUID-00B91456-0C70-468E-8974-17DE3836849C"> <title>MDisplayControl</title> <p>The <xref href="GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11.dita"><apiname>MDisplayControl</apiname></xref> interface |
|
56 provides Window Server clients with functions for setting and getting the |
|
57 current display configuration, getting a list of available resolutions and |
|
58 enabling display change event notifications (<codeph>EEventDisplayChanged</codeph>). |
|
59 The following diagram shows the class hierarchy. </p> <fig id="GUID-F9D95387-151F-5725-8BDD-C44A3D333A97"> |
|
60 <title> Display control class diagram </title> |
|
61 <image href="GUID-68E3609C-3429-5B1C-B8D9-C0EBBACEF357_d0e193491_href.png" placement="inline"/> |
|
62 </fig> <p>Once you have obtained |
|
63 the <xref href="GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11.dita"><apiname>MDisplayControl</apiname></xref> interface, you can call <codeph>GetResolutions()</codeph> on |
|
64 it. For example: </p> <codeblock id="GUID-C82D0166-0E29-5F90-8087-800EDDE2D895" xml:space="preserve">// Get available resolutions |
|
65 RArray<MDisplayControl::TResolution> resolutions; |
|
66 User::LeaveIfError(iDisplayControl->GetResolutions(resolutions)); |
|
67 |
|
68 // Use resolution list. |
|
69 |
|
70 </codeblock> <p>You can use the <codeph>EnableDisplayChangedEvents()</codeph> function |
|
71 to register for notifications of the <codeph>EEventDisplayChanged</codeph> event. |
|
72 This is generated when the display device is attached or detached or there |
|
73 is a change in the current resolution, the resolution list or the current |
|
74 configuration. For example, this can be generated by a render stage or the |
|
75 composition engine in response to a hardware event (such as an external display |
|
76 being connected or disconnected). The event is sometimes, but not always, |
|
77 triggered by a change in the screen mode. </p> <p>There are therefore two |
|
78 aspects to the event in that it can be triggered by a display change or a |
|
79 configuration change. Typically you check the event against the previous one |
|
80 to see what has changed. </p> <p>The following table provides a summary of |
|
81 how this event compares to <codeph>EEventScreenDeviceChanged</codeph>. </p> <table id="GUID-50D8232A-E394-590F-A762-79567E4424C3"> |
|
82 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
83 <thead> |
|
84 <row> |
|
85 <entry>Action</entry> |
|
86 <entry><codeph>EEventScreenDeviceChanged</codeph> </entry> |
|
87 <entry><codeph>EEventDisplayChanged</codeph> </entry> |
|
88 </row> |
|
89 </thead> |
|
90 <tbody> |
|
91 <row> |
|
92 <entry><p>Screen mode change </p> </entry> |
|
93 <entry><p>Always triggers this event </p> </entry> |
|
94 <entry><p>Triggers this event only if it causes a change in the configuration. </p> </entry> |
|
95 </row> |
|
96 <row> |
|
97 <entry><p>Display configuration change </p> </entry> |
|
98 <entry><p>Generally does not trigger this event </p> </entry> |
|
99 <entry><p>Generally triggers this event </p> </entry> |
|
100 </row> |
|
101 </tbody> |
|
102 </tgroup> |
|
103 </table> <p>The following example first registers for notification of <codeph>EEventDisplayChanged</codeph> events |
|
104 and then changes the screen mode. The second part illustrates a simplified |
|
105 handler for the events. It demonstrates checking the event against the previous |
|
106 one to see whether the resolution or configuration has changed. </p> <codeblock id="GUID-E78D2CA8-4C1E-5E19-92EC-7E87B010E5BE" xml:space="preserve">// Establish connection and get display control interface. |
|
107 |
|
108 iDisplayControl->EnableDisplayChangeEvents(ETrue); |
|
109 |
|
110 iScreenDevice->SetScreenMode(2); // Number depends on WSINI.INI config. |
|
111 iScreenDevice->SetAppScreenMode(2); // Ensure application windows are |
|
112 // shown in the new mode. |
|
113 ... |
|
114 |
|
115 // Simplified event handler. |
|
116 TWsEvent event; |
|
117 iSession.GetEvent(event); |
|
118 |
|
119 switch (event.Type()) |
|
120 { |
|
121 case EEventScreenDeviceChanged: |
|
122 { |
|
123 TSize screenSize = iScreenDevice->SizeInPixels(); |
|
124 // Re-layout windows for new application screen dimensions |
|
125 } |
|
126 break; |
|
127 case Redraw: |
|
128 { |
|
129 // Draw content of window |
|
130 } |
|
131 break; |
|
132 case EEventDisplayChanged: |
|
133 { |
|
134 TWsDisplayChangedEvent* newEvent; |
|
135 newEvent = event.DisplayChanged(); |
|
136 |
|
137 if (newEvent->iResolutionListChangeId != |
|
138 iLastEvent.iResolutionListChangeId) |
|
139 { |
|
140 // ... |
|
141 } |
|
142 |
|
143 if (newEvent->iConfigurationChangeId != |
|
144 iLastEvent.iConfigurationChangeId) |
|
145 { |
|
146 TDisplayConfiguration config; |
|
147 User::LeaveIfError( |
|
148 iDisplayControl->GetConfiguration(config))); |
|
149 // Handle updated configuration |
|
150 // May be entirely handled by screen device changed event |
|
151 } |
|
152 iLastEvent = *newEvent; |
|
153 } |
|
154 break; |
|
155 }</codeblock> <p>Here is an example of setting a new display resolution: </p> <codeblock id="GUID-B9C0254D-3990-5B41-9F63-1A81D30A3FB6" xml:space="preserve">TDisplayConfiguration config; |
|
156 config.SetResolution(TSize(1280, 720)); |
|
157 config.SetRotation(MDisplayControl::ERotation180); |
|
158 |
|
159 User::LeaveIfError(iDisplayControl->SetConfiguration(config)); |
|
160 </codeblock> </section> |
|
161 <section id="GUID-EF610977-6881-4542-AEFF-C562A7022B21"> <title>MDisplayMapping</title> <p>The <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface |
|
162 enables Window Server clients to map between coordinate spaces, allowing for |
|
163 translation and scaling of coordinates. For example, suppose an application |
|
164 is to draw a virtual keyboard outside of the application's extent. This requires |
|
165 knowing the extent of both the application and the full UI area. The application |
|
166 can use the <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface to get this information, |
|
167 so that the virtual keyboard can be drawn within the full UI area but outside |
|
168 of the application's extent. </p> <fig id="GUID-55BD49C6-9A51-53A7-A587-29A151FACF6B"> |
|
169 <title> Display mapping class diagram </title> |
|
170 <image href="GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e193629_href.png" placement="inline"/> |
|
171 </fig> <p> </p> <p>The <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface is very |
|
172 flexible. UIDs are used to signify the application UI coordinate space, the |
|
173 full UI space, the composition/display coordinate space (which may be a different |
|
174 scale to the UI coordinate space) and the Direct Screen Access (DSA) space |
|
175 (which may match the full UI space, or be offset relative to the application |
|
176 UI space). </p> <p>The <codeph>MapCoordinates()</codeph> function |
|
177 takes a rectangle, a source space and a target space and returns the correspondingly |
|
178 mapped rectangle in the target space. To map a point, use a rectangle with |
|
179 a width and height of one pixel, because the scaling between UI space and |
|
180 composition/display space may enlarge (or sometimes reduce) the rectangle’s |
|
181 size. </p> <p>For example, consider the following diagram, in which the outer |
|
182 rectangle represents the display area and the inner one represents the application |
|
183 space (screen mode). </p> <fig id="GUID-6935A7BE-C651-5582-8E2A-11A18CDD531F"> |
|
184 <title>Display area and application extent </title> |
|
185 <image href="GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e193658_href.png" placement="inline"/> |
|
186 </fig> <p>The display resolution is 1280 x 720, the application size is 176 |
|
187 x 208 and a virtual resolution of 426 x 240 has been introduced, which gives |
|
188 a scaling factor of three in each direction. All pixels are approximately |
|
189 square, for simplicity. The application area has been centered in the display, |
|
190 giving an <i>X</i> offset of (426-176)/2 and a <i>Y</i> offset of (240-208)/2, |
|
191 or (125, 16). </p> <p>To put a window on screen to fill the display, create |
|
192 a rectangle positioned at (0,0) with a size of the current resolution (426 |
|
193 x 240). Then pass this in with a source space of the full UI and target space |
|
194 of the application. This results in a rectangle of the same size but at offset |
|
195 (125,16). </p> <p>In addition, to use an external surface at the real resolution, |
|
196 pass this rectangle in with a source space of the application UI and a target |
|
197 space of the composition/display. This results in a rectangle with size of |
|
198 1280 x 720, which you can then use when creating the surface. Because the |
|
199 UI surface and external surface are scaled independently, the UI memory requirements |
|
200 can remain low, even with high resolution video, viewfinder and games. For |
|
201 an example code snippet, see <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External |
|
202 Surfaces Overview</xref>. </p> </section> |
|
203 </conbody><related-links> |
|
204 <link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server |
|
205 Client-Side Library Concepts</linktext></link> |
|
206 <link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution |
|
207 Switching</linktext></link> |
|
208 <link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini |
|
209 File Reference</linktext></link> |
|
210 </related-links></concept> |