NightFox’s Lib
Data Structures | Macros | Functions | Variables
3D sprite functions.

These functions are special, since they use the 3D engine to draw sprites by using textured polygons. More...

Data Structures

struct  NF_TYPE_3DSPRITE_INFO
 Struct that holds information about 3D sprites. More...
 
struct  NF_TYPE_TEX256VRAM_INFO
 Struct that holds information about 3D sprite textures in VRAM. More...
 
struct  NF_TYPE_3DSPRPALSLOT_INFO
 Struct that holds information about 3D sprite palettes in VRAM. More...
 
struct  NF_TYPE_TEXVRAM_INFO
 Struct with information of 3D sprite allocation in VRAM. More...
 
struct  NF_TYPE_CREATED_3DSPRITE_INFO
 Struct with information about created 3D sprites. More...
 

Macros

#define NF_3DSPRITES   256
 Maximum number of slots of 3D sprites.
 

Functions

void NF_Init3dSpriteSys (void)
 Initialize 3D sprite system. More...
 
void NF_Vram3dSpriteGfx (u32 ram, u32 vram, bool keepframes)
 Copy a texture from RAM to VRAM to use it for 3D sprites. More...
 
void NF_Free3dSpriteGfx (u32 id)
 Delete from VRAM the texture in the selected slot. More...
 
void NF_Vram3dSpriteGfxDefrag (void)
 Defragments the free VRAM used for 3D sprite textures. More...
 
void NF_Vram3dSpritePal (u32 id, u32 slot)
 Copy a palette from RAM to the specified slot in VRAM. More...
 
void NF_Create3dSprite (u32 id, u32 gfx, u32 pal, s32 x, s32 y)
 Create a 3D sprite with the specified ID and display it on the screen. More...
 
void NF_Delete3dSprite (u32 id)
 Remove the sprite with the specified ID from the screen. More...
 
void NF_Sort3dSprites (void)
 Sets the priorities of 3D sprites based on their sprite IDs. More...
 
void NF_Set3dSpritePriority (u32 id, u32 prio)
 Changes the draw priority of the 3D sprite with the specified ID. More...
 
void NF_Swap3dSpritePriority (u32 id_a, u32 id_b)
 Swaps the priority of two 3D sprites. More...
 
void NF_Set3dSpriteFrame (u32 id, u32 frame)
 Select the frame of an animation to display in the 3D sprite. More...
 
void NF_Draw3dSprites (void)
 Draw all created 3D sprites on the screen. More...
 
void NF_Update3dSpritesGfx (void)
 Update the textures of all animated 3D sprites that need it. More...
 
void NF_Rotate3dSprite (u32 id, s32 x, s32 y, s32 z)
 Rotates a 3D sprite on its 3 axes. More...
 
void NF_Scale3dSprite (u32 id, u32 x, u32 y)
 Scales 3D sprite on X and Y axes. More...
 
void NF_Blend3dSprite (u32 sprite, u32 poly_id, u32 alpha)
 Set the alpha level of a 3D sprite. More...
 
void NF_3dSpritesLayer (u32 layer)
 Select the layer where 3D sprites are drawn. More...
 
void NF_3dSpriteEditPalColor (u32 pal, u32 number, u32 r, u32 g, u32 b)
 Changes one color of one 3D sprite palette. More...
 
void NF_3dSpriteUpdatePalette (u32 pal)
 Updates the VRAM copy of a palette with the RAM copy of it. More...
 
void NF_3dSpriteGetPalColor (u32 pal, u32 number, u8 *r, u8 *g, u8 *b)
 Gets the RGB value of a color from a 3D sprite palette loaded in RAM. More...
 
void NF_3dSpriteSetDepth (u32 id, s32 z)
 Sets the depth of the selected 3D sprite. More...
 

Variables

NF_TYPE_3DSPRITE_INFO NF_3DSPRITE [NF_3DSPRITES]
 Information of all 3D sprites.
 
NF_TYPE_TEX256VRAM_INFO NF_TEX256VRAM [NF_3DSPRITES]
 Information of all 3D sprite textures in VRAM.
 
NF_TYPE_3DSPRPALSLOT_INFO NF_TEXPALSLOT [32]
 Information of all 3D sprite palettes in VRAM.
 
NF_TYPE_TEXVRAM_INFO NF_TEXVRAM
 Information of 3D sprite allocation in VRAM.
 
NF_TYPE_CREATED_3DSPRITE_INFO NF_CREATED_3DSPRITE
 Information of created 3D sprites.
 

Detailed Description

These functions are special, since they use the 3D engine to draw sprites by using textured polygons.

It can only be used in one screen at the same time, and background layer 0 is replaced by the 3D output.

In return we can create up to 256 sprites of a maximum size of 1024x1024, we can use any size in base 2, and use a maximum of 32 palettes simultaneously.

For the loading of graphics and palettes, use the same functions as with 2D sprites. You can convert indexed images of 256 colors to create textures for 3D sprites with the following grit command:

grit image.png -ftb -fh! -gb -gu8 -gB8 -pu8 -gTFF00FF

You can also use the same bat scripts as for 8 bit backgrounds.

Function Documentation

◆ NF_3dSpriteEditPalColor()

void NF_3dSpriteEditPalColor ( u32  pal,
u32  number,
u32  r,
u32  g,
u32  b 
)

Changes one color of one 3D sprite palette.

The change is made to the RAM copy of the palette, so you won't see any change until you update the VRAM copy with NF_3dSpriteUpdatePalette(). Use this function to make cool effects with your 3D sprites.

Example:

// Set color 1 of palette 3 to red
NF_3dSpriteSetPalColor(3, 1, 31, 0, 0);
Parameters
palPalette slot (0 - 31).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_3dSpriteGetPalColor()

void NF_3dSpriteGetPalColor ( u32  pal,
u32  number,
u8 *  r,
u8 *  g,
u8 *  b 
)

Gets the RGB value of a color from a 3D sprite palette loaded in RAM.

Example:

// Gets the RGB values of color 200 of sprite palette 3 and stores it in
// variables "red", "green" and "blue".
u8 red;
u8 green;
u8 blue;
NF_3dSpriteGetPalColor(3, 200, &red, &green, &blue);
void NF_3dSpriteGetPalColor(u32 pal, u32 number, u8 *r, u8 *g, u8 *b)
Gets the RGB value of a color from a 3D sprite palette loaded in RAM.
Definition: nf_sprite3d.c:839
Parameters
palPalette slot (0 - 31).
numberColor number (0 - 255).
rRed component (0 - 31).
gGreen component (0 - 31).
bBlue component (0 - 31).

◆ NF_3dSpriteSetDepth()

void NF_3dSpriteSetDepth ( u32  id,
s32  z 
)

Sets the depth of the selected 3D sprite.

-512 is highest priority (on top of the other sprites). 0 is the default value, and 512 the lowest priority.

Change the sprite depth to prevent it from intersecting with other sprites when rotation or zoom are applied.

Parameters
idSprite ID (0 - 255).
zDepth (-512 - 512)

◆ NF_3dSpritesLayer()

void NF_3dSpritesLayer ( u32  layer)

Select the layer where 3D sprites are drawn.

This function only changes the priority of background layer 0. The 3D output can only be sent to layer 0 because of how the hardware was designed.

Parameters
layerLayer (0 - 3).

◆ NF_3dSpriteUpdatePalette()

void NF_3dSpriteUpdatePalette ( u32  pal)

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

Example:

// Update palette 2
void NF_3dSpriteUpdatePalette(u32 pal)
Updates the VRAM copy of a palette with the RAM copy of it.
Definition: nf_sprite3d.c:824
Parameters
palPalette slot (0 - 31).

◆ NF_Blend3dSprite()

void NF_Blend3dSprite ( u32  sprite,
u32  poly_id,
u32  alpha 
)

Set the alpha level of a 3D sprite.

For transparency to work properly between different translucent sprites you need to use different polygon IDs for them (between 1 and 62). The alpha range is 0 to 31, with 31 being fully opaque.

To disable transparency, select an alpha value of 31 or a polygon ID of 0.

Parameters
spriteSprite ID (0 - 255).
poly_idPolygon ID (1 - 62).
alphaTransparency (0 - 31).

◆ NF_Create3dSprite()

void NF_Create3dSprite ( u32  id,
u32  gfx,
u32  pal,
s32  x,
s32  y 
)

Create a 3D sprite with the specified ID and display it on the screen.

Example:

// Create a sprite with ID 12, using the texture stored in slot 30 of VRAM
// and the palette in slot 1. The sprite is created at coordinates (100, 50)
NF_Create3dSprite(12, 30, 1, 100, 50);
void NF_Create3dSprite(u32 id, u32 gfx, u32 pal, s32 x, s32 y)
Create a 3D sprite with the specified ID and display it on the screen.
Definition: nf_sprite3d.c:390
Parameters
idSprite ID (0 - 255).
gfxTexture slot (0 - 255).
palPalette slot (0 - 31).
xX coordinate.
yY coordinate.

◆ NF_Delete3dSprite()

void NF_Delete3dSprite ( u32  id)

Remove the sprite with the specified ID from the screen.

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

Example:

// Delete from screen the sprite with ID 12
void NF_Delete3dSprite(u32 id)
Remove the sprite with the specified ID from the screen.
Definition: nf_sprite3d.c:456
Parameters
idSprite ID (0 - 255).

◆ NF_Draw3dSprites()

void NF_Draw3dSprites ( void  )

Draw all created 3D sprites on the screen.

You need to call this function once per frame. This is the basic code to show them:

// Draw all 3D Sprites
// Tell the 3D hardware that all commands for this frame have been sent
glFlush(0);
// Wait for the vertical sync
swiWaitForVBlank();
void NF_Draw3dSprites(void)
Draw all created 3D sprites on the screen.
Definition: nf_sprite3d.c:609

