--- a/Symbian3/PDK/Source/GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,24 +1,24 @@
-<?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 xml:lang="en" id="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE"><title>Render Stage Display Control and Mapping</title><shortdesc>ScreenPlay has a new approach to display resolution control to support externally connected displays, such as TV-out. It involves the render stages plus a number of other components in the Graphics package, including the Window Server and the composition engine. The render stages are able to monitor and modify display control attributes, and to scale and position the application extent within the full UI area. In addition, they can optionally implement a display policy, which determines the UI to composition mapping policy. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target audience</b>: Device creators. </p> <p>This topic builds on the material covered in the following topics: </p> <ul><li id="GUID-2DC0F65B-E3B0-501C-98ED-0DE32A2C112C"><p><xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution Switching</xref> </p> </li> <li id="GUID-8DA1CE87-22C3-5F38-B21A-B53EF6125869"><p><xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages Overview</xref> </p> </li> <li id="GUID-B281AE5F-48B8-5FEE-A847-F22192CEC841"><p><xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita">Render Stage Interfaces</xref> </p> </li> </ul> <section><title>Render stage display control and mapping interfaces</title> <p>The following diagram provides an overview of the render stage display control interfaces. There is further information about the interfaces under separate headings below the diagram. </p> <fig id="GUID-0AC1C9CD-462F-5D6C-B641-F896DC1CF945"><title>
- The render stage display control interfaces
- </title> <image href="GUID-B34485AB-FA14-5453-A2B2-EB85055E62A4_d0e219925_href.png" placement="inline"/></fig> <p>Symbian provides a reference render stage implementation that device creators can use as an example when implementing their own. It demonstrates how to implement these interfaces. See <xref href="GUID-23E414B0-581B-5B6C-A449-8DA7AD8E1FA4.dita">Window Server Plugins Component Overview</xref> for more information. </p> </section> <section><title>MWsDisplayControl</title> <p> <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> is derived from the <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> and <xref href="GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4.dita"><apiname>MDisplayControlBase</apiname></xref> interfaces as shown in the following diagram. </p> <fig id="GUID-AD527796-B8AF-58D8-BA4C-CA48946EA504"><title>
- MWsDisplayControl class diagram
- </title> <image href="GUID-768D58BA-28A8-5325-A3C3-6A95E1F98578_d0e219957_href.png" placement="inline"/></fig> <p>For a diagram of the <xref href="GUID-7ED11E23-6E13-36D4-BB10-8AE9E745C560.dita"><apiname>TDisplayConfiguration</apiname></xref> class hierarchy, see the <xref href="GUID-19C3DA8C-0128-5172-B859-4FD6F6197451.dita">Common Graphics Headers Component Overview</xref>. </p> <p>A render stage uses the <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> interface to intercept <xref href="GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4.dita#GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4/GUID-E4DE786F-547E-3A3B-90D2-31892A708E25"><apiname>MDisplayControlBase::GetResolutions()</apiname></xref> calls at runtime. A render stage can add <b>virtual resolutions</b> into the list of display resolutions in order to scale the full UI area to the full composition area. Using virtual resolutions in this way reduces the memory required for the UI buffers and allows the Window Server to work purely in the application UI coordinate space. Virtual resolutions are marked with a flag in the <xref href="GUID-15E9E782-1D64-3E7C-8D43-51DF267FE6A9.dita"><apiname>TResolution</apiname></xref> structure provided by <codeph>GetResolutions()</codeph>. The structure also includes the size of the resolution in both pixels and twips. A render stage may also remove physical resolutions from the list in order to disable the client's ability to change the resolution. </p> <p>A render stage that provides virtual resolutions can include one (or more) virtual resolutions that give the UI pixel aspect ratio to fit a screen mode defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. However, this may require anisotropic scaling of the UI surface in the composition engine. For example, PAL has 720 x 576 non-square pixels. To get approximately square pixels, virtual resolutions of either 788 x 576 or 720 x 540 would work on a 4:3 display, and 1050 x 576 or 720 x 395 would work on a 16:9 display. The choice of stretching or shrinking virtual resolutions may depend on the quality of scaling available and other factors, and should only be used for backwards compatibility purposes. This is because 1:1 or integer scaling generally gives a better appearance for user interfaces. Providing shrinking virtual resolutions may also raise expectations in applications of a higher horizontal resolution than actually exists. </p> <p>The term <b>real resolution</b> is used for the display resolutions that are returned by the composition engine adaptation. These correspond to the supported composition spaces that the Window Server can select for output. These may be scaled and filtered beyond the composition engine adaptation (for example, in the physical display device, such as an HDMI TV). </p> <p>In addition to defining static screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>, device creators can define one or two <b>dynamic screen modes</b> in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. These are used to represent the current display configuration—one for 0° and 180° rotations and the other for 90° and 270° rotations. The latter has the dimensions in both pixels and in twips swapped, to appear similar to the static modes. You define a dynamic screen mode by setting the <codeph>SCR_WIDTH</codeph> and <codeph>SCR_HEIGHT</codeph> parameters to -1. If there is only one dynamic mode, it is not possible to use the <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> API to change the current rotation by 90 degrees. </p> <p>If <xref href="GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11.dita#GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11/GUID-EC440412-68AA-36F1-9DD4-DD85EF09E2B2"><apiname>MDisplayControl::SetConfiguration()</apiname></xref> is used to change the configuration, the dynamic mode(s) are updated as necessary. With two dynamic modes, if one is the current mode, the other generally becomes the new mode (even if only the resolution changed, for example) so that applications see a mode number change. The only time this does not happen is in the case of a 180° rotation, because the static mode behavior is to retain the current mode. </p> <p>Whenever the dynamic mode data changes, or a new mode is selected, an <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref> event is sent to all clients that have enabled it. Window Server client functions are provided to query whether the current or a given mode index is dynamic. </p> <p>Without dynamic size modes, an application can still use the full display, by positioning windows outside the reported display area. </p> </section> <section><title>MWsDisplayMapping</title> <p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> is an "information" interface, answering questions rather than anything else. In ScreenPlay, there are several coordinate spaces and there is a common requirement to map a rectangle from one space to another. The render stage implements this interface and ultimately the Window Server exposes the mapping feature to its clients. The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> interface derives from the <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> and <xref href="GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF.dita"><apiname>MDisplayMappingBase</apiname></xref> interfaces as shown in the following diagram. </p> <fig id="GUID-4C9F606A-D11E-5555-BC1A-32B20FA59362"><title>
- MWsDisplayMapping class diagram
- </title> <image href="GUID-A6DE13A9-BD2F-5F14-864E-BAEC9C52B9DD_d0e220069_href.png" placement="inline"/></fig> <p>The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> interface is very flexible. UIDs are used to signify the application UI coordinate space, the full UI space, the composition/display coordinate space (which may be a different scale to the UI coordinate space) and the Direct Screen Access (DSA) space (which may match the full UI space, or be offset relative to the application UI space). </p> <p>The <xref href="GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF.dita#GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF/GUID-4BA10CBB-E4BA-3E56-816F-8F75AC4B6A2F"><apiname>MDisplayMappingBase::MapCoordinates()</apiname></xref> function simply takes a rectangle, a source space and a target space and returns the correspondingly mapped rectangle in the target space. The render stage must guarantee that if two rectangles abut in the source coordinate space, their mapped equivalents also abut. For information about the use of the <codeph>MapCoordinates()</codeph> function by Window Server clients, see <xref href="GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita">Display Control and Mapping in the Window Server Client</xref>. </p> <p>The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita#GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104/GUID-F77D8AB1-CF35-36CB-B317-9857317A6E66"><apiname>MWsDisplayMapping::SetSizeModeExtent()</apiname></xref> function sets the screen mode extent for use in one or more contexts. If this is successful, the offset is set on the render stage pipeline in two ways: </p> <ul><li id="GUID-E74FCA00-4A72-5317-A359-1641CB37FD46"><p>Firstly, the offset applies to rendering and must only affect the coordinates in the first render stage that actually performs rendering, and not to later stages. For example, in the reference configuration of the <i>flicker buffer</i> and <i>display</i> render stages, only the <i>flicker buffer</i> render stage applies the rendering offset. A render stage using a <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref> can use <xref href="GUID-BA0355E9-F878-3B2D-A0B3-DAABE6054990.dita"><apiname>SetOrigin()</apiname></xref> to apply the offset. Other graphics contexts may have a similar feature. </p> </li> <li id="GUID-D9F36E47-60BB-5AF3-8861-BA4773BE9E10"><p>Secondly, the offset is applied to translate the coordinates of the scene element's destination rectangle (layer extent). This means it is applied only by the first stage that implements the scene element translation. In the reference configuration, this is the <i>display</i> stage. </p> </li> </ul> </section> <section><title>MWsDisplayPolicy</title> <p> <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is an optional interface, which derives from <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> as shown in the following diagram. The main purpose of <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is to enable the render stage chain to position the application extent as intelligently as possible to suit the resolution. However, there is no requirement for the render stage chain to implement the interface. If it is not implemented, the offset defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> is used. If that is not available a zero offset is used. </p> <fig id="GUID-BF62EC7F-AA84-5D55-BD20-80413A609C77"><title>
- MWsDisplayPolicy class diagram
- </title> <image href="GUID-20C633DE-CD37-5807-9F2E-6E4CFC35DB28_d0e220157_href.png" placement="inline"/></fig> <p>The <codeph>GetSizeModeConfiguration()</codeph> function determines the display configuration and application rendering extent to use for a given screen mode defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. The Window Server calls this when an eligible client does one of the following: </p> <ul><li id="GUID-9B507277-6B4F-5301-92E0-1394BCAA60C8"><p>Sets the system screen mode using <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-9F04C517-7891-3A44-B280-4FD18FABBA0E"><apiname>CWsScreenDevice::SetScreenMode()</apiname></xref>. In this case the configuration structure passed to the policy function is empty because it is the current configuration. </p> </li> <li id="GUID-F904BE5B-B3D3-5C6A-B6B7-D5DEC52B8A1A"><p>Sets a new display configuration. In this case the requested configuration is passed to the policy function. </p> </li> </ul> <p>On success, the render stage fills in the <xref href="GUID-7ED11E23-6E13-36D4-BB10-8AE9E745C560.dita"><apiname>TDisplayConfiguration</apiname></xref> structure. Then the Window Server calls the following as appropriate: </p> <ul><li id="GUID-22BC6E2C-7DE5-523B-A342-1AC9921D7B1E"><p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita#GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104/GUID-F77D8AB1-CF35-36CB-B317-9857317A6E66"><apiname>MWsDisplayMapping::SetSizeModeExtent()</apiname></xref> and passes the configuration structure to indicate the position and size of the application area. </p> </li> <li id="GUID-266C1CDD-21B1-5FD9-B91A-1C6092AF1D63"><p> <xref href="GUID-41595893-B693-34C3-A5FF-05EC433153E6.dita#GUID-41595893-B693-34C3-A5FF-05EC433153E6/GUID-275B3E0B-26DF-3292-9DE5-2E9D020FC4CC"><apiname>MWsDisplayContol::SetConfiguration()</apiname></xref> and passes the configuration structure to indicate the appropriate real or virtual display resolution. </p> </li> </ul> <p>On failure, the current screen mode and display resolution are retained, but a screen device changed event should still be sent, because there is no way to return failure to the caller. </p> <p>Applications are given the static offset associated with the screen mode, not the offset described above. Note that because of the way that DSA works, if the render stage uses a <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref> object for rendering, the DSA buffer and the UI buffer are the same (that is, the Screen Driver surface). This means that the offset returned by this policy function must be the same as the one passed in. The policy function has the option to reject the mode change, however. </p> <p>The Symbian <i>display</i> render stage applies a "best fit" approach, taking into account virtual resolutions if configured, whereby the offset and resolution are chosen to make the screen mode fill as much of the display as possible, while retaining the same (or very similar) pixel aspect ratio. The offset may be limited if the Screen Driver surface is being used for rendering, as described above. The quality of the scaling of screen modes to virtual resolutions and real resolutions is determined by the <codeph>DP_SCALING</codeph> <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> parameter. However, more typically a render stage would implement just one scaling mode, and not require configuration. </p> </section> <section><title>MWsScreenConfigList</title> <p>The Window Server exposes the <xref href="GUID-4A0B562B-8AF2-3381-864A-2B55166F0322.dita"><apiname>MWsScreenConfigList</apiname></xref> interface for use by render stages. Render stages can use this to get the screen mode parameters for a given index without parsing the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. This interface is similar to <xref href="GUID-02C89F7D-6464-33A7-ABE6-C02B2941382A.dita"><apiname>MWsScreenConfig</apiname></xref>, which applies only to the current mode. The <xref href="GUID-4A0B562B-8AF2-3381-864A-2B55166F0322.dita"><apiname>MWsScreenConfigList</apiname></xref> methods leave only if the mode index is out of range. </p> <fig id="GUID-6E9333CE-FB17-5E4A-BEBA-77633CAE74F3"><title>
- MWsScreenConfigList class diagram
- </title> <image href="GUID-6DE7E0C8-A75E-5F09-BEC1-180602BF2051_d0e220260_href.png" placement="inline"/></fig> </section> </conbody><related-links><link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution
- Switching</linktext> </link> <link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext> </link> <link href="GUID-23E414B0-581B-5B6C-A449-8DA7AD8E1FA4.dita"><linktext>Window Server Plugins Component
+<?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 xml:lang="en" id="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE"><title>Render Stage Display Control and Mapping</title><shortdesc>ScreenPlay has a new approach to display resolution control to support externally connected displays, such as TV-out. It involves the render stages plus a number of other components in the Graphics package, including the Window Server and the composition engine. The render stages are able to monitor and modify display control attributes, and to scale and position the application extent within the full UI area. In addition, they can optionally implement a display policy, which determines the UI to composition mapping policy. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target audience</b>: Device creators. </p> <p>This topic builds on the material covered in the following topics: </p> <ul><li id="GUID-2DC0F65B-E3B0-501C-98ED-0DE32A2C112C"><p><xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution Switching</xref> </p> </li> <li id="GUID-8DA1CE87-22C3-5F38-B21A-B53EF6125869"><p><xref href="GUID-2E8929E6-9555-51D2-B41D-6F1D05A4DB87.dita">Render Stages Overview</xref> </p> </li> <li id="GUID-B281AE5F-48B8-5FEE-A847-F22192CEC841"><p><xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita">Render Stage Interfaces</xref> </p> </li> </ul> <section><title>Render stage display control and mapping interfaces</title> <p>The following diagram provides an overview of the render stage display control interfaces. There is further information about the interfaces under separate headings below the diagram. </p> <fig id="GUID-0AC1C9CD-462F-5D6C-B641-F896DC1CF945"><title>
+ The render stage display control interfaces
+ </title> <image href="GUID-B34485AB-FA14-5453-A2B2-EB85055E62A4_d0e247725_href.png" placement="inline"/></fig> <p>Symbian provides a reference render stage implementation that device creators can use as an example when implementing their own. It demonstrates how to implement these interfaces. See <xref href="GUID-23E414B0-581B-5B6C-A449-8DA7AD8E1FA4.dita">Window Server Plugins Component Overview</xref> for more information. </p> </section> <section><title>MWsDisplayControl</title> <p> <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> is derived from the <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> and <xref href="GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4.dita"><apiname>MDisplayControlBase</apiname></xref> interfaces as shown in the following diagram. </p> <fig id="GUID-AD527796-B8AF-58D8-BA4C-CA48946EA504"><title>
+ MWsDisplayControl class diagram
+ </title> <image href="GUID-768D58BA-28A8-5325-A3C3-6A95E1F98578_d0e247757_href.png" placement="inline"/></fig> <p>For a diagram of the <xref href="GUID-7ED11E23-6E13-36D4-BB10-8AE9E745C560.dita"><apiname>TDisplayConfiguration</apiname></xref> class hierarchy, see the <xref href="GUID-19C3DA8C-0128-5172-B859-4FD6F6197451.dita">Common Graphics Headers Component Overview</xref>. </p> <p>A render stage uses the <xref href="GUID-415B5416-A6DD-3471-8800-C76C48DA59DA.dita"><apiname>MWsDisplayControl</apiname></xref> interface to intercept <xref href="GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4.dita#GUID-8391795F-3766-3F31-BDFA-832AE8B4DFD4/GUID-E4DE786F-547E-3A3B-90D2-31892A708E25"><apiname>MDisplayControlBase::GetResolutions()</apiname></xref> calls at runtime. A render stage can add <b>virtual resolutions</b> into the list of display resolutions in order to scale the full UI area to the full composition area. Using virtual resolutions in this way reduces the memory required for the UI buffers and allows the Window Server to work purely in the application UI coordinate space. Virtual resolutions are marked with a flag in the <xref href="GUID-15E9E782-1D64-3E7C-8D43-51DF267FE6A9.dita"><apiname>TResolution</apiname></xref> structure provided by <codeph>GetResolutions()</codeph>. The structure also includes the size of the resolution in both pixels and twips. A render stage may also remove physical resolutions from the list in order to disable the client's ability to change the resolution. </p> <p>A render stage that provides virtual resolutions can include one (or more) virtual resolutions that give the UI pixel aspect ratio to fit a screen mode defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. However, this may require anisotropic scaling of the UI surface in the composition engine. For example, PAL has 720 x 576 non-square pixels. To get approximately square pixels, virtual resolutions of either 788 x 576 or 720 x 540 would work on a 4:3 display, and 1050 x 576 or 720 x 395 would work on a 16:9 display. The choice of stretching or shrinking virtual resolutions may depend on the quality of scaling available and other factors, and should only be used for backwards compatibility purposes. This is because 1:1 or integer scaling generally gives a better appearance for user interfaces. Providing shrinking virtual resolutions may also raise expectations in applications of a higher horizontal resolution than actually exists. </p> <p>The term <b>real resolution</b> is used for the display resolutions that are returned by the composition engine adaptation. These correspond to the supported composition spaces that the Window Server can select for output. These may be scaled and filtered beyond the composition engine adaptation (for example, in the physical display device, such as an HDMI TV). </p> <p>In addition to defining static screen modes in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>, device creators can define one or two <b>dynamic screen modes</b> in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. These are used to represent the current display configuration—one for 0° and 180° rotations and the other for 90° and 270° rotations. The latter has the dimensions in both pixels and in twips swapped, to appear similar to the static modes. You define a dynamic screen mode by setting the <codeph>SCR_WIDTH</codeph> and <codeph>SCR_HEIGHT</codeph> parameters to -1. If there is only one dynamic mode, it is not possible to use the <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> API to change the current rotation by 90 degrees. </p> <p>If <xref href="GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11.dita#GUID-0C384D35-77DD-318E-AF3E-C9ED5ADD9D11/GUID-EC440412-68AA-36F1-9DD4-DD85EF09E2B2"><apiname>MDisplayControl::SetConfiguration()</apiname></xref> is used to change the configuration, the dynamic mode(s) are updated as necessary. With two dynamic modes, if one is the current mode, the other generally becomes the new mode (even if only the resolution changed, for example) so that applications see a mode number change. The only time this does not happen is in the case of a 180° rotation, because the static mode behavior is to retain the current mode. </p> <p>Whenever the dynamic mode data changes, or a new mode is selected, an <xref href="GUID-CC1E6B2E-F68F-3A00-B4EA-4917007F7320.dita"><apiname>EEventScreenDeviceChanged</apiname></xref> event is sent to all clients that have enabled it. Window Server client functions are provided to query whether the current or a given mode index is dynamic. </p> <p>Without dynamic size modes, an application can still use the full display, by positioning windows outside the reported display area. </p> </section> <section><title>MWsDisplayMapping</title> <p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> is an "information" interface, answering questions rather than anything else. In ScreenPlay, there are several coordinate spaces and there is a common requirement to map a rectangle from one space to another. The render stage implements this interface and ultimately the Window Server exposes the mapping feature to its clients. The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> interface derives from the <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> and <xref href="GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF.dita"><apiname>MDisplayMappingBase</apiname></xref> interfaces as shown in the following diagram. </p> <fig id="GUID-4C9F606A-D11E-5555-BC1A-32B20FA59362"><title>
+ MWsDisplayMapping class diagram
+ </title> <image href="GUID-A6DE13A9-BD2F-5F14-864E-BAEC9C52B9DD_d0e247869_href.png" placement="inline"/></fig> <p>The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita"><apiname>MWsDisplayMapping</apiname></xref> interface is very flexible. UIDs are used to signify the application UI coordinate space, the full UI space, the composition/display coordinate space (which may be a different scale to the UI coordinate space) and the Direct Screen Access (DSA) space (which may match the full UI space, or be offset relative to the application UI space). </p> <p>The <xref href="GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF.dita#GUID-DE613CC2-E977-34E9-9476-21D349B1C1CF/GUID-4BA10CBB-E4BA-3E56-816F-8F75AC4B6A2F"><apiname>MDisplayMappingBase::MapCoordinates()</apiname></xref> function simply takes a rectangle, a source space and a target space and returns the correspondingly mapped rectangle in the target space. The render stage must guarantee that if two rectangles abut in the source coordinate space, their mapped equivalents also abut. For information about the use of the <codeph>MapCoordinates()</codeph> function by Window Server clients, see <xref href="GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita">Display Control and Mapping in the Window Server Client</xref>. </p> <p>The <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita#GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104/GUID-F77D8AB1-CF35-36CB-B317-9857317A6E66"><apiname>MWsDisplayMapping::SetSizeModeExtent()</apiname></xref> function sets the screen mode extent for use in one or more contexts. If this is successful, the offset is set on the render stage pipeline in two ways: </p> <ul><li id="GUID-E74FCA00-4A72-5317-A359-1641CB37FD46"><p>Firstly, the offset applies to rendering and must only affect the coordinates in the first render stage that actually performs rendering, and not to later stages. For example, in the reference configuration of the <i>flicker buffer</i> and <i>display</i> render stages, only the <i>flicker buffer</i> render stage applies the rendering offset. A render stage using a <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref> can use <xref href="GUID-BA0355E9-F878-3B2D-A0B3-DAABE6054990.dita"><apiname>SetOrigin()</apiname></xref> to apply the offset. Other graphics contexts may have a similar feature. </p> </li> <li id="GUID-D9F36E47-60BB-5AF3-8861-BA4773BE9E10"><p>Secondly, the offset is applied to translate the coordinates of the scene element's destination rectangle (layer extent). This means it is applied only by the first stage that implements the scene element translation. In the reference configuration, this is the <i>display</i> stage. </p> </li> </ul> </section> <section><title>MWsDisplayPolicy</title> <p> <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is an optional interface, which derives from <xref href="GUID-A47A4139-70FD-3F76-B51E-0452A0F6A76F.dita"><apiname>MWsObjectProvider</apiname></xref> as shown in the following diagram. The main purpose of <xref href="GUID-0A31CF3E-25A9-36BA-80D6-8FBD18419506.dita"><apiname>MWsDisplayPolicy</apiname></xref> is to enable the render stage chain to position the application extent as intelligently as possible to suit the resolution. However, there is no requirement for the render stage chain to implement the interface. If it is not implemented, the offset defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> is used. If that is not available a zero offset is used. </p> <fig id="GUID-BF62EC7F-AA84-5D55-BD20-80413A609C77"><title>
+ MWsDisplayPolicy class diagram
+ </title> <image href="GUID-20C633DE-CD37-5807-9F2E-6E4CFC35DB28_d0e247957_href.png" placement="inline"/></fig> <p>The <codeph>GetSizeModeConfiguration()</codeph> function determines the display configuration and application rendering extent to use for a given screen mode defined in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. The Window Server calls this when an eligible client does one of the following: </p> <ul><li id="GUID-9B507277-6B4F-5301-92E0-1394BCAA60C8"><p>Sets the system screen mode using <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-9F04C517-7891-3A44-B280-4FD18FABBA0E"><apiname>CWsScreenDevice::SetScreenMode()</apiname></xref>. In this case the configuration structure passed to the policy function is empty because it is the current configuration. </p> </li> <li id="GUID-F904BE5B-B3D3-5C6A-B6B7-D5DEC52B8A1A"><p>Sets a new display configuration. In this case the requested configuration is passed to the policy function. </p> </li> </ul> <p>On success, the render stage fills in the <xref href="GUID-7ED11E23-6E13-36D4-BB10-8AE9E745C560.dita"><apiname>TDisplayConfiguration</apiname></xref> structure. Then the Window Server calls the following as appropriate: </p> <ul><li id="GUID-22BC6E2C-7DE5-523B-A342-1AC9921D7B1E"><p> <xref href="GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104.dita#GUID-ED4CAB66-F8F8-3AF2-A388-F28406A3B104/GUID-F77D8AB1-CF35-36CB-B317-9857317A6E66"><apiname>MWsDisplayMapping::SetSizeModeExtent()</apiname></xref> and passes the configuration structure to indicate the position and size of the application area. </p> </li> <li id="GUID-266C1CDD-21B1-5FD9-B91A-1C6092AF1D63"><p> <xref href="GUID-41595893-B693-34C3-A5FF-05EC433153E6.dita#GUID-41595893-B693-34C3-A5FF-05EC433153E6/GUID-275B3E0B-26DF-3292-9DE5-2E9D020FC4CC"><apiname>MWsDisplayContol::SetConfiguration()</apiname></xref> and passes the configuration structure to indicate the appropriate real or virtual display resolution. </p> </li> </ul> <p>On failure, the current screen mode and display resolution are retained, but a screen device changed event should still be sent, because there is no way to return failure to the caller. </p> <p>Applications are given the static offset associated with the screen mode, not the offset described above. Note that because of the way that DSA works, if the render stage uses a <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref> object for rendering, the DSA buffer and the UI buffer are the same (that is, the Screen Driver surface). This means that the offset returned by this policy function must be the same as the one passed in. The policy function has the option to reject the mode change, however. </p> <p>The Symbian <i>display</i> render stage applies a "best fit" approach, taking into account virtual resolutions if configured, whereby the offset and resolution are chosen to make the screen mode fill as much of the display as possible, while retaining the same (or very similar) pixel aspect ratio. The offset may be limited if the Screen Driver surface is being used for rendering, as described above. The quality of the scaling of screen modes to virtual resolutions and real resolutions is determined by the <codeph>DP_SCALING</codeph> <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> parameter. However, more typically a render stage would implement just one scaling mode, and not require configuration. </p> </section> <section><title>MWsScreenConfigList</title> <p>The Window Server exposes the <xref href="GUID-4A0B562B-8AF2-3381-864A-2B55166F0322.dita"><apiname>MWsScreenConfigList</apiname></xref> interface for use by render stages. Render stages can use this to get the screen mode parameters for a given index without parsing the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref>. This interface is similar to <xref href="GUID-02C89F7D-6464-33A7-ABE6-C02B2941382A.dita"><apiname>MWsScreenConfig</apiname></xref>, which applies only to the current mode. The <xref href="GUID-4A0B562B-8AF2-3381-864A-2B55166F0322.dita"><apiname>MWsScreenConfigList</apiname></xref> methods leave only if the mode index is out of range. </p> <fig id="GUID-6E9333CE-FB17-5E4A-BEBA-77633CAE74F3"><title>
+ MWsScreenConfigList class diagram
+ </title> <image href="GUID-6DE7E0C8-A75E-5F09-BEC1-180602BF2051_d0e248060_href.png" placement="inline"/></fig> </section> </conbody><related-links><link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution
+ Switching</linktext> </link> <link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext> </link> <link href="GUID-23E414B0-581B-5B6C-A449-8DA7AD8E1FA4.dita"><linktext>Window Server Plugins Component
Overview</linktext> </link> </related-links></concept>
\ No newline at end of file