1 aknsrleffect.h

     1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  ?Description

    15 *

    16 */

    17 

    18 

    19 #ifndef AKNSRLEFFECT_H

    20 #define AKNSRLEFFECT_H

    21 

    22 //  INCLUDES

    23 #include <AknsRlEffectContext.h>

    24 #include <AknsRlParameter.h>

    25 

    26 // CONSTANTS

    27 

    28 /**

    29 * Constant value indicating that @c MAknsRlEffect::Render has not completed

    30 * rendering and should be called again.

    31 *

    32 * @since 2.8

    33 */

    34 const TInt KAknsRlRenderIncomplete        = 1;

    35 

    36 // DATA TYPES

    37 

    38 /**

    39 * Effect capabilities structure.

    40 *

    41 * @since 2.8

    42 */

    43 struct TAknsRlEffectCaps

    44     {

    45     /**

    46     * Supported status of input layer A.

    47     * This must be a binary combination of @c KAknsRlLayer constants.

    48     *

    49     * @since 2.8

    50     */

    51     TInt iInputLayerASupport;

    52 

    53     /**

    54     * Supported status of input layer B.

    55     * This must be a binary combination of @c KAknsRlLayer constants.

    56     *

    57     * @since 2.8

    58     */

    59     TInt iInputLayerBSupport;

    60 

    61     /**

    62     * Supported status of output layer.

    63     * This must be a binary combination of @c KAknsRlLayer constants.

    64     *

    65     * @since 2.8

    66     */

    67     TInt iOutputLayerSupport;

    68     };

    69 

    70 /**

    71 * Rendering operation parameter structure.

    72 *

    73 * @since 2.8

    74 */

    75 struct TAknsRlRenderOpParam

    76     {

    77     /**

    78     * Status (including channel configuration) of input layer A.

    79     * This value must be one of @c KAknsRlLayer constants.

    80     *

    81     * @since 2.8

    82     */

    83     TInt iInputLayerAStatus;

    84 

    85     /**

    86     * Index of input layer A.

    87     * If iInputLayerAStatus is @c KAknsRlLayerNone, this value is

    88     * undefined.

    89     *

    90     * @since 2.8

    91     */

    92     TInt iInputLayerAIndex;

    93 

    94     /**

    95     * Status (including channel configuration) of input layer B.

    96     * This value must be one of @c KAknsRlLayer constants.

    97     *

    98     * @since 2.8

    99     */

   100     TInt iInputLayerBStatus;

   101 

   102     /**

   103     * Index of input layer B.

   104     * If iInputLayerBStatus is @c KAknsRlLayerNone, this value is

   105     * undefined.

   106     *

   107     * @since 2.8

   108     */

   109     TInt iInputLayerBIndex;

   110 

   111     /**

   112     * Status (including channel configuration) of output layer.

   113     * This value must be one of @c KAknsRlLayer constants.

   114     * The value of this field is never @c KAknsRlLayerNone.

   115     *

   116     * @since 2.8

   117     */

   118     TInt iOutputLayerStatus;

   119 

   120     /**

   121     * Index of output layer.

   122     *

   123     * @since 2.8

   124     */

   125     TInt iOutputLayerIndex;

   126     };

   127 

   128 // FORWARD DECLARATIONS

   129 

   130 // CLASS DECLARATION

   131 

   132 /**

   133 * Interface to skin effect plugin implementation.

   134 * 

   135 * States of an effect plugin are:

   136 *  - Dead: Effect plugin has not been created. Destructing the plugin

   137 *       returns the plugin to this state.

   138 *  - Created: Effect plugin has been created (by calling its default

   139 *       constructor). No dynamic data can be allocated at this state.

   140 *       Call to @c Release returns the plugin to this state.

   141 *  - Initialized: Effect plugin has been successfully initialized

   142 *       (by calling @c InitializeL). Any dynamic data (common to the

   143 *       entire lifetime of the plugin) has been constructed.

   144 *       Call to @c Deactivate returns the plugin to this state.

   145 *  - Activated: Effect plugin has been successfully activated

   146 *       for rendering (by calling @c ActivateL). This is the only

   147 *       state where parameter setup or rendering can take place.

   148 *

   149 * A plugin instance is owned by the effect pool. A plugin instance

   150 * is activated by the effect renderer to perform one rendering

   151 * operation.

   152 *

   153 * The effect renderer maintains a set of layers to store graphical

   154 * content during the rendering of a single skin item. The effect renderer

   155 * provides the active plugin with an effect context that is used to access

   156 * these layers.

   157 *

   158 * The plugin may assume the following restrictions:

   159 *  - No calls (except construction) are made to a dead plugin.

   160 *  - No calls (except initialization or destruction) are made to a 

   161 *       created plugin.

   162 *  - Parameter setup or rendering operation is never requested from

   163 *       a plugin that has not been activated.

   164 *  - Capabilities can be queried only from an initialized or activated

   165 *       plugin.

   166 *  - After a rendering operation has been requested, no further

   167 *       parameter setup or capability queries are made.

   168 *

   169 * @since 2.8

   170 */

   171 class MAknsRlEffect

   172     {

   173     public: // Constructors and destructor

   174 

   175         // This interface is not used to control ownership.

   176 

   177     public: // New functions - Lifetime handling

   178 

   179         /**

   180         * Initializes the effect plugin instance.

   181         *

   182         * This method is called once for each effect by the effect pool before

   183         * calls to any other methods are made.

   184         *

   185         * @par Exceptions:

   186         * If effect plugin initialization fails (i.e., this method leaves

   187         * with an error code), the effect is considered to be non-existent.

   188         * 

   189         * @since 2.8

   190         */

   191         virtual void InitializeL() =0;

   192 

   193         /**

   194         * Releases the effect plugin instance.

   195         *

   196         * This method is called once for each effect by the effect pool. No

   197         * calls to any methods can be done after this method has been called.

   198         *

   199         * @since 2.8

   200         */

   201         virtual void Release() =0;

   202 

   203         /**

   204         * Activates the effect plugin to perform a single rendering operation.

   205         *

   206         * This method is called once by the effect renderer before a rendering

   207         * operation is requested.

   208         *

   209         * @param aContext Effect context. The context is guaranteed to be valid

   210         *   (and non-null) until @c Deactivate is called. No ownership is

   211         *   transferred.

   212         *

   213         * @par Exceptions:

   214         * If effect plugin activation fails (i.e., this method leaves with an 

   215         * error code), the effect renderer may try to re-activate the effect

   216         * later or instruct the effect pool to release it permanently 

   217         * (by calling @c Release).

   218         *

   219         * @since 2.8

   220         */

   221         virtual void ActivateL( MAknsRlEffectContext* aContext ) =0;

   222 

   223         /**

   224         * Deactivates the effect plugin after a rendering operation.

   225         *

   226         * This method is called once by the effect renderer after a rendering

   227         * operation has completed, or the operation is aborted.

   228         *

   229         * @since 2.8

   230         */

   231         virtual void Deactivate() =0;

   232 

   233     public: // New functions - Rendering setup

   234 

   235         /**

   236         * Sets the parameters for an active effect plugin.

   237         *

   238         * The effect may call this method zero or more times for any

   239         * active plugin before starting the rendering operation

   240         *

   241         * If any parameter appears more than once in the given iterator

   242         * (or in iterators given in more than one call to this method),

   243         * the latest parameter value must be used. Already set parameters

   244         * can not be removed, but their values can be updated.

   245         *

   246         * Any parameters not supported by this plugin at all (i.e., the

   247         * name of the parameter is not recognized) must be ignored silently.

   248         * If parameter type or value is not supported, the plugin may 

   249         * leave with @c KErrArgument.

   250         *

   251         * If a particular combination of parameters is not supported

   252         * (and further calls to this method can not change the situation), 

   253         * the plugin may leave with @c KErrArgument. Otherwise, the invalid

   254         * combination should be checked in @c Render.

   255         *

   256         * @c SetParametersL should also leave if the parameter values

   257         * can not be stored, e.g., because of an OOM condition.

   258         *

   259         * @param aParameters Iterator to the parameters. The iterator (and all

   260         *   the returned values) is guaranteed to be valid during the call

   261         *   to this method. No ownership is transferred, unless specified 

   262         *   otherwise in iterator API.

   263         *

   264         * @par Exceptions:

   265         * If parameter setup fails (i.e., this method leaves with an error 

   266         * code), the effect renderer will abort the rendering operation and 

   267         * deactivate the plugin.

   268         *

   269         * @since 2.8

   270         */

   271         virtual void SetParametersL(

   272             MAknsRlParameterIterator& aParameters ) =0;

   273 

   274     public: // New functions - Capability retrieval

   275 

   276         /**

   277         * Retrieves the capabilities of the effect plugin.

   278         *

   279         * The capabilities returned by this method must reflect the currently

   280         * set parameters (if any). If @c SetParametersL is called after 

   281         * querying the capabilities, the effect renderer may call this method

   282         * again to fetch the updated capabilities.

   283         *

   284         * If this method is called for an effect instance that has been

   285         * initialized but not activated, the capabilities must reflect the

   286         * support for any (valid and supported) parameters. If the plugin

   287         * can not determine the capabilities without knowing the parameters,

   288         * it must set all the layer support fields to 

   289         * @c KAknsRlLayerNone.

   290         *

   291         * If the returned capabilities indicate that no output layer is

   292         * supported (only @c KAknsRlLayerNone is returned in output layer

   293         * field), the rendering operation will not be started at all,

   294         * unless additional parameters are supplied.

   295         *

   296         * @param aCaps Capabilities structure that the plugin must fill

   297         *   during the call. The initial values of the structure are

   298         *   undefined.

   299         *

   300         * @since 2.8

   301         */

   302         virtual void GetCapabilities( TAknsRlEffectCaps& aCaps ) =0;

   303 

   304     public: // New functions - Rendering

   305 

   306         /**

   307         * Renders the effect.

   308         *

   309         * The plugin implementation can perform rendering in one or more

   310         * steps. Although the plugin has access to all the layers

   311         * (and both RGB and alpha channels) during rendering, it should

   312         * only use the content of the input layers (and channels) 

   313         * specified in @c aParam. Similarly, it should only alter the

   314         * content of the specified output layer (and channels), although

   315         * the context initialization for previously unused layers should

   316         * be followed.

   317         *

   318         * The same layer index can be specified as both the input and

   319         * the output layer (if at least one input layer is supported by the 

   320         * plugin). The plugin must implement the effect so that any combination

   321         * of layer indices is correctly rendered.

   322         *

   323         * The plugin may assume that rendering operation is never called

   324         * with parameters inconsistent with the plugin capabilities (as

   325         * the capabilities would have been returned if @c GetCapabilities was

   326         * called just before starting the rendering operation).

   327         *

   328         * @param aParam Rendering operation parameters. The structure

   329         *   is guaranteed to be valid for the duration of the call.

   330         *   If @c KAknsRlRenderIncomplete is returned, the same structure

   331         *   is given for subsequent calls.

   332         *

   333         * @return Result of the rendering operation. This must be one of the

   334         *   following values:

   335         *   - @c KErrNone Rendering was completed successfully.

   336         *   - @c KAknsRlRenderIncomplete Rendering was not completed and

   337         *       @c Render should be called again.

   338         *   - Any negative value indicates that an error occured. Notably,

   339         *       @c KErrArgument must be returned, if the given combination

   340         *       of parameters is not supported, or the parameters are

   341         *       insufficient. The effect renderer will deactivate the plugin.

   342         *

   343         * @since 2.8

   344         */

   345         virtual TInt Render( const TAknsRlRenderOpParam& aParam ) =0;

   346     };

   347 

   348 #endif // AKNSRLEFFECT_H

   349             

   350 // End of File