NightFox’s Lib
Data Structures | Macros | Functions | Variables
256 color sprites

Functions to load and handle 256 color sprites. More...

Data Structures

struct  NF_TYPE_SPR256GFX_INFO
 Struct that holds information about sprite graphics in RAM. More...
 
struct  NF_TYPE_SPR256PAL_INFO
 Struct that holds information about sprite palettes in RAM. More...
 
struct  NF_TYPE_SPR256VRAM_INFO
 Struct that holds information about sprite graphics in VRAM. More...
 
struct  NF_TYPE_SPRPALSLOT_INFO
 Struct that holds information about sprite palettes in VRAM. More...
 
struct  NF_TYPE_SPRITEOAM_INFO
 Struct that defines OAM information. More...
 
struct  NF_TYPE_SPRVRAM_INFO
 Struct with information of sprite allocation in VRAM. More...
 

Macros

#define NF_SLOTS_SPR256GFX   256
 Maximum number of slots of 256 color sprites.
 
#define NF_SLOTS_SPR256PAL   64
 Maximum number of slots of palettes of 256 color sprites.
 

Functions

void NF_InitSpriteBuffers (void)
 Initialize library to load files from the filesystem to create 256 color sprites. More...
 
void NF_ResetSpriteBuffers (void)
 Reset state used for 256 color sprites loaded from FAT. More...
 
void NF_InitSpriteSys (int screen,...)
 Initialize sprite system in the specified screen. More...
 
void NF_LoadSpriteGfx (const char *file, u32 id, u32 width, u32 height)
 Load sprite graphics from the filesystem to RAM to use it later. More...
 
void NF_UnloadSpriteGfx (u32 id)
 Delete from RAM the graphics of the selected slot and mark it as free. More...
 
void NF_LoadSpritePal (const char *file, u32 id)
 Load a palette from the filesystem to RAM to be used for a sprite. More...
 
void NF_UnloadSpritePal (u32 id)
 Delete the selected palette from RAM and mark it as free. More...
 
void NF_VramSpriteGfx (int screen, u32 ram, u32 vram, bool keepframes)
 Copy a graphics object from RAM to VRAM of the selected screen to be used as a sprite. More...
 
void NF_FreeSpriteGfx (int screen, u32 id)
 Delete from VRAM the graphics object of the selected slot and a screen. More...
 
void NF_VramSpriteGfxDefrag (int screen)
 Defragments the free VRAM used for sprite graphics. More...
 
void NF_VramSpritePal (int screen, u32 id, u32 slot)
 Copy the palette from RAM to a slot of extended palettes in VRAM. More...
 
void NF_CreateSprite (int screen, u32 id, u32 gfx, u32 pal, s32 x, s32 y)
 Create a sprite with the specified ID in the selcted screen. More...
 
void NF_DeleteSprite (int screen, u32 id)
 Delete the selected sprite ID from the specified screen. More...
 
void NF_SpriteOamSet (int screen)
 Copy data from the shadow OAM used by NFLib to the real OAM of libnds. More...
 
void NF_SpriteSetPalColor (int screen, u32 pal, u32 number, u32 r, u32 g, u32 b)
 Changes a color of a sprite palette in the specified screen. More...
 
void NF_SpriteEditPalColor (int screen, u32 pal, u32 number, u32 r, u32 g, u32 b)
 Changes the value of one color in a sprite palettes of the specified screen. More...
 
void NF_SpriteUpdatePalette (int screen, u32 pal)
 Updates a sprite palette in VRAM with the copy in RAM of it. More...
 
void NF_SpriteGetPalColor (int screen, u32 pal, u32 number, u8 *r, u8 *g, u8 *b)
 Gets the RGB value of a color of a sprites palette in RAM. More...
 

Variables

char * NF_BUFFER_SPR256GFX [NF_SLOTS_SPR256GFX]
 Buffers to hold 256 color sprite graphics.
 
char * NF_BUFFER_SPR256PAL [NF_SLOTS_SPR256PAL]
 Buffers to hold 256 color sprite palettes.
 
NF_TYPE_SPR256GFX_INFO NF_SPR256GFX [NF_SLOTS_SPR256GFX]
 Information of all sprite graphics in RAM.
 
NF_TYPE_SPR256PAL_INFO NF_SPR256PAL [NF_SLOTS_SPR256PAL]
 Information of all palettes in RAM.
 
