Header file for SDL_ttf library. More...

Classes
struct	SDL::TtfInitFlag
	Flag to init TTF. More...

struct	SDL::FontBase
	The internal structure containing font information. More...

struct	SDL::FontRef
	Handle to a non owned font. More...

struct	SDL::Font
	Handle to an owned font. More...

struct	SDL::TextEngineBase
	A text engine used to create text objects. More...

struct	SDL::TextEngineRef
	Handle to a non owned textEngine. More...

struct	SDL::TextEngine
	Handle to an owned textEngine. More...

struct	SDL::TextBase
	Text created with TextBase.TextBase() More...

struct	SDL::TextRef
	Handle to a non owned text. More...

struct	SDL::Text
	Handle to an owned text. More...

class	SDL::SubStringIterator
	Iterator for substrings. More...

Macros
#define	SDL_TTF_VERSION
	This is the version number macro for the current SDL_ttf version.

#define	SDL_TTF_VERSION_ATLEAST(X, Y, Z)
	This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z.

#define	SDL_FONT_WEIGHT_THIN TTF_FONT_WEIGHT_THIN
	Thin (100) named font weight value.

#define	SDL_FONT_WEIGHT_EXTRA_LIGHT TTF_FONT_WEIGHT_EXTRA_LIGHT
	ExtraLight (200) named font weight value.

#define	SDL_FONT_WEIGHT_LIGHT TTF_FONT_WEIGHT_LIGHT
	Light (300) named font weight value.

#define	SDL_FONT_WEIGHT_NORMAL TTF_FONT_WEIGHT_NORMAL
	Normal (400) named font weight value.

#define	SDL_FONT_WEIGHT_MEDIUM TTF_FONT_WEIGHT_MEDIUM
	Medium (500) named font weight value.

#define	SDL_FONT_WEIGHT_SEMI_BOLD TTF_FONT_WEIGHT_SEMI_BOLD
	SemiBold (600) named font weight value.

#define	SDL_FONT_WEIGHT_BOLD TTF_FONT_WEIGHT_BOLD
	Bold (700) named font weight value.

#define	SDL_FONT_WEIGHT_EXTRA_BOLD TTF_FONT_WEIGHT_EXTRA_BOLD
	ExtraBold (800) named font weight value.

#define	SDL_FONT_WEIGHT_BLACK TTF_FONT_WEIGHT_BLACK
	Black (900) named font weight value.

#define	SDL_FONT_WEIGHT_EXTRA_BLACK TTF_FONT_WEIGHT_EXTRA_BLACK
	ExtraBlack (950) named font weight value.

Typedefs
using	SDL::TextData = TTF_TextData
	Internal data for TTF_Text.

using	SDL::GPUAtlasDrawSequence = TTF_GPUAtlasDrawSequence
	Draw sequence returned by TextBase.GetGPUDrawData.

using	SDL::SubString = TTF_SubString
	The representation of a substring within text.

Functions
int	SDL::TTF_Version ()
	This function gets the version of the dynamically linked SDL_ttf library.

void	SDL::GetFreeTypeVersion (int major, int minor, int *patch)
	Query the version of the FreeType library in use.

void	SDL::GetHarfBuzzVersion (int major, int minor, int *patch)
	Query the version of the HarfBuzz library in use.

void	SDL::InitSubSystem (TtfInitFlag _)
	Initialize SDL_ttf.

Uint32	SDL::StringToTag (StringParam string)
	Convert from a 4 character string to a 32-bit tag.

void	SDL::TagToString (Uint32 tag, char *string, size_t size)
	Convert from a 32-bit tag to a 4 character string.

TextEngine	SDL::CreateSurfaceTextEngine ()
	Create a text engine for drawing text on SDL surfaces.

TextEngine	SDL::CreateRendererTextEngine (RendererBase &renderer)
	Create a text engine for drawing text on an SDL renderer.

