15.5. TrueType font API (stbimage_ttf)

High-level TrueType font loading and text rendering API. Loads fonts via stb_truetype packing API, stores atlas as Image, and provides software text rendering with alpha blending. Built on stbimage_boost and stbtruetype.

15.5.1. Structures

Font

Font loaded from a TTF file. Supports both atlas-based rendering (via load_ttf) and lightweight metrics/shape queries (via load_font).

Fields:

  • fontinfo : stbtt_fontinfo - Initialized font info (for metrics queries).

  • chardata : array< stbtt_packedchar> - Packed character data for the loaded range.

  • bitmap : Image - Font atlas as 1-channel uint8 Image.

  • font_data : array<uint8> - Raw TTF file data (must outlive fontinfo).

  • pixel_height : float - Font size in pixels (0 if loaded without atlas).

  • char_range : int2 - (first_char, num_chars) of the packed range.

  • tex : uint64 - Opaque texture handle (0 by default, set by graphics layer).

15.5.2. Low-level initialization

stbtt_init(info: stbtt_fontinfo; data: array<uint8>; font_index: int = 0): bool

Initialize a stbtt_fontinfo from font data. Returns true on success.

Arguments:
stbtt_num_fonts(data: array<uint8>): int

Returns the number of fonts in a TrueType collection (.ttc), or 1 for a single .ttf.

Arguments:

  • data : array<uint8>

15.5.3. Low-level scale

stbtt_scale_for_em(info: stbtt_fontinfo; pixels: float): float

Compute scale factor for mapping em to pixels.

Arguments:
stbtt_scale_for_pixel_height(info: stbtt_fontinfo; pixel_height: float): float

Compute scale factor for a given pixel height.

Arguments:

15.5.4. Low-level metrics

stbtt_codepoint_box(info: stbtt_fontinfo; codepoint: int): int4

Returns glyph bounding box int4(x0, y0, x1, y1) in font units. Returns int4(0) if the codepoint has no outline.

Arguments:
stbtt_codepoint_hmetrics(info: stbtt_fontinfo; codepoint: int): tuple<advance_width:int;left_side_bearing:int>

Returns horizontal metrics in font units for a codepoint.

Arguments:
stbtt_codepoint_kern(info: stbtt_fontinfo; ch1: int; ch2: int): int

Returns kerning advance between two codepoints in font units.

Arguments:
stbtt_find_glyph(info: stbtt_fontinfo; codepoint: int): int

Returns glyph index for a codepoint. Returns 0 if not found.

Arguments:
stbtt_font_bbox(info: stbtt_fontinfo): int4

Returns font bounding box int4(x0, y0, x1, y1) in font units.

Arguments:
stbtt_font_vmetrics(info: stbtt_fontinfo): tuple<ascent:int;descent:int;line_gap:int>

Returns vertical metrics in font units: ascent, descent, line gap.

Arguments:

15.5.5. Low-level glyph shape

stbtt_codepoint_shape(info: stbtt_fontinfo; codepoint: int; blk: block<(v:stbtt_vertex_das):void>)

Iterate glyph shape vertices for a codepoint via callback.

Arguments:
stbtt_codepoint_shape_count(info: stbtt_fontinfo; codepoint: int): int

Returns the number of shape vertices for a codepoint.

Arguments:

15.5.6. Low-level bitmap rendering

stbtt_codepoint_bitmap(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float): tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap at the given scale. Returns a 1-channel Image and pixel offset. The returned Image owns the pixel data (copied from stb allocation).

Arguments:

  • info : stbtt_fontinfo

  • codepoint : int

  • scale_x : float

  • scale_y : float

stbtt_codepoint_bitmap_box(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float): int4

Returns pixel-space bounding box int4(ix0, iy0, ix1, iy1) for a codepoint bitmap at the given scale.

Arguments:

  • info : stbtt_fontinfo

  • codepoint : int

  • scale_x : float

  • scale_y : float

stbtt_codepoint_bitmap_box_subpixel(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float): int4

Returns pixel-space bounding box with subpixel shift.

Arguments:

  • info : stbtt_fontinfo

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

stbtt_codepoint_bitmap_subpixel(info: stbtt_fontinfo; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float): tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap with subpixel shift. Returns a 1-channel Image and pixel offset.

Arguments:

  • info : stbtt_fontinfo

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

stbtt_make_codepoint_bitmap(info: stbtt_fontinfo; buf: array<uint8>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int)

Renders a codepoint glyph into a caller-provided buffer. buf must be at least out_h * out_stride bytes.

Arguments:

  • info : stbtt_fontinfo

  • buf : array<uint8>

  • out_w : int

  • out_h : int

  • out_stride : int

  • scale_x : float

  • scale_y : float

  • codepoint : int

stbtt_make_codepoint_bitmap_subpixel(info: stbtt_fontinfo; buf: array<uint8>; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int)

Renders a codepoint glyph with subpixel shift into a caller-provided buffer.

Arguments:

  • info : stbtt_fontinfo

  • buf : array<uint8>

  • out_w : int

  • out_h : int

  • out_stride : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

  • codepoint : int

15.5.7. Low-level packing

stbtt_pack(data: array<uint8>; pixels: array<uint8>; atlas_w: int; atlas_h: int; chardata: array<stbtt_packedchar>; font_size: float; first_char: int; num_chars: int; oversampling: int = 1; font_index: int = 0)

Pack a character range into an atlas bitmap. Wraps PackBegin + SetOversampling + PackFontRange + PackEnd.

