font.h File Reference

Detailed Description

Design Philosophy

Fonts are used to draw text to the display. Each font is comprised of the ASCII characters from ' ' to '~'.

All characters in the font have the same height. Each character in the font may have it's own width.

Each character is represented by a bit-packed bitmap where each bit is one pixel. Characters may be drawn in any color.

Fonts can be loaded from the filesystem with helper functions in fs_font.h. Once loaded from the filesystem they can be used to draw text to the display.

Usage

drawText() is used to draw a line of text to the display. The line won't wrap around if it draws off the display. drawTextWordWrap() can also be used to draw text to the display, and the text will wrap around if it would draw off the display. This is more computationally expensive.

drawChar() can be used to draw a single character to the display.

textWidth() is used to measure the width of text before drawing. This is useful for centering or aligning text.

textWordWrapHeight() is used to measure the height of a word-wrapped text block. There is no function to get the height of text because it is accessible in font_t.height.

Example

// Declare and load a font
font_t ibm;
loadFont("ibm_vga8.font", &ibm, false);
// Draw some white text
drawText(&ibm, c555, "Hello World", 0, 0);
// Free the font
freeFont(&ibm);

Go to the source code of this file.

Data Structures
struct	font_ch_t
	A character used in a font_t. Each character is a bitmap with the same height as the other characters in the font. More...
struct	font_t
	A font is a collection of font_ch_t for all ASCII characters. Each character has the same height and variable width. More...

Functions
void	drawChar (paletteColor_t color, int h, const font_ch_t *ch, int16_t xOff, int16_t yOff)
	Draw a single character from a font to a display.
int16_t	drawText (const font_t *font, paletteColor_t color, const char *text, int16_t xOff, int16_t yOff)
	Draw text to a display with the given color and font.
void	drawCharBounds (paletteColor_t color, int h, const font_ch_t *ch, int16_t xOff, int16_t yOff, int16_t xMin, int16_t yMin, int16_t xMax, int16_t yMax)
	Draw a single character from a font to a display.
int16_t	drawTextBounds (const font_t *font, paletteColor_t color, const char *text, int16_t xOff, int16_t yOff, int16_t xMin, int16_t yMin, int16_t xMax, int16_t yMax)
	Draw text to a display with the given color and font.
const char *	drawTextWordWrap (const font_t *font, paletteColor_t color, const char *text, int16_t *xOff, int16_t *yOff, int16_t xMax, int16_t yMax)
	Draws text, breaking on word boundaries, until the given bounds are filled or all text is drawn.
const char *	drawTextWordWrapFixed (const font_t *font, paletteColor_t color, const char *text, int16_t xStart, int16_t yStart, int16_t *xOff, int16_t *yOff, int16_t xMax, int16_t yMax)
uint16_t	textWidth (const font_t *font, const char *text)
	Return the pixel width of some text in a given font.
uint16_t	textWordWrapHeight (const font_t *font, const char *text, int16_t width, int16_t maxHeight)
	Return the height of a block of word wrapped text.
void	makeOutlineFont (font_t *srcFont, font_t *dstFont, bool spiRam)
	Create the outline of a font as a separate font.
int16_t	drawTextMarquee (const font_t *font, paletteColor_t color, const char *text, int16_t xOff, int16_t yOff, int16_t xMax, int32_t *timer)
	Draw text to the display with a marquee effect.
bool	drawTextEllipsize (const font_t *font, paletteColor_t color, const char *text, int16_t xOff, int16_t yOff, int16_t maxW, bool center)
	Draw text to the display that fits within a given length, replacing any overflowing text with "...".
int16_t	drawTextMulticolored (const font_t *font, const char *text, int16_t xOff, int16_t yOff, const paletteColor_t *colors, uint32_t colorCount, uint32_t segmentCount)
	Draws text divided into any number of colored segments.

---

Data Structure Documentation

font_ch_t

struct font_ch_t

Data Fields
uint8_t	width	The width of this character.
uint8_t *	bitmap	This character's bitmap data.

font_t

struct font_t

Data Fields
uint8_t	height	The height of this font. All chars have the same height.
font_ch_t	chars['~' - ' '+2]	An array of characters, enough space for all printed ASCII chars, and pi.

Function Documentation

drawChar()

void drawChar	(	paletteColor_t	color,
		int	h,
		const font_ch_t *	ch,
		int16_t	xOff,
		int16_t	yOff )

Draw a single character from a font to a display.

Parameters

color	The color of the character to draw
h	The height of the character to draw
ch	The character bitmap to draw (includes the width of the char)
xOff	The x offset to draw the char at
yOff	The y offset to draw the char at

drawText()

int16_t drawText	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t	xOff,
		int16_t	yOff )

Draw text to a display with the given color and font.

Parameters

font	The font to use for the text
color	The color of the character to draw
text	The text to draw to the display
xOff	The x offset to draw the text at
yOff	The y offset to draw the text at

Returns

The x offset at the end of the drawn string

drawCharBounds()

void drawCharBounds	(	paletteColor_t	color,
		int	h,
		const font_ch_t *	ch,
		int16_t	xOff,
		int16_t	yOff,
		int16_t	xMin,
		int16_t	yMin,
		int16_t	xMax,
		int16_t	yMax )

