NightFox’s Lib
Data Structures | Macros | Functions | Variables
Text support functions.

Text support functions of NFLIb. More...

Data Structures

struct  NF_TYPE_TEXT_INFO
 Struct that holds text layer information. More...
 

Macros

#define NF_TEXT_FONT_CHARS   127
 Number of characters available in a font.
 
#define NF_TEXT_FONT_LAST_VALID_CHAR   113
 Last valid character in a font.
 

Functions

void NF_InitTextSys (int screen)
 Initialize the text engine for the selected screen. More...
 
void NF_LoadTextFont (const char *file, const char *name, u32 width, u32 height, u32 rotation)
 Load font and palette files from the filesystem to RAM. More...
 
void NF_UnloadTextFont (const char *name)
 Delete from RAM the font with the specified name. More...
 
void NF_CreateTextLayer (int screen, u32 layer, u32 rotation, const char *name)
 Create a special tiled background to write text on it. More...
 
void NF_DeleteTextLayer (int screen, u32 layer)
 Delete a text layer. More...
 
void NF_WriteText (int screen, u32 layer, u32 x, u32 y, const char *text)
 Write text in a layer at the specified coordinates. More...
 
void NF_UpdateTextLayers (void)
 Copy the temporary text buffers of both screens to VRAM. More...
 
void NF_ClearTextLayer (int screen, u32 layer)
 Clears the contents of a text layer filling it with zeroes. More...
 
void NF_DefineTextColor (int screen, u32 layer, u32 color, u32 r, u32 g, u32 b)
 Defines a RGB color to be used later as a text color. More...
 

Variables

NF_TYPE_TEXT_INFO NF_TEXT [2][4]
 Information of all text layers.
 

Detailed Description

Text support functions of NFLIb.

Function Documentation

◆ NF_ClearTextLayer()

void NF_ClearTextLayer ( int  screen,
u32  layer 
)

Clears the contents of a text layer filling it with zeroes.

Example:

// Clears the contents of text layer 2 of screen 0
void NF_ClearTextLayer(int screen, u32 layer)
Clears the contents of a text layer filling it with zeroes.
Definition: nf_text.c:386
Parameters
screenScreen (0 - 1)
layerBackground layer (0 - 3)

◆ NF_CreateTextLayer()

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

Create a special tiled background to write text on it.

You must select the screen and layer where the background will be created, the orientation of the text and the font you want to use.

Example:

// Create a text layer on layer 0 of screen 1, using the font with name
// "titulo" and with the text rotated to the left.
NF_CreateTextLayer(1, 0, 2, "titulo");
void NF_CreateTextLayer(int screen, u32 layer, u32 rotation, const char *name)
Create a special tiled background to write text on it.
Definition: nf_text.c:126
Parameters
screenScreen (0 - 1)
layerBackground layer (0 - 3)
rotationRotation (0 - 2)
nameFont name

◆ NF_DefineTextColor()

void NF_DefineTextColor ( int  screen,
u32  layer,
u32  color,
u32  r,
u32  g,
u32  b 
)

Defines a RGB color to be used later as a text color.

The color is stored in the specified slot. To make this function work, the font palette must be indexed and it must have 2 colors (Magenta/White). Only color index 1 is updated by this function, so any other color in higher indices won't be updated.

Example:

// Defines color numer 13 of text layer 0 of the top screen as light green
NF_DefineTextColor(0, 0, 13, 15, 31, 15);
void NF_DefineTextColor(int screen, u32 layer, u32 color, u32 r, u32 g, u32 b)
Defines a RGB color to be used later as a text color.
Definition: nf_text.c:402
Parameters
screenScreen (0 - 1)
layerBackground layer (0 - 3)
colorColor number (0 - 15)
rRed component (0 - 31)
gGreen component (0 - 31)
bBlue component (0 - 31)

◆ NF_DeleteTextLayer()

void NF_DeleteTextLayer ( int  screen,
u32  layer 
)

