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_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 for TTF_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 call TTF_Quit().

Returns

The number of times TTF_Init() has been called without a corresponding TTF_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)

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.

  • index (int) – The index (from 0 to 15) of the font face to open. For

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 the src has been freed, performing any addotinoal operations with the returned TTF_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_CloseFont(font)[source]

Closes and frees the memory associated with a given font.

This function should be called on a font when you are done with it. A TTF_Font cannot be used after it has been closed.

Parameters

font (TTF_Font) – The font to close.

Font attribute 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_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

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_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

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_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

sdl2.sdlttf.TTF_FontFaceFamilyName(font)[source]

Gets the current family name (e.g. Helvetica) from a given font.

Parameters

font (TTF_Font) – The font object for which the family name should be retrieved.

Returns

The family name of the given font, or None if not available.

Return type

bytes

sdl2.sdlttf.TTF_FontFaceStyleName(font)[source]

Gets the current style name (e.g. Bold) from a given font.

Parameters

font (TTF_Font) – The font object for which the style name should be retrieved.

Returns

The style name of the given font, or None if not available.

Return type

bytes

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_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_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.

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

Text rendering functions

Size calculation functions

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() and TTF_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 palettized SDL_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 by TTF_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 or UNICODE_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 their TTF_RenderUNICODE counterparts. In addition to having a much friendlier Python API, SDL_ttf uses the TTF_RenderUTF8 functions internally for all the TTF_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)

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 palettized SDL_Surface with a solid background color and antialiasing. This is the second-fastest of the text rendering types, being slightly faster than TTF_RenderText_Blended() but slower than TTF_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 with TTF_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, and TTF_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, and TTF_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)

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 ARGB SDL_Surface with antialiasing and background transparency. This is the highest quality (and slowest) of all TTF rendering types.

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.

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, and TTF_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, and TTF_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_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)

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 using TTF_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

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.