diff -r 000000000000 -r 05e9090e2422 uiresources_pub/skins_api/inc/AknsRlEffect.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiresources_pub/skins_api/inc/AknsRlEffect.h Thu Dec 17 09:14:12 2009 +0200 @@ -0,0 +1,350 @@ +/* +* 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 +#include + +// 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