pico_font.h File Reference

A simple, dynamic (online) font atlas. More...

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

Include dependency graph for pico_font.h:

Go to the source code of this file.

Classes
struct	pf_glyph_t
	UV coordinates and metrics for a cached glyph. More...
struct	pf_quad_t
	Quad emitted by pf_draw_text. More...
struct	pf_metrics_t
	Vertical font metrics for a face. More...

Typedefs
typedef struct pf_atlas_t	pf_atlas_t
	Opaque atlas handle.
typedef struct pf_face_t	pf_face_t
	Opaque font-face handle.
typedef bool(*	pf_draw_callback_fn) (const pf_quad_t *quad, void *user)
	Callback invoked for each glyph quad during text drawing.
typedef bool(*	pf_upload_callback_fn) (size_t page, const unsigned char *pixels, int width, int height, void *user)
	Callback invoked for each dirty atlas page during pf_upload_atlas.

Functions
pf_atlas_t *	pf_create_atlas (int page_width, int max_page_height)
	Allocates and initializes a font atlas.
void	pf_destroy_atlas (pf_atlas_t *atlas)
	Destroys a font atlas and frees all associated pages and glyphs.
pf_face_t *	pf_create_face (pf_atlas_t *atlas, const unsigned char *ttf_data, size_t ttf_data_size, float pixel_height)
	Create a font face at a given pixel height.
void	pf_destroy_face (pf_face_t *face)
	Destroys a font face and frees the TTF data it owns.
const pf_glyph_t *	pf_get_glyph (pf_face_t *face, uint32_t codepoint)
	Get (or rasterize) a single glyph.
void	pf_draw_text (pf_face_t *face, const char *text, float *x, float *y, pf_draw_callback_fn cb, void *user)
	Lay out and emit quads for a UTF-8 string.
void	pf_upload_atlas (pf_atlas_t *atlas, pf_upload_callback_fn cb, void *user)
	Iterate over dirty pages and invoke the callback for each one.
void	pf_measure_text (pf_face_t *face, const char *text, float *out_width, float *out_height)
	Measure a UTF-8 string without drawing.
void	pf_get_metrics (const pf_face_t *face, pf_metrics_t *metrics)
	Retrieve vertical font metrics for a face.
float	pf_get_kerning (const pf_face_t *face, uint32_t cp1, uint32_t cp2)
	Get the horizontal kerning adjustment between two codepoints.

Detailed Description

A simple, dynamic (online) font atlas.

---

Licensing information at end of header

Introduction:

A single-header library that rasterizes and caches glyphs on demand into a multi-page texture atlas. Each page is a single-channel (alpha) bitmap with a fixed width and a height that grows on demand up to a configurable maximum. When a page is full, a new page is appended automatically. Glyph placement uses row-based shelf packing. The library also supports basic, single line drawing, but can be customized using the available metrics and measurement functions.

Features:

• Written in C99
• On-demand glyph rasterization via stb_truetype.h
• Multi-page atlas with automatic page growth and creation
• Hashtable glyph cache with automatic rehashing
• UTF-8 text layout with kerning (rendering API agnostic)
• Text measurement and font metrics
• Dirty-page tracking for efficient GPU uploads

Revision History:

• 0.1 (2026/04/11):
  • On-demand glyph rasterization and storage
  • Simple text rendering

Usage:

#define PICO_FONT_IMPLEMENTATION
#include "pico_font.h"

You must also have stb_truetype.h available. Define STB_TRUETYPE_IMPLEMENTATION exactly once in your project after including this file.

Quick Start:

pf_atlas_t* atlas = pf_create_atlas(512, 512);   // page width, max page height
pf_face_t*  face  = pf_create_face(atlas, ttf_data, 32.0f);  // 32px height
 
// During rendering (call every frame for each string):
float x = 10, y = 50;
pf_draw_text(face, "Hello!", &x, &y, my_quad_callback, user_ptr);
 
// The callback receives screen-space quads with atlas UVs and page index.
// After pf_draw_text, upload any dirty atlas pages to the GPU:
pf_upload_atlas(atlas, my_upload_callback, user_ptr);
 
pf_destroy_face(face);
pf_destroy_atlas(atlas);

Full Example:

A more or less complete example can be found at: examples_pico_gfx/text.c

Macro Overrides:

• PICO_FONT_ASSERT (default: assert)
• PICO_FONT_MALLOC (default: malloc)
• PICO_FONT_CALLOC (default: calloc)
• PICO_FONT_REALLOC (default: realloc)
• PICO_FONT_FREE (default: free)
• PICO_FONT_MEMSET (default: memset)
• PICO_FONT_MEMCPY (default: memcpy)

Constant Overrides:

• PICO_FONT_GLYPH_PADDING (default: 1)
• PICO_FONT_CACHE_INIT_SIZE (default: 256)
• PICO_FONT_INIT_PAGE_HEIGHT (default: 64)

Typedef Documentation

pf_atlas_t

typedef struct pf_atlas_t pf_atlas_t

Opaque atlas handle.

pf_face_t

typedef struct pf_face_t pf_face_t

Opaque font-face handle.

pf_draw_callback_fn

typedef bool(* pf_draw_callback_fn) (const pf_quad_t *quad, void *user)

Callback invoked for each glyph quad during text drawing.

