MAknsRlEffect Class Reference

Public Member Functions

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

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.

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.

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.

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.

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.

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.