Lettering masks

Outlined, shadowed and gradient lettering, logos and the cover titles. More...

Classes
struct	Mask
	A 1 bpp shape being built in the chunk scratch. Made by maskBegin(). More...

Functions
Mask	maskBegin (int w, int h)
	Start an empty mask in the chunk scratch.
void	maskText35 (Mask &m, int x, int y, const char *s, uint8_t scale=1, const int8_t *dy=nullptr)
	Add text in the 3x5 font to a mask, at an integer scale.
int	text35WidthScaled (const char *s, uint8_t scale)
	The width of 3x5 text at a scale, for sizing a mask.
void	maskBlit1 (Mask &m, const uint8_t *bits, uint8_t w, uint8_t h, uint8_t scale=1)
	Add a 1 bpp bitmap (a logo) to a mask.
void	maskDraw (const Mask &m, int x, int y, uint8_t fill, int outline=-1, int shadow=-1, const uint8_t *ramp=nullptr)
	Paint a mask, with an optional outline, shadow and gradient.
void	maskPaint (const Mask &m, int x, int y, uint8_t c)
	Paint just the shape in one colour (no outline, no shadow).
void	maskTitle (const Mask &m, int x, int y, uint8_t base, const uint8_t *ramp, uint8_t depth, uint8_t side)
	Paint a title as the covers set it, in the house gold.
void	titleArt (const uint8_t *bits, uint8_t w, uint8_t h, int x, int y, uint8_t base, const uint8_t *ramp, uint8_t depth, uint8_t side)
	Paint a game's title from the arrays tools/titleart.py writes from its cover recipe: maskBegin(), maskBlit1() and maskTitle() in one call.

Detailed Description

Outlined, shadowed and gradient lettering, logos and the cover titles.

The mask lives in CHGfx's chunk buffers (gfx_chunkScratch, 1 KB), which are idle between gfx_wait() and the next flush - i.e. while drawing. Never keep a Mask across frames or use one outside drawing. Masks paint anywhere on screen: they ignore CHGfx's clip rectangle.

Mask m = maskBegin(text35WidthScaled("WIN", 3), 6 * 3);
maskText35(m, 0, 0, "WIN", 3);
maskDraw(m, 40, 50, GOLD, INK, WINE);       // fill, outline, shadow

Function Documentation

maskBegin()

Mask maskBegin	(	int	w,
		int	h
	)

Start an empty mask in the chunk scratch.

Parameters

w,h	Usable size in pixels; with the 1 px margin, (w + 2) x (h + 2) must fit in 1 KB of bits (about 8000 px).

Returns

The mask, cleared. Valid until the next flush or the next maskBegin() (or anything else that uses gfx_chunkScratch()).

maskText35()

void maskText35	(	Mask &	m,
		int	x,
		int	y,
		const char *	s,
		uint8_t	scale = 1,
		const int8_t *	dy = nullptr
	)

Add text in the 3x5 font to a mask, at an integer scale.

Parameters

m	The mask.
x,y	Top-left of the text inside the mask.
s	The text ('~' is a half space).
scale	Size: each font pixel becomes scale x scale (4*scale px advance, 6*scale rows with the descender).
dy	Optional: a vertical offset for each character (wavy banners).

text35WidthScaled()

int text35WidthScaled	(	const char *	s,
		uint8_t	scale
	)

The width of 3x5 text at a scale, for sizing a mask.

Parameters

s	The text.
scale	The scale given to maskText35().

Returns

text35Width(s) * scale.

maskBlit1()

void maskBlit1	(	Mask &	m,
		const uint8_t *	bits,
		uint8_t	w,
		uint8_t	h,
		uint8_t	scale = 1
	)

Add a 1 bpp bitmap (a logo) to a mask.

Parameters

m	A mask begun at w*scale x h*scale.
bits	The bitmap: MSB-first rows of (w + 7) / 8 bytes, zero padding bits.
w,h	Its size in pixels.
scale	Each bitmap pixel becomes scale x scale.

maskDraw()

void maskDraw	(	const Mask &	m,
		int	x,
		int	y,
		uint8_t	fill,
		int	outline = -1,
		int	shadow = -1,
		const uint8_t *	ramp = nullptr
	)

Paint a mask, with an optional outline, shadow and gradient.

Parameters

m	The mask.
x,y	Where its top-left (inside the margin) goes on screen.
fill	Colour of the shape.
outline	Colour of a 1 px ring around it (all 8 directions), or -1 for none.
shadow	Colour of a shadow, or -1 for none: the outline moved a pixel down and right, or without an outline the shape moved so.
ramp	Optional: a fill colour for each mask row, replacing fill (gradient lettering).

maskPaint()

void maskPaint	(	const Mask &	m,
		int	x,
		int	y,
		uint8_t	c
	)

Paint just the shape in one colour (no outline, no shadow).

Parameters

m	The mask.
x,y	Where its top-left goes on screen.
c	Colour.

maskTitle()

void maskTitle	(	const Mask &	m,
		int	x,
		int	y,
		uint8_t	base,
		const uint8_t *	ramp,
		uint8_t	depth,
		uint8_t	side
	)

Paint a title as the covers set it, in the house gold.

(docs/cover-art.md, "the stack".) The shape extruded depth px down and right in side, an INK outline round letters and extrusion together, thickened a pixel down and right (the drop shadow), and the face a smooth gradient. A one-pixel gap between letters stays INK. About twice a maskDraw(): draw it onto still screens where the game can.

Parameters

m	The mask holding the lettering.
x,y	Where its top-left goes on screen.
base	The face's base colour.
ramp	A byte for each mask row: a colour (high nibble) laid over base where the row's dither pattern (low nibble, MSB the first of every 4 pixels from the lettering's left; 0 none, 15 all) has bits. tools/titleart.py works the patterns out of a 4x4 ordered dither.
depth	The extrusion in pixels, at most 4.
side	The extrusion's colour.

titleArt()

void titleArt	(	const uint8_t *	bits,
		uint8_t	w,
		uint8_t	h,
		int	x,
		int	y,
		uint8_t	base,
		const uint8_t *	ramp,
		uint8_t	depth,
		uint8_t	side
	)

Paint a game's title from the arrays tools/titleart.py writes from its cover recipe: maskBegin(), maskBlit1() and maskTitle() in one call.

Parameters

bits	The 1 bpp lettering (as maskBlit1()).
w,h	Its size in pixels.
x,y	Where its top-left goes on screen.
base	The face's base colour.
ramp	The gradient, a byte a row (as maskTitle()).
depth	The extrusion in pixels, at most 4.
side	The extrusion's colour.