My Project
Loading...
Searching...
No Matches
SDL_ttf.h File Reference
#include "SDL.h"
#include "begin_code.h"
#include "close_code.h"

Go to the source code of this file.

Macros

#define SDL_TTF_MAJOR_VERSION   2
 
#define SDL_TTF_MINOR_VERSION   20
 
#define SDL_TTF_PATCHLEVEL   2
 
#define SDL_TTF_VERSION(X)
 
#define TTF_MAJOR_VERSION   SDL_TTF_MAJOR_VERSION
 
#define TTF_MINOR_VERSION   SDL_TTF_MINOR_VERSION
 
#define TTF_PATCHLEVEL   SDL_TTF_PATCHLEVEL
 
#define TTF_VERSION(X)   SDL_TTF_VERSION(X)
 
#define SDL_TTF_COMPILEDVERSION    SDL_VERSIONNUM(SDL_TTF_MAJOR_VERSION, SDL_TTF_MINOR_VERSION, SDL_TTF_PATCHLEVEL)
 
#define SDL_TTF_VERSION_ATLEAST(X, Y, Z)
 
#define UNICODE_BOM_NATIVE   0xFEFF
 
#define UNICODE_BOM_SWAPPED   0xFFFE
 
#define TTF_STYLE_NORMAL   0x00
 
#define TTF_STYLE_BOLD   0x01
 
#define TTF_STYLE_ITALIC   0x02
 
#define TTF_STYLE_UNDERLINE   0x04
 
#define TTF_STYLE_STRIKETHROUGH   0x08
 
#define TTF_HINTING_NORMAL   0
 
#define TTF_HINTING_LIGHT   1
 
#define TTF_HINTING_MONO   2
 
#define TTF_HINTING_NONE   3
 
#define TTF_HINTING_LIGHT_SUBPIXEL   4
 
#define TTF_WRAPPED_ALIGN_LEFT   0
 
#define TTF_WRAPPED_ALIGN_CENTER   1
 
#define TTF_WRAPPED_ALIGN_RIGHT   2
 
#define TTF_RenderText(font, text, fg, bg)    TTF_RenderText_Shaded(font, text, fg, bg)
 
#define TTF_RenderUTF8(font, text, fg, bg)    TTF_RenderUTF8_Shaded(font, text, fg, bg)
 
#define TTF_RenderUNICODE(font, text, fg, bg)    TTF_RenderUNICODE_Shaded(font, text, fg, bg)
 
#define TTF_SetError   SDL_SetError
 
#define TTF_GetError   SDL_GetError
 

Typedefs

typedef struct _TTF_Font TTF_Font
 

Enumerations

enum  TTF_Direction { TTF_DIRECTION_LTR = 0 , TTF_DIRECTION_RTL , TTF_DIRECTION_TTB , TTF_DIRECTION_BTT }
 

Functions

DECLSPEC const SDL_version *SDLCALL TTF_Linked_Version (void)
 
DECLSPEC void SDLCALL TTF_GetFreeTypeVersion (int *major, int *minor, int *patch)
 
DECLSPEC void SDLCALL TTF_GetHarfBuzzVersion (int *major, int *minor, int *patch)
 
DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE (SDL_bool swapped)
 
DECLSPEC int SDLCALL TTF_Init (void)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFont (const char *file, int ptsize)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndex (const char *file, int ptsize, long index)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontRW (SDL_RWops *src, int freesrc, int ptsize)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexRW (SDL_RWops *src, int freesrc, int ptsize, long index)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontDPI (const char *file, int ptsize, unsigned int hdpi, unsigned int vdpi)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexDPI (const char *file, int ptsize, long index, unsigned int hdpi, unsigned int vdpi)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontDPIRW (SDL_RWops *src, int freesrc, int ptsize, unsigned int hdpi, unsigned int vdpi)
 
DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexDPIRW (SDL_RWops *src, int freesrc, int ptsize, long index, unsigned int hdpi, unsigned int vdpi)
 
DECLSPEC int SDLCALL TTF_SetFontSize (TTF_Font *font, int ptsize)
 
DECLSPEC int SDLCALL TTF_SetFontSizeDPI (TTF_Font *font, int ptsize, unsigned int hdpi, unsigned int vdpi)
 
