/*******************************************************************************

 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     Nokia Corporation - initial API and implementation

 *******************************************************************************/

#ifndef GRAPHICS_H

#define GRAPHICS_H

#include <QImage>

#include <QPixmap>

#ifdef __SYMBIAN32__

#include <EGL/egl.h>

#endif

class QFont;

class QByteArray;

namespace Java { namespace GFX {

class Buffer;

class GraphicsContext;

class GraphicsFactory;

class Image;

class ImageLoader;

class ImageDataWrapper;

class PaletteDataWrapper;

class WindowSurface;

/**

 * gfx errors

 */

enum TGfxError

{

    EGfxErrorNone                   = 0,

    EGfxErrorNoMemory               = 1,

    EGfxErrorIO                     = 2,

    EGfxErrorIllegalArgument        = 4,

    EGfxErrorIllegalState           = 5,

    EGfxErrorArrayIndexOutOfBounds  = 6

};

/**

 * Rendering target types

 */

enum TTargetType

{

    ETypeNone           =  0,

    ETypeWidget         =  1,

    ETypeImage          =  2,

    ETypeBuffer         =  3,

    ETypeWindowSurface  =  4

};

/**

 * Image pixel formats

 */

enum TImageFormat

{

    EFormatNone                  = 0,

    EFormatRGB32                 = 1,

    EFormatARGB32                = 2,

    EFormatARGB32Premultiplied   = 3,

    EFormatRGB16                 = 4,

    EFormatRGB555                = 5,

    EFormatRGB444                = 6,

    EFormatARGB4444Premultiplied = 7,

    EFormatMONO                  = 8

};

/**

 * Native image types

 */

enum TImageType

{

    ENone    = -1,  // Type not defined

    EImage   = 0,   // QImage

    EPixmap  = 1    // QPixmap

};

/**

 * Image transforms

 */

enum TTransform

{

    ETransNone              = 100,

    ETransRot90             = 101,

    ETransRot180            = 102,

    ETransRot270            = 103,

    ETransMirror            = 104,

    ETransMirrorRot90       = 105,

    ETransMirrorRot180      = 106,

    ETransMirrorRot270      = 107,

    ETransFlipHorizontal    = 108,

    ETransFlipVertical      = 109

};

/**

 * Supported reflections.

 */

enum TReflection

{

    /**

     * Identity transformation.

     */

    EReflectNone = 0,

    /**

     * Vertical reflection (in horizontal line through region center).

     */

    EReflectVert = 1,

    /**

     * Horizontal reflection (in vertical line through region center).

     */

    EReflectHorz = 2,

    /**

     * Reflection in diagonal line from top left corner to bottom right corner

     */

    EReflectDiag = 4

}; 

/**

 * Supported transformation are all combinations of the supported reflections.

 * Note that two reflections make a rotation, so that this list includes pure

 * rotations by multiples of 90 degrees.

 */

enum TTransformType

{

    ETransNoneType          = EReflectNone,

    ETransMirrorRot180Type  = EReflectVert,

    ETransMirrorType        = EReflectHorz,

    ETransRot180Type        = EReflectVert | EReflectHorz,

    ETransMirrorRot270Type  = EReflectDiag,

    ETransRot90Type         = EReflectVert | EReflectDiag,

    ETransRot270Type        = EReflectHorz | EReflectDiag,

    ETransMirrorRot90Type   = EReflectVert | EReflectHorz|EReflectDiag

};

/**

 * Blending modes

 */

enum TBlendingMode

{

    ESrc        = 10,

    ESrcOver    = 11,

    EXor        = 12

};

/**

 * Stroke styles

 */

enum TStrokeStyle

{

    EStrokeNo           = 0,

    EStrokeSolid        = 1,

    EStrokeDot          = 2,

    EStrokeDash         = 3,

    EStrokeDashDot      = 4,

    EStrokeDashDotDot   = 5

};

/**

 * Indices for font metrics data

 */

enum TFontMetricsDataIndex

{

    EFmAscent           = 0,

    EFmAverageCharWidth = 1,

    EFmDescent          = 2,

    EFmHeight           = 3,

    EFmLeading          = 4

};

/**

 * Common indexes for rectangle data arrays

 */

enum TRectIndex

{

    ERectX      = 0,

    ERectY      = 1,

    ERectWidth  = 2,

    ERectHeight = 3

};

/**

 * Window surface types

 *

 */

enum WindowSurfaceType

{

    WsTypeUnknown       = 0x0000,  // unknonwn or uninitialized type

    WsTypeQtImage       = 0x0001,  // QImage

    WsTypeQtPixmap      = 0x0002,  // QPixmap

    WsTypeSymbianBitmap = 0x0004,  // CFbsBitmap

    WsTypeEglSurface    = 0x0016   // EGL surface

};

/**

 * Interface to Buffer.

 */

class Buffer

{

public:

    /**

     * Destructor

     * Use dispose instead of delete

     */

    virtual ~Buffer() {}

    /**

     * Disposes this instance of buffer

     */

    virtual void dispose() = 0;

    /**

     * Retrieves bindable target of Buffer, i.e. QPaintDevice.

     * @return bindable

     */

