HAM Documentation

Home · Downloads · Your Account · Submit News

Documentation Homepage HAMLib reference Back to HAM Homepage |

# BG Mode Control Functions

## Functions

void | ham_InitBg (u16 bgno, u16 active, u16 prio, u16 mosaic)
| Initialize a tiled BG for use in HAM.
void | ham_ResetBg ()
| Reinitialize the complete BG system.
void | ham_DeInitBg (u16 bgno)
| Deinitialize a BG again.
u8 | ham_GetBgType (u8 bgno)
| Retrieve if BG is rotation compatible.
void | ham_SetBgMode (u8 bgmode)
| Set the GBA hardware to operate in new BGMode.
void | ham_SetBgVisible (u32 bgno, u32 active)
| Turn a specific BG layer on or off.
void | ham_SetBgXY (u16 bgno, u16 x, u16 y)
| Set the Scroll offset of a BG Layer.

## Detailed Description

This section lists functions that control the BG Mode system of HAMlib. You can Initialize BGs, get the current mode and so on.

## Function Documentation

void ham_DeInitBg | ( | u16 | bgno | ) |

Deinitialize a BG again.

Parameters:

  bgno | The BG number we want to deinitialize (0-3)

This function will free the resources assigned to the bgno . This will only work if the bgno specified was previously initialized using ham_InitBg(). Note that this will also unload the Tileset and Map from that BG and therefore free more RAM.

For more information on tiles and maps, see ham_InitTileSet() , ham_InitMapSet() and ham_InitMapEmptySet()

u8 ham_GetBgType | ( | u8 | bgno | ) |

Retrieve if BG is rotation compatible.

Parameters:

  bgno | The BG number we want to check (0-3)

This will return one of three Values:

- 1 = The BG is rotatable in the BGMode currently set
- 0 = The BG is not rotatable in the BGMode currently set
- 255 = The BG is non existant in the current BGMode

See also: ham_SetBgMode()

void ham_InitBg | ( | u16 | bgno,
|  | u16 | active,
|  | u16 | prio,
|  | u16 | mosaic
| ) |

Initialize a tiled BG for use in HAM.

Parameters:

  bgno | The BG number we want to initialize (0-3)
  active | Turn the BG on or off (0,1)
  prio | Priority of this BG to other BGs (0=highest prio,3=lowest)
  mosaic | Enable / Disable Mosaic for this BG (0=off,1=on)

You can call this function to actually commit this BG to the hardware. This command will throw an error if the BG that you want to init has not yet been assigned a TileSet or MapSet.

A TileSet is a collection of 8*8 pixel Tile graphics that will be used when constructing this BG A MapSet is a collection of data that defines which Tile goes where on the display. See ham_SetMapTile() for information how to later change the tile assignment.

For more information on how to assign these to a BG, see ham_InitTileSet() , ham_InitMapSet() and ham_InitMapEmptySet()

See also: ham_SetMapTile() ham_InitMapSet() ham_InitTileSet() ham_InitMapEmptySet() ham_InitMapFragment()

void ham_ResetBg | ( |  | ) |

Reinitialize the complete BG system.

This function will reset the BG (Tile mode) systems of HAM. It will clear the VRAM for BG and also clear all map and tile assignments for BG0 - BG3. It will not switch to a different BGMode though, this information will persist. The state generated, apart from the BG Mode currently set, equals the initial state when using HAMlib.

See also: ham_ResetObj() ham_InitBg() ham_InitTileSet() , ham_InitMapSet() , ham_InitMapEmptySet()

void ham_SetBgMode | ( | u8 | bgmode | ) |

Set the GBA hardware to operate in new BGMode.

Parameters:

  bgmode | The BGMode we want to set (0-5)

Set a new BGMode in the GBA. All the rendering after setting this Mode will be carried out in this new Mode.

- 0 = Tiled, BG 1-4 all no rot
- 1 = Tiled, BG 1-2 are no rot, 3 is rot, 4 n/a
- 2 = Tiled, BG 1-2 n/a , 3-4 are rot
- 3 = Bitmap, 16bitcol, single buffer
- 4 = Bitmap, 8bitcol, double buffer
- 5 = Bitmap, 16bitcol, double buffer (screensize 160*120)

void ham_SetBgVisible | ( | u32 | bgno,
|  | u32 | active
| ) |

Turn a specific BG layer on or off.

Parameters:

  bgno | The BG number to turn on or off (0-3)

  active

  - 0 = inactive
  - 1 = active

This function will disable/enable the display of a certain BG. Please note that this function is to be used only in BG Mode 0-2 .

See also: ham_SetBgMode() ham_InitBg()

void ham_SetBgXY | ( | u16 | bgno,
|  | u16 | x,
|  | u16 | y
| ) |

Set the Scroll offset of a BG Layer.

Parameters:

  bgno | The BG number we want to scroll
  x | The new X offset value
  y | The new Y offset value

Will immediately scroll the given BG number to the new X and Y values provided. Notice this function does NOT work with rotation BGs.

See also: ham_RotBg() ham_RotBgEx() ham_RotObjDefineSet()

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