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 *

    11 * Nokia Corporation - initial contribution.

    12 * Contributors:

    13 *

    14 * Description:   Defines CHuiTextureManager class for texture objects loading 

    15 *                and management.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __HUITEXTUREMANAGER_H__

    22 #define __HUITEXTUREMANAGER_H__

    23 

    24 

    25 #include <e32base.h>

    26 #include <gdi.h>

    27 #include <imageconversion.h>

    28 

    29 #include <uiacceltk/HuiObserverArray.h>

    30 #include <uiacceltk/HuiTimeObserver.h>

    31 #include <uiacceltk/HuiTexture.h>

    32 #include <uiacceltk/HuiBitmapProvider.h>

    33 

    34 

    35 /* Forward declarations */

    36 class CHuiEnv;

    37 class CHuiTextureManager;

    38 class CHuiTextureProcessor;

    39 class CHuiTextureAnimationState;

    40 

    41 /**

    42  * Provides callback methods for getting notifications of texture manager state

    43  * changes. An observer of a CHuiTextureManager.

    44  *

    45  * The class willing to receive these events must implement the methods

    46  * of this interface, and then register itself to the obsevers list of

    47  * the texture manager.

    48  *

    49  * @see CHuiTextureManager

    50  */

    51 class MHuiTextureManagerStateChangedObserver

    52     {

    53 public:

    54     /**

    55      * Called to notify the observer that the state of the texture manager

    56      * has changed. This is called when the state changes between Idle and

    57      * Loading.

    58      *

    59      * @param aManager  Texture manager.

    60      */

    61     virtual void TextureManagerStateChanged(const CHuiTextureManager& aManager) = 0;

    62 

    63     };

    64 

    65 /**

    66  * Provides callback methods for getting notifications when texture manager

    67  * finishes asynchronous texture loads. An observer of a CHuiTextureManager.

    68  *

    69  * The class willing to receive these events must implement the methods

    70  * of this interface, and then register itself to the obsevers list of

    71  * the texture manager.

    72  *

    73  * @see CHuiTextureManager

    74  */

    75 class MHuiTextureLoadingCompletedObserver

    76     {

    77 public:

    78     /**

    79      * Called to notify the observer that loading of a texture has

    80      * been completed.

    81      * @param aTexture Reference to the texture that has been loaded.

    82      * @param aTextureId Id of the texture in the texture manager. Can be used

    83      * to identify the loaded texture, provided that an id was assigned to the

    84      * texture.

    85      * @param aErrorCode KErrNone if the load was successful, otherwise one of

    86      * the system-wide error codes indicating reason why the texture loading

    87      * failed.

    88      * @note One should not commence loading of a new texture in this callback method.

    89      */

    90     virtual void TextureLoadingCompleted(CHuiTexture& aTexture,

    91                                          TInt aTextureId,

    92                                          TInt aErrorCode) = 0;

    93 

    94     };

    95 

    96 

    97 /**

    98  * Provides callback methods for getting notifications when texture manager

    99  * notices a texture which preferrred size is changed.

   100  *

   101  * The class willing to receive these events must implement the methods

   102  * of this interface, and then register itself to the obsevers list of

   103  * the texture manager.

   104  *

   105  * @see CHuiTextureManager

   106  */

   107 class MHuiTextureAutoSizeObserver

   108     {

   109 public:

   110     /**

   111      * Called to notify the observer that the preferred size of a texture

   112      * has beem changed.

   113      *

   114      * @param aTexture  Texture which preferred size has changed.

   115      * @param aTextureId Id of the changed texture.

   116      * @param aSize New preferred size for texture.

   117      * @return ETrue if observer accepts new size, EFalse if it does not accept or 

   118      * doesn't care. 

   119      */

   120     virtual TBool PreferredSizeChanged(const CHuiTexture& aTexture, TInt aTextureId, const THuiRealSize& aSize) = 0;    

   121     

   122     /**

   123      * Called to notify the observer that all changed preferred sizes of textures are

   124      * reported (for this frame).

   125      */

   126     virtual void PreferredSizeReportCompleted() = 0;

   127     };

   128 

   129 /**

   130  * CHuiTextureManager is responsible for managing the texture objects used by

   131  * the application. It provides asynchronous loading of image data into

   132  * CHuiTexture instances. The texture manager also manages font textures,

   133  * which can be used for compositing text in text meshes.

   134  *

   135  * The texture manager makes sure that only one copy of each image is loaded

   136  * at a time, so even if the application requests the same image several times

   137  * it is only loaded once. Textures are identified either by an integer ID or

   138  * by their file name.

   139  *

   140  * @todo Document supported image (file) formats / how are the images loaded

   141  *

   142  * CHuiTextureManager is owned by CHuiEnv, and should be accessed via a

   143  * CHuiEnv instance. You should never construct your own texturemanagers.

   144  *

   145  * @lib hitchcock.lib

   146  */

   147 class CHuiTextureManager : public CActive

   148     {

   149 public:

   150 

   151     /**

   152      * States of a CHuiTextureManager object.

   153      */

   154     enum TState

   155         {

   156         /** Indicates that the manager is in idle state. A new bitmap loading

   157             operation can be started. */

   158         EIdle,

   159 

   160         /** Indicates that the manager is loading a bitmap. */

   161         ELoading

   162         };

   163 

   164 

   165     /* Constructors and destructor. */

   166 

   167     /**

   168      * Destructor.

   169      */

   170     IMPORT_C virtual ~CHuiTextureManager();

   171 

   172 

   173     /* Methods. */

   174 

   175     /** @beginAPI */

   176 

   177     /**

   178      * Determines the environment the manager belongs to.

   179      */

   180     IMPORT_C CHuiEnv& Env();

   181 

   182     /**

   183      * Retuns a texture having given id. Will return a blank

   184      * texture if the id was not found. With this method

   185      * there is a danger of editing the blank texture

   186      * instead of the real texture you intended to edit.

   187      */

   188     IMPORT_C CHuiTexture* Texture(TInt aId);

   189 

   190     /**

   191      * Retuns a texture having given id. Will return a default blank

   192      * texture if the id was not found.

   193      */

   194     IMPORT_C const CHuiTexture* Texture(TInt aId) const;

   195 

   196     /**

   197      * Returns a texture associated with the given id.

   198      * Will leave if no associated texture exists. If the texture

   199      * is defined using the DefineFileNameL but the texture data

   200      * is not yet loaded then this method call will result in

   201      * LoadTextureL call.

   202      *

   203      * @param aId Id of the retrieved texture.

   204      * @return Pointer to the texture. If the method leaves the return value is undefined.

   205      * @leave KErrNotFound If a texture with the given id does not exist.

   206      */

   207     IMPORT_C CHuiTexture* TextureL(TInt aId);

   208 

   209     /**

   210      * Sets the path where bitmaps are loaded from. If drive is not included, tries to resolver that 

   211      * using CCoeEnv

   212      *

   213      * @param aPath  Path for bitmap files.

   214      * @see LoadTexture() Call to load textures from this location.

   215      */

   216     IMPORT_C void SetImagePathL(const TDesC& aPath);

   217 

   218     /**

   219      * Returns the current image path.

   220      * @see LoadTexture() Call to load textures from this location.

   221      */

   222     IMPORT_C const TDesC& ImagePath() const;

   223 

   224     /**

   225      * Returns the blank texture. This can be used as a dummy texture if

   226      * no real texture is available.

   227      */

   228     IMPORT_C const CHuiTexture& BlankTexture() const;

   229 

   230     /**

   231      * Returns the blank texture. This can be used as a dummy texture if

   232      * no real texture is available. Will generate the blank texture

   233      * if the texture is not yet available.

   234      */

   235     IMPORT_C CHuiTexture& BlankTexture();

   236 

   237     /**

   238      * Loads an image and makes it a texture. The bitmap files are searched in

   239      * the path specified with SetImagePathL. The format of the loaded image

   240      * must be supported by the system (Series 60) codecs.

   241      *

   242      * LoadTextureL is an asynchronous method, which returns an empty texture

   243      * which is loaded and filled in the background. Register an

   244      * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers

   245      * array, whose TextureLoadingCompleted() method will be called when

   246      * textures finish loading. The same observer is also called if an error

   247      * occurs during the loading process. The other method is to check if an

   248      * image has been loaded with TextureManagers IsLoaded().

   249      *

   250      * If a texture with the given id or filename is already loaded the previously

   251      * loaded texture is returned. If texture with the given id has been unloaded

   252      * with UnloadTexture() method then the id is reused by loading a new texture

   253      * on the id.

   254      *

   255      * @param aImageFileName    Name of the image bitmap file to load. Relative

   256      *                          to the image load path. If empty filename is

   257      *                          used, will check if a filename for the id has

   258      *                          been defined and load a texture using that resource

   259      *                          location, if possible.

   260      * @param aFlags            Specify flags for the texture loading and

   261      *                          uploading - how to convert the bitmap to

   262      *                          texture.

   263      * @param aId               Id for the texture. Must be unique, but may be

   264      *                          left unassigned. Use zero for unassigned id.

   265      *

   266      * @note                    If both image name and id are left undefined

   267      *                          ("" and zero), will return a blank texture.

   268      *

   269      * @return                  Reference to the texture.

   270      *

   271      * @see SetImagePathL() To set the image search path. Set to "" to use

   272      * absolute image filenames.

   273      * @see iLoadObservers

   274      * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted()

   275      * @see IsLoaded()

   276      */

   277     IMPORT_C CHuiTexture& LoadTextureL(const TDesC& aImageFileName,

   278                                        THuiTextureUploadFlags aFlags

   279                                          = EHuiTextureUploadFlagDefault,

   280                                        TInt aId = 0,

   281                                        TInt aFrameNumber = 0);

   282 

   283    /**

   284      * Loads an image based on pre-registered id and file name.

   285      *

   286      * @see DefineFileName()

   287      *

   288      * LoadTextureL is an asynchronous method, which returns an empty texture

   289      * which is loaded and filled in the background. Register an

   290      * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers

   291      * array, whose TextureLoadingCompleted() method will be called when

   292      * textures finish loading. The same observer is also called if an error

   293      * occurs during the loading process. The other method is to check if an

   294      * image has been loaded with TextureManagers IsLoaded().

   295      *

   296      * If a texture with the given id or filename is already loaded the previously

   297      * loaded texture is returned. If texture with the given id has been unloaded

   298      * with UnloadTexture() method then the id is reused by loading a new texture

   299      * on the id.

   300      *

   301      * @param aId             The id of the texture/filename to load. The id must

   302      *                        have a filename assigned by a call to DefineFileName().

   303      *                        If the id is left undefined (zero), will return a

   304      *                        blank texture.

   305      * @param aTextureMaxSize Can be used to define a maximum dimensions for

   306      *                        the final texture. The image data loaded will be

   307      *                        scaled (down) and fitted to these dimensions. Use

   308      *                        zero or below-zero values if size does not matter.

   309      *                        If the texture size is larger than the texture size

   310      *                        supported by the GL, the texture will be split to

   311      *                        multiple segments.

   312      * @param aFlags          Specify upload behavior - how to convert the bitmap

   313      *                        to texture and other load/upload behavior.

   314      *

   315      * @return                Reference to the texture.

   316      *

   317      * @see SetImagePathL()   To set the image search path. Set to "" to use

   318      *                        absolute image filenames.

   319      * @see iLoadObservers

   320      * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted()

   321      * @see IsLoaded()

   322      */

   323     IMPORT_C CHuiTexture& LoadTextureL(const TInt aId,

   324                                        const TSize& aTextureMaxSize = TSize(0,0),

   325                                        THuiTextureUploadFlags aFlags = EHuiTextureUploadFlagDefault);

   326 

   327     /**

   328      * Loads an image and makes it a texture. The bitmap files are searched in

   329      * the path specified with SetImagePathL. The format of the loaded image

   330      * must be supported by the system (Series 60) codecs.

   331      *

   332      * LoadTextureL is an asynchronous method, which returns an empty texture

   333      * which is loaded and filled in the background. Register an

   334      * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers

   335      * array, whose TextureLoadingCompleted() method will be called when

   336      * textures finish loading. The same observer is also called if an error

   337      * occurs during the loading process. The other method is to check if an

   338      * image has been loaded with TextureManagers IsLoaded().

   339      *

   340      * If a texture with the given id or filename is already loaded the previously

   341      * loaded texture is returned. If texture with the given id has been unloaded

   342      * with UnloadTexture() method then the id is reused by loading a new texture

   343      * on the id.

   344      *

   345      * @param aImageName            Name of the image bitmap file to load. If

   346      *                              empty filename is used, will check if a

   347      *                              filename for the aId has been defined

   348      *                              (using DefineFileNameL()) and load a texture

   349      *                              using that resource location, if possible.

   350      * @param aTextureMaxSize       Can be used to define a maximum dimensions

   351      *                              for the final texture. The image data

   352      *                              loaded will be scaled (down) and fitted to

   353      *                              these dimensions. Use zero or below-zero

   354      *                              values if size does not matter. If the

   355      *                              texture size is larger than the texture

   356      *                              size supported by the GL, the texture will

   357      *                              be split to multiple segments.

   358      * @param aFlags                Specify load/upload behavior - how to convert

   359      *                              the bitmap to texture.

   360      * @param aId                   Id for the texture. Must be unique.

   361      *                              Use zero for unassigned id.

   362      *

   363      * @note                        If both image name and id are left undefined

   364      *                              ("" and zero), will return a blank texture.

   365      *

   366      * @return Reference to the texture.

   367      *

   368      * @see SetImagePathL() To set the image search path. Set to "" to use

   369      * absolute image filenames.

   370      * @see iLoadObservers

   371      * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted()

   372      * @see IsLoaded()

   373      */

   374     IMPORT_C CHuiTexture& LoadTextureL(const TDesC& aImageName,

   375                                        const TSize& aTextureMaxSize,

   376                                        THuiTextureUploadFlags aFlags

   377                                          = EHuiTextureUploadFlagDefault,

   378                                        TInt aId = 0,

   379                                        TInt aFrameNumber = 0);

   380 

   381     /**

   382      * Creates a texture by calling the ProvideBitmapL method of the passed MHuiBitmapProvider.

   383      *

   384      * If a texture with the given id is already created or loaded the previously

   385      * existing texture is returned. If texture with the given id has been unloaded

   386      * with UnloadTexture() method then the id is reused by loading a new texture

   387      * on the id.

   388      *

   389      * If EHuiTextureFlagAllowDirectBitmapUsage flag is used, the provided bitmaps should be in the 

   390      * preferred format. That can be found using CHuiDisplay::GetPreferredTextureFormats(). Also 

   391      * the bitmaps shall not be compressed or have duplicated handle.

   392      *

   393      * @param aBitmapProvider       A bitmap provider that will load the bitmaps for us. The

   394      *                              ProvideBitmapL method of this will be called, which should

   395      *                              load or generate the needed bitmaps.

   396      * @param aFlags                Specify load/upload behavior - how to convert

   397      *                              the bitmap to texture.

   398      * @param aId                   Id for the texture. Must be unique.

   399      *                              Use zero for unassigned id.

   400      * @return Reference to the created texture.

   401      * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size) or 

   402                            in incorrect format

   403      */

   404     IMPORT_C CHuiTexture& CreateTextureL(TInt aId,

   405                                          MHuiBitmapProvider* aBitmapProvider,

   406                                          THuiTextureUploadFlags aFlags);

   407 

   408     /**

   409      * Update the texture content by calling the ProvideBitmapL method for the existing provider. 

   410      * Also a new provider can be given as a parameter. The texture must exist prior calling this 

   411      * method. 

   412      *

   413      * If EHuiTextureFlagAllowDirectBitmapUsage flag is used, the provided bitmaps should be in the 

   414      * preferred format. That can be found using CHuiDisplay::GetPreferredTextureFormats(). Also 

   415      * the bitmaps shall not be compressed or have duplicated handle.

   416      *

   417      * @param aId                   Id for the texture. Must be unique.

   418      *                              Use zero for unassigned id.

   419      * @param aBitmapProvider       A bitmap provider that will load the bitmaps for us. The

   420      *                              ProvideBitmapL method of this will be called, which should

   421      *                              load or generate the needed bitmaps.

   422      * @leave KErrNotFound The texture id does not exist or the source bitmap is not found.

   423      * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size) or 

   424                            in incorrect format

   425      */

   426  	IMPORT_C void UpdateTextureFromBitmapL(TInt aId, MHuiBitmapProvider* aBitmapProvider = NULL);

   427  

   428    /**

   429      * Unloads a texture from memory.

   430      *

   431      * This method releases the texture id and image name for reusing.

   432      * @see LoadTexture().

   433      *

   434      * @note May unload several textures from memory, if they have the

   435      * sane image name assigned!

   436      */

   437     IMPORT_C void UnloadTexture(const TDesC& aImageName, const TInt aFrameNumber = 0);

   438 

   439     /**

   440      * Unloads a texture from memory.

   441      *

   442      * This method releases the texture id and image name for reusing.

   443      * @see LoadTexture().

   444      */

   445     IMPORT_C void UnloadTexture(TInt aId);

   446 

   447     /**

   448      * Define (register) a texture resource (filename/path) for

   449      * a texture id. Enables calling the LoadTextureL only with an id.

   450      * This resource will then be loaded when LoadTextureL

   451      * is called with the id.

   452      */

   453     IMPORT_C void DefineFileNameL(TInt aId, const TDesC& aImageName);

   454 

   455     /**

   456      * Returns the number of images waiting to be loaded.

   457      *

   458      * @return  Length of the load queue.

   459      */

   460     IMPORT_C TInt LoadQueueCount() const;

   461 

   462     /**

   463      * Returns the state of the texture manager.

   464      */

   465     inline TState State() const

   466         {

   467         return iState;

   468         }

   469 

   470     /**

   471      * Returns a reference to the texture processor.

   472      *

   473      * @panic THuiPanic::ETextureManagerNoProcessor  Texture processor is not available.

   474      */

   475     IMPORT_C CHuiTextureProcessor& Processor();

   476 

   477     /**

   478      * Prepends the image path to the beginning of the file name,

   479      * if necessary.

   480      */

   481     IMPORT_C void PrependImagePath(TDes& aFileName) const;

   482 

   483     /**

   484      * Iterates through the managed textures to find aTexture, and then

   485      * assigns it a new ID of aId.

   486      *

   487      * @param aTexture  The managed texture whose ID we want to change.

   488      * @param aId       The texture ID that we want to assign to the managed texture.

   489      *

   490      * @return          ETrue if the texture was found and the ID set, EFalse if the

   491      *                  texture was not found in the manager's list.

   492      */

   493     IMPORT_C TBool SetTextureId(CHuiTexture* aTexture, TInt aId);

   494 

   495     /**

   496      * Checks if a texture exists, has content and is not found

   497      * from the texture load queue.

   498      * 

   499      * Mainly meant for file-based textures to check if the 

   500      * texture is ready to be used. 

   501      * 

   502      * Note that textures may have some temporary placeholder

   503      * content already before they have been fully loaded!

   504      * 

   505      * For CreateTextureL -based textures it is recommended to use

   506      * CHuiTexture::HasContent() directly.

   507      * 

   508      * @see LoadTextureL()

   509      * @see CreateTextureL()

   510      * @see CHuiTexture::HasContent()

   511      *

   512      * @param aImageName  Name of the image bitmap file to check. 

   513      * 					  ImagePath (if set) will be prepended to 

   514      * 					  this name.

   515      * @return 			  ETrue if texture exists, has content and 

   516      * 					  is not found from the texture load queue.

   517      */

   518     IMPORT_C TBool IsLoaded(const TDesC& aImageName, const TInt aFrameNumber = 0) const;

   519 

   520     /**

   521      * Checks if a texture exists, has content and is not found

   522      * from the texture load queue.

   523      * 

   524      * Mainly meant for file-based textures to check if the 

   525      * texture is ready to be used. 

   526      * 

   527      * Note that textures may have some temporary placeholder

   528      * content already before they have been fully loaded!

   529      * 

   530      * For CreateTextureL -based textures it is recommended to use

   531      * CHuiTexture::HasContent() directly.

   532      * 

   533      * @see LoadTextureL()

   534      * @see CreateTextureL()

   535      * @see CHuiTexture::HasContent()

   536      *

   537      * @param aId 		Id of the texture.

   538      * @return 			ETrue if texture exists, has content and is not found

   539      * 					from the texture load queue.

   540      */

   541     IMPORT_C TBool IsLoaded(TInt aId) const;

   542 

   543     /**

   544      * Checks if a texture exists, has content and is not found

   545      * from the texture load queue.

   546      * 

   547      * Mainly meant for file-based textures to check when the 

   548      * texture is ready to be used. 

   549      * 

   550      * Note that textures may have some temporary placeholder

   551      * content already before they have been fully loaded!

   552      * 

   553      * For CreateTextureL -based textures it is recommended to use

   554      * CHuiTexture::HasContent() directly.

   555      * 

   556      * @see LoadTextureL()

   557      * @see CreateTextureL()

   558      * @see CHuiTexture::HasContent()

   559      *

   560      * @param aTexture Texture object.

   561      * @return True if texture exists, has content and is not found

   562      * from the texture load queue.

   563      */

   564     IMPORT_C TBool IsLoaded(const CHuiTexture * aTexture) const;

   565 

   566     /** @endAPI */

   567 

   568 

   569     /**

   570      * Appends a texture to the texture manager's list of managed textures.

   571      * Ownership of the texture is transferred to the manager; when the manager

   572      * is destroyed, the texture will be destroyed, too.

   573      *

   574      * @param aTexture  Texture to transfer to the manager.

   575      * @param aId       Id for the texture. Must be unique. Use zero for

   576      * unassigned id.

   577      * @leave KErrAlreadyExists if a texture with the given id already exists.

   578      *

   579      * @todo Does not check (or replace) already existing duplicate textures

   580      * having matching id.

   581      */

   582     IMPORT_C virtual void AppendTextureL(CHuiTexture* aTexture, TInt aId = 0);

   583 

   584     /**

   585      * Removes a texture from management. The texture's ownership is

   586      * transferred to the caller.

   587      *

   588      * @param aTexture  Texture to remove from management.

   589      */

   590     IMPORT_C virtual void RemoveTexture(CHuiTexture& aTexture);

   591 

   592     /**

   593      * Informs the texture manager that time has progressed. The manager will

   594      * update any animated textures.

   595      */

   596     IMPORT_C void AdvanceTime(TReal32 aElapsedTime) const;

   597 

   598     /**

   599      * Releases texture manager resources. Releases all textures. Called when the

   600      * render plugin is released.

   601      *

   602      * While the release operation is in progress, it is not possible to delete

   603      * CHuiTexture instances or create new ones. After the release has been

   604      * completed, textures can again be deleted and created.

   605      *

   606      * @return ETrue if the all the textures were released.

   607      *         EFalse if some of the textures 

   608      * @panic ETextureManagerTextureConstructedDuringRelease

   609      *      A new CHuiTexture was constructed and added to the texture

   610      *      manager during the release operation.

   611      * @panic ETextureManagerTextureDestroyedDuringRelease

   612      *      An existing CHuiTexture was destroyed and removed from the texture

   613      *      manager during the release operation.

   614      *

   615      * @see RestoreL()

   616      */

   617     IMPORT_C virtual TBool Release();

   618 

   619     /**

   620      * Restores texture manager resources. Restores the content of all textures

   621      * released in Release(). Called when render plugin restored.

   622      *

   623      * While the restore operation is in progress, it is not possible to delete

   624      * CHuiTexture instances or create new ones. After the restore has been

   625      * completed, textures can again be deleted and created.

   626      *

   627      * @panic ETextureManagerTextureConstructedDuringRestore

   628      *      A new CHuiTexture was constructed and added to the texture

   629      *      manager during the restore operation.

   630      * @panic ETextureManagerTextureDestroyedDuringRestore

   631      *      An existing CHuiTexture was destroyed and removed from the texture

   632      *      manager during the restore operation.

   633      *

   634      * @see Release()

   635      */

   636     IMPORT_C virtual void RestoreL();

   637     

   638     /**

   639      * Releases and restores skin dependent textures. Usually called after

   640      * system skin has been changed.

   641      */

   642     IMPORT_C void NotifySkinChangedL();

   643     

   644     /**

   645      * Adds animated texture group. 

   646      * Use this method to inform texture manager that when texture is loaded, 

   647      * it's allowed to use previous state of the group. Each texture id should 

   648      * belong at most to one group. This method should be called before

   649      * using these texture ids to load textures.

   650      * @param aTextureIds texture ids that form a group.

   651      * @return animated texture group id.

   652      */

   653     IMPORT_C TInt AddAnimatedTextureGroupL( const RArray<TInt>& aTextureIds );

   654     

   655     /**

   656      * Removes animated texture group.

   657      * @param aGroupId animated texture group id.

   658      */

   659     IMPORT_C void RemoveAnimatedTextureGroup( TInt aGroupId );

   660 

   661     

   662     /**

   663      * Clears texture changed flags.

   664      */

   665     IMPORT_C void ClearChangedTextures();

   666     

   667     /**

   668      * Sets a flag that indicates that there are changed textures.

   669      */

   670     IMPORT_C void SetHasChangedTextures();

   671     

   672     /**

   673      * Sets a flag if texture memory usage calculation should be done and printed.

   674      */

   675     IMPORT_C void EnableTexMemoryCalculation( TBool aEnableTeMemCal );

   676 

   677     /**

   678      * Estimated mem usage for textures assuming that textures which have pixel content

   679      * are using given amount of memory per pixel.

   680      * @return Estimated texture memory usage in bytes

   681      */

   682     TInt EstimatedTextureMemUsage(TInt aAverageBitsPerPixel) const;

   683 

   684     /**

   685      * Enables (or disables) texture autosize calculations.

   686      */

   687     void EnableAutoSizeCalculation(TBool aEnable = ETrue);

   688 

   689 protected:

   690 

   691     /* Protected data structures. */

   692 

   693     /**

   694      * Permanent registration entry for textures.

   695      */

   696     NONSHARABLE_CLASS(CTextureEntry) : public CBase, public MHuiTextureContentObserver

   697         {

   698     private:

   699         CTextureEntry(); // the dummy constructor is private!

   700     public:

   701         CTextureEntry(TInt aId,

   702                       const TFileName & aFileName,

   703                       const TSize& aMaxTextureSize = TSize(0,0),

   704                       THuiTextureUploadFlags aFlags = EHuiTextureUploadFlagDefault,

   705                       TInt aFrameNumber = 0);

   706                       

   707         CTextureEntry(TInt aId, CHuiTexture * aTexture);

   708         

   709         CTextureEntry & operator=(const CTextureEntry &aSrc);

   710         

   711     private:

   712         CTextureEntry(const CTextureEntry &aSrc);

   713         

   714     public:

   715     

   716         ~CTextureEntry();

   717         

   718         void SetFileName(const TFileName & aFileName);

   719 

   720         void TextureContentUploaded(CHuiTexture& aTexture);

   721 

   722         void TextureContentReleased(CHuiTexture& aTexture);

   723 

   724         void RestoreTextureContentL(CHuiTexture& aTexture);

   725 

   726         /** The texture id. Set to zero for no id. */

   727         TInt iId;

   728 

   729         /** Resource location for the texture. */

   730         HBufC*  iFileName;

   731 

   732         /** The texture entry. */

   733         CHuiTexture* iTexture;

   734 

   735         /** Requested maximum size for the texture. */

   736         TSize iMaxTextureSize;

   737 

   738         /** Specify upload behavior - how to convert the bitmap

   739           to texture. */

   740         THuiTextureUploadFlags iFlags;

   741 

   742         /** Bitmap content provider. Alternative content (re)loading

   743          * mechanism to filenames (loading from a file). */

   744         MHuiBitmapProvider* iBitmapProvider;

   745         

   746         /* Number of bits perpixel, used by texture. This field is used while 

   747          * calculating total memory consumption by texturemanager, for textures.

   748          */

   749         TInt iBitDepth;       

   750         

   751         /** The frame number. */

   752         TInt iFrameNumber;

   753         TInt iFrameCount;

   754         TInt iFrameInterval;

   755         };

   756 

   757     /**

   758      * Temporary asynchronous load entry for textures.

   759      */

   760     struct SLoadQueueEntry

   761         {

   762         /** The texture entry that is being loaded. */

   763         CTextureEntry* iLoading;

   764 

   765         /** The image being loaded has an alpha channel. */

   766         TBool iHasAlpha;

   767 

   768         /** The original, non-downscaled size of the image. */

   769         TSize iOriginalSize;

   770 

   771         /** Image decoder to load bitmap images. */

   772         CImageDecoder* iDecoder;

   773 

   774         /** True, if the texture was already unloaded before it finished

   775             loading. */

   776         TBool iUnloaded;

   777 

   778         };

   779 

   780 

   781     enum TReleaseState

   782         {

   783         /** The texture manager is operating normally in the non-released state. */

   784         ENormal,

   785 

   786         /** The texture manager is currently releasing textures. */

   787         EReleasing,

   788 

   789         /** The texture manager is operating normally in the released state. */

   790         EReleased,

   791         

   792         /** The texture manager is operating normally in the partly released state. 

   793             This occurs if some of the textures cannot be released*/

   794         EPartiallyReleased,

   795 

   796         /** The texture manager is current restoring textures. */

   797         ERestoring

   798         };

   799 

   800 

   801 protected:

   802 

   803     /* Constructors. */

   804 

   805     /**

   806      * Constructor.

   807      */

   808     IMPORT_C CHuiTextureManager(CHuiEnv& aEnv /*MHuiTextureManagerObserver* aObserver = NULL*/);

   809 

   810     /**

   811      * Second-phase constructor.

   812      */

   813     IMPORT_C void BaseConstructL();

   814 

   815 

   816     /* Methods. */

   817 

   818     /**

   819      * Sets the texture processor of the manager. Ownership of the processor

   820      * is given to the manager.

   821      *

   822      * @param aProcessor  Texture processor instance. Ownership is transferred.

   823      */

   824     IMPORT_C void SetProcessor(CHuiTextureProcessor* aProcessor);

   825 

   826     /**

   827      * Returns a texture entry.

   828      *

   829      * @param aIndex  Index of the texture.

   830      *

   831      * @return  Returns a texture entry from the set of existing textures.

   832      */

   833     IMPORT_C CTextureEntry* TextureEntry(TInt aIndex);

   834 

   835     /**

   836      * Returns the number of texture entries.

   837      */

   838     IMPORT_C TInt TextureEntryCount() const;

   839 

   840     /**

   841      * Check the existence of a texture.

   842      *

   843      * @param aFileName  File name of the texture.

   844      *

   845      * @return  Index of the texture, in the iTextures array, or -1 if not found.

   846      */

   847     IMPORT_C TInt CheckTexture(const TDesC& aFileName, TInt aFrameNumber = 0) const;

   848 

   849     /**

   850      * Check the existence of a texture.

   851      * @param aId Id of the texture to check.

   852      * @return  Index of the texture, in the iTextures array, or

   853      * -1 if not found.

   854      */

   855     IMPORT_C TInt CheckTexture(TInt aId) const;

   856 

   857     /**

   858      * Helper method that notifies observers of texture load completion.

   859      * @see iLoadObservers

   860      */

   861     IMPORT_C void NotifyTextureLoaded(CHuiTexture& aTexture,

   862                              TInt aTextureId,

   863                              TInt aErrorCode) const;

   864 

   865 protected: // New methods

   866     

   867     /**

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

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

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

   871      * extension APIs.

   872      * 

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

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

   875      */

   876     IMPORT_C virtual void TextureManagerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   877 

   878 private:

   879     

   880     /* Private methods */

   881 

   882     /**

   883      * Creates a texture from the given CFbsBitmap and its mask bitmap.

   884      * This is a synchronous method call and will result in consequent call

   885      * of TextureLoadingCompleted of all observers if the texture creation

   886      * was successful. As filename cannot be acquired for created

   887      * textures the user provided string will be used. Note that the filename

   888      * has to be unique for all textures. Textures are identified by their

   889      * filename and if a texture with existing filename is loaded / created

   890      * then already loaded / created texture will be returned instead of

   891      * creating a new texture.

   892      *

   893      * @note There are problems in creating textures from icon bitmaps exported

   894      * using AknsUtils::CreateAppIconLC(). It seems that it is impossible to

   895      * access the bitmap data of created icon directly using DataAddtess() - method

   896      * or THuiBitmapUtil - method. HUIToolkit relies on these methods.

   897      * To create textures from the system icons you have to copy the icons to temporary

   898      * CFbsBitmaps. Notice that duplicating the bitmap handle with CFbsBitmap::Duplicate is

   899      * not enough. You have to make a physical copy.

   900      *

   901      * @param aBitmap    The source bitmap from which the texture is created.

   902      * @param aMask      Pointer to the mask bitmap that is used as alpha blending

   903      *                   mask for the texture. This parameter can be NULL for

   904      *                   textures without alpha channel.

   905      * @param aId        The id of the texture/filename to load. The id must have

   906      *                   a filename assigned by a call to DefineFileName().

   907      * @return Reference to the created texture.

   908      * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size).

   909      */

   910     IMPORT_C virtual CHuiTexture& CreateTextureL(CFbsBitmap& aBitmap,

   911                                          const CFbsBitmap* aMask,

   912                                          THuiTextureUploadFlags aFlags,

   913                                          TInt id);

   914 

   915     /**

   916      * Returns the file server session that should be used by the manager.

   917      */

   918     RFs& FsSession() const;

   919 

   920     /** Returns true if the given texture is still in the load queue. */

   921     TBool IsInLoadQueue(const CHuiTexture * texture) const;

   922 

   923     /** Returns true if the given texture is still in the load queue. */

   924     TBool IsInLoadQueue(TInt id) const;

   925 

   926     /**

   927      * Called when image loading (decoding) operation is complete.

   928      */

   929     IMPORT_C void RunL();

   930 

   931     /**

   932      * Handles a leave occurring in the request completion event handler RunL().

   933      */

   934     IMPORT_C TInt RunError( TInt aError );

   935 

   936     /**

   937      * Called when a sub-image has been loaded

   938      * (before calling @c ImageLoadingCompleteL).

   939      * This method checks if we need to continue loading.

   940      * @return Error code or positive integer. If positive integer,

   941      *         stop and do not continue to frame generation.

   942      */

   943     TInt ImageLoadingContinue();

   944     

   945     /**

   946      * Called when an image has finished loading. Handles

   947      * uploading of the loaded bitmap to the texture.

   948      * @param aEntry queue entry.

   949      */

   950     void ImageLoadingCompleteL(SLoadQueueEntry& aEntry);

   951 

   952     /**

   953      * Processes animated frame.

   954      * @param aEntry queue entry.

   955      */

   956     void ProcessAnimatedFrameL(SLoadQueueEntry& aEntry);

   957 

   958     /**

   959      * Cancel active object operation.

   960      */

   961     IMPORT_C void DoCancel();

   962 

   963     /**

   964      * Starts loading next images from the load queue. If scheduling a

   965      * queue entry fails for some reason, the entry is discarded and the

   966      * next queue entry is processed.

   967      */

   968     void StartLoading();

   969 

   970     /**

   971      * Cleans up the topmost load queue entry and removes it from the

   972      * load queue. Deletes the decoder, but not the loaded texture entry.

   973      */

   974     SLoadQueueEntry PopLoadedQueueEntry();

   975 

   976     /**

   977      * Sets up image decoding and starts to load the first entry in the load

   978      * queue.

   979      * @leave Standard error code if decoder initialization/resource read

   980      * fails.

   981      */

   982     void DoLoadNextL();

   983 

   984     /**

   985      * Unloads a texture having given index in the texture array (iTextures).

   986      */

   987     void DoUnload(TInt index);

   988 

   989     /**

   990      * Cancels the scheduled or ongoing loading of a texture.

   991      * If the texture is found from load queue it is immediately removed from

   992      * the queue.

   993      * If the removed texture was being loaded at the time this method is called

   994      * the loading is cancelled and restarted from the next unloaded texture.

   995      *

   996      * @param aTexture Reference to the texture of which load is cancelled.

   997      */

   998     void CancelLoadingOfTexture(CHuiTexture& aTexture);

   999 

  1000     /**

  1001      * Helper method that notifies observers of texture manager state change.

  1002      * @see iStateObservers

  1003      */

  1004     void NotifyStateChange() const;

  1005     

  1006     /**

  1007      * Update texture flags if needed.

  1008      * @param aBitmap    Bitmap.

  1009      * @param aMask      Mask.

  1010      * @param aFlags     Texture flags. This returns the changed value.

  1011      */

  1012     void UpdateFlags(const CFbsBitmap& aBitmap, const CFbsBitmap* aMaskBitmap, THuiTextureUploadFlags& aFlags);

  1013     

  1014     void NotifyTextureAutoSizeObservers() const;

  1015 

  1016     /**

  1017      * Creates animation state.

  1018      * @param aGroupId group id.

  1019      * @param aImageFile image file.

  1020      * @param aFrameNumber frame number.

  1021      * @param aFrameCount frame count.

  1022      */

  1023     CHuiTextureAnimationState* CreateAnimationStateL( 

  1024         TInt aGroupId, const TDesC& aImageFile, 

  1025         TInt aFrameNumber, TInt aFrameCount );

  1026     

  1027     /**

  1028      * Finds animation state owned by aGroupId.

  1029      * @return animation state or NULL if not found.

  1030      */

  1031     CHuiTextureAnimationState* FindAnimationState( TInt aGroupId );

  1032     

  1033     /**

  1034      * Removes animation state.

  1035      * @param aState state to be removed.

  1036      */

  1037     void RemoveAnimationState( CHuiTextureAnimationState* aState );

  1038     

  1039     /**

  1040      * Finds group id by texture id.

  1041      * @param aTextureId texture id to look for.

  1042      * @param aGroupId updated to contain found group id.

  1043      * @return ETrue if succeeded, EFalse otherwise.

  1044      */

  1045     TBool FindGroupIdByTextureId( TInt aTextureId, TInt& aGroupId ) const;

  1046     

  1047     /**

  1048      * Checks if animation state is needed.

  1049      * @param aDecoder decoder.

  1050      * @return ETrue if needed, EFalse otherwise.

  1051      */

  1052     static TBool NeedsAnimationState( const CImageDecoder& aDecoder );

  1053     

  1054     // For debugging purposes! Used to calculate texture memory usage

  1055     /* Calculates memory used by texturemanager for all the textures and prints as info messages

  1056      */

  1057     void TextureMemUsage() const;

  1058 

  1059 public:

  1060 

  1061     /* Public properties. */

  1062 

  1063     /**

  1064      * Observers that are notified of changes in the state of the manager.

  1065      * Applications may directly add and remove their own observers using

  1066      * this public property.

  1067      */

  1068     RHuiObserverArray<MHuiTextureManagerStateChangedObserver> iStateObservers;

  1069 

  1070     /**

  1071      * Observers that are notified loaded textures of the manager.

  1072      * Applications may directly add and remove their own observers using

  1073      * this public property.

  1074      */

  1075     RHuiObserverArray<MHuiTextureLoadingCompletedObserver> iLoadObservers;

  1076 

  1077     /** Animated textures. */

  1078     RHuiObserverArray<MHuiTimeObserver> iAnimatedTextures;

  1079 

  1080     /** 

  1081      * Observers that are notified when toolkit notices a change in texture

  1082      * auto size e.g. it is now being drawn as different size than before.

  1083      * Observers are notified possibly between every frame, they should handle

  1084      * notifications as quickly as possible.

  1085      */

  1086     RHuiObserverArray<MHuiTextureAutoSizeObserver> iTextureAutoSizeObservers;

  1087 

  1088 private:

  1089 

  1090     /** Environment. */

  1091     CHuiEnv& iEnv;

  1092 

  1093     /** Empty texture that is returned if an invalid image is specified. */

  1094     CHuiTexture* iBlankTexture;

  1095 

  1096     /** State of the texture manager. */

  1097     TState iState;

  1098 

  1099     /** This variable tells whether there has been a valid texture in the load queue

  1100         that we have started to load in the current texture load loop. This variable 

  1101         indicates that we have started to load at least one texture during the load loop. */

  1102     TBool iLoadQueueHadValidTexture;

  1103 

  1104     /** State of the release/restore process. */

  1105     TReleaseState iReleaseState;

  1106 

  1107     /** Path where image files are loaded from. */

  1108     HBufC* iImagePath;

  1109 

  1110     /** Queue of loading tasks. */

  1111     RArray<SLoadQueueEntry> iLoadQueue;

  1112 

  1113     /** Counter for generating new font identifiers. */

  1114     TInt iFontIdEnumerator;

  1115 

  1116     /**

  1117      * Registry of all textures within this toolkit.

  1118      * Accessed by texture ids (iId) or texture filenames (iFileName).

  1119      * Members may be NULL if a texture is not loaded.

  1120      */

  1121     RPointerArray<CTextureEntry> iTextures;

  1122 

  1123     /** Bitmap for loading asynchronously into. */

  1124     CFbsBitmap* iBitmap;

  1125 

  1126     /** Mask bitmap for loading alpha channels. */

  1127     CFbsBitmap* iMaskBitmap;

  1128 

  1129     /** Texture processor instance. */

  1130     CHuiTextureProcessor* iProcessor;

  1131 

  1132     /** Open file server session for image loading. */

  1133     RFs& iFS;

  1134 

  1135     /**