    virtual QPaintDevice* getBindable() = 0;

    /**

     * Gets the invalid rect, i.e. rectangle containing area where

     * draw operations have affected.

     *

     * Values are stored in aRect array as follows:

     * <ul>

     * <li>aRect[ERectX] - the x coordinate of rect</li>

     * <li>aRect[ERectY] - the y coordinate of rect</li>

     * <li>aRect[ERectWidth] - the width of rect</li>

     * <li>aRect[ERectHeight] - the height of rect</li>

     * </ul>

     *

     * @param aRect Int array where rect data is populated

     */

    virtual void getInvalidRect(int aRect[]) = 0;

    /**

     * Retrieves wrapped buffer object

     * @return QPicture

     */

    virtual QPicture* getPicture() = 0;

};

/**

 * WindowSurface class wraps actual rendering surface for sharing it between java grapchics

 * external renderers like m3g and m2g. It also perfroms needed blitting activations in case

 * external renderer does not directly support current surface type.

 *

 * Example of using WindowSurface

 * <code>

 * // Set supported surface types of external renderer

 * int caps = Java::GXF:SwImage | Java::GFX::PBuffer;

 * // get surface

 * QPaintDevice* surface = WindowSurface.bind(caps);

 * // cast device to actual type

 * switch (WindowSurface.getType)

 * {

 *      case SwImage:

 *           surface = static_cast<QImage*>(surface);

 *           break;

 *       case PBuffer:

 *           surface = static_cast<QGLPixelBuffer*>(surface);

 *

 * </code>

 *

 * After using surface WindowSurface.release() must be called

 */

class WindowSurface

{

public:

    /**

     * Destructor

     * @note use dispose method instead of delete

     */

    virtual ~WindowSurface() {}

    /**

     * Binds this surface for rendering outside GraphicsContext, e.g. rendering by m3g.

     * When rendering has been finished by external renderer release() must be called on this instance.

     *

     * Surface type given to caller depends on the graphics hardware configuration, the

     * graphics system used by QPainter and on the capabilites given on the aCapability parameter.

     * Note that the minimun requirement is that SwImage (QImage) is supported.

     *

     * If caller is for instance capable for rendering on VgImage and QImage it should set value for

     * aCapabilites as shown below. If in this case QPainter is operating in OpenVG (Hw) the returned surface is VgImage,

     * if it is on turn operating on software based raster paintengine returned surface is SwImage (QImage).

     *

     * <code>

     * int caps = Java::GFX::SwImage|Java::GFX::VgImage;

     * </code>

     *

     * IMPORTANT: The caller must not delete QPaintDevice pointer returned from bind -method

     *

     * @param aCapabilies The hints of supported surface types, one or combination of surfacetypes

     *                     defined in WindowSurfaceTypes, Default SwImage

     * @return QPaintDevice to be used as rendering target

     */

    virtual void bind(int aCapabilies = WsTypeQtImage) = 0;

    /**

     * Prepares this window surface for painting. Must be called before painting starts.

     * Should be called by UI toolkits, not by external renderers, like m3g.

     * @param aX The x-coordinate of the paint area

     * @param aY The y-coordinate of the paint area

     * @param aWidth The width of the paint area

     * @param aHeight The height of the paint area

     */

    virtual void beginPaint(int aX, int aY, int aWidth, int aHeight) = 0;

    /**

     * Ends painting intiated by call to beginPaint. Must be when painting has ended.

     * Should be called by UI toolkits, not by external renderers, like m3g.

     */

    virtual void endPaint() = 0;

    /**

     * Flushes the contents of this window surface to the display. Should be called by 

     * UI toolkits.

     */

    virtual void flush() = 0;

    /**

     * Gets the type of the windowSurface

     * @return One of types defined in WindowSurfaceType

     */

    virtual int getType() = 0;

    /**

     * Getter for the QPaintDevice of contained target. Primarily to be used 

     * when drawing to window surface target with QPainter

     * @return The paintDevice of the target

     */

    virtual QPaintDevice* getDevice() = 0;

#ifdef __SYMBIAN32__

    /**

     * Getter for egl surface.

     * @return The egl draw surface id, or EGL_NO_SURFACE if the target is not egl type

     */

    virtual EGLSurface getEglSurface() = 0;

    /**

     * Getter for current the API that is currently bound to EGL. 

     * In order to get valid return value the type of this window surface 

     * must be WsTypeEglSurface.

     * @return The API that's bound to EGL

     */

    virtual EGLenum getEglApi() = 0;

#endif

    /**

     * Getter for QImage

     * @return The target QImage, or NULL it is not the true type of target

     */

    virtual QImage* getQtImage() = 0;

    /**

     * Refreshes the window surface data. Refresh needs to be called

     * e.g. when Qt has changed its window surface when switching from sw to hw

     * rendering.

     */

    virtual void refresh() = 0;

    /**

     * Releases external renderer from this instance.

     * Calling this method automatically blits all pixels rendered on the surface to

     * actual target, i.e. to widget or offscreen image.

     */

    virtual void release() = 0;

    /**

     * Disposes this instance of windowsurface

     */

