NightFox’s Lib
Data Structures | Macros | Functions | Variables
Functions related to regular tiled backgrounds.

Functions related to regular (non-affine) tiled backgrounds. More...

Data Structures

struct  NF_TYPE_TBG_INFO
 Struct that holds information about regular tiled backgrounds. More...
 
struct  NF_TYPE_EXBGPAL_INFO
 Struct that holds information about extended palettes. More...
 
struct  NF_TYPE_TBGLAYERS_INFO
 Struct that holds information about backgrounds loaded to the screen. More...
 

Macros

#define NF_SLOTS_TBG   64
 Maximum number of slots of tiled backgrounds.
 
#define NF_SLOTS_EXBGPAL   128
 Maximum number of slots for extended palettes (max 16 per background)
 
#define NF_MAX_BANKS_TILES   8
 Maxmimum number of VRAM blocks used for tilesets.
 
#define NF_MAX_BANKS_MAPS   16
 Maxmimum number of VRAM blocks used for maps.
 

Functions

void NF_InitTiledBgBuffers (void)
 Initialize library to load files from the filesystem to create tiled BGs. More...
 
void NF_ResetTiledBgBuffers (void)
 Reset state used for tiled BGs loaded from FAT. More...
 
void NF_InitTiledBgSys (int screen)
 Initialize the tiled BG engine of the selected screen. More...
 
void NF_LoadTiledBg (const char *file, const char *name, u32 width, u32 height)
 Load all files needed to create a tiled BG from FAT to RAM. More...
 
void NF_LoadTilesForBg (const char *file, const char *name, u32 width, u32 height, u32 tile_start, u32 tile_end)
 Load a tilesed and palette from FAT to RAM. More...
 
void NF_UnloadTiledBg (const char *name)
 Delete from RAM the BG with the specified name. More...
 
void NF_CreateTiledBg (int screen, u32 layer, const char *name)
 Create a BG on the screen, using data loaded in RAM. More...
 
void NF_DeleteTiledBg (int screen, u32 layer)
 Delete the BG of the specified screen and layer. More...
 
u32 NF_GetTileMapAddress (int screen, u32 layer, u32 tile_x, u32 tile_y)
 Gets the address of the tile at the specified position. More...
 
u32 NF_GetTileOfMap (int screen, u32 layer, u32 tile_x, u32 tile_y)
 Gets the value of the tile at the specified position. More...
 
void NF_SetTileOfMap (int screen, u32 layer, u32 tile_x, u32 tile_y, u32 tile)
 Sets the value of the tile at the specified position. More...
 
void NF_UpdateVramMap (int screen, u32 layer)
 Updates the map of the specified screen and layer specified. More...
 
void NF_BgSetPalColor (int screen, u32 layer, u32 number, u32 r, u32 g, u32 b)
 Changes the value of one color of the palette of a background. More...
 
void NF_BgEditPalColor (int screen, u32 layer, u32 number, u32 r, u32 g, u32 b)
 Changes the value of one color of the palete of the specified background. More...
 
void NF_BgUpdatePalette (int screen, u32 layer)
 Updates the palette of a background from RAM to VRAM. More...
 
void NF_BgGetPalColor (int screen, u32 layer, u32 number, u8 *r, u8 *g, u8 *b)
 Gets the RGB value of a color of the palette of the selected background, which is loaded in RAM. More...
 
u32 NF_GetTilePal (int screen, u32 layer, u32 tile_x, u32 tile_y)
 Returns the number of extended palette used by specified tile. More...
 
void NF_SetTilePal (int screen, u32 layer, u32 tile_x, u32 tile_y, u32 pal)
 Sets the extended palette to use for the tile especified. More...
 
void NF_LoadExBgPal (const char *file, u32 slot)
 Load a palette from a file to RAM to use it as a background extended palette. More...
 
void NF_UnloadExBgPal (u32 slot)
 Deletes a loaded palette from RAM. More...
 
void NF_VramExBgPal (int screen, u32 layer, u32 id, u32 slot)
 Transfers a palette from RAM to VRAM to be used as extended palette. More...
 
void NF_SetExBgPal (int screen, u32 layer, u32 pal)
 Sets the extended palette to be used in the specified background. More...
 
void NF_SetTileHflip (int screen, u32 layer, u32 tile_x, u32 tile_y)
 Inverts the horizontal flip status of a tile in the specified map. More...
 
void NF_SetTileVflip (int screen, u32 layer, u32 tile_x, u32 tile_y)
 Inverts the vertical flip status of a tile in the specified map. More...
 