Delete a text layer.

You must specify the layer and screen of the text layer you want to delete.

Example:

// Delete the text layer of layer 0 of the bottom screen.
void NF_DeleteTextLayer(int screen, u32 layer)
Delete a text layer.
Definition: nf_text.c:160
Parameters
screenScreen (0 - 1)
layerBackground layer (0 - 3)

◆ NF_InitTextSys()

void NF_InitTextSys ( int  screen)

Initialize the text engine for the selected screen.

You must also initialize the tiled background system of that screen before using the text engine. You can get more information about it in NF_InitTiledBgBuffers() and NF_InitTiledBgSys().

Use this function also to reset text system.

Example:

// Initialize text engine of screen 1
void NF_InitTextSys(int screen)
Initialize the text engine for the selected screen.
Definition: nf_text.c:22
Parameters
screenScreen (0 - 1).

◆ NF_LoadTextFont()

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

Load font and palette files from the filesystem to RAM.

You must specify the filename without extension and the name you want to give to the font and the size of the text layer you want to create, in pixels.

If the font includes the characters for rotated text, the values are:

  • 0: No rotation
  • 1: Rotate clockwise
  • 2: Rotate counter-clockwise

The font uses two files, the tileset with extension ".fnt" and the palette with extension ".pal".

You must load the font for every text layer you want to create. Every font loaded uses a slot of tiled backgrounds of RAM.

There are many examples with custom fonts in the examples folder.

Example:

// Load the font with files "default" from folder "stage4" and call it
// "titulo", rotated counter-clockwise. The text layer created is of 32x32
// tiles (256x256 pixels).
NF_LoadTextFont("stage4/default", "titulo", 256, 256, 2);
void NF_LoadTextFont(const char *file, const char *name, u32 width, u32 height, u32 rotation)
Load font and palette files from the filesystem to RAM.
Definition: nf_text.c:36
Parameters
fileFile name
nameFont name
widthMap width (in pixels)
heightMap height (in pixels)
rotationRotation (0 - 2)

◆ NF_UnloadTextFont()

void NF_UnloadTextFont ( const char *  name)

Delete from RAM the font with the specified name.

Example:

// Delete from RAM the font with name "titulo".
void NF_UnloadTextFont(const char *name)
Delete from RAM the font with the specified name.
Definition: nf_text.c:121
Parameters
nameFont name

◆ NF_UpdateTextLayers()

void NF_UpdateTextLayers ( void  )

Copy the temporary text buffers of both screens to VRAM.

Buffers are only copied if the copy in VRAM is outdated.

Example:

// Update all text layers that require it
void NF_UpdateTextLayers(void)
Copy the temporary text buffers of both screens to VRAM.
Definition: nf_text.c:369

◆ NF_WriteText()

void NF_WriteText ( int  screen,
u32  layer,
u32  x,
u32  y,
const char *  text 
)

Write text in a layer at the specified coordinates.

You must specify the screen and layer where you want to write the text. The text is not writen directly on the screen. It's stored in a temporary buffer and it's transferred to the screen when the function NF_UpdateTextLayers() is called. This is done to minimize the number of times VRAM is updated.

If you want to write variables or formated text, use snprintf().

Example 1:

// Write "Hello World!" to layer 1 of the bottom screen
NF_WriteText(1, 0, 1, 1, "Hello World!");
void NF_WriteText(int screen, u32 layer, u32 x, u32 y, const char *text)
Write text in a layer at the specified coordinates.
Definition: nf_text.c:177

Example 2:

// Write a formatted string to layer 1 of the bottom screen
char buffer[32];
int myvar = 10;
snprintf(buffer, sizeof(buffer), “Hello world %d times”, myvar);
NF_WriteText(1, 0, 1, 1, buffer);
Parameters
screenScreen (0 - 1)
layerBackground layer (0 - 3)
xX coordinate
yY coordinate
textString to write to the screen