/*

 * 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