TextEngine	SDL::CreateRendererTextEngineWithProperties (PropertiesBase &props)
	Create a text engine for drawing text on an SDL renderer, with the specified properties.

TextEngine	SDL::CreateGPUTextEngine (SDL_GPUDevice *device)
	Create a text engine for drawing text with the SDL GPU API.

TextEngine	SDL::CreateGPUTextEngineWithProperties (PropertiesBase &props)
	Create a text engine for drawing text with the SDL GPU API, with the specified properties.

void	SDL::QuitSubSystem (TtfInitFlag _)
	Deinitialize SDL_ttf.

int	SDL::WasInit (TtfInitFlag _)
	Check if SDL_ttf is initialized.

Font	SDL::FontBase::Copy () const
	Create a copy of an existing font.

Variables
SDL::TtfInitFlag	SDL::INIT_TTF
	Flag to init TTF support.

Font Style Flags
using	SDL::FontStyleFlags = Uint32
	Font style flags for FontBase.

constexpr FontStyleFlags	SDL::STYLE_NORMAL = TTF_STYLE_NORMAL
	No special style.

constexpr FontStyleFlags	SDL::STYLE_BOLD = TTF_STYLE_BOLD
	Bold style.

constexpr FontStyleFlags	SDL::STYLE_ITALIC = TTF_STYLE_ITALIC
	Italic style.

constexpr FontStyleFlags	SDL::STYLE_UNDERLINE
	Underlined text.

constexpr FontStyleFlags	SDL::STYLE_STRIKETHROUGH
	Strikethrough text.

Hinting Flags
using	SDL::HintingFlags = TTF_HintingFlags
	Hinting flags for TTF (TrueType Fonts)

constexpr HintingFlags	SDL::HINTING_INVALID = TTF_HINTING_INVALID
	INVALID.

constexpr HintingFlags	SDL::HINTING_NORMAL
	Normal hinting applies standard grid-fitting.

constexpr HintingFlags	SDL::HINTING_LIGHT = TTF_HINTING_LIGHT
	Light hinting applies subtle adjustments to improve rendering.

constexpr HintingFlags	SDL::HINTING_MONO = TTF_HINTING_MONO
	Monochrome hinting adjusts the font for better rendering at lower resolutions.

constexpr HintingFlags	SDL::HINTING_NONE = TTF_HINTING_NONE
	No hinting, the font is rendered without any grid-fitting.

constexpr HintingFlags	SDL::HINTING_LIGHT_SUBPIXEL = TTF_HINTING_LIGHT_SUBPIXEL
	Light hinting with subpixel rendering for more precise font edges.

HorizontalAlignments
using	SDL::HorizontalAlignment = TTF_HorizontalAlignment
	The horizontal alignment used when rendering wrapped text.

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_INVALID
	INVALID.

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_LEFT
	LEFT.

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_CENTER
	CENTER.

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_RIGHT
	RIGHT.

Direction Flags
using	SDL::Direction = TTF_Direction
	Direction flags.

constexpr Direction	SDL::DIRECTION_INVALID = TTF_DIRECTION_INVALID
	INVALID.

constexpr Direction	SDL::DIRECTION_LTR = TTF_DIRECTION_LTR
	Left to Right.

constexpr Direction	SDL::DIRECTION_RTL = TTF_DIRECTION_RTL
	Right to Left.

constexpr Direction	SDL::DIRECTION_TTB = TTF_DIRECTION_TTB
	Top to Bottom.

constexpr Direction	SDL::DIRECTION_BTT = TTF_DIRECTION_BTT
	Bottom to Top.

Image types
using	SDL::ImageType = TTF_ImageType
	The type of data in a glyph image.

constexpr ImageType	SDL::IMAGE_INVALID = TTF_IMAGE_INVALID
	INVALID.

constexpr ImageType	SDL::IMAGE_ALPHA
	The color channels are white.

constexpr ImageType	SDL::IMAGE_COLOR
	The color channels have image data.

