1 /*

     2 * Copyright (c) 2006-2007 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Definition of CHuiTextureProcessor. CHuiTextureProcessor is 

    15 *                the abstract base class for texture processors.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __HUITEXTUREPROCESSOR_H__

    22 #define __HUITEXTUREPROCESSOR_H__

    23 

    24 

    25 #include <e32base.h>

    26 #include <uiacceltk/HuiTextureHandle.h>

    27 

    28 

    29 /* Forward declarations. */

    30 class CHuiEnv;

    31 

    32 

    33 /**

    34  * CHuiTextureProcessor is a collection of texture filters. Each filter 

    35  * takes a texture as input, processes it, and produces a new texture as a 

    36  * result. Examples of processing filters are blurring and shadow generation. 

    37  * Concrete implementations of this class are rendering plugin specific.

    38  * CHuiTextureProcessor is the public, user-friendly way of filtering 

    39  * textures, because each filtering operation can be applied with a single

    40  * function call.

    41  *

    42  * @todo  Create an abstract CHuiTextureFilter class to represent a filter

    43  *        operation. Each filter could then be configured with an arbitrary

    44  *        number of parameters, and then applied on a texture. This would

    45  *        allow filters to have persistent state information.

    46  */

    47 class CHuiTextureProcessor : public CBase

    48     {

    49 public:

    50 

    51     /* Types. */

    52 

    53     /** @beginAPI */

    54 

    55     /** Flags for blur filtering. */

    56     enum TBlurFlags

    57         {

    58         /** Default blurring settings. */

    59         EBlurFlagDefault = 0,

    60         

    61         /** Include an alpha channel in the result. */

    62         EBlurFlagAlpha = 1,

    63         

    64         /** Retain extra space for edges so that the blurred edges that will

    65             always remain within the bounds of the resulting texture. Note

    66             that when the blurred texture is drawn, it has to be expanded 

    67             so that it will match the original images content. */

    68         EBlurFlagExpandEdges = 2,

    69         

    70         /** Replace source color RGB with white. Note that this flag is 

    71             mutually exclusive with flag EBlurFlagBlack. If both are defined

    72             then this flag overrides the EBlurFlagBlack. */

    73         EBlurFlagWhite = 4,

    74         

    75         /** Replace source color RGB with black. Note that this flag is 

    76             mutually exclusive with flag EBlurFlagWhite. If both are defined

    77             then this flag overridden by EBlurFlagWhite. */

    78         EBlurFlagBlack = 8,

    79         

    80         /** High quality blur. The blurring process is done twice, and the 

    81             results are averaged. */

    82         EBlurFlagHighQuality = 16,

    83         };

    84 

    85     /** @endAPI */

    86 

    87 

    88     /* Destructor. */

    89 

    90     /**

    91      * Destructor.

    92      */

    93     IMPORT_C virtual ~CHuiTextureProcessor();

    94     

    95 

    96     /* Methods. */

    97 

    98     /**

    99      * Returns the environment of the texture processor.

   100      */

   101     IMPORT_C CHuiEnv& Env();

   102 

   103 

   104     /** @beginAPI */

   105 

   106     /**

   107      * Blurs a texture. The dimensions of the resulting image are chosen

   108      * automatically. 

   109      *

   110      * Returns a handle to a new texture which contains

   111      * a blurred version of the texture. Ownership of the new texture is

   112      * transferred to the caller, which means it is responsible for either

   113      * creating a CHuiTexture out of the handle, or calling 

   114      * THuiTextureHandle::Release() when the generated texture is no longer

   115      * needed.

   116      *

   117      * Note that the algorithm used for blurring favors speed over accuracy.

   118      * This means that when hardware acceleration is available, the blurring

   119      * can be redone for each frame. However, the quality of the blurring 

   120      * may not be optimal. For example, color range reduction and pixel 

   121      * artifacts may be visible.

   122      *

   123      * @param aSrc  Texture to be blurred (single segment). Not modified.

   124      * @param aDest  New blurred texture. Ownership is transferred to the caller.

   125      *               Allowed to be the same as aSrc.

   126      * @param aFilterSize  Size of the blurring filter. 3 = 3x3 filter, 4 = 4x4 filter.

   127      * @param aFlags  Flags that modify the filter's parameters. @see TBlurFlags

   128      */    

   129     IMPORT_C virtual void BlurL(const THuiTextureHandle& aSrc,

   130                        THuiTextureHandle& aDest,

   131                        TInt aFilterSize = 3, TInt aFlags = 0) = 0;

   132 

   133     /**

   134      * Blurs a texture. The dimensions of the resulting image are as close to

   135      * aPreferredSize as possible, depending on the limitations of the 

   136      * implementation. 

   137      * 

   138      * See comments avobe.

   139      *

   140      * @param aSrc  Texture to be blurred (single segment). Not modified.

   141      * @param aDest  New blurred texture. Ownership is transferred to the caller.

   142      *               Allowed to be the same as aSrc.

   143      * @param aPreferredSize  Preferred size of the result.

   144      * @param aFilterSize  Size of the blurring filter. 3 = 3x3 filter, 4 = 4x4 filter.

   145      * @param aFlags  Flags that modify the filter's parameters. @see TBlurFlags

   146      */

   147     IMPORT_C virtual void BlurL(const THuiTextureHandle& aSrc, 

   148                        THuiTextureHandle& aDest,

   149                        const TSize& aPreferredSize,

   150                        TInt aFilterSize = 3, TInt aFlag = 0) = 0;

   151 

   152     

   153     /**

   154      * Blurs a texture. The dimensions of the resulting image are chosen

   155      * automatically. 

   156      *

   157      * See comments avobe.

   158      *

   159      * @param aSrc  Texture to be blurred (multi segment). Not modified.

   160      * @param aDest  New blurred texture. Ownership is transferred to the caller.

   161      *               Allowed to be the same as aSrc.

   162      * @param aFilterSize  Size of the blurring filter. 3 = 3x3 filter, 4 = 4x4 filter.

   163      * @param aFlags  Flags that modify the filter's parameters. @see TBlurFlags

   164      */ 

   165     IMPORT_C virtual void BlurSegmentedL(const MHuiSegmentedTexture& aSrc,

   166                        THuiTextureHandle& aDest,

   167                        TInt aFilterSize = 3, TInt aFlags = 0) = 0;

   168     

   169     /**

   170      * Blurs a texture. The dimensions of the resulting image are as close to

   171      * aPreferredSize as possible, depending on the limitations of the 

   172      * implementation. 

   173      *

   174      * See comments avobe.

   175      *

   176      *

   177      * @param aSrc  Texture to be blurred (multi segment). Not modified.

   178      * @param aDest  New blurred texture. Ownership is transferred to the caller.

   179      *               Allowed to be the same as aSrc.

   180      * @param aPreferredSize  Preferred size of the result.

   181      * @param aFilterSize  Size of the blurring filter. 3 = 3x3 filter, 4 = 4x4 filter.

   182      * @param aFlags  Flags that modify the filter's parameters. @see TBlurFlags

   183      */                

   184     IMPORT_C virtual void BlurSegmentedL(const MHuiSegmentedTexture& aSrc, 

   185                        THuiTextureHandle& aDest,

   186                        const TSize& aPreferredSize,

   187                        TInt aFilterSize = 3, TInt aFlag = 0) = 0;

   188 

   189     /** @endAPI */

   190     

   191     

   192     IMPORT_C virtual void Release();

   193     

   194     IMPORT_C virtual void RestoreL();

   195 

   196 

   197 protected:

   198 

   199     /* Constructors. */

   200 

   201     /**

   202      * Constructor.

   203      */

   204     IMPORT_C CHuiTextureProcessor(CHuiEnv& aEnv);

   205 

   206 

   207 protected: // New methods

   208     

   209     /**

   210      * Provides expandability, helps keeping the binary compatibility. Since virtual

   211      * table is now exported and this class is dll derivable and the implementation

   212      * is more difficult to change, hence this method, which can provide additional

   213      * extension APIs.

   214      * 

   215      * @param aExtensionUid     UID, which is being used for recognizing the extension

   216      * @param aExtensionParams  Return pointer to the extension API, once recognized from the extension uid

   217      */

   218     IMPORT_C virtual void TextureProcessorExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   219     

   220 private:

   221 

   222     /** Environment. */

   223     CHuiEnv& iEnv;

   224 

   225     /** Spare member to help keeping binary compatibility, since

   226         HuiTextureProcessor is now dll derivable **/

   227     TInt iSpare;

   228     };

   229 

   230 #endif  // __HUITEXTUREPROCESSOR_H__