MAknsRlEffect Class Reference

API published in: S60 2nd Ed FP 3

Link against: aknskins.lib aknskinsrv.lib aknswallpaperutils.lib

Capability Information

Required Capabilities

None


#include <aknsrleffect.h>

Detailed Description

Interface to skin effect plugin implementation.

States of an effect plugin are:

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:


Public Member Functions

virtual void  InitializeL ()=0
  Initializes the effect plugin instance.
virtual void  Release ()=0
  Releases the effect plugin instance.
virtual void  ActivateL (MAknsRlEffectContext *aContext)=0
  Activates the effect plugin to perform a single rendering operation.
virtual void  Deactivate ()=0
  Deactivates the effect plugin after a rendering operation.
virtual void  SetParametersL (MAknsRlParameterIterator &aParameters)=0
  Sets the parameters for an active effect plugin.
virtual void  GetCapabilities (TAknsRlEffectCaps &aCaps)=0
  Retrieves the capabilities of the effect plugin.
virtual TInt  Render (const TAknsRlRenderOpParam &aParam)=0
  Renders the effect.

Member Function Documentation

virtual void MAknsRlEffect::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.

Parameters:
aContext  Effect context. The context is guaranteed to be valid (and non-null) until Deactivate is called. No ownership is transferred.
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).
virtual void MAknsRlEffect::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.

virtual void MAknsRlEffect::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.

Parameters:
aCaps  Capabilities structure that the plugin must fill during the call. The initial values of the structure are undefined.
virtual void MAknsRlEffect::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.
virtual void MAknsRlEffect::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.

virtual TInt MAknsRlEffect::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).

Parameters:
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.
virtual void MAknsRlEffect::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.

Parameters:
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.
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.

The documentation for this class was generated from the following file:

Copyright © Nokia Corporation 2001-2008
Back to top