constexpr ImageType	SDL::IMAGE_SDF = TTF_IMAGE_SDF
	The alpha channel has signed distance field information.

Flags for SubString
using	SDL::SubStringFlags = Uint32
	Flags for SubString.

constexpr SubStringFlags	SDL::SUBSTRING_DIRECTION_MASK
	The mask for the flow direction for this substring.

constexpr SubStringFlags	SDL::SUBSTRING_TEXT_START
	This substring contains the beginning of the text.

constexpr SubStringFlags	SDL::SUBSTRING_LINE_START = TTF_SUBSTRING_LINE_START
	This substring contains the beginning of line `line_index`

constexpr SubStringFlags	SDL::SUBSTRING_LINE_END = TTF_SUBSTRING_LINE_END
	This substring contains the end of line `line_index`

constexpr SubStringFlags	SDL::SUBSTRING_TEXT_END
	This substring contains the end of the text.

GPUTextEngineWindings
using	SDL::GPUTextEngineWinding = TTF_GPUTextEngineWinding
	The winding order of the vertices returned by TextBase.GetGPUDrawData.

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_INVALID
	INVALID.

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_CLOCKWISE
	CLOCKWISE.

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_COUNTER_CLOCKWISE
	COUNTER_CLOCKWISE.

Detailed Description

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

Macro Definition Documentation

◆ SDL_TTF_VERSION

#define SDL_TTF_VERSION

Value:

SDL_VERSIONNUM( \

SDL_TTF_MAJOR_VERSION, SDL_TTF_MINOR_VERSION, SDL_TTF_MICRO_VERSION)

SDL_VERSIONNUM

#define SDL_VERSIONNUM(major, minor, patch)

This macro turns the version numbers into a numeric value.

Definition SDL3pp_version.h:59

◆ SDL_TTF_VERSION_ATLEAST

#define SDL_TTF_VERSION_ATLEAST	(	X,
		Y,
		Z
	)

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_MICRO_VERSION >= Z))

Typedef Documentation

◆ Direction

using SDL::Direction = typedef TTF_Direction

The values here are chosen to match hb_direction_t.

Since: This enum is available since SDL_ttf 3.0.0.

See also: FontBase.SetDirection

◆ FontStyleFlags

using SDL::FontStyleFlags = typedef Uint32

These are the flags which can be used to set the style of a font in SDL_ttf. A combination of these flags can be used with functions that set or query font style, such as FontBase.SetStyle or FontBase.GetStyle.

Since: This datatype is available since SDL_ttf 3.0.0.

See also: FontBase.SetStyle; FontBase.GetStyle

◆ GPUAtlasDrawSequence

using SDL::GPUAtlasDrawSequence = typedef TTF_GPUAtlasDrawSequence

Since: This struct is available since SDL_ttf 3.0.0.

See also: TextBase.GetGPUDrawData

◆ GPUTextEngineWinding

using SDL::GPUTextEngineWinding = typedef TTF_GPUTextEngineWinding

Since: This enum is available since SDL_ttf 3.0.0.

◆ HintingFlags

using SDL::HintingFlags = typedef TTF_HintingFlags

This enum specifies the level of hinting to be applied to the font rendering. The hinting level determines how much the font's outlines are adjusted for better alignment on the pixel grid.

Since: This enum is available since SDL_ttf 3.0.0.

See also: FontBase.SetHinting; FontBase.GetHinting

◆ HorizontalAlignment

using SDL::HorizontalAlignment = typedef TTF_HorizontalAlignment

Since: This enum is available since SDL_ttf 3.0.0.

◆ ImageType

using SDL::ImageType = typedef TTF_ImageType

Since: This enum is available since SDL_ttf 3.0.0.

◆ SubString

using SDL::SubString = typedef TTF_SubString

Since: This struct is available since SDL_ttf 3.0.0.