DECLSPEC int SDLCALL TTF_GetFontStyle (const TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_SetFontStyle (TTF_Font *font, int style)
 
DECLSPEC int SDLCALL TTF_GetFontOutline (const TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_SetFontOutline (TTF_Font *font, int outline)
 
DECLSPEC int SDLCALL TTF_GetFontHinting (const TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_SetFontHinting (TTF_Font *font, int hinting)
 
DECLSPEC int SDLCALL TTF_GetFontWrappedAlign (const TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_SetFontWrappedAlign (TTF_Font *font, int align)
 
DECLSPEC int SDLCALL TTF_FontHeight (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_FontAscent (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_FontDescent (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_FontLineSkip (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_GetFontKerning (const TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_SetFontKerning (TTF_Font *font, int allowed)
 
DECLSPEC long SDLCALL TTF_FontFaces (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth (const TTF_Font *font)
 
DECLSPEC const char *SDLCALL TTF_FontFaceFamilyName (const TTF_Font *font)
 
DECLSPEC const char *SDLCALL TTF_FontFaceStyleName (const TTF_Font *font)
 
DECLSPEC int SDLCALL TTF_GlyphIsProvided (TTF_Font *font, Uint16 ch)
 
DECLSPEC int SDLCALL TTF_GlyphIsProvided32 (TTF_Font *font, Uint32 ch)
 
DECLSPEC int SDLCALL TTF_GlyphMetrics (TTF_Font *font, Uint16 ch, int *minx, int *maxx, int *miny, int *maxy, int *advance)
 
DECLSPEC int SDLCALL TTF_GlyphMetrics32 (TTF_Font *font, Uint32 ch, int *minx, int *maxx, int *miny, int *maxy, int *advance)
 
DECLSPEC int SDLCALL TTF_SizeText (TTF_Font *font, const char *text, int *w, int *h)
 
DECLSPEC int SDLCALL TTF_SizeUTF8 (TTF_Font *font, const char *text, int *w, int *h)
 
DECLSPEC int SDLCALL TTF_SizeUNICODE (TTF_Font *font, const Uint16 *text, int *w, int *h)
 
DECLSPEC int SDLCALL TTF_MeasureText (TTF_Font *font, const char *text, int measure_width, int *extent, int *count)
 
DECLSPEC int SDLCALL TTF_MeasureUTF8 (TTF_Font *font, const char *text, int measure_width, int *extent, int *count)
 
DECLSPEC int SDLCALL TTF_MeasureUNICODE (TTF_Font *font, const Uint16 *text, int measure_width, int *extent, int *count)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Solid (TTF_Font *font, const char *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Solid (TTF_Font *font, const char *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Solid (TTF_Font *font, const Uint16 *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Solid_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Solid_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Solid_Wrapped (TTF_Font *font, const Uint16 *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Solid (TTF_Font *font, Uint16 ch, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Solid (TTF_Font *font, Uint32 ch, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Shaded (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Shaded (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Shaded (TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Shaded_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Shaded_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Shaded_Wrapped (TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Shaded (TTF_Font *font, Uint16 ch, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Shaded (TTF_Font *font, Uint32 ch, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Blended (TTF_Font *font, const char *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Blended (TTF_Font *font, const char *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Blended (TTF_Font *font, const Uint16 *text, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Blended_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Blended_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Blended_Wrapped (TTF_Font *font, const Uint16 *text, SDL_Color fg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Blended (TTF_Font *font, Uint16 ch, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Blended (TTF_Font *font, Uint32 ch, SDL_Color fg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_LCD (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_LCD (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_LCD (TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_LCD_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_LCD_Wrapped (TTF_Font *font, const char *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_LCD_Wrapped (TTF_Font *font, const Uint16 *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_LCD (TTF_Font *font, Uint16 ch, SDL_Color fg, SDL_Color bg)
 
DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_LCD (TTF_Font *font, Uint32 ch, SDL_Color fg, SDL_Color bg)
 
DECLSPEC void SDLCALL TTF_CloseFont (TTF_Font *font)
 
DECLSPEC void SDLCALL TTF_Quit (void)
 
DECLSPEC int SDLCALL TTF_WasInit (void)
 
SDL_DEPRECATED DECLSPEC int TTF_GetFontKerningSize (TTF_Font *font, int prev_index, int index)
 
DECLSPEC int TTF_GetFontKerningSizeGlyphs (TTF_Font *font, Uint16 previous_ch, Uint16 ch)
 
DECLSPEC int TTF_GetFontKerningSizeGlyphs32 (TTF_Font *font, Uint32 previous_ch, Uint32 ch)
 
DECLSPEC int TTF_SetFontSDF (TTF_Font *font, SDL_bool on_off)
 
DECLSPEC SDL_bool TTF_GetFontSDF (const TTF_Font *font)
 
SDL_DEPRECATED DECLSPEC int SDLCALL TTF_SetDirection (int direction)
 
SDL_DEPRECATED DECLSPEC int SDLCALL TTF_SetScript (int script)
 
DECLSPEC int SDLCALL TTF_SetFontDirection (TTF_Font *font, TTF_Direction direction)
 
DECLSPEC int SDLCALL TTF_SetFontScriptName (TTF_Font *font, const char *script)
 

Detailed Description

Header file for SDL_ttf library

This library is a wrapper around the excellent FreeType 2.0 library, available at: https://www.freetype.org/

Note: In many places, SDL_ttf will say "glyph" when it means "code point." Unicode is hard, we learn as we go, and we apologize for adding to the confusion.

Macro Definition Documentation

◆ SDL_TTF_COMPILEDVERSION

#define SDL_TTF_COMPILEDVERSION    SDL_VERSIONNUM(SDL_TTF_MAJOR_VERSION, SDL_TTF_MINOR_VERSION, SDL_TTF_PATCHLEVEL)

This is the version number macro for the current SDL_ttf version.

In versions higher than 2.9.0, the minor version overflows into the thousands digit: for example, 2.23.0 is encoded as 4300. This macro will not be available in SDL 3.x or SDL_ttf 3.x.

Deprecated:
, use SDL_TTF_VERSION_ATLEAST or SDL_TTF_VERSION instead.

◆ SDL_TTF_MAJOR_VERSION

#define SDL_TTF_MAJOR_VERSION   2

Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL

◆ SDL_TTF_VERSION

#define SDL_TTF_VERSION (   X)
Value:
{ \
(X)->major = SDL_TTF_MAJOR_VERSION; \
(X)->minor = SDL_TTF_MINOR_VERSION; \
(X)->patch = SDL_TTF_PATCHLEVEL; \
}
#define SDL_TTF_MAJOR_VERSION
Definition: SDL_ttf.h:50

This macro can be used to fill a version structure with the compile-time version of the SDL_ttf library.

◆ SDL_TTF_VERSION_ATLEAST

#define SDL_TTF_VERSION_ATLEAST (   X,
  Y,
 
)
Value:
((SDL_TTF_MAJOR_VERSION >= X) && \
(SDL_TTF_MAJOR_VERSION > X || SDL_TTF_MINOR_VERSION >= Y) && \
(SDL_TTF_MAJOR_VERSION > X || SDL_TTF_MINOR_VERSION > Y || SDL_TTF_PATCHLEVEL >= Z))

This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z.

◆ TTF_GetError

#define TTF_GetError   SDL_GetError

Get last SDL_ttf error

See also
TTF_SetError

◆ TTF_HINTING_NORMAL

#define TTF_HINTING_NORMAL   0

Hinting flags

◆ TTF_MAJOR_VERSION

#define TTF_MAJOR_VERSION   SDL_TTF_MAJOR_VERSION

Backwards compatibility

◆ TTF_SetError

#define TTF_SetError   SDL_SetError

Report SDL_ttf errors

See also
TTF_GetError

◆ TTF_STYLE_NORMAL

#define TTF_STYLE_NORMAL   0x00

Font style flags

◆ TTF_WRAPPED_ALIGN_LEFT

#define TTF_WRAPPED_ALIGN_LEFT   0

Special layout option for rendering wrapped text

◆ UNICODE_BOM_NATIVE

#define UNICODE_BOM_NATIVE   0xFEFF

ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark)

Typedef Documentation

◆ TTF_Font

typedef struct _TTF_Font TTF_Font

The internal structure containing font information. Opaque data!

Enumeration Type Documentation

◆ TTF_Direction

Direction flags

See also
TTF_SetFontDirection

Function Documentation

◆ TTF_ByteSwappedUNICODE()

DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE ( SDL_bool  swapped)

Tell SDL_ttf whether UNICODE text is generally byteswapped.

A UNICODE BOM character in a string will override this setting for the remainder of that string.

Parameters
swappedboolean to indicate whether text is byteswapped
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_CloseFont()

DECLSPEC void SDLCALL TTF_CloseFont ( TTF_Font font)

Dispose of a previously-created font.

Call this when done with a font. This function will free any resources associated with it.

The font is not valid after being passed to this function. String pointers from functions that return information on this font, such as TTF_FontFaceFamilyName() and TTF_FontFaceStyleName(), are no longer valid after this call, as well.

Parameters
fontthe font to dispose of.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_OpenFontIndexDPIRW
TTF_OpenFontRW
TTF_OpenFontDPI
TTF_OpenFontDPIRW
TTF_OpenFontIndex
TTF_OpenFontIndexDPI
TTF_OpenFontIndexDPIRW
TTF_OpenFontIndexRW

◆ TTF_FontAscent()

DECLSPEC int SDLCALL TTF_FontAscent ( const TTF_Font font)

Query the offset from the baseline to the top of a font.

This is a positive value, relative to the baseline.

Parameters
fontthe font to query.
Returns
the font's ascent.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontDescent()

DECLSPEC int SDLCALL TTF_FontDescent ( const TTF_Font font)

Query the offset from the baseline to the bottom of a font.

This is a negative value, relative to the baseline.

Parameters
fontthe font to query.
Returns
the font's descent.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontFaceFamilyName()

DECLSPEC const char *SDLCALL TTF_FontFaceFamilyName ( const TTF_Font font)

Query a font's family name.

This string is dictated by the contents of the font file.

Note that the returned string is to internal storage, and should not be modifed or free'd by the caller. The string becomes invalid, with the rest of the font, when font is handed to TTF_CloseFont().

Parameters
fontthe font to query.
Returns
the font's family name.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontFaceIsFixedWidth()

DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth ( const TTF_Font font)

Query whether a font is fixed-width.

A "fixed-width" font means all glyphs are the same width across; a lowercase 'i' will be the same size across as a capital 'W', for example. This is common for terminals and text editors, and other apps that treat text as a grid. Most other things (WYSIWYG word processors, web pages, etc) are more likely to not be fixed-width in most cases.

Parameters
fontthe font to query.
Returns
non-zero if fixed-width, zero if not.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontFaces()

DECLSPEC long SDLCALL TTF_FontFaces ( const TTF_Font font)

Query the number of faces of a font.

Parameters
fontthe font to query.
Returns
the number of FreeType font faces.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontFaceStyleName()

DECLSPEC const char *SDLCALL TTF_FontFaceStyleName ( const TTF_Font font)

Query a font's style name.

This string is dictated by the contents of the font file.

Note that the returned string is to internal storage, and should not be modifed or free'd by the caller. The string becomes invalid, with the rest of the font, when font is handed to TTF_CloseFont().

Parameters
fontthe font to query.
Returns
the font's style name.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontHeight()

DECLSPEC int SDLCALL TTF_FontHeight ( const TTF_Font font)

Query the total height of a font.

This is usually equal to point size.

Parameters
fontthe font to query.
Returns
the font's height.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_FontLineSkip()

DECLSPEC int SDLCALL TTF_FontLineSkip ( const TTF_Font font)

Query the recommended spacing between lines of text for a font.

Parameters
fontthe font to query.
Returns
the font's recommended spacing.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_GetFontHinting()

DECLSPEC int SDLCALL TTF_GetFontHinting ( const TTF_Font font)

Query a font's current FreeType hinter setting.

The hinter setting is a single value:

  • TTF_HINTING_NORMAL
  • TTF_HINTING_LIGHT
  • TTF_HINTING_MONO
  • TTF_HINTING_NONE
  • TTF_HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 2.0.18 and later)
Parameters
fontthe font to query.
Returns
the font's current hinter value.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SetFontHinting

◆ TTF_GetFontKerning()

DECLSPEC int SDLCALL TTF_GetFontKerning ( const TTF_Font font)

Query whether or not kerning is allowed for a font.

Parameters
fontthe font to query.
Returns
non-zero if kerning is enabled, zero otherwise.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_GetFontKerningSize()

SDL_DEPRECATED DECLSPEC int TTF_GetFontKerningSize ( TTF_Font font,
int  prev_index,
int  index 
)

Query the kerning size of two glyphs indices.

Deprecated:
This function accidentally requires FreeType font indexes, not codepoints, which we don't expose through this API, so it could give wildly incorrect results, especially with non-ASCII values. Going forward, please use TTF_GetFontKerningSizeGlyphs() instead, which does what you probably expected this function to do.
Parameters
fontthe font to query.
prev_indexthe font index, NOT codepoint, of the previous character.
indexthe font index, NOT codepoint, of the current character.
Returns
The kerning size between the two specified characters, in pixels, or -1 on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GetFontKerningSizeGlyphs

◆ TTF_GetFontKerningSizeGlyphs()

DECLSPEC int TTF_GetFontKerningSizeGlyphs ( TTF_Font font,
Uint16  previous_ch,
Uint16  ch 
)

Query the kerning size of two 16-bit glyphs.

Note that this version of the function takes 16-bit character codes, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_GetFontKerningSizeGlyphs32() instead, which offers the same functionality but takes a 32-bit codepoints instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

Parameters
fontthe font to query.
previous_chthe previous character's code, 16 bits.
chthe current character's code, 16 bits.
Returns
The kerning size between the two specified characters, in pixels, or -1 on error.
Since
This function is available since SDL_ttf 2.0.14.
See also
TTF_GetFontKerningSizeGlyphs32

◆ TTF_GetFontKerningSizeGlyphs32()

DECLSPEC int TTF_GetFontKerningSizeGlyphs32 ( TTF_Font font,
Uint32  previous_ch,
Uint32  ch 
)

Query the kerning size of two 32-bit glyphs.

This is the same as TTF_GetFontKerningSizeGlyphs(), but takes 32-bit characters instead of 16-bit, and thus can manage a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

Parameters
fontthe font to query.
previous_chthe previous character's code, 32 bits.
chthe current character's code, 32 bits.
Returns
The kerning size between the two specified characters, in pixels, or -1 on error.
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_GetFontOutline()

DECLSPEC int SDLCALL TTF_GetFontOutline ( const TTF_Font font)

Query a font's current outline.

Parameters
fontthe font to query.
Returns
the font's current outline value.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SetFontOutline

◆ TTF_GetFontSDF()

DECLSPEC SDL_bool TTF_GetFontSDF ( const TTF_Font font)

Query whether Signed Distance Field rendering is enabled for a font.

Parameters
fontthe font to query
Returns
SDL_TRUE if enabled, SDL_FALSE otherwise.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_SetFontSDF

◆ TTF_GetFontStyle()

DECLSPEC int SDLCALL TTF_GetFontStyle ( const TTF_Font font)

Query a font's current style.

The font styles are a set of bit flags, OR'd together:

  • TTF_STYLE_NORMAL (is zero)
  • TTF_STYLE_BOLD
  • TTF_STYLE_ITALIC
  • TTF_STYLE_UNDERLINE
  • TTF_STYLE_STRIKETHROUGH
Parameters
fontthe font to query.
Returns
the current font style, as a set of bit flags.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SetFontStyle

◆ TTF_GetFontWrappedAlign()

DECLSPEC int SDLCALL TTF_GetFontWrappedAlign ( const TTF_Font font)

Query a font's current wrap alignment option.

The wrap alignment option can be one of the following:

  • TTF_WRAPPED_ALIGN_LEFT
  • TTF_WRAPPED_ALIGN_CENTER
  • TTF_WRAPPED_ALIGN_RIGHT
Parameters
fontthe font to query.
Returns
the font's current wrap alignment option.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_SetFontWrappedAlign

◆ TTF_GetFreeTypeVersion()

DECLSPEC void SDLCALL TTF_GetFreeTypeVersion ( int *  major,
int *  minor,
int *  patch 
)

Query the version of the FreeType library in use.

TTF_Init() should be called before calling this function.

Parameters
majorto be filled in with the major version number. Can be NULL.
minorto be filled in with the minor version number. Can be NULL.
patchto be filled in with the param version number. Can be NULL.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_Init

◆ TTF_GetHarfBuzzVersion()

DECLSPEC void SDLCALL TTF_GetHarfBuzzVersion ( int *  major,
int *  minor,
int *  patch 
)

Query the version of the HarfBuzz library in use.

If HarfBuzz is not available, the version reported is 0.0.0.

Parameters
majorto be filled in with the major version number. Can be NULL.
minorto be filled in with the minor version number. Can be NULL.
patchto be filled in with the param version number. Can be NULL.
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_GlyphIsProvided()

DECLSPEC int SDLCALL TTF_GlyphIsProvided ( TTF_Font font,
Uint16  ch 
)

Check whether a glyph is provided by the font for a 16-bit codepoint.

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_GlyphIsProvided32() instead, which offers the same functionality but takes a 32-bit codepoint instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

Parameters
fontthe font to query.
chthe character code to check.
Returns
non-zero if font provides a glyph for this character, zero if not.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GlyphIsProvided32

◆ TTF_GlyphIsProvided32()

DECLSPEC int SDLCALL TTF_GlyphIsProvided32 ( TTF_Font font,
Uint32  ch 
)

Check whether a glyph is provided by the font for a 32-bit codepoint.

This is the same as TTF_GlyphIsProvided(), but takes a 32-bit character instead of 16-bit, and thus can query a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

Parameters
fontthe font to query.
chthe character code to check.
Returns
non-zero if font provides a glyph for this character, zero if not.
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_GlyphMetrics()

DECLSPEC int SDLCALL TTF_GlyphMetrics ( TTF_Font font,
Uint16  ch,
int *  minx,
int *  maxx,
int *  miny,
int *  maxy,
int *  advance 
)

Query the metrics (dimensions) of a font's 16-bit glyph.

To understand what these metrics mean, here is a useful link:

https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_GlyphMetrics32() instead, which offers the same functionality but takes a 32-bit codepoint instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

Parameters
fontthe font to query.
chthe character code to check.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GlyphMetrics32

◆ TTF_GlyphMetrics32()

DECLSPEC int SDLCALL TTF_GlyphMetrics32 ( TTF_Font font,
Uint32  ch,
int *  minx,
int *  maxx,
int *  miny,
int *  maxy,
int *  advance 
)

Query the metrics (dimensions) of a font's 32-bit glyph.

To understand what these metrics mean, here is a useful link:

https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html

This is the same as TTF_GlyphMetrics(), but takes a 32-bit character instead of 16-bit, and thus can query a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

Parameters
fontthe font to query.
chthe character code to check.
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_Init()

DECLSPEC int SDLCALL TTF_Init ( void  )

Initialize SDL_ttf.

You must successfully call this function before it is safe to call any other function in this library, with one exception: a human-readable error message can be retrieved from TTF_GetError() if this function fails.

SDL must be initialized before calls to functions in this library, because this library uses utility functions from the SDL library.

It is safe to call this more than once; the library keeps a counter of init calls, and decrements it on each call to TTF_Quit, so you must pair your init and quit calls.

Returns
0 on success, -1 on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_Quit

◆ TTF_Linked_Version()

DECLSPEC const SDL_version *SDLCALL TTF_Linked_Version ( void  )

Query the version of SDL_ttf that the program is linked against.

This function gets the version of the dynamically linked SDL_ttf library. This is separate from the SDL_TTF_VERSION() macro, which tells you what version of the SDL_ttf headers you compiled against.

This returns static internal data; do not free or modify it!

Returns
a pointer to the version information.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_MeasureText()

DECLSPEC int SDLCALL TTF_MeasureText ( TTF_Font font,
const char *  text,
int  measure_width,
int *  extent,
int *  count 
)

Calculate how much of a Latin1 string will fit in a given width.

This reports the number of characters that can be rendered before reaching measure_width.

This does not need to render the string to do this calculation.

You almost certainly want TTF_MeasureUTF8() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

Parameters
fontthe font to query.
texttext to calculate, in Latin1 encoding.
measure_widthmaximum width, in pixels, available for the string.
counton return, filled with number of characters that can be rendered.
extenton return, filled with latest calculated width.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_MeasureText
TTF_MeasureUTF8
TTF_MeasureUNICODE

◆ TTF_MeasureUNICODE()

DECLSPEC int SDLCALL TTF_MeasureUNICODE ( TTF_Font font,
const Uint16 *  text,
int  measure_width,
int *  extent,
int *  count 
)

Calculate how much of a UCS-2 string will fit in a given width.

This reports the number of characters that can be rendered before reaching measure_width.

This does not need to render the string to do this calculation.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

Parameters
fontthe font to query.
texttext to calculate, in UCS-2 encoding.
measure_widthmaximum width, in pixels, available for the string.
counton return, filled with number of characters that can be rendered.
extenton return, filled with latest calculated width.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_MeasureText
TTF_MeasureUTF8
TTF_MeasureUNICODE

◆ TTF_MeasureUTF8()

DECLSPEC int SDLCALL TTF_MeasureUTF8 ( TTF_Font font,
const char *  text,
int  measure_width,
int *  extent,
int *  count 
)

Calculate how much of a UTF-8 string will fit in a given width.

This reports the number of characters that can be rendered before reaching measure_width.

This does not need to render the string to do this calculation.

Parameters
fontthe font to query.
texttext to calculate, in UTF-8 encoding.
measure_widthmaximum width, in pixels, available for the string.
counton return, filled with number of characters that can be rendered.
extenton return, filled with latest calculated width.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_MeasureText
TTF_MeasureUTF8
TTF_MeasureUNICODE

◆ TTF_OpenFont()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFont ( const char *  file,
int  ptsize 
)

Create a font from a file, using a specified point size.

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
filepath to font file.
ptsizepoint size to use for the newly-opened font.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_CloseFont

◆ TTF_OpenFontDPI()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontDPI ( const char *  file,
int  ptsize,
unsigned int  hdpi,
unsigned int  vdpi 
)

Create a font from a file, using target resolutions (in DPI).

DPI scaling only applies to scalable fonts (e.g. TrueType).

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
filepath to font file.
ptsizepoint size to use for the newly-opened font.
hdpithe target horizontal DPI.
vdpithe target vertical DPI.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_CloseFont

◆ TTF_OpenFontDPIRW()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontDPIRW ( SDL_RWops src,
int  freesrc,
int  ptsize,
unsigned int  hdpi,
unsigned int  vdpi 
)

Opens a font from an SDL_RWops with target resolutions (in DPI).

DPI scaling only applies to scalable fonts (e.g. TrueType).

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

If freesrc is non-zero, the RWops will be closed before returning, whether this function succeeds or not. SDL_ttf reads everything it needs from the RWops during this call in any case.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
srcan SDL_RWops to provide a font file's data.
freesrcnon-zero to close the RWops before returning, zero to leave it open.
ptsizepoint size to use for the newly-opened font.
hdpithe target horizontal DPI.
vdpithe target vertical DPI.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_CloseFont

◆ TTF_OpenFontIndex()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndex ( const char *  file,
int  ptsize,
long  index 
)

Create a font from a file, using a specified face index.

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

Some fonts have multiple "faces" included. The index specifies which face to use from the font file. Font files with only one face should specify zero for the index.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
filepath to font file.
ptsizepoint size to use for the newly-opened font.
indexindex of the face in the font file.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_CloseFont

◆ TTF_OpenFontIndexDPI()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexDPI ( const char *  file,
int  ptsize,
long  index,
unsigned int  hdpi,
unsigned int  vdpi 
)

Create a font from a file, using target resolutions (in DPI).

DPI scaling only applies to scalable fonts (e.g. TrueType).

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

Some fonts have multiple "faces" included. The index specifies which face to use from the font file. Font files with only one face should specify zero for the index.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
filepath to font file.
ptsizepoint size to use for the newly-opened font.
indexindex of the face in the font file.
hdpithe target horizontal DPI.
vdpithe target vertical DPI.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_CloseFont

◆ TTF_OpenFontIndexDPIRW()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexDPIRW ( SDL_RWops src,
int  freesrc,
int  ptsize,
long  index,
unsigned int  hdpi,
unsigned int  vdpi 
)

Opens a font from an SDL_RWops with target resolutions (in DPI).

DPI scaling only applies to scalable fonts (e.g. TrueType).

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

If freesrc is non-zero, the RWops will be closed before returning, whether this function succeeds or not. SDL_ttf reads everything it needs from the RWops during this call in any case.

Some fonts have multiple "faces" included. The index specifies which face to use from the font file. Font files with only one face should specify zero for the index.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
srcan SDL_RWops to provide a font file's data.
freesrcnon-zero to close the RWops before returning, zero to leave it open.
ptsizepoint size to use for the newly-opened font.
indexindex of the face in the font file.
hdpithe target horizontal DPI.
vdpithe target vertical DPI.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_CloseFont

◆ TTF_OpenFontIndexRW()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontIndexRW ( SDL_RWops src,
int  freesrc,
int  ptsize,
long  index 
)

Create a font from an SDL_RWops, using a specified face index.

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

If freesrc is non-zero, the RWops will be closed before returning, whether this function succeeds or not. SDL_ttf reads everything it needs from the RWops during this call in any case.

Some fonts have multiple "faces" included. The index specifies which face to use from the font file. Font files with only one face should specify zero for the index.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
srcan SDL_RWops to provide a font file's data.
freesrcnon-zero to close the RWops before returning, zero to leave it open.
ptsizepoint size to use for the newly-opened font.
indexindex of the face in the font file.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_CloseFont

◆ TTF_OpenFontRW()

DECLSPEC TTF_Font *SDLCALL TTF_OpenFontRW ( SDL_RWops src,
int  freesrc,
int  ptsize 
)

Create a font from an SDL_RWops, using a specified point size.

Some .fon fonts will have several sizes embedded in the file, so the point size becomes the index of choosing which size. If the value is too high, the last indexed size will be the default.

If freesrc is non-zero, the RWops will be closed before returning, whether this function succeeds or not. SDL_ttf reads everything it needs from the RWops during this call in any case.

When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.

Parameters
srcan SDL_RWops to provide a font file's data.
freesrcnon-zero to close the RWops before returning, zero to leave it open.
ptsizepoint size to use for the newly-opened font.
Returns
a valid TTF_Font, or NULL on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_CloseFont

◆ TTF_Quit()

DECLSPEC void SDLCALL TTF_Quit ( void  )

Deinitialize SDL_ttf.

You must call this when done with the library, to free internal resources. It is safe to call this when the library isn't initialized, as it will just return immediately.

Once you have as many quit calls as you have had successful calls to TTF_Init, the library will actually deinitialize.

Please note that this does not automatically close any fonts that are still open at the time of deinitialization, and it is possibly not safe to close them afterwards, as parts of the library will no longer be initialized to deal with it. A well-written program should call TTF_CloseFont() on any open fonts before calling this function!

Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_RenderGlyph32_Blended()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Blended ( TTF_Font font,
Uint32  ch,
SDL_Color  fg 
)

Render a single 32-bit glyph at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

This is the same as TTF_RenderGlyph_Blended(), but takes a 32-bit character instead of 16-bit, and thus can render a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

You can render at other quality levels with TTF_RenderGlyph32_Solid, TTF_RenderGlyph32_Shaded, and TTF_RenderGlyph32_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderGlyph32_Solid
TTF_RenderGlyph32_Shaded
TTF_RenderGlyph32_LCD

◆ TTF_RenderGlyph32_LCD()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_LCD ( TTF_Font font,
Uint32  ch,
SDL_Color  fg,
SDL_Color  bg 
)

Render a single 32-bit glyph at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

This is the same as TTF_RenderGlyph_LCD(), but takes a 32-bit character instead of 16-bit, and thus can render a larger range. Between the two, you should always use this function.

You can render at other quality levels with TTF_RenderGlyph32_Solid, TTF_RenderGlyph32_Shaded, and TTF_RenderGlyph32_Blended.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderGlyph32_Solid
TTF_RenderGlyph32_Shaded
TTF_RenderGlyph32_Blended

◆ TTF_RenderGlyph32_Shaded()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Shaded ( TTF_Font font,
Uint32  ch,
SDL_Color  fg,
SDL_Color  bg 
)

Render a single 32-bit glyph at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

This is the same as TTF_RenderGlyph_Shaded(), but takes a 32-bit character instead of 16-bit, and thus can render a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

You can render at other quality levels with TTF_RenderGlyph32_Solid, TTF_RenderGlyph32_Blended, and TTF_RenderGlyph32_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderGlyph32_Solid
TTF_RenderGlyph32_Blended
TTF_RenderGlyph32_LCD

◆ TTF_RenderGlyph32_Solid()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph32_Solid ( TTF_Font font,
Uint32  ch,
SDL_Color  fg 
)

Render a single 32-bit glyph at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

This is the same as TTF_RenderGlyph_Solid(), but takes a 32-bit character instead of 16-bit, and thus can render a larger range. If you are sure you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason not to use this function exclusively.

You can render at other quality levels with TTF_RenderGlyph32_Shaded, TTF_RenderGlyph32_Blended, and TTF_RenderGlyph32_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderGlyph32_Shaded
TTF_RenderGlyph32_Blended
TTF_RenderGlyph32_LCD

◆ TTF_RenderGlyph_Blended()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Blended ( TTF_Font font,
Uint16  ch,
SDL_Color  fg 
)

Render a single 16-bit glyph at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_RenderGlyph32_Blended() instead, which offers the same functionality but takes a 32-bit codepoint instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

You can render at other quality levels with TTF_RenderGlyph_Solid, TTF_RenderGlyph_Shaded, and TTF_RenderGlyph_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderGlyph32_Blended

◆ TTF_RenderGlyph_LCD()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_LCD ( TTF_Font font,
Uint16  ch,
SDL_Color  fg,
SDL_Color  bg 
)

Render a single 16-bit glyph at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_RenderGlyph32_LCD() instead, which offers the same functionality but takes a 32-bit codepoint instead.

This function only exists for consistency with the existing API at the time of its addition.

You can render at other quality levels with TTF_RenderGlyph_Solid, TTF_RenderGlyph_Shaded, and TTF_RenderGlyph_Blended.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderGlyph32_LCD

◆ TTF_RenderGlyph_Shaded()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Shaded ( TTF_Font font,
Uint16  ch,
SDL_Color  fg,
SDL_Color  bg 
)

Render a single 16-bit glyph at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_RenderGlyph32_Shaded() instead, which offers the same functionality but takes a 32-bit codepoint instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

You can render at other quality levels with TTF_RenderGlyph_Solid, TTF_RenderGlyph_Blended, and TTF_RenderGlyph_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderGlyph32_Shaded

◆ TTF_RenderGlyph_Solid()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderGlyph_Solid ( TTF_Font font,
Uint16  ch,
SDL_Color  fg 
)

Render a single 16-bit glyph at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

The glyph is rendered without any padding or centering in the X direction, and aligned normally in the Y direction.

Note that this version of the function takes a 16-bit character code, which covers the Basic Multilingual Plane, but is insufficient to cover the entire set of possible Unicode values, including emoji glyphs. You should use TTF_RenderGlyph32_Solid() instead, which offers the same functionality but takes a 32-bit codepoint instead.

The only reason to use this function is that it was available since the beginning of time, more or less.

You can render at other quality levels with TTF_RenderGlyph_Shaded, TTF_RenderGlyph_Blended, and TTF_RenderGlyph_LCD.

Parameters
fontthe font to render with.
chthe character to render.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderGlyph32_Solid

◆ TTF_RenderText_Blended()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Blended ( TTF_Font font,
const char *  text,
SDL_Color  fg 
)

Render Latin1 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderText_Blended_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Blended() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid, TTF_RenderText_Blended, and TTF_RenderText_LCD.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Shaded
TTF_RenderUNICODE_Shaded

◆ TTF_RenderText_Blended_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Blended_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped Latin1 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Blended_Wrapped() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid_Wrapped, TTF_RenderText_Shaded_Wrapped, and TTF_RenderText_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Blended_Wrapped
TTF_RenderUNICODE_Blended_Wrapped

◆ TTF_RenderText_LCD()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_LCD ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render Latin1 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderText_LCD_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You almost certainly want TTF_RenderUTF8_LCD() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid, TTF_RenderText_Shaded, and TTF_RenderText_Blended.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUTF8_LCD
TTF_RenderUNICODE_LCD

◆ TTF_RenderText_LCD_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_LCD_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped Latin1 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You almost certainly want TTF_RenderUTF8_LCD_Wrapped() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid_Wrapped, TTF_RenderText_Shaded_Wrapped, and TTF_RenderText_Blended_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUTF8_LCD_Wrapped
TTF_RenderUNICODE_LCD_Wrapped

◆ TTF_RenderText_Shaded()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Shaded ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render Latin1 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderText_Shaded_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Shaded() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid, TTF_RenderText_Blended, and TTF_RenderText_LCD.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Shaded
TTF_RenderUNICODE_Shaded

◆ TTF_RenderText_Shaded_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Shaded_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped Latin1 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Shaded_Wrapped() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Solid_Wrapped, TTF_RenderText_Blended_Wrapped, and TTF_RenderText_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Shaded_Wrapped
TTF_RenderUNICODE_Shaded_Wrapped

◆ TTF_RenderText_Solid()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Solid ( TTF_Font font,
const char *  text,
SDL_Color  fg 
)

Render Latin1 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderText_Solid_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Solid() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Shaded, TTF_RenderText_Blended, and TTF_RenderText_LCD.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Solid
TTF_RenderUNICODE_Solid

◆ TTF_RenderText_Solid_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderText_Solid_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped Latin1 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You almost certainly want TTF_RenderUTF8_Solid_Wrapped() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

You can render at other quality levels with TTF_RenderText_Shaded_Wrapped, TTF_RenderText_Blended_Wrapped, and TTF_RenderText_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in Latin1 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Solid_Wrapped
TTF_RenderUNICODE_Solid_Wrapped

◆ TTF_RenderUNICODE_Blended()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Blended ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg 
)

Render UCS-2 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUNICODE_Blended_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid, TTF_RenderUNICODE_Shaded, and TTF_RenderUNICODE_LCD.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Blended

◆ TTF_RenderUNICODE_Blended_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Blended_Wrapped ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped UCS-2 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Shaded_Wrapped, and TTF_RenderUNICODE_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Blended_Wrapped

◆ TTF_RenderUNICODE_LCD()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_LCD ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render UCS-2 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUNICODE_LCD_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid, TTF_RenderUNICODE_Shaded, and TTF_RenderUNICODE_Blended.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUTF8_LCD

◆ TTF_RenderUNICODE_LCD_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_LCD_Wrapped ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped UCS-2 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Shaded_Wrapped, and TTF_RenderUNICODE_Blended_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUTF8_LCD_Wrapped

◆ TTF_RenderUNICODE_Shaded()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Shaded ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render UCS-2 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUNICODE_Shaded_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid, TTF_RenderUNICODE_Blended, and TTF_RenderUNICODE_LCD.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Shaded

◆ TTF_RenderUNICODE_Shaded_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Shaded_Wrapped ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped UCS-2 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Solid_Wrapped, TTF_RenderUNICODE_Blended_Wrapped, and TTF_RenderUNICODE_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Shaded_Wrapped

◆ TTF_RenderUNICODE_Solid()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Solid ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg 
)

Render UCS-2 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUNICODE_Solid_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Shaded, TTF_RenderUNICODE_Blended, and TTF_RenderUNICODE_LCD.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Solid

◆ TTF_RenderUNICODE_Solid_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUNICODE_Solid_Wrapped ( TTF_Font font,
const Uint16 *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped UCS-2 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

You can render at other quality levels with TTF_RenderUNICODE_Shaded_Wrapped, TTF_RenderUNICODE_Blended_Wrapped, and TTF_RenderUNICODE_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UCS-2 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Solid_Wrapped

◆ TTF_RenderUTF8_Blended()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Blended ( TTF_Font font,
const char *  text,
SDL_Color  fg 
)

Render UTF-8 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUTF8_Blended_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid, TTF_RenderUTF8_Shaded, and TTF_RenderUTF8_LCD.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUNICODE_Blended

◆ TTF_RenderUTF8_Blended_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Blended_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped UTF-8 text at high quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, using alpha blending to dither the font with the given color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, TTF_RenderUTF8_Shaded_Wrapped, and TTF_RenderUTF8_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Solid_Wrapped
TTF_RenderUTF8_Shaded_Wrapped
TTF_RenderUTF8_LCD_Wrapped

◆ TTF_RenderUTF8_LCD()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_LCD ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render UTF-8 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUTF8_LCD_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid, TTF_RenderUTF8_Shaded, and TTF_RenderUTF8_Blended.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUNICODE_LCD

◆ TTF_RenderUTF8_LCD_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_LCD_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped UTF-8 text at LCD subpixel quality to a new ARGB surface.

This function will allocate a new 32-bit, ARGB surface, and render alpha-blended text using FreeType's LCD subpixel rendering. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, TTF_RenderUTF8_Shaded_Wrapped, and TTF_RenderUTF8_Blended_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
bgthe background color for the text.
Returns
a new 32-bit, ARGB surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_RenderUTF8_Solid_Wrapped
TTF_RenderUTF8_Shaded_Wrapped
TTF_RenderUTF8_Blended_Wrapped

◆ TTF_RenderUTF8_Shaded()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Shaded ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg 
)

Render UTF-8 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUTF8_Shaded_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid, TTF_RenderUTF8_Blended, and TTF_RenderUTF8_LCD.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUNICODE_Shaded

◆ TTF_RenderUTF8_Shaded_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Shaded_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
SDL_Color  bg,
Uint32  wrapLength 
)

Render word-wrapped UTF-8 text at high quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the specified background color, while other pixels have varying degrees of the foreground color. This function returns the new surface, or NULL if there was an error.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Solid_Wrapped, TTF_RenderUTF8_Blended_Wrapped, and TTF_RenderUTF8_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Solid_Wrapped
TTF_RenderUTF8_Blended_Wrapped
TTF_RenderUTF8_LCD_Wrapped

◆ TTF_RenderUTF8_Solid()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Solid ( TTF_Font font,
const char *  text,
SDL_Color  fg 
)

Render UTF-8 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

This will not word-wrap the string; you'll get a surface with a single line of text, as long as the string requires. You can use TTF_RenderUTF8_Solid_Wrapped() instead if you need to wrap the output to multiple lines.

This will not wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Shaded, TTF_RenderUTF8_Blended, and TTF_RenderUTF8_LCD.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_RenderUTF8_Shaded
TTF_RenderUTF8_Blended
TTF_RenderUTF8_LCD

◆ TTF_RenderUTF8_Solid_Wrapped()

DECLSPEC SDL_Surface *SDLCALL TTF_RenderUTF8_Solid_Wrapped ( TTF_Font font,
const char *  text,
SDL_Color  fg,
Uint32  wrapLength 
)

Render word-wrapped UTF-8 text at fast quality to a new 8-bit surface.

This function will allocate a new 8-bit, palettized surface. The surface's 0 pixel will be the colorkey, giving a transparent background. The 1 pixel will be set to the text color.

Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.

If wrapLength is 0, this function will only wrap on newline characters.

You can render at other quality levels with TTF_RenderUTF8_Shaded_Wrapped, TTF_RenderUTF8_Blended_Wrapped, and TTF_RenderUTF8_LCD_Wrapped.

Parameters
fontthe font to render with.
texttext to render, in UTF-8 encoding.
fgthe foreground color for the text.
Returns
a new 8-bit, palettized surface, or NULL if there was an error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_RenderUTF8_Shaded_Wrapped
TTF_RenderUTF8_Blended_Wrapped
TTF_RenderUTF8_LCD_Wrapped

◆ TTF_SetDirection()

SDL_DEPRECATED DECLSPEC int SDLCALL TTF_SetDirection ( int  direction)

Set a global direction to be used for text shaping.

Deprecated:
This function expects an hb_direction_t value, from HarfBuzz, cast to an int, and affects all fonts globally. Please use TTF_SetFontDirection() instead, which uses an enum supplied by SDL_ttf itself and operates on a per-font basis.

This is a global setting; fonts will favor a value set with TTF_SetFontDirection(), but if they have not had one explicitly set, they will use the value specified here.

The default value is HB_DIRECTION_LTR (left-to-right text flow).

Parameters
directionan hb_direction_t value.
Returns
0, or -1 if SDL_ttf is not compiled with HarfBuzz support.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_SetFontDirection

◆ TTF_SetFontDirection()

DECLSPEC int SDLCALL TTF_SetFontDirection ( TTF_Font font,
TTF_Direction  direction 
)

Set direction to be used for text shaping by a font.

Any value supplied here will override the global direction set with the deprecated TTF_SetDirection().

Possible direction values are:

  • TTF_DIRECTION_LTR (Left to Right)
  • TTF_DIRECTION_RTL (Right to Left)
  • TTF_DIRECTION_TTB (Top to Bottom)
  • TTF_DIRECTION_BTT (Bottom to Top)

If SDL_ttf was not built with HarfBuzz support, this function returns -1.

Parameters
fontthe font to specify a direction for.
directionthe new direction for text to flow.
Returns
0 on success, or -1 on error.
Since
This function is available since SDL_ttf 2.20.0.

◆ TTF_SetFontHinting()

DECLSPEC void SDLCALL TTF_SetFontHinting ( TTF_Font font,
int  hinting 
)

Set a font's current hinter setting.

Setting it clears already-generated glyphs, if any, from the cache.

The hinter setting is a single value:

  • TTF_HINTING_NORMAL
  • TTF_HINTING_LIGHT
  • TTF_HINTING_MONO
  • TTF_HINTING_NONE
  • TTF_HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 2.0.18 and later)
Parameters
fontthe font to set a new hinter setting on.
hintingthe new hinter setting.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GetFontHinting

◆ TTF_SetFontKerning()

DECLSPEC void SDLCALL TTF_SetFontKerning ( TTF_Font font,
int  allowed 
)

Set if kerning is allowed for a font.

Newly-opened fonts default to allowing kerning. This is generally a good policy unless you have a strong reason to disable it, as it tends to produce better rendering (with kerning disabled, some fonts might render the word kerning as something that looks like keming for example).

Parameters
fontthe font to set kerning on.
allowednon-zero to allow kerning, zero to disallow.
Since
This function is available since SDL_ttf 2.0.12.

◆ TTF_SetFontOutline()

DECLSPEC void SDLCALL TTF_SetFontOutline ( TTF_Font font,
int  outline 
)

Set a font's current outline.

Parameters
fontthe font to set a new outline on.
outlinepositive outline value, 0 to default.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GetFontOutline

◆ TTF_SetFontScriptName()

DECLSPEC int SDLCALL TTF_SetFontScriptName ( TTF_Font font,
const char *  script 
)

Set script to be used for text shaping by a font.

Any value supplied here will override the global script set with the deprecated TTF_SetScript().

The supplied script value must be a null-terminated string of exactly four characters.

If SDL_ttf was not built with HarfBuzz support, this function returns -1.

Parameters
fontthe font to specify a direction for.
scriptnull-terminated string of exactly 4 characters.
Returns
0 on success, or -1 on error.
Since
This function is available since SDL_ttf 2.20.0.

◆ TTF_SetFontSDF()

DECLSPEC int TTF_SetFontSDF ( TTF_Font font,
SDL_bool  on_off 
)

Enable Signed Distance Field rendering for a font.

This works with the Blended APIs. SDF is a technique that helps fonts look sharp even when scaling and rotating.

This clears already-generated glyphs, if any, from the cache.

Parameters
fontthe font to set SDF support on.
on_offSDL_TRUE to enable SDF, SDL_FALSE to disable.
Returns
0 on success, -1 on error.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_GetFontSDF

◆ TTF_SetFontSize()

DECLSPEC int SDLCALL TTF_SetFontSize ( TTF_Font font,
int  ptsize 
)

Set a font's size dynamically.

This clears already-generated glyphs, if any, from the cache.

Parameters
fontthe font to resize.
ptsizethe new point size.
Returns
0 if successful, -1 on error
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_SetFontSizeDPI()

DECLSPEC int SDLCALL TTF_SetFontSizeDPI ( TTF_Font font,
int  ptsize,
unsigned int  hdpi,
unsigned int  vdpi 
)

Set font size dynamically with target resolutions (in DPI).

This clears already-generated glyphs, if any, from the cache.

Parameters
fontthe font to resize.
ptsizethe new point size.
hdpithe target horizontal DPI.
vdpithe target vertical DPI.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.18.

◆ TTF_SetFontStyle()

DECLSPEC void SDLCALL TTF_SetFontStyle ( TTF_Font font,
int  style 
)

Set a font's current style.

Setting the style clears already-generated glyphs, if any, from the cache.

The font styles are a set of bit flags, OR'd together:

  • TTF_STYLE_NORMAL (is zero)
  • TTF_STYLE_BOLD
  • TTF_STYLE_ITALIC
  • TTF_STYLE_UNDERLINE
  • TTF_STYLE_STRIKETHROUGH
Parameters
fontthe font to set a new style on.
stylethe new style values to set, OR'd together.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_GetFontStyle

◆ TTF_SetFontWrappedAlign()

DECLSPEC void SDLCALL TTF_SetFontWrappedAlign ( TTF_Font font,
int  align 
)

Set a font's current wrap alignment option.

The wrap alignment option can be one of the following:

  • TTF_WRAPPED_ALIGN_LEFT
  • TTF_WRAPPED_ALIGN_CENTER
  • TTF_WRAPPED_ALIGN_RIGHT
Parameters
fontthe font to set a new wrap alignment option on.
alignthe new wrap alignment option.
Since
This function is available since SDL_ttf 2.20.0.
See also
TTF_GetFontWrappedAlign

◆ TTF_SetScript()

SDL_DEPRECATED DECLSPEC int SDLCALL TTF_SetScript ( int  script)

Set a global script to be used for text shaping.

Deprecated:
This function expects an hb_script_t value, from HarfBuzz, cast to an int, and affects all fonts globally. Please use TTF_SetFontScriptName() instead, which accepts a string that is converted to an equivalent int internally, and operates on a per-font basis.

This is a global setting; fonts will favor a value set with TTF_SetFontScriptName(), but if they have not had one explicitly set, they will use the value specified here.

The default value is HB_SCRIPT_UNKNOWN.

Returns
0, or -1 if SDL_ttf is not compiled with HarfBuzz support.
Since
This function is available since SDL_ttf 2.0.18.
See also
TTF_SetFontScriptName

◆ TTF_SizeText()

DECLSPEC int SDLCALL TTF_SizeText ( TTF_Font font,
const char *  text,
int *  w,
int *  h 
)

Calculate the dimensions of a rendered string of Latin1 text.

This will report the width and height, in pixels, of the space that the specified string will take to fully render.

This does not need to render the string to do this calculation.

You almost certainly want TTF_SizeUTF8() unless you're sure you have a 1-byte Latin1 encoding. US ASCII characters will work with either function, but most other Unicode characters packed into a const char * will need UTF-8.

Parameters
fontthe font to query.
texttext to calculate, in Latin1 encoding.
wwill be filled with width, in pixels, on return.
hwill be filled with height, in pixels, on return.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SizeUTF8
TTF_SizeUNICODE

◆ TTF_SizeUNICODE()

DECLSPEC int SDLCALL TTF_SizeUNICODE ( TTF_Font font,
const Uint16 *  text,
int *  w,
int *  h 
)

Calculate the dimensions of a rendered string of UCS-2 text.

This will report the width and height, in pixels, of the space that the specified string will take to fully render.

This does not need to render the string to do this calculation.

Please note that this function is named "Unicode" but currently expects UCS-2 encoding (16 bits per codepoint). This does not give you access to large Unicode values, such as emoji glyphs. These codepoints are accessible through the UTF-8 version of this function.

Parameters
fontthe font to query.
texttext to calculate, in UCS-2 encoding.
wwill be filled with width, in pixels, on return.
hwill be filled with height, in pixels, on return.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SizeUTF8

◆ TTF_SizeUTF8()

DECLSPEC int SDLCALL TTF_SizeUTF8 ( TTF_Font font,
const char *  text,
int *  w,
int *  h 
)

Calculate the dimensions of a rendered string of UTF-8 text.

This will report the width and height, in pixels, of the space that the specified string will take to fully render.

This does not need to render the string to do this calculation.

Parameters
fontthe font to query.
texttext to calculate, in Latin1 encoding.
wwill be filled with width, in pixels, on return.
hwill be filled with height, in pixels, on return.
Returns
0 if successful, -1 on error.
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_SizeUNICODE

◆ TTF_WasInit()

DECLSPEC int SDLCALL TTF_WasInit ( void  )

Check if SDL_ttf is initialized.

This reports the number of times the library has been initialized by a call to TTF_Init(), without a paired deinitialization request from TTF_Quit().

In short: if it's greater than zero, the library is currently initialized and ready to work. If zero, it is not initialized.

Despite the return value being a signed integer, this function should not return a negative number.

Returns
the current number of initialization calls, that need to eventually be paired with this many calls to TTF_Quit().
Since
This function is available since SDL_ttf 2.0.12.
See also
TTF_Init
TTF_Quit