Parameters

quad	The screen-space quad with atlas UVs and page index
user	Opaque pointer supplied by the caller

Returns

false to stop iteration, true to continue

pf_upload_callback_fn

typedef bool(* pf_upload_callback_fn) (size_t page, const unsigned char *pixels, int width, int height, void *user)

Callback invoked for each dirty atlas page during pf_upload_atlas.

Parameters

page	Page index
pixels	Single-channel bitmap (width * height bytes)
width	Bitmap width in pixels
height	Bitmap height in pixels
user	Opaque pointer supplied by the caller

Returns

false to stop iteration, true to continue. The dirty flag is cleared automatically after a successful (true) return.

Function Documentation

pf_create_atlas()

pf_atlas_t * pf_create_atlas	(	int	page_width,
		int	max_page_height
	)

Allocates and initializes a font atlas.

Each atlas is composed of one or more bitmap pages that store rasterized glyphs and their associated metadata. Pages start empty and grow vertically (doubling in height) as glyphs are added, up to max_page_height. Once a page is full, a new page is appended automatically.

Parameters

page_width	Width of each atlas page in pixels.
max_page_height	Maximum height each page may grow to in pixels.

Returns

A new atlas, or NULL on allocation failure.

pf_destroy_atlas()

void pf_destroy_atlas

(

pf_atlas_t *

atlas

)

Destroys a font atlas and frees all associated pages and glyphs.

Parameters

atlas

Atlas to destroy. May be NULL (no-op).

pf_create_face()

pf_face_t * pf_create_face	(	pf_atlas_t *	atlas,
		const unsigned char *	ttf_data,
		size_t	ttf_data_size,
		float	pixel_height
	)

Create a font face at a given pixel height.

Initialises an stb_truetype font from raw TrueType data and binds it to atlas for glyph caching. The face takes ownership of ttf_data: it is released with PICO_FONT_FREE by pf_destroy_face (or immediately if creation fails), so it must have been allocated compatibly with PICO_FONT_FREE and must not be freed by the caller.

Parameters

atlas	Atlas that will store rasterized glyphs.
ttf_data	Pointer to the raw TrueType font file contents.
pixel_height	Desired font height in pixels.

Returns

A new face, or NULL on failure.

pf_destroy_face()

void pf_destroy_face

(

pf_face_t *

face

)

Destroys a font face and frees the TTF data it owns.

Does not destroy the atlas it was bound to.

Parameters

face	Face to destroy. May be NULL (no-op).

pf_get_glyph()

const pf_glyph_t * pf_get_glyph	(	pf_face_t *	face,
		uint32_t	codepoint
	)

Get (or rasterize) a single glyph.

If the glyph is already cached, returns it immediately. Otherwise it is rasterized into the atlas and cached for future lookups.

Parameters

face	Face to use for rasterization.
codepoint	Unicode codepoint.

Returns

Pointer into the atlas glyph array, or NULL on failure.

pf_draw_text()

void pf_draw_text	(	pf_face_t *	face,
		const char *	text,
		float *	x,
		float *	y,
		pf_draw_callback_fn	cb,
		void *	user
	)

Lay out and emit quads for a UTF-8 string.

For each visible glyph the callback receives a screen-space quad with atlas UVs and a page index. Kerning is applied automatically between adjacent codepoints. The caller is responsible for line breaking; use pf_get_metrics() to obtain the line height for advancing y between lines.

Parameters

face	Face to use.
text	Null-terminated UTF-8 string.
x	In/out cursor X position. Updated after the last glyph.
y	In/out cursor Y position. Updated after the last glyph.
cb	Callback invoked for each visible glyph quad. May be NULL.
user	Opaque pointer forwarded to cb.

pf_upload_atlas()

void pf_upload_atlas	(	pf_atlas_t *	atlas,
		pf_upload_callback_fn	cb,
		void *	user
	)

Iterate over dirty pages and invoke the callback for each one.

A page becomes dirty whenever a new glyph is rasterized into it. The dirty flag is cleared for each page whose callback returns non-zero, so calling this after drawing ensures the GPU copy stays in sync.

Parameters

atlas	The atlas to upload.
cb	Callback invoked once per dirty page.
user	Opaque pointer forwarded to cb.

pf_measure_text()

void pf_measure_text	(	pf_face_t *	face,
		const char *	text,
		float *	out_width,
		float *	out_height
	)

Measure a UTF-8 string without drawing.

Performs the same layout as pf_draw_text but does not emit quads.

Parameters

face	Face to use.
text	Null-terminated UTF-8 string.
out_width	Receives the bounding-box width. May be NULL.
out_height	Receives the bounding-box height. May be NULL.

pf_get_metrics()

void pf_get_metrics	(	const pf_face_t *	face,
		pf_metrics_t *	metrics
	)

Retrieve vertical font metrics for a face.

Parameters

face	Face to query.
metrics	Receives the metrics. Must not be NULL.

pf_get_kerning()

float pf_get_kerning	(	const pf_face_t *	face,
		uint32_t	cp1,
		uint32_t	cp2
	)

Get the horizontal kerning adjustment between two codepoints.

Parameters

face	Face to query.
cp1	Left codepoint.
cp2	Right codepoint.

Returns

Kerning offset in pixels (typically negative for tighter pairs).