williamr@2: /* williamr@2: * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: ?Description williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef AKNSRLEFFECT_H williamr@2: #define AKNSRLEFFECT_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: /** williamr@2: * Constant value indicating that @c MAknsRlEffect::Render has not completed williamr@2: * rendering and should be called again. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: const TInt KAknsRlRenderIncomplete = 1; williamr@2: williamr@2: // DATA TYPES williamr@2: williamr@2: /** williamr@2: * Effect capabilities structure. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: struct TAknsRlEffectCaps williamr@2: { williamr@2: /** williamr@2: * Supported status of input layer A. williamr@2: * This must be a binary combination of @c KAknsRlLayer constants. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerASupport; williamr@2: williamr@2: /** williamr@2: * Supported status of input layer B. williamr@2: * This must be a binary combination of @c KAknsRlLayer constants. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerBSupport; williamr@2: williamr@2: /** williamr@2: * Supported status of output layer. williamr@2: * This must be a binary combination of @c KAknsRlLayer constants. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iOutputLayerSupport; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Rendering operation parameter structure. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: struct TAknsRlRenderOpParam williamr@2: { williamr@2: /** williamr@2: * Status (including channel configuration) of input layer A. williamr@2: * This value must be one of @c KAknsRlLayer constants. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerAStatus; williamr@2: williamr@2: /** williamr@2: * Index of input layer A. williamr@2: * If iInputLayerAStatus is @c KAknsRlLayerNone, this value is williamr@2: * undefined. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerAIndex; williamr@2: williamr@2: /** williamr@2: * Status (including channel configuration) of input layer B. williamr@2: * This value must be one of @c KAknsRlLayer constants. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerBStatus; williamr@2: williamr@2: /** williamr@2: * Index of input layer B. williamr@2: * If iInputLayerBStatus is @c KAknsRlLayerNone, this value is williamr@2: * undefined. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iInputLayerBIndex; williamr@2: williamr@2: /** williamr@2: * Status (including channel configuration) of output layer. williamr@2: * This value must be one of @c KAknsRlLayer constants. williamr@2: * The value of this field is never @c KAknsRlLayerNone. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iOutputLayerStatus; williamr@2: williamr@2: /** williamr@2: * Index of output layer. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: TInt iOutputLayerIndex; williamr@2: }; williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * Interface to skin effect plugin implementation. williamr@2: * williamr@2: * States of an effect plugin are: williamr@2: * - Dead: Effect plugin has not been created. Destructing the plugin williamr@2: * returns the plugin to this state. williamr@2: * - Created: Effect plugin has been created (by calling its default williamr@2: * constructor). No dynamic data can be allocated at this state. williamr@2: * Call to @c Release returns the plugin to this state. williamr@2: * - Initialized: Effect plugin has been successfully initialized williamr@2: * (by calling @c InitializeL). Any dynamic data (common to the williamr@2: * entire lifetime of the plugin) has been constructed. williamr@2: * Call to @c Deactivate returns the plugin to this state. williamr@2: * - Activated: Effect plugin has been successfully activated williamr@2: * for rendering (by calling @c ActivateL). This is the only williamr@2: * state where parameter setup or rendering can take place. williamr@2: * williamr@2: * A plugin instance is owned by the effect pool. A plugin instance williamr@2: * is activated by the effect renderer to perform one rendering williamr@2: * operation. williamr@2: * williamr@2: * The effect renderer maintains a set of layers to store graphical williamr@2: * content during the rendering of a single skin item. The effect renderer williamr@2: * provides the active plugin with an effect context that is used to access williamr@2: * these layers. williamr@2: * williamr@2: * The plugin may assume the following restrictions: williamr@2: * - No calls (except construction) are made to a dead plugin. williamr@2: * - No calls (except initialization or destruction) are made to a williamr@2: * created plugin. williamr@2: * - Parameter setup or rendering operation is never requested from williamr@2: * a plugin that has not been activated. williamr@2: * - Capabilities can be queried only from an initialized or activated williamr@2: * plugin. williamr@2: * - After a rendering operation has been requested, no further williamr@2: * parameter setup or capability queries are made. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: class MAknsRlEffect williamr@2: { williamr@2: public: // Constructors and destructor williamr@2: williamr@2: // This interface is not used to control ownership. williamr@2: williamr@2: public: // New functions - Lifetime handling williamr@2: williamr@2: /** williamr@2: * Initializes the effect plugin instance. williamr@2: * williamr@2: * This method is called once for each effect by the effect pool before williamr@2: * calls to any other methods are made. williamr@2: * williamr@2: * @par Exceptions: williamr@2: * If effect plugin initialization fails (i.e., this method leaves williamr@2: * with an error code), the effect is considered to be non-existent. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void InitializeL() =0; williamr@2: williamr@2: /** williamr@2: * Releases the effect plugin instance. williamr@2: * williamr@2: * This method is called once for each effect by the effect pool. No williamr@2: * calls to any methods can be done after this method has been called. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void Release() =0; williamr@2: williamr@2: /** williamr@2: * Activates the effect plugin to perform a single rendering operation. williamr@2: * williamr@2: * This method is called once by the effect renderer before a rendering williamr@2: * operation is requested. williamr@2: * williamr@2: * @param aContext Effect context. The context is guaranteed to be valid williamr@2: * (and non-null) until @c Deactivate is called. No ownership is williamr@2: * transferred. williamr@2: * williamr@2: * @par Exceptions: williamr@2: * If effect plugin activation fails (i.e., this method leaves with an williamr@2: * error code), the effect renderer may try to re-activate the effect williamr@2: * later or instruct the effect pool to release it permanently williamr@2: * (by calling @c Release). williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void ActivateL( MAknsRlEffectContext* aContext ) =0; williamr@2: williamr@2: /** williamr@2: * Deactivates the effect plugin after a rendering operation. williamr@2: * williamr@2: * This method is called once by the effect renderer after a rendering williamr@2: * operation has completed, or the operation is aborted. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void Deactivate() =0; williamr@2: williamr@2: public: // New functions - Rendering setup williamr@2: williamr@2: /** williamr@2: * Sets the parameters for an active effect plugin. williamr@2: * williamr@2: * The effect may call this method zero or more times for any williamr@2: * active plugin before starting the rendering operation williamr@2: * williamr@2: * If any parameter appears more than once in the given iterator williamr@2: * (or in iterators given in more than one call to this method), williamr@2: * the latest parameter value must be used. Already set parameters williamr@2: * can not be removed, but their values can be updated. williamr@2: * williamr@2: * Any parameters not supported by this plugin at all (i.e., the williamr@2: * name of the parameter is not recognized) must be ignored silently. williamr@2: * If parameter type or value is not supported, the plugin may williamr@2: * leave with @c KErrArgument. williamr@2: * williamr@2: * If a particular combination of parameters is not supported williamr@2: * (and further calls to this method can not change the situation), williamr@2: * the plugin may leave with @c KErrArgument. Otherwise, the invalid williamr@2: * combination should be checked in @c Render. williamr@2: * williamr@2: * @c SetParametersL should also leave if the parameter values williamr@2: * can not be stored, e.g., because of an OOM condition. williamr@2: * williamr@2: * @param aParameters Iterator to the parameters. The iterator (and all williamr@2: * the returned values) is guaranteed to be valid during the call williamr@2: * to this method. No ownership is transferred, unless specified williamr@2: * otherwise in iterator API. williamr@2: * williamr@2: * @par Exceptions: williamr@2: * If parameter setup fails (i.e., this method leaves with an error williamr@2: * code), the effect renderer will abort the rendering operation and williamr@2: * deactivate the plugin. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void SetParametersL( williamr@2: MAknsRlParameterIterator& aParameters ) =0; williamr@2: williamr@2: public: // New functions - Capability retrieval williamr@2: williamr@2: /** williamr@2: * Retrieves the capabilities of the effect plugin. williamr@2: * williamr@2: * The capabilities returned by this method must reflect the currently williamr@2: * set parameters (if any). If @c SetParametersL is called after williamr@2: * querying the capabilities, the effect renderer may call this method williamr@2: * again to fetch the updated capabilities. williamr@2: * williamr@2: * If this method is called for an effect instance that has been williamr@2: * initialized but not activated, the capabilities must reflect the williamr@2: * support for any (valid and supported) parameters. If the plugin williamr@2: * can not determine the capabilities without knowing the parameters, williamr@2: * it must set all the layer support fields to williamr@2: * @c KAknsRlLayerNone. williamr@2: * williamr@2: * If the returned capabilities indicate that no output layer is williamr@2: * supported (only @c KAknsRlLayerNone is returned in output layer williamr@2: * field), the rendering operation will not be started at all, williamr@2: * unless additional parameters are supplied. williamr@2: * williamr@2: * @param aCaps Capabilities structure that the plugin must fill williamr@2: * during the call. The initial values of the structure are williamr@2: * undefined. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual void GetCapabilities( TAknsRlEffectCaps& aCaps ) =0; williamr@2: williamr@2: public: // New functions - Rendering williamr@2: williamr@2: /** williamr@2: * Renders the effect. williamr@2: * williamr@2: * The plugin implementation can perform rendering in one or more williamr@2: * steps. Although the plugin has access to all the layers williamr@2: * (and both RGB and alpha channels) during rendering, it should williamr@2: * only use the content of the input layers (and channels) williamr@2: * specified in @c aParam. Similarly, it should only alter the williamr@2: * content of the specified output layer (and channels), although williamr@2: * the context initialization for previously unused layers should williamr@2: * be followed. williamr@2: * williamr@2: * The same layer index can be specified as both the input and williamr@2: * the output layer (if at least one input layer is supported by the williamr@2: * plugin). The plugin must implement the effect so that any combination williamr@2: * of layer indices is correctly rendered. williamr@2: * williamr@2: * The plugin may assume that rendering operation is never called williamr@2: * with parameters inconsistent with the plugin capabilities (as williamr@2: * the capabilities would have been returned if @c GetCapabilities was williamr@2: * called just before starting the rendering operation). williamr@2: * williamr@2: * @param aParam Rendering operation parameters. The structure williamr@2: * is guaranteed to be valid for the duration of the call. williamr@2: * If @c KAknsRlRenderIncomplete is returned, the same structure williamr@2: * is given for subsequent calls. williamr@2: * williamr@2: * @return Result of the rendering operation. This must be one of the williamr@2: * following values: williamr@2: * - @c KErrNone Rendering was completed successfully. williamr@2: * - @c KAknsRlRenderIncomplete Rendering was not completed and williamr@2: * @c Render should be called again. williamr@2: * - Any negative value indicates that an error occured. Notably, williamr@2: * @c KErrArgument must be returned, if the given combination williamr@2: * of parameters is not supported, or the parameters are williamr@2: * insufficient. The effect renderer will deactivate the plugin. williamr@2: * williamr@2: * @since 2.8 williamr@2: */ williamr@2: virtual TInt Render( const TAknsRlRenderOpParam& aParam ) =0; williamr@2: }; williamr@2: williamr@2: #endif // AKNSRLEFFECT_H williamr@2: williamr@2: // End of File