HAM Documentation

Home · Downloads · Your Account · Submit News

Documentation Homepage HAMLib reference Back to HAM Homepage |

# Bitmap Mode Functions

## Functions

void | ham_ClearBackBuffer (u32 col_value)
| Set the back buffer to a given color value.
void | ham_PutPixel (u32 x, u32 y, u32 col_value)
| Plot a single Pixel in Bitmap Mode.
void | ham_PutLine (s16 x1, s16 y1, s16 x2, s16 y2, u16 col_value)
| Plot a straight line in Bitmap modes.
void | ham_LoadBitmap (void *src)
| Load a Bitmap into the Video RAM.
void | ham_FlipBGBuffer ()
| Flip the back buffer with the front (currently shown) buffer.
u8 | ham_GetBGBuffer ()
| Get the current buffer number in BGmodes 4 and 5.

## Detailed Description

This section contains all Bitmap Mode (BG Mode 3,4,5) functions that are available in HAM. Please note that these functions will not behave correctly in Tiled Display Modes 0,1,2.

## Function Documentation

void ham_ClearBackBuffer | ( | u32 | col_value | ) |

Set the back buffer to a given color value.

Parameters:

  col_value | The color value you want to fill the buffer with

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

This function will clear the current back buffer with the given col_value . A back buffer is only available in BGMode 4 and 5, and therefore this function should only be used in these display modes.

void ham_FlipBGBuffer | ( |  | ) |

Flip the back buffer with the front (currently shown) buffer.

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

When you use other Bitmap mode functions, they will always draw to the Back Buffer. This function will flip this Back Buffer to the Front Buffer. All subsequent drawing will then be done on the new back buffer, and the new front buffer is displayed on the GBA screen.

u8 ham_GetBGBuffer | ( |  | ) |

Get the current buffer number in BGmodes 4 and 5.

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

This function returns:

- 0 if the currently displayed buffer is 0. This means that the VideoRAM displayed starts at 0x06000000 and all Bitmap Mode Functions operate on the buffer at 0x0600A000
- 1 if the currently displayed buffer is 1. This means that the VideoRAM displayed starts at 0x0600A000 and all Bitmap Mode Functions operate on the buffer at 0x06000000

void ham_LoadBitmap | ( | void * | src | ) |

Load a Bitmap into the Video RAM.

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

This function will load a bitmap graphic (converted into GBA format with tools suchas GFX2GBA) into the Video display of the GBA. The type of graphic that is to be loaded is determined by the current display mode. See ham_SetBgMode() for specifics how to set the BGMode. It expects a pointer to the bitmap that is to be loaded:

- Mode 3 : 240*160 15bit GBA format (will immediately display after loaded)
- Mode 4 : 240*160 8 bit GBA palettized format (will be loaded into the backbuffer, see ham_FlipBGBuffer() for how to show it)
- Mode 5 : 160*120 15bit GBA format (will be loaded into the backbuffer, see ham_FlipBGBuffer() for how to show it)

Please note that you also have to load a palette in Mode 4 , using ham_LoadBGPal256() or ham_LoadBGPal()

void ham_PutLine | ( | s16 | x1,
|  | s16 | y1,
|  | s16 | x2,
|  | s16 | y2,
|  | u16 | col_value
| ) |

Plot a straight line in Bitmap modes.

Parameters:

  x1 | X start coordinate for the line
  y1 | Y start coordinate for the line
  x2 | X end coordinate for the line
  y2 | Y end coordinate for the line
  col_value | Color Value of the Line (Either Palette Number or RGB value)

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

This will draw a Line in Bitmap Modes 3,4 and 5. It uses an implementation of the Bresenham line algorithm. Depending on the Mode you need to supply it with a palette entry number (256 color modes) or a 15bit GBA RGB value. This function is not the fastest line plotter on earth since it is very flexible and uses subsequent calls to ham_PutPixel() to generate the lines.

void ham_PutPixel | ( | u32 | x,
|  | u32 | y,
|  | u32 | col_value
| ) |

Plot a single Pixel in Bitmap Mode.

Parameters:

  x | X Position of the Pixel to be Plotted
  y | Y Position of the Pixel to be Plotted
  col_value | Color Value of the Pixel (Either Palette Number or RGB value)

Warning:
  does not work in tiled modes. See ham_SetBgMode() for changing the display mode.

This function plots a single pixel of the desired color onto the display. This function works with all Bitmap BGModes. Depending on the Mode you need to supply it with a palette entry number (256 color modes) or a 15bit GBA RGB value. The color value given will be written into VRAM at the appropiate location.

If you are in a bitmap mode with Backbuffer capability, ham_PutPixel() will always draw into the buffer currently being the back buffer. To flip back buffers, use ham_FlipBGBuffer()

Documentation Homepage | HAMLib reference | Back to HAM Homepage
documentation created with Doxygen