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.
Table Of Contents
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_Init()[source]
Initializes the TTF engine.
This function must be called before using other functions in this library (except for
TTF_WasInit()
). SDL does not have to be initialized before this function is called.- Returns
0 if successful, or -1 on error.
- Return type
int
- sdl2.sdlttf.TTF_Quit()[source]
De-initializes the TTF engine.
Once this has been called, other functions in the module should not be used until
TTF_Init()
is called to re-initialize the engine (except forTTF_WasInit()
).Note
If
TTF_Init()
is called multiple times, this function should be called an equal number of times to properly de-initialize the library.
- sdl2.sdlttf.TTF_WasInit()[source]
Checks if the TTF engine is initialized.
This function can be used before calling
TTF_Init()
to avoid initializing twice in a row, or to determine if need to callTTF_Quit()
.- Returns
The number of times
TTF_Init()
has been called without a correspondingTTF_Quit()
.- Return type
int
- 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
- sdl2.sdlttf.TTF_ByteSwappedUNICODE(swapped)[source]
Tells the library whether UCS-2 unicode text is generally byteswapped.
A unicode BOM character in a string will override this setting for the remainder of that string. The default mode is non-swapped, native endianness of the CPU.
Note that this only affects the behaviour of
UNICODE
(UCS-2) functions and has no effect on UTF8 functions.- Parameters
swapped (int) – If 0, native CPU endianness will be used. If not 0, UCS-2 data will be byte-swapped relative to native CPU endianness.
- sdl2.sdlttf.TTF_Linked_Version()[source]
Gets the version of the dynamically-linked SDL2_ttf library.
- Returns
A pointer to a structure containing the version of the SDL2_ttf library currently in use.
- Return type
POINTER(
SDL_version
)
- sdl2.sdlttf.TTF_GetFreeTypeVersion(major, minor, patch)[source]
Gets the version of the FreeType library currently linked by SDL2_ttf.
This function returns the version numbers by reference, meaning that it needs to be called using pre-allocated ctypes variables (see
TTF_GlyphMetrics()
for an example).Note: Added in SDL_ttf 2.0.18
- Parameters
major (byref(
c_int
)) – A pointer to an integer containing the major version number of the linked FreeType library.minor (byref(
c_int
)) – A pointer to an integer containing the minor version number of the linked FreeType library.patch (byref(
c_int
)) – A pointer to an integer containing the patch level of the linked FreeType library.
- sdl2.sdlttf.TTF_GetHarfBuzzVersion(major, minor, patch)[source]
Gets the version of the HarfBuzz library currently linked by SDL2_ttf.
This function returns the version numbers by reference, meaning that it needs to be called using pre-allocated ctypes variables (see
TTF_GlyphMetrics()
for an example).Note: Added in SDL_ttf 2.0.18
- Parameters
major (byref(
c_int
)) – A pointer to an integer containing the major version number of the linked HarfBuzz library.minor (byref(
c_int
)) – A pointer to an integer containing the minor version number of the linked HarfBuzz library.patch (byref(
c_int
)) – A pointer to an integer containing the patch level of the linked HarfBuzz library.
Font loading functions
- sdl2.sdlttf.TTF_OpenFont(file, ptsize)[source]
Opens a font file at a given size.
Point sizes are based on a DPI of 72. Use the
TTF_GetError()
function to check for any errors opening the font.- Parameters
file (bytes) – A UTF8-encoded bytestring containing the path of the font file to load.
ptsize (int) – The size (in points) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontIndex(file, ptsize, index)[source]
Opens a specific font face by index from a file at a given size.
This function allows for loading a specific font face from a multi-face font. See
TTF_OpenFont()
for more information.- Parameters
file (bytes) – A UTF8-encoded bytestring containing the path of the font file to load.
ptsize (int) – The size (in points) at which to open the font.
index (int) – The index (from 0 to 15) of the font face to open. For font files with only one face, this should always be 0.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontRW(src, freesrc, ptsize)[source]
Opens a font from a file object at a given size.
Point sizes are based on a DPI of 72. Use the
TTF_GetError()
function to check for any errors opening the font.Note
The file object used to create the font (
src
) must be kept in memory until you are done with the font. Once thesrc
has been freed, performing any additional operations with the returnedTTF_Font
will result in a hard Python crash (segmentation fault).- Parameters
src (
SDL_RWops
) – A file object containing a valid font.freesrc (int) – If non-zero, the provided file object will be closed and freed automatically when the resulting
TTF_Font
is closed (or if an error is encountered opening the font).ptsize (int) – The size (in points) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontIndexRW(src, freesrc, ptsize, index)[source]
Opens a specific font face by index from a file object at a given size.
This function allows for loading a specific font face from a multi-face font. See
TTF_OpenFontRW()
for more information.- Parameters
src (
SDL_RWops
) – A file object containing a valid font.freesrc (int) – If non-zero, the provided file object will be closed and freed automatically when the resulting
TTF_Font
is closed (or if an error is encountered opening the font).ptsize (int) – The size (in points) at which to open the font.
index (int) – The index (from 0 to 15) of the font face to open. For font files with only one face, this should always be 0.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontDPI(file, ptsize, hdpi, vdpi)[source]
Opens a font file at a given size and DPI.
The font will be opened with the given horizontal and vertical target resolutions (in DPI). DPI scaling only applies to scalable fonts (e.g. TrueType). Use the
TTF_GetError()
function to check for any errors opening the font.Note: Added in SDL_ttf 2.0.18
- Parameters
file (bytes) – A UTF8-encoded bytestring containing the path of the font file to load.
ptsize (int) – The size (in points) at which to open the font.
hdpi (int) – The horizontal resolution (in DPI) at which to open the font.
vdpi (int) – The vertical resolution (in DPI) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontIndexDPI(file, ptsize, index, hdpi, vdpi)[source]
Opens a specific font face by index from a file at a given size and DPI.
See
TTF_OpenFontDPI()
and :func:`TTF_OpenFontIndex for more information.Note: Added in SDL_ttf 2.0.18
- Parameters
file (bytes) – A UTF8-encoded bytestring containing the path of the font file to load.
ptsize (int) – The size (in points) at which to open the font.
index (int) – The index (from 0 to 15) of the font face to open. For font files with only one face, this should always be 0.
hdpi (int) – The horizontal resolution (in DPI) at which to open the font.
vdpi (int) – The vertical resolution (in DPI) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontDPIRW(src, freesrc, ptsize, hdpi, vdpi)[source]
Opens a font from a file object at a given size and DPI.
See
TTF_OpenFontDPI()
and :func:`TTF_OpenFontRW for more information.Note: Added in SDL_ttf 2.0.18
- Parameters
src (
SDL_RWops
) – A file object containing a valid font.freesrc (int) – If non-zero, the provided file object will be closed and freed automatically when the resulting
TTF_Font
is closed (or if an error is encountered opening the font).ptsize (int) – The size (in points) at which to open the font.
hdpi (int) – The horizontal resolution (in DPI) at which to open the font.
vdpi (int) – The vertical resolution (in DPI) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
- sdl2.sdlttf.TTF_OpenFontIndexDPIRW(src, freesrc, ptsize, index, hdpi, vdpi)[source]
Opens a font face by index from a file object at a given size and DPI.
See
TTF_OpenFontDPI()
and :func:`TTF_OpenFontIndexRW for more information.Note: Added in SDL_ttf 2.0.18
- Parameters
src (
SDL_RWops
) – A file object containing a valid font.freesrc (int) – If non-zero, the provided file object will be closed and freed automatically when the resulting
TTF_Font
is closed (or if an error is encountered opening the font).ptsize (int) – The size (in points) at which to open the font.
index (int) – The index (from 0 to 15) of the font face to open. For font files with only one face, this should always be 0.
hdpi (int) – The horizontal resolution (in DPI) at which to open the font.
vdpi (int) – The vertical resolution (in DPI) at which to open the font.
- Returns
A pointer to the opened font object, or a null pointer if there was an error.
- Return type
POINTER(
TTF_Font
)
Font attribute functions
Sizing functions
- sdl2.sdlttf.TTF_SetFontSize(font, ptsize)[source]
Changes the size of a TTF font object dynamically.
Use
TTF_GetError()
to check for errors.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to update.ptsize (int) – The new size (in points) to use for the font.
- Returns
0 on success, or -1 on error.
- Return type
int
- sdl2.sdlttf.TTF_SetFontSizeDPI(font, ptsize, hdpi, vdpi)[source]
Changes the size and DPI of a TTF font object dynamically.
Use
TTF_GetError()
to check for errors.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to update.ptsize (int) – The new size (in points) to use for the font.
hdpi (int) – The new horizontal resolution (in DPI) at which to render the font.
vdpi (int) – The vertical resolution (in DPI) at which to render the font.
- Returns
0 on success, or -1 on error.
- Return type
int
- sdl2.sdlttf.TTF_FontHeight(font)[source]
Gets the maximum pixel height of all glyphs in a given font.
You can use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can’t touch.
- Parameters
font (
TTF_Font
) – The font object for which the maximum glyph height should be retrieved.- Returns
The maximum height (in pixels) of all glyphs in the font.
- Return type
int
- sdl2.sdlttf.TTF_FontAscent(font)[source]
Gets the maximum pixel ascent of all glyphs in a given font.
The ascent of a glyph is defined as the distance from the top of the glyph to its baseline. For example, a lower-case “t” will generally have a larger ascent than a lower-case “o”.
- Parameters
font (
TTF_Font
) – The font object for which the maximum glyph ascent should be retrieved.- Returns
The maximum ascent (in pixels) of all glyphs in the font.
- Return type
int
- sdl2.sdlttf.TTF_FontDescent(font)[source]
Gets the maximum pixel descent of all glyphs in a given font.
The descent of a glyph is defined as the distance from the bottom of the glyph to its baseline. For example, a lower-case “g” will typically have a non-zero descent whereas a lower-case “o” will generally have a descent of zero.
- Parameters
font (
TTF_Font
) – The font object for which the maximum glyph descent should be retrieved.- Returns
The maximum descent (in pixels) of all glyphs in the font.
- Return type
int
- sdl2.sdlttf.TTF_FontLineSkip(font)[source]
Gets the recommended spacing between lines for a given font.
This is usually larger than the result of
TTF_FontHeight()
.- Parameters
font (
TTF_Font
) – The font object for which the recommended line skip height should be retrieved.- Returns
The recommended line skip height (in pixels) for the font.
- Return type
int
Style functions
- sdl2.sdlttf.TTF_SetFontStyle(font, style)[source]
Sets the rendering style for a given font.
Font styles can be specified using the following constants:
Style
Constant
Normal
TTF_STYLE_NORMAL
Bold
TTF_STYLE_BOLD
Italics
TTF_STYLE_ITALICS
Underlined
TTF_STYLE_UNDERLINE
Strikethrough
TTF_STYLE_STRIKETHROUGH
Multiple font styles (e.g. bold and italics) can be combined using the bitwise
|
operator:underlined_bold = (TTF_STYLE_BOLD | TTF_STYLE_UNDERLINE) TTF_SetFontStyle(font, underlined_bold)
Note
Setting the underline style for a font may cause the surfaces created by
TTF_RenderGlyph
functions to be taller, in order to make room for the underline to be drawn underneath.- Parameters
font (
TTF_Font
) – The font object for which the style will be set.style (int) – A bitmask specifying the style(s) to use for the font.
- sdl2.sdlttf.TTF_GetFontStyle(font)[source]
Retrieves the current rendering style of a given font.
To check for the presence of a given style within a font, the return value of this function can be used with a bitwise
&
operator:style = TTF_GetFontStyle(font) is_bold = style & TTF_STYLE_BOLD == TTF_STYLE_BOLD is_underlined = style & TTF_STYLE_UNDERLINE == TTF_STYLE_UNDERLINE
- Parameters
font (
TTF_Font
) – The font object for which the style should be retrieved.- Returns
A bitmask of one or more style constants (see
TTF_SetFontStyle()
).- Return type
int
- sdl2.sdlttf.TTF_FontFaceIsFixedWidth(font)[source]
Checks if the current face of a given font is fixed width.
Fixed width fonts are monospace, meaning every character that exists in the font is the same width, thus you can assume that a rendered string’s width is going to be the result of a simple calculation:
glyph_width * string_length
.- Parameters
font (
TTF_Font
) – The font object for which the fixed-width status should be retrieved.- Returns
A positive integer if the font is fixed-width, otherwise 0.
- Return type
int
Glyph information functions
- sdl2.sdlttf.TTF_GlyphIsProvided(font, ch)[source]
Checks whether a character is provided by a given font.
The built-in Python
ord()
function can be used to convert a string character to an integer for use with this function (e.g.ord("A")
).- Parameters
font (
TTF_Font
) – The font object within which to check for a glyph for the given character.ch (int) – A unicode integer representing the character to check for within the font.
- Returns
A non-zero integer if the font provides a glyph for the character, otherwise 0.
- Return type
int
- sdl2.sdlttf.TTF_GlyphIsProvided32(font, ch)[source]
Checks whether a character is provided by a given font.
Functionally identical to
TTF_GlyphIsProvided()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
- sdl2.sdlttf.TTF_GlyphMetrics(font, ch, minx, maxx, miny, maxy, advance)[source]
Gets the glyph metrics for a character with a given font.
This function returns the calculated metrics by reference, meaning that it needs to be called using pre-allocated ctypes variables:
from ctypes import c_int, byref minX, maxX, minY, maxY = c_int(0), c_int(0), c_int(0), c_int(0) adv = c_int(0) TTF_GlyphMetrics( font, ord(char), byref(minX), byref(maxX), byref(minY), byref(maxY), byref(adv) ) results = [x.value for x in (minX, maxX, minY, maxY, adv)]
The following link may be useful for understanding what these metrics mean: http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
- Parameters
font (
TTF_Font
) – The font object to use.ch (int) – A unicode integer representing the character for which to retrieve glyph metrics.
minx (byref(
c_int
)) – A pointer to an integer in which to store the glyph’s minimum X offset.maxx (byref(
c_int
)) – A pointer to an integer in which to store the glyph’s maximum X offset.miny (byref(
c_int
)) – A pointer to an integer in which to store the glyph’s minimum Y offset.maxy (byref(
c_int
)) – A pointer to an integer in which to store the glyph’s maximum Y offset.
- Returns
0 on success, or -1 on error (e.g. if the glyph does not exist in the font).
- Return type
int
- sdl2.sdlttf.TTF_GlyphMetrics32(font, ch, minx, maxx, miny, maxy, advance)[source]
Gets the glyph metrics for a character with a given font.
Functionally identical to
TTF_GlyphMetrics()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
Kerning functions
- sdl2.sdlttf.TTF_GetFontKerning(font)[source]
Checks whether or not kerning is enabled for a given font.
- Parameters
font (
TTF_Font
) – The font object for which the kerning status should be retrieved.- Returns
Non-zero if kerning is enabled for the font, otherwise 0.
- Return type
int
- sdl2.sdlttf.TTF_SetFontKerning(font, allowed)[source]
Enables or disables kerning for a given font.
Kerning is enabled for all fonts by default.
- Parameters
font (
TTF_Font
) – The font object for which the kerning status should be changed.allowed (int) – 0 to disable kerning, or non-zero to enable it.
- sdl2.sdlttf.TTF_GetFontKerningSizeGlyphs(font, previous_ch, ch)[source]
Gets the kerning size of two glyphs (by FreeType index) for a given font.
Note
The units of kerning size returned by this function differ between fonts depending on their format and how they were designed.
Note: Added in SDL_ttf 2.0.14
- Parameters
font (
TTF_Font
) – The font object for which the kerning size should be retrieved.previous_ch (int) – The unicode integer representing the first glyph.
ch (int) – The unicode integer representing the second glyph.
- Returns
The kerning size of the two glyphs in the current font.
- Return type
int
- sdl2.sdlttf.TTF_GetFontKerningSizeGlyphs32(font, previous_ch, ch)[source]
Gets the kerning size of two glyphs (by FreeType index) for a given font.
Functionally identical to
TTF_GetFontKerningSizeGlyphs()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
Render settings functions
- sdl2.sdlttf.TTF_SetFontHinting(font, hinting)[source]
Sets the rendering hinting mode for a given font.
The hinting mode can be specified using one of the following constants:
Hinting type
Constant
Normal
TTF_HINTING_NORMAL
Light
TTF_HINTING_LIGHT
Mono
TTF_HINTING_MONO
None
TTF_HINTING_NONE
Light (Subpixel)
TTF_HINTING_LIGHT_SUBPIXEL
Note that the
TTF_HINTING_LIGHT_SUBPIXEL
hinting mode requires SDL_ttf 2.0.18 or newer. If no hinting mode is is explicitly set, “normal” hinting is used for rendering.- Parameters
font (
TTF_Font
) – The font object for which the hinting style will be set.hinting (int) – A constant specifiying the hinting style to use when rendering text.
- sdl2.sdlttf.TTF_GetFontHinting(font)[source]
Retrieves the current hinting style of a given font.
This function returns one of the constants specified in the documentation for
TTF_SetFontHinting()
.- Parameters
font (
TTF_Font
) – The font object for which the hinting style should be retrieved.- Returns
A constant indicating the hinting style of the font.
- Return type
int
- sdl2.sdlttf.TTF_SetFontSDF(font, on_off)[source]
Enables or disables Signed Distance Field rendering for a given font.
Requires a version of FreeType that supports SDF rendering (2.11.0 or newer). As of SDL2_ttf 2.0.18, the FreeType version bundled with the official binaries is too old to support SDF.
Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object for which SDF should be enabled or disabled.on_off (int) – Whether to enable (
SDL_TRUE
) or disable (SDL_FALSE
) SDF rendering for the given font.
- Returns
0 on success, or -1 if SDF support not available.
- Return type
int
- sdl2.sdlttf.TTF_GetFontSDF(font)[source]
Checks if Signed Distance Field rendering is enabled for a given font.
If using a version of FreeType without SDF support, this will always return 0.
Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object for which SDF usage should be checked.- Returns
1 if the font is using SDF, otherwise 0.
- Return type
int
- sdl2.sdlttf.TTF_SetFontWrappedAlign(font, align)[source]
Sets the alignment to use when rendering wrapped text with a given font.
The alignment type can be specified using one of the following constants:
Alignment
Constant
Left-justified
TTF_WRAPPED_ALIGN_LEFT
Centered
TTF_WRAPPED_ALIGN_CENTER
Right-justified
TTF_WRAPPED_ALIGN_RIGHT
Wrapped text will be left-justified if no alignment is explicitly set.
Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object for which the alignment type will be set.align (int) – A constant specifiying the aligmnent to use when rendering wrapped text.
- sdl2.sdlttf.TTF_GetFontWrappedAlign(font)[source]
Retrieves the current wrapping alignment for a given font.
This function returns one of the constants specified in the documentation for
TTF_SetFontWrappedAlign()
.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object for which the alignment type should be retrieved.- Returns
A constant indicating the current wrap alignment for the font.
- Return type
int
- sdl2.sdlttf.TTF_SetFontDirection(font, direction)[source]
Sets the text direction to use for rendering a given font.
This function lets you manually specify the direction to use for rendering text with a given font, using the following constants:
Text Direction
Constant
Left-to-right
TTF_DIRECTION_LTR
Right-to-left
TTF_DIRECTION_RTL
Top-to-bottom
TTF_DIRECTION_TTB
Bottom-to-top
TTF_DIRECTION_BTT
Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to configure.direction (int) – A constant specifying the direction to use for rendering text with the given font.
- Returns
0 on success, -1 on error.
- Return type
int
- sdl2.sdlttf.TTF_SetFontScriptName(font, script)[source]
Sets the script (e.g. Arabic) to use for rendering a given font.
Setting the script gives the text renderer extra information about how to best shape words and characters for a given language. This can produce better results when rendering with non-Latin languages and fonts.
The script type is specified as a 4-character ISO 15924 character code (e.g. ‘Arab’ for Arabic). A full list of possible 4-character script codes can be found here: https://unicode.org/iso15924/iso15924-codes.html
Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to configure.script (bytes) – A 4-character ISO 15924 character code indicating the script type to use for text shaping.
- Returns
0 on success, -1 on error.
- Return type
int
Text rendering functions
Size calculation functions
- sdl2.sdlttf.TTF_MeasureText(font, text, measure_width, extent, count)[source]
Gets the number of characters that can fit within a given width.
This function determines how many rendered characters from a given string of ASCII text can fit within a given width. It additionally returns the rendered width of the fitting characters.
Use the
TTF_GetError()
function to check for any errors.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text.
measure_width (int) – The maximum width (in pixels) of the rendered output surface.
extent (byref(
c_int
)) – A pointer to an integer containing the calculated rendered width of the firstcount
characters of the string.count (byref(
c_int
)) – A pointer to an integer containing the returned number of characters from the string that can fit within the given width.
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
- sdl2.sdlttf.TTF_MeasureUTF8(font, text, measure_width, extent, count)[source]
Gets the number of characters that can fit within a given width.
Identical to
TTF_MeasureText()
, except that this function is used with UTF8-encoded bytestrings instead of ASCII-encoded ones.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text.
measure_width (int) – The maximum width (in pixels) of the rendered output surface.
extent (byref(
c_int
)) – A pointer to an integer containing the calculated rendered width of the firstcount
characters of the string.count (byref(
c_int
)) – A pointer to an integer containing the returned number of characters from the string that can fit within the given width.
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
- sdl2.sdlttf.TTF_MeasureUNICODE(font, text, measure_width, extent, count)[source]
Gets the number of characters that can fit within a given width.
Identical to
TTF_MeasureText()
, except that this function is used with UCS-2 byte arrays instead of ASCII-encoded bytestrings. See theTTF_RenderUNICODE_Solid()
documentation for more information on converting text to UCS-2 in Python.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text.measure_width (int) – The maximum width (in pixels) of the rendered output surface.
extent (byref(
c_int
)) – A pointer to an integer containing the calculated rendered width of the firstcount
characters of the string.count (byref(
c_int
)) – A pointer to an integer containing the returned number of characters from the string that can fit within the given width.
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
- sdl2.sdlttf.TTF_SizeText(font, text, w, h)[source]
Calculates the size of an ASCII string rendered with a given font.
This function does not perform any actual rendering, but correct kerning is performed to get the actual width. For a string without any newlines, the height will be the same as that returned by
TTF_FontHeight()
.This function returns the calculated metrics by reference, meaning that it needs to be called using pre-allocated ctypes variables:
from ctypes import c_int, byref text_w, text_h = c_int(0), c_int(0) TTF_SizeText(font, b"hello!", byref(text_w), byref(text_h)) text_size = [x.value for x in (text_w, text_h)]
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text for which the rendered surface size should be calculated.
w (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface width (in pixels).h (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface height (in pixels).
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
- sdl2.sdlttf.TTF_SizeUTF8(font, text, w, h)[source]
Calculates the size of a UTF8-encoded string rendered with a given font.
See
TTF_SizeText()
for more info.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text for which the rendered surface size should be calculated.
w (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface width (in pixels).h (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface height (in pixels).
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
- sdl2.sdlttf.TTF_SizeUNICODE(font, text, w, h)[source]
Calculates the size of a UCS-2 encoded string rendered with a given font.
See
TTF_SizeText()
andTTF_RenderUNICODE_Solid()
for more info.- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text for which the rendered surface size should be calculated.w (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface width (in pixels).h (byref(
c_int
)) – A pointer to an integer in which to store the calculated surface height (in pixels).
- Returns
0 on success, or -1 on error (e.g. if a glyph is not found in the font).
- Return type
int
Solid rendering functions
- sdl2.sdlttf.TTF_RenderText_Solid(font, text, fg)[source]
Renders an ASCII-encoded string to a non-antialiased 8-bit surface.
The
Solid
family of TTF functions render text to an 8-bit palettizedSDL_Surface
with a transparent background and no antialiasing. This is the fastest (and lowest quality) of all TTF rendering types.The resulting surface has a transparent background unlike
TTF_RenderText_Shaded()
, but the rendered text is not antialised and will thus appear pixelated and difficult to read at small sizes. The resulting surface should blit faster than the one returned byTTF_RenderText_Blended()
. This rendering type should be used in cases when you need to render lots of text very quickly (e.g. if you’re updating it every frame) or when you don’t care about antialiasing.The 0 pixel is the colorkey for the resulting surface, giving a transparent background, and the 1 pixel is set to the text color. This allows you to change the color without having to render the text again. Palette index 0 is not drawn when the returned surface is blitted to another surface (since it is the colorkey and thus transparent), though its actual color is 255 minus each of the RGB components of the foreground color.
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Solid(font, text, fg)[source]
Renders a UTF8-encoded string to a non-antialiased 8-bit surface.
See
TTF_RenderText_Solid()
for more details on the rendering style.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Solid(font, text, fg)[source]
Renders a UCS-2 encoded string to a non-antialiased 8-bit surface.
The required text input format for this function is a ctypes array of UNICODE (UCS-2) glyphs in uint16 format, optionally terminated by a byte-order mark (
UNICODE_BOM_NATIVE
orUNICODE_BOM_SWAPPED
) indicating how the text should be interpreted. Python strings can be converted to this format using the following process:# Generate a UCS-2 array from a Python string teststr = u"Hello world!" strlen = len(teststr + 1) # +1 for byte-order mark intstr = unpack('H' * strlen, teststr.encode('utf-16')) intstr = intstr + (0, ) # Null-terminate the string strarr = (ctypes.c_uint16 * len(intstr))(*intstr) # Render the UCS-2 string col = SDL_Color(0, 0, 0) rendered = TTF_RenderUNICODE_Solid(font, strarr, col)
Unless there is a very specific need, the
TTF_RenderUTF8
functions should always be used instead of theirTTF_RenderUNICODE
counterparts. In addition to having a much friendlier Python API, SDL_ttf uses theTTF_RenderUTF8
functions internally for all theTTF_RenderUNICODE
functions anyway so there is no benefit in terms of supporting a wider range of characters.See
TTF_RenderText_Solid()
for more details on the rendering style.- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph_Solid(font, ch, fg)[source]
Renders a unicode character to a non-antialiased 8-bit surface.
The built-in Python
ord()
function can be used to convert a string character to an integer for use with this function (e.g.ord("A")
).The glyph is rendered without any padding or centering in the X direction, and is aligned normally in the Y direction. See
TTF_RenderText_Solid()
for more details on the rendering style.- Parameters
font (
TTF_Font
) – The font object to use.ch (int) – A unicode integer representing the glyph to render.
fg (
SDL_Color
) – The color to use for rendering the glyph. This becomes colormap index 1.
- Returns
A pointer to the new surface containing the rendered glyph, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph32_Solid(font, ch, fg)[source]
Renders a unicode character to a non-antialiased 8-bit surface.
Functionally identical to
TTF_RenderGlyph_Solid()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
- sdl2.sdlttf.TTF_RenderText_Solid_Wrapped(font, text, fg, wrapLength)[source]
Renders an ASCII-encoded string to a non-antialiased 8-bit surface.
This function is identical to
TTF_RenderText_Solid()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Solid_Wrapped(font, text, fg, wrapLength)[source]
Renders a UTF8-encoded string to a non-antialiased 8-bit surface.
This function is identical to
TTF_RenderUTF8_Solid()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Solid_Wrapped(font, text, fg, wrapLength)[source]
Renders a UCS-2 encoded string to a non-antialiased 8-bit surface.
This function is identical to
TTF_RenderUNICODE_Solid()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
Shaded rendering functions
- sdl2.sdlttf.TTF_RenderText_Shaded(font, text, fg, bg)[source]
Renders an ASCII-encoded string to a solid antialiased 8-bit surface.
The
Shaded
family of TTF functions render text to an 8-bit palettizedSDL_Surface
with a solid background color and antialiasing. This is the second-fastest of the text rendering types, being slightly faster thanTTF_RenderText_Blended()
but slower thanTTF_RenderText_Solid()
.Text rendered using the
Shaded
method will be antialiased, but the resulting surface will have a solid background colour instead of a transparent one. Surfaces rendered with this function should blit as quickly as those created withTTF_RenderText_Blended()
. This rendering type should be used in cases when you want nice-looking text but don’t need background transparency.The 0 pixel is the background color for the resulting surface, while other pixels have varying levels of the foreground color. This results in a box of the background color around the text in the foreground color.
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Shaded(font, text, fg, bg)[source]
Renders a UTF8-encoded string to a solid antialiased 8-bit surface.
See
TTF_RenderText_Shaded()
for more details on the rendering style.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Shaded(font, text, fg, bg)[source]
Renders a UCS-2 encoded string to a solid antialiased 8-bit surface.
See
TTF_RenderText_Shaded()
for more details on the rendering style, andTTF_RenderUNICODE_Solid()
for documentation of the text format.- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph_Shaded(font, ch, fg, bg)[source]
Renders a unicode character to an 8-bit surface using a given font.
See
TTF_RenderText_Shaded()
for more details on the rendering style, andTTF_RenderGlyph_Solid()
for additional usage information.- Parameters
font (
TTF_Font
) – The font object to use.ch (int) – A unicode integer representing the glyph to render.
fg (
SDL_Color
) – The color to use for rendering the glyph. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the glyph. This becomes colormap index 0.
- Returns
A pointer to the new surface containing the rendered glyph, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph32_Shaded(font, ch, fg, bg)[source]
Renders a unicode character to an 8-bit surface using a given font.
Functionally identical to
TTF_RenderGlyph_Shaded()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
- sdl2.sdlttf.TTF_RenderText_Shaded_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders an ASCII-encoded string to a solid antialiased 8-bit surface.
This function is identical to
TTF_RenderText_Shaded()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Shaded_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders a UTF8-encoded string to a solid antialiased 8-bit surface.
This function is identical to
TTF_RenderUTF8_Shaded()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Shaded_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders a UCS-2 encoded string to a solid antialiased 8-bit surface.
This function is identical to
TTF_RenderUNICODE_Shaded()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.0.18
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text. This becomes colormap index 1.bg (
SDL_Color
) – The background fill color for the text. This becomes colormap index 0.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
Blended rendering functions
- sdl2.sdlttf.TTF_RenderText_Blended(font, text, fg)[source]
Renders an ASCII-encoded string to an antialiased 32-bit surface.
The
Blended
family of TTF functions render text to a 32-bit ARGBSDL_Surface
with antialiasing and background transparency.The rendered text will be antialiased on a transparent surface using alpha blending. This rendering type should be used in cases when you want to overlay the rendered text over something else, and in in most other cases where high performance isn’t the primary concern. For rendering high-quality text on a solid background or at smaller font sizes, see the
LCD
family of rendering functions.Note
To render an RGBA surface instead of an ARGB one, just swap the R and B values when creating the SDL_Color.
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Blended(font, text, fg)[source]
Renders a UTF8-encoded string to an antialiased 32-bit surface.
See
TTF_RenderText_Blended()
for more details on the rendering style.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Blended(font, text, fg)[source]
Renders a UCS-2 encoded string to an antialiased 32-bit surface.
See
TTF_RenderText_Blended()
for more details on the rendering style, andTTF_RenderUNICODE_Solid()
for documentation of the text format.- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph_Blended(font, ch, fg)[source]
Renders a unicode character to an antialiased 32-bit surface.
See
TTF_RenderText_Blended()
for more details on the rendering style, andTTF_RenderGlyph_Solid()
for additional usage information.- Parameters
font (
TTF_Font
) – The font object to use.ch (int) – A unicode integer representing the glyph to render.
fg (
SDL_Color
) – The color to use for rendering the glyph.
- Returns
A pointer to the new surface containing the rendered glyph, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph32_Blended(font, ch, fg)[source]
Renders a unicode character to an antialiased 32-bit surface.
Functionally identical to
TTF_RenderGlyph_Blended()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.0.18
- sdl2.sdlttf.TTF_RenderText_Blended_Wrapped(font, text, fg, wrapLength)[source]
Renders an ASCII-encoded string to an antialiased 32-bit surface.
This function is identical to
TTF_RenderText_Blended()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_Blended_Wrapped(font, text, fg, wrapLength)[source]
Renders a UTF8-encoded string to an antialiased 32-bit surface.
This function is identical to
TTF_RenderUTF8_Blended()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_Blended_Wrapped(font, text, fg, wrapLength)[source]
Renders a UCS-2 encoded string to an antialiased 32-bit surface.
This function is identical to
TTF_RenderUNICODE_Blended()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
LCD rendering functions
- sdl2.sdlttf.TTF_RenderText_LCD(font, text, fg, bg)[source]
Renders an ASCII-encoded string to a solid 32-bit surface.
The
LCD
family of TTF functions render text to av32-bit ARGBSDL_Surface
with high-quality subpixel rendering. This should produce better results at small sizes thanTTF_RenderText_Shaded()
, but may be slower and requires a solid background colour for best results.Note
To render an RGBA surface instead of an ARGB one, just swap the R and B values when creating the foreground and background colors.
Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_LCD(font, text, fg, bg)[source]
Renders a UTF8-encoded string to a solid antialiased 32-bit surface.
See
TTF_RenderText_LCD()
for more details on the rendering style.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_LCD(font, text, fg, bg)[source]
Renders a UCS-2 encoded string to a solid antialiased 32-bit surface.
See
TTF_RenderText_LCD()
for more details on the rendering style, andTTF_RenderUNICODE_Solid()
for documentation of the text format.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph_LCD(font, ch, fg, bg)[source]
Renders a unicode character to a 32-bit surface using a given font.
See
TTF_RenderText_LCD()
for more details on the rendering style, andTTF_RenderGlyph_Solid()
for additional usage information.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.ch (int) – A unicode integer representing the glyph to render.
fg (
SDL_Color
) – The color to use for rendering the glyph.bg (
SDL_Color
) – The background fill color for the glyph.
- Returns
A pointer to the new surface containing the rendered glyph, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderGlyph32_LCD(font, ch, fg, bg)[source]
Renders a unicode character to a 32-bit surface using a given font.
Functionally identical to
TTF_RenderGlyph_LCD()
, except it supports 32-bit character codes instead of just 16-bit ones.Note: Added in SDL_ttf 2.20.0
- sdl2.sdlttf.TTF_RenderText_LCD_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders an ASCII-encoded string to a solid antialiased 32-bit surface.
This function is identical to
TTF_RenderText_LCD()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – An ASCII-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUTF8_LCD_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders a UTF8-encoded string to a solid antialiased 32-bit surface.
This function is identical to
TTF_RenderUTF8_LCD()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (byref(
c_uint16
)) – A ctypes array containing a UCS-2 encoded string of text to render.fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
- sdl2.sdlttf.TTF_RenderUNICODE_LCD_Wrapped(font, text, fg, bg, wrapLength)[source]
Renders a UCS-2 encoded string to a solid antialiased 32-bit surface.
This function is identical to
TTF_RenderUNICODE_LCD()
, except that any lines exceeding the specified wrap length will be wrapped to fit within the given width.Note: Added in SDL_ttf 2.20.0
- Parameters
font (
TTF_Font
) – The font object to use.text (bytes) – A UTF8-encoded bytestring of text to render.
fg (
SDL_Color
) – The color to use for rendering the text.bg (
SDL_Color
) – The background fill color for the text.wrapLength (int) – The maximum width of the output surface (in pixels)
- Returns
A pointer to the new surface containing the rendered text, or a null pointer if there was an error.
- Return type
POINTER(
SDL_Surface
)
Renderer configuration functions
- sdl2.sdlttf.TTF_SetDirection(direction)[source]
Sets the global text direction to use for rendering.
Note
This function has been deprecated in favor of
TTF_SetFontDirection()
and should not be used in new projects.This function lets you manually specify the direction in which SDL_ttf should render text, and can be set or changed at any time.
The direction value is passed to the underlying HarfBuzz library, meaning that the direction must be one of the following HarfBuzz constants:
Text Direction
Constant
Left-to-right
HB_DIRECTION_LTR
Right-to-left
HB_DIRECTION_RTL
Top-to-bottom
HB_DIRECTION_TTB
Bottom-to-top
HB_DIRECTION_BTT
For convenience, these constants are provided by the
sdl2.sdlttf
module. If not specified, SDL_ttf defaults to left-to-right text rendering.Note: Added in SDL_ttf 2.0.18
- Parameters
direction (int) – A constant specifying the direction to use for text rendering with the TTF library.
- Returns
0 on success, or -1 if HarfBuzz not available.
- Return type
int
- sdl2.sdlttf.TTF_SetScript(script)[source]
Sets the global script (e.g. Arabic) to use for rendering text.
Note
This function has been deprecated in favor of
TTF_SetFontScriptName()
and should not be used in new projects.Setting the script gives the text renderer extra information about how to best shape words and characters for a given language. This can produce better results when rendering with non-Latin languages and fonts.
The script value is passed to the underlying HarfBuzz library, meaning that it needs to be specified as a HarfBuzz script constant. To make this convenient, the
sdl2.sdlttf
module implements HarfBuzz’sHB_TAG()
macro for converting ISO 15924 character codes to HarfBuzz scripts:arabic_script = HB_TAG('A', 'r', 'a', 'b') TTF_SetScript(arabic_script)
If no script has been set, the TTF library defaults to the unknown (‘Zzzz’) script.
Note: Added in SDL_ttf 2.0.18
- Parameters
script (int) – An integer specifying the script style to use for text shaping.
- Returns
0 on success, or -1 if HarfBuzz not available.
- Return type
int
Data types
- class sdl2.sdlttf.TTF_Font[source]
The opaque data type for fonts opened using the TTF library.
This contains all data associated with a loaded font. Once you are done with a
TTF_Font
, it should be freed usingTTF_CloseFont()
.
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
Indicates normal (i.e. regular) rendering style.
- sdl2.sdlttf.TTF_STYLE_BOLD
Indicates bold rendering style. This is used in a bitmask along with other styles.
- sdl2.sdlttf.TTF_STYLE_ITALIC
Indicates italicized rendering style. This is used in a bitmask along with other styles.
- sdl2.sdlttf.TTF_STYLE_UNDERLINE
Indicates underlined rendering style. This is used in a bitmask along with other styles.
- sdl2.sdlttf.TTF_STYLE_STRIKETHROUGH
Indicates strikethrough rendering style. This is used in a bitmask along with other styles.
- sdl2.sdlttf.TTF_HINTING_NORMAL
Indicates normal font hinting. This corresponds to the default hinting algorithm, optimized for standard gray-level rendering.
- sdl2.sdlttf.TTF_HINTING_LIGHT
Indicates light font hinting. 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
Indicates monochrome font hinting. 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
Indicates disabled font hinting. No hinting is used, so the font may become very blurry or messy at smaller sizes.
- sdl2.sdlttf.TTF_HINTING_LIGHT_SUBPIXEL
Indicates light subpixel font hinting. This produces better results for small text sizes: glyph are rendered at subpixel positions, so they look blurrier but are uniformly positioned. This mode is slower than others since glyphs are rendered on the fly.
- sdl2.sdlttf.TTF_WRAPPED_ALIGN_LEFT
Indicates left-justified alignment for wrapped multi-line text.
- sdl2.sdlttf.TTF_WRAPPED_ALIGN_CENTER
Indicates centered alignment for wrapped multi-line text.
- sdl2.sdlttf.TTF_WRAPPED_ALIGN_RIGHT
Indicates right-justified alignment for wrapped multi-line text.
- sdl2.sdlttf.TTF_DIRECTION_LTR
Indicates left-to-right text rendering.
- sdl2.sdlttf.TTF_DIRECTION_RTL
Indicates right-to-left text rendering.
- sdl2.sdlttf.TTF_DIRECTION_TTB
Indicates top-to-bottom text rendering.
- sdl2.sdlttf.TTF_DIRECTION_BTT
Indicates bottom-to-top text rendering.
HarfBuzz functions and constants
As of version 2.0.18, SDL2_ttf makes use of the HarfBuzz library for advanced text rendering and shaping unless explicitly compiled without it. As a consequence, some specific SDL2_ttf functions require HarfBuzz constants and macros for input.
To make these easier to use, the sdlttf
module defines and implements the
constants and macro functions necessary to make full use of the SDL2_ttf
library.
Note
In version 2.20.0, SDL2_ttf added new functions for configuring
HarfBuzz settings that avoid the need for these macros and constants
entirely. For new projects, please use those functions
(TTF_SetFontDirection
and TTF_SetFontScriptName
) instead.
- sdl2.sdlttf.HB_TAG(c1, c2, c3, c4)[source]
Converts a 4-character ISO 15924 code into a HarfBuzz script constant.
A full list of possible 4-character script codes can be found here: https://unicode.org/iso15924/iso15924-codes.html
- Parameters
c1 (str) – The first character of the code.
c2 (str) – The second character of the code.
c3 (str) – The third character of the code.
c4 (str) – The fourth character of the code.
- Returns
The HarfBuzz contstant corresponding to the given script.
- Return type
int
- sdl2.sdlttf.HB_DIRECTION_LTR
A constant indicating left-to-right text rendering.
- sdl2.sdlttf.HB_DIRECTION_RTL
A constant indicating right-to-left text rendering.
- sdl2.sdlttf.HB_DIRECTION_TTB
A constant indicating top-to-bottom text rendering.
- sdl2.sdlttf.HB_DIRECTION_BTT
A constant indicating bottom-to-top text rendering.