sdl2.sdlttf - Python bindings for SDL_ttf

py-sdl2 provides bindings for SDL2_ttf, a library designed for use with SDL2 that provides high quality TrueType font rendering.

SDL2_ttf supports a wide range of font formats, including TrueType (.ttf) and OpenType (.otf) fonts. It also supports different font styles, font hinting modes, and font outlines.

The SDL2_ttf library provides functions for rendering three main formats of text, denoted by the suffix of the function. Functions ending in Text can only render plain ASCII text, whereas functions ending in UTF8 or UNICODE can render most unicode characters provided that a font supports them. In general, you should always use the UTF8 rendering functions unless you have a strong reason to do otherwise.

Note

This module handles font sizes in units of points (pt) instead of pixels. To obtain a font with a given pixel height, you can use the TTF_GlyphMetrics() function to get the pixel heights of different glyphs in the font at a given pt size and use the px/pt ratio to figure out the pt size needed to render text at a given height in px.

Note

The surface sizes and contents of rendered text may vary slightly between systems depending on the version of FreeType used by SDL2_ttf.

Initialization functions

sdl2.sdlttf.TTF_GetError()

Returns the most recently encountered SDL2 error message, if any.

This function is a simple wrapper around SDL_GetError().

Retuns:A UTF-8 encoded string describing the most recent SDL2 error.
Return type:bytes
sdl2.sdlttf.TTF_SetError(fmt)

Sets the most recent SDL2 error message to a given string.

This function is a simple wrapper around SDL_SetError().

Parameters:fmt (bytes) – A UTF-8 encoded string containing the error message to set.
Retuns:Always returns -1.
Return type:int

Text rendering functions

Module constants

sdl2.sdlttf.TTF_MAJOR_VERSION

Latest SDL2_ttf library major number supported by PySDL2.

sdl2.sdlttf.TTF_MINOR_VERSION

Latest SDL2_ttf library minor number supported by PySDL2.

sdl2.sdlttf.TTF_PATCHLEVEL

Latest SDL2_ttf library patch level number supported by PySDL2.

sdl2.sdlttf.UNICODE_BOM_NATIVE

This allows you to switch byte-order of UNICODE (UCS-2) text data to native order, meaning the mode of your CPU. This is meant to be used in UNICODE strings that you are using with the SDL2_ttf API. Not needed for UTF8 strings.

sdl2.sdlttf.UNICODE_BOM_SWAPPED

This allows you to switch byte-order of UNICODE (UCS-2) text data to swapped order, meaning the reversed mode of your CPU. Thus, if your CPU is LSB, then the data will be interpretted as MSB. This is meant to be used in UNICODE strings that you are using with the SDL2_ttf API. Not needed for UTF8 strings.

sdl2.sdlttf.TTF_STYLE_NORMAL

Used to indicate regular, normal, plain rendering style.

sdl2.sdlttf.TTF_STYLE_BOLD

Used to indicate bold rendering style. This is used in a bitmask along with other styles.

sdl2.sdlttf.TTF_STYLE_ITALIC

Used to indicate italicized rendering style. This is used in a bitmask along with other styles.

sdl2.sdlttf.TTF_STYLE_UNDERLINE

Used to indicate underlined rendering style. This is used in a bitmask along with other styles.

sdl2.sdlttf.TTF_STYLE_STRIKETHROUGH

Used to indicate strikethrough rendering style. This is used in a bitmask along with other styles.

sdl2.sdlttf.TTF_HINTING_NORMAL

Used to indicate set hinting type to normal. This corresponds to the default hinting algorithm, optimized for standard gray-level rendering.

sdl2.sdlttf.TTF_HINTING_LIGHT

Used to indicate set hinting type to light. A lighter hinting algorithm for non-monochrome modes. Many generated glyphs are more fuzzy but better resemble its original shape. A bit like rendering on macOS.

sdl2.sdlttf.TTF_HINTING_MONO

Used to indicate set hinting type to monochrome. Strong hinting algorithm that should only be used for monochrome output. The result is probably unpleasant if the glyph is rendered in non-monochrome modes.

sdl2.sdlttf.TTF_HINTING_NONE

Used to indicate set hinting type to none. No hinting is used, so the font may become very blurry or messy at smaller sizes.