See also: TextBase.GetNextSubString; TextBase.GetPreviousSubString; TextBase.GetSubString; TextBase.GetSubStrings; TextBase.GetSubStringForLine; TextBase.GetSubStringForPoint; TextBase.GetSubStringsForRange

◆ SubStringFlags

using SDL::SubStringFlags = typedef Uint32

Since: This datatype is available since SDL_ttf 3.0.0.

See also: SubString

◆ TextData

using SDL::TextData = typedef TTF_TextData

Since: This struct is available since SDL_ttf 3.0.0.

Function Documentation

◆ Copy()

Font SDL::FontBase::Copy ( ) const

inline

The copy will be distinct from the original, but will share the font file and have the same size and style as the original.

Returns: a valid Font on success.

Exceptions

Error on failure.

Thread safety:: This function should be called on the thread that created the original font.

Since: This function is available since SDL_ttf 3.0.0.

◆ CreateGPUTextEngine()

TextEngine SDL::CreateGPUTextEngine ( SDL_GPUDevice * device )

inline

Parameters

device the SDL_GPUDevice to use for creating textures and drawing text.

Returns: a TextEngine object or nullptr on failure; call GetError() for more information.

Thread safety:: This function should be called on the thread that created the device.

Since: This function is available since SDL_ttf 3.0.0.

See also: CreateGPUTextEngineWithProperties; Text; TextBase.GetGPUDrawData

◆ CreateGPUTextEngineWithProperties()

TextEngine SDL::CreateGPUTextEngineWithProperties ( PropertiesBase & props )

inline

These are the supported properties:

prop::GpuTextEngine.DEVICE: the SDL_GPUDevice to use for creating textures and drawing text.
prop::GpuTextEngine.ATLAS_TEXTURE_SIZE: the size of the texture atlas

Parameters

props the properties to use.

Returns: a TextEngineBase object or nullptr on failure; call GetError() for more information.

Thread safety:: This function should be called on the thread that created the device.

Since: This function is available since SDL_ttf 3.0.0.

See also: CreateGPUTextEngine; Text; TextBase.GetGPUDrawData

◆ CreateRendererTextEngine()

TextEngine SDL::CreateRendererTextEngine ( RendererBase & renderer )

inline

Parameters

renderer the renderer to use for creating textures and drawing text.

Returns: a TextEngine object or nullptr on failure; call GetError() for more information.

Thread safety:: This function should be called on the thread that created the renderer.

Since: This function is available since SDL_ttf 3.0.0.

See also: TextBase.DrawRenderer; Text; CreateRendererTextEngineWithProperties

◆ CreateRendererTextEngineWithProperties()

TextEngine SDL::CreateRendererTextEngineWithProperties ( PropertiesBase & props )

inline

These are the supported properties:

prop::RendererTextEngine.RENDERER: the renderer to use for creating textures and drawing text
prop::RendererTextEngine.ATLAS_TEXTURE_SIZE: the size of the texture atlas

Parameters

props the properties to use.

Returns: a TextEngineBase object or nullptr on failure; call GetError() for more information.

Thread safety:: This function should be called on the thread that created the renderer.

Since: This function is available since SDL_ttf 3.0.0.

See also: CreateRendererTextEngine; Text; TextBase.DrawRenderer

◆ CreateSurfaceTextEngine()

TextEngine SDL::CreateSurfaceTextEngine ( )

inline

Returns: a TextEngine object or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

See also: Text; TextBase.DrawSurface

◆ GetFreeTypeVersion()

void SDL::GetFreeTypeVersion	(	int *	major,
		int *	minor,
		int *	patch
	)

inline

Either Init() or InitSubSystem() should with with INIT_TTF be called before calling this function.

Parameters

major	to be filled in with the major version number. Can be nullptr.
minor	to be filled in with the minor version number. Can be nullptr.
patch	to be filled in with the param version number. Can be nullptr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

See also: Init; InitSubSystem

