text.h File Reference

Text rendering functions for OpenSNES. More...

#include <snes/types.h>

Go to the source code of this file.

Classes
struct	TextConfig
	Text rendering configuration. More...

Macros
#define	TEXT_DEFAULT_FONT_TILE   0
	Default first font tile (zero — font occupies tiles 0-95).
#define	TEXT_DEFAULT_PALETTE   0
	Default palette slot (palette 0).
#define	TEXT_DEFAULT_TILEMAP_ADDR   0x3800
	Default tilemap WORD address — 32×32 tilemap at VRAM word $3800.
#define	TEXT_MAP_ROWS   32
	Tilemap buffer height in rows.

Functions
void	textClear (void)
	Clear entire tilemap with spaces.
void	textClearRect (u8 x, u8 y, u8 w, u8 h)
	Clear a rectangular region (fills with spaces).
void	textFlush (void)
	Request tilemap DMA transfer to VRAM (rarely needed).
u8	textGetX (void)
	Get current cursor X position.
u8	textGetY (void)
	Get current cursor Y position.
void	textInit (u16 tilemap_addr, u16 font_tile, u8 palette)
	Initialize the text rendering system.
void	textLoadFont (u16 vram_addr)
	Load font tiles to VRAM.
void	textLoadFont4bpp (u16 vram_addr)
	Load font as 4bpp tiles for Mode 1 BGs.
void	textModeInit (void)
	Initialize text display mode — one-call setup for text-based examples.
void	textPrint (const char *str)
	Print a string at cursor position.
void	textPrintAt (u8 x, u8 y, const char *str)
	Print a string at specific position.
void	textPrintHex (u16 value, u8 digits)
	Print an unsigned integer in hexadecimal.
void	textPrintU16 (u16 value)
	Print an unsigned integer.
void	textPutChar (char c)
	Print a single character at cursor position.
void	textSetPos (u8 x, u8 y)
	Set cursor position.

Variables
TextConfig	text_config
	Default text configuration.

Detailed Description

Text rendering functions for OpenSNES.

Simple text rendering system using 8x8 tile fonts. Text is rendered to a background layer tilemap.

License: CC0 (Public Domain)

Macro Definition Documentation

TEXT_DEFAULT_FONT_TILE

#define TEXT_DEFAULT_FONT_TILE   0

Default first font tile (zero — font occupies tiles 0-95).

TEXT_DEFAULT_PALETTE

#define TEXT_DEFAULT_PALETTE   0

Default palette slot (palette 0).

TEXT_DEFAULT_TILEMAP_ADDR

#define TEXT_DEFAULT_TILEMAP_ADDR   0x3800

Default tilemap WORD address — 32×32 tilemap at VRAM word $3800.

Convenience constant for the most common text setup (BG3 in Mode 0/1 with text drawn at the standard tile-map slot). Pass to textInit() if you don't have a project-specific layout. This is a VRAM word address — the same unit as bgSetMapPtr() and the rest of the SDK.

TEXT_MAP_ROWS

#define TEXT_MAP_ROWS   32

Tilemap buffer height in rows.

Cost

Linking the text module takes 2048 bytes of the 8 KB plain C RAM band ($00:0000-$1FFF) for that buffer — a quarter of it — and the NMI flushes all 2048 bytes by DMA on every frame the buffer changed.

The RAM tilemap buffer is 32×32 entries (2048 bytes). The cursor wraps back to row 0 past the last row — text output never writes outside the buffer.

Function Documentation

textClear()

void textClear

(

void

)

Clear entire tilemap with spaces.

textClearRect()

void textClearRect	(	u8	x,
		u8	y,
		u8	w,
		u8	h )

Clear a rectangular region (fills with spaces).

Parameters

x	Start column
y	Start row
w	Width in tiles
h	Height in tiles

textFlush()

void textFlush

(

void

)

Request tilemap DMA transfer to VRAM (rarely needed).

As of chantier T.4 every text writer (textPutChar, textPrint, textPrintAt, textPrintU16, textPrintHex, textClear, textClearRect) sets the dirty flag itself, so the NMI handler always flushes the tilemap on the next VBlank without an explicit call.

Keep using this only when you wrote to tilemapBuffer directly, outside of the text* API — for example, if you patched a tile by hand for a custom UI element: it sends the whole buffer (2048 bytes, 16,384 master cycles of the VBlank), where the text* writers have the NMI send only the bytes they wrote since the last VBlank (since 2026-10-12). Calling it after a regular textPrint* costs that full transfer once.

textGetX()

