/*
* Copyright (c)  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:   Declares CAlfTexture texture class.
*
*/



#ifndef C_ALFTEXTURE_H
#define C_ALFTEXTURE_H

#include <coemain.h>
#include <alf/alftextureautosizeparams.h>

class CAlfEnv;
class MAlfBitmapProvider;
class CAlfTextureManager;

/** Flags for texture Uploading. */
enum TAlfTextureFlags
    {
    /** No special actions/behavior needed. */
    EAlfTextureFlagDefault = 0,

    /**
     * @deprecated This is default functionality
     */
    EAlfTextureFlagRetainResolution = 1,

    /**
     * @deprecated 
     * Automatically generates a shadow for the texture.
     */
    EAlfTextureFlagGenerateShadow = 2,

    /**
     * Use to retain the color depth of the
     * ((up)loaded) image as well as possible. Otherwise
     * the toolkit may reduce the color depth of the texture
     * to conserve memory.
     */
    EAlfTextureFlagRetainColorDepth = 4,

    /**
     * If this flag has been set, texturemanager automatically releases and 
     * restores texture after system skin changes so that it has the
     * updated content. 
     */
    EAlfTextureFlagSkinContent = 8,

    /**
     * Set if it is not necessary to retain the full resolution of the bitmap. 
     * Default functionality is try to match texture resolution
     * with bitmap resolution).
     * This may save some memory with hardware acceleration, but image quality changes to worse
     */
    EAlfTextureFlagDoNotRetainResolution = 0x10,

    /**
     * Lets texture manager report preferred texture size via MAlfTexturePreferredSizeObserver 
     * interface and automatically re-request upload from the bitmap provider 
     * (which should be aware of the new size).
     * 
     * Preferred size is determined by the actual usage of the texture and the size(s) that
     * texture appears on the display.
     *   
     * Automatically determined preferred size may not be always the most optimal and 
     * performance may be degraded due multiple (re)uploads if texture usage changes frequently.
     * 
     * Also it is not quaranteed that texture manager is able to report preferred size in 
     * all possible situations.
     */
    EAlfTextureFlagAutoSize = 0x40,
    
    /*
     * If defined the texture manager will not try to check whether or not the texture has
     * multiple frames. This can be used load animated texture's first frame as a simple image
     * or to reduce the loading time of a texture (e.g. in case of large size images) if the
     * user knows that the image does not have any frames. 
     */
    EAlfTextureFlagLoadAnimAsImage = 0x80
    };


    
/**
 * CAlfTexture is the client side class for all texture objects.
 *
 * A CAlfTexture always represents one or more fully loaded (OpenGL ES) texture
 * objects. When drawing something, TAlfImages are used for determining the
 * area of  the texture to draw. However, different segments may utilize
 * textures in different resolutions.
 * Usage:
 * @code
 *  //load texture from Texture Manager
 *   CAlfTexture* tex = iTextureMgr->LoadTexture(imageFileName1,
 * 								 EAlfTextureFlagDefault,
 * 								 AUTO_GENERATED_TEXTURE_ID);
 *  
 *  //Use texture to create Image instance
 *  TAlfImage image( *tex );
 * 
 *  //For textures, which should never be released, set priority to be 0
 *  //see CAlfEnv::Release()
 *  tex->SetPriority(0);
 *  
 *  //cleanup
 *   delete env; //  delete texturemanager and all the textures.
 * 
 * @endcode
 * @see CAlfTextureManager
 * @see TAlfImage
 * @lib alfclient.dll
 * @since S60 v3.2
 */

