Creating a Render Stage Plug-in

Background information

This topic assumes that you have a general understanding of render stages and ECom. For more information on these topics, see:

• Using ECom

• Render Stages

Summary

Creating and configuring a render stage plug-in involves the following:

• Implementing the render stage classes

• Packaging the plug-ins

• Configuring the render stage chain

Implementing the render stage classes

The render stage factory

For each render stage plug-in, you must create a concrete render stage factory class, which must be able to produce the render stage object. The render stage factory class must derive from CWsPlugin and MWsRenderStageFactory, as shown in the following diagram.

Figure 1. Render stage factory class diagram

CWsPlugin is a thin wrapper around the Symbian ECom functionality.

The render stage itself

For each render stage plug-in, you must create a concrete render stage class that derives from CWsRenderStage. In ScreenPlay, the render stage is responsible for constructing the pixel target. Typically, you would do this in the ConstructL() function. Other important functions to implement are Begin() and End().

You must also create implementations of all of the required render stage interfaces, plus any optional ones that you want to use. You can do this in the main render stage class itself, or you can delegate them to a helper class. If delegated to a helper class, multiple render stage plug-ins could potentially share the same implementation of some of the interfaces.

If the render stage is to host a transition effect (TFX) engine, you need to implement the transition effects.

For example render stage plug-ins, see the reference render stages provided by Symbian. These are located in os/graphics/windowing/windowserverplugins/.

Packaging the plug-ins

Render stage plug-ins are ECom plug-ins and as such they require an ECom resource file that must specify the UIDs of the DLL, interface and implementation(s), respectively. The interface is defined by CWsPlugin and its UID is 0x10285A29. You can optionally wrap up multiple render stage plug-ins in a single DLL. This would then have a single ECom resource file. See How to Provide ECom Registry Information for more information.

For an example render stage plug-in resource file, see the one provided for the reference render stages. This is located in os/graphics/wserv_std_plugins/src.

Configuring the render stage chain

You configure the render stage chain in the wsini.ini file. Here is an example:

// General parameters.
// ...
    
// Specify the plug-ins you want the Window Server to load.
PLUGINS tfxrenderstage fbrenderstage display 
    
[SCREEN0] // This section configures the first screen.
//...
    
// Configure the render stage chain for the first screen.
RENDERSTAGES tfxrenderstage display
    
[SCREEN1] // This section configures the second screen.
//...
    
// Configure the render stage chain for the second screen.
RENDERSTAGES fbrenderstage display
    
[TFXRENDERSTAGE] // This section configures tfxrenderstage.
ID 0x12345678
    
[FBRENDERSTAGE] // This section configures fbrenderstage.
ID 0x12345679

• The PLUGINS parameter controls which plug-ins the Window Server loads when it starts up. If you supply your own plug-ins and want to use any of the default plug-ins supplied by Symbian, you need to specify them here.

• The RENDERSTAGES parameter configures the render stage chain. You can specify this separately for each screen, so that different effects can be used for each screen.

• For each plug-in that you specify, create a separate section to specify its details (such as UID and type).

• TFX render stages that implement their own visual stores typically use the CHANGETRACKING parameter to put the Window Server rendering loop into change-tracking mode, rather than the default dirty-rectangle tracking mode. See Window Server Rendering Loop for more information.

• In addition, you can optionally use parameters in the wsini.ini file to set up dynamic screen modes and configure the render stage display control handling. For example, the reference render stage chain uses the DP_SCALING parameter to specify the type of scaling. However, this is not mandatory.

See The wsini.ini File Reference for more information.