You are looking at historical revision 33025 of this page. It may differ significantly from its current revision.

sdl2-ttf

The sdl2-ttf egg provides bindings to SDL_ttf version 2. SDL_ttf is a library for rendering TTF and FON fonts, compatible with Simple DirectMedia Layer version 2 (SDL2), a popular library used in games and other media-rich software.

The sdl2-ttf egg is designed to be compatible with the sdl2 egg, which provides bindings to SDL 2 itself.

Project / Source Code Repository

https://gitlab.com/chicken-sdl2/chicken-sdl2-ttf

Issue Tracker

https://gitlab.com/chicken-sdl2/chicken-sdl2-ttf/issues

Maintainer

John Croisant (john+chicken at croisant dot net)

License

BSD 2-Clause

Table of Contents:

Requirements

The sdl2-ttf egg requires the sdl2 egg, Simple DirectMedia Layer version 2.0.0 or higher, and SDL_ttf version 2.0 or higher. It will not work with older versions of SDL or SDL_ttf.

This egg requires CHICKEN Scheme 4.8 or higher. Please file an issue or contact the maintainer if you need to use this library with an earlier version of CHICKEN Scheme.

Installation

ATTENTION: The sdl2-ttf egg has not been released yet. For now, you must download it from its source code repository and follow the instructions in the README.

When installing the egg, you should set the SDL2_FLAGS environment variable to a string of compiler flags to be used when compiling the egg. If you have the sdl2-config helper program installed on your system, you can set appropriate flags and install the extension like so (notice these are back ticks, not quotes):

export SDL2_FLAGS=`sdl2-config --cflags --libs`
chicken-install sdl2-ttf

If you do not have the sdl2-config helper program installed on your computer, you may manually specify SDL-related compiler flags (notice these are double quotes, not back ticks):

export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
chicken-install sdl2-ttf

By default, the sdl2-ttf egg will be linked against SDL_ttf using the compiler flag -lSDL2_ttf. You can override this by setting the SDL2_TTF_FLAGS environment variable, if needed. You can also use that environment variable in case you have installed SDL_ttf in a different location than SDL.

The SDL2_FLAGS and SDL2_TTF_FLAGS environment variables are only needed during installation of the egg. They do not need to be set during normal use.

Usage and Examples

To avoid procedure name collisions, it is recommended that you import the sdl2-ttf module using a prefix such as "ttf:", like so:

(use (prefix sdl2-ttf ttf:))
(ttf:init!)

The chicken-sdl2-examples repository contains complete example games and programs, some of which use the sdl2-ttf egg.

Version History

The sdl2-ttf egg has not been released yet.

API

About the API

API Stability

The sdl2-ttf egg follows "semantic versioning". Until version 1.0.0 is released, the API is not guaranteed to be "stable". That means the maintainer reserves the right to change the API if needed, possibly in ways that break backwards compatibility with previous versions. Large backwards-incompatible changes are unlikely, but there may be small tweaks and fixes to the API if problems are discovered.

After version 1.0.0 is released, the API is guaranteed to remain stable (no backwards-incompatible changes) until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).

Conventions

