15.4. TrueType font loading and rasterization (stb_truetype)

Low-level TrueType font bindings for stb_truetype. Provides font loading, glyph packing into atlases, font metrics, codepoint metrics, and bitmap rasterization. Use stbimage_ttf for a high-level API.

15.4.1. Constants

STBTT_vmove = 1

Vertex type constant for a move-to command (start of a new contour).

STBTT_vline = 2

Vertex type constant for a line-to command (straight line segment).

STBTT_vcurve = 3

Vertex type constant for a quadratic Bezier curve segment.

STBTT_vcubic = 4

Vertex type constant for a cubic Bezier curve segment.

15.4.2. Handled structures

stbtt_packedchar

Packed character data produced by PackFontRange. Contains atlas coordinates, screen offsets, and advance width.

Fields:

  • x0 : uint16 - Atlas left edge (in pixels).

  • y0 : uint16 - Atlas top edge (in pixels).

  • x1 : uint16 - Atlas right edge (in pixels).

  • y1 : uint16 - Atlas bottom edge (in pixels).

  • xoff : float - Screen-space left offset from cursor.

  • yoff : float - Screen-space top offset from baseline.

  • xadvance : float - Horizontal advance to next character.

  • xoff2 : float - Screen-space right offset from cursor.

  • yoff2 : float - Screen-space bottom offset from baseline.

stbtt_aligned_quad

Screen-space quad with texture coordinates, produced by GetPackedQuad.

Fields:

  • x0 : float - Texture coordinate top (V).

  • y0 : float - Screen-space right edge.

  • s0 : float - Screen-space left edge.

  • t0 : float - Texture coordinate bottom (V).

  • x1 : float - Texture coordinate left (U).

  • y1 : float - Screen-space top edge.

  • s1 : float - Screen-space bottom edge.

  • t1 : float - Texture coordinate right (U).

stbtt_vertex_das

A glyph outline vertex with endpoint coordinates, control points, and a vertex type.

Fields:

  • x : int16 - Endpoint x coordinate.

  • y : int16 - Endpoint y coordinate.

  • cx : int16 - Quadratic Bezier control point x coordinate.

  • cy : int16 - Quadratic Bezier control point y coordinate.

  • cx1 : int16 - Cubic Bezier control point x coordinate.

  • cy1 : int16 - Cubic Bezier control point y coordinate.

  • vtype : uint8 - Vertex type: STBTT_vmove (1), STBTT_vline (2), STBTT_vcurve (3), or STBTT_vcubic (4).

stbtt_fontinfo

Font info structure initialized by InitFont. Required by all metric and rasterization functions.

Fields:

  • numGlyphs : int - Number of glyphs in the font.

stbtt_pack_context

Opaque packing context used by PackBegin, PackFontRange, and PackEnd.

15.4.3. Font loading

stbtt_GetFontOffsetForIndex(data: uint8 const?; index: int): int

Return the byte offset of the Nth font in a collection. For non-collection files, index 0 returns 0.

Arguments:

  • data : uint8? implicit

  • index : int

stbtt_GetNumberOfFonts(data: uint8 const?): int

Return the number of fonts in a TrueType collection (.ttc) file. Returns 1 for ordinary .ttf files.

Arguments:

  • data : uint8? implicit

stbtt_InitFont(info: stbtt_fontinfo?; data: uint8 const?; offset: int): int

Initialize a font info structure from raw font data at the given byte offset. Returns non-zero on success.

Arguments:

15.4.4. Font packing

stbtt_GetPackedQuad(chardata: stbtt_packedchar const?; pw: int; ph: int; char_index: int; xpos: float?; ypos: float?; q: stbtt_aligned_quad?; align_to_integer: int)

Get the screen-space quad and texture coordinates for a packed character. Advances the cursor position for the next character.

Arguments:

  • chardata : stbtt_packedchar? implicit

  • pw : int

  • ph : int

  • char_index : int

  • xpos : float? implicit

  • ypos : float? implicit

  • q : stbtt_aligned_quad? implicit

  • align_to_integer : int

