[[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);
int LoadBitmap(const char* pszFilename);
}}}

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

==== Return Value ====

0 successful
-2 file cannot be opened
-3 bitmap header cannot be read
-4 bitmap info cannot be read
-5 width is greater than 640, height is greater than 480, or bitmap is not 8 bits per pixel.
-6 color palette cannot be read
-7 Too many colors in palette

==== Remarks ====

==== Example ====

{{{
CBitmap bitamp;
if(bitmap.LoadBitmap("/mnt/nand/apps/myapp/myapp.bmp") != 0)
{
    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 ====


==== 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 ====


==== 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.
0 successful
-2 file cannot be opened
-3 bitmap header cannot be read
-4 bitmap info cannot be read
-5 width is greater than 640, height is greater than 480, or bitmap is not 8 bits per pixel.
-6 color palette cannot be read
-7 Too many colors in palette

-10 Draw attempted that would place bitmap off screen or partially off screen.

==== Remarks ====


==== Example ====

{{{
CBitmap bitmap("/mnt/nand/apps/myapp/myapp.bmp");
int err = bitmap.GetError();
if(err != 0)
{
   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);
}}}