/*

* Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  ?Description

*

*/

#ifndef AKNSRLEFFECT_H

#define AKNSRLEFFECT_H

//  INCLUDES

#include <AknsRlEffectContext.h>

#include <AknsRlParameter.h>

// CONSTANTS

/**

* Constant value indicating that @c MAknsRlEffect::Render has not completed

* rendering and should be called again.

*

* @since 2.8

*/

const TInt KAknsRlRenderIncomplete        = 1;

// DATA TYPES

/**

* Effect capabilities structure.

*

* @since 2.8

*/

struct TAknsRlEffectCaps

    {

    /**

    * Supported status of input layer A.

    * This must be a binary combination of @c KAknsRlLayer constants.

    *

    * @since 2.8

    */

    TInt iInputLayerASupport;

    /**

    * Supported status of input layer B.

    * This must be a binary combination of @c KAknsRlLayer constants.

    *

    * @since 2.8

    */

    TInt iInputLayerBSupport;

    /**

    * Supported status of output layer.

    * This must be a binary combination of @c KAknsRlLayer constants.

    *

    * @since 2.8

    */

    TInt iOutputLayerSupport;

    };

/**

* Rendering operation parameter structure.

*

* @since 2.8

*/

struct TAknsRlRenderOpParam

    {

    /**

    * Status (including channel configuration) of input layer A.

    * This value must be one of @c KAknsRlLayer constants.

    *

    * @since 2.8

    */

    TInt iInputLayerAStatus;

    /**

    * Index of input layer A.

    * If iInputLayerAStatus is @c KAknsRlLayerNone, this value is

    * undefined.

    *

    * @since 2.8

    */

    TInt iInputLayerAIndex;

    /**

    * Status (including channel configuration) of input layer B.

    * This value must be one of @c KAknsRlLayer constants.

    *

    * @since 2.8

    */

    TInt iInputLayerBStatus;

    /**

    * Index of input layer B.

    * If iInputLayerBStatus is @c KAknsRlLayerNone, this value is

    * undefined.

    *

    * @since 2.8

    */

    TInt iInputLayerBIndex;

    /**

    * Status (including channel configuration) of output layer.

    * This value must be one of @c KAknsRlLayer constants.

    * The value of this field is never @c KAknsRlLayerNone.

    *

    * @since 2.8

    */

    TInt iOutputLayerStatus;

    /**

    * Index of output layer.

    *

    * @since 2.8

    */

    TInt iOutputLayerIndex;

    };

// FORWARD DECLARATIONS

// CLASS DECLARATION

/**

* 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 @c Release returns the plugin to this state.

*  - Initialized: Effect plugin has been successfully initialized

*       (by calling @c InitializeL). Any dynamic data (common to the

*       entire lifetime of the plugin) has been constructed.

*       Call to @c Deactivate returns the plugin to this state.

*  - Activated: Effect plugin has been successfully activated

*       for rendering (by calling @c 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

*/

class MAknsRlEffect

    {

    public: // Constructors and destructor

        // This interface is not used to control ownership.

    public: // New functions - Lifetime handling

        /**

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

        *

        * @par 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

        */

        virtual void InitializeL() =0;

        /**

        * 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

        */

        virtual void Release() =0;

        /**

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

        *

        * @param aContext Effect context. The context is guaranteed to be valid

        *   (and non-null) until @c Deactivate is called. No ownership is

        *   transferred.

        *

        * @par 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 @c Release).

        *

        * @since 2.8

        */

        virtual void ActivateL( MAknsRlEffectContext* aContext ) =0;

        /**

        * 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

        */

        virtual void Deactivate() =0;

    public: // New functions - Rendering setup

        /**

        * 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 @c 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 @c KErrArgument. Otherwise, the invalid

        * combination should be checked in @c Render.

        *

        * @c SetParametersL should also leave if the parameter values

        * can not be stored, e.g., because of an OOM condition.

        *

        * @param 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.

        *

        * @par 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

        */

        virtual void SetParametersL(

            MAknsRlParameterIterator& aParameters ) =0;

    public: // New functions - Capability retrieval

        /**

        * Retrieves the capabilities of the effect plugin.

        *

        * The capabilities returned by this method must reflect the currently

        * set parameters (if any). If @c 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 

        * @c KAknsRlLayerNone.

        *

        * If the returned capabilities indicate that no output layer is

        * supported (only @c KAknsRlLayerNone is returned in output layer

        * field), the rendering operation will not be started at all,

        * unless additional parameters are supplied.

        *

        * @param aCaps Capabilities structure that the plugin must fill

        *   during the call. The initial values of the structure are

        *   undefined.

        *

        * @since 2.8

        */

        virtual void GetCapabilities( TAknsRlEffectCaps& aCaps ) =0;

    public: // New functions - Rendering

        /**

        * 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 @c 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 @c GetCapabilities was

        * called just before starting the rendering operation).

        *

        * @param aParam Rendering operation parameters. The structure

        *   is guaranteed to be valid for the duration of the call.

        *   If @c KAknsRlRenderIncomplete is returned, the same structure

        *   is given for subsequent calls.

        *

        * @return Result of the rendering operation. This must be one of the

        *   following values:

        *   - @c KErrNone Rendering was completed successfully.

        *   - @c KAknsRlRenderIncomplete Rendering was not completed and

        *       @c Render should be called again.

        *   - Any negative value indicates that an error occured. Notably,

        *       @c 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.

        *

        * @since 2.8

        */

        virtual TInt Render( const TAknsRlRenderOpParam& aParam ) =0;

    };

#endif // AKNSRLEFFECT_H

// End of File