/*

* Copyright (c) 2006 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:   Loads textures.

*

*/

#ifndef C_ALFTEXTUREMANAGER_H

#define C_ALFTEXTUREMANAGER_H

#include <e32base.h>

#include <e32cmn.h>

#include <alf/alftexture.h>

/* Forward declarations */

class CAlfEnv;

class CAlfTextureProcessor;

class CAlfTextureManager;

class MAlfBitmapProvider;

struct TLoadQueueEntry;

struct TTextureEntry;

/**

 * Special texture id, can be used to let CAlfTextureManager to assign

 * ids for textures when those are created or loaded.

 * 

 * @see CAlfTextureManager

 */

const TInt KAlfAutoGeneratedTextureId = 0;

/**

 * Texture release level. 

 *

 * @see Release(), RestoreL()

 * @see CAlfTexture::SetPriority()

 */

enum TAlfTexturePriority

    {

    /** Texture is released only on destruction */

    EAlfTexturePriorityHighest = 0,

    /** Texture is released on the background only if memory is running out */ 

    EAlfTexturePriorityHigh = 1000,

    /** Texture is released when application goes into background */ 

    EAlfTexturePriorityNormal= 2000, // = default

    /** Texture is released on the foreground if memory is running out */

    EAlfTexturePriorityLow= 3000

    };

/**

 * Provides callback methods for getting notifications when texture manager

 * finishes asynchronous texture loads. An observer of a CAlfTextureManager.

 *

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

 */

class MAlfTextureLoadingCompletedObserver

    {

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(CAlfTexture& aTexture,

                                         TInt aTextureId,

                                         TInt aErrorCode) = 0;

    };

/**

 * Provides callback methods for getting notifications of texture manager state

 * changes. An observer of a CAlfTextureManager.

 *

 * @see CAlfTextureManager

 */

class MAlfTextureManagerStateChangedObserver

    {

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 CAlfTextureManager& aManager) = 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.

 *

 */

