#ifndef  AEEBITMAP_H
#define  AEEBITMAP_H
/*=================================================================================
FILE:          AEEBitmap.h

SERVICES:      AEE Bitmap interfaces

DESCRIPTION:   This file provides definitions for the bitmap interfaces made
available by the AEE to the application developers  This is a standard header
file that must be included by all applications using IBitmap modules of AEE.

PUBLIC CLASSES:   Not Applicable

INITIALIAZTION AND SEQUENCEING REQUIREMENTS: Not Applicable

        Copyright © 1999-2002 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=================================================================================*/

/*---------------------------------------------------------------------------------
      Include Files
---------------------------------------------------------------------------------*/

#include "AEE.h"

/*---------------------------------------------------------------------------------
      Interface IDs
---------------------------------------------------------------------------------*/

// IBitmapDev
#define AEEIID_BITMAPDEV       0x01012719


/*---------------------------------------------------------------------------------
      Type Declarations
---------------------------------------------------------------------------------*/

// RGB Values - Note that values in the range CLR_XXX - CLR_MAX use the
// pre-defined system color.

typedef uint32 RGBVAL;

#define MAKE_RGB(r, g, b)     (RGBVAL) ( ((uint32)(r) << 8) + ((uint32)(g) << 16) + ((uint32)(b) << 24) )
#define MAKE_RGBA(r, g, b, a) (RGBVAL) ( ((uint32)(r) << 8) + ((uint32)(g) << 16) + ((uint32)(b) << 24) + ((uint32)(a)))

#define RGB_NONE              (0xffffffffL)
#define RGB_WHITE             (MAKE_RGB(0xff, 0xff, 0xff))
#define RGB_BLACK             (MAKE_RGB(0,0,0))

// Point type
typedef struct _point
{
   int16       x, y;
}AEEPoint;


// Bitmap raster operation type
enum {
   AEE_RO_OR,
   AEE_RO_XOR,
   AEE_RO_COPY,
   AEE_RO_NOT,
   AEE_RO_OLDMASK,    // same as TRANSPARENT in v1.0; not supported in IBitmap
   AEE_RO_MERGENOT,
   AEE_RO_ANDNOT,
   AEE_RO_TRANSPARENT,
   AEE_RO_AND,
   AEE_RO_BLEND,
   AEE_RO_TOTAL
};
#ifdef WIN32
typedef unsigned AEERasterOp;
#else
typedef int8 AEERasterOp;
#endif


#define AEE_RO_MASK           AEE_RO_TRANSPARENT
#define AEE_RO_MASKNOT        AEE_RO_ANDNOT

#define AEE_RO_OLDTRANSPARENT AEE_RO_OLDMASK   // soon to be deleted


//
// AEE_RO_TRANSPARENT Mask Values: These describe the default transparent
// colors for the display bitmap and bitmaps compatible with it.  For
// monochrome and greyscale displays, the transparent color is
// RGBToNative(RGB_WHITE), and for color displays the default transparent
// color is RGBToNative(RGB_MASK_COLOR).
//

#define RGB_MASK_MONO      (RGB_WHITE)
#define RGB_MASK_GREY      (RGB_WHITE)
#define RGB_MASK_COLOR     MAKE_RGB(255, 0, 255)      // Magenta


// This is used for the native color values, whose meanings are local (native)
// to the bitmap in which they are used.
typedef uint32 NativeColor;


//*********************************************************************************
//
// IBitmap Interface
//
//*********************************************************************************

typedef struct {
   uint32  cx;
   uint32  cy;
   uint32  nDepth;
} AEEBitmapInfo;

typedef struct IBitmap    IBitmap;

#define INHERIT_IBitmap(iname) \
   INHERIT_IQueryInterface(iname); \
   NativeColor (*RGBToNative)     (iname *po, RGBVAL rgb); \
   RGBVAL      (*NativeToRGB)     (iname *po, NativeColor clr); \
   int  (*DrawPixel)              (iname *po, unsigned x, unsigned y, NativeColor color, AEERasterOp rop); \
   int  (*GetPixel)               (iname *po, unsigned x, unsigned y, NativeColor *pColor); \
   int  (*SetPixels)              (iname *po, unsigned cnt, AEEPoint *pPoint, NativeColor color, AEERasterOp rop); \
   int  (*DrawHScanline)          (iname *po, unsigned y, unsigned xMin, unsigned xMax, NativeColor color, AEERasterOp rop); \
   int  (*FillRect)               (iname *po, const AEERect *prc, NativeColor color, AEERasterOp rop); \
   int  (*BltIn)                  (iname *po, int xDst, int yDst, int dx, int dy, \
                                   IBitmap *pSrc, int xSrc, int ySrc, AEERasterOp rop); \
   int  (*BltOut)                 (iname *po, int xDst, int yDst, int dx, int dy, \
                                   IBitmap *pDst, int xSrc, int ySrc, AEERasterOp rop); \
   int  (*GetInfo)                (iname *po, AEEBitmapInfo *pinfo, int nSize); \
   int  (*CreateCompatibleBitmap) (iname *po, IBitmap **ppIBitmap, uint16 w, uint16 h); \
   int  (*SetTransparencyColor)   (iname *po, NativeColor color); \
   int  (*GetTransparencyColor)   (iname *po, NativeColor *pColor)


AEEINTERFACE(IBitmap)
{
   INHERIT_IBitmap(IBitmap);
};