NONSHARABLE_CLASS( CAlfTexture ): public CBase
    {
public:

    /* Constructors and destructor. */

    /**
     * Destructor.
     */
    IMPORT_C virtual ~CAlfTexture();

    /**
     * Static factory method. Creates a texture appropriate for the current
     * renderer.
     */
    static CAlfTexture* NewL(CAlfEnv& aEnv, TUid aManagerUid, 
        TInt aId = 0, TInt aBitmapHandle = 0, TInt aMaskHandle = 0, 
        TAlfTextureFlags aFlags = EAlfTextureFlagDefault, 
        TBool aAnimated = EFalse );

    /**
     * Static factory method. Creates a texture appropriate for the current
     * renderer.
     */
    static CAlfTexture* NewLC(CAlfEnv& aEnv, TUid aManagerUid, 
        TInt aId = 0, TInt aBitmapHandle = 0, TInt aMaskHandle = 0, 
        TAlfTextureFlags aFlags = EAlfTextureFlagDefault,
        TBool aAnimated = EFalse);

    /**
     * Sets server side handle.
     * @param aHandle Serverside handle
     */
    void SetServerHandle(TInt aHandle);

    /**
     * Sets bitmap provider.
     * @param bitmap provider.
     */
    void SetBitmapProvider(MAlfBitmapProvider* aBitmapProvider);
    
    /**
     * Gets bitmap provider.
     * @return bitmap provider.
     */
    MAlfBitmapProvider* BitmapProvider() const;
    
    /**
     * Sets filename.
     * @param file name.
     */    
    void SetFileNameL(const TFileName & aFileName);

    /**
     * Sets max texture size.
     * @param max texture size.
     */    
    void SetMaxTextureSize(TSize aTextureMaxSize);    

    /**
     * Gets texture flags.
     * @return Texture flags.
     */    
    TAlfTextureFlags Flags() const;

    /**
     * Sets texture flags.
     * @param Texture flags.
     */    
    void SetFlags(TAlfTextureFlags aFlags);
    
    /**
     * Sets texture logical size.
     * @param logical texture size.
     */    
    void SetSize(TSize aSize);        
    
    /** @beginAPI */

    /**
     * Gets texture id.
     * @return Texture id.
     */    
    IMPORT_C TInt Id() const;
        
    /**
     * Gets server side handle.
     * @return Serverside handle
     */
    IMPORT_C TInt ServerHandle() const;    

    /**
     * Gets filename.
     * @param file name.
     */    
    IMPORT_C HBufC* FileName() const;
    
    /**
     * Returns ETrue if the texture has content - existing texture
     * data. This indicates that the texture has been (up)loaded 
     * and is ready to be used.
     */
    IMPORT_C TBool HasContent() const;

    /**
     * Gets max texture size.
     * @return max texture size.
     */    
    IMPORT_C TSize MaxTextureSize();    

    /**
     * Gets texture logical size.
     * @return logical texture size.
     */    
    IMPORT_C TSize Size() const;    

    /**
     * Returns ETrue if the texture is animated,
     * EFalse otherwise
     * @return the animation status of the texture.
     */    
    IMPORT_C TBool IsAnimated() const;

    /**
     * Starts the animation if the texture is animated.
     * Does nothing if the texture is not animated, or
     * the animation has already been started
     */    
    IMPORT_C void StartAnimation();

    /**
     * Stops the animation if the texture is animated.
     * Does nothing if the texture is not animated, or
     * the animation has already been stopped
     */    
    IMPORT_C void StopAnimation();
    
    /**
     * Sets the texture priority. The priority is used when releasing/restoring
     * textures.
     *
     * @param aPriority 0 = never release
     *                  See TAlfTexturePriority from
     *                  alftexturemanager.h
     *                  By default != 0
     */ 
    IMPORT_C void SetPriority( TInt aPriority );
    
    /**
     * Returns the priority of the texture
     *
     * @return The priority
     *
     * @see SetPriority()
     */
    IMPORT_C TInt Priority() const;

    /**
     * Sets parameters to be used when automatically calculating preferred size.
     * @param aParams New parameters.
     */
    IMPORT_C void SetAutoSizeParams(const TAlfTextureAutoSizeParams& aParams);
    
    /**
     * Gets parameters to be used when automatically calculating preferred size.
     * @return Currently used parameters.
     */
    IMPORT_C TAlfTextureAutoSizeParams AutoSizeParams() const;

    /**
    * Enables texture reference counting. If enabled,the user
    * does not need to delete or unload the texture, but can leave 
    * the responsibility for the toolkit. Needs to be enabled per texture. Allows
    * keeping important textures in memory if disabled. Even if
    * the refcounting is disabled, internally bookkeeping is still
    * made in order to correctly free unused textures when 
    * refcounting is enabled again.
    *
    * The whole feature is disabled by default and needs to be enabled
    * when necessary.
    *
    * Action that will be taken when ref count reaches zero 
    * can be defined using SetRefCountingAction method, by default
    * it is ERefCountingActionUnload.
    *
    * @param aEnable if ETrue, reference counting is enabled.
    */
    IMPORT_C void EnableRefCounting(TBool aEnable=ETrue);
    
    /**
    * Queries the reference counting state
    *
    * @return ETrue if texture is refcounted, EFalse otherwise.
    */
    IMPORT_C TBool RefCountingEnabled();

    
    enum TAlfTextureRefCountingAction
        {
        ERefCountingActionDelete,
        ERefCountingActionUnload
        };

    /** 
    * Sets action that is performed when reference counting reaches zero.
    * @param aAction Possible values are ERefCountingActionDelete and
    * ERefCountingActionUnload but in the future there may be new ones.
    *   
    */
    IMPORT_C void SetRefCountingAction(TInt aAction);

    /**
    * Gets action that is performed when reference counting reaches zero.
    * @return Possible values are ERefCountingActionDelete and
    * ERefCountingActionUnload but in the future there may be new ones.
    */
    IMPORT_C TInt RefCountingAction() const;

    /** @endAPI */

    enum TAlfTextureReleaseFlags
        {
        EReleaseNone = 0x0,
        EReleaseFromEnv = 0x1,
        EReleaseFromRefCounting = 0x2,
        EReleaseFromUnload = 0x4           
        };
    /**
     * Returns the flags which tell if texture has been released.
     * @return Release flags
     */
    TInt ReleaseFlags() const;
    
    /**
     * Sets the flags which tell if texture has been released.
     * @param aReleased EReleaseNone when it is restored, others when texture gets released.
     */
    void SetReleaseFlags(TInt aReleaseFlags); 

    /**
     * Gets the texturemanager instance which manages this texture.
     * @return Texture manager for this texture.
     */
     CAlfTextureManager* TextureManager();
        
protected:

    /* Constructors. */

    /**
     * Constructor. Creates a new texture object with no texture maps.
     */
    CAlfTexture();

    /**
     * Second-phase constructor.
     */
    void ConstructL(CAlfEnv& aEnv, TUid aManagerUid, TInt aId, TInt aBitmapHandle, TInt aMaskHandle, TAlfTextureFlags aFlags, TBool aAnimated);

private:

	/** Private data */
    struct TPrivateData;    
    TPrivateData* iData;
    };

#endif  // C_ALFTEXTURE_H