<?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-A40C75A2-59FF-5472-B279-8B5FBFF68794" xml:lang="en"><title>Content

Rendering Plug-ins (CRPs) Overview</title><shortdesc>Content Rendering Plug-ins (CRPs) are Window Server plug-ins that

can perform custom drawing in response to client requests. The client simply

calls <codeph>CWindowGc::DrawWsGraphic(TWsGraphicId, TRect)</codeph>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>To the client, a CRP call appears like any other draw operation—the thing

it most resembles is drawing a bitmap. In particular, a CRP call can be issued

as part of a stream of draw operations. If there are draw operations before

and after the CRP call, it may draw above some elements and other elements

may be drawn above it. This is in contrast to anims and sprites, which always

appear above other window drawing. </p>

<p>On the server side, the plugin provides a subclass of <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer</apiname></xref>. When the client’s <codeph>CWindowGc::DrawWsGraphic()</codeph> call is processed,

the appropriate <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer</apiname></xref> subclass

is called to perform the rendering. </p>

<p>CRPs have several benefits: </p>

<ul>

<li id="GUID-EAF066AE-72E8-5029-B7EA-B2F6BB4D80E7"><p> <b>Content abstraction</b> —the

client has no knowledge of what is rendered—that is left to the plug-in. As

a result, CRPs can enable the appearance of an application to be customized

without any change to application code. (This is similar to the use of skin

bitmaps to customize application appearance, but it goes further.) </p> </li>

<li id="GUID-B175FE51-4BF5-56A6-8AD9-D4A03A48F7BB"><p> <b>Server-side execution</b> —CRP

rendering code executes inside the Window Server process. This means that

it is less susceptible to interruptions under CPU loading than client-side

code. However, it also means that CRPs must be written with greater care,

because their failure can cause a device reset rather than a simple application

exit. </p> </li>

<li id="GUID-459F38EA-08E3-54E0-B761-51ED774DFCA9"><p> <b>Animation</b> —CRPs

are able to schedule their own reanimation within the Window Server. This

is managed by the Window Server animation scheduler and so provides more reliable

animation than can be achieved from the client-side alone. </p> </li>

</ul>

<p>CRPs are generally written by device creators for showing customized content

on the screen. For example, a CRP might be an SVG renderer, where the client

application provides data in the form of an SVG source file and the CRP decodes

and renders it. </p>

<p>Unlike animations created using <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CAnim</apiname></xref>,

other drawing can appear above the CRP-based content within the same window. </p>

<section id="GUID-01B7CC86-E06B-467E-B75B-ED5FCA1839C6"><title>Architecture</title> <p>The following diagram shows how the

client application and the server-side CRP work together: </p> <fig id="GUID-DCD46D7C-575D-5F96-B9AF-118FEB6DA8DC">

<title>              Figure 1: Relationship of a client application and the

CRP            </title>

</fig> <dl>

<dlentry>

<dt>Client UI application</dt>

<dd><p>This originates the draw request that drives the system to render the

result of a CRP to a given location of the screen. </p> </dd>

</dlentry>

<dlentry>

<dt>Server-side CRP</dt>

<dd><p>This runs in the Window Server process. It has the priorities and privileges

of the Window Server. </p> </dd>

</dlentry>

</dl> <p>Prioritized scheduling and access to Window Server resources enable

CRPs to function more efficiently than if they were modeled in the client

UI application. </p> <p>The typical workflow in the client application is

as follows: </p> <ol id="GUID-889BC31D-0085-521B-AF16-D78320B00D9C">

<li id="GUID-5B5B06A5-9AFF-56DA-8A66-48CC6A74DA20"><p>Set up the necessary

CRPs by calling constructors. </p> </li>

<li id="GUID-E499C0CC-709A-5D52-8A60-706FBB0B1F32"><p>Set application-specific

values for the CRP by sending method calls from the client UI application

to the client-side CRP proxy (there is more information about this below). </p> </li>

<li id="GUID-9F2D8783-9DAC-5C22-9AE6-789FA7B5D5FD"><p>Call the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWindowGc::DrawWsGraphic()</apiname></xref> command. This initiates the drawing,

