Symbian3/SDK/Source/GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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-495EA1C8-E95F-54AE-B4D1-0F463003C2D7" xml:lang="en"><title>External
       
    13 Surfaces Overview</title><shortdesc>This topic provides an introduction to displaying an external surface
       
    14 on a window. The surface is then known as a background surface. This feature
       
    15 is available in ScreenPlay only. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    16 <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. <b>Target
       
    17 audience</b>: Device creators. </p>
       
    18 <p>There are two main use cases for using external surfaces in this way. One
       
    19 is to display a video, in which case DevVideo renders the content. The other
       
    20 main use case is an OpenGL ES background surface, in which case the client
       
    21 issues OpenGL ES rendering commands. This topic covers how to get the surface
       
    22 onto the screen and not rendering the content to the surface. </p>
       
    23 <section><title> Key concepts</title> <p>The following diagram illustrates
       
    24 some of the key concepts that are used in the documentation of surfaces. </p> <fig id="GUID-F134C262-EC19-5925-A188-2C7C2CD5EEEA">
       
    25 <title>Composition of the UI surface and an external surface, showing the
       
    26              viewport and extent</title>
       
    27 <image href="GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e171376_href.png" placement="inline"/>
       
    28 </fig> <dl>
       
    29 <dlentry>
       
    30 <dt>Graphics surface</dt>
       
    31 <dd><p>A graphics surface (usually simply called a <i>surface</i>) is a hardware-independent
       
    32 memory buffer for holding an image or part of a scene. A surface has a set
       
    33 of attributes, the most important of which is its ID (which is a <xref href="GUID-11F60AEB-003B-3E8D-BDB9-D97F698627DF.dita"><apiname>TSurfaceId</apiname></xref>). </p> </dd>
       
    34 </dlentry>
       
    35 <dlentry>
       
    36 <dt>UI surface</dt>
       
    37 <dd><p>The UI surface is a special surface onto which the Window Server renders
       
    38 all of the UI content. It is created automatically during system start up
       
    39 and corresponds to the frame buffer in the non-ScreenPlay variant. The UI
       
    40 surface is semi-transparent and is always the topmost layer.</p> </dd>
       
    41 </dlentry>
       
    42 <dlentry>
       
    43 <dt>External surface</dt>
       
    44 <dd><p>An external surface is any surface other than the UI surface—for example,
       
    45 a surface that holds a video or to which OpenGL ES content is rendered. External
       
    46 surfaces are always opaque. When an external surface is attached to a window,
       
    47 the Window Server creates a transparent hole in the UI surface to reveal the
       
    48 external surface. </p> </dd>
       
    49 </dlentry>
       
    50 <dlentry>
       
    51 <dt>Viewport</dt>
       
    52 <dd><p>The viewport is a rectangular area of an external surface all or part
       
    53 of which is to be displayed. You can think of the viewport as the source. </p> </dd>
       
    54 </dlentry>
       
    55 <dlentry>
       
    56 <dt>Extent</dt>
       
    57 <dd><p>The extent is a rectangular area in the composition scene in which
       
    58 all or part of the viewport is placed. The content of the viewport can be
       
    59 scaled and rotated within the extent relative to its normal size and orientation.
       
    60 The extent is normally a window to which the external surface is attached. </p> </dd>
       
    61 </dlentry>
       
    62 </dl> <p>The following diagram provides a cross-section view through the surfaces
       
    63 shown in the previous figure. Notice that the UI surface is the topmost layer
       
    64 and that it contains a hole through which the external surface
       
    65 can be seen.</p> <fig id="GUID-4DB99814-988F-5D51-A1A7-E864B6DA6DFB">
       
    66 <title>              A cross section through the surfaces, showing the display
       
    67 output            </title>
       
    68 <image href="GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e171454_href.png" placement="inline"/>
       
    69 </fig> </section>
       
    70 <section id="GUID-F9D7659B-1325-5DC2-9D7A-9B6C0DFB8A62"><title>Supported Uses</title> <p>You
       
    71 can: </p> <ul>
       
    72 <li id="GUID-97CAD13E-1C70-59FF-B271-F3E77198086A"><p>Display an external
       
    73 surface (for example, video content or a viewfinder image) within a window. </p> </li>
       
    74 <li id="GUID-BD8FFB28-D56C-581B-9E1C-B2BD97FDAFBC"><p>Dynamically set or remove
       
    75 a background surface across multiple windows on the same screen without having
       
    76 to register and unregister the surface. This reduces resource churn and content
       
    77 transfer. </p> </li>
       
    78 <li id="GUID-0A3FD92E-7E99-5961-BC5A-3FBB970A7889"><p>Reconfigure the attributes
       
    79 of the surface such as its extent, viewport and orientation, after it is set
       
    80 as a background. </p> </li>
       
    81 <li id="GUID-6E962607-1E7D-516E-B855-15A1A67923B6"><p>Reposition the displayed
       
    82 surface on the window. </p> </li>
       
    83 <li id="GUID-26E561E7-92BB-5EBA-A3B9-F660507A258D"><p>Zoom in and out of the
       
    84 contents of the surface. </p> </li>
       
    85 <li id="GUID-287D3286-209B-5E01-B1C6-2373A2B07172"><p>Place the surface content
       
    86 in a specified window area rather than filling the entire window. </p> </li>
       
    87 <li id="GUID-6F2DCF0C-32D7-53CD-A2DD-4DBE662015B5"><p>Crop the surface content
       
    88 rather than using the entire surface. </p> </li>
       
    89 <li id="GUID-8E49A7FB-0709-5127-8C94-104C512EA6AC"><p>Rotate the contents
       
    90 of the background surface by quadrant angles. </p> </li>
       
    91 <li id="GUID-5631047A-A8AD-59DF-82FF-021964BA571D"><p>Flip the background
       
    92 surface from top to bottom and rotate it by 180° to achieve a mirroring effect. </p> </li>
       
    93 </ul> <p>The following diagrams shows some surface configuration use cases. </p> <fig id="GUID-FF25ED24-7A3D-5C4B-A711-D6AEA53E972F">
       
    94 <title>              Surface configuration use cases            </title>
       
    95 <image href="GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e171521_href.png" placement="inline"/>
       
    96 </fig> </section>
       
    97 <section id="GUID-7EAB8F5D-6290-5B63-B396-8A1FAE7D91A5"><title> Configuration</title> <p>There
       
    98 are a number of ways in which dynamically updated content can be configured
       
    99 to appear on a window. </p> <p><b>A single content surface filling the window </b> </p> <p>External
       
   100 content can be fitted onto a Window Server window. Each axis of the surface
       
   101 can be stretched independently of the other axis. The window must be a visible
       
   102 client window: <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> or <xref href="GUID-A5DFCFA7-7B2D-3872-B6D0-4526DF743630.dita"><apiname>RBlankWindow</apiname></xref>. </p> <p><b>Placement
       
   103 of a single surface on a selected area of the window </b> </p> <p>The position
       
   104 and display size for the external content can be specified as an area within
       
   105 the Window Server window, rather than filling the window. The window must
       
   106 be a visible client (<xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita"><apiname>RWindow</apiname></xref> or <xref href="GUID-A5DFCFA7-7B2D-3872-B6D0-4526DF743630.dita"><apiname>RBlankWindow</apiname></xref>)
       
   107 as before. You specify the area by using <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita#GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA/GUID-8984E1F8-2807-301D-B82B-A52CC4254B04"><apiname>TSurfaceConfiguration::SetExtent(const
       
   108 TRect&amp;           aExtent)</apiname></xref>. </p> <p>After the extent is specified,
       
   109 its size does not change if the window size changes but its position moves
       
   110 to maintain its relative position on the window. </p> <p><b>Clipping of a
       
   111 surface </b> </p> <p>Video sometimes needs to appear cropped, so that a sub-area
       
   112 of the video is displayed instead of the full image. The crop viewport is
       
   113 specified in surface co-ordinates. The cropped viewport fills the output extent
       
   114 (or the window when the extent is not specified). The content appears scaled
       
   115 if the size of the viewport does not match the size of the extent (or the
       
   116 window). </p> <p><b>Scaling </b> </p> <p>It is possible to arbitrarily scale
       
   117 a surface to user specifications using the extent and viewport features. Each
       
   118 axis is scaled independently. When the extent and viewport are coincident,
       
   119 no scaling occurs. Filtering can be applied by the implementation of stretching
       
   120 and shrinking. </p> <p><b>Rotation </b> </p> <p>The viewport can be displayed
       
   121 rotated relative to its normal orientation. For example, if there is a fixed
       
   122 camera on the front of a device and the device is rotated by 90°, the image
       
   123 captured by the camera needs to be rotated by 90° in the other direction to
       
   124 get the expected result. The orientation is always relative to the current
       
   125 device orientation. </p> <p><b>Flipping </b> </p> <p>An external surface can
       
   126 be flipped from top to bottom around the x axis. </p> <p><b>Atomic combination
       
   127 of these operations </b> </p> <p>All the above mentioned configurations can
       
   128 be specified and combined unambiguously for a particular content on a particular
       
   129 window. You can specify parameters for a combination of these configurations
       
   130 in a single operation. </p> <p><b>Changing surfaces </b> </p> <p>The surface
       
   131 assigned to a window can be changed. </p> <p><b>Reconfiguring </b> </p> <p>It
       
   132 is possible to change the configuration options applied to a surface without
       
   133 re-assigning the surface. </p> <p><b>Sharing surfaces </b> </p> <p>Content
       
   134 surfaces are transferable and sharable between windows. </p> <p>The initial
       
   135 registration step ensures that any resources allocated to the content surface
       
   136 are held while the surface is removed from one window and added to another.
       
   137 This reduces the likelihood of failure between operations. </p> </section>
       
   138 <section><title>API Summary</title> <p>This section provides a summary of
       
   139 the classes and functions that you use to manage surfaces: </p> <ul>
       
   140 <li id="GUID-D7C9343C-BFAB-5153-B3E6-E5EBA5859570"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-3E1EF2ED-7E9C-541F-A439-F2CBA5B6F211">RWindowBase</xref>  </p> </li>
       
   141 <li id="GUID-5AD3B9D5-60E8-5A2A-9C6B-4C914540FE9E"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-1DC9E4DF-248F-59A6-92A9-F756F73414B3">TSurfaceConfiguration</xref>  </p> </li>
       
   142 <li id="GUID-2627F547-B979-5682-A69A-97D89969F9B3"><p><xref href="GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita#GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7/GUID-E2A62988-58F8-5021-BA44-25AE3C3D95B5">RWsSession</xref>  </p> </li>
       
   143 </ul> </section>
       
   144 <section id="GUID-3E1EF2ED-7E9C-541F-A439-F2CBA5B6F211"><title>RWindowBase </title> <ul>
       
   145 <li id="GUID-7A5D0A6F-C0B6-5D87-B0F4-99C92FA8227B"><p> <codeph>SetBackgroundSurface(const
       
   146 TSurfaceConfiguration                 &amp;,TBool)</codeph> sets the background
       
   147 of the window to be a given surface. The <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref> argument
       
   148 contains the surface ID and the configuration attributes. Another form of
       
   149 the function simply takes a surface ID as an argument, which provides less
       
   150 control and auto-stretches the surface to fill the window. </p> </li>
       
   151 <li id="GUID-C86F37F7-5017-56F3-9B14-E3B8E0EC0E8A"><p> <codeph>RemoveBackgroundSurface()</codeph> removes
       
   152 any background surface that has been set to the window. </p> </li>
       
   153 <li id="GUID-11ABFBDE-556F-5096-810E-6BBA2C81C4B1"><p> <codeph>GetBackgroundSurface()</codeph> retrieves
       
   154 a copy of the current configuration for the background surface attached to
       
   155 the window. </p> </li>
       
   156 </ul> <p>See <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita"><apiname>RWindowBase</apiname></xref>. </p> </section>
       
   157 <section id="GUID-1DC9E4DF-248F-59A6-92A9-F756F73414B3"><title> TSurfaceConfiguration</title> <p>This
       
   158 class encapsulates the surface configuration attributes that can be specified
       
   159 while setting the background surface of a window. If the values for the attributes
       
   160 are not set, the default values for the corresponding attribute are used. </p> <p>Symbian
       
   161 recommends that the client validates the surface configuration data before
       
   162 passing it on to the server. Invalid data that inadvertently slips through
       
   163 the client-side validation mechanism, or maliciously bypasses it, causes a
       
   164 panic. </p> <p>See <xref href="GUID-59A10068-E37A-37CF-85C9-36D8DA6619FA.dita"><apiname>TSurfaceConfiguration</apiname></xref>. </p> </section>
       
   165 <section id="GUID-E2A62988-58F8-5021-BA44-25AE3C3D95B5"><title> RWsSession</title> <ul>
       
   166 <li id="GUID-B1A1CE19-6E12-5BA7-B79A-A6D7C44F5920"><p> <codeph>RegisterSurface()</codeph> registers
       
   167 a surface for use in composition on the screen associated with this device
       
   168 within this session. </p> </li>
       
   169 <li id="GUID-6678C53D-F0B5-5ADD-BCC7-43FC31E81FEE"><p> <codeph>UnregisterSurface()</codeph> removes
       
   170 the surface from the session’s register of surfaces that are used in composition
       
   171 on the screen associated with this device. </p> </li>
       
   172 <li id="GUID-9F5FF304-794C-5BC3-B16E-F036C859F1E2"><p> <codeph>PreferredSurfaceConfigurationSize()</codeph> returns
       
   173 the window server’s preferred size for the <codeph>TSurfaceConfiguration</codeph> object,
       
   174 used for <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-AC4FBD36-8CC7-3191-B266-1805DEDE6D50"><apiname>RWindow::SetBackgroundSurface()</apiname></xref>. </p> </li>
       
   175 </ul> <p>See <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref>. </p> </section>
       
   176 <section><title>Example</title> <p>This code snippet is provided for illustrative
       
   177 purposes only. A Window Server client application wants to run a 3D game full-screen
       
   178 at the native physical resolution of the display (either current or selected
       
   179 using a display controlling system application). This example assumes that
       
   180 the <xref href="GUID-BA6FEFAE-8891-3286-A38F-2EA522D7A27E.dita"><apiname>MDisplayMapping</apiname></xref> interface has already been obtained,
       
   181 as shown in <xref href="GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita">Display
       
   182 Control and Mapping in the Window Server Client</xref>. </p> <codeblock id="GUID-DE5C6DB0-1096-5BA3-8BB7-78AE3B6619B1" xml:space="preserve">// Establish connection and get display mapping interface.
       
   183 RWindowGroup group = RWindowGroup(iSession);
       
   184 RWindow window(iSession);
       
   185     
       
   186 group.Construct(1, iScreenDevice);
       
   187 window.Construct(group, 2);
       
   188     
       
   189 TRect winExtent;
       
   190 iDisplayMapping.GetMaximumWindowExtent(winExtent);
       
   191 window.SetExtent(winExtent);
       
   192     
       
   193 // Map window size to composition coordinates
       
   194 TRect surfaceExtent;
       
   195 iDisplayMapping.MapCoordinates(EApplicationSpace, winExtent,
       
   196     ECompositionSpace, surfaceExtent);
       
   197     
       
   198 RSurfaceManager::TSurfaceCreationAttributes attribs;
       
   199 attribs.iSize = surfaceExtent.Size();
       
   200     
       
   201 // Set up other attributes and create surface
       
   202     
       
   203 window.SetBackgroundSurface(surface);
       
   204     
       
   205 window.Activate();
       
   206 </codeblock> <p>A similar approach can be used by other surface content providers,
       
   207 such as video. </p> </section>
       
   208 </conbody><related-links>
       
   209 <link href="GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita"><linktext>Graphics
       
   210 Composition</linktext></link>
       
   211 
       
   212 <link href="GUID-1F9A47CE-7F4C-52BD-8823-25D5D1BEF42F.dita"><linktext>Window Server
       
   213 Client-Side Library Concepts</linktext></link>
       
   214 <link href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita"><linktext>Dynamic Resolution
       
   215 Switching</linktext></link>
       
   216 <link href="GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita"><linktext>Flipping
       
   217 and Rotating an External  Surface</linktext></link>
       
   218 </related-links></concept>