// Access macros for IBitmap
#define  IBITMAP_AddRef(p)                       AEEGETPVTBL(p,IBitmap)->AddRef(p)
#define  IBITMAP_Release(p)                      AEEGETPVTBL(p,IBitmap)->Release(p)
#define  IBITMAP_QueryInterface(p,i,p2)          AEEGETPVTBL(p,IBitmap)->QueryInterface(p,i,p2)
#define  IBITMAP_RGBToNative(p,c)                AEEGETPVTBL(p,IBitmap)->RGBToNative(p,c)
#define  IBITMAP_NativeToRGB(p,c)                AEEGETPVTBL(p,IBitmap)->NativeToRGB(p,c)
#define  IBITMAP_DrawPixel(p,x,y,c,r)            AEEGETPVTBL(p,IBitmap)->DrawPixel(p,x,y,c,r)
#define  IBITMAP_GetPixel(p,x,y,c)               AEEGETPVTBL(p,IBitmap)->GetPixel(p,x,y,c)
#define  IBITMAP_SetPixels(p,n,pnt,c,r)          AEEGETPVTBL(p,IBitmap)->SetPixels(p,n,pnt,c,r)
#define  IBITMAP_DrawHScanline(p,y,x0,x1,c,r)    AEEGETPVTBL(p,IBitmap)->DrawHScanline(p,y,x0,x1,c,r)
#define  IBITMAP_FillRect(p,r,c,o)               AEEGETPVTBL(p,IBitmap)->FillRect(p,r,c,o)
#define  IBITMAP_BltIn(p,xd,yd,cx,cy,s,x,y,f)    AEEGETPVTBL(p,IBitmap)->BltIn(p,xd,yd,cx,cy,s,x,y,f)
#define  IBITMAP_BltOut(p,xd,yd,cx,cy,s,x,y,f)   AEEGETPVTBL(p,IBitmap)->BltOut(p,xd,yd,cx,cy,s,x,y,f)
#define  IBITMAP_GetInfo(p,i,n)                  AEEGETPVTBL(p,IBitmap)->GetInfo(p,i,n)
#define  IBITMAP_CreateCompatibleBitmap(p, pp, w, h)  AEEGETPVTBL(p, IBitmap)->CreateCompatibleBitmap(p, pp, w, h)
#define  IBITMAP_SetTransparencyColor(p, c)      AEEGETPVTBL(p,IBitmap)->SetTransparencyColor(p,c)
#define  IBITMAP_GetTransparencyColor(p, c)      AEEGETPVTBL(p,IBitmap)->GetTransparencyColor(p,c)
#define  IBITMAP_Invalidate(p,r)                 AEEGETPVTBL(p,IBitmap)->FillRect(p,r,0,AEE_RO_TRANSPARENT)



//*********************************************************************************
//
// IBitmapDev Interface
//
//*********************************************************************************

typedef struct IBitmapDev IBitmapDev;

#define INHERIT_IBitmapDev(iname) \
   INHERIT_IQueryInterface(iname); \
   int      (*Update)               (iname *po); \
   boolean  (*IsEnabled)            (iname *po); \
   int      (*NotifyEnable)         (iname *po, AEECallback *pcb)


AEEINTERFACE(IBitmapDev)
{
   INHERIT_IBitmapDev(IBitmapDev);
};


// Access macros for IBitmap
#define  IBITMAPDEV_AddRef(p)                    AEEGETPVTBL(p,IBitmapDev)->AddRef(p)
#define  IBITMAPDEV_Release(p)                   AEEGETPVTBL(p,IBitmapDev)->Release(p)
#define  IBITMAPDEV_QueryInterface(p,i,p2)       AEEGETPVTBL(p,IBitmapDev)->QueryInterface(p,i,p2)
#define  IBITMAPDEV_Update(p)                    AEEGETPVTBL(p,IBitmapDev)->Update(p)
#define  IBITMAPDEV_IsEnabled(p)                 AEEGETPVTBL(p,IBitmapDev)->IsEnabled(p)
#define  IBITMAPDEV_NotifyEnable(p,c)            AEEGETPVTBL(p,IBitmapDev)->NotifyEnable(p,c)



//*********************************************************************************
//
// IDIB Interface
//
//*********************************************************************************

// IDIB : BREW Device Independent Bitmap (DIB) format.
//
// This is a struct with public members.  It is also an interface so that the
// behavior of QueryInterface() is consistent.

#define IDIB_COLORSCHEME_NONE   0   // no fixed mapping for pixel values

#define IDIB_COLORSCHEME_332    8   // 3 bits red, 3 bits green, 2 bits blue
#define IDIB_COLORSCHEME_444   12   // 4 red, 4 green, 4 blue
#define IDIB_COLORSCHEME_555   15   // 5 red, 5 green, 5 blue
#define IDIB_COLORSCHEME_565   16   // 5 red, 6 green, 5 blue
#define IDIB_COLORSCHEME_666   18   // 6 red, 6 green, 6 blue
#define IDIB_COLORSCHEME_888   24   // 8 red, 8 green, 8 blue


typedef struct IDIB        IDIB;

struct IDIB {
   AEEVTBL(IBitmap) *pvt;
   IQueryInterface * pPaletteMap;    // cache for computed palette mapping info
   byte *            pBmp;           // pointer to top row
   uint32 *          pRGB;           // palette
   NativeColor       ncTransparent;  // 32-bit native color value
   uint16            cx;             // number of pixels in width
   uint16            cy;             // number of pixels in height
   int16             nPitch;         // offset from one row to the next
   uint16            cntRGB;         // number of palette entries
   uint8             nDepth;         // size of pixel in bits
   uint8             nColorScheme;   // IDIB_COLORSCHEME_...
   uint8             reserved[6];    // initialize to 0 when constructing a DIB; ignore when using a DIB
};


// AEEDIB is included for backward compatibility; this will be phased out.
typedef struct _aee_dib {
   IQueryInterface * pPaletteMap;
   byte    *         pBmp;
   uint32  *         pRGB;
   NativeColor       transparentColor;
   uint16            cx;
   uint16            cy;
   int16             nPitch;
   uint16            cntRGB;
   uint8             colorDepth;
   uint8             reserved[7];
} AEEDIB;

#define AEEDIB_FlushPalette(pdib)   ((pdib)->pPaletteMap && (IQI_Release((pdib)->pPaletteMap), (pdib)->pPaletteMap = 0))

// This is just for type safe casting of an IDIB* to an IBitmap*.
static __inline IBitmap *IDIB_TO_IBITMAP(const IDIB *pIDIB)
{
   return (IBitmap*)(void*)pIDIB;
}