    virtual void dispose() = 0;

    // Symbian specific methods

#ifdef __SYMBIAN32__    

    /**

     * Getter for symbian bitmap.

     * @return The symbian bitmap if it is available, otherwise NULL

     */

    virtual CFbsBitmap* getSymbianBitmap() = 0;

#endif    

    /**

     * Switches to software rendering if the window goes invisible

     * and back to hardware rendering when becoming visible.

     */

    virtual void handleSymbianWindowVisibilityChange(bool aVisible) = 0;

};

/**

 * Interface to graphics context

 */

class GraphicsContext

{

public:

    /**

     * Destructor

     * @note use dispose method instead of delete

     */

    virtual ~GraphicsContext() {}

    /**

     * Gets window surface for currrently bound target

     */

    virtual WindowSurface* getWindowSurface() = 0;

    /**

     * Disposes graphics context, i.e. frees all resources.

     */

    virtual void dispose() = 0;

    /**

     * Binds graphics context to given rendering target.

     * @param aTarget The rendering target handle.

     * @param aType The type of given rendering target.

     * @param aBufferFlushTargetHandle The actual target where the buffer will be flushed to

     * @exception GfxException

     */

    virtual void bindTarget(int aTarget, TTargetType aType, const int& aBufferFlushTargetHandle) = 0;

    /**

     * Renders draw commands stored in given buffer to currently bound target.

     * @param aBuffer The rendering target handle.

     * @exception GfxException

     */

    virtual void render(Buffer* aBuffer) = 0;

    /**

     * Releases current rendering target and frees resources.

     * After calling release target no graphics operations are allowed

     * as there's no target to render to. Note, there is no checking for

     * existing target, so it fails on platform operations.

     */

    virtual void releaseTarget() = 0;

    /**

     * Copies rectangular area from currently bound target to given image target.

     * The copy rectangle top left corned is defined by x and y and bottom right corner

     * by image width and height.

     *

     * @param aImage The image to copy into

     * @param aX The x coordinate of top left corner copy area

     * @param aY The y coordinate of top left corner copy area

     */

    virtual void copyArea(Image* aImage, int aX, int aY) = 0;

    /**

     * Copies rectangular area within currently bound target from source

     * location to destination location.

     *

     * @param aSrcX The top left x coordinate of source rectangle

     * @param aSrcY The top left y coordinate of source rectangle

     * @param aWidth The width of source rectangle

     * @param aHeight The height of source rectangle

     * @param aDestX The top left x coordinate for the copy

     * @param aDestY The top left y coordinate for the copy

     * @param aPaint If to generate paint events for the new and obscured areas

     */

    virtual void copyArea(int aSrcX, int aSrcY, int aWidth, int aHeight, int aDestX, int aDestY, bool aPaint) = 0;

    /**

     * Draws outline of elliptical arc within specified rectangle.

     * Arc is drawn counterclockwise.

     *

     * @param aX The x coordinate of top left corner of arc rectangle

     * @param aY The y coordinate of top left corner of arc rectangle

     * @param aWidth The width of arc rectangle

     * @param aHeight The height of arc rectangle

     * @param aStartAngle The starting angle for arc

     * @param aArcAngle The span angle for arc

     */

    virtual void drawArc(int aX, int aY, int aWidth, int aHeight, int aStartAngle, int aArcAngle) = 0;

    /**

     * Draws an ellipse specified by rectangle.

     *

     * @param aX The x coordinate of top left corner of ellipse rectangle

     * @param aY The y coordinate of top left corner of ellipse rectangle

     * @param aWidth The width of ellipse rectangle

     * @param aHeight The height of ellipse rectangle

     */

    virtual void drawEllipse(int aX, int aY, int aWidth, int aHeight) = 0;

    /**

     * Draws a focus rectangle specified by the parameters.

     *

     * @param aX The x coordinate of top left corner of the rectangle

     * @param aY The y coordinate of top left corner of the rectangle

     * @param aWidth The width of the rectangle

     * @param aHeight The height of the rectangle

     */

    virtual void drawFocus(int aX, int aY, int aWidth, int aHeight) = 0;

    /**

     * Draws an image at (x, y) by copying a part of image into the paint device.

     * The default, (0, 0) (and negative) means all the way to the bottom-right of the image.

     *

     * @param aImage The source from where to draw

     * @param aManipulation The transformation to be applied to the region before it is drawn 

     * @param aTx The top-left x coordinate in the paint device that is to be drawn onto

     * @param aTy The top-left y coordinate in the paint device that is to be drawn onto

     * @param aTw The width of the image that is to be drawn onto.

     * @param aTh The heigth of the image that is to be drawn onto.

     * @param aSx The top-left x coordinate in image that is to be drawn

     * @param aSy The top-left y coordinate in image that is to be drawn

     * @param aSw The width of the image that is to be drawn.

     * @param aSh The heigth of the image that is to be drawn.

     * @see QPainter::drawImage

     */

    virtual void drawImage(Image* aImage, int aManipulation, int aTx, int aTy, int aTw = -1, int aTh = -1,

                           int aSx = 0, int aSy = 0, int aSw = -1, int aSh = -1) = 0;