console.h File Reference

NDS stdout and stderr support. More...

#include <stdio.h>
#include <nds/arm9/background.h>
#include <nds/ndstypes.h>

Data Structures
struct	ConsoleFont
	A font struct for the console. More...
struct	PrintConsole
	Console structure used to store the state of a console render context. More...

Typedefs
typedef struct ConsoleFont	ConsoleFont
	A font struct for the console.
typedef ssize_t(*	ConsoleOutFn) (const char *ptr, size_t len)
	Function type used by libnds to redirect characters sent to stdout and stderr (skipping the call to the ConsolePrint handler).
typedef bool(*	ConsolePrint) (void *con, char c)
	Function type used by the PrintConsole struct to send characters to the console.
typedef struct PrintConsole	PrintConsole
	Console structure used to store the state of a console render context.

Enumerations
enum	ConsoleColor {   CONSOLE_BLACK = 0 ,   CONSOLE_RED = 1 ,   CONSOLE_GREEN = 2 ,   CONSOLE_YELLOW = 3 ,   CONSOLE_BLUE = 4 ,   CONSOLE_MAGENTA = 5 ,   CONSOLE_CYAN = 6 ,   CONSOLE_LIGHT_GRAY = 7 ,   CONSOLE_GRAY = 8 ,   CONSOLE_LIGHT_RED = 9 ,   CONSOLE_LIGHT_GREEN = 10 ,   CONSOLE_LIGHT_YELLOW = 11 ,   CONSOLE_LIGHT_BLUE = 12 ,   CONSOLE_LIGHT_MAGENTA = 13 ,   CONSOLE_LIGHT_CYAN = 14 ,   CONSOLE_WHITE = 15 ,   CONSOLE_DEFAULT = 16 }
	Colors of the default palettes of libnds. More...
enum	DebugDevice {   DebugDevice_NULL = 0x0 ,   DebugDevice_NOCASH = 0x1 ,   DebugDevice_CONSOLE = 0x02 }
	Console debug devices supported by libnds. More...

Functions
void	consoleAddToCursor (PrintConsole *console, int deltaX, int deltaY)
	Moves the console cursor position from its current position.
int	consoleArm7Disable (void)
	It disables the ARM7 console and frees the shared buffer.
void	consoleArm7Flush (void)
	This function checks the ring buffer and prints all enqueued text.
int	consoleArm7Setup (PrintConsole *console, size_t buffer_size)
	Initialize the ARM7 console and direct the output to the specified console.
void	consoleClear (void)
	Clears the console and returns the cursor to the top left corner.
void	consoleDebugInit (DebugDevice device)
	Initializes the debug console output on stderr to the specified device.
PrintConsole *	consoleDemoInit (void)
	Initialize the console to a default state for prototyping.
void	consoleGetCursor (PrintConsole *console, int *x, int *y)
	Gets the console cursor.
const PrintConsole *	consoleGetDefault (void)
	Gets a pointer to the console with the default values.
PrintConsole *	consoleInit (PrintConsole *console, int layer, BgType type, BgSize size, int mapBase, int tileBase, bool mainDisplay, bool loadGraphics)
	Initialise the console.
PrintConsole *	consoleInitEx (PrintConsole *console, int layer, BgType type, BgSize size, int mapBase, int tileBase, int palIndex, int fontCharOffset, bool mainDisplay, bool loadGraphics)
	Initialise the console.
void	consolePrintChar (char c)
	Prints a character to the default console.
PrintConsole *	consoleSelect (PrintConsole *console)
	Make the specified console the render target.
void	consoleSetColor (PrintConsole *console, ConsoleColor color)
	Sets the color to use to print new text.
void	consoleSetCursor (PrintConsole *console, int x, int y)
	Sets the console cursor position.
void	consoleSetCustomStderr (ConsoleOutFn fn)
	Sets the function where stderr is sent, bypassing the PrintConsole handler.
void	consoleSetCustomStdout (ConsoleOutFn fn)
	Sets the function where stdout is sent, bypassing the PrintConsole handler.