// IDIB macros
#define IDIB_AddRef(p)                       AEEGETPVTBL(IDIB_TO_IBITMAP(p), IBitmap)->AddRef(IDIB_TO_IBITMAP(p))
#define IDIB_Release(p)                      AEEGETPVTBL(IDIB_TO_IBITMAP(p), IBitmap)->Release(IDIB_TO_IBITMAP(p))
#define IDIB_QueryInterface(p,i,p2)          AEEGETPVTBL(IDIB_TO_IBITMAP(p), IBitmap)->QueryInterface(IDIB_TO_IBITMAP(p),(i),(p2))

#define IDIB_FlushPalette(pdib)              if ((pdib)->pPaletteMap) {IQI_Release((pdib)->pPaletteMap); (pdib)->pPaletteMap = 0;}


/*=================================================================================
   INTERFACES DOCUMENTATION
===================================================================================

IDIB Interface

Description:

IDIB is a structure and an interface. This structure defines the BREW device-independent bitmap format.

IDIB inherits all of the member functions
of IBitmap, so an IDIB may be used as an IBitmap by type casting. (The
IDIB_TO_IBITMAP() inline function is supplied for type safe casting.) Unlike other
BREW interfaces, IDIB also has public data members. These data members can be
used to efficiently read or modify image data.

An application typically obtains an IDIB pointer from an IBitmap pointer by
calling IBITMAP_QueryInterface() with the class ID AEECLSID_DIB. Not all
IBitmap classes support IDIB, and in those cases QueryInterface() will return
an error code. On success, an IDIB pointer is returned, which must be
released when the caller has finished using it.

A bitmap consists of a 2-dimensional array of pixels. IDIB contains members
that indicate where in memory the pixels are, and how the pixel values are to
be interpreted.

===H2>
     Pixel array structure
===/H2>
===p>

The locations and sizes of pixels in the pixel array are described by the
pBmp, nPitch, and nDepth members.

The nPitch field specifies the distance (in bytes) from the beginning of any
row to the beginning of the next row.  Pitch is typically a function of the
bitmap width, the padding being applied, and whether it is a top-down or
bottom-up bitmap.  Bottom-up bitmaps will have a negative pitch value.
Users of an IDIB should honor the nPitch value and make no assumptions about
padding or directionality in the bitmap.

pBmp points to the first scanline (that is, y = 0) in the memory buffer that
holds the pixel data of a DIB. For a top-down DIB, it points to the
beginning of the first row.  For a bottom-up DIB, it points to the beginning
of the last row in memory.
===H2>
Usage example:
===/H2>
===p>
    For a bitmap of color depth 8 (one byte per pixel), width of 9, and
    height of 10, the following representations are possible (among others):
===pre>
                               nPitch    pBmp - start of bit array
    Top-down BMP file:           12           0
    Bottom-up BMP file:         -12          96
    Top-down packed bitmap:       9           0
    Bottom-up packed bitmap:     -9          72
===/pre>

    In *all* of these cases, and in fact for any 8-bit DIB, the code for
    reading a pixel remains the same:~
===center>
       COLORVALUE = pdib->pBmp[ y * pdib->nPitch + x ]
===/center>

Alignment: Rows will typically start at 32-bit boundaries, but alignment is
not guaranteed except in two cases.  When nDepth is 32, rows should be 32-bit
aligned, and when nDepth is 16, each row must be aligned on a 16-bit boundary.

Within a row, the left-most (x=0) pixel begins at the most significant bit of
the first byte.  Pixels are packed, bitwise, and split across bytes if
necessary.  1, 2, 4, 8, and 16 bit bitmaps minimize splitting of pixel values
across bytes, and yield the most efficiency.  While possible and well-defined,
sizes that tend to map irregularly to byte boundaries (like 3 or 12) will lead
to reduced efficiency.
~
NOTE: When modifying the pixel buffer, it is important to call
IBITMAP_Invalidate in case dirty rectangle optimizations have been implemented.
*
===h2>
     Pixel values
===/h2>
===p>

The type "NativeColor" is defined to represent values stored in pixels in the
pixel array.  Palette information (cntRGB and pRGB, or alternatively
nColorScheme) describes how pixel values map to red, green, and blue intensity
values.

When cntRGB is nonzero, the pixel values are treated as indices into the
palette, which is an array of 32-bit R-G-B color values.  (See pRGB, below.)

When nColorScheme is nonzero, it identifies a mapping of pixel values to
R-G-B values.  This can be thought of as a hard-coded palette.  (See
nColorScheme, below.)

When both cntRGB and nColorScheme are zero, the bitmap's color mapping is
"empty."  Blits to or from DIBs with empty color mapping result in pixel
values being copied literally, without translation, from source to
destination.  If the destination pixels are too small to hold source pixel
values, the results are undefined.  When the color mapping is empty, the color
conversion functions (RGBToNative() and NativeToRGB()) produce undefined
results.

Both cntRGB and nColorScheme can be non-zero, but if they conflict, the
bitmap's color mapping is undefined (not empty).  Undefined color mapping leads
to unpredictable results from blits and color conversion functions.

Note that this mapping between pixel values and colors is somewhat independent
of pixel size.  A 4096 color bitmap requires 12 bits to represent all color
values, but these could be stored in 12-bit (a "packed" representation) or
16-bit pixels (unpacked).

Transparency is a special case in interpreting pixel values.  For operations
that support transparency, such as IBITMAP_BltIn() when called with the
AEE_RO_TRANSPARENT raster op, pixels whose values match the transparent color
(ncTransparent) are treated as transparent, which means that the corresponding
pixels in the destination are left unmodified.  ncTransparent is a NativeColor
value, and the matching is performed on pixel values, not on the corresponding
R-G-B intensities.
===h2>
     Palette Map
===/h2>
===p>

The pPaletteMap member is provided as a way for driver software to cache
information computed from the bitmap's palette.  This is not simply a function
of the palette; it depends also on the graphics algorithm, and any other
bitmaps with which the DIB might interact.  This member is set to NULL when
there is no palette mapping object associated with the IDIB.

Every IDIB implementation must ensure that the pPaletteMap object (if set) is
released when the IDIB itself is deleted.  The IDIB_FlushPalette() macro
performed this task.

Any pPaletteMap must be released whenever an IDIB is modified such that the
interpretation of pixel values are affected (i.e. when cntRGB, pRGB[],
nColorScheme, or ncTransparent are modified).  Otherwise, a graphics algorithm
might proceed to use stale data or perhaps even corrupt memory on a subsequent
call.

Generally, users can ignore this value unless they modify a DIB's palette data
after it has been used (that is, graphics operations, such as IBitmap member
functions, have been used on it).  In that case, IDIB_FlushPalette() must be
called.

===h2>
     Software Support
===/h2>
===p>

IDIB presents a wide latititude of possibilites for bitmap layouts, but
practical constraints limit the number of formats that are supported by other
software in the handset.  Of the layouts that are supported, not all of those
will be fully optimized.  These limitations can differ from handset to
handset.  The purpose of DIBs, however, is to communicate bitmap data to or
from the graphics driver, so the target device's level of support for
particular formats is important to application software.  Here are some
general guidelines:
~
   Each handset's primary display (whether monochrome, greyscale, or color)
   should support blitting from palette-based 1-, 2-, 4-, and 8-bit DIBs.
   Color mapping generally will be done in an expedient (that is, not the most
   accurate) fashion.  1-bit and 8-bit operations should be particularly well
   optimized.  Additionally, 16-bit handsets will support 16-bit DIB formats
   using either IDIB_COLORSCHEME_555 or IDIB_COLORSCHEME_565 color schemes,
   but blitting a 5-5-5 DIB to a 5-6-5 device, or vice versa, will incur a
   performance penalty.

   8-bit palette-based DIBs should work well with all color displays, and are
   much smaller than 16-bit images, so are recommended for color images.
   Since each 8-bit image can have its own selection of 256 colors, color
   accuracy should not be a problem.
*

Definition:

OBJECT(IDIB) {
   AEEVTBL(IDIB)  *pvt;
   IQueryInterface * pPaletteMap;
   byte *            pBmp;
   uint32 *          pRGB;
   NativeColor       ncTransparent;
   uint16            cx;
   uint16            cy;
   int16             nPitch;
   uint16            cntRGB;
   uint8             nDepth;
   uint8             nColorScheme;
   uint8             reserved[6];
}


Members:

Members:

  pvt:
~
    pointer to the v-table.  Users should not access this directly; macros are
    provided for all the member functions (IDIB_AddRef, IDIB_Release, and
    IDIB_QueryInterface).
*
  pPaletteMap:
~
    Cache for computed palette mapping data.


    Generally, developers can ignore this field.

    This member provided for graphics operations that read from or write to
    the DIB.  Some algorithms, like optimized DIB to native blits, involve
    complicated initialization steps that transform palette data to a more
    readily accessible foramt.  Such an algorithm can store the initialization
    data in pPaletteMap to avoid the need for recomputing the next time it
    runs.  Anyone replacing a non-NULL pointer must release the pre-existing
    pointer (with IQI_Release()), and when the DIB is deleted any non-NULL
    pointer will be released.
*
  pBmp:
~
    Pointer to the top row of the pixel array.
*
  pRGB:
~
    Pointer to the color palette.



    The color palette is an array of 32-bit color values.  The size of the
    palette array is given in the 'cntRGB' member.

    A palette defines the meaning of pixel values in the bitmap data.  A pixel
    value of N corresponds to the color at index N in the palette.  Any pixel
    value greater than the size of the palette is undefined.

    Palette color values are not RGBVAL values.  Palette values are specified
    in terms of memory layout.  The first byte is blue, the second byte is
    green, the third bute is red, and the fourth byte is ignored.  On a
    little-endian processor, a palette value is the same as NTOHL(rgb).  On
    a big-endian processor, it is compatible with RGBVAL.
*
  ncTransparent:
~
    Transparent color for the DIB.  Note that this is not in RGB form; it is
    specified as a NativeColor, which corresponds directly to values in the
    pixel array.
*
  cx:
~
    Width of bitmap in pixels.  Reading or writing pixels at or above this
    indexn must be avoided.
*
  cy:
~
    Height of bitmap in pixels.  Reading or writing pixels at or above this
    index must be avoided.
*
  nPitch:
~
    Offset from any row to the row below it.
*
  cntRGB:
~
    Number of entries in the palette.  If this is zero, the bitmap contains no
    palette.  If this is nonzero, then pRGB points to an array of palette
    entries.
*
  nDepth:
~
    Size of each pixel, in bits.
*
  nColorScheme:
~
    If nonzero, describes mapping from pixel values to R-G-B values.




    The following currently defined values for nColorScheme describe how bit
    fields within each pixel value represent red, green, and blue intenstiy
    values:
===pre>
      IDIB_COLORSCHEME_332 : 3 bits red, 3 bits green, 2 bits blue
      IDIB_COLORSCHEME_444 : 4 red, 4 green, 4 blue
      IDIB_COLORSCHEME_555 : 5 red, 5 green, 5 blue
      IDIB_COLORSCHEME_565 : 5 red, 6 green, 5 blue
      IDIB_COLORSCHEME_666 : 6 red, 6 green, 6 blue
      IDIB_COLORSCHEME_888 : 8 red, 8 green, 8 blue
===/pre>

    In each case, the blue bits occupy the least significant bits of the pixel
    value, the green bits the next most significant, and then the red bits.
    Any leftover most significant bits are unused.
*
  reserved:
~
    Reserved bytes for future version.  Initialize these bits to zeros when
    constructing a DIB; ingnore the value when parsing a DIB.

*

Comments:

   R-G-B intensity values correlate with actual perceived color, but the
   precise relationship is complex and dependent upon the display hardware.
   IBitmap and IDIB are unconcerned with such issues.

See Also:

   IBitmap Interface
   IQI Interface
   IDIB_TO_IBITMAP()
   IBITMAP_Invalidate()



===================================================================================

Function: IDIB_TO_IBITMAP()

Description:
  This function provides type safe casting from IDIB interface pointers to
  IBitmap interface pointers.  This function should be used when passing
  an IDIB interface to an IBitmap function.  This is safer than a simple
  cast, since the compiler will verify the pointer type.

Prototype:
  __inline IBitmap *IDIB_TO_IBITMAP(const IDIB *pIDIB);

Parameters:
  pIDIB      [in]: Pointer to an IDIB interface.

Return Value:
  Returns pIDIB cast to an IBitmap*.

Comments:
  None.

Version:
   Introduced BREW Client 2.0

See Also:
  IDIB

===================================================================================

Function: IDIB_FlushPalette()

Description:
  This macro is used to flush the palette map of an IDIB structure.  The palette
  map stores cached palette conversion information.  It is necessary call this
  macro after making any change to the IDIB's palette.  If this is not done,
  the palette map may contain information that conflicts with the palette.

Prototype:
  #define IDIB_FlushPalette(pdib) if ((pdib)->pPaletteMap) {IQI_Release((pdib)->pPaletteMap); (pdib)->pPaletteMap = 0;}

Parameters:
  pdib       [in]: Pointer to an IDIB structure

Return Value:
  None.

Comments:
  None.

Version:
   Introduced BREW Client 2.0

See Also:
  IDIB

===================================================================================

Function: MAKE_RGB()

Description:
  This macro is used to compose an RGBVAL from red, green, and blue components.

Prototype:
  #define MAKE_RGB(r, g, b)     (RGBVAL) ( ((uint32)(r) << 8) + ((uint32)(g) << 16) + ((uint32)(b) << 24) )

Parameters:
  r          [in]: Red component
  g          [in]: Green component
  b          [in]: Blue component

Return Value:
  Returns an RGBVAL.

Comments:
  None.

Version:
   Introduced BREW Client 1.1

See Also:
  RGBVAL

  
===================================================================================
DATA STRUCTURES DOCUMENTATION
===================================================================================

AEEBitmapInfo

Description:
   This structure contains all of the information regarding the dimensions of a
bitmap, for both DIB and device dependent bitmap (DDB).

Definition:

typedef struct {
   uint32  cx;
   uint32  cy;
   uint32  nDepth;
} AEEBitmapInfo;

Members:

cx:      Number of pixels per row.
cy:      Number of pixel per column.
nDepth:  Number of significant bits per pixel.  This differs from the nDepth field
         in IDIB in that this one does not include padding bits.

Comments:
   None.

See Also:
   None.

=============================================================================
    NativeColor

Description:
    The NativeColor type is used to represent the value of a single pixel in the
bitmap. The interpretation of this value as a color is dependent of the format of
the bitmap. You should not rely on this being in a particular format. Instead, you
should use IBITMAP_NativeToRGB() and IBITMAP_RGBToNative() to access a NativeColor.

Definition:
    typedef uint32 NativeColor;

Comments:
    None.

See Also:
    IBITMAP_RGBToNative()
    IBITMAP_NativeToRGB()

===================================================================================
   INTERFACE DOCUMENTATION
===================================================================================

IBitmap Interface

Description:

   This interface provides a way to manipulate bitmaps.  Each IBitmap instance
   represents a bitmap.

   IBitmap is an interface with multiple implementations.  Device-independent
   bitmaps (DIBs) created with IDISPLAY_CreateDIBitmap() are one class, and
   bitmaps that represent the handset's display are of another class.  While
   both classes implement the IBitmap interface, each has different
   capabilities.  Both DIBs and display bitmaps can be used in blit
   operations.  Display bitmaps support all drawing operations, but DIBs do
   not generally support drawing (except blitting), and return EUNSUPPORTED
   from most functions.

   All functions that return an error code can potentially return
   EUNSUPPORTED.  Users should be prepared for all types of error codes,
   however.

The following header file is required:~
AEEBitmap.h

==============================================================================
Function: IBITMAP_AddRef()

This function is inherited from IQI_AddRef().

==============================================================================
Function: IBITMAP_Release()

This function is inherited from IQI_Release().

==============================================================================
Function: IBITMAP_QueryInterface()

This function is inherited from IQI_QueryInterface().

==============================================================================
Function: IBITMAP_RGBToNative()

Description:

   This function converts a RGBVAL into a native color value (pixel value).

   Native color values are the values stored in the pixel array; the mapping
   between native and RGB values is a property of the bitmap.  If no
   NativeColor corresponds exactly to the specified RGBVAL, a close match is
   returned.  This function is not required to return the closest match, and
   for performance reasons a close match (but not the closest) could be returned.

Prototype:
   NativeColor IBITMAP_RGBToNative(IBitmap *po, RGBVAL RGBColor)

Parameters:
   po [in]: Pointer to IBitmap interface.

   RGBColor [in]: The RGB value to be converted from.  Only true RGB values
   are supported.  Color table indices are not supported.

Return Value:

   The correponding native color value.

Comments:

   If the bitmap's lacks palette information, the result is undefined.


Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   RGBVAL, IBITMAP_NativeToRGB()

==============================================================================
Function:   IBITMAP_NativeToRGB

Description:

   This function obtains the R-G-B definition of a NativeColor value, in
   RGBVAL format.

   Each valid NativeColor corresponds to an R-G-B value.  The mapping of
   NativeColor values is a propery of the bitmap.

Prototype:
   RGBVAL   IBITMAP_NativeToRGB(IBitmap *po, NativeColor clr);

Parameter:
   po [in]:    Pointer to IBitmap interface.

   clr [in]:   Native color value.

Return Value:

   It returns the corresponding RGBVAL.

Comments:

   If the NativeColor provided is not associated with a specific RGB value,
   the return value from this function is undefined.

Side Effect:
   None.

Version:
   Introduced BREW Client 2.0

See Also:
   RGBVAL, IBITMAP_RGBToNative()

==============================================================================

Function: IBITMAP_DrawPixel()

Description:
   Draws a single pixel in the bitamp.

Prototype:
   int IBITMAP_DrawPixel(IBitmap *po, unsigned x, unsigned y, NativeColor color, AEERasterOp rop)

Parameters:
   po [in]: Pointer to IBitmap interface to which pixel will be drawn.

   x [in]: X coordinate of pixel.

   y [in]: Y coordinate of pixel.

   color [in]: Specifies the color to be used to draw the pixel.  This is a
   native color, which can be obtained with IBITMAP_RGBToNative().

   rop [in]: Specifies the raster operation that will be used to draw the
   pixel.  Only AEE_RO_COPY and AEE_RO_XOR are valid.

Return Value:
   Return SUCCESS on success.
   Return EUNSUPPORTED if the operation is not supported by the IBitmap.
   Return EBADPARM if raster op is invalid.~
   Other error codes can be returned (implementation specific).

Comments:

   If x or y are outside the bounds of the bitmap, nothing is drawn, and
   SUCCESS is returned.

Version:
   Introduced BREW Client 2.0

Side Effects:
   None.

==============================================================================

Function: IBITMAP_GetPixel()

Description:
   Retrieves the value of the specified pixel.

Prototype:
   int IBITMAP_GetPixel(IBitmap *po, unsigned x, unsigned y, NativeColor *pColor)

Parameters:
   po [in]: Pointer to IBitmap interface to which pixel will be drawn.

   x [in]: X coordinate of pixel.

   y [in]: Y coordinate of pixel.

   pColor [out]: Color of specified pixel.

Return Value:

   Return SUCCESS on success.~
   Return EBADPARM is coordinate is out of range.~
   Return EUNSUPPORTED if operation is not supported.~
   Other error codes can be returned (implementation specific).

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None

==============================================================================

Function: IBITMAP_SetPixels()

Description:
   Draws multiple pixels with the same color.

Prototype:
   int IBITMAP_SetPixels(IBitmap *po, unsigned cnt, AEEPoint *pPoint,
                         NativeColor color, AEERasterOp rop);

Parameters:
   po [in]:       Pointer to IBitmap interface to which pixel will be drawn.

   cnt [in]:      Number of pixels.

   pPoint [in]:   Array of 2D points.

   color [in]: Specifies the color to be used to draw the input multiple pixels.
   This is a native color, which is obtained with IBITMAP_RGBToNative.

   rop [in]: Specifies the raster operation that will be used to
   draw the pixel.

Return Value:
   Return SUCCESS on success, otherwise returns error code.~
   Other error codes can be returned (implementation specific).

Comments:
   Only AEE_RO_COPY and AEE_RO_XOR are valid raster operations.  If any value
   other these two are passed in as parameters, they will be treated as AEE_RO_COPY.

   In the current version, this function will return EUNSUPPORTED.

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None
====================================================================================

Function: IBITMAP_DrawHScanline()

Description:
   This function draws a horizontal line.

Prototype:
   int IBITMAP_DrawHScanline(IBitmap *po, unsigned y, unsigned xMin, unsigned xMax,
                             NativeColor color, AEERasterOp rop)

Parameters:
   po [in]: Pointer to IBitmap interface object to be used to draw the
   horizontal line.

   y  [in]: Y coordinate of the line.

   xMin  [in]: X coordinate of left end of line.

   xMax  [in]: X coordinate of right end of line.

   color [in]: Specifies the color to be used to draw the line.  This
   is a native color, which is obtained with IBITMAP_RGBToNative.

   rop [in]: Specifies the raster operation that will be used to
   draw the line.  Only AEE_RO_COPY and AEE_RO_XOR are valid.

Return Value:
   Return SUCCESS on success.~
   Return EBADPARM if raster op is invalid.~
   Other error codes can be returned (implementation specific).

Comments:
   None

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None

==============================================================================

Function: IBITMAP_FillRect()

Description:
   This function draws a solid rectangle of the specified color.

Prototype:
   int IBITMAP_FillRect(IBitmap *po, const AEERect *prc, NativeColor color, AEERasterOp rop)

Parameters:
   po [in]: Pointer to IBitmap interface object to be used to fill the rectangle.

   prc: [in]: A pointer to a rectangle that needs to be filled with the
   specified color.

   color: [in]: Specifies the color to be used to fill the rectangle.  This
   is a native color, which is obtained with IBITMAP_CovertColor.

   rop: [in]: Specifies the raster operation that will be used
   while drawing the rectangle.  Only AEE_RO_COPY and AEE_RO_XOR are valid.

Return Value:
   Return SUCCESS on success.~
   Return EBADPARM if raster op is invalid.~
   Other error codes can be returned (implementation specific).

Comments:

   'prc' must be a valid pointer.

   Any portions of the rectangle that fall outside the bitmap's bounds will be
   silently ignored (no errors will be generated).

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None

==============================================================================
Function: IBITMAP_BltIn()

Description:

  This function performs a bit-block transfer of the data corresponding to a
  rectangle of pixels from the specified source bitmap into this bitmap.

  Each pixel in the source is associated with a corresponding pixel in the
  destination.  A logical operation is performed on each pair of source and
  destination pixels, and the result is written over the destination pixel.


Prototype:
   int    IBITMAP_BltIn(IBitmap * po,
                            int xDst,
                            int yDst,
                            int dx,
                            int dy,
                            IBitmap *pSrc,
                            int xSrc,
                            int ySrc,
                            AEERasterOp rop)

Parameters:
   po :[in]: Pointer to the IBitmap interface object into which the bit-block
   transfer needs to be done.

   xDst: [in]: Specifies the x-coordinates of the upper left corner of the
   destination rectangular area.

   yDst: [in]: Specifies the y-coordinates of the upper left corner of the
   destination rectangular area.

   dx: [in]: Specifies the width of the destination and source
   rectangles. Negative values will be treated

   dy: [in]: Specifies the height of the destination and source rectangles.
   Negative values will be treated as zero.

   pSrc: [in]: Pointer to another IBitmap interface that represents the
   source bitmap.

   xSrc: [in]: Specifies the x-coordinate of the upper left corner of the
   source bitmap from where the bit-block transfer must begin.

   ySrc: [in]: Specifies the y-coordinate of the upper left corner of the
   source bitmap from where the bit-block transfer must begin.

   rop: [in]: Specifies the raster operation that will be used while doing the
   bit-block transfer.

Return Value:

   Returns SUCCESS if successful.

   Returns EUNSUPPORTED or some other error code if the operation is not~
   supported.  This might be due to the format of the source bitmap or the~
   type of raster operation that was requested or a combination of the two.

Comments:

   When either dx or dy is negative, nothing will be written to the
   destination bitmap.  (The rectangles are treated as empty.)

   It is legal for all or part of the source or destination rectangles that
   fall outside the corresponding bitmap bounds (including negative
   coordinates).  When parts of the source or destination rectangles exceed a
   bitmap's bounds they will be ignored silently (clipped).  Clipping will not
   affect the mapping from source to destination of any unclipped portions,
   and will not result in an error code, even when everything is clipped.

   When the width and height of the source bitmap are not known and one wishes
   to blit the entire bitmap, very large values can be supplied for dx and dy,
   and clipping will limit the rectangle to the size of the source.

   The source bitmap may or may not be the same format as the destination
   bitmap, but not all source formats are necessarily supported.


Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None

==============================================================================
Function: IBITMAP_BltOut()

Description:

  Perform a bit-block transfer from this bitmap into a specified destination
  bitmap.

  Users would not normally call this function directly.  Instead, the
  destination bitmap's IBITMAP_BltIn() member function should be called,
  because that will succeed in more cases.

Prototype:
   int      IBITMAP_BltOut(IBitmap * po,
                            int xDst,
                            int yDst,
                            int dx,
                            int dy,
                            IBitmap *pDst,
                            int xSrc,
                            int ySrc,
                            AEERasterOp rop)

Parameters:
   po :[in]: Pointer to the IBitmap interface object from which the bit-block
   transfer needs to be done.

   xDst: [in]: Specifies the x-coordinates of the upper left corner of the
   destination rectangular area.

   yDst: [in]: Specifies the y-coordinates of the upper left corner of the
   destination rectangular area.

   dx: [in]: Specifies the width of the destination rectangle.

   dy: [in]: Specifies the height of the destination rectangle.

   pDst: [in]: Pointer to another IBitmap interface that represents the
   destination bitmap.

   xSrc: [in]: Specifies the x-coordinate of the upper left corner of the
   source bitmap from where the bit-block transfer must begin.

   ySrc: [in]: Specifies the y-coordinate of the upper left corner of the
   source bitmap from where the bit-block transfer must begin.

   rop: [in]: Specifies the raster operation that will be used while doing the
   bit-block transfer.

Return Value:

   Returns SUCCESS if successful.~
   Returns EUNSUPPORTED if the operation is not supported.~
   Other error codes can be returned (implementation specific).

Comments:

   There is no need to call this function except from the implementation of
   IBITMAP_BltIn().

   IBITMAP_BltOut() exists to help IBITMAP_BltIn().  IBITMAP_BltIn() will
   delegate to the source bitmap's IBITMAP_BltOut() when the destination does
   not support the operation and the bitmaps are of different classes.  In
   this manner, both classes have the opportunity to perform the operation,
   and it will succeed as long as either class supports it.  Note that
   IBITMAP_BltOut() cannot delegate likewise to IBITMAP_BltIn(), because that
   would lead to infinite recusrion.

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   None

==============================================================================
Function: IBITMAP_GetInfo()

Description:
   This function retrieves the dimension of the bitmap.

Prototype:
   int IBITMAP_GetInfo(IBitmap *po, AEEBitmapInfo *pinfo, int nSize);

Parameters:
   po [in]:       Pointer to IBitmap interface.

   pinfo [out]:   Pointer to AEEBitmapInfo result.

   nSize [in]:    The size of AEEBitmapInfo in the current version.  AEEBitmapInfo STRUCT
                  may grow over time.  This field will allow backward compatibility.

Return Value:
   Return SUCCESS on success.~
   Returns EUNSUPPORTED if the size is not recognized by the bitmap.

Comments:

   This function should *always* succeed when nSize is equal to
   sizeof(AEEBitmapInfo), and when pinfo is a valid pointer.

Side Effects:
   None

Version:
   Introduced BREW Client 2.0

See Also:
   AEEBitmapInfo

==================================================================================

Function: IBITMAP_CreateCompatibleBitmap()

Description:

   This function creates a new bitmap compatible with this bitmap interface
   (the first parameter).

   "Compatible" means having equivalent pixel sizes and the same mapping
   between pixel values (native colors) and R-G-B values.  Width and height do
   not affect compatibility.

   A blit operation involving two compatible bitmaps will be reasonably fast,
   because it does not need to perform complex translations of pixel data.
   Being a common case, this type of operation is typically highly optimized.
   Also, copies between compatible bitmaps do not result in the loss of any
   color information.

   A compatible bitmap will generally support all the same drawing operations
   that the original bitmap supports.

Prototype:

  int IBITMAP_CreateCompatibleBitmap(IBITMAP *po, IBitmap **ppIBitmap, uint16 w, uint16 h);

Parameters:
  po         [in]: Pointer to the current bitmap interface.
  ppIBitmap [out]: Pointer to IBitmap interface of the new bitmap.
  w          [in]: Width of new bitmap.
  h          [in]: Height of new bitmap.

Return Value:
  SUCCESS is returned if function executed correctly.~
  ENOMEMORY if there was not enough memory for the operation.~
  Other error codes can be returned (implementation specific).

Comments:

   The new bitmap inherits the transparency color of the bitmap from which it
   is created.

Side Effects:
  None.

Version:
   Introduced BREW Client 2.0

See Also:
  None.

==================================================================================

Function: IBITMAP_SetTransparencyColor()

Description:

  This function sets the transparency color of the bitmap.  This is used when
  this bitmap is the source bitmap of a transparent bit blit operation.  For
  pixels that contain this NativeColor, the correponding destination pixel
  will be unaffected.

Prototype:
  int IBITMAP_SetTransparencyColor(IBITMAP *pMe, NativeColor color);

Parameters:
  pMe        [in]: Pointer to the current bitmap interface.
  color      [in]: Color to make transparent.

Return Value:
  SUCCESS is returned if function executed correctly.~
  EUNSUPPORTED if the operation is not supported.~
  Other error codes can be returned (implementation specific).

Comments:
  None.

Side Effects:
  None.

Version:
   Introduced BREW Client 2.0

See Also:
  IBITMAP_GetTransparencyColor(), IBITMAP_BltIn(), IBITMAP_BltOut()

==================================================================================

Function: IBITMAP_GetTransparencyColor()

Description:

  This function gets the current transparency color of the bitmap.  This is
  used when this bitmap is the source bitmap of a transparent bit blit
  operation.

Prototype:
  int IBITMAP_GetTransparencyColor(IBITMAP *pMe, NativeColor *pColor);

Parameters:
  pMe        [in]: Pointer to the current bitmap interface.

  pColor    [out]: Transparency color.

Return Value:
  SUCCESS is returned if function executed correctly.~
  EBADPARM is return if pColor is NULL.~
  EUNSUPPORTED if the operation is not supported.~
  Other error codes can be returned (implementation specific).

Comments:

  The transparency color is a NativeColor value, not an RGBVAL.

Side Effects:
  None.

Version:
   Introduced BREW Client 2.0

See Also:
  IBITMAP_SetTransparencyColor(), IBITMAP_BltIn(), IBITMAP_BltOut()

==================================================================================

Function: IBITMAP_Invalidate()

Description:
  This function expands the bitmap's dirty rectangle to include the rectangle
  passed in the prc parameter.

Prototype:
  int IBITMAP_Invalidate(IBitmap *po, const AEERect *prc);

Parameters:
  po         [in]: Pointer to the bitmap interface.

  prc       [out]: Pointer to the rectangle that should be included in the dirty
                   region.

Return Value:
  SUCCESS is returned if function executed correctly.~
  EUNSUPPORTED if dirty rectangle optimizations are not implemented.

Comments:
  Some implementations of the device IBitmap optimize screen updates by keeping
  track of what parts of the screen have changed since the last update.  This
  "dirty rectangle" is automatically expanded by each IBitmap drawing function,
  and reset on update.  If an application obtains an IDIB from this IBitmap and
  modifies the pixel buffer directly, there is no way for the IBitmap implementation
  to know when a change has occurred.  It is therefore necessary to call this
  function to expand the dirty rectangle to include the pixels that have changed
  before an update occurs.  It is not necessary to call this function if the pixel
  buffer is not being modified directly through IDIB.

Side Effects:
  None.

Version:
   Introduced BREW Client 2.1

See Also:
  IDIB

===================================================================================
   INTERFACE DOCUMENTATION
===================================================================================

IBitmapDev Interface

Description:
   This interface is used for various functions relevent to device bitmaps.  It
   is only implemented for device bitmaps and is obtained by calling a bitmap's
   QueryInterface method with an interface ID of AEEIID_BITMAPDEV.

The following header file is required:~
AEEBitmap.h

==============================================================================
Function: IBITMAPDEV_AddRef()

This function is inherited from IQI_AddRef().

==============================================================================
Function: IBITMAPDEV_Release()

This function is inherited from IQI_Release().

==============================================================================
Function: IBITMAPDEV_QueryInterface()

This function is inherited from IQI_QueryInterface().

==============================================================================
Function: IBITMAPDEV_Update()

Description:
   This function copies the bitmap to its associated display synchronously.
   If dirty rectangle optimization is implemented, only areas of the display
   marked as dirty will be copied.

Prototype:
   int IBITMAPDEV_Update(IBitmapDev *po);

Parameters:
   po       [in]: Pointer to IBitmapDev interface.

Return Value:
   SUCCESS if functiona executed correctly.~
   Other error codes may be returned depending on the implementation.

Comments:
   This function has no effect if the bitmap is disabled.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IBITMAP_Invalidate()

==============================================================================
Function: IBITMAPDEV_IsEnabled()

Description:
   This function is used to query the enabled state of the bitmap.

Prototype:
   boolean IBITMAPDEV_IsEnabled(IBitmapDev *po);

Parameters:
   po       [in]: Pointer to IBitmapDev interface.

Return Value:
   TRUE if this bitmap is enabled.~
   FALSE otherwise.

Comments:
   While the bitmap is disabled, no drawing operations are allowed.  IBitmap
   drawing functions will have no effect.  If an application has direct access
   to the bitmap's pixel buffer through IDIB, it is important that the app
   refrain from modifying the pixel buffer while the bitmap is disabled.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IBITMAPDEV_NotifyEnable()

==============================================================================
Function: IBITMAPDEV_NotifyEnable()

Description:
   This function registers for a notification of a change to the bitmap's
   enabled state.  The callback will be triggered when the state of the bitmap
   changes either from enabled to disabled or disabled to enabled.

Prototype:
   int IBITMAPDEV_NotifyEnable(IBitmapDev *po, AEECallback *pcb);

Parameters:
   po       [in]: Pointer to IBitmapDev interface.
   pcb      [in]: Pointer to callback structure.

Return Value:
   SUCCESS if function executed correctly.~
   EBADPARM if pcb is NULL.~
   Other error codes may be returned depending on the implementation.

Comments:
   It is desirable to reregister for this notification in the callback function,
   so as not to miss any state changes.

   This callback is also triggered when this bitmap goes away.

Side Effects:
   None

Version:
   Introduced BREW Client 3.0

See Also:
   IBITMAPDEV_IsEnabled()

=================================================================================*/

#endif /* AEEBITMAP_H */

