Font loading, text measurement and text drawing. More...

#include <stddef.h>
#include <stdint.h>
#include "tinyimg/image.h"
#include "tinyimg/memory.h"
#include "tinyimg/tinyimg.h"

Classes
struct	TinyFont
	A loaded face. More...
struct	TinyFontMetrics
	What a face says about itself, in pixels at a size. More...
struct	TinyTextStyle
	How a run of text is set. More...
struct	TinyTextMetrics
	What a run of text occupies. More...

Typedefs
typedef enum TinyFontKind	TinyFontKind
	Outline and bitmap face formats.
typedef enum TinyTextAlign	TinyTextAlign
	Where a line sits inside the width it was given.

Enumerations
enum	TinyFontKind { TINYIMG_FONT_TRUETYPE = 0 , TINYIMG_FONT_PSF = 1 , TINYIMG_FONT_BDF = 2 }
	Outline and bitmap face formats. More...
enum	TinyTextAlign { TINYIMG_ALIGN_LEFT = 0 , TINYIMG_ALIGN_CENTER = 1 , TINYIMG_ALIGN_RIGHT = 2 }
	Where a line sits inside the width it was given. More...

Functions
int	tiny_font_load (TinyFont font, const char blob_id)
	Loads a face from a resident blob.
int	tiny_font_load_bytes (TinyFont font, const uint8_t data, size_t size)
	Loads a face from bytes the caller keeps.
void	tiny_font_free (TinyFont *font)
	Releases whatever a face owns.
int	tiny_font_metrics (const TinyFont font, float size, TinyFontMetrics out)
	Reads a face's vertical metrics at an em size.
int	tiny_font_has_glyph (const TinyFont *font, uint32_t codepoint)
	Reports whether a face has a glyph for a codepoint.
uint32_t	tiny_font_sizeof (void)
	Size of a TinyFont, for a host allocating one across the wasm boundary.
uint32_t	tiny_font_metrics_sizeof (void)
	Size of a TinyFontMetrics, for the same reason.
void	tiny_text_style (TinyTextStyle *style, float size)
	Fills a style in with the defaults.
int	tiny_image_draw_text (TinyImage image, const TinyFont font, const char text, int32_t x, int32_t y, const TinyTextStyle style, const uint8_t *color)
	Draws a line of text.
int	tiny_image_draw_text_box (TinyImage image, const TinyFont font, const char text, int32_t x, int32_t y, uint32_t width, uint32_t height, const TinyTextStyle style, TinyTextAlign align, const uint8_t *color)
	Draws text wrapped and aligned inside a rectangle.
int	tiny_text_measure (const TinyFont font, const char text, const TinyTextStyle style, TinyTextMetrics out)
	Measures a run of text without drawing it.
int	tiny_text_measure_wrapped (const TinyFont font, const char text, uint32_t width, const TinyTextStyle style, TinyTextMetrics out)
	Measures a run of text as it would be wrapped inside a width.
uint32_t	tiny_text_style_sizeof (void)
	Size of a TinyTextStyle, for a host allocating one across the wasm boundary.
uint32_t	tiny_text_metrics_sizeof (void)
	Size of a TinyTextMetrics, for the same reason.

Detailed Description

Font loading, text measurement and text drawing.

Author: Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version: 1.0.0

Date: 2026-09-03

Copyright: Copyright (c) 2026

Typedef Documentation

◆ TinyFontKind

typedef enum TinyFontKind TinyFontKind

Outline and bitmap face formats.

Dispatched from the first four bytes, so a caller never says which one they have. The three are genuinely different shapes rather than variants of one: an outline face has a curve per glyph and scales to any size, and a bitmap face has a fixed grid and one size.

Enumeration Type Documentation

◆ TinyFontKind

enum TinyFontKind

Outline and bitmap face formats.

Dispatched from the first four bytes, so a caller never says which one they have. The three are genuinely different shapes rather than variants of one: an outline face has a curve per glyph and scales to any size, and a bitmap face has a fixed grid and one size.

Enumerator

TINYIMG_FONT_TRUETYPE

