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