--- /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 <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