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)

Variables
u8	cursor_x
	Set cursor position.
u8	cursor_y
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.

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. Calling it redundantly after a regular textPrint* is a no-op.

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)

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

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

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 )

inline

Variable Documentation

cursor_x

u8 cursor_x

extern

Set cursor position.

Parameters

x	Column (0-31; masked to the 32-column buffer)
y	Row (0-31; masked to TEXT_MAP_ROWS) Inlined for zero-call-overhead access (wave 4 retrofit; uses the relaxed CC_INLINE_MAX_INSTR=16 default).

cursor_y

u8 cursor_y

extern

text_config

TextConfig text_config

extern

Default text configuration.

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