Draw a single character from a font to a display.

Parameters

color	The color of the character to draw
h	The height of the character to draw
ch	The character bitmap to draw (includes the width of the char)
xOff	The x offset to draw the char at
yOff	The y offset to draw the char at
xMin	The left edge of the text bounds
yMin	The top edge of the text bounds
xMax	The right edge of the text bounds
yMax	The bottom edge of the text bounds

drawTextBounds()

int16_t drawTextBounds	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t	xOff,
		int16_t	yOff,
		int16_t	xMin,
		int16_t	yMin,
		int16_t	xMax,
		int16_t	yMax )

Draw text to a display with the given color and font.

Parameters

font	The font to use for the text
color	The color of the character to draw
text	The text to draw to the display
xOff	The x offset to draw the text at
yOff	The y offset to draw the text at
xMin	The left edge of the text bounds
yMin	The top edge of the text bounds
xMax	The right edge of the text bounds
yMax	The bottom edge of the text bounds

Returns

The x offset at the end of the drawn string

drawTextWordWrap()

const char * drawTextWordWrap	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t *	xOff,
		int16_t *	yOff,
		int16_t	xMax,
		int16_t	yMax )

Draws text, breaking on word boundaries, until the given bounds are filled or all text is drawn.

Text will be drawn, starting at (xOff, yOff), wrapping to the next line at ' ' or '-' when the next word would exceed xMax, or immediately when a newline ('\n') is encountered. Carriage returns and tabs ('\r', '\t') are not supported. When the bottom of the next character would exceed yMax, no more text is drawn and a pointer to the next undrawn character within text is returned. If all text has been written, NULL is returned.

Parameters

font	The font to use when drawing the text
color	The color of the text to be drawn
text	The text to be pointed, as a null-terminated string
xOff	The X-coordinate to begin drawing the text at
yOff	The Y-coordinate to begin drawing the text at
xMax	The maximum x-coordinate at which any text may be drawn
yMax	The maximum y-coordinate at which text may be drawn

Returns

A pointer to the first unprinted character within text, or NULL if all text has been written

drawTextWordWrapFixed()

const char * drawTextWordWrapFixed	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t	xStart,
		int16_t	yStart,
		int16_t *	xOff,
		int16_t *	yOff,
		int16_t	xMax,
		int16_t	yMax )

textWidth()

uint16_t textWidth	(	const font_t *	font,
		const char *	text )

Return the pixel width of some text in a given font.

Parameters

font	The font to use
text	The text to measure

Returns

The width of the text rendered in the font

textWordWrapHeight()

uint16_t textWordWrapHeight	(	const font_t *	font,
		const char *	text,
		int16_t	width,
		int16_t	maxHeight )

Return the height of a block of word wrapped text.

Parameters

font	The font to use when drawing the text
text	The text to be pointed, as a null-terminated string
width	The maximum x-coordinate at which any text may be drawn
maxHeight	The maximum y-coordinate at which text may be drawn

Returns

The height of the word wrapped text block

makeOutlineFont()

void makeOutlineFont	(	font_t *	srcFont,
		font_t *	dstFont,
		bool	spiRam )

Create the outline of a font as a separate font.

Parameters

srcFont	The source font to make an outline of
dstFont	The destination font that will be initialized as an outline of the source font
spiRam	true to allocate memory in SPI RAM, false to allocate memory in normal RAM

drawTextMarquee()

int16_t drawTextMarquee	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t	xOff,
		int16_t	yOff,
		int16_t	xMax,
		int32_t *	timer )

Draw text to the display with a marquee effect.

Parameters

	font	The font to use for the text
	color	The color of the character to draw
	text	The text to draw to the display
	xOff	The x offset to draw the text at
	yOff	The y offset to draw the text at
	xMax	The x offset of the right edge of the marquee text
[in,out]	timer	A pointer to a timer value used to time the marquee

Returns

The x offset at the end of the drawn string

drawTextEllipsize()

bool drawTextEllipsize	(	const font_t *	font,
		paletteColor_t	color,
		const char *	text,
		int16_t	xOff,
		int16_t	yOff,
		int16_t	maxW,
		bool	center )

Draw text to the display that fits within a given length, replacing any overflowing text with "...".

Parameters

font	The font to use for the text
color	The color of the character to draw
text	The text to draw to the display
xOff	The x offset to draw the text at
yOff	The y offset to draw the text at
maxW	The maximum width of text to draw
center	If true, when text is not ellipsize it will be centered within the box

Returns

true

false

drawTextMulticolored()

int16_t drawTextMulticolored	(	const font_t *	font,
		const char *	text,
		int16_t	xOff,
		int16_t	yOff,
		const paletteColor_t *	colors,
		uint32_t	colorCount,
		uint32_t	segmentCount )

Draws text divided into any number of colored segments.

The entire length of text will be divided into colorCount segments

Parameters

font	The font to use for the text
text	The text to draw to the display
xOff	The x offset to draw the text at
yOff	The y offset to draw the text at
colors	An array of colors to use when drawing the text
colorCount	The number of elements in the colors array
segmentCount	The number of segments to divide the text into

Returns

int16_t The x-offset at the end of the text