Tile Functions

Description. More...

Defines

Functions


Detailed Description

Description.

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.

Note:
Dynamic tile reloading for rotatation maps is not supported.

Define Documentation

#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.

See also:
hel_TileInit


Function Documentation

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.

Parameters:
[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

Note:
Allocating more memory than 1024*3 halfwords for pBufferB is not necessary, because the maximum amount of tile-slots in hardware is 1024.
Attention:
When you deal with 4bit graphics and you use gfx2gba to convert them, specify -b0 for the palette bank. If you don't do this, the graphics will be garbled. Also see MAP_FLAGS_DYNAMICTILERELOADING
See also:
hel_TileDelete, hel_TileShare

void 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.

Parameters:
[in] BgNo Background Number of Tile-System
See also:
hel_TileCreate

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.

Parameters:
[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);

    // ...
}

See also:
hel_TileQuit, hel_TileCreate

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.

Parameters:
[in] BgNo Background Number of Tile-System
[in] RomTileNo The tilenumber to check
Returns:
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.

Parameters:
[in] BgNo Background Number of Tile-System
[in] RomTileNo The tilenumber in ROM to preload
Note:
Preloaded graphics must be manually released when they are no longer needed. Releasing the graphics must be done with hel_TileReleaseGraphic.
See also:
hel_TileReleaseGraphic

void hel_TileQuit ( void   ) 

Uninitialize Tile-System.

The hel_TileQuit function uninitializes all Tile-Systems that have been created using the hel_TileCreate function.

See also:
hel_TileInit, hel_TileCreate, hel_TileDelete

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.

Parameters:
[in] BgNo Background Number of Tile-System
[in] RomTileNo The tilenumber in ROM to release
Note:
Only preloaded graphics must be manually released. If the graphic is used by another tile, it will not be released.
See also:
hel_TilePreloadGraphic

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.

Parameters:
[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.
Note:
Since hel_TileReloadGraphic first checks the colordepth to compute the correct datasize before loading the new tile to vram, this functions is slightly slower than the more specific reloading functions such as hel_TileReloadGraphic16 and hel_TileReloadGraphic256. Before reloading a tile, first check if it is already loaded. In case it is not, you cannot reload it. To check if a tile is loaded, use hel_TileIsGraphicLoaded.
See also:
hel_TileReloadGraphic16, hel_TileReloadGraphic256

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).

Parameters:
[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.
Note:
This function is faster than hel_TileReloadGraphic. Before reloading a tile, first check if it is already loaded. In case it is not, you cannot reload it. To check if a tile is loaded, use hel_TileIsGraphicLoaded.
See also:
hel_TileReloadGraphic, hel_TileReloadGraphic256

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).

Parameters:
[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.
Note:
This function is faster than hel_TileReloadGraphic. Before reloading a tile, first check if it is already loaded. In case it is not, you cannot reload it. To check if a tile is loaded, use hel_TileIsGraphicLoaded.
See also:
hel_TileReloadGraphic, hel_TileReloadGraphic16

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.

Parameters:
[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
  • MAP_DRAWINFOFLAGS_SHOW
Flags:
MAP_DRAWINFOFLAGS_HIDE
If the map-tile at the destination address specified by 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
Use the MAP_DRAWINFOFLAGS_SHOW to let the Tile-System know you want to show and allocate a new slot for the map-tile.

Note:
Because this function wants pointers to the destination and source addresses, it's probably not really obvious how to use it. Here is an example which shows how to use hel_TileSetMapTile using x,y tile coordinates:
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.

Parameters:
[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.
When you no longer need the shared TileSystem, call hel_TileDelete.

Note:
If you share tilesetdata, please keep in mind it is used by at least two backgrounds. This means it will probably display more tiles from the same tileset and therefore the TileSystem needs more tileslots to work with. To increase the tileslots, use NumTilesRam and pBufferB parameter which you pass to hel_TileCreate, when initializing the source tileset.
See also:
hel_TileCreate, hel_TileDelete


Generated on Fri Aug 17 12:12:39 2007 for HEL Library by  doxygen 1.5.3