◆ NF_Free3dSpriteGfx()

void NF_Free3dSpriteGfx ( u32  id)

Delete from VRAM the texture in the selected slot.

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

Example:

// Delete from VRAM the texture in slot 34.
void NF_Free3dSpriteGfx(u32 id)
Delete from VRAM the texture in the selected slot.
Definition: nf_sprite3d.c:244
Parameters
idVRAM slot (0 - 255)

◆ NF_Init3dSpriteSys()

void NF_Init3dSpriteSys ( void  )

Initialize 3D sprite system.

Asigns 128 KB of VRAM for textures and 16 KB for palettes.

It enables extended palettes.

Example:

// Initialize the 3D sprite system
void NF_Init3dSpriteSys(void)
Initialize 3D sprite system.
Definition: nf_sprite3d.c:34

◆ NF_Rotate3dSprite()

void NF_Rotate3dSprite ( u32  id,
s32  x,
s32  y,
s32  z 
)

Rotates a 3D sprite on its 3 axes.

You can set a rotation between -512 and 512, with 0 meaning no rotation.

Parameters
idSprite ID (0 - 255).
xRotation by X axis.
yRotation by Y axis.
zRotation by Z axis.

◆ NF_Scale3dSprite()

void NF_Scale3dSprite ( u32  id,
u32  x,
u32  y 
)

Scales 3D sprite on X and Y axes.

The scale range goes from 0 to 64 (original size) to any greater value.

Parameters
idSprite ID (0 - 255).
xX axis scale.
yY axis scale.

◆ NF_Set3dSpriteFrame()

void NF_Set3dSpriteFrame ( u32  id,
u32  frame 
)

Select the frame of an animation to display in the 3D sprite.

Example:

// Make sprite 20 show frame 5
void NF_Set3dSpriteFrame(u32 id, u32 frame)
Select the frame of an animation to display in the 3D sprite.
Definition: nf_sprite3d.c:575
Parameters
idSprite ID (0 - 255).
frameFrame index.

◆ NF_Set3dSpritePriority()

void NF_Set3dSpritePriority ( u32  id,
u32  prio 
)

Changes the draw priority of the 3D sprite with the specified ID.

Lower priority values have a higher priority.

Parameters
idSprite ID (0 - 255).
prioPriority (0 - 255).

◆ NF_Sort3dSprites()

void NF_Sort3dSprites ( void  )

Sets the priorities of 3D sprites based on their sprite IDs.

Lower sprite IDs have higher priorities.

◆ NF_Swap3dSpritePriority()

void NF_Swap3dSpritePriority ( u32  id_a,
u32  id_b 
)

Swaps the priority of two 3D sprites.

Parameters
id_aSprite ID A (0 - 255).
id_bSprite ID B (0 - 255).

◆ NF_Update3dSpritesGfx()

void NF_Update3dSpritesGfx ( void  )

Update the textures of all animated 3D sprites that need it.

Use this if any of your 3D sprites has the flag "keepframes" set to true.

Call this function just after swiWaitForVBlank().

◆ NF_Vram3dSpriteGfx()

void NF_Vram3dSpriteGfx ( u32  ram,
u32  vram,
bool  keepframes 
)

Copy a texture from RAM to VRAM to use it for 3D sprites.

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

Example:

// Copy the texture stored in slot 160 of RAM to slot 23 of VRAM, copying
// all frames if it's animated.
NF_Vram3dSpriteGfx(160, 23, false);
void NF_Vram3dSpriteGfx(u32 ram, u32 vram, bool keepframes)
Copy a texture from RAM to VRAM to use it for 3D sprites.
Definition: nf_sprite3d.c:84
Parameters
ramRAM slot (0 - 255)
vramVRAM slot (0 - 255)
keepframesFor animated sprites. If true, copy all frames to VRAM.

◆ NF_Vram3dSpriteGfxDefrag()

void NF_Vram3dSpriteGfxDefrag ( void  )

Defragments the free VRAM used for 3D sprite textures.

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_TEXVRAM[screen].free // Total free VRAM
NF_TEXVRAM[screen].fragmented // Total fragmented free VRAM
NF_TEXVRAM[screen].inarow // Largest free block of VRAM at the end
NF_TEXVRAM[screen].lost // Unusable free VRAM because fragmentation
NF_TYPE_TEXVRAM_INFO NF_TEXVRAM
Information of 3D sprite allocation in VRAM.
Definition: nf_sprite3d.c:29
s32 inarow
Contiguous VRAM.
Definition: nf_sprite3d.h:113
s32 fragmented
Fragmented VRAM.
Definition: nf_sprite3d.h:112
s32 free
Free VRAM.
Definition: nf_sprite3d.h:106

◆ NF_Vram3dSpritePal()

void NF_Vram3dSpritePal ( u32  id,
u32  slot 
)

Copy a palette from RAM to the specified slot in VRAM.

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

Example:

// Copy the palette from RAM slot 56 to VRAM slot 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
idRAM slot (0 - 64)
slotVRAM slot (0 - 31)