/* Copyright (c) 2009 The Khronos Group Inc.

 * Portions copyright (c) 2009-2010  Nokia Corporation and/or its subsidiary(-ies)

 *

 * Permission is hereby granted, free of charge, to any person obtaining a

 * copy of this software and/or associated documentation files (the

 * "Materials"), to deal in the Materials without restriction, including

 * without limitation the rights to use, copy, modify, merge, publish,

 * distribute, sublicense, and/or sell copies of the Materials, and to

 * permit persons to whom the Materials are furnished to do so, subject to

 * the following conditions:

 *

 * The above copyright notice and this permission notice shall be included

 * in all copies or substantial portions of the Materials.

 *

 * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

 * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

 */

#ifndef OWFIMAGE_H_

#define OWFIMAGE_H_

#include "owftypes.h"

#ifdef __cplusplus

extern "C" {

#endif

typedef void*   OWF_DISPCTX;

#undef USE_FLOAT_PIXEL

/*

 * This is and always should be the only place where USE_FLOAT_PIXEL is 

 * defined so if #define USE_FLOAT_PIXEL is absent in owfimage.h then it

 * can be assumed it is not defined elsewhere. 

 */ 

//#define USE_FLOAT_PIXEL

/* --

* internal pixel format

*/

#ifdef USE_FLOAT_PIXEL

#define OWF_IMAGE_INTERNAL_PIXEL_IS_FLOAT

typedef OWFfloat            OWFsubpixel; /* subpixel representation */

#define OWF_RED_MIN_VALUE   0.0f

#define OWF_RED_MAX_VALUE   1.0f

#define OWF_GREEN_MIN_VALUE 0.0f

#define OWF_GREEN_MAX_VALUE 1.0f

#define OWF_BLUE_MIN_VALUE  0.0f

#define OWF_BLUE_MAX_VALUE  1.0f

#define OWF_ALPHA_MIN_VALUE 0.0f

#define OWF_ALPHA_MAX_VALUE 1.0f

#define OWF_FULLY_OPAQUE        OWF_ALPHA_MAX_VALUE

#define OWF_FULLY_TRANSPARENT   OWF_ALPHA_MIN_VALUE

#define OWF_BYTE_MAX_VALUE  255.0f

#define OWF_BILINEAR_ROUNDING_VALUE 0.0f

#define OWF_BLEND_ROUNDING_VALUE 0.0f

#define OWF_PREMUL_ROUNDING_FACTOR  0.0f

#define OWF_SOURCE_CONVERSION_ROUNDING_VALUE 0.0f

#else

#undef OWF_IMAGE_INTERNAL_PIXEL_IS_FLOAT

typedef OWFuint8            OWFsubpixel; /* subpixel representation */

#define OWF_RED_MIN_VALUE         0

#define OWF_RED_MAX_VALUE       255

#define OWF_GREEN_MIN_VALUE       0

#define OWF_GREEN_MAX_VALUE     255

#define OWF_BLUE_MIN_VALUE        0

#define OWF_BLUE_MAX_VALUE      255

#define OWF_ALPHA_MIN_VALUE       0

#define OWF_ALPHA_MAX_VALUE     255

#define OWF_FULLY_OPAQUE        OWF_ALPHA_MAX_VALUE

#define OWF_FULLY_TRANSPARENT   OWF_ALPHA_MIN_VALUE

#define OWF_BYTE_MAX_VALUE      255

#define OWF_BILINEAR_ROUNDING_VALUE 0.5f

#define OWF_SOURCE_CONVERSION_ROUNDING_VALUE 0.5f

#define OWF_BLEND_ROUNDING_VALUE (OWF_ALPHA_MAX_VALUE/2)

#define OWF_PREMUL_ROUNDING_FACTOR (OWF_ALPHA_MAX_VALUE/2)

#endif

/*

 * Byte order of different color formats

 * these are used when converting from/to

 * internal format

 */

#define ARGB8888_ALPHA_MASK         0xFF000000

#define ARGB8888_RED_MASK           0x00FF0000

#define ARGB8888_GREEN_MASK         0x0000FF00

#define ARGB8888_BLUE_MASK          0x000000FF

#define ARGB8888_ALPHA_SHIFT        24

#define ARGB8888_RED_SHIFT          16

#define ARGB8888_GREEN_SHIFT        8

#define ARGB8888_BLUE_SHIFT         0

#define RGB565_ALPHA_MASK   0xFFFF

#define RGB565_RED_MASK     0xF800

#define RGB565_GREEN_MASK   0x07E0

#define RGB565_BLUE_MASK    0x001F

/* These are used when converting from RGB565 to ARGB8888. */

#define RGB565_ALPHA_SHIFT  16

#define RGB565_RED_SHIFT    11

#define RGB565_GREEN_SHIFT  5

/* subpixels per pixel */

#define OWF_PIXEL_SIZE      4

/* subpixel in bytes */

#define OWF_SUBPIXEL_SIZE   sizeof(OWFsubpixel)

#define OWF_BYTES_PER_PIXEL (OWF_PIXEL_SIZE * OWF_SUBPIXEL_SIZE)

#pragma pack(push, 1)

typedef union {

    struct {

        OWFsubpixel         blue;

        OWFsubpixel         green;

        OWFsubpixel         red;

        OWFsubpixel         alpha;

    } color;

    OWFsubpixel             subpixel[OWF_PIXEL_SIZE];

    OWFuint8                pixelbytes[OWF_BYTES_PER_PIXEL];

} OWFpixel;

#pragma pack(pop)

/* -- */

/* filters used in OWF_Image_Stretch */

typedef enum {

    OWF_FILTER_POINT_SAMPLING,  /* nearest pixel */

    OWF_FILTER_BILINEAR        /* nearest 4 */

} OWF_FILTERING;

typedef struct {

    OWFint                  width;

    OWFint                  height;

    OWFint                  stride; /* number of bytes per line */

    OWFint                  pixelSize; /* pixel size in bytes */

    OWF_IMAGE_FORMAT        format;

    OWFboolean              foreign;

    OWFint                  dataMax; /* data buffer max size */

    void*                   data;

} OWF_IMAGE;

/* This typedef denotes an owned OWF_IMAGE, as opposed to a temporary association.

 * Owned instances must be destroyed when the containing object is destroyed.

 */

typedef OWF_IMAGE* OWF_IMAGE_INST;

typedef enum {

    OWF_FLIP_NONE,

    OWF_FLIP_VERTICALLY     = 1,

    OWF_FLIP_HORIZONTALLY   = 2

} OWF_FLIP_DIRECTION;

typedef enum {

    OWF_ROTATION_0          = 0,

    OWF_ROTATION_90         = 90,

    OWF_ROTATION_180        = 180,

    OWF_ROTATION_270        = 270

} OWF_ROTATION;

typedef enum {

    OWF_TRANSPARENCY_NONE,

    OWF_TRANSPARENCY_GLOBAL_ALPHA   = (1 << 0),

    OWF_TRANSPARENCY_SOURCE_ALPHA   = (1 << 1),

    OWF_TRANSPARENCY_MASK           = (1 << 2),

    OWF_TRANSPARENCY_COLOR_KEY      = (1 << 3)

} OWF_TRANSPARENCY;

typedef struct _OWF_BLEND_INFO {

    struct {

        OWF_IMAGE*          image;

        OWF_RECTANGLE*      rectangle;

    } destination;

    struct {

        OWF_IMAGE*          image;

        OWF_RECTANGLE*      rectangle;

    } source;

    OWF_IMAGE*              mask;

    OWFsubpixel             globalAlpha;

} OWF_BLEND_INFO;

/*!---------------------------------------------------------------------------

 *  \brief Initialize image object

 *

 *  \param image            Image object to initialize

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Init(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Creates new reference counted image object

 *

 *  \param width            Image width (in pixels)

 *  \param height           Image height (in pixels)

 *  \param format           Image format (\see OWF_IMAGE_FORMAT)

 *  \param buffer           Pointer to image pixel data. If NULL, then a new

 *                          buffer is allocated for storing image pixel data.

 *                          Allocated buffer is owned by the image. If non-NULL,

 *                          then the image will be a "foreign" one, that doesn't

 *                          own the pixel data but merely uses it.

 *  \param minimumStride    Minimum number of bytes per scanline (may be zero)

 *

 *

 *  \return New image object or NULL if error occured.

 *----------------------------------------------------------------------------*/

OWF_PUBLIC OWF_IMAGE*

OWF_Image_Create(OWFint width,

                 OWFint height,

                 const OWF_IMAGE_FORMAT* format,

                 void* buffer,

                 OWFint minimumStride);

/*!---------------------------------------------------------------------------

 *  \brief Destroy image object. Rather than actually destroying the image

 *  immediately, this decrements image's reference count by one and once the

 *  counter reaches zero, the actual deletion will occur.

 *

 *  \param image            Image to destroy

 *----------------------------------------------------------------------------*/

OWF_PUBLIC void

OWF_Image_Destroy(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Create a pixel-perfect copy (clone) of the image. The copy will be

 *  totally independent from the original image, i.e. doesn't share pixel

 *  buffers or anything.

 *

 *  \param image            Image to copy

 *

 *  \param Copy of the image or NULL if error occured.

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWF_IMAGE*

OWF_Image_Copy(const OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Set image size. This doesn't modify the pixel data in anyway,

 *  merely just changes the image header. Mostly used for (recycling) foreign

 *  images that point to external pixel buffers.

 *

 *  If the new pixel count (width * height) exceeds

 *  current values, the pixel buffer will NOT be resized, but the call will FAIL.

 *

 *  \param image            Image to resize

 *  \param width            New width of the image

 *  \param height           New height of the image

 *

 *

 *  \return Boolean value indicating success of the operation. In case of

 *  failure, no modifications are done to original image.

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_SetSize(OWF_IMAGE* image,

                  OWFint width,

                  OWFint height);

/*!---------------------------------------------------------------------------

 *  \brief Set internal mode flags. This doesn't modify the pixel data in anyway,

 *  merely just changes the image header. Mostly used for (recycling) foreign

 *  images that point to external pixel buffers.

 *

 *

 *  \param image            Image to resize

 *  \param premultiply      Image data is premultiplied

 *  \param linear           Image colour data is linear

 *

 *

 *  \return Boolean value indicating success of the operation. In case of

 *  failure, no modifications are done to original image.

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_SetFlags(OWF_IMAGE* image,

                  OWFboolean premultiply,

                  OWFboolean linear);

/*!---------------------------------------------------------------------------

 *  \brief Set the pixel buffer to an alternate location.

 *  All other parameters remain the same.

 *

 *  \param image            Image to resize

 *  \param buffer           Image data source to start using

 *

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_SetPixelBuffer(OWF_IMAGE* image,      void* buffer);

/*!---------------------------------------------------------------------------

 *  \brief Blit (1:1 copy) pixels from image to another w/ clipping.

 *

 *  \param dst              Destination image

 *  \param dstRect          Destination rectangle

 *  \param src              Source image

 *  \param srcRect          Source rectangle

 *

 *  \return Boolean value indicating whether pixels were copied or not. If not,

 *  it means that either of the rectangles is outside its respective image's

 *  bounds.

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_Blit(OWF_IMAGE* dst,

               OWF_RECTANGLE const* dstRect,

               OWF_IMAGE const* src,

               OWF_RECTANGLE const* srcRect);

/*!---------------------------------------------------------------------------

 *  \brief Stretch-blit (scaled copy) pixels from image to another w/ clipping.

 *

 *  \param dst              Destination image

 *  \param dstRect          Destination rectangle

 *  \param src              Source image

 *  \param srcRect          Source rectangle

 *

 *  \return Boolean value indicating whether pixels were copied or not. If not,

 *  it means that either of the rectangles is outside its respective image's

 *  bounds.

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_Stretch(OWF_IMAGE* dst,

                  OWF_RECTANGLE* dstRect,

                  OWF_IMAGE* src,

                  OWFfloat* srcRect,

                  OWF_FILTERING filter);

/*!---------------------------------------------------------------------------

 *  \brief Multiply pixels' alpha value into rgb-color components.

 *  Multiplies only if image source image is non-premultiplied.

 *  \param image            Image to convert to pre-multiplied domain.

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_PremultiplyAlpha(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Divide pixels' rgb-color components by its alpha value.

 *

 *  \param image            Image to convert to nonpre-multiplied domain.

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_UnpremultiplyAlpha(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Linearizes image pixel data

 *

 *  \param image            Image to convert to linear domain

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_LinearizeData(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Non-linearizes image pixel data

 *

 *  \param image            Image to convert to non-linear domain

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_NonLinearizeData(OWF_IMAGE* image);

/*!---------------------------------------------------------------------------

 *  \brief Apply gamma correction to image pixel values

 *

 *  \param image            Image to operate on

 *  \param gamma            Gamma value

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Gamma(OWF_IMAGE* image, OWFfloat gamma);

/*!---------------------------------------------------------------------------

 *  \brief Flip (mirror) image about one or both of its center axes.

 *

 *  \param image            Image to flip

 *  \param dir              Flip direction. Valid values are

 *                          OWF_FLIP_NONE, OWF_FLIP_HORIZONTALLY,

 *                          OWF_FLIP_VERTICALLY or any bitwise-or combination

 *                          of the former.

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Flip(OWF_IMAGE* image,

               OWF_FLIP_DIRECTION dir);

/*!---------------------------------------------------------------------------

 *  \brief Rotate image n*90 degrees about its center

 *

 *  \param dst              Result (rotated) image.

 *  \param src              Source image.

 *  \param rotation         Rotation angle (OWF_ROTATION_0, OWF_ROTATION_90,

 *                          OWF_ROTATION_180, or OWF_ROTATION_270)

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Rotate(OWF_IMAGE* dst,

                 OWF_IMAGE* src,

                 OWF_ROTATION rotation);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Blend(OWF_BLEND_INFO* blend,

                OWF_TRANSPARENCY transparency);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_Clear(OWF_IMAGE* image,

                OWFsubpixel red,

                OWFsubpixel green,

                OWFsubpixel blue,

                OWFsubpixel alpha);

/*!---------------------------------------------------------------------------

 *  \brief Convert image data from internal color format to destination format

 *

 *  \param dst

 *  \param src

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_DestinationFormatConversion(OWF_IMAGE* dst,

                                      OWF_IMAGE* src);

/*!---------------------------------------------------------------------------

 *  \brief Test whether it will be possible to convert to destination format.

 *  Note, no IMAGE object yet extists. This is effectively a "static" member method.

 *  \param format proposed destination format

 *

 *  \return boolean true if image lib can convert image data from internal color format 

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_IsValidDestinationFormat(OWF_IMAGE_FORMAT* format);

/*!---------------------------------------------------------------------------

*  \brief Convert image data from source format to internal format

 *

 *  \param src

 *  \param dst

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFboolean

OWF_Image_SourceFormatConversion(OWF_IMAGE* dst,

                                 OWF_IMAGE* src);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL void*

OWF_Image_AllocData(OWF_DISPCTX dc, OWFint width,

                    OWFint height,

                    OWF_PIXEL_FORMAT format);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL void

OWF_Image_FreeData(OWF_DISPCTX dc, void** buffer);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFint

OWF_Image_GetFormatPixelSize(OWF_PIXEL_FORMAT format);

/*!---------------------------------------------------------------------------

 * \brief Return stride (aligned row size in bytes) calculated from image

 * width and pixelSize. If pixelSize is negative image width must be divisible

 * by pixelSize.

 *

 * \param width             Width of image

 * \param pixelSize         Size of single pixel in bytes. Negative size

 *                          means value is a divisor (i.e. 1/pixelSize)

 * \param padding           Number of bits each row is padded to.

 * \return Row size in bytes.

 *----------------------------------------------------------------------------*/

OWF_PUBLIC OWFint

OWF_Image_GetStride(OWFint width,

                    const OWF_IMAGE_FORMAT* format,OWFint minimumStride);

/*!---------------------------------------------------------------------------

 *  \brief

 *

 *  \param

 *

 *  \return

 *----------------------------------------------------------------------------*/

OWF_API_CALL OWFint

OWF_Image_GetFormatPadding(OWF_PIXEL_FORMAT format);