rdpq_font.c File Reference

Macros
#define	MAX_STYLES   256
	Maximum number of font styles.
#define	PTR_DECODE(font, ptr)   ((void*)(((uint8_t*)(font)) + (uint32_t)(ptr)))
	Decode a pointer relative to font base.
#define	PTR_ENCODE(font, ptr)   ((void*)(((uint8_t*)(ptr)) - (uint32_t)(font)))
	Encode a pointer relative to font base.

Functions
rdpq_font_t *	rdpq_font_load_buf (void *buf, int sz)
	Load a font from a buffer in memory (.font64 format).
rdpq_font_t *	rdpq_font_load (const char *fn)
	Load a font from a file (.font64 format).
void	rdpq_font_free (rdpq_font_t *fnt)
	Free a font.
int16_t	__rdpq_font_glyph (const rdpq_font_t *fnt, uint32_t codepoint)
	Look up a glyph in a font.
float	__rdpq_font_kerning (const rdpq_font_t *fnt, int16_t glyph1, int16_t glyph2)
	Get kerning between two glyphs.
void	rdpq_font_style (rdpq_font_t *fnt, uint8_t style_id, const rdpq_fontstyle_t *style)
	Create a style for a font.
int	rdpq_font_render_paragraph (const rdpq_font_t *fnt, const rdpq_paragraph_char_t *chars, float x0, float y0)
	Render a certain number of chars from a paragraph.
bool	rdpq_font_get_glyph_ranges (const rdpq_font_t *fnt, int idx, uint32_t *start, uint32_t *end, bool *sparse)
	Get information on the Unicode codepoint ranges covered by a font.
int	rdpq_font_get_glyph_index (const rdpq_font_t *fnt, uint32_t codepoint)
	Get the internal index of a glyoh given the codepoint.
bool	rdpq_font_get_glyph_metrics (const rdpq_font_t *fnt, uint32_t codepoint, rdpq_font_gmetrics_t *metrics)
	Get the metrics of a glyph in a font.
rdpq_font_t *	__rdpq_font_load_builtin_1 (void)
	Load built-in font 1 (monogram)
rdpq_font_t *	__rdpq_font_load_builtin_2 (void)
	Load built-in font 2 (At01)
void	__rdpq_font_glyph_metrics (const rdpq_font_t *fnt, int16_t index, float *xadvance, int8_t *xoff, int8_t *xoff2, bool *has_kerning, uint8_t *sort_key)
	Get glyph metrics for a font glyph.
rdpq_font_t *	rdpq_font_load_builtin (rdpq_font_builtin_t font)
	Load a builtin font provided by libdragon.

Detailed Description

Author

Giovanni Bajo giova.nosp@m.nnib.nosp@m.ajo@g.nosp@m.mail.nosp@m..com

Function Documentation

rdpq_font_load_buf()

rdpq_font_t * rdpq_font_load_buf	(	void *	buf,
		int	sz
	)

Load a font from a buffer in memory (.font64 format).

This function is similar to rdpq_font_load, but it loads the font from a buffer in memory instead of a file. The contents of the buffer must be in the .font64 format, as created by the mkfont tool.

As data is not duplicated, the buffer must stay in memory for the lifetime of the font.

Parameters

buf	Buffer to load
sz	Size of the buffer

Returns

rdpq_font_t* Loaded font

rdpq_font_load()

rdpq_font_t * rdpq_font_load

(

const char *

fn

)

Load a font from a file (.font64 format).

This function loads a font from a file. The file must be in the .font64 format, as created by the mkfont tool.

Parameters

fn	Filename to load (including filesystem prefix, eg: "rom:/arial.font64")

Returns

rdpq_font_t* Loaded font

rdpq_font_free()

void rdpq_font_free

(

rdpq_font_t *

fnt

)

Free a font.

This function frees a font previously loaded with rdpq_font_load or rdpq_font_load_buf (though in the latter case, the buffer must then be freed manually).

Parameters

fnt	Font to free

__rdpq_font_glyph()

int16_t __rdpq_font_glyph	(	const rdpq_font_t *	font,
		uint32_t	codepoint
	)

Look up a glyph in a font.

Parameters

font	Font to look up the glyph in
codepoint	Unicode codepoint of the glyph

Returns

int16_t Index of the glyph in the font, or -1 if not found

rdpq_font_style()

void rdpq_font_style	(	rdpq_font_t *	font,
		uint8_t	style_id,
		const rdpq_fontstyle_t *	style
	)

Create a style for a font.

This function creates a style for a font. Styles are used to change the visual appearance of a font, for example to change the color of the text.

Each style is identified with a "style ID" (which is a number in range 0..255). After calling this function, the style will be available for rendering.

