What is SDL2_ttf?

SDL2_ttf renders TrueType and OpenType fonts to SDL2 surfaces using the FreeType engine. It is the standard way to display text in SDL2 games and interactive applications. Fonts are loaded from .ttf or .otf files (or from memory), scaled to any point size, and rendered with configurable quality modes. The resulting surfaces can be used directly with SDL2 or uploaded to the GPU as textures for efficient rendering.

Full UTF-8 is supported — including Arabic, CJK, Devanagari, and emoji. For complex shaping (ligatures, bidirectional text), combine with HarfBuzz.

Render Quality Modes

Mode	Description	Best For
Solid	Fastest. Single foreground color, no antialiasing. Palette surface.	HUDs, game scores, real-time counters
Shaded	Antialiased with opaque background box. Cleaner than Solid.	Subtitles, console text, fixed backgrounds
Blended	Best quality. Full alpha-blended antialiasing. ARGB surface.	UI labels, menus, general text
LCD	Sub-pixel rendering for crisp text on LCD screens.	Desktop apps, readability on LCD

Types

All handle types are opaque Integer values backed by the native C library.

Type	Description
TTTFFont	Font handle returned by OpenFont. Must be closed with CloseFont.
TSDLSurface	SDL_Surface handle. Pixel data in CPU memory.
TSDLTexture	SDL_Texture handle. Pixel data on GPU memory.
TSDLRenderer	SDL_Renderer handle. Required for RenderTextTexture.
TSDLColor	Packed RGBA color value. Created with MakeColor(R,G,B,A).

TTTFHinting

Value	Description
thNormal = 0	Default FreeType hinting. Good balance.
thLight = 1	Lighter hinting, softer appearance.
thMono = 2	Monochrome hinting for crisp 1-bit rendering.
thNone = 3	No hinting. Pure glyph outlines.
thLightSub = 4	Light hinting with sub-pixel positioning.

TTTFStyle — combinable flags

Value	Hex	Description
tsNormal	$00	No style applied.
tsBold	$01	Bold weight (synthesized if font has no bold face).
tsItalic	$02	Italic slant (synthesized if font has no italic face).
tsUnderline	$04	Underline decoration.
tsStrikethrough	$08	Strikethrough decoration.

TTTFGlyphMetrics record

Field	Description
MinX	Left bearing — distance from pen to leftmost pixel.
MaxX	Rightmost pixel position.
MinY	Bottom bearing — distance from baseline to bottommost pixel.
MaxY	Topmost pixel position.
Advance	Horizontal advance — how far the pen moves after this glyph.

API Reference

Init

Function	Description
Init: Boolean	Initialize SDL2_ttf. Must be called before any other TTF function. Returns True on success.
Quit	Shutdown SDL2_ttf and free all internal resources.
Version: string	Returns the linked SDL2_ttf version string.

Open / Close Font

Function	Description
OpenFont(Path, PointSize): TTTFFont	Open a TrueType font at a given point size (72 DPI). Returns a font handle.
OpenFontIndex(Path, PointSize, FaceIndex): TTTFFont	Open a specific face inside a .ttc font collection.
OpenFontFromMemory(Data, PointSize): TTTFFont	Load a font from an in-memory byte string. Useful for embedded assets.
CloseFont(Font)	Close the font and release all memory associated with it.

Font Properties

Function	Description
SetStyle(Font, Style)	Set style flags. Combine with or: tsBold or tsItalic.
GetStyle(Font): Integer	Return current style bitmask.
SetHinting(Font, Hinting)	Set FreeType hinting mode (TTTFHinting enum).
SetOutline(Font, Outline)	Set outline stroke width in pixels. 0 = no outline.
SetKerning(Font, Enable)	Enable or disable kerning. Kerning is on by default.
GetHeight(Font): Integer	Maximum glyph height in pixels.
GetAscent(Font): Integer	Positive pixels above the baseline.
GetDescent(Font): Integer	Negative pixels below the baseline.
GetLineSkip(Font): Integer	Recommended line spacing in pixels.
GetFamilyName(Font): string	Font family name (e.g. 'DejaVu Sans').
GetStyleName(Font): string	Face style name (e.g. 'Bold Italic').

Text Measurement

Function	Description
SizeText(Font, Text, out W, H)	Measure pixel dimensions of a string without rendering it.
MeasureText(Font, Text, MaxWidth, out FitChars, ActualWidth)	Find how many characters fit within MaxWidth pixels and the actual rendered width.
GlyphMetrics(Font, Codepoint): TTTFGlyphMetrics	Return per-glyph bearing and advance for a Unicode codepoint.
GlyphProvided(Font, Codepoint): Boolean	Check if the font contains a glyph for the given codepoint.

Render Text → Surface

Function	Description
RenderSolid(Font, Text, FgColor): TSDLSurface	Solid render: fast, no antialiasing. Best for HUDs and scores.
RenderShaded(Font, Text, FgColor, BgColor): TSDLSurface	Antialiased with opaque background box. Good for subtitles.
RenderBlended(Font, Text, FgColor): TSDLSurface	Best quality: full alpha-blended antialiasing.
RenderBlendedWrapped(Font, Text, FgColor, WrapWidth): TSDLSurface	Blended render with automatic line wrapping at WrapWidth pixels.
RenderLCD(Font, Text, FgColor, BgColor): TSDLSurface	Sub-pixel LCD rendering for crisp text on screens.

Render Text → Texture

Function	Description
RenderTextTexture(Renderer, Font, Text, FgColor): TSDLTexture	Render blended text directly to a GPU SDL_Texture. Skips the surface step for convenience.

Color & Error

Function	Description
MakeColor(R, G, B, A): TSDLColor	Pack RGBA components (0–255) into a single TSDLColor value.
GetError: string	Return the last SDL2_ttf error message string.

Code Example

uses sdl2_ttf;

var
  Font   : TTTFFont;
  Surface: TSDLSurface;
  Tex    : TSDLTexture;
  W, H   : Integer;
  White  : TSDLColor;

begin
  Init;
  Font := OpenFont('assets/DejaVuSans.ttf', 24);
  SetStyle(Font, tsBold);
  White := MakeColor(255, 255, 255, 255);

  { Measure before rendering }
  SizeText(Font, 'Score: 1234', W, H);
  WriteLn('Text size: ', W, 'x', H, ' px');

  { Best quality render }
  Surface := RenderBlended(Font, 'Hello World!', White);

  { Convert to GPU texture }
  Tex := RenderTextTexture(Renderer, Font, 'FPS: 60', White);

  { Wrapped text }
  Surface := RenderBlendedWrapped(Font, LongParagraph, White, 400);

  CloseFont(Font);
  Quit;
end.