class MAlfTextureAutoSizeObserver

    {

public:

    /**

     * Called to notify the observer that the preferred size of some texture

     * has been changed.

     *

     * @param aChangedTexture  Texture which preferred size has changed.

     * @param aPreferredSize 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 CAlfTexture& aChangedTexture, TSize aPreferredSize) = 0;

    };

/**

 * CAlfTextureManager is responsible for managing the texture objects used by

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

 * CAlfTexture 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.

 *

 * CAlfTextureManager is owned by CAlfEnv, and should be accessed via a

 * CAlfEnv instance. You should never construct your own texturemanagers.

 * 

 * Usage:

 * @code

 * 

 *  //Get TextureManager

 * CAlfTextureManager* textureMgr =  &iEnv->TextureManager();

 * 

 * //Set texturemanager image path

 * textureMgr->setImagePath(_L( "C:\\data\\Images\\Pictures\\" ) );

 * 

 * //Load texture

 * CAlfTexture* texture = textureMgr->LoadTextureL( _L("1.bmp"), EAlfTextureFlagDefault, 10 );

 * 

 * //Unload texture. Here, texture instance itself is not destroyed, only its 

 * //contents are emptied.

 * textureMgr->UnloadTexture(10);

 * 

 *  //Update texturecontent without changing the texture istance

 *  textureMgr->updateTextureFromFile( 10, _L( "2.jpg" ) );

 * 

 *  //Create texture 

 *  //BitmapProviderTest - implements MalfBitMapProvider interface

 *  //Default implementation of this interface, provided by toolkit is

 *  //CAlfImageLoaderUtil

 *  BitmapProviderTest* callback = new (ELeave) BitmapProviderTest();

 *  textureMgr->CreateTextureL( 42, *callback, EAlfTextureFlagDefault );

 * 

 *  @endcode

 *  @lib alfclient.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CAlfTextureManager ): public CActive

    {

public:

    /**

     * States of a CAlfTextureManager 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. */

    /**

     * Static factory method. Creates a texture appropriate for the current

     * renderer.

     */

    static CAlfTextureManager* NewL(CAlfEnv& aEnv, TUid aUid);

    /**

     * Static factory method. Creates a texture appropriate for the current

     * renderer.

     */

    static CAlfTextureManager* NewLC(CAlfEnv& aEnv, TUid aUid);

    /**

     * Destructor.

     */

    virtual ~CAlfTextureManager();

    /* Methods. */

    /** @beginAPI */

    /**

     * Determines the environment the manager belongs to.

     */

	IMPORT_C CAlfEnv& Env();

    /**

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

     * texture if the id was not found.

     */

    IMPORT_C const CAlfTexture* Texture(TInt aId) const;

    /**

     * Returns a texture associated with the given id.

     * Will leave if no associated texture exists. 

     *

     * @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 CAlfTexture* 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 CAlfTexture& 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 CAlfTexture& 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

     * MAlfTextureLoadingCompletedObserver 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.

     *                          KAlfAutoGeneratedTextureId can be used to let 

     *                          texture manager automatically decide 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 MAlfTextureLoadingCompletedObserver::TextureLoadingCompleted()

     * @see IsLoaded()

     */

    IMPORT_C CAlfTexture& LoadTextureL(const TDesC& aImageFileName,

                                       TAlfTextureFlags aFlags,

                                       TInt aId);

   /**

     * 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

     * MAlfTextureLoadingCompletedObserver 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().

     *                        

     * @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 MAlfTextureLoadingCompletedObserver::TextureLoadingCompleted()

     * @see IsLoaded()

     */

    IMPORT_C CAlfTexture& LoadTextureL(const TInt aId,

                                       TSize aTextureMaxSize = TSize(0,0),

                                       TAlfTextureFlags aFlags = EAlfTextureFlagDefault);

    /**

     * 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

     * MAlfTextureLoadingCompletedObserver 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.

     *                              KAlfAutoGeneratedTextureId can be used to let 

     *                              texture manager automatically decide 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 MAlfTextureLoadingCompletedObserver::TextureLoadingCompleted()

     * @see IsLoaded()

     */

    IMPORT_C CAlfTexture& LoadTextureL(const TDesC& aImageName,

                                       TSize aTextureMaxSize,

                                       TAlfTextureFlags aFlags,

                                       TInt aId);

    /**

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

     *

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

     *

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

     *                              KAlfAutoGeneratedTextureId to let texture manager

     *                              automatically decide id.

     *                              

     * @return Reference to the created texture.

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

     */

    IMPORT_C CAlfTexture& CreateTextureL(TInt aId,

                                         MAlfBitmapProvider* aBitmapProvider,

                                         TAlfTextureFlags aFlags);

    /**

     * 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);

    /**

     * Unloads a texture from memory.

     *

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

     * 

     */

    IMPORT_C void UnloadTexture(TInt aId);

    /**

     * Updates texture content without changing the texture address.

     *

     * this is an asynchronous method which is loaded and filled in 

     * the background. Register an MAlfTextureLoadingCompletedObserver 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().

     *

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

     *

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

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

     *                          not given, will check if a filename for the id has

     *                          been defined and load a texture using that resource

     *                          location, if possible.

     * @leave 					If this method leaves the texture is not valid any more.

     *

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

     * absolute image filenames.

     * @see iLoadObservers

     * @see MAlfTextureLoadingCompletedObserver::TextureLoadingCompleted()

     * @see IsLoaded()

     */

    IMPORT_C void UpdateTextureFromFileL(TInt aId, const TDesC* aFileName = NULL);

    /**

     * Updates texture content without changing the texture address.

     *

     * @param aId               Id for the texture. 

     * @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. If this is not given 

     *                          the current provider is called instead.

     * @leave 					If this method leaves the texture is not valid any more.

     */

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

    /**

     * 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);

    /**

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

     * if necessary.

     */

    IMPORT_C void PrependImagePath(TDes& aFileName);

     /**

     * Adds texture loading observer

     *

     * @param aObserver observer to be added to array

     * @leave any system wide error code

     */

    IMPORT_C void AddLoadObserverL(MAlfTextureLoadingCompletedObserver* aObserver);

     /**

     * Removes texture loading observer, this must be done at latest when observer is being deleted

     *

     * @param aObserver observer to be removed from array

     */

    IMPORT_C void RemoveLoadObserver(MAlfTextureLoadingCompletedObserver* aObserver);