See rdpq_text_printn for information on how to specify the style of a text being printed.

Parameters

font	Font to create the style for
style_id	Style ID to assign to the style
style	Parameters of the style to create

rdpq_font_render_paragraph()

int rdpq_font_render_paragraph	(	const rdpq_font_t *	fnt,
		const rdpq_paragraph_char_t *	chars,
		float	x0,
		float	y0
	)

Render a certain number of chars from a paragraph.

This function will render a set of characters from a paragraph. It assumes that the paragraph has already been fully built, so the chars must be in strict sorted order (by style and glyph index).

The number of chars is not specified. The function is expected to go through the array rendering all characters with the same font_id as the first one, until it finds a different font_id.

Parameters

fnt	Font to use to render the paragraph
chars	Array of chars to render
x0	X coordinate of the start of the paragraph (baseline first char)
y0	Y coordinate of the start of the paragraph (baseline first char)

Returns

int Number of chars rendered

rdpq_font_get_glyph_ranges()

bool rdpq_font_get_glyph_ranges	(	const rdpq_font_t *	fnt,
		int	idx,
		uint32_t *	start,
		uint32_t *	end,
		bool *	sparse
	)

Get information on the Unicode codepoint ranges covered by a font.

Fonts can cover several ranges of Unicode codepoints. This function allows to query the ranges one by one, using the idx parameter. There is no minimum or maximum size for a range.

If the idx parameter is out of bounds, the function will return false. To iterate over all ranges, start with idx = 0 and increment it until the function returns false.

The ranges are guranteed to be sorted in ascending order.

Notice that font64 support "sparse ranges", which are ranges where not all glyphs are defined. To avoid excess memory usage, the font doesn't store exactly which glyphs are stored, so it is not possible to retrieve this information.

Parameters

[in]	fnt	Font to query
[in]	idx	Index of the range to query
[out]	start	Start of the range
[out]	end	End of the range (inclusive)
[out]	sparse	Set to true if not all glyphs in the range are defined

Returns

true If the index is valid

false If the index is out of bounds

rdpq_font_get_glyph_index()

int rdpq_font_get_glyph_index	(	const rdpq_font_t *	fnt,
		uint32_t	codepoint
	)

Get the internal index of a glyoh given the codepoint.

This function returns the internal index of a glyph given its unicode codepoint. The index can be used to perform further lookups (eg: get the metrics), or just to verify whether a glyph exists in the font or not.

When calling this query for a glyph that falls within a sparse range, false positives can be returned. That is, for a certain unicode codepoint within the range but that is not present in the font, this function might return a wrong index (actually referring to a different glyph). This happens because font64 does not store the codepoints for glyphs in sparse ranges, and querying a non existing glyph is considered undefined behavior.

Parameters

fnt	Font to query
codepoint	Unicode codepoint of the glyph

Returns

int Internal index of the glyph, or -1 if the glyph does not exist

rdpq_font_get_glyph_metrics()

bool rdpq_font_get_glyph_metrics	(	const rdpq_font_t *	fnt,
		uint32_t	codepoint,
		rdpq_font_gmetrics_t *	metrics
	)

Get the metrics of a glyph in a font.

Note

This is a low-level function for very advanced use cases. Most users should instead rely to the layout functions provided by rdpq_text.h and rdpq_paragraph.h

Parameters

fnt	Font to query
codepoint	Unicode codepoint of the glyph
metrics	Pointer to a structure to store the metrics

Returns

bool true if the glyph was found, false otherwise

__rdpq_font_glyph_metrics()

void __rdpq_font_glyph_metrics ( const rdpq_font_t *  fnt, int16_t  index, float *  xadvance, int8_t *  xoff, int8_t *  xoff2, bool *  has_kerning, uint8_t *  atlas_id  )

externinline

Get glyph metrics for a font glyph.

Parameters

fnt	Font to query.
index	Index of the glyph in the font.
xadvance	Pointer to store the advance width (can be NULL).
xoff	Pointer to store the start x offset (can be NULL).
xoff2	Pointer to store the end x offset (can be NULL).
has_kerning	Pointer to store whether the glyph has kerning (can be NULL).
atlas_id	Pointer to store the atlas ID (can be NULL).

rdpq_font_load_builtin()

rdpq_font_t * rdpq_font_load_builtin ( rdpq_font_builtin_t  font )

externinline

Load a builtin font provided by libdragon.

Builtin fonts are simple debug fonts shipped with libdragon itself, to let people quickly write something on the screen without much hassle. They are meant mainly for debug purposes.

See rdpq_font_builtin_t for a list of available builtin fonts.

Parameters

font	Builtin font to load

Returns

rdpq_font_t* Loaded font