[[TOC]]

= CBitmap =

CBitmap is a C++ class that is provided to display bitmaps.

== Constructors ==

{{{
CBitmap(void);
CBitmap(const string& strFilename);
CBitmap(const char* pszfilename);
}}}
The constructors with a passed filename create a CBitmap object and load the file into memory.

==== Parameters ====
 * strFilename - filename
 * pszFilename - filename

==== Examples ====

{{{
CBitmap image("/mnt/nand/apps/myapp/myapp.bmp");
}}}

{{{
string strFile = "/mnt/nand/apps/myapp/myapp.bmp";
CBitmap image(strFile);
}}}

{{{
CBitmap image;
}}}
This constructs the bitmap object without loading any file yet.

== Member Functions ==

=== LoadBitmp ===
Opens a specified file.

{{{
int LoadBitmap(const string& strFilename, PALETTE_ITEM* transparent = NULL);
int LoadBitmap(const char* pszFilename, PALETTE_ITEM* transparent = NULL);
}}}

==== Parameters ====
 * strFilename - filename
 * pszFilename - filename
 * transparent - (optional parameter) if specified defines a particular color to treat as transparent instead of displaying the color

==== Return Value ====

||'''Response'''||'''Description'''||
||BITMAP_SUCCESS||Operation successful||
||ERR_BITMAP_FILE_OPEN||file cannot be opened||
||ERR_BITMAP_HEADER_READ||bitmap header cannot be read||
||ERR_BITMAP_INFO_READ||bitmap info cannot be read||
||ERR_BITMAP_SIZE_OR_TYPE||width is greater than 640, height is greater than 480, or bitmap is not 8 bits per pixel||
||ERR_BITMAP_PALETTE_READ||color palette cannot be read||
||ERR_BITMAP_TOO_MANY_COLORS||Too many colors in palette||
||ERR_BITMAP_BITS_READ||bitmap bits cannot be read||

==== Remarks ====

It is recommended that bitmaps should have a width that is evenly dividable by 4 such as 24, 32, 64, 68, etc... Otherwise the width will be padded to an even value.

==== Example ====

{{{
CBitmap bitamp;
if(bitmap.LoadBitmap("/mnt/nand/apps/myapp/myapp.bmp") != BITMAP_SUCCESS)
{
    DisplayText(0, 0, "Error loading bitmap");
}

}}}

{{{
PALETTE_ITEM trans;
trans.red = 128;
trans.green = 192;
trans.blue = 192;
trans.alpha = 0;

CBitmap bitamp;
if(bitmap.LoadBitmap("/mnt/nand/apps/myapp/myapp.bmp", &trans) != BITMAP_SUCCESS)
{
    DisplayText(0, 0, "Error loading bitmap");
}
}}}

=== DeleteBitmap ===
Deletes memory in RAM allocated to the bitmap. This does not delete the file.
{{{
void DeleteBitmap(void);
}}}

==== Parameters ====

Function does not accept any parameters

==== Return Value ====
 
Function does not return any result.

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
bitmap.Draw(0, 0);
SleepSeconds(1);
ClearLCD();
bitmap.DeleteBitmap();
}}}

=== Draw ===
Draws the bitmap on the LCD display
{{{
void Draw(int x, int y);
}}}

==== Parameters ====

x - The X coordinate for the left side of the bitmap to be displayed
y - The Y coordinate for the top of the bitmap to be displayed

==== Return Value ====
 
Function does not return any result.

==== Remarks ====

The X coordinate should be at an even four pixel coordinate such as 0, 4, 8, etc... Otherwise the displayed position will be moved to the right to the nearest even four pixel location. 

==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
bitmap.Draw(0, 0);
}}}


=== GetWidth ===
Get the width of the bitmap in pixels
{{{
int GetWidth(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function returns the width of the bitmap in pixels.

==== Remarks ====

Be sure that the InitLCD(1) call at the beginning of the application includes the parameter 1 so that the application will get the graphic data address. Bitmaps will not show if the default InitLCD() is called.

==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int x = bitmap.GetWidth();
}}}


=== GetHeight ===
Get the height of the bitmap in pixels
{{{
int GetHeight(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function returns the height of the bitmap in pixels.

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int y = bitmap.GetHeight();
}}}


=== GetColorCnt ===
Get the number of colors the bitmap uses
{{{
int GetColorCnt(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function returns the number of colors used by the bitmap.

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int n = bitmap.GetColorCnt();
}}}


=== GetColorsAdded ===
Get the numbers of colors added to the 825 global palette when the bitmap was loaded
{{{
int GetColorsAdded(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function returns the number of colors added to the 825 global palette when the bitmap was loaded.

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int n = bitmap.GetColorsAdded();
}}}


=== GetError ===
Get the error code
{{{
int GetError(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function returns the current error code.

||'''Response'''||'''Description'''||
||BITMAP_SUCCESS||Operation successful||
||ERR_BITMAP_FILE_OPEN||file cannot be opened||
||ERR_BITMAP_HEADER_READ||bitmap header cannot be read||
||ERR_BITMAP_INFO_READ||bitmap info cannot be read||
||ERR_BITMAP_SIZE_OR_TYPE||width is greater than 640, height is greater than 480, or bitmap is not 8 bits per pixel||
||ERR_BITMAP_PALETTE_READ||color palette cannot be read||
||ERR_BITMAP_TOO_MANY_COLORS||Too many colors in palette||
||ERR_BITMAP_BITS_READ||bitmap bits cannot be read||
||ERR_BITMAP_DRAW_OFF_SCREEN||Bitmap draw would have placed bitmap off screen or partially off screen||

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int err = bitmap.GetError();
if(err != BITMAP_SUCCESS)
{
   DisplayText(0, 0, "Error loading bitmap");
}
}}}


=== ReclaimColors ===
Reclaim custom colors added by loading bitmaps
{{{
static void ReclaimColors(void);
}}}

==== Parameters ====

Function does not accept any parameters.

==== Return Value ====
 
Function does not return any value.

==== Remarks ====

In 8 bits per pixel mode all bitmaps and text or other graphics on the display at any given time must share a palette of 256 colors. Each color in the palette is a specified RGB (reg, green, blue) color. Loading multiple 8 bit per pixel bitmaps into memory may cause the palette to run out of space to add new colors, LoadBitmap may then error with code -7.

ReclaimColors releases the colors that were added by displaying bitmaps and returns the palette to the default text colors. ReclaimColors should only be called after any bitmaps on the display have been cleared, such as after calling ClearLCD.

==== Example ====

{{{
CBitmap img1("/mnt/nand/apps/myapp/img1.bmp");
CBitmap img2("/mnt/nand/apps/myapp/img2.bmp");
img1.Draw(0, 0);
img2.Draw(320, 0);

SleepSeconds(5);
ClearLCD();
img1.DeleteBitmap();
img2.DeleteBitmap();

CBitmap::ReclaimColors();

CBitmap img3("/mnt/nand/apps/myapp/img3.bmp");
CBitmap img4("/mnt/nand/apps/myapp/img4.bmp");
img3.Draw(0, 0);
img4.Draw(320, 0);
}}}