• Procedures names, including function bindings, are Scheme style.
  • All procedure names are lower case and hyphenated, with no "TTF_" prefix.
  • Procedures that ask a "true or false" question (aka predicates) are suffixed with "?". Usually words such as "has" or "is" are removed from predicate names.
  • Procedures that cause a mutation or side effect are suffixed with "!".
  • Procedures that set the value of a field are named like TYPE-FIELD-set!, e.g. font-style-set!. For setters that have a corresponding getter, it is also possible to use (set! ...) to set the value, e.g. (set! (font-style my-font) '(bold)). Both forms are equivalent.
• Some procedures signal an exception of kind (exn sdl2) if an error occurs or the operation fails. This is instead of returning an integer error code or null pointer.
• Some procedures have two versions: one that returns a managed object, and one that returns an unmanaged object. See Struct Memory Management in the sdl2 egg docs.
• Some procedures return multiple values. For example, size-text returns two values, the width and height. You can use receive, let-values, etc. to capture all the return values.

General

[procedure] (init!)

See TTF_Init.

Signals an exception of kind (exn sdl2) if initialization fails.

[procedure] (was-init?) → boolean

See TTF_WasInit.

[procedure] (quit!)

See TTF_Quit.

[procedure] (compiled-version) → list of integers
[procedure] (current-version) → list of integers

Returns a list of three nonnegative integers, indicating a version number of SDL_ttf. For example, the list (2 0 0) indicates SDL_ttf 2.0.0.

• compiled-version returns the version of SDL_ttf that the sdl2-ttf egg was compiled with.
• current-version returns the version of SDL_ttf that the sdl2-ttf egg is currently using.

For example, the user may have compiled the sdl2-ttf egg with SDL_ttf 2.0.0, then later upgraded SDL_ttf to 2.1.0, but not yet recompiled the sdl2-ttf egg with the new version. In such a case, compiled-version would return (2 0 0), and current-version would return (2 1 0). But, features from the new version would not be available until the user recompiles the sdl2-ttf egg.

See SDL_TTF_VERSION and IMG_LinkedVersion.

Font

Font Loading

[procedure] (open-font filepath ptsize #!optional index) → ttf:font
[procedure] (open-font* filepath ptsize #!optional index) → ttf:font

Attempts to load the TTF or FON font file at the given filepath (a string). See TTF_OpenFontIndex.

ptsize is the point size (based on 72DPI) to load the font as. This basically translates to pixel height.

index allows you to choose a font face from a file containing multiple font faces. The first face is always index 0.

Returns a ttf:font with the font data. Signals an exception of kind (exn sdl2) if the font could not be loaded.

• open-font returns a managed ttf:font.
• open-font* returns an unmanaged ttf:font, which must be closed with close-font! when you are done with it.

[procedure] (open-font-rw rwops close? ptsize #!optional index) → ttf:font
[procedure] (open-font-rw* rwops close? ptsize #!optional index) → ttf:font

Attempts a TTF or FON font from an sdl2:rwops. This procedure allows you to load a font from a variety of sources, such as a blob, string, memory pointer, or file. See TTF_OpenFontIndexRW.

If close? is #t, the sdl2:rwops will be automatically closed after the font is loaded. See rw-close! in the sdl2 egg. If close? is #f (the default), the sdl2:rwops will not be closed.

ptsize is the point size (based on 72DPI) to load the font as. This basically translates to pixel height.

index allows you to choose a font face from a file containing multiple font faces. The first face is always index 0.

Returns a ttf:font with the font data. Signals an exception of kind (exn sdl2) if the font could not be loaded.

• open-font-rw returns a managed ttf:font.
• open-font-rw* returns an unmanaged ttf:font, which must be closed with close-font! when you are done with it.

ttf:font

ttf:font is a record type that wraps a pointer to a TTF_Font struct.

[procedure] (font? obj) → boolean

Returns #t if obj is a ttf:font.

[procedure] (close-font! font)
[procedure] (free-font! font)

See TTF_CloseFont.

Close and free the memory of the ttf:font's underlying struct. font's pointer will be set to null (see struct-null? in the sdl2 egg). It is safe to call this procedure with managed or unmanaged ttf:fonts. It is safe (but has no effect) to free a struct record multiple times.

free-font! is another name for {[close-font!}}, to be consistent with other free-procedures.

Font Attributes

[procedure] (font-style font) → list of symbols
[setter] (set! (font-style font) style)
[setter] (font-style-set! font style)

Get or set the ttf:font's style, as a list of zero or more of the following symbols:

• bold
• italic
• underline
• strikethrough

Returns an empty list if the font has no style. See TTF_FontGetStyle and TTF_FontSetStyle.

The setters accept either a list of symbols or an integer, representing bitwise-or'd integer constants.

[procedure] (font-outline font) → integer
[setter] (set! (font-outline font) outline)
[setter] (font-outline-set! font outline)

Get or set the ttf:font's outline, as a nonnegative integer number of pixels. See TTF_GetFontOutline and TTF_SetFontOutline.

[procedure] (font-hinting font) → symbol
[setter] (set! (font-hinting font) hinting)
[setter] (font-hinting-set! font hinting)

Get or set the ttf:font's hinting, as one of the following symbols:

• normal
• light
• mono
• none

See TTF_GetFontHinting and TTF_SetFontHinting.

[procedure] (font-kerning? font) → boolean
[setter] (set! (font-kerning? font) kerning)
[setter] (font-kerning-set! font kerning)

Get or set the ttf:font's kerning, as a boolean. #t means kerning is enabled, #f means kerning is disabled.

See TTF_GetFontKerning and TTF_SetFontKerning.

Font Metrics

[procedure] (font-height font) → integer
[procedure] (font-ascent font) → integer
[procedure] (font-descent font) → integer
[procedure] (font-line-skip font) → integer

Return various measurements of the ttf:font.

See TTF_FontHeight, TTF_FontAscent, TTF_FontDescent, TTF_FontLineSkip.

Font Faces

[procedure] (font-faces font) → integer

Returns the number of faces ("sub-fonts") available in the ttf:font. See TTF_FontFaces.

[procedure] (font-face-fixed-width? font) → boolean

Returns #t if the current face of the given ttf:font is a fixed width font (i.e. every glyph is the same width). See TTF_FontFaceIsFixedWidth.

[procedure] (font-face-family-name font) → string

Returns the current font face family name for the given ttf:font. See TTF_FontFaceFamilyName.

[procedure] (font-face-style-name font) → string

Returns the current font face style name for the given ttf:font. See TTF_FontFaceStyleName.

Rendering

Rendering Latin 1 (ISO 8859-1) Text

[procedure] (size-text font text) → [w h]

Calculate the resulting surface size of the Latin 1 (ISO 8859-1) text rendered using the ttf:font. Returns two values, the calculated width and the height, as integers. See TTF_SizeText.

[procedure] (render-text-solid font text fg) → sdl2:surface
[procedure] (render-text-solid* font text fg) → sdl2:surface

Render the given Latin 1 (ISO 8859-1) encoded text using "solid" rendering mode. See TTF_RenderText_Solid.

• font is a ttf:font specifying the font to render with.
• text is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-text-solid returns a managed sdl2:surface.
• render-text-solid* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.

[procedure] (render-text-shaded font text fg bg) → sdl2:surface
[procedure] (render-text-shaded* font text fg bg) → sdl2:surface

Render the given Latin 1-encoded text using "shaded" rendering mode. See TTF_RenderText_Shaded.

• font is a ttf:font specifying the font to render with.
• text is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
• bg is a sdl2:color specifying the background color.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-text-shaded returns a managed sdl2:surface.
• render-text-shaded* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.

[procedure] (render-text-blended font text fg) → sdl2:surface
[procedure] (render-text-blended* font text fg) → sdl2:surface

Render the given Latin 1 (ISO 8859-1) encoded text using "blended" rendering mode. See TTF_RenderText_Blended.

• font is a ttf:font specifying the font to render with.
• text is a Latin 1 (ISO 8859-1) encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-text-blended returns a managed sdl2:surface.
• render-text-blended* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.

Rendering UTF8 Text

[procedure] (size-utf8 font text) → [w h]

Calculate the resulting surface size of the UTF8 text rendered using the given ttf:font. Returns two values, the calculated width and the height, as integers. See TTF_SizeUTF8.

[procedure] (render-utf8-solid font text fg) → sdl2:surface
[procedure] (render-utf8-solid* font text fg) → sdl2:surface

Render the given UTF8 encoded text using "solid" rendering mode. See TTF_RenderUTF8_Solid.

• font is a ttf:font specifying the font to render with.
• text is a UTF8 encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-utf8-solid returns a managed sdl2:surface.
• render-utf8-solid* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.

[procedure] (render-utf8-shaded font text fg bg) → sdl2:surface
[procedure] (render-utf8-shaded* font text fg bg) → sdl2:surface

Render the given UTF8 encoded text using "shaded" rendering mode. See TTF_RenderUTF8_Shaded.

• font is a ttf:font specifying the font to render with.
• text is a UTF8 encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.
• bg is a sdl2:color specifying the background color.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-utf8-shaded returns a managed sdl2:surface.
• render-utf8-shaded* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.

[procedure] (render-utf8-blended font text fg) → sdl2:surface
[procedure] (render-utf8-blended* font text fg) → sdl2:surface

Render the given UTF8 encoded text using "blended" rendering mode. See TTF_RenderUTF8_Blended.

• font is a ttf:font specifying the font to render with.
• text is a UTF8 encoded string specifying the text to render.
• fg is a sdl2:color specifying the foreground color, i.e. the color of the text itself.

Returns a sdl2:surface containing the rendered text. Signals an exception of kind (exn sdl2) if an error occurred.

• render-utf8-blended returns a managed sdl2:surface.
• render-utf8-blended* returns an unmanaged sdl2:surface, which must be freed with free-surface! (from the sdl2 egg) when you are done with it.