HAM Documentation

Home · Downloads · Your Account · Submit News

Documentation Homepage HAMLib reference Back to HAM Homepage |

# Tiled Mode Functions

## Functions

void | ham_SetMapTile (u8 bgno, u32 x, u32 y, u32 tileno)
| Set a Tile on a map to any other Tile you want
void | ham_SetMapTileEx (u8 bgno, u32 x, u32 y, u32 tileno, u32 hflip, u32 vflip, u32 palno)
| Set a Tile on a map, and also set flip and palettes for the tile
u16 | ham_GetMapTile (u8 bgno, u8 x, u8 y)
| Return the Tile number on a maps X and Y position
tile_info_ptr | ham_InitTileSet (void *src, u16 size_u16, u8 col_mode, u8 cbb_only_mode)
| Initializes a Tile Set and Loads the Tile GFX into VRAM
tile_info_ptr | ham_InitTileEmptySet (u16 num_tiles, u8 col_mode, u8 cbb_only_mode)
| Initializes an Empty (all transparent) Tile Set
void | ham_ReloadTileGfx (tile_info_ptr ti, u16 *src, u16 target_tileno, u16 num_tiles)
| Reloads parts of a Tileset with new graphics data
void | ham_DeInitTileSet (tile_info_ptr ti)
| Deinitializes a Tile Set and unloads the GFX from GBA VRAM
void | ham_DeInitMapSet (map_info_ptr mi)
| Deinitializes a Map Set and unloads the map information from GBA VRAM
void | ham_DeInitMapFragment (map_fragment_info_ptr mfi)
| Deinitializes a Map Fragment and unloads the map information from GBA RAM
map_info_ptr | ham_InitMapSet (void *src, u16 size_u16, u8 map_size, u8 map_rot)
| Initializes a Map Set and loads it into GBA VRAM
map_fragment_info_ptr | ham_InitMapFragment (void *src, u16 map_total_x, u16 map_total_y, u16 map_ofs_x, u16 map_ofs_y, u8 map_tiles_x, u8 map_tiles_y, u8 map_rot)
| Initializes a Map Fragment (A rectangle within a Map)
void | ham_InsertMapFragment (map_fragment_info_ptr mfi, u8 bgno, u8 x, u8 y)
| Inserts a Map Fragment (A rectangle within a Map) into an onscreen Map
map_info_ptr | ham_InitMapEmptySet (u8 map_size, u8 map_rot)
| Initializes an Empty (all zero) Map Set in GBA VRAM

## Function Documentation

void ham_DeInitMapFragment | ( | map_fragment_info_ptr | mfi | ) |

Deinitializes a Map Fragment and unloads the map information from GBA RAM

Parameters:

  mfi | a pointer to the map_fragment_info structure, previously obtained by calls like ham_InitMapFragment()

This function frees the map fragment info structure and all associated data in VRAM.

See also: ham_InitBg() ham_InitMapFragment()

void ham_DeInitMapSet | ( | map_info_ptr | mi | ) |

Deinitializes a Map Set and unloads the map information from GBA VRAM

Parameters:

  mi | a pointer to the map_info structure, previously obtained by calls like ham_InitMapSet()

This function frees the map info structure and all associated data in VRAM.

See also: ham_InitBg() ham_InitMapSet()

void ham_DeInitTileSet | ( | tile_info_ptr | ti | ) |

Deinitializes a Tile Set and unloads the GFX from GBA VRAM

Parameters:

  ti | a pointer to the tile_info structure, previously obtained by calls like ham_InitTileSet()

This function frees the tile info structure and all associated data in VRAM.

See also: ham_InitBg() ham_InitTileSet()

u16 ham_GetMapTile | ( | u8 | bgno,
|  | u8 | x,
|  | u8 | y
| ) |

Return the Tile number on a maps X and Y position

Parameters:

  bgno | The bgno (0-3) you want to get the Tile number from
  x | The tile index in x direction where the tile is to be gathered from
  y | The tile index in y direction where the tile is to be gathered from

This function will return the tiles index number for the specified BG number and position.

Attention: The BG this is used on needs to be set up using ham_InitBg() for this function to work.

See also: ham_InitBg()

map_info_ptr ham_InitMapEmptySet | ( | u8 | map_size,
|  | u8 | map_rot
| ) |

Initializes an Empty (all zero) Map Set in GBA VRAM

Parameters:

  map_size

  the size of the map (0-3). This depends on the map_rot parameter!
  - if map_rot is 0:
    - 0 = 32*32 tiles (256*256 screen)
    - 1 = 64*32 tiles (512*256 screen)
    - 2 = 32*64 tiles (256*512 screen)
    - 3 = 64*64 tiles (512*512 screen)
  - if map_rot is 1:
    - 0 = 16*16 tiles (128*128 screen)
    - 1 = 32*32 tiles (256*256 screen)
    - 2 = 64*64 tiles (512*512 screen)
    - 3 = 128*128 tiles (1024*1024 screen)