Arguments:

  • data : array<uint8>

  • pixels : array<uint8>

  • atlas_w : int

  • atlas_h : int

  • chardata : array< stbtt_packedchar>

  • font_size : float

  • first_char : int

  • num_chars : int

  • oversampling : int

  • font_index : int

stbtt_packed_quad(chardata: array<stbtt_packedchar>; atlas_w: int; atlas_h: int; char_index: int; xpos: float&; align_to_integer: bool = false): stbtt_aligned_quad

Returns the packed quad for a character, advancing xpos. char_index is relative to the first packed character.

Arguments:

  • chardata : array< stbtt_packedchar>

  • atlas_w : int

  • atlas_h : int

  • char_index : int

  • xpos : float&

  • align_to_integer : bool

15.5.8. Font loading

is_valid(font: Font): bool

Returns true if the font has been successfully loaded.

Arguments:
load_font(fname: string): Font

Load a TrueType font from file for metrics and shape queries (no atlas).

Returns a Font with pixel_height = 0 and empty atlas fields. Use scale_for_pixel_height to compute a scale factor for a desired size.

Arguments:

  • fname : string

load_ttf(fname: string; pixel_height: float = 32f; atlas_dim: int2 = int2(512, 512); first_char: int = 32; num_chars: int = 96; oversampling: int = 1): Font

Load a TrueType font from file and pack a character range into an atlas.

Returns a Font with bitmap stored as a 1-channel Image. If loading fails, returns a Font with an invalid bitmap.

Arguments:

  • fname : string

  • pixel_height : float

  • atlas_dim : int2

  • first_char : int

  • num_chars : int

  • oversampling : int

15.5.9. Font scale

scale_for_em(font: Font; pixels: float): float

Compute scale factor for mapping em to pixels.

Arguments:

  • font : Font

  • pixels : float

scale_for_pixel_height(font: Font; pixel_height: float): float

Compute scale factor for a given pixel height.

Arguments:

  • font : Font

  • pixel_height : float

15.5.10. Font metrics

codepoint_box(font: Font; codepoint: int): int4

Returns glyph bounding box int4(x0, y0, x1, y1) in font units.

Arguments:

  • font : Font

  • codepoint : int

codepoint_hmetrics(font: Font; codepoint: int): tuple<advance_width:int;left_side_bearing:int>

Returns horizontal metrics in font units for a codepoint.

Arguments:

  • font : Font

  • codepoint : int

codepoint_kern(font: Font; ch1: int; ch2: int): int

Returns kerning advance between two codepoints in font units.

Arguments:

  • font : Font

  • ch1 : int

  • ch2 : int

find_glyph(font: Font; codepoint: int): int

Returns glyph index for a codepoint. Returns 0 if not found.

Arguments:

  • font : Font

  • codepoint : int

font_bounding_box(font: Font): int4

Returns font bounding box int4(x0, y0, x1, y1) in font units.

Arguments:

15.5.10.1. font_metrics

font_metrics(font: Font): tuple<ascent:float;descent:float;line_height:float>

Returns font metrics in pixels using the font’s pixel_height. Ascent is baseline to top, descent is baseline to bottom (negative), line_height is recommended line spacing.

Arguments:
font_metrics(font: Font; pixel_height: float): tuple<ascent:float;descent:float;line_height:float>
font_vmetrics(font: Font): tuple<ascent:int;descent:int;line_gap:int>

Returns vertical metrics in font units: ascent, descent, line gap.

Arguments:

15.5.11. Font glyph shape

codepoint_shape(font: Font; codepoint: int; blk: block<(v:stbtt_vertex_das):void>)

Iterate glyph shape vertices for a codepoint via callback.

Arguments:
codepoint_shape_count(font: Font; codepoint: int): int

Returns the number of shape vertices for a codepoint.

Arguments:

  • font : Font

  • codepoint : int

15.5.12. Font bitmap rendering

codepoint_bitmap(font: Font; codepoint: int; scale_x: float; scale_y: float): tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap at the given scale. Returns a 1-channel Image and pixel offset.

Arguments:

  • font : Font

  • codepoint : int

  • scale_x : float

  • scale_y : float

codepoint_bitmap_box(font: Font; codepoint: int; scale_x: float; scale_y: float): int4

Returns pixel-space bounding box int4(ix0, iy0, ix1, iy1) for a codepoint bitmap.

Arguments:

  • font : Font

  • codepoint : int

  • scale_x : float

  • scale_y : float

codepoint_bitmap_box_subpixel(font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float): int4

Returns pixel-space bounding box with subpixel shift.

Arguments:

  • font : Font

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

codepoint_bitmap_subpixel(font: Font; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float): tuple<image:Image;offset:int2>

Renders a codepoint glyph bitmap with subpixel shift.

Arguments:

  • font : Font

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

15.5.13. Text measurement and rendering

measure_text(font: Font; text: string; pixel_height: float): float

Measure the width of a string in pixels at the given pixel height.

Arguments:

  • font : Font

  • text : string

  • pixel_height : float

render_text(dst: Image; font: Font; text: string; x: int; y: int; r: int; g: int; b: int)

Render text onto a 4-channel RGBA image using pixel-to-pixel alpha blit.

x, y is the position of the text baseline origin. Each glyph is blitted from the 1-channel font atlas with the given (r,g,b) color. Uses packedchar fields directly for pixel-to-pixel blit. Best results with oversampling=1 (the default for software rendering). Clips to destination bounds automatically.

Arguments:

  • dst : Image

  • font : Font

  • text : string

  • x : int

  • y : int

  • r : int

  • g : int

  • b : int