12 TrueType Fonts

9.0.0.11

Racket

12 TrueType Fonts🔗ℹ

This section covers TrueType font loading and text rendering using SDL_ttf.

12.1 Font Management🔗ℹ

procedure
(open-font path size [#:custodian cust]) → font?
  path : (or/c string? path?)
  size : real?
  cust : custodian? = (current-custodian)

Opens a TrueType font from a file.

size is the point size of the font.

(define font (open-font "/path/to/font.ttf" 24))

procedure
(open-font-io source
size
[ #:close? close?
#:custodian cust]) → font?
  source : (or/c bytes? input-port? cpointer?)
  size : real?
  close? : boolean? = #t
  cust : custodian? = (current-custodian)

Opens a font from bytes, an input port, or an IOStream.

When close? is #t, SDL takes ownership of the stream.

procedure
(font? v) → boolean?
v : any/c

Returns #t if v is a font.

procedure
(font-ptr f) → cpointer?
f : font?

Returns the underlying SDL_ttf font pointer.

procedure
(close-font! f) → void?
f : font?

Closes a font and frees its resources.

Note: Fonts are automatically closed when their custodian shuts down.

procedure
(copy-font f [#:custodian cust]) → font?
f : font?
cust : custodian? = (current-custodian)

Creates a copy of a font with independent properties.

12.2 Font Properties🔗ℹ

12.2.1 Metrics🔗ℹ

procedure
(font-size f) → real?
f : font?

Returns the point size of the font.

procedure
(font-height f) → exact-integer?
f : font?

Returns the maximum height of the font in pixels.

This is the recommended line spacing for text.

procedure
(font-ascent f) → exact-integer?
f : font?

Returns the ascent (height above baseline) in pixels.

procedure
(font-descent f) → exact-integer?
f : font?

Returns the descent (depth below baseline) in pixels.

Note: This is typically a negative value.

procedure
(font-line-skip f) → exact-integer?
f : font?

Returns the recommended line skip (spacing between lines) in pixels.

12.2.2 Style🔗ℹ

procedure
(font-style f) → (listof symbol?)
f : font?

Returns the current font style as a list of symbols.

Possible values: 'normal, 'bold, 'italic, 'underline, 'strikethrough.

procedure
(set-font-style! f style ...) → void?
f : font?
style : symbol?

Sets the font style.

(set-font-style! font 'bold)
(set-font-style! font 'bold 'italic)
(set-font-style! font 'normal) ; Reset to normal

procedure
(font-outline f) → exact-integer?
f : font?

Returns the current outline thickness in pixels.

procedure
(set-font-outline! f pixels) → void?
f : font?
pixels : exact-integer?

Sets the outline thickness. Use 0 for no outline.

procedure
(font-hinting f) → symbol?
f : font?

Returns the current hinting mode.

Values: 'normal, 'light, 'mono, 'none, 'light-subpixel.

procedure
(set-font-hinting! f mode) → void?
f : font?
mode : symbol?

Sets the hinting mode for the font.

12.2.3 Other Properties🔗ℹ

procedure
(font-weight f) → exact-integer?
f : font?

Returns the font weight (e.g., 400 for normal, 700 for bold).

procedure
(font-family-name f) → (or/c string? #f)
f : font?

Returns the font family name.

procedure
(font-style-name f) → (or/c string? #f)
f : font?

Returns the font style name (e.g., "Regular", "Bold").

procedure
(font-fixed-width? f) → boolean?
f : font?

Returns #t if the font is monospaced.

procedure
(font-scalable? f) → boolean?
f : font?

Returns #t if the font is scalable (TrueType/OpenType).

procedure
(font-kerning? f) → boolean?
f : font?

Returns #t if kerning is enabled.

procedure
(set-font-kerning! f enabled?) → void?
f : font?
enabled? : boolean?

Enables or disables kerning.

procedure
(set-font-size! f
size
[ #:hdpi hdpi
#:vdpi vdpi]) → void?
  f : font?
  size : real?
  hdpi : (or/c exact-nonnegative-integer? #f) = #f
  vdpi : (or/c exact-nonnegative-integer? #f) = #f

Changes the font size.

Optional DPI parameters allow for high-DPI rendering.

12.3 Text Measurement🔗ℹ

procedure
(text-size f text) →
exact-integer? exact-integer?
f : font?
text : string?

Returns the width and height needed to render the text.

(define-values (w h) (text-size font "Hello, World!"))

procedure
(text-size-wrapped f text wrap-width)
→
exact-integer? exact-integer?
  f : font?
  text : string?
  wrap-width : exact-nonnegative-integer?

Returns the size needed for word-wrapped text.

procedure
(measure-text f text max-width)
→
exact-integer? exact-nonnegative-integer?
  f : font?
  text : string?
  max-width : exact-nonnegative-integer?

Measures how much text fits within a maximum width.

Returns the actual width used and the number of characters that fit.

12.4 Text Rendering🔗ℹ

procedure
(draw-text! renderer
font
text
x
y
color
[ #:mode mode
#:custodian cust]) → void?
  renderer : renderer?
  font : font?
  text : string?
  x : real?
  y : real?
   color :
(or/c (list/c byte? byte? byte?)
      (list/c byte? byte? byte? byte?))
  mode : (or/c 'solid 'blended) = 'blended
  cust : custodian? = (current-custodian)

Renders text directly to the screen at the specified position.

This is a convenience function that renders text to a temporary texture and draws it immediately.

mode controls rendering quality:

'solid — Fast but rough edges
'blended — High quality with anti-aliasing (default)

(draw-text! ren font "Hello, World!" 100 100 '(255 255 255))
(draw-text! ren font "Score: 42" 10 10 '(255 255 0))

procedure
(render-text font
text
color
#:renderer renderer
[ #:mode mode
#:custodian cust]) → (or/c texture? #f)
  font : font?
  text : string?
   color :
(or/c (list/c byte? byte? byte?)
      (list/c byte? byte? byte? byte?))
  renderer : renderer?
  mode : (or/c 'solid 'blended) = 'blended
  cust : custodian? = (current-custodian)

Renders text to a texture.

Returns #f for empty text or if the text is too large for a texture.

This is useful when you want to render the same text multiple times without re-rasterizing it each frame.

(define score-label (render-text font "Score:" '(255 255 255)
#:renderer ren))
;; Use the texture multiple times
(render-texture! ren score-label 10 10)

12.5 Text Direction and Alignment🔗ℹ

For languages with different text directions (RTL, vertical), these functions configure text layout.

procedure
(font-direction f) → symbol?
f : font?

Returns the text direction.

Values: 'ltr (left-to-right), 'rtl (right-to-left), 'ttb (top-to-bottom), 'btt (bottom-to-top).

procedure
(set-font-direction! f direction) → void?
f : font?
direction : symbol?

Sets the text direction.

Note: Requires HarfBuzz support. May fail on some builds.

procedure
(font-wrap-alignment f) → symbol?
f : font?

Returns the text alignment for wrapped text.

Values: 'left, 'center, 'right.

procedure
(set-font-wrap-alignment! f alignment) → void?
f : font?
alignment : symbol?

Sets the alignment for wrapped text.

12.6 Fallback Fonts🔗ℹ

Fallback fonts provide glyphs for characters not present in the primary font.

procedure
(add-fallback-font! f fallback) → void?
f : font?
fallback : font?

Adds a fallback font.

When the primary font doesn’t have a glyph, SDL_ttf will try the fallback.

procedure
(remove-fallback-font! f fallback) → void?
f : font?
fallback : font?

Removes a fallback font.

procedure
(clear-fallback-fonts! f) → void?
f : font?

Removes all fallback fonts.

12.7 Glyph Operations🔗ℹ

procedure
(font-has-glyph? f ch) → boolean?
f : font?
ch : (or/c char? exact-nonnegative-integer?)

Returns #t if the font has a glyph for the character.

procedure
(glyph-metrics f ch) →
exact-integer?
exact-integer?
exact-integer?
exact-integer?
exact-integer?
f : font?
ch : (or/c char? exact-nonnegative-integer?)

Returns detailed metrics for a glyph.

Returns: (values min-x max-x min-y max-y advance).

procedure
(glyph-kerning f prev-ch ch) → exact-integer?
  f : font?
  prev-ch : (or/c char? exact-nonnegative-integer?)
  ch : (or/c char? exact-nonnegative-integer?)

Returns the kerning adjustment between two characters.

12.8 Advanced: Text Objects🔗ℹ

For complex text layouts and efficient updates, SDL_ttf provides text objects that can be modified and re-rendered efficiently.

procedure
(make-text font
text
[ #:engine engine
#:custodian cust]) → text?
  font : font?
  text : string?
   engine :
(or/c renderer-text-engine? surface-text-engine?
      gpu-text-engine? #f)
= #f
  cust : custodian? = (current-custodian)

Creates a text object for advanced text rendering.

procedure
(text? v) → boolean?
v : any/c

Returns #t if v is a text object.

procedure
(text-set-string! t text) → void?
t : text?
text : string?

Replaces the text content.

procedure
(text-append-string! t text) → void?
t : text?
text : string?

Appends to the text content.

procedure
(text-insert-string! t offset text) → void?
  t : text?
  offset : exact-nonnegative-integer?
  text : string?

Inserts text at the specified byte offset.

procedure
(text-delete-string! t offset length) → void?
  t : text?
  offset : exact-nonnegative-integer?
  length : exact-nonnegative-integer?

Deletes text starting at the specified byte offset.

procedure
(text-object-size t) →
exact-integer? exact-integer?
t : text?

Returns the size of the rendered text.

procedure
(draw-renderer-text! t x y) → void?
  t : text?
  x : real?
  y : real?

Draws a text object using a renderer text engine.

12.9 Text Engines🔗ℹ

Text engines manage glyph caching and rendering. They’re needed for advanced text object rendering.

procedure
(make-renderer-text-engine renderer
[ #:custodian cust])
→ renderer-text-engine?
renderer : renderer?
cust : custodian? = (current-custodian)

Creates a text engine for renderer-based text drawing.

procedure
(renderer-text-engine? v) → boolean?
v : any/c

Returns #t if v is a renderer text engine.

procedure
(make-surface-text-engine [#:custodian cust])
→ surface-text-engine?
cust : custodian? = (current-custodian)

Creates a text engine for surface-based text drawing.

procedure
(surface-text-engine? v) → boolean?
v : any/c

Returns #t if v is a surface text engine.

12.10 SDF Rendering🔗ℹ

Signed Distance Field rendering allows for high-quality text at any scale.

procedure
(font-sdf? f) → boolean?
f : font?

Returns #t if SDF mode is enabled.

procedure
(set-font-sdf! f enabled?) → void?
f : font?
enabled? : boolean?

Enables or disables SDF mode.

12.11 Version Information🔗ℹ

procedure
(ttf-version) →
exact-nonnegative-integer?
exact-nonnegative-integer?
exact-nonnegative-integer?

Returns the SDL_ttf version as (values major minor patch).

procedure
(freetype-version) →
exact-nonnegative-integer?
exact-nonnegative-integer?
exact-nonnegative-integer?

Returns the FreeType version as (values major minor patch).

procedure
(harfbuzz-version) →
(or/c exact-nonnegative-integer? #f)
(or/c exact-nonnegative-integer? #f)
(or/c exact-nonnegative-integer? #f)

Returns the HarfBuzz version as (values major minor patch).

Returns (values #f #f #f) if HarfBuzz is not available.

1	Overview
2	Quick Start
3	Resource Management
4	Initialization
5	Windows and Renderers
6	Timer Functions
7	Configuration Hints
8	Properties
9	Drawing
10	Textures
11	Images and Surfaces
12	True Type Fonts
13	Rectangle Collision Detection
14	Events
15	Keyboard Functions
16	Mouse Functions
17	Gamepads
18	Joysticks
19	Audio
20	Camera
21	Display Information
22	Clipboard
23	Dialogs
24	System Tray
25	Open GL
26	Vulkan
27	GPU API

12.1	Font Management
12.2	Font Properties
12.3	Text Measurement
12.4	Text Rendering
12.5	Text Direction and Alignment
12.6	Fallback Fonts
12.7	Glyph Operations
12.8	Advanced: Text Objects
12.9	Text Engines
12.10	SDF Rendering
12.11	Version Information