diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_core_toolkit_api/inc/uiacceltk/HuiTextureManager.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_core_toolkit_api/inc/uiacceltk/HuiTextureManager.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,1174 @@ +/* +* Copyright (c) 2006-2007 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: Defines CHuiTextureManager class for texture objects loading +* and management. +* +*/ + + + +#ifndef __HUITEXTUREMANAGER_H__ +#define __HUITEXTUREMANAGER_H__ + + +#include +#include +#include + +#include +#include +#include +#include + + +/* Forward declarations */ +class CHuiEnv; +class CHuiTextureManager; +class CHuiTextureProcessor; +class CHuiTextureAnimationState; + +/** + * Provides callback methods for getting notifications of texture manager state + * changes. An observer of a CHuiTextureManager. + * + * The class willing to receive these events must implement the methods + * of this interface, and then register itself to the obsevers list of + * the texture manager. + * + * @see CHuiTextureManager + */ +class MHuiTextureManagerStateChangedObserver + { +public: + /** + * Called to notify the observer that the state of the texture manager + * has changed. This is called when the state changes between Idle and + * Loading. + * + * @param aManager Texture manager. + */ + virtual void TextureManagerStateChanged(const CHuiTextureManager& aManager) = 0; + + }; + +/** + * Provides callback methods for getting notifications when texture manager + * finishes asynchronous texture loads. An observer of a CHuiTextureManager. + * + * The class willing to receive these events must implement the methods + * of this interface, and then register itself to the obsevers list of + * the texture manager. + * + * @see CHuiTextureManager + */ +class MHuiTextureLoadingCompletedObserver + { +public: + /** + * Called to notify the observer that loading of a texture has + * been completed. + * @param aTexture Reference to the texture that has been loaded. + * @param aTextureId Id of the texture in the texture manager. Can be used + * to identify the loaded texture, provided that an id was assigned to the + * texture. + * @param aErrorCode KErrNone if the load was successful, otherwise one of + * the system-wide error codes indicating reason why the texture loading + * failed. + * @note One should not commence loading of a new texture in this callback method. + */ + virtual void TextureLoadingCompleted(CHuiTexture& aTexture, + TInt aTextureId, + TInt aErrorCode) = 0; + + }; + + +/** + * Provides callback methods for getting notifications when texture manager + * notices a texture which preferrred size is changed. + * + * The class willing to receive these events must implement the methods + * of this interface, and then register itself to the obsevers list of + * the texture manager. + * + * @see CHuiTextureManager + */ +class MHuiTextureAutoSizeObserver + { +public: + /** + * Called to notify the observer that the preferred size of a texture + * has beem changed. + * + * @param aTexture Texture which preferred size has changed. + * @param aTextureId Id of the changed texture. + * @param aSize New preferred size for texture. + * @return ETrue if observer accepts new size, EFalse if it does not accept or + * doesn't care. + */ + virtual TBool PreferredSizeChanged(const CHuiTexture& aTexture, TInt aTextureId, const THuiRealSize& aSize) = 0; + + /** + * Called to notify the observer that all changed preferred sizes of textures are + * reported (for this frame). + */ + virtual void PreferredSizeReportCompleted() = 0; + }; + +/** + * CHuiTextureManager is responsible for managing the texture objects used by + * the application. It provides asynchronous loading of image data into + * CHuiTexture instances. The texture manager also manages font textures, + * which can be used for compositing text in text meshes. + * + * The texture manager makes sure that only one copy of each image is loaded + * at a time, so even if the application requests the same image several times + * it is only loaded once. Textures are identified either by an integer ID or + * by their file name. + * + * @todo Document supported image (file) formats / how are the images loaded + * + * CHuiTextureManager is owned by CHuiEnv, and should be accessed via a + * CHuiEnv instance. You should never construct your own texturemanagers. + * + * @lib hitchcock.lib + */ +class CHuiTextureManager : public CActive + { +public: + + /** + * States of a CHuiTextureManager object. + */ + enum TState + { + /** Indicates that the manager is in idle state. A new bitmap loading + operation can be started. */ + EIdle, + + /** Indicates that the manager is loading a bitmap. */ + ELoading + }; + + + /* Constructors and destructor. */ + + /** + * Destructor. + */ + IMPORT_C virtual ~CHuiTextureManager(); + + + /* Methods. */ + + /** @beginAPI */ + + /** + * Determines the environment the manager belongs to. + */ + IMPORT_C CHuiEnv& Env(); + + /** + * Retuns a texture having given id. Will return a blank + * texture if the id was not found. With this method + * there is a danger of editing the blank texture + * instead of the real texture you intended to edit. + */ + IMPORT_C CHuiTexture* Texture(TInt aId); + + /** + * Retuns a texture having given id. Will return a default blank + * texture if the id was not found. + */ + IMPORT_C const CHuiTexture* Texture(TInt aId) const; + + /** + * Returns a texture associated with the given id. + * Will leave if no associated texture exists. If the texture + * is defined using the DefineFileNameL but the texture data + * is not yet loaded then this method call will result in + * LoadTextureL call. + * + * @param aId Id of the retrieved texture. + * @return Pointer to the texture. If the method leaves the return value is undefined. + * @leave KErrNotFound If a texture with the given id does not exist. + */ + IMPORT_C CHuiTexture* TextureL(TInt aId); + + /** + * Sets the path where bitmaps are loaded from. If drive is not included, tries to resolver that + * using CCoeEnv + * + * @param aPath Path for bitmap files. + * @see LoadTexture() Call to load textures from this location. + */ + IMPORT_C void SetImagePathL(const TDesC& aPath); + + /** + * Returns the current image path. + * @see LoadTexture() Call to load textures from this location. + */ + IMPORT_C const TDesC& ImagePath() const; + + /** + * Returns the blank texture. This can be used as a dummy texture if + * no real texture is available. + */ + IMPORT_C const CHuiTexture& BlankTexture() const; + + /** + * Returns the blank texture. This can be used as a dummy texture if + * no real texture is available. Will generate the blank texture + * if the texture is not yet available. + */ + IMPORT_C CHuiTexture& BlankTexture(); + + /** + * Loads an image and makes it a texture. The bitmap files are searched in + * the path specified with SetImagePathL. The format of the loaded image + * must be supported by the system (Series 60) codecs. + * + * LoadTextureL is an asynchronous method, which returns an empty texture + * which is loaded and filled in the background. Register an + * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers + * array, whose TextureLoadingCompleted() method will be called when + * textures finish loading. The same observer is also called if an error + * occurs during the loading process. The other method is to check if an + * image has been loaded with TextureManagers IsLoaded(). + * + * If a texture with the given id or filename is already loaded the previously + * loaded texture is returned. If texture with the given id has been unloaded + * with UnloadTexture() method then the id is reused by loading a new texture + * on the id. + * + * @param aImageFileName Name of the image bitmap file to load. Relative + * to the image load path. If empty filename is + * used, will check if a filename for the id has + * been defined and load a texture using that resource + * location, if possible. + * @param aFlags Specify flags for the texture loading and + * uploading - how to convert the bitmap to + * texture. + * @param aId Id for the texture. Must be unique, but may be + * left unassigned. Use zero for unassigned id. + * + * @note If both image name and id are left undefined + * ("" and zero), will return a blank texture. + * + * @return Reference to the texture. + * + * @see SetImagePathL() To set the image search path. Set to "" to use + * absolute image filenames. + * @see iLoadObservers + * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted() + * @see IsLoaded() + */ + IMPORT_C CHuiTexture& LoadTextureL(const TDesC& aImageFileName, + THuiTextureUploadFlags aFlags + = EHuiTextureUploadFlagDefault, + TInt aId = 0, + TInt aFrameNumber = 0); + + /** + * Loads an image based on pre-registered id and file name. + * + * @see DefineFileName() + * + * LoadTextureL is an asynchronous method, which returns an empty texture + * which is loaded and filled in the background. Register an + * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers + * array, whose TextureLoadingCompleted() method will be called when + * textures finish loading. The same observer is also called if an error + * occurs during the loading process. The other method is to check if an + * image has been loaded with TextureManagers IsLoaded(). + * + * If a texture with the given id or filename is already loaded the previously + * loaded texture is returned. If texture with the given id has been unloaded + * with UnloadTexture() method then the id is reused by loading a new texture + * on the id. + * + * @param aId The id of the texture/filename to load. The id must + * have a filename assigned by a call to DefineFileName(). + * If the id is left undefined (zero), will return a + * blank texture. + * @param aTextureMaxSize Can be used to define a maximum dimensions for + * the final texture. The image data loaded will be + * scaled (down) and fitted to these dimensions. Use + * zero or below-zero values if size does not matter. + * If the texture size is larger than the texture size + * supported by the GL, the texture will be split to + * multiple segments. + * @param aFlags Specify upload behavior - how to convert the bitmap + * to texture and other load/upload behavior. + * + * @return Reference to the texture. + * + * @see SetImagePathL() To set the image search path. Set to "" to use + * absolute image filenames. + * @see iLoadObservers + * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted() + * @see IsLoaded() + */ + IMPORT_C CHuiTexture& LoadTextureL(const TInt aId, + const TSize& aTextureMaxSize = TSize(0,0), + THuiTextureUploadFlags aFlags = EHuiTextureUploadFlagDefault); + + /** + * Loads an image and makes it a texture. The bitmap files are searched in + * the path specified with SetImagePathL. The format of the loaded image + * must be supported by the system (Series 60) codecs. + * + * LoadTextureL is an asynchronous method, which returns an empty texture + * which is loaded and filled in the background. Register an + * MHuiTextureLoadingCompletedObserver instance to the iLoadedObservers + * array, whose TextureLoadingCompleted() method will be called when + * textures finish loading. The same observer is also called if an error + * occurs during the loading process. The other method is to check if an + * image has been loaded with TextureManagers IsLoaded(). + * + * If a texture with the given id or filename is already loaded the previously + * loaded texture is returned. If texture with the given id has been unloaded + * with UnloadTexture() method then the id is reused by loading a new texture + * on the id. + * + * @param aImageName Name of the image bitmap file to load. If + * empty filename is used, will check if a + * filename for the aId has been defined + * (using DefineFileNameL()) and load a texture + * using that resource location, if possible. + * @param aTextureMaxSize Can be used to define a maximum dimensions + * for the final texture. The image data + * loaded will be scaled (down) and fitted to + * these dimensions. Use zero or below-zero + * values if size does not matter. If the + * texture size is larger than the texture + * size supported by the GL, the texture will + * be split to multiple segments. + * @param aFlags Specify load/upload behavior - how to convert + * the bitmap to texture. + * @param aId Id for the texture. Must be unique. + * Use zero for unassigned id. + * + * @note If both image name and id are left undefined + * ("" and zero), will return a blank texture. + * + * @return Reference to the texture. + * + * @see SetImagePathL() To set the image search path. Set to "" to use + * absolute image filenames. + * @see iLoadObservers + * @see MHuiTextureLoadingCompletedObserver::TextureLoadingCompleted() + * @see IsLoaded() + */ + IMPORT_C CHuiTexture& LoadTextureL(const TDesC& aImageName, + const TSize& aTextureMaxSize, + THuiTextureUploadFlags aFlags + = EHuiTextureUploadFlagDefault, + TInt aId = 0, + TInt aFrameNumber = 0); + + /** + * Creates a texture by calling the ProvideBitmapL method of the passed MHuiBitmapProvider. + * + * If a texture with the given id is already created or loaded the previously + * existing texture is returned. If texture with the given id has been unloaded + * with UnloadTexture() method then the id is reused by loading a new texture + * on the id. + * + * If EHuiTextureFlagAllowDirectBitmapUsage flag is used, the provided bitmaps should be in the + * preferred format. That can be found using CHuiDisplay::GetPreferredTextureFormats(). Also + * the bitmaps shall not be compressed or have duplicated handle. + * + * @param aBitmapProvider A bitmap provider that will load the bitmaps for us. The + * ProvideBitmapL method of this will be called, which should + * load or generate the needed bitmaps. + * @param aFlags Specify load/upload behavior - how to convert + * the bitmap to texture. + * @param aId Id for the texture. Must be unique. + * Use zero for unassigned id. + * @return Reference to the created texture. + * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size) or + in incorrect format + */ + IMPORT_C CHuiTexture& CreateTextureL(TInt aId, + MHuiBitmapProvider* aBitmapProvider, + THuiTextureUploadFlags aFlags); + + /** + * Update the texture content by calling the ProvideBitmapL method for the existing provider. + * Also a new provider can be given as a parameter. The texture must exist prior calling this + * method. + * + * If EHuiTextureFlagAllowDirectBitmapUsage flag is used, the provided bitmaps should be in the + * preferred format. That can be found using CHuiDisplay::GetPreferredTextureFormats(). Also + * the bitmaps shall not be compressed or have duplicated handle. + * + * @param aId Id for the texture. Must be unique. + * Use zero for unassigned id. + * @param aBitmapProvider A bitmap provider that will load the bitmaps for us. The + * ProvideBitmapL method of this will be called, which should + * load or generate the needed bitmaps. + * @leave KErrNotFound The texture id does not exist or the source bitmap is not found. + * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size) or + in incorrect format + */ + IMPORT_C void UpdateTextureFromBitmapL(TInt aId, MHuiBitmapProvider* aBitmapProvider = NULL); + + /** + * Unloads a texture from memory. + * + * This method releases the texture id and image name for reusing. + * @see LoadTexture(). + * + * @note May unload several textures from memory, if they have the + * sane image name assigned! + */ + IMPORT_C void UnloadTexture(const TDesC& aImageName, const TInt aFrameNumber = 0); + + /** + * Unloads a texture from memory. + * + * This method releases the texture id and image name for reusing. + * @see LoadTexture(). + */ + IMPORT_C void UnloadTexture(TInt aId); + + /** + * Define (register) a texture resource (filename/path) for + * a texture id. Enables calling the LoadTextureL only with an id. + * This resource will then be loaded when LoadTextureL + * is called with the id. + */ + IMPORT_C void DefineFileNameL(TInt aId, const TDesC& aImageName); + + /** + * Returns the number of images waiting to be loaded. + * + * @return Length of the load queue. + */ + IMPORT_C TInt LoadQueueCount() const; + + /** + * Returns the state of the texture manager. + */ + inline TState State() const + { + return iState; + } + + /** + * Returns a reference to the texture processor. + * + * @panic THuiPanic::ETextureManagerNoProcessor Texture processor is not available. + */ + IMPORT_C CHuiTextureProcessor& Processor(); + + /** + * Prepends the image path to the beginning of the file name, + * if necessary. + */ + IMPORT_C void PrependImagePath(TDes& aFileName) const; + + /** + * Iterates through the managed textures to find aTexture, and then + * assigns it a new ID of aId. + * + * @param aTexture The managed texture whose ID we want to change. + * @param aId The texture ID that we want to assign to the managed texture. + * + * @return ETrue if the texture was found and the ID set, EFalse if the + * texture was not found in the manager's list. + */ + IMPORT_C TBool SetTextureId(CHuiTexture* aTexture, TInt aId); + + /** + * Checks if a texture exists, has content and is not found + * from the texture load queue. + * + * Mainly meant for file-based textures to check if the + * texture is ready to be used. + * + * Note that textures may have some temporary placeholder + * content already before they have been fully loaded! + * + * For CreateTextureL -based textures it is recommended to use + * CHuiTexture::HasContent() directly. + * + * @see LoadTextureL() + * @see CreateTextureL() + * @see CHuiTexture::HasContent() + * + * @param aImageName Name of the image bitmap file to check. + * ImagePath (if set) will be prepended to + * this name. + * @return ETrue if texture exists, has content and + * is not found from the texture load queue. + */ + IMPORT_C TBool IsLoaded(const TDesC& aImageName, const TInt aFrameNumber = 0) const; + + /** + * Checks if a texture exists, has content and is not found + * from the texture load queue. + * + * Mainly meant for file-based textures to check if the + * texture is ready to be used. + * + * Note that textures may have some temporary placeholder + * content already before they have been fully loaded! + * + * For CreateTextureL -based textures it is recommended to use + * CHuiTexture::HasContent() directly. + * + * @see LoadTextureL() + * @see CreateTextureL() + * @see CHuiTexture::HasContent() + * + * @param aId Id of the texture. + * @return ETrue if texture exists, has content and is not found + * from the texture load queue. + */ + IMPORT_C TBool IsLoaded(TInt aId) const; + + /** + * Checks if a texture exists, has content and is not found + * from the texture load queue. + * + * Mainly meant for file-based textures to check when the + * texture is ready to be used. + * + * Note that textures may have some temporary placeholder + * content already before they have been fully loaded! + * + * For CreateTextureL -based textures it is recommended to use + * CHuiTexture::HasContent() directly. + * + * @see LoadTextureL() + * @see CreateTextureL() + * @see CHuiTexture::HasContent() + * + * @param aTexture Texture object. + * @return True if texture exists, has content and is not found + * from the texture load queue. + */ + IMPORT_C TBool IsLoaded(const CHuiTexture * aTexture) const; + + /** @endAPI */ + + + /** + * Appends a texture to the texture manager's list of managed textures. + * Ownership of the texture is transferred to the manager; when the manager + * is destroyed, the texture will be destroyed, too. + * + * @param aTexture Texture to transfer to the manager. + * @param aId Id for the texture. Must be unique. Use zero for + * unassigned id. + * @leave KErrAlreadyExists if a texture with the given id already exists. + * + * @todo Does not check (or replace) already existing duplicate textures + * having matching id. + */ + IMPORT_C virtual void AppendTextureL(CHuiTexture* aTexture, TInt aId = 0); + + /** + * Removes a texture from management. The texture's ownership is + * transferred to the caller. + * + * @param aTexture Texture to remove from management. + */ + IMPORT_C virtual void RemoveTexture(CHuiTexture& aTexture); + + /** + * Informs the texture manager that time has progressed. The manager will + * update any animated textures. + */ + IMPORT_C void AdvanceTime(TReal32 aElapsedTime) const; + + /** + * Releases texture manager resources. Releases all textures. Called when the + * render plugin is released. + * + * While the release operation is in progress, it is not possible to delete + * CHuiTexture instances or create new ones. After the release has been + * completed, textures can again be deleted and created. + * + * @return ETrue if the all the textures were released. + * EFalse if some of the textures + * @panic ETextureManagerTextureConstructedDuringRelease + * A new CHuiTexture was constructed and added to the texture + * manager during the release operation. + * @panic ETextureManagerTextureDestroyedDuringRelease + * An existing CHuiTexture was destroyed and removed from the texture + * manager during the release operation. + * + * @see RestoreL() + */ + IMPORT_C virtual TBool Release(); + + /** + * Restores texture manager resources. Restores the content of all textures + * released in Release(). Called when render plugin restored. + * + * While the restore operation is in progress, it is not possible to delete + * CHuiTexture instances or create new ones. After the restore has been + * completed, textures can again be deleted and created. + * + * @panic ETextureManagerTextureConstructedDuringRestore + * A new CHuiTexture was constructed and added to the texture + * manager during the restore operation. + * @panic ETextureManagerTextureDestroyedDuringRestore + * An existing CHuiTexture was destroyed and removed from the texture + * manager during the restore operation. + * + * @see Release() + */ + IMPORT_C virtual void RestoreL(); + + /** + * Releases and restores skin dependent textures. Usually called after + * system skin has been changed. + */ + IMPORT_C void NotifySkinChangedL(); + + /** + * Adds animated texture group. + * Use this method to inform texture manager that when texture is loaded, + * it's allowed to use previous state of the group. Each texture id should + * belong at most to one group. This method should be called before + * using these texture ids to load textures. + * @param aTextureIds texture ids that form a group. + * @return animated texture group id. + */ + IMPORT_C TInt AddAnimatedTextureGroupL( const RArray& aTextureIds ); + + /** + * Removes animated texture group. + * @param aGroupId animated texture group id. + */ + IMPORT_C void RemoveAnimatedTextureGroup( TInt aGroupId ); + + + /** + * Clears texture changed flags. + */ + IMPORT_C void ClearChangedTextures(); + + /** + * Sets a flag that indicates that there are changed textures. + */ + IMPORT_C void SetHasChangedTextures(); + + /** + * Sets a flag if texture memory usage calculation should be done and printed. + */ + IMPORT_C void EnableTexMemoryCalculation( TBool aEnableTeMemCal ); + + /** + * Estimated mem usage for textures assuming that textures which have pixel content + * are using given amount of memory per pixel. + * @return Estimated texture memory usage in bytes + */ + TInt EstimatedTextureMemUsage(TInt aAverageBitsPerPixel) const; + + /** + * Enables (or disables) texture autosize calculations. + */ + void EnableAutoSizeCalculation(TBool aEnable = ETrue); + +protected: + + /* Protected data structures. */ + + /** + * Permanent registration entry for textures. + */ + NONSHARABLE_CLASS(CTextureEntry) : public CBase, public MHuiTextureContentObserver + { + private: + CTextureEntry(); // the dummy constructor is private! + public: + CTextureEntry(TInt aId, + const TFileName & aFileName, + const TSize& aMaxTextureSize = TSize(0,0), + THuiTextureUploadFlags aFlags = EHuiTextureUploadFlagDefault, + TInt aFrameNumber = 0); + + CTextureEntry(TInt aId, CHuiTexture * aTexture); + + CTextureEntry & operator=(const CTextureEntry &aSrc); + + private: + CTextureEntry(const CTextureEntry &aSrc); + + public: + + ~CTextureEntry(); + + void SetFileName(const TFileName & aFileName); + + void TextureContentUploaded(CHuiTexture& aTexture); + + void TextureContentReleased(CHuiTexture& aTexture); + + void RestoreTextureContentL(CHuiTexture& aTexture); + + /** The texture id. Set to zero for no id. */ + TInt iId; + + /** Resource location for the texture. */ + HBufC* iFileName; + + /** The texture entry. */ + CHuiTexture* iTexture; + + /** Requested maximum size for the texture. */ + TSize iMaxTextureSize; + + /** Specify upload behavior - how to convert the bitmap + to texture. */ + THuiTextureUploadFlags iFlags; + + /** Bitmap content provider. Alternative content (re)loading + * mechanism to filenames (loading from a file). */ + MHuiBitmapProvider* iBitmapProvider; + + /* Number of bits perpixel, used by texture. This field is used while + * calculating total memory consumption by texturemanager, for textures. + */ + TInt iBitDepth; + + /** The frame number. */ + TInt iFrameNumber; + TInt iFrameCount; + TInt iFrameInterval; + }; + + /** + * Temporary asynchronous load entry for textures. + */ + struct SLoadQueueEntry + { + /** The texture entry that is being loaded. */ + CTextureEntry* iLoading; + + /** The image being loaded has an alpha channel. */ + TBool iHasAlpha; + + /** The original, non-downscaled size of the image. */ + TSize iOriginalSize; + + /** Image decoder to load bitmap images. */ + CImageDecoder* iDecoder; + + /** True, if the texture was already unloaded before it finished + loading. */ + TBool iUnloaded; + + }; + + + enum TReleaseState + { + /** The texture manager is operating normally in the non-released state. */ + ENormal, + + /** The texture manager is currently releasing textures. */ + EReleasing, + + /** The texture manager is operating normally in the released state. */ + EReleased, + + /** The texture manager is operating normally in the partly released state. + This occurs if some of the textures cannot be released*/ + EPartiallyReleased, + + /** The texture manager is current restoring textures. */ + ERestoring + }; + + +protected: + + /* Constructors. */ + + /** + * Constructor. + */ + IMPORT_C CHuiTextureManager(CHuiEnv& aEnv /*MHuiTextureManagerObserver* aObserver = NULL*/); + + /** + * Second-phase constructor. + */ + IMPORT_C void BaseConstructL(); + + + /* Methods. */ + + /** + * Sets the texture processor of the manager. Ownership of the processor + * is given to the manager. + * + * @param aProcessor Texture processor instance. Ownership is transferred. + */ + IMPORT_C void SetProcessor(CHuiTextureProcessor* aProcessor); + + /** + * Returns a texture entry. + * + * @param aIndex Index of the texture. + * + * @return Returns a texture entry from the set of existing textures. + */ + IMPORT_C CTextureEntry* TextureEntry(TInt aIndex); + + /** + * Returns the number of texture entries. + */ + IMPORT_C TInt TextureEntryCount() const; + + /** + * Check the existence of a texture. + * + * @param aFileName File name of the texture. + * + * @return Index of the texture, in the iTextures array, or -1 if not found. + */ + IMPORT_C TInt CheckTexture(const TDesC& aFileName, TInt aFrameNumber = 0) const; + + /** + * Check the existence of a texture. + * @param aId Id of the texture to check. + * @return Index of the texture, in the iTextures array, or + * -1 if not found. + */ + IMPORT_C TInt CheckTexture(TInt aId) const; + + /** + * Helper method that notifies observers of texture load completion. + * @see iLoadObservers + */ + IMPORT_C void NotifyTextureLoaded(CHuiTexture& aTexture, + TInt aTextureId, + TInt aErrorCode) const; + +protected: // New methods + + /** + * Provides expandability, helps keeping the binary compatibility. Since virtual + * table is now exported and this class is dll derivable and the implementation + * is more difficult to change, hence this method, which can provide additional + * extension APIs. + * + * @param aExtensionUid UID, which is being used for recognizing the extension + * @param aExtensionParams Return pointer to the extension API, once recognized from the extension uid + */ + IMPORT_C virtual void TextureManagerExtension(const TUid& aExtensionUid, TAny** aExtensionParams); + +private: + + /* Private methods */ + + /** + * Creates a texture from the given CFbsBitmap and its mask bitmap. + * This is a synchronous method call and will result in consequent call + * of TextureLoadingCompleted of all observers if the texture creation + * was successful. As filename cannot be acquired for created + * textures the user provided string will be used. Note that the filename + * has to be unique for all textures. Textures are identified by their + * filename and if a texture with existing filename is loaded / created + * then already loaded / created texture will be returned instead of + * creating a new texture. + * + * @note There are problems in creating textures from icon bitmaps exported + * using AknsUtils::CreateAppIconLC(). It seems that it is impossible to + * access the bitmap data of created icon directly using DataAddtess() - method + * or THuiBitmapUtil - method. HUIToolkit relies on these methods. + * To create textures from the system icons you have to copy the icons to temporary + * CFbsBitmaps. Notice that duplicating the bitmap handle with CFbsBitmap::Duplicate is + * not enough. You have to make a physical copy. + * + * @param aBitmap The source bitmap from which the texture is created. + * @param aMask Pointer to the mask bitmap that is used as alpha blending + * mask for the texture. This parameter can be NULL for + * textures without alpha channel. + * @param aId The id of the texture/filename to load. The id must have + * a filename assigned by a call to DefineFileName(). + * @return Reference to the created texture. + * @leave KErrArgument The bitmap and the mask bitmap are incompatible (different size). + */ + IMPORT_C virtual CHuiTexture& CreateTextureL(CFbsBitmap& aBitmap, + const CFbsBitmap* aMask, + THuiTextureUploadFlags aFlags, + TInt id); + + /** + * Returns the file server session that should be used by the manager. + */ + RFs& FsSession() const; + + /** Returns true if the given texture is still in the load queue. */ + TBool IsInLoadQueue(const CHuiTexture * texture) const; + + /** Returns true if the given texture is still in the load queue. */ + TBool IsInLoadQueue(TInt id) const; + + /** + * Called when image loading (decoding) operation is complete. + */ + IMPORT_C void RunL(); + + /** + * Handles a leave occurring in the request completion event handler RunL(). + */ + IMPORT_C TInt RunError( TInt aError ); + + /** + * Called when a sub-image has been loaded + * (before calling @c ImageLoadingCompleteL). + * This method checks if we need to continue loading. + * @return Error code or positive integer. If positive integer, + * stop and do not continue to frame generation. + */ + TInt ImageLoadingContinue(); + + /** + * Called when an image has finished loading. Handles + * uploading of the loaded bitmap to the texture. + * @param aEntry queue entry. + */ + void ImageLoadingCompleteL(SLoadQueueEntry& aEntry); + + /** + * Processes animated frame. + * @param aEntry queue entry. + */ + void ProcessAnimatedFrameL(SLoadQueueEntry& aEntry); + + /** + * Cancel active object operation. + */ + IMPORT_C void DoCancel(); + + /** + * Starts loading next images from the load queue. If scheduling a + * queue entry fails for some reason, the entry is discarded and the + * next queue entry is processed. + */ + void StartLoading(); + + /** + * Cleans up the topmost load queue entry and removes it from the + * load queue. Deletes the decoder, but not the loaded texture entry. + */ + SLoadQueueEntry PopLoadedQueueEntry(); + + /** + * Sets up image decoding and starts to load the first entry in the load + * queue. + * @leave Standard error code if decoder initialization/resource read + * fails. + */ + void DoLoadNextL(); + + /** + * Unloads a texture having given index in the texture array (iTextures). + */ + void DoUnload(TInt index); + + /** + * Cancels the scheduled or ongoing loading of a texture. + * If the texture is found from load queue it is immediately removed from + * the queue. + * If the removed texture was being loaded at the time this method is called + * the loading is cancelled and restarted from the next unloaded texture. + * + * @param aTexture Reference to the texture of which load is cancelled. + */ + void CancelLoadingOfTexture(CHuiTexture& aTexture); + + /** + * Helper method that notifies observers of texture manager state change. + * @see iStateObservers + */ + void NotifyStateChange() const; + + /** + * Update texture flags if needed. + * @param aBitmap Bitmap. + * @param aMask Mask. + * @param aFlags Texture flags. This returns the changed value. + */ + void UpdateFlags(const CFbsBitmap& aBitmap, const CFbsBitmap* aMaskBitmap, THuiTextureUploadFlags& aFlags); + + void NotifyTextureAutoSizeObservers() const; + + /** + * Creates animation state. + * @param aGroupId group id. + * @param aImageFile image file. + * @param aFrameNumber frame number. + * @param aFrameCount frame count. + */ + CHuiTextureAnimationState* CreateAnimationStateL( + TInt aGroupId, const TDesC& aImageFile, + TInt aFrameNumber, TInt aFrameCount ); + + /** + * Finds animation state owned by aGroupId. + * @return animation state or NULL if not found. + */ + CHuiTextureAnimationState* FindAnimationState( TInt aGroupId ); + + /** + * Removes animation state. + * @param aState state to be removed. + */ + void RemoveAnimationState( CHuiTextureAnimationState* aState ); + + /** + * Finds group id by texture id. + * @param aTextureId texture id to look for. + * @param aGroupId updated to contain found group id. + * @return ETrue if succeeded, EFalse otherwise. + */ + TBool FindGroupIdByTextureId( TInt aTextureId, TInt& aGroupId ) const; + + /** + * Checks if animation state is needed. + * @param aDecoder decoder. + * @return ETrue if needed, EFalse otherwise. + */ + static TBool NeedsAnimationState( const CImageDecoder& aDecoder ); + + // For debugging purposes! Used to calculate texture memory usage + /* Calculates memory used by texturemanager for all the textures and prints as info messages + */ + void TextureMemUsage() const; + +public: + + /* Public properties. */ + + /** + * Observers that are notified of changes in the state of the manager. + * Applications may directly add and remove their own observers using + * this public property. + */ + RHuiObserverArray iStateObservers; + + /** + * Observers that are notified loaded textures of the manager. + * Applications may directly add and remove their own observers using + * this public property. + */ + RHuiObserverArray iLoadObservers; + + /** Animated textures. */ + RHuiObserverArray iAnimatedTextures; + + /** + * Observers that are notified when toolkit notices a change in texture + * auto size e.g. it is now being drawn as different size than before. + * Observers are notified possibly between every frame, they should handle + * notifications as quickly as possible. + */ + RHuiObserverArray iTextureAutoSizeObservers; + +private: + + /** Environment. */ + CHuiEnv& iEnv; + + /** Empty texture that is returned if an invalid image is specified. */ + CHuiTexture* iBlankTexture; + + /** State of the texture manager. */ + TState iState; + + /** This variable tells whether there has been a valid texture in the load queue + that we have started to load in the current texture load loop. This variable + indicates that we have started to load at least one texture during the load loop. */ + TBool iLoadQueueHadValidTexture; + + /** State of the release/restore process. */ + TReleaseState iReleaseState; + + /** Path where image files are loaded from. */ + HBufC* iImagePath; + + /** Queue of loading tasks. */ + RArray iLoadQueue; + + /** Counter for generating new font identifiers. */ + TInt iFontIdEnumerator; + + /** + * Registry of all textures within this toolkit. + * Accessed by texture ids (iId) or texture filenames (iFileName). + * Members may be NULL if a texture is not loaded. + */ + RPointerArray iTextures; + + /** Bitmap for loading asynchronously into. */ + CFbsBitmap* iBitmap; + + /** Mask bitmap for loading alpha channels. */ + CFbsBitmap* iMaskBitmap; + + /** Texture processor instance. */ + CHuiTextureProcessor* iProcessor; + + /** Open file server session for image loading. */ + RFs& iFS; + + /** + * Struct containing animated texture group item. + * Typically, each group consists of two textures and amount + * of groups is small. Thus, simple array based approach was + * selected. + */ + struct TAnimatedTextureGroupItem + { + TInt iGroupId; + TInt iTextureId; + }; + + /** + * Array of animated texture group items. + */ + RArray< TAnimatedTextureGroupItem > iAnimatedTextureGroupItems; + + /** + * Array of animation states. + * Own. + */ + RPointerArray< CHuiTextureAnimationState > iAnimations; + + /** + * Animation state that does not belong to any group. + * Own. + */ + CHuiTextureAnimationState* iAnimationWithoutGroup; + + /** Flag to optimize changed texture lookup */ + TBool iHasChangedTextures; + + /** To do texture memory usage calculation and print it as info messages */ + TBool iEnableTexMemCalculation; + + /** Flag to tell wheter texture autosizing is enabled */ + mutable TBool iTextureAutoSizingEnabled; + }; + +#endif // __HUITEXTUREMANAGER_H__