|
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 <xref href="GUID-49DCA149-A46F-3DB1-9879-AEDDFE1746B9.dita"><apiname>GetInterface()</apiname></xref> function, which you can use to return |
|
25 pointers 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 <xref href="GUID-01040953-1D8A-3DD8-B3E4-047C29F7BAAC.dita"><apiname>IsCurrentModeDynamic()</apiname></xref> and <xref href="GUID-259598EF-8A53-3EED-8A4D-E24038B902F2.dita"><apiname>IsModeDynamic()</apiname></xref> 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> <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 (<xref href="GUID-6426E0A6-35F2-3704-962C-0A8AE8AF7226.dita"><apiname>EEventDisplayChanged</apiname></xref>). |
|
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_d0e211210_href.png" placement="inline"/> |
|
62 </fig> <p>For a diagram of the <xref href="GUID-7ED11E23-6E13-36D4-BB10-8AE9E745C560.dita"><apiname>TDisplayConfiguration</apiname></xref> class |
|
63 hierarchy, see the <xref href="GUID-19C3DA8C-0128-5172-B859-4FD6F6197451.dita">Common |
|
64 Graphics Headers Component Overview</xref>. </p> <p>Once you have obtained |
|
65 the <xref href="GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11.dita"><apiname>MDisplayControl</apiname></xref> interface, you can call <xref href="GUID-B50897AC-CF6F-3887-9475-A46A7C86A42D.dita"><apiname>GetResolutions()</apiname></xref> on |
|
66 it. For example: </p> <codeblock id="GUID-C82D0166-0E29-5F90-8087-800EDDE2D895" xml:space="preserve">// Get available resolutions |
|
67 RArray<MDisplayControl::TResolution> resolutions; |
|
68 User::LeaveIfError(iDisplayControl->GetResolutions(resolutions)); |
|
69 |
|
70 // Use resolution list. |
|
71 |
|
72 </codeblock> <p>You can use the <xref href="GUID-66F4BAEC-13F4-3617-B86A-5BD3BCAB82A0.dita"><apiname>EnableDisplayChangedEvents()</apiname></xref> function |
|
73 to register for notifications of the <xref href="GUID-6426E0A6-35F2-3704-962C-0A8AE8AF7226.dita"><apiname>EEventDisplayChanged</apiname></xref> event. |
|
74 This is generated when the display device is attached or detached or there |
|
75 is a change in the current resolution, the resolution list or the current |
|
76 configuration. For example, this can be generated by a render stage or the |
|
77 composition engine in response to a hardware event (such as an external display |
|
78 being connected or disconnected). The event is sometimes, but not always, |
|
79 triggered by a change in the screen mode. </p> <p>There are therefore two |
|
80 aspects to the event in that it can be triggered by a display change or a |
|
81 configuration change. Typically you check the event against the previous one |
|
82 to see what has changed. </p> <p>The following table provides a summary of |
|
83 how this event compares to <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref>. </p> <table id="GUID-50D8232A-E394-590F-A762-79567E4424C3"> |
|
84 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
85 <thead> |
|
86 <row> |
|
87 <entry>Action</entry> |
|
88 <entry><codeph>EEventScreenDeviceChanged</codeph> </entry> |
|
89 <entry><codeph>EEventDisplayChanged</codeph> </entry> |
|
90 </row> |
|
91 </thead> |
|
92 <tbody> |
|
93 <row> |
|
94 <entry><p>Screen mode change </p> </entry> |
|
95 <entry><p>Always triggers this event </p> </entry> |
|
96 <entry><p>Triggers this event only if it causes a change in the configuration. </p> </entry> |
|
97 </row> |
|
98 <row> |
|
99 <entry><p>Display configuration change </p> </entry> |
|
100 <entry><p>Generally does not trigger this event </p> </entry> |
|
101 <entry><p>Generally triggers this event </p> </entry> |
|
102 </row> |
|
103 </tbody> |
|
104 </tgroup> |
|
105 </table> <p>The following example first registers for notification of <xref href="GUID-6426E0A6-35F2-3704-962C-0A8AE8AF7226.dita"><apiname>EEventDisplayChanged</apiname></xref> events |
|
106 and then changes the screen mode. The second part illustrates a simplified |
|
107 handler for the events. It demonstrates checking the event against the previous |
|
108 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. |
|
109 |
|
110 iDisplayControl->EnableDisplayChangeEvents(ETrue); |
|
111 |
|
112 iScreenDevice->SetScreenMode(2); // Number depends on WSINI.INI config. |
|
113 iScreenDevice->SetAppScreenMode(2); // Ensure application windows are |
|
114 // shown in the new mode. |
|
115 ... |
|
116 |
|
117 // Simplified event handler. |
|
118 TWsEvent event; |
|
119 iSession.GetEvent(event); |
|
120 |
|
121 switch (event.Type()) |
|
122 { |
|
123 case EEventScreenDeviceChanged: |
|
124 { |
|
125 TSize screenSize = iScreenDevice->SizeInPixels(); |
|
126 // Re-layout windows for new application screen dimensions |
|
127 } |
|
128 break; |
|
129 case Redraw: |
|
130 { |
|
131 // Draw content of window |
|
132 } |
|
133 break; |
|
134 case EEventDisplayChanged: |
|
135 { |
|
136 TWsDisplayChangedEvent* newEvent; |
|
137 newEvent = event.DisplayChanged(); |
|
138 |
|
139 if (newEvent->iResolutionListChangeId != |
|
140 iLastEvent.iResolutionListChangeId) |
|
141 { |
|
142 // ... |
|
143 } |
|
144 |
|
145 if (newEvent->iConfigurationChangeId != |
|
146 iLastEvent.iConfigurationChangeId) |
|
147 { |
|
148 TDisplayConfiguration config; |
|
149 User::LeaveIfError( |
|
150 iDisplayControl->GetConfiguration(config))); |
|
151 // Handle updated configuration |
|
152 // May be entirely handled by screen device changed event |
|
153 } |
|
154 iLastEvent = *newEvent; |
|
155 } |
|
156 break; |
|
157 }</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; |
|
158 config.SetResolution(TSize(1280, 720)); |
|
159 config.SetRotation(MDisplayControl::ERotation180); |
|
160 |
|
161 User::LeaveIfError(iDisplayControl->SetConfiguration(config)); |
|
162 </codeblock> </section> |
|
163 <section> <title>MDisplayMapping</title> <p>The <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface |
|
164 enables Window Server clients to map between coordinate spaces, allowing for |
|
165 translation and scaling of coordinates. For example, suppose an application |
|
166 is to draw a virtual keyboard outside of the application's extent. This requires |
|
167 knowing the extent of both the application and the full UI area. The application |
|
168 can use the <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface to get this information, |
|
169 so that the virtual keyboard can be drawn within the full UI area but outside |
|
170 of the application's extent. </p> <fig id="GUID-55BD49C6-9A51-53A7-A587-29A151FACF6B"> |
|
171 <title> Display mapping class diagram </title> |
|
172 <image href="GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e211363_href.png" placement="inline"/> |
|
173 </fig> <p> </p> <p>The <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface is very |
|
174 flexible. UIDs are used to signify the application UI coordinate space, the |
|
175 full UI space, the composition/display coordinate space (which may be a different |
|
176 scale to the UI coordinate space) and the Direct Screen Access (DSA) space |
|
177 (which may match the full UI space, or be offset relative to the application |
|
178 UI space). </p> <p>The <xref href="GUID-53AF1470-F06E-321C-AF64-FE422A7662DA.dita"><apiname>MapCoordinates()</apiname></xref> function takes |
|
179 a rectangle, a source space and a target space and returns the correspondingly |
|
180 mapped rectangle in the target space. To map a point, use a rectangle with |
|
181 a width and height of one pixel, because the scaling between UI space and |
|
182 composition/display space may enlarge (or sometimes reduce) the rectangle’s |
|
183 size. </p> <p>For example, consider the following diagram, in which the outer |
|
184 rectangle represents the display area and the inner one represents the application |
|
185 space (screen mode). </p> <fig id="GUID-6935A7BE-C651-5582-8E2A-11A18CDD531F"> |
|
186 <title>Display area and application extent </title> |
|
187 <image href="GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e211391_href.png" placement="inline"/> |
|
188 </fig> <p>The display resolution is 1280 x 720, the application size is 176 |
|
189 x 208 and a virtual resolution of 426 x 240 has been introduced, which gives |
|
190 a scaling factor of three in each direction. All pixels are approximately |
|
191 square, for simplicity. The application area has been centered in the display, |
|
192 giving an <i>X</i> offset of (426-176)/2 and a <i>Y</i> offset of (240-208)/2, |
|
193 or (125, 16). </p> <p>To put a window on screen to fill the display, create |
|
194 a rectangle positioned at (0,0) with a size of the current resolution (426 |
|
195 x 240). Then pass this in with a source space of the full UI and target space |
|
196 of the application. This results in a rectangle of the same size but at offset |
|
197 (125,16). </p> <p>In addition, to use an external surface at the real resolution, |
|
198 pass this rectangle in with a source space of the application UI and a target |
|
199 space of the composition/display. This results in a rectangle with size of |
|
200 1280 x 720, which you can then use when creating the surface. Because the |
|
201 UI surface and external surface are scaled independently, the UI memory requirements |
|
202 can remain low, even with high resolution video, viewfinder and games. For |
|
203 an example code snippet, see <xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita">External |
|
204 Surfaces Overview</xref>. </p> </section> |
|
205 </conbody><related-links> |
|
206 <link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server |
|
207 Client-Side Library Concepts</linktext></link> |
|
208 <link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution |
|
209 Switching</linktext></link> |
|
210 <link href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita"><linktext>The wsini.ini |
|
211 File Reference</linktext></link> |
|
212 </related-links></concept> |