u8 textGetX

(

void

)

Get current cursor X position.

Returns

Current column

textGetY()

u8 textGetY

(

void

)

Get current cursor Y position.

Returns

Current row

textInit()

void textInit	(	u16	tilemap_addr,
		u16	font_tile,
		u8	palette )

Initialize the text rendering system.

Configures the tilemap address, the first font tile, and the palette slot used for text glyphs. Replaces the v1 textInit/textInitEx pair — pass TEXT_DEFAULT_* constants for the previous textInit(void) defaults.

Parameters

tilemap_addr	VRAM word address for the tilemap — the same unit as bgSetMapPtr() and the rest of the SDK (use TEXT_DEFAULT_TILEMAP_ADDR for the standard $3800)
font_tile	Tile number of the first font glyph in VRAM (use TEXT_DEFAULT_FONT_TILE for tile 0)
palette	Palette slot 0-7 (use TEXT_DEFAULT_PALETTE for 0)

Warning

This writes VRAM immediately — it clears the tilemap through the synchronous flush, unlike textFlush(), which only raises a flag for the NMI. Call it during forced blank, with the rest of your setup, not from a running frame.

Note

As of v0.23.0 this takes a VRAM word address. It used to take a byte address (the lone SDK unit inconsistency, now removed); old call sites that passed W * 2 should now pass W.

textLoadFont()

void textLoadFont

(

u16

vram_addr

)

Load font tiles to VRAM.

Loads the built-in OpenSNES font to VRAM. Call during forced blank.

Parameters

vram_addr

VRAM word address for tiles

Warning

Not callable from an nmiSet() callback: the DMA registers are written with absolute addressing (sta $4300) and the callback runs with the data bank at $7E, so the writes would land in WRAM and no font would be uploaded (library audit l.21). An init-time call, before the loop, is the intended use.

textLoadFont4bpp()

void textLoadFont4bpp

(

u16

vram_addr

)

Load font as 4bpp tiles for Mode 1 BGs.

Bitplanes 2-3 are zero; font uses colors 0-3 of its palette slot. Use this instead of textLoadFont() when text is on a 4bpp BG layer (e.g., BG1 or BG2 in Mode 1).

Requires 'text4bpp' in LIB_MODULES.

Parameters

vram_addr

VRAM word address for tiles

Warning

Not callable from an nmiSet() callback, like textLoadFont(): absolute DMA register writes under the callback's $7E data bank.

textModeInit()

void textModeInit

(

void

)

Initialize text display mode — one-call setup for text-based examples.

Sets up Mode 0, BG1, white-on-black palette, font at VRAM $0000, tilemap at $3800 (32x32). Replaces the 8-line init sequence found in most text-based examples.

Call setScreenOn() after this to display.

Equivalent to:

consoleInit();
setMode(BG_MODE0, 0);
setColor(0, 0x0000);
setColor(1, RGB(31, 31, 31));
textInit(TEXT_DEFAULT_TILEMAP_ADDR, TEXT_DEFAULT_FONT_TILE, TEXT_DEFAULT_PALETTE);
textLoadFont(0x0000);
bgSetGfxPtr(0, 0x0000);
bgSetMapPtr(0, 0x3800, BG_MAP_32x32);
setMainScreen(LAYER_BG1);

textPrint()

void textPrint

(

const char *

str

)

Print a string at cursor position.

Parameters

str	Null-terminated string

textPrintAt()

void textPrintAt	(	u8	x,
		u8	y,
		const char *	str )

Print a string at specific position.

Parameters

x	Column
y	Row
str	Null-terminated string

textPrintHex()

void textPrintHex	(	u16	value,
		u8	digits )

Print an unsigned integer in hexadecimal.

Parameters

value	Number to print
digits	Number of hex digits (1-4)

textPrintU16()

void textPrintU16

(

u16

value

)

Print an unsigned integer.

Parameters

value

Number to print

textPutChar()

void textPutChar

(

char

c

)

Print a single character at cursor position.

Advances cursor. Handles newlines.

Parameters

c	Character to print (ASCII 32-127)

textSetPos()

void textSetPos	(	u8	x,
		u8	y )

Set cursor position.

Parameters

x	Column (0-31; masked to the 32-column buffer)
y	Row (0-31; masked to TEXT_MAP_ROWS)

A lib function since 2026-10-03 (it was inline in this header, which forced the cursor variables to be exported; API decision D4).

Variable Documentation

text_config

TextConfig text_config

extern

Default text configuration.

Assumes font at tile 0, tilemap at word $3800, palette 0