<?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-2C443E6F-BC3D-5252-8098-9F850AA88A35" xml:lang="en"><title>Window

Server Component Overview</title><shortdesc>The Window Server manages the use of the screen and input devices

by applications and controls and co-ordinates access. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-4BE363E2-E630-462D-A958-721B3636792E"><title>Architecture</title> <p>The

architecture of the Window Server varies depending on whether you are using

the <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay (NGA)</xref> or <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref> variant.

However, with a few exceptions, the client-side API is the same in both variants.

Both variants use an improved version of the Window Server, sometimes known

as <codeph>WSERV2</codeph>, which was introduced in Symbian^2 (Symbian OS

v9.4). </p> <p>The following diagram provides an overview of the Window Server

architecture in ScreenPlay. </p> <fig id="GUID-80DA5DEB-019E-5CE3-812E-496A1D713FFB">

<title>              The Window Server in ScreenPlay            </title>

<image href="GUID-1635E243-BDC9-55D8-8913-0D2DB622B22C_d0e237066_href.png" placement="inline"/>

</fig> <p>Below we list some of the key features of the Window Server, including

differences between the two architectures. The term <b>surface</b> is used

in ScreenPlay for a hardware-independent memory buffer for holding an image

or part of a scene. The <b>UI surface</b> is a special surface onto which

the Window Server renders all of the UI content. It is created automatically

during system start up. An <b>external surface</b> is any other surface—for

example, a surface that holds a video or to which OpenGL ES content is rendered. </p> <ul>

<li id="GUID-A56D68E9-99E0-528A-9DDD-977BECE50A45"><p>The Window Server has

a render stage framework, which enables the last stage of the Window Server

rendering to be customizable through plug-ins called <b> render stages</b>.

These can be chained to form a rendering pipeline, which takes the drawing

operations that are produced by the Window Server and ultimately passes them

to the UI surface. Render stages can selectively filter, modify, or redirect

the draw operation stream, as required—for example, to perform transition

effects (TFX). </p> </li>

<li id="GUID-A6589F28-B8B5-5FBA-B241-6E526D6A9BF1"><p>In ScreenPlay, composition

takes place in two stages. First, the render stages render the drawing to

the UI surface. Then the composition engine combines the UI surface and any

external surfaces into elements (sometimes called <b>layers</b>) and composes

them to the screen. This enables the composition to be performed in software

or hardware accelerator chips. </p> </li>

<li id="GUID-BA8D10A1-F0CB-56F7-817B-F1425AC1DA56"><p>In the non-ScreenPlay

variant, the concept of surfaces is not used and the Window Server composes

directly onto the <b>frame buffer</b> which is then displayed on the screen. </p> </li>

<li id="GUID-FC88013B-E5A4-5DD6-9906-A526D137CF43"><p>There are differences

in the plug-in framework APIs in the two architectures. In addition, in ScreenPlay,

fading effects are implemented by using render stages, whereas when ScreenPlay

is not enabled they are implemented by using a separate fader plug-in type

(not shown on the diagram). </p> </li>

<li id="GUID-86A8FB36-B9DF-50F2-AE0B-798D717899A6"><p>In ScreenPlay, the Window

Server provides advanced pointer features, such as support for multiple pointers

and proximity and pressure coordinates. The non-ScreenPlay variant does not

provide this support. </p> </li>

<li id="GUID-46123A93-AF91-5FAB-995E-CDEAE9C8B961"><p>ScreenPlay provides

support for externally connected displays, such as TV-out. The non-ScreenPlay

variant considers the size of each display to be fixed. However, for High-Definition

Multimedia Interface (HDMI) and composite video connectors, there are a range

of resolutions that can change dynamically. ScreenPlay provides an optional

feature that supports switching between resolutions at runtime and notifications

to Window Server clients when there are changes to the resolution and connectedness. </p> </li>

</ul> </section>

<section id="GUID-2459A480-EC83-4595-97AA-D090331C9A88"><title>Building the

ScreenPlay and non-ScreenPlay variants</title> <p>To build the ScreenPlay

version of the Window Server components, declare the following macros in the <filepath>Symbian_OS.hrh</filepath> file. </p><codeblock xml:space="preserve">SYMBIAN_BUILD_GCE

SYMBIAN_GRAPHICS_BUILD_OPENWF_WSERV

</codeblock><p>This causes the ScreenPlay versions of the components in the