NF_TYPE_SPR256VRAM_INFO NF_SPR256VRAM [2][128]
 Information of all sprite graphics in VRAM.
 
NF_TYPE_SPRPALSLOT_INFO NF_SPRPALSLOT [2][16]
 Information of all palettes in VRAM.
 
NF_TYPE_SPRITEOAM_INFO NF_SPRITEOAM [2][128]
 OAM information of all sprites.
 
NF_TYPE_SPRVRAM_INFO NF_SPRVRAM [2]
 Information of sprite allocation in VRAM of both screens.
 

Detailed Description

Functions to load and handle 256 color sprites.

Function Documentation

◆ NF_CreateSprite()

void NF_CreateSprite ( int  screen,
u32  id,
u32  gfx,
u32  pal,
s32  x,
s32  y 
)

Create a sprite with the specified ID in the selcted screen.

You have to select the graphics object to use, as well as the palette to use. You also have to select the initial coordinates of the sprite.

Example:

// Create a sprite on screen 0, with ID 12, using the graphics stored in
// slot 30 of VRAM and the palette in slot 1. The sprite is created at the
// coordinates (100, 50).
NF_CreateSprite(0, 12, 30, 1, 100, 50);
void NF_CreateSprite(int screen, u32 id, u32 gfx, u32 pal, s32 x, s32 y)
Create a sprite with the specified ID in the selcted screen.
Definition: nf_sprite256.c:555
Parameters
screenScreen (0 - 1).
idSprite ID (0 - 127).
gfxGraphics object ID (0 - 127).
palPalette (0 - 15).
xX coordinate.
yY coordinate.

◆ NF_DeleteSprite()

void NF_DeleteSprite ( int  screen,
u32  id 
)

Delete the selected sprite ID from the specified screen.

The graphics and palette used by the sprite won't be deleted from VRAM.

Example:

// Delete sprite ID 12 from screen 0
void NF_DeleteSprite(int screen, u32 id)
Delete the selected sprite ID from the specified screen.
Definition: nf_sprite256.c:635
Parameters
screenScreen (0 - 1).
idSprite ID (0 - 127).

◆ NF_FreeSpriteGfx()

void NF_FreeSpriteGfx ( int  screen,
u32  id 
)

Delete from VRAM the graphics object of the selected slot and a screen.

You mustn't delete the graphics while a sprite is using them.

Example:

// Delete from VRAM of screen 1 the graphics in slot 34
void NF_FreeSpriteGfx(int screen, u32 id)
Delete from VRAM the graphics object of the selected slot and a screen.
Definition: nf_sprite256.c:403
Parameters
screenScreen (0 - 1).
idVRAM slot (0 - 127).

◆ NF_InitSpriteBuffers()

void NF_InitSpriteBuffers ( void  )

Initialize library to load files from the filesystem to create 256 color sprites.

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

Example:

// Init buffers and variables to load sprites.
void NF_InitSpriteBuffers(void)
Initialize library to load files from the filesystem to create 256 color sprites.
Definition: nf_sprite256.c:37

◆ NF_InitSpriteSys()

void NF_InitSpriteSys ( int  screen,
  ... 
)

Initialize sprite system in the specified screen.

  • Initializes OAM with default parameters.
  • It assigns 128 KB of VRAM for graphics and palettes.
  • It enables extended palettes.

The VRAM mapping parameter is optional, if you don’t set it, 64 is set by default. You can use up to 1024 chunks of 64 bytes (64 mapping mode) or 128 bytes (128 mapping mode) and 16 palettes. The use of mode 64 limits the amount of usable VRAM to 64 KB. When using mode 128, 8x8 pixels sprites can't be used.

Example:

// Initialize 256 color sprite system in screen 0 in 64 mapping mode and in
// screen 1 in 128 mapping mode
void NF_InitSpriteSys(int screen,...)
Initialize sprite system in the specified screen.
Definition: nf_sprite256.c:71
Parameters
screenScreen (0 - 1).
...VRAM mapping mode (64 or 128).

◆ NF_LoadSpriteGfx()

void NF_LoadSpriteGfx ( const char *  file,
u32  id,
u32  width,
u32  height 
)

Load sprite graphics from the filesystem to RAM to use it later.

You must specify the filename without extension. You must use the ".img" extension in the filename of you sprite graphics file. You must select the RAM slot to hold the graphics (0 to 255), and the graphics sizes. If it's an animated sprite, put the size in pixels of first frame.