which is actually done by the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer::DoDraw()</apiname></xref> method of the server-side CRP. </p> </li>

</ol> </section>

<section id="GUID-ACE9A1E6-C9C5-49E3-B10A-72A6B1D8DCB4"><title>Graphic Drawer library details</title> <p>The following table

shows the DLLs that provide the server-side functionality. </p> <table id="GUID-E4F2FF7F-87D6-5F36-BDAF-74B16746B5E1">

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

<thead>

<row>

<entry>DLL</entry>

<entry>LIB</entry>

<entry>Short description</entry>

</row>

</thead>

<tbody>

<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 graphic drawers in the ScreenPlay

variant. </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 graphic drawers in the non-ScreenPlay

variant. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-FBB7F0CA-045B-441D-B0D9-55543AFBEA57"><title>APIs</title> <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref>. </p> <p>Assuming

the construction of objects has been done, the client UI application issues

a <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWindowGc::DrawWsGraphic()</apiname></xref> call

each time it wants a CRP to be shown on the screen. For our SVG rendering

example, the UI application simply decides where on the screen the CRP is

to be shown. </p> <p>Any additional information (such as the location of the

SVG file) is handled by the client-side CRP proxy. This is a subclass of <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphic</apiname></xref>.

You can pass application-specific data to the server-side CRP by implementing

the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphic::SendMessage()</apiname></xref> method.

When a client-side CRP invokes <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphic::SendMessage()</apiname></xref>, the server-side CRP receives a <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer::HandleMessage()</apiname></xref> call. </p> <p>The client-side UI application uses the GDI interface to issue

draw commands. <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWindowGc::DrawWsGraphic()</apiname></xref> can

be considered to be just another draw command. </p> <p>The server-side CRP

interface is defined by the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer</apiname></xref> interface.

This cannot be extended. However, the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer::HandleMessage()</apiname></xref> method that accepts a data buffer can be interpreted in an application-specific

manner by the server-side CRP author. </p> <p><b>Summary </b> </p> <table id="GUID-5418A2B7-B872-55FF-B0A3-A61E47D70997">

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

<thead>

<row>

<entry>API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer</apiname></xref>  </p> </entry>

<entry><p>The abstract base class for the server-side graphic drawer. Each

CRP has a concrete implementation of this class. The most important function

is <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer::DoDraw(MWsGc,

TRect)</apiname></xref>, which issues the drawing commands. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>MWsGc</apiname></xref>  </p> </entry>

<entry><p>This is provided to the graphic drawer in the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphicDrawer::DoDraw(MWsGc,

TRect)</apiname></xref> function. There main things to note about this interface: </p> <ul>

<li id="GUID-7C8FF1A8-D0E7-55CE-A7D2-9D26BAE9884F"><p>Because it is derived

from <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>MWsObjectProvider</apiname></xref>,

it provides the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>MWsObjectProvider::ResolveObjectInterface()</apiname></xref> function. The CRP can call this to obtain a concrete implementation of the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>MWsGraphicsContext</apiname></xref> interface

against which to issue draw operations. </p> </li>

<li id="GUID-B60F4FE8-E982-56B0-8403-9C724B0AC33C"><p>It provides the <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>MWsGc::ScheduleAnimation()</apiname></xref> function,

which as its name suggests enables the CRP to schedule animations. During

drawing, the CRP can ask to be drawn again after a specified time period. </p> </li>

</ul> <p>CRPs do not need to hold onto a handle to a graphic context, because

they are passed one every time they are required to draw. This means that

other parts of the Window Server (specifically render stages) can safely redirect

drawing without any concern that CRPs hold invalid graphics contexts. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>CWsGraphic</apiname></xref>  </p> </entry>

<entry><p>This is the abstract base class for the client-side proxy. This

serves a function similar to <xref href="GUID-213DF770-58AE-3176-93E8-8D72E516AE45.dita"><apiname>RAnim</apiname></xref>,

enabling the client to control the CRP's state remotely. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

</conbody><related-links>

<link href="GUID-5D81D4E2-BE8B-58CE-A745-4F044DE2FB5F.dita"><linktext>Window Server

Plug-in                 Framework</linktext></link>

</related-links></concept>