Parameters:

  map_rot

  - 0 = no rotation map
  - 1 = rotation map determines if this is a map for a rotation screen. Please make sure that the map data you will load corresponds to the map type you set, as the data format for rotation maps is different than for non rotating maps. See the gfx2gba documentation for details how to correctly export map data.

This function will load an empty (all zero) map and copy it into an appropiate spot in the GBAs BG VRAM. The spot is decided by the memory manager, and passed back in the structure. Returns a pointer to a new structure of type map_info that contains all the neccessary data for the new map getting linked to the BG.

YOu can then for example populate this empty map with ham_InsertMapFragment() .

See also: ham_InitBg() ham_DeInitMapSet() ham_InsertMapFragment()

map_fragment_info_ptr ham_InitMapFragment | ( | void * | src,
|  | u16 | map_total_x,
|  | u16 | map_total_y,
|  | u16 | map_ofs_x,
|  | u16 | map_ofs_y,
|  | u8 | map_tiles_x,
|  | u8 | map_tiles_y,
|  | u8 | map_rot
| ) |

Initializes a Map Fragment (A rectangle within a Map)

Parameters:

  src | A pointer to the source data for the map we want to create the Map Fragment from, usually in ROM.
  map_total_x | the total width of the map you are pointing to in tiles.
  map_total_y | the total height of the map you are pointing to in tiles.
  map_ofs_x | the horizontal offset, in tiles, on the map you want to start copying from
  map_ofs_y | the vertical offset, in tiles, on the map you want to start copying from
  map_tiles_x | the number of tiles (from the offset on) you want to specify horizontally
  map_tiles_y | the number of tiles (from the offset on) you want to specify vertically

  map_rot

  - 0 = no rotation map
  - 1 = rotation map

This function will allocate a new structure that can be used to reference the map data (usually in ROM) for rectangle copies onto a map currently on screen. Returns a pointer to a new structure of type map_fragment_info that contains all the neccessary data for further operations, such as copying this part of the ROM map onto an existing screen map using ham_InsertMapFragment()

See also: ham_DeInitMapFragment() ham_InsertMapFragment()

map_info_ptr ham_InitMapSet | ( | void * | src,
|  | u16 | size_u16,
|  | u8 | map_size,
|  | u8 | map_rot
| ) |

Initializes a Map Set and loads it into GBA VRAM

Parameters:

  src | A pointer to the source data, usually in ROM.
  size_u16 | The size of the map to be copied into BG RAM, in number of 16bit chunks

  map_size

  the size of the map (0-3). This depends on the map_rot parameter!
  - if map_rot is 0:
    - 0 = 32*32 tiles (256*256 screen)
    - 1 = 64*32 tiles (512*256 screen)
    - 2 = 32*64 tiles (256*512 screen)
    - 3 = 64*64 tiles (512*512 screen)
  - if map_rot is 1:
    - 0 = 16*16 tiles (128*128 screen)
    - 1 = 32*32 tiles (256*256 screen)
    - 2 = 64*64 tiles (512*512 screen)
    - 3 = 128*128 tiles (1024*1024 screen)

Parameters:

  map_rot

  - 0 = no rotation map
  - 1 = rotation map determines if this is a map for a rotation screen. Please make sure that the map data you will load corresponds to the map type you set, as the data format for rotation maps is different than for non rotating maps. See the gfx2gba documentation for details how to correctly export map data.

This function will load a map (usually from ROM) from the src pointer and copy it into an appropiate spot in the GBAs BG VRAM. The spot is decided by the memory manager, and passed back in the structure. Returns a pointer to a new structure of type map_info that contains all the neccessary data for getting linked to the BG.

See also: ham_InitBg() ham_DeInitMapSet()

tile_info_ptr ham_InitTileEmptySet | ( | u16 | num_tiles,
|  | u8 | col_mode,
|  | u8 | cbb_only_mode
| ) |

Initializes an Empty (all transparent) Tile Set

Parameters:

  num_tiles | The number of tiles to reserve in the empty tileset
  col_mode | The Color mode of the tile set: 0 = 16colors/16 palettes 1 = 256 colors / 1palette

  cbb_only_mode

  Setting this one requires a bit of understanding of the GBA hardware. Basically, if you put tiles into the GBA memory, you will have to put them at the start of a Character Base block in order to be able to access tile #0 with a map entry of 0. If the allocated block is not directly at the start of a CBB, you will have to offset your map entries. This is automatically done for you when you use ham_SetMapTile. However, when you load your map from ROM, you might want to align your tileset to a CBB boundary. If in doubt, and you have some VRAM left, set this to 1 always.
  - 0=allocate at the earliest possible spot, unsafe if you do not know / do not want to offset your map entries!
  - 1=allocate only on a CBB start to ensure tile 0 is map index no 0. Again, if you have no idea what this is, set it to 1.