Quadratic outlines in a glyf table.

Both the .ttf and the .otf wrappers of it. An OpenType file whose outlines are CFF charstrings rather than glyf is a different format behind the same extension, and loading one reports TINYIMG_ERR_UNSUPPORTED_VARIANT.

TINYIMG_FONT_PSF

A PC screen font: one fixed cell, one bit per pixel.

TINYIMG_FONT_BDF

Glyph Bitmap Distribution Format, one bitmap per glyph.

◆ TinyTextAlign

enum TinyTextAlign

Where a line sits inside the width it was given.

Enumerator
TINYIMG_ALIGN_LEFT	Against the left edge.
TINYIMG_ALIGN_CENTER	Centered in the width.
TINYIMG_ALIGN_RIGHT	Against the right edge.

Function Documentation

◆ tiny_font_free()

void tiny_font_free ( TinyFont * font )

Releases whatever a face owns.

Never the bytes, which belong to the blob table or to the caller. Only a BDF face owns anything, so this is a no-op for the other two; calling it always is still the right habit and costs a branch.

Parameters

font	The face, left safe to load into again.

◆ tiny_font_has_glyph()

int tiny_font_has_glyph	(	const TinyFont *	font,
		uint32_t	codepoint )

Reports whether a face has a glyph for a codepoint.

Parameters

font	The face.
codepoint	The Unicode codepoint.

Returns: int Non-zero when it does. A codepoint it does not have still draws: it maps to glyph zero, which is what a text renderer does with one.

◆ tiny_font_load()

int tiny_font_load	(	TinyFont *	font,
		const char *	blob_id )

Loads a face from a resident blob.

The blob is what a Worker has: imported as a wrangler Data module, or fetched from a bucket and handed to tiny_blob_load. Its bytes stay owned by the blob table, so the face borrows them and tiny_blob_free invalidates it.

Parameters

font	Receives the face.
blob_id	The id it was loaded under, or NULL for the first font blob.

Returns: int TINYIMG_OK, TINYIMG_ERR_BLOB_MISSING when no such blob is resident, TINYIMG_ERR_UNKNOWN_FORMAT when the bytes match no face format, TINYIMG_ERR_UNSUPPORTED_VARIANT for a CFF-outlined OpenType file, or TINYIMG_ERR_CORRUPT.

◆ tiny_font_load_bytes()

int tiny_font_load_bytes	(	TinyFont *	font,
		const uint8_t *	data,
		size_t	size )

Loads a face from bytes the caller keeps.

The escape hatch from the blob table, and the difference is ownership: tiny_blob_load takes the bytes and frees them, this borrows them and frees nothing. Use it when the bytes are already somewhere convenient, or when a face is wanted for one call and should not occupy a blob slot.

Parameters

font	Receives the face.
data	The face's bytes, which must outlive the face.
size	How many.

Returns: int TINYIMG_OK or a negative TinyImageError; see tiny_font_load.

◆ tiny_font_metrics()

int tiny_font_metrics	(	const TinyFont *	font,
		float	size,
		TinyFontMetrics *	out )

Reads a face's vertical metrics at an em size.

Parameters

font	The face.
size	Em size in pixels. Zero, or any size for a bitmap face, reports the face's own.
out	Receives the metrics.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_font_metrics_sizeof()

uint32_t tiny_font_metrics_sizeof ( void )

Size of a TinyFontMetrics, for the same reason.

Returns: uint32_t sizeof(TinyFontMetrics).

◆ tiny_font_sizeof()

uint32_t tiny_font_sizeof ( void )

Size of a TinyFont, for a host allocating one across the wasm boundary.

Returns: uint32_t sizeof(TinyFont).

◆ tiny_image_draw_text()

int tiny_image_draw_text	(	TinyImage *	image,
		const TinyFont *	font,
		const char *	text,
		int32_t	x,
		int32_t	y,
		const TinyTextStyle *	style,
		const uint8_t *	color )

Draws a line of text.

x and y are the top left of the line box, not the baseline, which is what every other drawing entry point in this library takes and what a caller placing a label wants. The baseline is y + metrics.ascent, so a caller who wants to sit text on a baseline subtracts that.