There are 256 available slots, as specified in:

#define NF_SLOTS_SPR256GFX 256

Example:

// Loads file "name.img" from folder "stage3" and stores it in slot 100 of
// RAM. This graphics objectx has a size of 64 x 32.
NF_LoadSpriteGfx("stage3/nave", 100, 64, 32);
void NF_LoadSpriteGfx(const char *file, u32 id, u32 width, u32 height)
Load sprite graphics from the filesystem to RAM to use it later.
Definition: nf_sprite256.c:173
Parameters
fileFile name without extension.
idSlot number (0 - 255).
widthWidth of the graphics object (in pixels).
heightHeight of the graphics object (in pixels).

◆ NF_LoadSpritePal()

void NF_LoadSpritePal ( const char *  file,
u32  id 
)

Load a palette from the filesystem to RAM to be used for a sprite.

You must enter the filename without extension. You must use ".pal" extension in all your palette files.

You can store up to 64 palettes, as specified in:

#define NF_SLOTS_SPR256PAL 64

Example:

// Load file "player.pal" from folder "stage3" and store it in slot 34
NF_LoadSpritePal(“stage3/player”, 34);
void NF_LoadSpritePal(const char *file, u32 id)
Load a palette from the filesystem to RAM to be used for a sprite.
Definition: nf_sprite256.c:218
Parameters
fileFile name without extension.
idSlot number (0 - 63).

◆ NF_ResetSpriteBuffers()

void NF_ResetSpriteBuffers ( void  )

Reset state used for 256 color sprites 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_ResetSpriteBuffers(void)
Reset state used for 256 color sprites loaded from FAT.
Definition: nf_sprite256.c:58

◆ NF_SpriteEditPalColor()

void NF_SpriteEditPalColor ( int  screen,
u32  pal,
u32  number,
u32  r,
u32  g,
u32  b 
)

Changes the value of one color in a sprite palettes of the specified screen.

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

Use this function to make cool effect on your sprites.

Example:

// Set the value of color 1 of palette 3 of the top screen to red.
NF_SpriteSetPalColor(0, 3, 1, 31, 0, 0);
void NF_SpriteSetPalColor(int screen, u32 pal, u32 number, u32 r, u32 g, u32 b)
Changes a color of a sprite palette in the specified screen.
Definition: nf_sprite256.c:716
Parameters
screenScreen (0 - 1).
palPalette index (0 - 15).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_SpriteGetPalColor()

void NF_SpriteGetPalColor ( int  screen,
u32  pal,
u32  number,
u8 *  r,
u8 *  g,
u8 *  b 
)

Gets the RGB value of a color of a sprites palette in RAM.

Example:

// Gets the RGB value of color 200 from sprites palette 3 of the bottom
// screen, and stores it in variables "red", "green" and "blue".
u8 red;
u8 green;
u8 blue;
NF_SpriteGetPalColor(1, 3, 200, &red, &green, &blue);
void NF_SpriteGetPalColor(int screen, u32 pal, u32 number, u8 *r, u8 *g, u8 *b)
Gets the RGB value of a color of a sprites palette in RAM.
Definition: nf_sprite256.c:781
Parameters
screenScreen (0 - 1).
palPalette index (0 - 15).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_SpriteOamSet()

void NF_SpriteOamSet ( int  screen)

Copy data from the shadow OAM used by NFLib to the real OAM of libnds.

OAM must be updated only during the vertical blanking period. For example, if you don't have a vertical blanking interrupt handler, you can do:

swiWaitForVBlank();
oamUpdate(&oamMain);
oamUpdate(&oamSub);
void NF_SpriteOamSet(int screen)
Copy data from the shadow OAM used by NFLib to the real OAM of libnds.
Definition: nf_sprite256.c:670

If your vertical blanking interrupt handler takes too long to finish, oamUpdate() will be called outside of the vertical blanking period, which will cause issues. In that case, call the functions from the interrupt handler.

Parameters
screenScreen (0 - 1).

◆ NF_SpriteSetPalColor()

void NF_SpriteSetPalColor ( int  screen,
u32  pal,
u32  number,
u32  r,
u32  g,
u32  b 
)

Changes a color of a sprite palette in the specified screen.

The change is made directly in VRAM, so it may be overwritten from the copy in RAM.

Example:

// Set color 1 of palette 3 of the top screen to red.
NF_SpriteSetPalColor(0, 3, 1, 31, 0, 0);
Parameters
screenScreen (0 - 1).
palPalette index (0 - 15).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_SpriteUpdatePalette()

void NF_SpriteUpdatePalette ( int  screen,
u32  pal 
)

Updates a sprite palette in VRAM with the copy in RAM of it.

Example:

// Updates palette 2 of the bottom screen.
void NF_SpriteUpdatePalette(int screen, u32 pal)
Updates a sprite palette in VRAM with the copy in RAM of it.
Definition: nf_sprite256.c:756
Parameters
screenScreen (0 - 1).
palPalette index (0 - 15).

◆ NF_UnloadSpriteGfx()

void NF_UnloadSpriteGfx ( u32  id)

Delete from RAM the graphics of the selected slot and mark it as free.

You can delete the graphics from RAM once the sprite is created if you don't need it anymore or, if it's animated, after transferring all frames to VRAM.

Example:

// Delete from RAM the graphics in slot 100 and mark it as free
void NF_UnloadSpriteGfx(u32 id)
Delete from RAM the graphics of the selected slot and mark it as free.
Definition: nf_sprite256.c:199
Parameters
idSlot number (0 - 255).

◆ NF_UnloadSpritePal()

void NF_UnloadSpritePal ( u32  id)

Delete the selected palette from RAM and mark it as free.

You can delete it if you don't need it anymore or if it's already in VRAM.

Parameters
idSlot number (0 - 63).

◆ NF_VramSpriteGfx()

void NF_VramSpriteGfx ( int  screen,
u32  ram,
u32  vram,
bool  keepframes 
)

Copy a graphics object from RAM to VRAM of the selected screen to be used as a sprite.

You must specify if you want to copy all frames to VRAM (false) or just the first one (true).

Example:

// Copy the graphics object stored in slot 160 of RAM to slot 23 of VRAM of
// screen 1, copying all frames if it’s animated.
NF_VramSpriteGfx(1, 160, 23, false);
void NF_VramSpriteGfx(int screen, u32 ram, u32 vram, bool keepframes)
Copy a graphics object from RAM to VRAM of the selected screen to be used as a sprite.
Definition: nf_sprite256.c:258
Parameters
screenScreen (0 - 1).
ramRAM slot (0 - 255).
vramVRAM slot (0 - 127).
keepframesFor animated sprites. If true, copy all frames to VRAM.

◆ NF_VramSpriteGfxDefrag()

void NF_VramSpriteGfxDefrag ( int  screen)

Defragments the free VRAM used for sprite graphics.

This function is automaticaly executed when fragmented free VRAM is bigger than 50% of the total free VRAM. You don’t need to manually execute this function. You can get the state of VRAM reading the following variables:

NF_SPRVRAM[int screen].free // Total free VRAM
NF_SPRVRAM[int screen].fragmented // Total fragmented free VRAM
NF_SPRVRAM[int screen].inarow // Largest free block of VRAM at the end
NF_SPRVRAM[int screen].lost // Unusable free VRAM because fragmentation
NF_TYPE_SPRVRAM_INFO NF_SPRVRAM[2]
Information of sprite allocation in VRAM of both screens.
Definition: nf_sprite256.c:35
s32 free
Free VRAM.
Definition: nf_sprite256.h:112
s32 fragmented
Fragmented VRAM.
Definition: nf_sprite256.h:118
s32 inarow
Contiguous VRAM.
Definition: nf_sprite256.h:119

Example:

// Defragments the free VRAM of sprites of screen 1
void NF_VramSpriteGfxDefrag(int screen)
Defragments the free VRAM used for sprite graphics.
Definition: nf_sprite256.c:438
Parameters
screenScreen (0 - 1).

◆ NF_VramSpritePal()

void NF_VramSpritePal ( int  screen,
u32  id,
u32  slot 
)

Copy the palette from RAM to a slot of extended palettes in VRAM.

If the slot is in use, its contents are overwritten.

Example:

// Copy palette from RAM slot 56 to the extended palettes slot 8 of screen 1
NF_VramSpritePal(1, 56, 8);
void NF_VramSpritePal(int screen, u32 id, u32 slot)
Copy the palette from RAM to a slot of extended palettes in VRAM.
Definition: nf_sprite256.c:524
Parameters
screenScreen (0 - 1).
idVRAM slot (0 - 64).
slotVRAM slot (0 - 15).