Symbian^3 Application Developer Library >

MAknsRlEffect Class Reference

class MAknsRlEffect

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
Public Member Functions
void ActivateL ( MAknsRlEffectContext *)
void Deactivate ()
void GetCapabilities ( TAknsRlEffectCaps &)
void InitializeL ()
void Release ()
TInt Render (const TAknsRlRenderOpParam &)
void SetParametersL ( MAknsRlParameterIterator &)

Member Functions 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

Parameters

MAknsRlEffectContext * 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

Parameters

TAknsRlEffectCaps & 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

Parameters

const TAknsRlRenderOpParam & 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.

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

Parameters

MAknsRlParameterIterator & 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.

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.