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-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7" xml:lang="en"><title>Creating

    13 a Render Stage Plug-in</title><shortdesc>This topic provides information about creating and configuring

    14 a render stage plug-in. It applies to ScreenPlay and is aimed at device creators

    15 and system integrators who want to create a customized rendering pipeline. </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 <section><title>Background information</title> <p>This topic assumes that

    19 you have a general understanding of render stages and ECom. For more information

    20 on these topics, see: </p> <ul>

    21 <li id="GUID-189C0DEB-01AC-554D-B5BF-45C17F84A38D"><p><xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">Using

    22 ECom</xref>  </p> </li>

    23 <li id="GUID-48020C41-8795-53EE-9D24-D9E6C0586742"><p><xref href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita">Render

    24 Stages</xref>  </p> </li>

    25 </ul> </section>

    26 <section><title>Summary</title> <p>Creating and configuring a render stage

    27 plug-in involves the following: </p> <ul>

    28 <li id="GUID-15333AD7-E535-57F7-8A61-068F44C0F362"><p><xref href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita#GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7/GUID-D7F5CCDE-3A35-582F-B480-6D77E26DE0C1">Implementing the render stage classes</xref>  </p> </li>

    29 <li id="GUID-B6723CA4-635A-5EC7-99C3-17EF627E04D5"><p><xref href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita#GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7/GUID-233E8010-2BF7-563D-94D9-8CFAE61F21EF">Packaging the plug-ins</xref>  </p> </li>

    30 <li id="GUID-C2C9D2F5-C84B-520B-8C99-84780890850D"><p><xref href="GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7.dita#GUID-98EA7E2B-4AC6-55AE-985F-B5EE1E0A79E7/GUID-140EDD81-76DF-5EF6-A34B-AE53283DBC73">Configuring the render stage chain</xref>  </p> </li>

    31 </ul> </section>

    32 <section id="GUID-D7F5CCDE-3A35-582F-B480-6D77E26DE0C1"><title>Implementing

    33 the render stage classes</title> <p><b>The render stage factory </b> </p> <p>For

    34 each render stage plug-in, you must create a concrete render stage factory

    35 class, which must be able to produce the render stage object. The render stage

    36 factory class must derive from <xref href="GUID-28DEFD88-3AB5-3F94-9A26-27B240294950.dita"><apiname>CWsPlugin</apiname></xref> and <xref href="GUID-DE3DA8CA-437D-33B8-A747-941810A48897.dita"><apiname>MWsRenderStageFactory</apiname></xref>,

    37 as shown in the following diagram. </p> <fig id="GUID-EFC66A6D-29E4-58FC-810C-A3BA276E0734">

    38 <title>              Render stage factory class diagram            </title>

    39 <image href="GUID-BFD09EE5-CCB3-5498-BAA6-86F537DE9155_d0e220381_href.png" placement="inline"/>

    40 </fig> <p> <xref href="GUID-28DEFD88-3AB5-3F94-9A26-27B240294950.dita"><apiname>CWsPlugin</apiname></xref> is a thin wrapper around the Symbian

    41 ECom functionality. </p> <p><b>The render stage itself </b> </p> <p>For each

    42 render stage plug-in, you must create a concrete render stage class that derives

    43 from <xref href="GUID-B89CEF40-0139-3E6F-803D-F74E2BCB029A.dita"><apiname>CWsRenderStage</apiname></xref>. In ScreenPlay, the render stage is

    44 responsible for constructing the pixel target. Typically, you would do this

    45 in the <xref href="GUID-C8E0575D-5A7F-3D00-9BE5-AD8D6DBCF2F7.dita"><apiname>ConstructL()</apiname></xref> function. Other important functions

    46 to implement are <xref href="GUID-96129474-AC75-350C-90EB-A8AF8E1CC663.dita"><apiname>Begin()</apiname></xref> and <xref href="GUID-95ED21B6-F0E5-3C9F-8AC3-CD73AD32E59D.dita"><apiname>End()</apiname></xref>. </p> <p>You

    47 must also create implementations of all of the required <xref href="GUID-11BC2AAA-FDB8-5600-8488-F27A9552E336.dita">render

    48 stage interfaces</xref>, plus any optional ones that you want to use. You

    49 can do this in the main render stage class itself, or you can delegate them

    50 to a helper class. If delegated to a helper class, multiple render stage plug-ins

    51 could potentially share the same implementation of some of the interfaces. </p> <p>If

    52 the render stage is to host a transition effect (TFX) engine, you need to

    53 implement the transition effects. </p> <p>For example render stage plug-ins,

    54 see the reference render stages provided by Symbian. These are located in <filepath>os/graphics/windowing/windowserverplugins/</filepath>. </p> </section>

    55 <section id="GUID-233E8010-2BF7-563D-94D9-8CFAE61F21EF"><title>Packaging the

    56 plug-ins</title> <p>Render stage plug-ins are ECom plug-ins and as such they

    57 require an ECom resource file that must specify the UIDs of the DLL, interface

    58 and implementation(s), respectively. The interface is defined by <xref href="GUID-28DEFD88-3AB5-3F94-9A26-27B240294950.dita"><apiname>CWsPlugin</apiname></xref> and

    59 its UID is 0x10285A29. You can optionally wrap up multiple render stage plug-ins

    60 in a single DLL. This would then have a single ECom resource file. See <xref href="GUID-9A9103E4-27B0-5CF3-855A-DCD44795A5C0.dita">How to Provide ECom Registry

    61 Information</xref> for more information. </p> <p>For an example render stage

    62 plug-in resource file, see the one provided for the reference render stages.

    63 This is located in <filepath>os/graphics/wserv_std_plugins/src</filepath>. </p> </section>

    64 <section id="GUID-140EDD81-76DF-5EF6-A34B-AE53283DBC73"><title>Configuring

    65 the render stage chain</title> <p> </p> <p>You configure the render stage

    66 chain in the <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini

    67 file</xref>. Here is an example: </p> <codeblock id="GUID-05CDB5C8-D6A0-5614-9CEE-7DCCF99FBB2E" xml:space="preserve">

    68 // General parameters.

    69 // ...

    70     

    71 // Specify the plug-ins you want the Window Server to load.

    72 PLUGINS tfxrenderstage fbrenderstage display 

    73     

    74 [SCREEN0] // This section configures the first screen.

    75 //...

    76     

    77 // Configure the render stage chain for the first screen.

    78 RENDERSTAGES tfxrenderstage display

    79     

    80 [SCREEN1] // This section configures the second screen.

    81 //...

    82     

    83 // Configure the render stage chain for the second screen.

    84 RENDERSTAGES fbrenderstage display

    85     

    86 [TFXRENDERSTAGE] // This section configures tfxrenderstage.

    87 ID 0x12345678

    88     

    89 [FBRENDERSTAGE] // This section configures fbrenderstage.

    90 ID 0x12345679</codeblock> <ul>

    91 <li id="GUID-02A77490-F545-53AC-A4C9-FA9A60F49297"><p>The <codeph>PLUGINS</codeph> parameter

    92 controls which plug-ins the Window Server loads when it starts up. If you

    93 supply your own plug-ins and want to use any of the default plug-ins supplied

    94 by Symbian, you need to specify them here. </p> </li>

    95 <li id="GUID-F3539B28-CDEB-5A4B-97B8-197AD14083A4"><p>The <codeph>RENDERSTAGES</codeph> parameter

    96 configures the render stage chain. You can specify this separately for each

    97 screen, so that different effects can be used for each screen. </p> </li>

    98 <li id="GUID-FC95C274-2E4E-514E-B2DC-BA221DFE5FB7"><p>For each plug-in that

    99 you specify, create a separate section to specify its details (such as UID

   100 and type). </p> </li>

   101 <li id="GUID-52F01B4D-5CDC-591B-BB02-046FCF8E81BE"><p>TFX render stages that

   102 implement their own visual stores typically use the <codeph>CHANGETRACKING</codeph> parameter

   103 to put the Window Server rendering loop into change-tracking mode, rather

   104 than the default dirty-rectangle tracking mode. See <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window

   105 Server Rendering Loop</xref> for more information. </p> </li>

   106 <li id="GUID-5DD25953-C7A0-537F-BF16-9C7A95C534E5"><p>In addition, you can

   107 optionally use parameters in the <filepath>wsini.ini</filepath> file to set

   108 up dynamic screen modes and configure the render stage <xref href="GUID-2B6D3A9D-1481-5587-A954-48CE7EC311EE.dita">display

   109 control handling</xref>. For example, the reference render stage chain uses

   110 the <codeph>DP_SCALING</codeph> parameter to specify the type of scaling.

   111 However, this is not mandatory. </p> </li>

   112 </ul> <p>See <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">The wsini.ini

   113 File Reference</xref> for more information. </p> </section>

   114 </conbody><related-links>

   115 <link href="GUID-3A2785D4-6185-50C3-8D7E-5D94CD2B7C98.dita"><linktext>Render Stages</linktext>

   116 </link>

   117 </related-links></concept>