MAknsRlEffect Class Reference

#include <mw/AknsRlEffect.h>

class MAknsRlEffect

Public Member Functions
pure virtual void	ActivateL(MAknsRlEffectContext *)
pure virtual void	Deactivate()
pure virtual void	GetCapabilities(TAknsRlEffectCaps &)
pure virtual void	InitializeL()
pure virtual void	Release()
pure virtual TInt	Render(const TAknsRlRenderOpParam &)
pure virtual void	SetParametersL(MAknsRlParameterIterator &)

Detailed Description

Interface to skin effect plugin implementation.

States of an effect plugin are:

Dead: Effect plugin has not been created. Destructing the plugin returns the plugin to this state.
Created: Effect plugin has been created (by calling its default constructor). No dynamic data can be allocated at this state. Call to Release returns the plugin to this state.
Initialized: Effect plugin has been successfully initialized (by calling InitializeL). Any dynamic data (common to the entire lifetime of the plugin) has been constructed. Call to Deactivate returns the plugin to this state.
Activated: Effect plugin has been successfully activated for rendering (by calling ActivateL). This is the only state where parameter setup or rendering can take place.

A plugin instance is owned by the effect pool. A plugin instance is activated by the effect renderer to perform one rendering operation.

The effect renderer maintains a set of layers to store graphical content during the rendering of a single skin item. The effect renderer provides the active plugin with an effect context that is used to access these layers.

The plugin may assume the following restrictions:

No calls (except construction) are made to a dead plugin.
No calls (except initialization or destruction) are made to a created plugin.
Parameter setup or rendering operation is never requested from a plugin that has not been activated.
Capabilities can be queried only from an initialized or activated plugin.
After a rendering operation has been requested, no further parameter setup or capability queries are made.

Since: 2.8

Member Function Documentation

ActivateL ( MAknsRlEffectContext * )

void

ActivateL

(

MAknsRlEffectContext *

aContext

)

[pure virtual]

Activates the effect plugin to perform a single rendering operation.

This method is called once by the effect renderer before a rendering operation is requested.

Exceptions:: If effect plugin activation fails (i.e., this method leaves with an error code), the effect renderer may try to re-activate the effect later or instruct the effect pool to release it permanently (by calling Release).

Since: 2.8

Parameter	Description
aContext	Effect context. The context is guaranteed to be valid (and non-null) until Deactivate is called. No ownership is transferred.

Deactivate ( )

void

Deactivate

(

)

[pure virtual]

Deactivates the effect plugin after a rendering operation.

This method is called once by the effect renderer after a rendering operation has completed, or the operation is aborted.

Since: 2.8

GetCapabilities ( TAknsRlEffectCaps & )

void

GetCapabilities

(

TAknsRlEffectCaps &

aCaps

)

[pure virtual]

Retrieves the capabilities of the effect plugin.

The capabilities returned by this method must reflect the currently set parameters (if any). If SetParametersL is called after querying the capabilities, the effect renderer may call this method again to fetch the updated capabilities.

If this method is called for an effect instance that has been initialized but not activated, the capabilities must reflect the support for any (valid and supported) parameters. If the plugin can not determine the capabilities without knowing the parameters, it must set all the layer support fields to KAknsRlLayerNone.

If the returned capabilities indicate that no output layer is supported (only KAknsRlLayerNone is returned in output layer field), the rendering operation will not be started at all, unless additional parameters are supplied.

Since: 2.8

Parameter	Description
aCaps	Capabilities structure that the plugin must fill during the call. The initial values of the structure are undefined.

InitializeL ( )

void

InitializeL

(

)

[pure virtual]

Initializes the effect plugin instance.

This method is called once for each effect by the effect pool before calls to any other methods are made.

Exceptions:: If effect plugin initialization fails (i.e., this method leaves with an error code), the effect is considered to be non-existent.

Since: 2.8

Release ( )

void

Release

(

)

[pure virtual]

Releases the effect plugin instance.

This method is called once for each effect by the effect pool. No calls to any methods can be done after this method has been called.

Since: 2.8

Render ( const TAknsRlRenderOpParam & )

TInt

Render

(

const TAknsRlRenderOpParam &

aParam

)

[pure virtual]

Renders the effect.

The plugin implementation can perform rendering in one or more steps. Although the plugin has access to all the layers (and both RGB and alpha channels) during rendering, it should only use the content of the input layers (and channels) specified in aParam. Similarly, it should only alter the content of the specified output layer (and channels), although the context initialization for previously unused layers should be followed.

The same layer index can be specified as both the input and the output layer (if at least one input layer is supported by the plugin). The plugin must implement the effect so that any combination of layer indices is correctly rendered.

The plugin may assume that rendering operation is never called with parameters inconsistent with the plugin capabilities (as the capabilities would have been returned if GetCapabilities was called just before starting the rendering operation).

Since: 2.8

Parameter	Description
aParam	Rendering operation parameters. The structure is guaranteed to be valid for the duration of the call. If KAknsRlRenderIncomplete is returned, the same structure is given for subsequent calls.

Returns: Result of the rendering operation. This must be one of the following values:KErrNone Rendering was completed successfully.KAknsRlRenderIncomplete Rendering was not completed and Render should be called again.Any negative value indicates that an error occured. Notably, KErrArgument must be returned, if the given combination of parameters is not supported, or the parameters are insufficient. The effect renderer will deactivate the plugin.

SetParametersL ( MAknsRlParameterIterator & )

void

SetParametersL

(

MAknsRlParameterIterator &

aParameters

)

[pure virtual]

Sets the parameters for an active effect plugin.

The effect may call this method zero or more times for any active plugin before starting the rendering operation

If any parameter appears more than once in the given iterator (or in iterators given in more than one call to this method), the latest parameter value must be used. Already set parameters can not be removed, but their values can be updated.

Any parameters not supported by this plugin at all (i.e., the name of the parameter is not recognized) must be ignored silently. If parameter type or value is not supported, the plugin may leave with KErrArgument.

If a particular combination of parameters is not supported (and further calls to this method can not change the situation), the plugin may leave with KErrArgument. Otherwise, the invalid combination should be checked in Render.

SetParametersL should also leave if the parameter values can not be stored, e.g., because of an OOM condition.

Exceptions:: If parameter setup fails (i.e., this method leaves with an error code), the effect renderer will abort the rendering operation and deactivate the plugin.

Since: 2.8

Parameter	Description
aParameters	Iterator to the parameters. The iterator (and all the returned values) is guaranteed to be valid during the call to this method. No ownership is transferred, unless specified otherwise in iterator API.