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   0x7000
	Default tilemap byte address — 32×32 tilemap at VRAM byte $7000.

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   0x7000

Default tilemap byte address — 32×32 tilemap at VRAM byte $7000.

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. textInit() expects a byte VRAM address — the value $7000 is what you'd read off a VRAM map.

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 byte address for the tilemap (use TEXT_DEFAULT_TILEMAP_ADDR for the standard $7000)
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)

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
	)

Set cursor position.

Parameters

x	Column (0-31 or 0-63)
y	Row (0-31 or 0-63)

Variable Documentation

text_config

TextConfig text_config

extern

Default text configuration.

Assumes font at tile 0, tilemap at $7000, palette 0