/*

* 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 <e32base.h>

#include <gdi.h>

#include <imageconversion.h>

#include <uiacceltk/HuiObserverArray.h>

#include <uiacceltk/HuiTimeObserver.h>

#include <uiacceltk/HuiTexture.h>

#include <uiacceltk/HuiBitmapProvider.h>

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

     *