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@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 <AknsRlEffectContext.h>
williamr@2: #include <AknsRlParameter.h>
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