void	consoleSetFont (PrintConsole *console, ConsoleFont *font)
	Loads the font into the console.
void	consoleSetWindow (PrintConsole *console, int x, int y, int width, int height)
	Sets the print window dimensions.

Detailed Description

NDS stdout and stderr support.

Provides stdio integration for printing using <stdio.h> functions.

Regular console

It is initialized by calling consoleDemoInit() (or consoleInit() to customize the console), and it will simply print messages to the screen of the DS whenever the user sends text to stdout (with printf(), for example).

The default console utilizes the sub display, approximatly 4 KiB of VRAM C starting at tile base 3 and 2 KiB of map at map base 22.

Debug console

The debug console uses stderr, and it is initialized by calling consoleDebugInit() as follows:

consoleDebugInit(DebugDevice_NOCASH);
fprintf(stderr, "debug message in no$gba window %i", stuff);

OR

consoleDebugInit(DebugDevice_CONSOLE);
fprintf(stderr, "debug message on DS console screen");

ANSI excape sequences

The regular console supports ANSI escape sequences. They are special strings that can be sent to printf() and have special effects on the console. For example, printf("\x1b[2J"); will clear the console.

Note that in the following strings a n means that you can use any positive integer value. It doesn't need to be only one character long. 0 is valid, but 23 is also valid. Also, note that you can use d instead of a hardcoded number. That way you can pass the ANSI escape sequence parameter as an argument to printf():

