/*
* 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:   Declares the MHuiTargetBitmap interface. MHuiTargetBitmap is 
*                an interface for a writable bitmap in raw format.
*
*/



#ifndef __HUITARGETBITMAP_H__
#define __HUITARGETBITMAP_H__


#include <e32base.h>


/**
 * Interface for a bitmap that can be drawn on as a raw bitmap. CHuiBitgdiGc
 * uses this interface for accessing the target bitmap where drawing is 
 * being done.
 */
class MHuiTargetBitmap
    {
public:

    virtual ~MHuiTargetBitmap() {}

    /**
     * Determines the size of the bitmap.
     * 
     * @return  Size of the bitmap in pixels.
     */
    virtual TSize Size() const = 0;
    
    /**
     * Determines the pixel format of the bitmap.
     *
     * @return  Format of the bitmap as a TDisplayMode.
     *
     * @see TDisplayMode in the platform documentation.
     */
    virtual TDisplayMode DisplayMode() const = 0;

    /**
     * Locks the heap so that the memory buffer of the bitmap can be 
     * accessed directly. Prevents heap compression done by other threads.
     * The heap must be unlocked with UnlockHeap() after the buffer
     * processing has been completed.
     *
     * @see CFbsBitmap::LockHeap()
     */
    virtual void LockHeap() = 0;

    /**
     * Unlocks the heap. Must be called after the heap has been locked 
     * and operated on.
     */    
    virtual void UnlockHeap() = 0;

    /** 
     * Provides access to the memory buffer of the bitmap.
     *
     * @return  Pointer to the beginning of the pixel data.
     *
     * @see LockHeap()
     * @see UnlockHeap()
     */     
    virtual TAny* DataAddress() = 0;

    /** 
     * Sets the clipping rectangle for the bitmap. All drawing operations
     * (FillRect(), BitBlt(), BitBltMasked()) are confined into this
     * rectangle when drawn.
     *
     * @param aRect  Clipping rectangle.
     */
    virtual void SetClippingRect(const TRect& aRect) = 0;
    
    /** 
     * Sets the clipping region for the bitmap. All drawing operations
     * (FillRect(), BitBlt(), BitBltMasked()) are confined into this
     * region when drawn.
     *
     * @param aRegion  Region containing clipping rectangles.
     */
    virtual void SetClippingRegion(const TRegion& aRegion) = 0;
    
    /** 
     * Draws a solid-colored rectangle. Affected by the clipping rectangle.
     *
     * @param aRect  Rectangle to fill with a solid color.
     * @param aColor  RGBA color to use for filling. Note that the alpha
     *                component of the TRgb is also valid.
     */
    virtual void FillRect(const TRect& aRect, const TRgb& aColor) = 0;
    
    /** 
     * Draws a bitmap. Affected by the clipping rectangle. Analogous to
     * the corresponding CFbsBitGc::BitBlt() method.
     *
     * @param aPoint  Position where to draw.
     * @param aBitmap  Bitmap to draw.
     * @param aSourceRect  Rectangle within the source bitmap where to draw from.
     */
    virtual void BitBlt(const TPoint& aPoint, const CFbsBitmap *aBitmap, const TRect &aSourceRect) = 0;
    
    /** 
     * Draws a masked bitmap. Affected by the clipping rectangle.
     * Analogous to the corresponding CFbsBitGc::BitBltMasked() method.
     *
     * @param aPoint  Position where to draw.
     * @param aBitmap  Bitmap to draw.
     * @param aSourceRect  Rectangle within the source bitmap where to draw from.
     * @param aMaskBitmap  Mask bitmap.
     * @param aInvertMask  ETrue if the mask should be inverted.
     */
    virtual void BitBltMasked(const TPoint &aPoint, const CFbsBitmap *aBitmap, const TRect &aSourceRect, const CFbsBitmap *aMaskBitmap, TBool aInvertMask) = 0;
    
    /**
     * Returns pointer to the bitmap. If the class do not have CFbsBitmap this methdod returns NULL.
     * 
     * @return  Pointer to the bitmap.
     */
    virtual CFbsBitmap* FbsBitmap() = 0;
    
    /**
     * Returns the BITGDI graphics context that is used for drawing in
     * the back buffer.
     * 
     * Writing a real implementation for this might not be needed if the renderer
     * does not support symbian graphics context.
     *
     * @return  BITGDI graphics context.
     */
    virtual CFbsBitGc* Gc() = 0;
    };


#endif // __HUITARGETBITMAP_H__