◆ GetHarfBuzzVersion()

void SDL::GetHarfBuzzVersion	(	int *	major,
		int *	minor,
		int *	patch
	)

inline

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

Parameters

major	to be filled in with the major version number. Can be nullptr.
minor	to be filled in with the minor version number. Can be nullptr.
patch	to be filled in with the param version number. Can be nullptr.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

◆ InitSubSystem()

void SDL::InitSubSystem ( TtfInitFlag _ )

inline

You must successfully call this function before it is safe to call any other function in this library.

It is safe to call this more than once, and each successful InitSubSystem() call should be paired with a matching QuitSubSystem(TtfInitFlag) call.

Parameters

_	An INIT_TTF value;

Exceptions

Error on failure.

Since: This function is available since SDL_ttf 3.0.0.

See also: QuitSubSystem(TtfInitFlag)

◆ QuitSubSystem()

void SDL::QuitSubSystem ( TtfInitFlag _ )

inline

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 InitSubSystem(TtfInitFlag), 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.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

◆ StringToTag()

Uint32 SDL::StringToTag ( StringParam string )

inline

Parameters

string the 4 character string to convert.

Returns: the 32-bit representation of the string.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ TagToString()

void SDL::TagToString	(	Uint32	tag,
		char *	string,
		size_t	size
	)

inline

Parameters

tag	the 32-bit tag to convert.
string	a pointer filled in with the 4 character representation of the tag.
size	the size of the buffer pointed at by string, should be at least 4.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ TTF_Version()

int SDL::TTF_Version ( )

inline

Returns: SDL_ttf version.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

◆ WasInit()

int SDL::WasInit ( TtfInitFlag _ )

inline

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

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 QuitSubSystem(TtfInitFlag).

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL_ttf 3.0.0.

See also: InitSubSystem(TtfInitFlag); QuitSubSystem(TtfInitFlag)

TTF_SUBSTRING_TEXT_START

Classes

Macros

Typedefs

Functions

Variables

Font Style Flags

Hinting Flags

HorizontalAlignments

Direction Flags

Image types

Flags for SubString

GPUTextEngineWindings

Detailed Description

Macro Definition Documentation

◆ SDL_TTF_VERSION

◆ SDL_TTF_VERSION_ATLEAST

Typedef Documentation

◆ Direction

◆ FontStyleFlags

◆ GPUAtlasDrawSequence

◆ GPUTextEngineWinding

◆ HintingFlags

◆ HorizontalAlignment

◆ ImageType

◆ SubString

◆ SubStringFlags

◆ TextData

Function Documentation

◆ Copy()

◆ CreateGPUTextEngine()

◆ CreateGPUTextEngineWithProperties()

◆ CreateRendererTextEngine()

◆ CreateRendererTextEngineWithProperties()

◆ CreateSurfaceTextEngine()

◆ GetFreeTypeVersion()

◆ GetHarfBuzzVersion()

◆ InitSubSystem()

◆ QuitSubSystem()

◆ StringToTag()

◆ TagToString()

◆ TTF_Version()

◆ WasInit()

Variable Documentation

◆ GPU_TEXTENGINE_WINDING_CLOCKWISE

◆ GPU_TEXTENGINE_WINDING_COUNTER_CLOCKWISE

◆ GPU_TEXTENGINE_WINDING_INVALID

◆ HINTING_NORMAL

◆ HORIZONTAL_ALIGN_CENTER

◆ HORIZONTAL_ALIGN_INVALID

◆ HORIZONTAL_ALIGN_LEFT

◆ HORIZONTAL_ALIGN_RIGHT

◆ IMAGE_ALPHA

◆ IMAGE_COLOR

◆ STYLE_STRIKETHROUGH

◆ STYLE_UNDERLINE

◆ SUBSTRING_DIRECTION_MASK

◆ SUBSTRING_TEXT_END

◆ SUBSTRING_TEXT_START