This function will create a tile set of the requested size in BG VRAM and set it to all transparent tiles. You can then use the ham_ReloadTileGfx() function to populate this tileset.

See also: ham_ReloadTileGfx() ham_InitBg()

tile_info_ptr ham_InitTileSet | ( | void * | src,
|  | u16 | size_u16,
|  | u8 | col_mode,
|  | u8 | cbb_only_mode
| ) |

Initializes a Tile Set and Loads the Tile GFX into VRAM

Parameters:

  src | a pointer to the source data
  size_u16 | the size of the tiles to be copied into Tile RAM, in number of 16bit chunks
  col_mode | The Color mode of the tile set: 0 = 16colors/16 palettes 1 = 256 colors / 1palette

  cbb_only_mode

  Setting this one requires a bit of understanding of the GBA hardware. Basically, if you put tiles into the GBA memory, you will have to put them at the start of a Character Base block in order to be able to access tile #0 with a map entry of 0. If the allocated block is not directly at the start of a CBB, you will have to offset your map entries. This is automatically done for you when you use ham_SetMapTile. However, when you load your map from ROM, you might want to align your tileset to a CBB boundary. If in doubt, and you have some VRAM left, set this to 1 always.
  - 0=allocate at the earliest possible spot, unsafe if you do not know / do not want to offset your map entries!
  - 1=allocate only on a CBB start to ensure tile 0 is map index no 0. Again, if you have no idea what this is, set it to 1.

This function will load a tileset (usually from ROM) from the src pointer and copy it into an appropiate spot in the GBAs BG VRAM. The spot is decided by the memory manager, and passed back in the structure. Returns a pointer to a new structure of type tile_info that contains all the neccessary data for getting linked to the BG.

See also: ham_InitBg()

void ham_InsertMapFragment | ( | map_fragment_info_ptr | mfi,
|  | u8 | bgno,
|  | u8 | x,
|  | u8 | y
| ) |

Inserts a Map Fragment (A rectangle within a Map) into an onscreen Map

Parameters:

  mfi | a map fragment info pointer previously created by ham_InitMapFragment
  bgno | the BG number you want to Insert the map fragment on (0-3)
  x | The X position (in tiles) in the BG map where you want the Fragment to be placed
  y | The Y position (in tiles) in the BG map where you want the Fragment to be placed

This will copy the map from the Map Fragment onto the BG Map currently used by the BG specified at a location the user chooses with the x and y parameters.

See also: ham_DeInitMapFragment() ham_InitMapFragment()

void ham_ReloadTileGfx | ( | tile_info_ptr | ti,
|  | u16 * | src,
|  | u16 | target_tileno,
|  | u16 | num_tiles
| ) |

Reloads parts of a Tileset with new graphics data

Parameters:

  ti | The tileset which you want to load new graphics data into
  src | A pointer to the tile graphics data you want to load
  target_tileno | The tile number in the target tileset where you want to start loading tile graphics
  num_tiles | The number of tiles you want to transfer to the tileset

See also: ham_InitTileEmptySet() ham_InitTileSet()

void ham_SetMapTile | ( | u8 | bgno,
|  | u32 | x,
|  | u32 | y,
|  | u32 | tileno
| ) | `[inline]`

Set a Tile on a map to any other Tile you want

Parameters:

  bgno | The bgno (0-3) you want to set the Tile on
  x | The tile index in x direction where the tile is to be placed in
  y | The tile index in y direction where the tile is to be placed in
  tileno | The Tiles number itself.

The tileset that is used when choosing a tile number is determined by the Tileset defined with ham_InitTileSet(). Also note that the tileset needs to be attached to the BG first. See ham_InitBg() for details.

Attention: The BG this is used on needs to be set up using ham_InitBg() for this function to work.

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

void ham_SetMapTileEx | ( | u8 | bgno,
|  | u32 | x,
|  | u32 | y,
|  | u32 | tileno,
|  | u32 | hflip,
|  | u32 | vflip,
|  | u32 | palno
| ) | `[inline]`

Set a Tile on a map, and also set flip and palettes for the tile

Parameters:

  bgno | The bgno (0-3) you want to set the Tile on
  x | The tile index in x direction where the tile is to be placed in
  y | The tile index in y direction where the tile is to be placed in
  tileno | The Tiles number itself.
  hflip | The horizontal flip bit for this tile (0=no flip, 1=flip)
  vflip | The vertical flip bit for this tile (0=no flip, 1=flip)
  palno | The palette number 0-15 if in 16 color mode.

The tileset that is used when choosing a tile number is determined by the Tileset defined with ham_InitTileSet(). Also note that the tileset needs to be attached to the BG first. See ham_InitBg() for details.

Attention: The BG this is used on needs to be set up using ham_InitBg() for this function to work.

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

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