void NF_RotateTileGfx (u32 slot, u32 tile, u32 rotation)
 Rotates the graphics of a tile in RAM by the specified angle. More...
 

Variables

u8 NF_BANKS_TILES [2]
 Maxmimum number of tile banks. More...
 
u8 NF_BANKS_MAPS [2]
 Maxmimum number of map banks. More...
 
char * NF_BUFFER_BGTILES [NF_SLOTS_TBG]
 Buffers to hold background tiles.
 
char * NF_BUFFER_BGMAP [NF_SLOTS_TBG]
 Buffers to hold background maps.
 
char * NF_BUFFER_BGPAL [NF_SLOTS_TBG]
 Buffers to hold background palettes.
 
NF_TYPE_TBG_INFO NF_TILEDBG [NF_SLOTS_TBG]
 Information of all tiled backgrounds.
 
NF_TYPE_EXBGPAL_INFO NF_EXBGPAL [NF_SLOTS_EXBGPAL]
 Information of all extended palettes.
 
NF_TYPE_TBGLAYERS_INFO NF_TILEDBG_LAYERS [2][4]
 Information of all backgrounds loaded to the screen.
 
u8 NF_TILEBLOCKS [2][NF_MAX_BANKS_TILES]
 Array of free blocks used for tiles.
 
u8 NF_MAPBLOCKS [2][NF_MAX_BANKS_MAPS]
 Array of free blocks used for maps.
 

Detailed Description

Functions related to regular (non-affine) tiled backgrounds.

Function Documentation

◆ NF_BgEditPalColor()

void NF_BgEditPalColor ( int  screen,
u32  layer,
u32  number,
u32  r,
u32  g,
u32  b 
)

Changes the value of one color of the palete of the specified background.

The change is made in the RAM copy of the palette, so you won't see any change until you update it on VRAM with NF_BgUpdatePalette().

Use this function to make cool effect on your tiled backgrounds.

Example:

// Set color 1 of the palette of layer 3 on top screen to red
NF_BgSetPalColor(0, 3, 1, 31, 0, 0);
void NF_BgSetPalColor(int screen, u32 layer, u32 number, u32 r, u32 g, u32 b)
Changes the value of one color of the palette of a background.
Definition: nf_tiledbg.c:840
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_BgGetPalColor()

void NF_BgGetPalColor ( int  screen,
u32  layer,
u32  number,
u8 *  r,
u8 *  g,
u8 *  b 
)

Gets the RGB value of a color of the palette of the selected background, which is loaded in RAM.

Example:

// Gets the RGB value of color number 200 of layer 3 of the bottom screen,
// stores it in the "red", "green" and "blue" variables.
u8 red;
u8 green;
u8 blue;
NF_BgGetPalColor(1, 3, 200, &red, &green, &blue);
void NF_BgGetPalColor(int screen, u32 layer, u32 number, u8 *r, u8 *g, u8 *b)
Gets the RGB value of a color of the palette of the selected background, which is loaded in RAM.
Definition: nf_tiledbg.c:918
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
numberColor number (0 - 255).
rRed component result (0 - 31).
gGreen component result (0 - 31).
bBlue component result (0 - 31).

◆ NF_BgSetPalColor()

void NF_BgSetPalColor ( int  screen,
u32  layer,
u32  number,
u32  r,
u32  g,
u32  b 
)

Changes the value of one color of the palette of a background.

The change is made directly in VRAM, so it may be overwritten from the copy in RAM. It's also a very slow function, use it twice or 3 times per frame.

Example:

// Change the value of color 1 of the palette of layer 3 on top screen to
// red. If this layer is a text layer with the default font, the text
// becomes red.
NF_BgSetPalColor(0, 3, 1, 31, 0, 0);
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_BgUpdatePalette()

void NF_BgUpdatePalette ( int  screen,
u32  layer 
)

Updates the palette of a background from RAM to VRAM.

Example:

// Updates the palette of layer 2 of the bottom screen
void NF_BgUpdatePalette(int screen, u32 layer)
Updates the palette of a background from RAM to VRAM.
Definition: nf_tiledbg.c:889
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).

◆ NF_CreateTiledBg()

void NF_CreateTiledBg ( int  screen,
u32  layer,
const char *  name 
)

Create a BG on the screen, using data loaded in RAM.

This function copies to VRAM all required data. Before you create the BG, you must load data to RAM using NF_LoadTiledBg(). The BG is created on the specified screen and layer.

Example:

// Create a tiled BG on layer 3 of screen 0, using the BG called "mifondo"
NF_CreateTiledBg(0, 3, "mifondo");
void NF_CreateTiledBg(int screen, u32 layer, const char *name)
Create a BG on the screen, using data loaded in RAM.
Definition: nf_tiledbg.c:342
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
nameName used for the BG.

◆ NF_DeleteTiledBg()

void NF_DeleteTiledBg ( int  screen,
u32  layer 
)

Delete the BG of the specified screen and layer.

This also deletes from VRAM the data used by this BG.

Example:

// Deletes the tiled BG from layer 3 of screen 0
void NF_DeleteTiledBg(int screen, u32 layer)
Delete the BG of the specified screen and layer.
Definition: nf_tiledbg.c:639
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).

◆ NF_GetTileMapAddress()

u32 NF_GetTileMapAddress ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y 
)

Gets the address of the tile at the specified position.

Internal use.

Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.
Returns
Tile address.

◆ NF_GetTileOfMap()

u32 NF_GetTileOfMap ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y 
)

Gets the value of the tile at the specified position.

Example:

// Gets the value of the tile at (20, 10) of the map loaded on screen 0,
// layer 2.
u16 mytile = NF_GetTileOfMap(0, 2, 10, 20);
u32 NF_GetTileOfMap(int screen, u32 layer, u32 tile_x, u32 tile_y)
Gets the value of the tile at the specified position.
Definition: nf_tiledbg.c:747
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.
Returns
Tile index.

◆ NF_GetTilePal()

u32 NF_GetTilePal ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y 
)

Returns the number of extended palette used by specified tile.

By default, all tiles use extended palette 0.

Example:

// Returns the extended palette used by tile in position (20, 10) of layer 3
// of the top screen
palette = NF_GetTilePal(0, 3, 20, 10);
u32 NF_GetTilePal(int screen, u32 layer, u32 tile_x, u32 tile_y)
Returns the number of extended palette used by specified tile.
Definition: nf_tiledbg.c:939
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.
Returns
Extended palette index (0 - 15).

◆ NF_InitTiledBgBuffers()

void NF_InitTiledBgBuffers ( void  )

Initialize library to load files from the filesystem to create tiled BGs.

Use this function once before loading any BG from FAT. Don't call it more than once.

Example:

// Init buffers and variables to load tiled BGs
void NF_InitTiledBgBuffers(void)
Initialize library to load files from the filesystem to create tiled BGs.
Definition: nf_tiledbg.c:41

◆ NF_InitTiledBgSys()

void NF_InitTiledBgSys ( int  screen)

Initialize the tiled BG engine of the selected screen.

You must call this function before using any tiled BG. This function:

  • Inititializes all variables to control BGs, tiles, palettes and maps.
  • Configures VRAM to use 128 KB for BGs (96 KB for tiles, 32 KB for maps).
  • Activates all 4 layers to use with tiled BGs.
  • Reserves 8 banks of 16 KB for tiles (2 for maps, 6 for tiles).
  • Reserves 16 banks of 2 KB for maps. The first 2 tile banks will be used for this.
  • Enables extended palettes.

The memory allocated for tiles and maps is defined in:

#define NF_BANKS_TILES 8
#define NF_BANKS_MAPS 16

Each tile bank is as big as 8 map banks.

Example:

// Init tiled BG system of screen 1
void NF_InitTiledBgSys(int screen)
Initialize the tiled BG engine of the selected screen.
Definition: nf_tiledbg.c:83
Parameters
screenScreen (0 - 1).

◆ NF_LoadExBgPal()

void NF_LoadExBgPal ( const char *  file,
u32  slot 
)

Load a palette from a file to RAM to use it as a background extended palette.

Example:

// Loads the "bg/sunset.pal" file from the filesystem to RAM slot 3.
NF_LoadExBgPal("bg/sunset", 3);
void NF_LoadExBgPal(const char *file, u32 slot)
Load a palette from a file to RAM to use it as a background extended palette.
Definition: nf_tiledbg.c:962
Parameters
fileFile (.pal extension).
slotRAM slot (0 - 127)

◆ NF_LoadTiledBg()

void NF_LoadTiledBg ( const char *  file,
const char *  name,
u32  width,
u32  height 
)

Load all files needed to create a tiled BG from FAT to RAM.

All files for a BG must have the same name, using IMG extension for tiles files, MAP for map files and PAL for palette files.

Check the GRIT folder for more info about BG files conversion.

You can load up to 32 BGs at the same time, this is defined in:

#define NF_SLOTS_TBG 32

Example:

// Load to RAM files "mainstage.img", "mainstage.map" and "mainstage.pal"
// from the "stage1" subfolder and call it “mifondo”. Also store the size of
// the BG (2048 x 256).
NF_LoadTiledBg("stage1/mainstage", "mifondo", 2048, 256);
void NF_LoadTiledBg(const char *file, const char *name, u32 width, u32 height)
Load all files needed to create a tiled BG from FAT to RAM.
Definition: nf_tiledbg.c:160
Parameters
fileFile path without extension.
nameName used for the BG for other functions.
widthBG width.
heightBG height.

◆ NF_LoadTilesForBg()

void NF_LoadTilesForBg ( const char *  file,
const char *  name,
u32  width,
u32  height,
u32  tile_start,
u32  tile_end 
)

Load a tilesed and palette from FAT to RAM.

It works like NF_LoadTiledBg() but it lets you specify the range of tiles to load. Also, no actual map is loaded. Instead, a blank map of the given size is created. The background is created using NF_CreateTiledBg().

Example:

// Load to RAM tiles 0 to 23 (24 tiles in total) from "mainstage.img" and
// the palette (from "mainstage.pal") file, from "stage1" subfolder and
// assigns the "mifondo" name to the background. It also sets the size of
// background to 256x256 pixels. This creates a 32x32 tiles blank map.
NF_LoadTilesForBg("stage1/mainstage", "mifondo", 256, 256, 0, 23);
void NF_LoadTilesForBg(const char *file, const char *name, u32 width, u32 height, u32 tile_start, u32 tile_end)
Load a tilesed and palette from FAT to RAM.
Definition: nf_tiledbg.c:226
Parameters
fileFile name, without extension.
nameName of the BG.
widthWidth of the BG in pixels.
heightHeight of the BG in pixels.
tile_startFirst tile to load.
tile_endLast tile to load.

◆ NF_ResetTiledBgBuffers()

void NF_ResetTiledBgBuffers ( void  )

Reset state used for tiled BGs loaded from FAT.

This function empties all buffers in use and resets variables to their default values. It’s useful to do this when you change a level in a game, to clean all stuff from RAM and make free space to load the new level.

Example:

// Empty all buffers and reset variable values
void NF_ResetTiledBgBuffers(void)
Reset state used for tiled BGs loaded from FAT.
Definition: nf_tiledbg.c:67

◆ NF_RotateTileGfx()

void NF_RotateTileGfx ( u32  slot,
u32  tile,
u32  rotation 
)

Rotates the graphics of a tile in RAM by the specified angle.

The rotated graphics are stored int the same tile.

Rotation values: 1 - 90 degrees clockwise 2 - 90 degrees counter-clockwise 3 - 180 degrees

Example:

// Rotates 90 degrees counter-clockwise tile 76 of the buffer in slot 3
NF_RotateTileGfx(3, 76, 2);
void NF_RotateTileGfx(u32 slot, u32 tile, u32 rotation)
Rotates the graphics of a tile in RAM by the specified angle.
Definition: nf_tiledbg.c:1078
Parameters
slotRAM slot (0 - 127).
tileTile index.
rotationRotation value.

◆ NF_SetExBgPal()

void NF_SetExBgPal ( int  screen,
u32  layer,
u32  pal 
)

Sets the extended palette to be used in the specified background.

Example:

// The backgroun on layer 3 of top screen, uses the extended palette 5
NF_SetExBgPal(0, 3, 5);
void NF_SetExBgPal(int screen, u32 layer, u32 pal)
Sets the extended palette to be used in the specified background.
Definition: nf_tiledbg.c:1023
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
palExtended palette index (0 - 15).

◆ NF_SetTileHflip()

void NF_SetTileHflip ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y 
)

Inverts the horizontal flip status of a tile in the specified map.

The changes are done to the copy of the map in RAM, so changes won't be visible until you update the copy in VRAM with NF_UpdateVramMap().

Example:

// Flips horizontaly the tile in the position (10, 20) of layer 1 of the top
// screen
NF_SetTileHflip(0, 1, 10, 20);
void NF_SetTileHflip(int screen, u32 layer, u32 tile_x, u32 tile_y)
Inverts the horizontal flip status of a tile in the specified map.
Definition: nf_tiledbg.c:1052
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.

◆ NF_SetTileOfMap()

void NF_SetTileOfMap ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y,
u32  tile 
)

Sets the value of the tile at the specified position.

Example:

// Sets to 5 the tile at (20, 10) of the map loaded on screen 0, layer 2.
NF_SetTileOfMap(0, 2, 10, 20, 5);
void NF_SetTileOfMap(int screen, u32 layer, u32 tile_x, u32 tile_y, u32 tile)
Sets the value of the tile at the specified position.
Definition: nf_tiledbg.c:757
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.
tileTile index.

◆ NF_SetTilePal()

void NF_SetTilePal ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y,
u32  pal 
)

Sets the extended palette to use for the tile especified.

The palette has to be loaded in VRAM, and the changes won't be visible until you use NF_UpdateVramMap() because all operations are done in the copy of the map in RAM.

Example:

// Sets tile on position (20, 10) of layer 3 on top screen to use the
// extended palette 2
NF_SetTilePal(0, 3, 20, 10, 2);
void NF_SetTilePal(int screen, u32 layer, u32 tile_x, u32 tile_y, u32 pal)
Sets the extended palette to use for the tile especified.
Definition: nf_tiledbg.c:949
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.
palExtended palette index (0 - 15).

◆ NF_SetTileVflip()

void NF_SetTileVflip ( int  screen,
u32  layer,
u32  tile_x,
u32  tile_y 
)

Inverts the vertical flip status of a tile in the specified map.

The changes are done to the copy of the map in RAM, so changes won't be visible until you update the copy in VRAM with NF_UpdateVramMap().

Example:

// Flips vertically the tile in the position (10, 20) of layer 1 of the top
// screen
NF_SetTileVflip(0, 1, 10, 20);
void NF_SetTileVflip(int screen, u32 layer, u32 tile_x, u32 tile_y)
Inverts the vertical flip status of a tile in the specified map.
Definition: nf_tiledbg.c:1065
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
tile_xX coordinate.
tile_yY coordinate.

◆ NF_UnloadExBgPal()

void NF_UnloadExBgPal ( u32  slot)

Deletes a loaded palette from RAM.

Example:

// Erase from RAM the palette loaded in slot 5. If the palette is already
// transfered to VRAM, you can still use it until you update the palettes.
void NF_UnloadExBgPal(u32 slot)
Deletes a loaded palette from RAM.
Definition: nf_tiledbg.c:980
Parameters
slotRAM slot (0 - 127)

◆ NF_UnloadTiledBg()

void NF_UnloadTiledBg ( const char *  name)

Delete from RAM the BG with the specified name.

You can delete from RAM the BG if you don't need it more or if the size of the BG size is less or equal than 512 x 512. If it's bigger, you must keep it in RAM until you don't need it anymore.

Example:

// Delete from RAM the BG with name "mifondo" and mark as free the slot it
// uses.
NF_UnloadTiledBg("mifondo");
void NF_UnloadTiledBg(const char *name)
Delete from RAM the BG with the specified name.
Definition: nf_tiledbg.c:308
Parameters
nameName used for the BG.

◆ NF_UpdateVramMap()

void NF_UpdateVramMap ( int  screen,
u32  layer 
)

Updates the map of the specified screen and layer specified.

This updates the map on VRAM with the copy of RAM, that can be modified. Use this fuction to apply changes made with NF_SetTileOfMap().

Example:

// Update the map in VRAM with the modified copy in RAM of screen 0, layer 2
void NF_UpdateVramMap(int screen, u32 layer)
Updates the map of the specified screen and layer specified.
Definition: nf_tiledbg.c:768
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).

◆ NF_VramExBgPal()

void NF_VramExBgPal ( int  screen,
u32  layer,
u32  id,
u32  slot 
)

Transfers a palette from RAM to VRAM to be used as extended palette.

Example:

// Transfers the palette from RAM slot 100 to VRAM of layer 3 of the top
// screen, to be used as extended palette 10.
NF_VramExBgPal(0, 3, 100, 10);
void NF_VramExBgPal(int screen, u32 layer, u32 id, u32 slot)
Transfers a palette from RAM to VRAM to be used as extended palette.
Definition: nf_tiledbg.c:998
Parameters
screenScreen (0 - 1).
layerLayer (0 - 3).
idSlot of the palette in RAM.
slotSlot of extended palette in VRAM.

Variable Documentation

◆ NF_BANKS_MAPS

u8 NF_BANKS_MAPS[2]
extern

Maxmimum number of map banks.

1 bank = 2 KB. One tile bank is equivalent to 8 map banks.

Use multiples of 8 for those values.

◆ NF_BANKS_TILES

u8 NF_BANKS_TILES[2]
extern

Maxmimum number of tile banks.

1 bank = 16 KB. One tile bank is equivalent to 8 map banks.