A newline in text starts a new line at x, so a short multi-line string needs no box.

Parameters

image	The image to draw on.
font	The face.
text	UTF-8, NUL terminated. A malformed sequence draws the replacement glyph rather than failing.
x	Left edge of the line box; may be negative.
y	Top edge of the line box; may be negative.
style	How to set it, or NULL for the defaults at the face's own size.
color	The color, as many channels as the image has.

Returns: int TINYIMG_OK, TINYIMG_ERR_BLOB_MISSING for an unloaded face, or a negative TinyImageError.

◆ tiny_image_draw_text_box()

int tiny_image_draw_text_box	(	TinyImage *	image,
		const TinyFont *	font,
		const char *	text,
		int32_t	x,
		int32_t	y,
		uint32_t	width,
		uint32_t	height,
		const TinyTextStyle *	style,
		TinyTextAlign	align,
		const uint8_t *	color )

Draws text wrapped and aligned inside a rectangle.

Wraps on spaces where it can and mid-word where a single word is wider than the box, so a long unbroken string is clipped by the box rather than running out of it. A line whose box has run out of height is not drawn, and the metrics still report every line the text would have taken, so a caller can tell that it overflowed.

Parameters

image	The image to draw on.
font	The face.
text	UTF-8, NUL terminated.
x	Left edge of the box.
y	Top edge of the box.
width	Width to wrap inside. Zero draws nothing.
height	Height to fill. Zero means no limit.
style	How to set it, or NULL for the defaults.
align	Where each line sits inside width.
color	The color, as many channels as the image has.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_text_measure()

int tiny_text_measure	(	const TinyFont *	font,
		const char *	text,
		const TinyTextStyle *	style,
		TinyTextMetrics *	out )

Measures a run of text without drawing it.

Named for the text rather than for an image because it takes none: the size of a string is a property of the face and the style. It is the same layout the drawing entry points use, so measuring and then drawing at the measured position lands where the measurement said.

Parameters

font	The face.
text	UTF-8, NUL terminated. Newlines count as line breaks.
style	How it would be set, or NULL for the defaults.
out	Receives the metrics.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_text_measure_wrapped()

int tiny_text_measure_wrapped	(	const TinyFont *	font,
		const char *	text,
		uint32_t	width,
		const TinyTextStyle *	style,
		TinyTextMetrics *	out )

Measures a run of text as it would be wrapped inside a width.

Parameters

font	The face.
text	UTF-8, NUL terminated.
width	Width to wrap inside. Zero measures without wrapping.
style	How it would be set, or NULL for the defaults.
out	Receives the metrics, whose lines is what the wrap produced.

Returns: int TINYIMG_OK or a negative TinyImageError.

◆ tiny_text_metrics_sizeof()

uint32_t tiny_text_metrics_sizeof ( void )

Size of a TinyTextMetrics, for the same reason.

Returns: uint32_t sizeof(TinyTextMetrics).

◆ tiny_text_style()

void tiny_text_style	(	TinyTextStyle *	style,
		float	size )

Fills a style in with the defaults.

Parameters

style	Receives them.
size	Em size in pixels.

◆ tiny_text_style_sizeof()

uint32_t tiny_text_style_sizeof ( void )

Size of a TinyTextStyle, for a host allocating one across the wasm boundary.

Returns: uint32_t sizeof(TinyTextStyle).

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ TinyFontKind

Enumeration Type Documentation

◆ TinyFontKind

◆ TinyTextAlign

Function Documentation

◆ tiny_font_free()

◆ tiny_font_has_glyph()

◆ tiny_font_load()

◆ tiny_font_load_bytes()

◆ tiny_font_metrics()

◆ tiny_font_metrics_sizeof()

◆ tiny_font_sizeof()

◆ tiny_image_draw_text()

◆ tiny_image_draw_text_box()

◆ tiny_text_measure()

◆ tiny_text_measure_wrapped()

◆ tiny_text_metrics_sizeof()

◆ tiny_text_style()

◆ tiny_text_style_sizeof()