stbtt_PackBegin(spc: stbtt_pack_context?; pixels: uint8?; width: int; height: int; stride_in_bytes: int; padding: int; alloc_context: void?): int

Initialize a packing context for packing font glyphs into an atlas bitmap. The bitmap must be pre-allocated.

Arguments:

  • spc : stbtt_pack_context? implicit

  • pixels : uint8? implicit

  • width : int

  • height : int

  • stride_in_bytes : int

  • padding : int

  • alloc_context : void? implicit

stbtt_PackEnd(spc: stbtt_pack_context?)

Clean up a packing context after all fonts have been packed.

Arguments:
stbtt_PackFontRange(spc: stbtt_pack_context?; fontdata: uint8 const?; font_index: int; font_size: float; first_unicode_char_in_range: int; num_chars_in_range: int; chardata_for_range: stbtt_packedchar?): int

Pack a range of characters from a font into the atlas at the specified pixel height. Stores packed character data for later quad generation.

Arguments:

  • spc : stbtt_pack_context? implicit

  • fontdata : uint8? implicit

  • font_index : int

  • font_size : float

  • first_unicode_char_in_range : int

  • num_chars_in_range : int

  • chardata_for_range : stbtt_packedchar? implicit

stbtt_PackSetOversampling(spc: stbtt_pack_context?; h_oversample: uint; v_oversample: uint)

Set horizontal and vertical oversampling for subsequent PackFontRange calls. Higher oversampling improves quality with GPU bilinear filtering but increases atlas size.

Arguments:
stbtt_PackSetSkipMissingCodepoints(spc: stbtt_pack_context?; skip: int)

Control whether missing codepoints produce warning rectangles (default) or are silently skipped during packing.

Arguments:

15.4.5. Font metrics

stbtt_GetFontBoundingBox(info: stbtt_fontinfo const?; x0: int?; y0: int?; x1: int?; y1: int?)

Get the bounding box of all glyphs in the font in unscaled coordinates.

Arguments:

  • info : stbtt_fontinfo? implicit

  • x0 : int? implicit

  • y0 : int? implicit

  • x1 : int? implicit

  • y1 : int? implicit

stbtt_GetFontVMetrics(info: stbtt_fontinfo const?; ascent: int?; descent: int?; lineGap: int?)

Get vertical metrics for the font: ascent, descent, and line gap in unscaled coordinates. Multiply by the scale factor for pixel values.

Arguments:

  • info : stbtt_fontinfo? implicit

  • ascent : int? implicit

  • descent : int? implicit

  • lineGap : int? implicit

stbtt_ScaleForMappingEmToPixels(info: stbtt_fontinfo const?; pixels: float): float

Compute the scale factor to map font design units (em) to the given pixel size.

Arguments:
stbtt_ScaleForPixelHeight(info: stbtt_fontinfo const?; pixels: float): float

Compute the scale factor to produce a font whose ascent-to-descent distance equals the given pixel height.

Arguments:

15.4.6. Codepoint metrics

stbtt_FindGlyphIndex(info: stbtt_fontinfo const?; unicode_codepoint: int): int

Return the glyph index for a Unicode codepoint. Returns 0 if the codepoint is not defined in the font.

Arguments:
stbtt_GetCodepointBox(info: stbtt_fontinfo const?; codepoint: int; x0: int?; y0: int?; x1: int?; y1: int?): int

Get the bounding box of a codepoint’s glyph in unscaled coordinates. Returns non-zero if the glyph exists.

Arguments:

  • info : stbtt_fontinfo? implicit

  • codepoint : int

  • x0 : int? implicit

  • y0 : int? implicit

  • x1 : int? implicit

  • y1 : int? implicit

stbtt_GetCodepointHMetrics(info: stbtt_fontinfo const?; codepoint: int; advanceWidth: int?; leftSideBearing: int?)

Get horizontal metrics for a codepoint: advance width and left side bearing in unscaled coordinates.

