Creating +a Render Stage Plug-in

Variant: ScreenPlay. Target +audience: Device creators.

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.

+ 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.