printf("\x1b[%d;%dm%c", color, intensity, char_to_print);`

The escape sequences supported by libnds are:

• [nA: Move cursor up by n chars (stops at the top row).
• [nB: Move cursor down by n chars (stops at the bottom row).
• [nC: Move cursor right by n chars (stops at the rightmost column).
• [nD: Move cursor left by n chars (stops at the leftmost column).

• [y;xH and [y;xf: Set cursor to (x, y).

  If the coordinates are too big, the cursor will stop at the rightmost column and the bottom row.

• [nJ: Clear screen.

  If n is 0 or it is missing, it will clear from the cursor to the end of the screen. If n is 1, it will clear from the beginning of the screen to the cursor. If n is 2, it will clear the screen and reset the cursor to (0, 0).

• [nK: Clear line.

  If n is 0 or it is missing, it will clear from the cursor to the end of the line. If n is 1, it will clear from the beginning of the line to the cursor. If n is 2, it will clear the line and reset the cursor to the start of the line.

• [s: Save current cursor position. It will overwrite the previously saved position.
• [u: Restore saved cursor position. It will preserve the saved position in case you want to restore it later.

• [c;im: Change color of the text that will be printed after this.

  Parameter c is the color, and parameter i is the intensity. Colors go from 30 to 37 (black, red, green, yellow, blue, magenta, cyan, white), and intensity can be 0 or 1 (1 will make the colors brighter).

  Color 39 resets the color back to white: printf("\x1b[39;0m");

A list of all ANSI escape sequences is available here: https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences

Typedef Documentation

ConsoleFont

typedef struct ConsoleFont ConsoleFont

A font struct for the console.

The graphics defined in this struct are loaded by consoleInit() if loadGraphics is true, and by consoleSetFont().

Warning

The space character must always be included in the font! It is required by the functions that clear the console, and it is printed when characters that are out of range are sent to the console.

PrintConsole

typedef struct PrintConsole PrintConsole

Console structure used to store the state of a console render context.

Many of the values in this struct are actually initialized by libnds, and the user should leave them as 0 when consoleInit() is called.

Default values from consoleGetDefault():

PrintConsole defaultConsole =
{
    .font =
    {
        .gfx = default_fontTiles, // Font tiles
        .pal = NULL,              // No font palette (use the default palettes)
        .numColors = 0,
        .bpp = 1,
        .asciiOffset = 32,        // First ASCII character in the set
        .numChars = 96            // Number of characters in the font set
    },
 
    .consoleWidth = 32,
    .consoleHeight = 24,
    .windowX = 0,
    .windowY = 0,
    .windowWidth = 32,
    .windowHeight = 24,
    .tabSize = 3,
    .PrintChar = NULL,
};

Enumeration Type Documentation

ConsoleColor

enum ConsoleColor

Colors of the default palettes of libnds.

Enumerator
CONSOLE_BLACK	Black.
CONSOLE_RED	Red.
CONSOLE_GREEN	Green.
CONSOLE_YELLOW	Yellow.
CONSOLE_BLUE	Blue.
CONSOLE_MAGENTA	Magenta.
CONSOLE_CYAN	Cyan.
CONSOLE_LIGHT_GRAY	Light gray.
CONSOLE_GRAY	Gray.
CONSOLE_LIGHT_RED	Light red.
CONSOLE_LIGHT_GREEN	Light green.
CONSOLE_LIGHT_YELLOW	Light yellow.
CONSOLE_LIGHT_BLUE	Light blue.
CONSOLE_LIGHT_MAGENTA	Light magenta.
CONSOLE_LIGHT_CYAN	Light cyan.
CONSOLE_WHITE	White.
CONSOLE_DEFAULT	Default color (white)

DebugDevice

enum DebugDevice

Console debug devices supported by libnds.

Enumerator
DebugDevice_NULL	Ignores prints to stderr.
DebugDevice_NOCASH	Directs stderr to the no$gba debug window.
DebugDevice_CONSOLE	Directs stderr to the DS console.

Function Documentation

consoleAddToCursor()

void consoleAddToCursor	(	PrintConsole *	console,
		int	deltaX,
		int	deltaY
	)

Moves the console cursor position from its current position.

Parameters

console	Console to set. If NULL it will set the current console window
deltaX	Value to add to the X location of the cursor.
deltaY	Value to add to the Y location of the cursor.

consoleArm7Disable()

int consoleArm7Disable

(

void

)

It disables the ARM7 console and frees the shared buffer.

Returns

It reutrns 0 on success, an error code otherwise.

consoleArm7Flush()

void consoleArm7Flush

(

void

)

This function checks the ring buffer and prints all enqueued text.

This function doesn't need to be called normally, this is requested by the ARM7 whenever it is required.

consoleArm7Setup()

int consoleArm7Setup	(	PrintConsole *	console,
		size_t	buffer_size
	)

Initialize the ARM7 console and direct the output to the specified console.

This function allocates a ring buffer in main RAM and shares the pointer with the ARM7. The ARM7 will start saving text to this buffer and the ARM9 is in charge of reading the buffer and sending it to the desired PrintConsole.

Parameters

console	Console that will receive the text from the ARM7. This must have been initialized with consoleInit() or similar functions.
buffer_size	Size of the shared buffer.

Returns

On success, it returns 0. On failure, a negative number. This can happen if the buffer is already setup or if there isn't enough space in the heap. Please, call consoleArm7Disable() first if you want to change the size of the buffer.

consoleDebugInit()

void consoleDebugInit

(

DebugDevice

device

)

Initializes the debug console output on stderr to the specified device.

Parameters

device

The debug device (or devices) to output debug print to.

consoleDemoInit()

PrintConsole * consoleDemoInit

(

void

)

Initialize the console to a default state for prototyping.

This function sets the console to use sub display, VRAM_C, and BG0 and enables MODE_0_2D on the sub display. It is intended for use in prototyping applications which need print ability and not actual game use. Print functionality can be utilized with just this call.

The console initialization is equivalent to:

consoleInit(NULL, 0, BgType_Text4bpp, BgSize_T_256x256, 22, 3, false, true);

Returns

A pointer to the current PrintConsole.

consoleGetCursor()

void consoleGetCursor	(	PrintConsole *	console,
		int *	x,
		int *	y
	)

Gets the console cursor.

Parameters

console	Console to set. If NULL it will set the current console window
x	Pointer to store the X location of the cursor.
y	Pointer to store the Y location of the cursor.

consoleGetDefault()

const PrintConsole * consoleGetDefault

(

void

)

Gets a pointer to the console with the default values.

This should only be used when using a single console or without changing the console that is returned, otherwise use consoleInit().

Returns

A read-only pointer to the console with the default values.

consoleInit()

PrintConsole * consoleInit	(	PrintConsole *	console,
		int	layer,
		BgType	type,
		BgSize	size,
		int	mapBase,
		int	tileBase,
		bool	mainDisplay,
		bool	loadGraphics
	)

Initialise the console.

Note

If you want a more customizable version of this function, check consoleInitEx().

Parameters

console	A pointer to the console data to initialze (if it's NULL, the default console will be used).
layer	Background layer to use.
type	Type of the background.
size	Size of the background.
mapBase	Map base.
tileBase	Tile graphics base.
mainDisplay	If true main engine is used, otherwise false.
loadGraphics	If true the default font graphics will be loaded into the layer.

Returns

A pointer to the current console.

consoleInitEx()

PrintConsole * consoleInitEx	(	PrintConsole *	console,
		int	layer,
		BgType	type,
		BgSize	size,
		int	mapBase,
		int	tileBase,
		int	palIndex,
		int	fontCharOffset,
		bool	mainDisplay,
		bool	loadGraphics
	)

Initialise the console.

Parameters

console	A pointer to the console data to initialze (if it's NULL, the default console will be used).
layer	Background layer to use.
type	Type of the background.
size	Size of the background.
mapBase	Map base.
tileBase	Tile graphics base.
palIndex	For 4 BPP (and 1 BPP) fonts. Palette index to load custom palettes to.
fontCharOffset	How many characters to skip in the tile base slot. This can be used to load multiple fonts to the same slot. One of them can set this to 0, and the other one can set it to 128 so that they don't overlap. Note that tile map slots can't be used by multiple consoles, they all need to be independent.
mainDisplay	If true main engine is used, otherwise false.
loadGraphics	If true the default font graphics will be loaded into the layer.

Returns

A pointer to the current console.

consolePrintChar()

void consolePrintChar

(

char

c

)

Prints a character to the default console.

Parameters

c	The character to print.

consoleSelect()

PrintConsole * consoleSelect

(

PrintConsole *

console

)

Make the specified console the render target.

Parameters

console

A pointer to the console struct (must have been initialized with consoleInit(PrintConsole* console)

Returns

A pointer to the previous console.

consoleSetColor()

void consoleSetColor	(	PrintConsole *	console,
		ConsoleColor	color
	)

Sets the color to use to print new text.

Note

This only works for 4 BPP backgrounds. 8 BPP extended palettes are not supported.

Parameters

console	Console to set. If NULL it will set the current console window
color	Color to be used for new text.

consoleSetCursor()

void consoleSetCursor	(	PrintConsole *	console,
		int	x,
		int	y
	)

Sets the console cursor position.

Parameters

console	Console to set. If NULL it will set the current console window
x	New X location of the cursor.
y	New Y location of the cursor.

consoleSetCustomStderr()

void consoleSetCustomStderr

(

ConsoleOutFn

fn

)

Sets the function where stderr is sent, bypassing the PrintConsole handler.

To reset it to the libnds console handler, call this function with NULL as an argument, or call consoleDebugInit().

Parameters

fn	Callback where stderr is sent.

consoleSetCustomStdout()

void consoleSetCustomStdout

(

ConsoleOutFn

fn

)

Sets the function where stdout is sent, bypassing the PrintConsole handler.

To reset it to the libnds console handler, call this function with NULL as an argument.

Parameters

fn	Callback where stdout is sent.

consoleSetFont()

void consoleSetFont	(	PrintConsole *	console,
		ConsoleFont *	font
	)

Loads the font into the console.

Parameters

console	Pointer to the console to update. If NULL, it will update the current console.
font	The font to load.

consoleSetWindow()

void consoleSetWindow	(	PrintConsole *	console,
		int	x,
		int	y,
		int	width,
		int	height
	)

Sets the print window dimensions.

Parameters

console	Console to set. If NULL it will set the current console window
x	X location of the window.
y	Y location of the window.
width	Width of the window.
height	Height of the window.