HEL's tile-system implementation dynamically reloads tile graphics and can therefore bypass the hardware limit of 1024 tiles which allows you to design more extended levels. The maximum amount of tiles what can be handled by HEL's tile-system is 32767
tiles. A few functions of HEL's tile-system are located in IWRAM, because they have to be fast.
HEL's tile-system does not dynamically allocate any memory. You have to pass allocated buffers instead. This option allows to use an own memory manager, in case it is necessary.
It can share tileset data between backgrounds. This is useful if you have one (huge) tileset which is used by several backgrounds. When you share 16 color graphics, you can specify a different palette number for the shared data. This makes it possible to use the same tileset with different colors.
It comes with a function to check if specific tiles are loaded to Vram and reload their graphics to perform tileanimations.
16 and 256 color graphics are supported, all associated calculations are done for you automatically. You only have to pass the colormode when initializing the tile-system.
In debugmode it displays an errormessage when it tries to load a new tile into Vram but cannot find enough space.
#define HEL_SUBSYSTEM_TILE_REQUIREDMEMORY |
Required memory for the Tile System.
This define represents the amount of memory, specified in bytes, the Tile System from HEL requires to manage its internal states. When you initialize the Tile System, you must pass a buffer which equals the size of HEL_SUBSYSTEM_TILE_REQUIREDMEMORY.
void hel_TileCreate | ( | u32 | BgNo, | |
const u8 * | pTileData, | |||
u16 | NumTilesRom, | |||
u16 * | pBufferA, | |||
u16 | NumTilesRam, | |||
u16 * | pBufferB, | |||
u8 | ColMode, | |||
u8 | PalNo, | |||
u8 | CbbOnlyMode | |||
) |
Create a Tile-System.
[in] | BgNo | Background Number |
[in] | pTileData | Pointer to source tilesetdata. |
[in] | NumTilesRom | Amount of tiles in the source tileset. |
[in] | pBufferA | A buffer of NumTilesRom allocated halfwords (u16's). pBufferA should be located in EWRAM . |
[in] | NumTilesRam | Amount of tiles you want to use in videoram. It's the maximum amount of tiles what can be displayed at the same time. For example, the screen consists entirely of unique tiles, then NumTilesRam has to be set to 31*21. 31 equals the display width in tiles, extended by one. 21 equals the display height in tiles, also extended by one. |
[in] | pBufferB | A buffer of NumTilesRam*3 allocated halfwords (u16's). pBufferB should be located in EWRAM . |
[in] | ColMode | Colormode of pTileData . Set it to COLORS_16 when using 4bit graphics, otherwise to COLORS_256. |
[in] | PalNo | When using 4bit graphics, set PalNo to palette number the graphic uses, otherwise set it to 0. |
[in] | CbbOnlyMode | Please consult your HAM documentation, see ham_InitTileSet |
#define RAM_SLOTS (224) u16 ATTR_EWRAM BufferA[451]; u16 ATTR_EWRAM BufferB[RAM_SLOTS*3]; hel_TileCreate ( 0, // BgNo world_Tiles, // Source GraphicData (Tileset) SIZEOF_16BIT(BufferA), // Amount of tiles in GraphicData BufferA, // BufferA RAM_SLOTS, // Amount of tiles to use in videoram BufferB, // BufferB COLORS_256, // Colormode (COLORS_256 or COLORS_16) 0, // Palettenumber (0..15) TRUE // CbbOnlyMode ); // Create a Map here and enable dynamic tile reloading // This can be done with #hel_MapCreate and #hel_MapCreateIndirect
pBufferB
is not necessary, because the maximum amount of tile-slots in hardware is 1024.-b0
for the palette bank. If you don't do this, the graphics will be garbled. Also see MAP_FLAGS_DYNAMICTILERELOADINGvoid hel_TileDelete | ( | u32 | BgNo | ) |
Delete a Tile-System.
The hel_TileDelete function deletes the tile system for the background specified by BgNo. If the tileset is shared with more backgrounds, the tileset gets released when all tile-systems, which are using it, have been deleted.
[in] | BgNo | Background Number of Tile-System |
void hel_TileInit | ( | void * | pBuffer | ) |
Initialize Tile-System.
Call this function before using any other function from the Tile System Module. If you don't initialize the Tile-System, the program behaviour is undefined.
[in] | pBuffer | Must point to a buffer of at least HEL_SUBSYSTEM_TILE_REQUIREDMEMORY allocated bytes. The buffer must be word-aligned and should be located in EWRAM. It must not be changed after initialization as long as the Tile System is running! |
// Allocate memory for Tile-System u8 ATTR_EWRAM ATTR_ALIGNED(4) g_TileSystemBuffer[HEL_SUBSYSTEM_TILE_REQUIREDMEMORY]; int main(void) { // Initialize Tile-System hel_TileInit((void*)g_TileSystemBuffer); // ... }
u32 hel_TileIsGraphicLoaded | ( | u32 | BgNo, | |
u32 | RomTileNo | |||
) |
Check if a graphic is loaded.
The hel_TileIsGraphicLoaded function can be used to check if a tile is currently loaded or not.
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber to check |
TRUE
if loaded, otherwise FALSE
void hel_TilePreloadGraphic | ( | u32 | BgNo, | |
u32 | RomTileNo | |||
) |
Preload a graphic.
The hel_TilePreloadGraphic function loads the graphic for the tile referenced by RomTileNo
to Vram.
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber in ROM to preload |
void hel_TileQuit | ( | void | ) |
Uninitialize Tile-System.
The hel_TileQuit function uninitializes all Tile-Systems that have been created using the hel_TileCreate function.
void hel_TileReleaseGraphic | ( | u32 | BgNo, | |
u32 | RomTileNo | |||
) |
Release a graphic.
The hel_TileReleaseGraphic function releases the graphic for the tile referenced by RomTileNo
in Vram.
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber in ROM to release |
void hel_TileReloadGraphic | ( | u32 | BgNo, | |
u32 | RomTileNo, | |||
const u8 * | pSource | |||
) |
Reload tile-graphic(s).
The hel_TileReloadGraphic can be used to reload the graphic for a given tile with either 4bit or 8bit color depth.
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber for what you want to reload the graphic. |
[in] | pSource | Pointer to source graphicdata. |
void hel_TileReloadGraphic16 | ( | u32 | BgNo, | |
u32 | RomTileNo, | |||
const u8 * | pSource | |||
) |
Reload 4bit tile-graphic(s).
The hel_TileReloadGraphic16 can be used to reload the graphic for a given tile with 4bit colordepth (16 colors).
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber for what you want to reload the graphic. |
[in] | pSource | Pointer to source graphicdata. |
void hel_TileReloadGraphic256 | ( | u32 | BgNo, | |
u32 | RomTileNo, | |||
const u8 * | pSource | |||
) |
Reload 8bit tile-graphic(s).
The hel_TileReloadGraphic256 can be used to reload the graphic for a given tile with 8bit colordepth (16 colors).
[in] | BgNo | Background Number of Tile-System |
[in] | RomTileNo | The tilenumber for what you want to reload the graphic. |
[in] | pSource | Pointer to source graphics. |
void ATTR_FASTFUNC ATTR_NOINSTRUMENT hel_TileSetMapTile | ( | u32 | BgNo, | |
u16 * | pDest, | |||
const void * | pSource, | |||
u32 | Flags | |||
) |
Set a map tile.
The hel_TileSetMapTile function can be used to set a tile in a map Vram using the Dynamic-Tile-Reloading feature from HEL Library.
[in] | BgNo | Background Number of Tile-System |
[in] | pDest | Pointer to destination map-tile in Vram |
[in] | pSource | Pointer to source map-tile |
[in] | Flags | Flags to control what actions to execute while setting a map-tile. Can be a combination of the following values:
|
MAP_DRAWINFOFLAGS_HIDE
pDest
has been already set using the hel_TileSetMapTile function, it must be hidden before assigning a new map-tile. This can be done by specifying the MAP_DRAWINFOFLAGS_HIDE
flag.
MAP_DRAWINFOFLAGS_SHOW
MAP_DRAWINFOFLAGS_SHOW
to let the Tile-System know you want to show and allocate a new slot for the map-tile.
void Tile_SetMapTileWrapper(u32 BgNo, u32 x, u32 y, u16 TileNo) { // Get Target screen-base-block of map u32 ScreenBlockBase = MEM_SCR_BB(ham_bg[BgNo].mi->first_block); // Compute offset to target tile in Vram u32 Offset = ((ham_bg[BgNo].mi->map_x * y) + x) * sizeof(u16); // Replace the map tile at specified x,y position. // It keeps track of tile allocating and freeing! // This example assumes a tile at the target address // has been already set using hel_TileSetMapTile. Otherwise // don't pass MAP_DRAWINFOFLAGS_HIDE flag. hel_TileSetMapTile ( BgNo, // BgNo (u16*)(ScreenBlockBase+Offset), // Target &TileNo, // Source MAP_DRAWINFOFLAGS_HIDE|MAP_DRAWINFOFLAGS_SHOW // Flags ); }
void hel_TileShare | ( | u32 | TargetBgNo, | |
u32 | SourceBgNo, | |||
u8 | PalNo | |||
) |
Share tilesetdata.
The hel_TileShare function can be used to share tilesetdata. This is useful if you have one tileset which is used by several backgrounds. Instead of initializing for each background an own TileSystem, you can (re)use the tilesetdata of an existing Tile System.
[in] | TargetBgNo | Target, this is the background number which receives the tilesetdata. |
[in] | SourceBgNo | Source, this is the background number which provides the tilesetdata. |
[in] | PalNo | Palettenumber the target background should use. This makes it possible to use the same tilesetdata, but with different colors for each background. If you share 256 color graphics, set it to 0, otherwise to a palettenumber between 0 and 15. |
NumTilesRam
and pBufferB
parameter which you pass to hel_TileCreate, when initializing the source tileset.