Graphics package to be built in addition to the non-ScreenPlay components.

Specifically the <codeph>SYMBIAN_BUILD_GCE</codeph> macro causes the ScreenPlay

version of the Window Server to be built. This means that the <filepath>w32_nga.mmp</filepath> and <filepath>wserv_nga.mmp</filepath> files

are built. These define a second macro, <codeph>SYMBIAN_GRAPHICS_GCE</codeph>,

which causes the ScreenPlay Window Server classes to be built. </p> <p>To include the ScreenPlay versions when building

ROM, use the <codeph>SYMBIAN_GRAPHICS_USE_GCE</codeph> flag. </p> </section>

<section id="GUID-BEBE7D33-06C7-4B07-837E-9E67633EEFBF"><title>Selecting the

ScreenPlay variant in the emulator</title><p>To select the ScreenPlay version

of the component in the emulator, add the following line to the <filepath>epoc.ini</filepath> file: </p> <codeblock id="GUID-E0A64D1F-19B8-5002-8031-06E58AAE0055" xml:space="preserve">SYMBIAN_GRAPHICS_USE_GCE ON</codeblock></section>

<section id="GUID-F13720C7-A6E1-4A3F-ACAF-10BEF6D2229F"><title>Executables</title> <p>This

section lists the main Window Server executables. For clarity, these are divided

into three groups. </p> <p><b>Window Server executable and client-side libraries </b> </p> <table id="GUID-E68F0783-FE52-55F3-8140-0FD527E91775">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Executable</entry>

<entry>LIB</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath>wserv_nga.exe</filepath>  </p> </entry>

<entry><p> </p> </entry>

<entry><p>The ScreenPlay version of the Window Server. </p> </entry>

</row>

<row>

<entry><p> <filepath>wserv_nonnga.exe</filepath>  </p> </entry>

<entry><p> </p> </entry>

<entry><p>The non-ScreenPlay version of the Window Server. </p> </entry>

</row>

<row>

<entry><p> <filepath>ws32_nga.dll</filepath>  </p> </entry>

<entry><p> <filepath>ws32.lib</filepath>  </p> </entry>

<entry><p>The Window Server client-side API library for the ScreenPlay variant.

See <xref href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita">Window Server Client-Side

Library</xref>. </p> </entry>

</row>

<row>

<entry><p> <filepath>ws32_nonnga.dll</filepath>  </p> </entry>

<entry><p> <filepath>ws32.lib</filepath>  </p> </entry>

<entry><p>The Window Server client-side API library for the non-ScreenPlay

variant. See <xref href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita">Window

Server Client-Side Library</xref>. </p> </entry>

</row>

<row>

<entry><p> <filepath>wsgraphicdrawer_nga.dll</filepath>  </p> </entry>

<entry><p> <filepath>wsgraphicdrawer.lib </filepath>  </p> </entry>

<entry><p>The server-side base classes for Window Server plug-ins in the ScreenPlay

variant. The plug-ins include graphic drawer plug-ins (which are also known

as Content Rendering Plug-ins or CRPs) and render stage plug-ins. </p> </entry>

</row>

<row>

<entry><p> <filepath>wsgraphicdrawer_nonnga.dll</filepath>  </p> </entry>

<entry><p> <filepath>wsgraphicdrawer.lib </filepath>  </p> </entry>

<entry><p>The server-side base classes for Window Server plug-ins in the non-ScreenPlay

variant. The plug-ins include graphic drawer plug-ins (which are also known

as Content Rendering Plug-ins or CRPs) and render stage and fader plug-ins. </p> </entry>

</row>

<row>

<entry><p> <filepath>remotegc_nga.dll </filepath>  </p> </entry>

<entry><p> <filepath>remotegc.lib </filepath>  </p> </entry>

<entry><p>The client-side API library for remote graphic contexts in ScreenPlay.

Remote graphic contexts store draw operations so that they can be played back

later. It is "remote" because the draw operations are generally played back

in a different location from where they are stored. For example, the draw

operations are frequently stored on the client side and then a transformation

engine uses them on the server side to make an effect. </p> </entry>

</row>

<row>

<entry><p> <filepath>remotegc_nonnga.dll </filepath>  </p> </entry>

<entry><p> <filepath>remotegc.lib </filepath>  </p> </entry>

<entry><p>The client-side API library for remote graphic contexts in the non-ScreenPlay

