/*

* 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 interface for HUITK render surfaces. The rendering 

*                surface is a destination where rendered graphics will 

*                ultimately end up.

*

*/

#ifndef __HUIRENDERSURFACE_H__

#define __HUIRENDERSURFACE_H__

#include <e32base.h>

/* Forward declarations. */

class MHuiSegmentedTexture;

class MHuiTargetBitmap;

class CFbsBitGc;

/**

 * The render surface is a destination where rendered graphics will ultimately

 * end up. This may be, e.g., the display frame buffer or a bitmap in memory.

 */

class MHuiRenderSurface

    {

public:

	/** Render surface flags */

	enum TFlags

    	{

    	EFlagNone =                            0x0,

		/** Surface uses double buffering. */    	

		EFlagUseDoubleBuffering =              0x1,

		/** Surface uses dirty rects. */    	

    	EFlagUseDirtyRects =                   0x2,

    	/** Surface uses transformed clipping rects. */

    	EFlagUsetransformedClippingRects =     0x4,

    	/** Surface uses Symbian graphics context rects. */

    	EFlagUseSymbianGC =                    0x8

    	};

public:

    /**

     * Virtual destructor.

     */

    IMPORT_C virtual ~MHuiRenderSurface();

    /**

     * Returns the flags of the render surface.

     * @return Flags.

     */

    virtual TUint Flags() const = 0;

    /**

     * Determines the location of the rendering surface on the screen.

     *

     * @param aOrigin  Top left corner coordinates returned here, in absolute screen

     *                 coordinates. The top left corner of the screen is (0, 0).

     *

     * @return  If location successfully determined, returns <code>ETrue</code>.

     *          If the surface is an off-screen surface, returns <code>EFalse</code>.

     */

    virtual TBool GetScreenOrigin(TPoint& aOrigin) const = 0;

    /**

     * Determines the size of the surface.

     *

     * @return  Size of the surface in pixels.

     */

    virtual TSize Size() const = 0;

    /**

     * Changes the size of the surface.

     *

     * @param aSize  Size of surface in pixels.

     */

    virtual void SetSizeL(const TSize& aSize) = 0;

    /**

     * Makes this the current rendering surface for any drawing operations.

     * Call CHuiStatic::SetCurrentRenderSurface().

     */

    virtual void MakeCurrent() = 0;

    /**

     * Swaps the back buffer to the front.

     */

    virtual void SwapBuffers() = 0;

    /**

     * Binds a texture to the surface to be used during subsequent drawing

     * operations.

     *

     * In practice, the texture is bound to the rendering context

     * of this render surface. When something is drawn in the surface's 

     * rendering context, the texture specified here is used.

     *

     * @param aTextureUnit Texture unit number to bind the texture to. Binding

     * to different units enables multitexturing, but using multiple texture

     * units (multitexturing) may not be supported.

     * @param aTexture The texture to be bound.

     * @param activeTextureSegment Index of the texture segment to be bound.

     * operations. 

     */

    virtual void BindTexture(TInt aTextureUnit,

                             const MHuiSegmentedTexture& aTexture,

                             TInt activeTextureSegment) = 0;

    /**

     * Handles change in surface visibility. This method is called if surface is either

     * hidden or shown.

     *

     * @param aIsVisible ETrue if surface becomes visible. EFalse if surface is hidden.

     */

    virtual void HandleVisibilityEvent(TBool aIsVisible) = 0;

    /**

    * Temporarily release the resources of this rendering surface. You

    * can call this method to free up resources related to the rendering surface,

    * for example when the display goes to background (ie. render surface is not needed).

    * @see RestoreL() 

    */

    virtual void Release() = 0;

    /**

    * Recreate any released resources of this rendering surface. You

    * can call this method to recreate resources related to rendering surface,

    * for example, when the display comes back to foreground (ie. becomes visible).

    * @see Release() 

    */

    virtual void RestoreL() = 0;

    /**

    * Handles change in the intended usage of display. Most render surfaces do not

    * have any special functionality for different display usage scenarios.

    */

    virtual void HandleDisplayUsageChangeL() = 0;

    /**

    * Sets the dirty region i.e. the rectangular area that needs to be updated.

    * 

    * Writing a real implementation for this might not be needed if the renderer

    * does not support dirty region handling.

    * 

    * @param aRect The rectangular area that is dirty

    */

    virtual void SetDirtyRect(const TRect& aRect) = 0;

    /**

     * Returns the back buffer bitmap.

     * 

     * Writing a real implementation for this might not be needed if the renderer

     * does not support symbian graphics context.

     *

     * @return  Back buffer bitmap.

     */

    virtual MHuiTargetBitmap* BackBuffer() = 0;

    /**

     * 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

     */

    virtual void RenderSurfaceExtension(const TUid& aExtensionUid, TAny** aExtensionParams) = 0;

    };

#endif