Arguments:

  • info : stbtt_fontinfo? implicit

  • codepoint : int

  • advanceWidth : int? implicit

  • leftSideBearing : int? implicit

stbtt_GetCodepointKernAdvance(info: stbtt_fontinfo const?; ch1: int; ch2: int): int

Get the kerning adjustment between two codepoints in unscaled coordinates.

Arguments:

15.4.7. Codepoint bitmaps

stbtt_FreeBitmap(bitmap: uint8?; userdata: void?)

Free a bitmap allocated by GetCodepointBitmap or GetCodepointBitmapSubpixel.

Arguments:

  • bitmap : uint8? implicit

  • userdata : void? implicit

stbtt_GetCodepointBitmap(info: stbtt_fontinfo const?; scale_x: float; scale_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?): uint8?

Render a codepoint glyph into a newly allocated 1-channel bitmap at the given scale. Returns the bitmap pointer, width, height, and offsets.

Arguments:

  • info : stbtt_fontinfo? implicit

  • scale_x : float

  • scale_y : float

  • codepoint : int

  • width : int? implicit

  • height : int? implicit

  • xoff : int? implicit

  • yoff : int? implicit

stbtt_GetCodepointBitmapBox(font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?)

Get the bounding box of the bitmap that would be generated for a codepoint at the given scale.

Arguments:

  • font : stbtt_fontinfo? implicit

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • ix0 : int? implicit

  • iy0 : int? implicit

  • ix1 : int? implicit

  • iy1 : int? implicit

stbtt_GetCodepointBitmapBoxSubpixel(font: stbtt_fontinfo const?; codepoint: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; ix0: int?; iy0: int?; ix1: int?; iy1: int?)

Get the bounding box of the bitmap for a codepoint at the given scale with sub-pixel offsets.

Arguments:

  • font : stbtt_fontinfo? implicit

  • codepoint : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

  • ix0 : int? implicit

  • iy0 : int? implicit

  • ix1 : int? implicit

  • iy1 : int? implicit

stbtt_GetCodepointBitmapSubpixel(info: stbtt_fontinfo const?; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int; width: int?; height: int?; xoff: int?; yoff: int?): uint8?

Render a codepoint glyph bitmap with sub-pixel positioning at the given scale and fractional offsets.

Arguments:

  • info : stbtt_fontinfo? implicit

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

  • codepoint : int

  • width : int? implicit

  • height : int? implicit

  • xoff : int? implicit

  • yoff : int? implicit

stbtt_MakeCodepointBitmap(info: stbtt_fontinfo const?; output: uint8?; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; codepoint: int)

Render a codepoint glyph into a pre-allocated buffer with the given dimensions and stride.

Arguments:

  • info : stbtt_fontinfo? implicit

  • output : uint8? implicit

  • out_w : int

  • out_h : int

  • out_stride : int

  • scale_x : float

  • scale_y : float

  • codepoint : int

stbtt_MakeCodepointBitmapSubpixel(info: stbtt_fontinfo const?; output: uint8?; out_w: int; out_h: int; out_stride: int; scale_x: float; scale_y: float; shift_x: float; shift_y: float; codepoint: int)

Render a codepoint glyph into a pre-allocated buffer with sub-pixel positioning.

Arguments:

  • info : stbtt_fontinfo? implicit

  • output : uint8? implicit

  • out_w : int

  • out_h : int

  • out_stride : int

  • scale_x : float

  • scale_y : float

  • shift_x : float

  • shift_y : float

  • codepoint : int

15.4.8. Glyph shape

stbtt_GetCodepointShape(info: stbtt_fontinfo const?; codepoint: int; block: block<(stbtt_vertex_das):void>)

Iterates over the vertices of a glyph outline for the given Unicode codepoint, invoking the block for each vertex. Each vertex describes a move, line, quadratic curve, or cubic curve segment.

Arguments:
stbtt_GetCodepointShape_count(info: stbtt_fontinfo const?; codepoint: int): int

Returns the number of vertices in the glyph outline for the given Unicode codepoint.

Arguments: