--- a/Symbian3/SDK/Source/GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,118 +1,118 @@
-<?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-0EBE5733-A267-5F4A-85AD-87C3ECF80731" xml:lang="en"><title>Dynamic
-Resolution Switching</title><shortdesc>ScreenPlay provides support for externally connected displays,
-such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant
-consider the size of all displays to be fixed, assuming them to be built into
-the phone. However, for High-Definition Multimedia Interface (HDMI) and composite
-video connectors, there is a range of resolutions that can change dynamically.
-ScreenPlay provides an optional feature that supports switching between resolutions
-at runtime. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. </p>
-<section id="GUID-374864AA-3757-4BD9-A5EB-4AC0E6DDD198"><title>The pre-ScreenPlay background</title> <p>Early devices typically
-had a screen size of 220 x 176 pixels. Over time, these were followed by higher
-resolution screens, such as 440 x 252 pixels. Applications that were designed
-for 220 x 176 pixel screens could run on 440 x 252 pixel screens because the
-Window Server simply scaled the pixels by a factor of two. </p> <p>However,
-this approach did not work when phones with 320 x 240 pixel screens were introduced,
-because each axis required a different scaling factor. Symbian introduced
-the <b>screen mode</b> feature to handle this and similar use cases. Device
-creators define in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
-file</xref> a number of screen modes for each physical screen on the device.
-For each screen mode the device creator defines parameters to control the
-offset from the top left corner of the screen, the height and width in both
-pixels and twips, <i>X</i> and <i>Y</i> axis scaling factors and so on. The
-Window Server uses these to position and scale old applications so that they
-can run on new phones with higher resolutions, as shown in the following diagram
-(which is not drawn to scale). The screen mode is still used in the same way
-in the <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay
-variant</xref>. </p> <fig id="GUID-FF86B974-1B1E-5EE1-A88A-9CD11B213A9B">
-<title>The screen mode enables old applications to run on new
- phones with higher resolutions </title>
-<image href="GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e191929_href.png" placement="inline"/>
-</fig> <p>There are several similar use cases, such as swapping between portrait
-and landscape orientations and flip phones that have a flap that, when closed,
-partially obscures the main screen. The Window Server uses the screen mode
-parameters to display applications differently depending on whether the phone
-is in portrait or landscape orientation and whether the flap is open or closed.
-The screen mode represents the area that is presented to the application and
-is available to application developers through <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>. </p> <p>Defining
-the screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
-file</xref> in this way means that all possible screen sizes and resolutions
-must be fixed and known at ROM building time. This approach has limitations
-when working with technologies such as HDMI and composite video connectors,
-where there is a very wide range of possible resolutions that may not be known
-until runtime. </p> </section>
-<section id="GUID-139F6C69-85CD-4796-AE8D-A48EEAEB5294"><title>The ScreenPlay approach</title> <p>In ScreenPlay the actual
-resolution of the full composition/display area can be determined at runtime.
-The full UI area is mapped to fill this display area but may be a lower virtual
-resolution, which is scaled. The render stage chain handles the
-scaling and positioning of applications and any external surfaces within the
-UI, and the composition engine performs the scaling of the pixel data to the
-actual display area at physical resolution. This has the advantage that the
-scaling can be handled by the graphics acceleration hardware, if it is available. </p> <p>Another
-advantage of this approach is that it enables dynamic scaling of the pixels.
-Usually pixels are square on a mobile phone display, but not square on many
-external displays. When the square pixels from the device are displayed on
-such a display, they may need to be scaled by different arbitrary factors
-on each axis. This is called <b>anisotropic scaling</b>. In contrast, <b>isotropic
-scaling</b> means that both pixel axes are scaled by the same arbitrary factor. </p> <p>The
-following diagram illustrates how the full UI area is mapped to fill the display/composition
-area. The application's area (which corresponds to the screen mode) is referred
-to as the <b>application extent</b> in ScreenPlay. </p> <fig id="GUID-724DB4EE-1F45-58D9-889C-B42ECEE7208D">
-<title>Coordinate spaces in ScreenPlay </title>
-<image href="GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e191975_href.png" placement="inline"/>
-</fig> <p>ScreenPlay handles application sizing and positioning in a fundamentally
-different way from the non-ScreenPlay variant. Using a fixed offset to position
-the application within the screen is inadequate when connecting to an external
-HDMI display, for example, when the resolution may not be known until runtime.
-For example, the offset designed for a QVGA display does not position the
-application correctly in a higher resolution display, as shown in the following
-diagram, where the red cross indicates the offset for a QVGA display. </p> <fig id="GUID-A2816D08-B61F-5605-B6AF-A9D186F6BED5">
-<title>A fixed offset and several display resolutions (not drawn
- to scale) </title>
-<image href="GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e191986_href.png" placement="inline"/>
-</fig> <p>In ScreenPlay there is no scaling of the application extent relative
-to the full UI area—there is always a 1:1 pixel correspondence between them.
-In addition, although supported, the screen mode offset is not necessarily
-used. Instead, the render stage chain selects an appropriate virtual resolution
-and handles the positioning—for example, centering it and using a best fit
-algorithm so that it takes up as much of the screen as possible or using the
-offset as a minimum margin size. The device creator can choose how to implement
-this in the render stages. In order to position the application correctly
-within the UI area, the Window Server gets the positioning information from
-the first render stage in the chain when the configuration or screen mode
-changes. </p> <p>ScreenPlay supports fixed screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
-file</xref>, although the scaling parameters are not used. However, the screen
-mode width and height in pixels and twips when specified and used together,
-provide the pixel aspect ratio. In order to maintain backwards compatibility,
-render stages should respect this aspect ratio whenever possible. </p> <p>It
-is possible for applications to determine and draw to the UI area outside
-the application extent using the APIs described below. However, <b>dynamic
-screen modes</b> provide an alternative mechanism for existing applications
-to access the full UI area. This is particularly suitable for HDMI and similar
-technologies where the resolution may not be known until runtime. To use this
-approach, the device creator must define one or two screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> and
-set their height and width in pixels to -1. One dynamic screen mode then represents
-the current display configuration and the other one, if present, represents
-the configuration when the screen is rotated by 90º or 270º. Using dynamic
-screen modes means that the display configuration can be changed at runtime
-according to the hardware that is available and detected by the composition
-engine. </p> <p>When a dynamic screen mode is used, the application extent
-always fills the full 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
-matches the actual resolution that is in use. </p> </section>
-</conbody><related-links>
-<link href="GUID-99BC101A-9466-59EE-B5C9-7622BAF6E6FF.dita"><linktext>Graphics
-Concepts</linktext></link>
-
-
+<?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-0EBE5733-A267-5F4A-85AD-87C3ECF80731" xml:lang="en"><title>Dynamic
+Resolution Switching</title><shortdesc>ScreenPlay provides support for externally connected displays,
+such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant
+consider the size of all displays to be fixed, assuming them to be built into
+the phone. However, for High-Definition Multimedia Interface (HDMI) and composite
+video connectors, there is a range of resolutions that can change dynamically.
+ScreenPlay provides an optional feature that supports switching between resolutions
+at runtime. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. </p>
+<section id="GUID-374864AA-3757-4BD9-A5EB-4AC0E6DDD198"><title>The pre-ScreenPlay background</title> <p>Early devices typically
+had a screen size of 220 x 176 pixels. Over time, these were followed by higher
+resolution screens, such as 440 x 252 pixels. Applications that were designed
+for 220 x 176 pixel screens could run on 440 x 252 pixel screens because the
+Window Server simply scaled the pixels by a factor of two. </p> <p>However,
+this approach did not work when phones with 320 x 240 pixel screens were introduced,
+because each axis required a different scaling factor. Symbian introduced
+the <b>screen mode</b> feature to handle this and similar use cases. Device
+creators define in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
+file</xref> a number of screen modes for each physical screen on the device.
+For each screen mode the device creator defines parameters to control the
+offset from the top left corner of the screen, the height and width in both
+pixels and twips, <i>X</i> and <i>Y</i> axis scaling factors and so on. The
+Window Server uses these to position and scale old applications so that they
+can run on new phones with higher resolutions, as shown in the following diagram
+(which is not drawn to scale). The screen mode is still used in the same way
+in the <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay
+variant</xref>. </p> <fig id="GUID-FF86B974-1B1E-5EE1-A88A-9CD11B213A9B">
+<title>The screen mode enables old applications to run on new
+ phones with higher resolutions </title>
+<image href="GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e185333_href.png" placement="inline"/>
+</fig> <p>There are several similar use cases, such as swapping between portrait
+and landscape orientations and flip phones that have a flap that, when closed,
+partially obscures the main screen. The Window Server uses the screen mode
+parameters to display applications differently depending on whether the phone
+is in portrait or landscape orientation and whether the flap is open or closed.
+The screen mode represents the area that is presented to the application and
+is available to application developers through <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>. </p> <p>Defining
+the screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
+file</xref> in this way means that all possible screen sizes and resolutions
+must be fixed and known at ROM building time. This approach has limitations
+when working with technologies such as HDMI and composite video connectors,
+where there is a very wide range of possible resolutions that may not be known
+until runtime. </p> </section>
+<section id="GUID-139F6C69-85CD-4796-AE8D-A48EEAEB5294"><title>The ScreenPlay approach</title> <p>In ScreenPlay the actual
+resolution of the full composition/display area can be determined at runtime.
+The full UI area is mapped to fill this display area but may be a lower virtual
+resolution, which is scaled. The render stage chain handles the
+scaling and positioning of applications and any external surfaces within the
+UI, and the composition engine performs the scaling of the pixel data to the
+actual display area at physical resolution. This has the advantage that the
+scaling can be handled by the graphics acceleration hardware, if it is available. </p> <p>Another
+advantage of this approach is that it enables dynamic scaling of the pixels.
+Usually pixels are square on a mobile phone display, but not square on many
+external displays. When the square pixels from the device are displayed on
+such a display, they may need to be scaled by different arbitrary factors
+on each axis. This is called <b>anisotropic scaling</b>. In contrast, <b>isotropic
+scaling</b> means that both pixel axes are scaled by the same arbitrary factor. </p> <p>The
+following diagram illustrates how the full UI area is mapped to fill the display/composition
+area. The application's area (which corresponds to the screen mode) is referred
+to as the <b>application extent</b> in ScreenPlay. </p> <fig id="GUID-724DB4EE-1F45-58D9-889C-B42ECEE7208D">
+<title>Coordinate spaces in ScreenPlay </title>
+<image href="GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e185379_href.png" placement="inline"/>
+</fig> <p>ScreenPlay handles application sizing and positioning in a fundamentally
+different way from the non-ScreenPlay variant. Using a fixed offset to position
+the application within the screen is inadequate when connecting to an external
+HDMI display, for example, when the resolution may not be known until runtime.
+For example, the offset designed for a QVGA display does not position the
+application correctly in a higher resolution display, as shown in the following
+diagram, where the red cross indicates the offset for a QVGA display. </p> <fig id="GUID-A2816D08-B61F-5605-B6AF-A9D186F6BED5">
+<title>A fixed offset and several display resolutions (not drawn
+ to scale) </title>
+<image href="GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e185390_href.png" placement="inline"/>
+</fig> <p>In ScreenPlay there is no scaling of the application extent relative
+to the full UI area—there is always a 1:1 pixel correspondence between them.
+In addition, although supported, the screen mode offset is not necessarily
+used. Instead, the render stage chain selects an appropriate virtual resolution
+and handles the positioning—for example, centering it and using a best fit
+algorithm so that it takes up as much of the screen as possible or using the
+offset as a minimum margin size. The device creator can choose how to implement
+this in the render stages. In order to position the application correctly
+within the UI area, the Window Server gets the positioning information from
+the first render stage in the chain when the configuration or screen mode
+changes. </p> <p>ScreenPlay supports fixed screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini
+file</xref>, although the scaling parameters are not used. However, the screen
+mode width and height in pixels and twips when specified and used together,
+provide the pixel aspect ratio. In order to maintain backwards compatibility,
+render stages should respect this aspect ratio whenever possible. </p> <p>It
+is possible for applications to determine and draw to the UI area outside
+the application extent using the APIs described below. However, <b>dynamic
+screen modes</b> provide an alternative mechanism for existing applications
+to access the full UI area. This is particularly suitable for HDMI and similar
+technologies where the resolution may not be known until runtime. To use this
+approach, the device creator must define one or two screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> and
+set their height and width in pixels to -1. One dynamic screen mode then represents
+the current display configuration and the other one, if present, represents
+the configuration when the screen is rotated by 90º or 270º. Using dynamic
+screen modes means that the display configuration can be changed at runtime
+according to the hardware that is available and detected by the composition
+engine. </p> <p>When a dynamic screen mode is used, the application extent
+always fills the full 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
+matches the actual resolution that is in use. </p> </section>
+</conbody><related-links>
+<link href="GUID-99BC101A-9466-59EE-B5C9-7622BAF6E6FF.dita"><linktext>Graphics
+Concepts</linktext></link>
+
+
</related-links></concept>
\ No newline at end of file