variant. This has a similar role as in ScreenPlay. </p> </entry>

</row>

<row>

<entry><p> <filepath>profilerkeys.dll </filepath>  </p> </entry>

<entry/>

<entry><p>Window Server profiling hotkeys library in both ScreenPlay and non-ScreenPlay

variants. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Logging libraries </b> </p> <table id="GUID-C233B864-B909-5C00-B90A-7C78F3D02AFC">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Executable</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath>dlog.dll </filepath>  </p> </entry>

<entry><p>On-screen logging library </p> </entry>

</row>

<row>

<entry><p> <filepath>dlogfl.dll </filepath>  </p> </entry>

<entry><p>File logging library </p> </entry>

</row>

<row>

<entry><p> <filepath>dlogrd.dll </filepath>  </p> </entry>

<entry/>

</row>

<row>

<entry><p> <filepath>dlogsr.dll </filepath>  </p> </entry>

<entry><p>Serial logging library </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Plug-ins </b> </p> <table id="GUID-E71B0099-14D9-5C44-99FA-1DDB535EB7BF">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Executable</entry>

<entry>Variant</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath>10281922.dll</filepath>  </p> </entry>

<entry><p>Both </p> </entry>

<entry><p>This is a standard reference CRP. This type of plug-in is called

a <i>CWsGraphics</i> ECOM plug-in. Device creators can replace this component. </p> </entry>

</row>

<row>

<entry><p> <filepath>2001b70b.dll</filepath>  </p> </entry>

<entry><p>Non-ScreenPlay </p> </entry>

<entry><p>This is a prototype reference render stage ECOM plug-in for the

non-ScreenPlay variant. This type of plug-in is called a <i>CWsPlugin</i>. </p> <p>Note:

The ScreenPlay render stage ECOM plug-in is delivered in the Window Server

Plugins component. </p> </entry>

</row>

<row>

<entry><p> <filepath>10285c4a.dll </filepath>  </p> </entry>

<entry><p>ScreenPlay </p> </entry>

<entry><p>This is a reference ScreenPlay surface-based CRP. Device creators

can replace this component. </p> </entry>

</row>

<row>

<entry><p> <filepath>samplegraphicsurface.dll </filepath>  </p> </entry>

<entry><p>ScreenPlay </p> </entry>

<entry><p>Sample ScreenPlay CRP (<i>CWsGraphics</i>) that demonstrates placing

a surface. </p> </entry>

</row>

<row>

<entry><p> <filepath>w32stdgraphic.dll </filepath>  </p> </entry>

<entry><p>Both </p> </entry>

<entry><p>Sample CRP (<i>CWsGraphics</i>). </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-439B39AD-4184-4928-BF35-ABAB94A89400"><title>Typical uses</title> <ul>

<li id="GUID-BF47989B-D205-5ED8-BBCF-44B099E15C97"><p>Application developers

use the <xref href="GUID-DC5E8C7D-D697-53E8-87F4-344301430E61.dita">client-side

library</xref> to control windows in their applications and respond to key

and pointer events. </p> </li>

<li id="GUID-51A64C2E-C689-5765-8455-02C6350E4E88"><p>Testers and application

developers use the <xref href="GUID-6E8807F5-9CC0-5A70-8182-22230D43AA9E.dita">logging

mechanism</xref> to log Window Server events when developing and testing their

code. </p> </li>

<li id="GUID-139581CB-1185-569E-878D-58088230CCE8"><p>Device creators create

Content Rendering Plug-ins (CRPs) for showing customized content on the screen. </p> </li>

<li id="GUID-75EE03DE-0F78-5114-BCB9-8DD648A7C3A3"><p>Device creators who

use ScreenPlay, can create render stage plug-ins. These enable the output

of the Window Server to be combined with auxiliary software subsystems (such

as a transition effect engine) and hardware-accelerated drawing (for example,

using OpenVG). </p> </li>

<li id="GUID-E712A357-5797-5291-829E-C054463FD286"><p>Device creators use

the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini file</xref> to

configure the Window Server to suit the specific requirements of the particular

device. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-0C4B86B5-530A-5839-86C1-46E7ABE281E0.dita"><linktext>Window Server

Component</linktext></link>

<link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita">

<linktext>Render-Stages</linktext></link>

<link href="GUID-E7F6DD98-9080-50E9-B071-56247EBBF570.dita">

<linktext>Window Server Plugins Component</linktext></link>