Header file for SDL_ttf library. More...

Collaboration diagram for True type font support:

Classes
struct	SDL::FontParam
	Safely wrap Font for non owning parameters. More...

struct	SDL::TextEngineParam
	Safely wrap TextEngine for non owning parameters. More...

struct	SDL::TextParam
	Safely wrap Text for non owning parameters. More...

struct	SDL::TextConstParam
	Safely wrap Text for non owning const parameters. More...

class	SDL::Font
	The internal structure containing font information. More...

struct	SDL::FontRef
	Semi-safe reference for Font. More...

class	SDL::TextEngine
	A resource engine. More...

struct	SDL::SurfaceTextEngine
	A surface based text engine. More...

struct	SDL::RendererTextEngine
	A renderer based text engine. More...

struct	SDL::GPUTextEngine
	A GPU based text engine. More...

class	SDL::Text
	Text created with Text.Text() More...

struct	SDL::TextRef
	Semi-safe reference for 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. More...

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

Typedefs
using	SDL::FontRaw = TTF_Font *
	Alias to raw representation for Font.

using	SDL::TextEngineRaw = TTF_TextEngine *
	Alias to raw representation for TextEngine.

using	SDL::TextRaw = TTF_Text *
	Alias to raw representation for Text.

using	SDL::TextData = TTF_TextData
	Internal data for Text.

using	SDL::FontStyleFlags = Uint32
	Font style flags for Font. More...

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

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

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

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

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

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

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

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

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

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

Font	SDL::OpenFont (StringParam file, float ptsize)
	Create a font from a file, using a specified point size. More...

Font	SDL::OpenFont (IOStreamParam src, float ptsize, bool closeio=false)
	Create a font from an IOStream, using a specified point size. More...

Font	SDL::OpenFontWithProperties (PropertiesParam props)
	Create a font with the specified properties. More...

Font	SDL::CopyFont (FontParam existing_font)
	Create a copy of an existing font. More...

PropertiesRef	SDL::GetFontProperties (FontParam font)
	Get the properties associated with a font. More...

Uint32	SDL::GetFontGeneration (FontParam font)
	Get the font generation. More...

void	SDL::AddFallbackFont (FontParam font, FontParam fallback)
	Add a fallback font. More...

void	SDL::RemoveFallbackFont (FontParam font, FontParam fallback)
	Remove a fallback font. More...

void	SDL::ClearFallbackFonts (FontParam font)
	Remove all fallback fonts. More...

void	SDL::SetFontSize (FontParam font, float ptsize)
	Set a font's size dynamically. More...

void	SDL::SetFontSizeDPI (FontParam font, float ptsize, int hdpi, int vdpi)
	Set font size dynamically with target resolutions, in dots per inch. More...

float	SDL::GetFontSize (FontParam font)
	Get the size of a font. More...

void	SDL::GetFontDPI (FontParam font, int hdpi, int vdpi)
	Get font target resolutions, in dots per inch. More...

void	SDL::SetFontStyle (FontParam font, FontStyleFlags style)
	Set a font's current style. More...

FontStyleFlags	SDL::GetFontStyle (FontParam font)
	Query a font's current style. More...

void	SDL::SetFontOutline (FontParam font, int outline)
	Set a font's current outline. More...

int	SDL::GetFontOutline (FontParam font)
	Query a font's current outline. More...

void	SDL::SetFontHinting (FontParam font, HintingFlags hinting)
	Set a font's current hinter setting. More...

int	SDL::GetNumFontFaces (FontParam font)
	Query the number of faces of a font. More...

HintingFlags	SDL::GetFontHinting (FontParam font)
	Query a font's current FreeType hinter setting. More...

void	SDL::SetFontSDF (FontParam font, bool enabled)
	Enable Signed Distance Field rendering for a font. More...

bool	SDL::GetFontSDF (FontParam font)
	Query whether Signed Distance Field rendering is enabled for a font. More...

int	SDL::GetFontWeight (FontParam font)
	Query a font's weight, in terms of the lightness/heaviness of the strokes. More...

void	SDL::SetFontWrapAlignment (FontParam font, HorizontalAlignment align)
	Set a font's current wrap alignment option. More...

HorizontalAlignment	SDL::GetFontWrapAlignment (FontParam font)
	Query a font's current wrap alignment option. More...

int	SDL::GetFontHeight (FontParam font)
	Query the total height of a font. More...

int	SDL::GetFontAscent (FontParam font)
	Query the offset from the baseline to the top of a font. More...

int	SDL::GetFontDescent (FontParam font)
	Query the offset from the baseline to the bottom of a font. More...

void	SDL::SetFontLineSkip (FontParam font, int lineskip)
	Set the spacing between lines of text for a font. More...

int	SDL::GetFontLineSkip (FontParam font)
	Query the spacing between lines of text for a font. More...

void	SDL::SetFontKerning (FontParam font, bool enabled)
	Set if kerning is enabled for a font. More...

bool	SDL::GetFontKerning (FontParam font)
	Query whether or not kerning is enabled for a font. More...

bool	SDL::FontIsFixedWidth (FontParam font)
	Query whether a font is fixed-width. More...

bool	SDL::FontIsScalable (FontParam font)
	Query whether a font is scalable or not. More...

const char *	SDL::GetFontFamilyName (FontParam font)
	Query a font's family name. More...

const char *	SDL::GetFontStyleName (FontParam font)
	Query a font's style name. More...

void	SDL::SetFontDirection (FontParam font, Direction direction)
	Set the direction to be used for text shaping by a font. More...

Direction	SDL::GetFontDirection (FontParam font)
	Get the direction to be used for text shaping by a font. More...

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

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

void	SDL::SetFontScript (FontParam font, Uint32 script)
	Set the script to be used for text shaping by a font. More...

Uint32	SDL::GetFontScript (FontParam font)
	Get the script used for text shaping a font. More...

Uint32	SDL::GetGlyphScript (Uint32 ch)
	Get the script used by a 32-bit codepoint. More...

void	SDL::SetFontLanguage (FontParam font, StringParam language_bcp47)
	Set language to be used for text shaping by a font. More...

bool	SDL::FontHasGlyph (FontParam font, Uint32 ch)
	Check whether a glyph is provided by the font for a UNICODE codepoint. More...

Surface	SDL::GetGlyphImage (FontParam font, Uint32 ch, ImageType *image_type)
	Get the pixel image for a UNICODE codepoint. More...

Surface	SDL::GetGlyphImageForIndex (FontParam font, Uint32 glyph_index, ImageType *image_type)
	Get the pixel image for a character index. More...

void	SDL::GetGlyphMetrics (FontParam font, Uint32 ch, int minx, int maxx, int miny, int maxy, int *advance)
	Query the metrics (dimensions) of a font's glyph for a UNICODE codepoint. More...

int	SDL::GetGlyphKerning (FontParam font, Uint32 previous_ch, Uint32 ch)
	Query the kerning size between the glyphs of two UNICODE codepoints. More...

void	SDL::GetStringSize (FontParam font, std::string_view text, int w, int h)
	Calculate the dimensions of a rendered string of UTF-8 text. More...

void	SDL::GetStringSizeWrapped (FontParam font, std::string_view text, int wrap_width, int w, int h)
	Calculate the dimensions of a rendered string of UTF-8 text. More...

void	SDL::MeasureString (FontParam font, std::string_view text, int max_width, int measured_width, size_t measured_length)
	Calculate how much of a UTF-8 string will fit in a given width. More...

Surface	SDL::RenderText_Solid (FontParam font, std::string_view text, Color fg)
	Render UTF-8 text at fast quality to a new 8-bit surface. More...

Surface	SDL::RenderText_Solid_Wrapped (FontParam font, std::string_view text, Color fg, int wrapLength)
	Render word-wrapped UTF-8 text at fast quality to a new 8-bit surface. More...

Surface	SDL::RenderGlyph_Solid (FontParam font, Uint32 ch, ColorRaw fg)
	Render a single 32-bit glyph at fast quality to a new 8-bit surface. More...

Surface	SDL::RenderText_Shaded (FontParam font, std::string_view text, Color fg, Color bg)
	Render UTF-8 text at high quality to a new 8-bit surface. More...

Surface	SDL::RenderText_Shaded_Wrapped (FontParam font, std::string_view text, Color fg, Color bg, int wrap_width)
	Render word-wrapped UTF-8 text at high quality to a new 8-bit surface. More...

Surface	SDL::RenderGlyph_Shaded (FontParam font, Uint32 ch, ColorRaw fg, ColorRaw bg)
	Render a single UNICODE codepoint at high quality to a new 8-bit surface. More...

Surface	SDL::RenderText_Blended (FontParam font, std::string_view text, Color fg)
	Render UTF-8 text at high quality to a new ARGB surface. More...

Surface	SDL::RenderText_Blended_Wrapped (FontParam font, std::string_view text, Color fg, int wrap_width)
	Render word-wrapped UTF-8 text at high quality to a new ARGB surface. More...

Surface	SDL::RenderGlyph_Blended (FontParam font, Uint32 ch, ColorRaw fg)
	Render a single UNICODE codepoint at high quality to a new ARGB surface. More...

Surface	SDL::RenderText_LCD (FontParam font, std::string_view text, Color fg, Color bg)
	Render UTF-8 text at LCD subpixel quality to a new ARGB surface. More...

Surface	SDL::RenderText_LCD_Wrapped (FontParam font, std::string_view text, Color fg, Color bg, int wrap_width)
	Render word-wrapped UTF-8 text at LCD subpixel quality to a new ARGB surface. More...

Surface	SDL::RenderGlyph_LCD (FontParam font, Uint32 ch, ColorRaw fg, ColorRaw bg)
	Render a single UNICODE codepoint at LCD subpixel quality to a new ARGB surface. More...

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

void	SDL::DrawSurfaceText (TextConstParam text, Point p, SurfaceParam surface)
	Draw text to an SDL surface. More...

void	SDL::DestroySurfaceTextEngine (TextEngineRaw engine)
	Destroy a text engine created for drawing text on SDL surfaces. More...

RendererTextEngine	SDL::CreateRendererTextEngine (RendererParam renderer)
	Create a text engine for drawing text on an SDL renderer. More...

RendererTextEngine	SDL::CreateRendererTextEngineWithProperties (PropertiesParam props)
	Create a text engine for drawing text on an SDL renderer, with the specified properties. More...

void	SDL::DrawRendererText (TextConstParam text, FPoint p)
	Draw text to an SDL renderer. More...

void	SDL::DestroyRendererTextEngine (TextEngineRaw engine)
	Destroy a text engine created for drawing text on an SDL renderer. More...

GPUTextEngine	SDL::CreateGPUTextEngine (GPUDeviceParam device)
	Create a text engine for drawing text with the SDL GPU API. More...

GPUTextEngine	SDL::CreateGPUTextEngineWithProperties (PropertiesParam props)
	Create a text engine for drawing text with the SDL GPU API, with the specified properties. More...

GPUAtlasDrawSequence *	SDL::GetGPUTextDrawData (TextConstParam text)
	Get the geometry data needed for drawing the text. More...

void	SDL::DestroyGPUTextEngine (TextEngineRaw engine)
	Destroy a text engine created for drawing text with the SDL GPU API. More...

void	SDL::SetGPUTextEngineWinding (TextEngineParam engine, GPUTextEngineWinding winding)
	Sets the winding order of the vertices returned by Text.GetGPUDrawData for a particular GPU text engine. More...

GPUTextEngineWinding	SDL::GetGPUTextEngineWinding (TextEngineParam engine)
	Get the winding order of the vertices returned by Text.GetGPUDrawData for a particular GPU text engine. More...

Text	SDL::CreateText (TextEngineParam engine, FontParam font, std::string_view text)
	Create a text object from UTF-8 text and a text engine. More...

PropertiesRef	SDL::GetTextProperties (TextConstParam text)
	Get the properties associated with a text object. More...

void	SDL::SetTextEngine (TextParam text, TextEngineParam engine)
	Set the text engine used by a text object. More...

TextEngineParam	SDL::GetTextEngine (TextConstParam text)
	Get the text engine used by a text object. More...

bool	SDL::SetTextFont (TextParam text, FontParam font)
	Set the font used by a text object. More...

FontRef	SDL::GetTextFont (TextConstParam text)
	Get the font used by a text object. More...

void	SDL::SetTextDirection (TextParam text, Direction direction)
	Set the direction to be used for text shaping a text object. More...

Direction	SDL::GetTextDirection (TextConstParam text)
	Get the direction to be used for text shaping a text object. More...

void	SDL::SetTextScript (TextParam text, Uint32 script)
	Set the script to be used for text shaping a text object. More...

Uint32	SDL::GetTextScript (TextConstParam text)
	Get the script used for text shaping a text object. More...

void	SDL::SetTextColor (TextParam text, Color c)
	Set the color of a text object. More...

void	SDL::SetTextColorFloat (TextParam text, FColor c)
	Set the color of a text object. More...

void	SDL::GetTextColor (TextConstParam text, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
	Get the color of a text object. More...

Color	SDL::GetTextColor (TextParam text)
	Get the color of a text object. More...

void	SDL::GetTextColorFloat (TextConstParam text, float r, float g, float b, float a)
	Get the color of a text object. More...

FColor	SDL::GetTextColorFloat (TextParam text)
	Get the color of a text object. More...

bool	SDL::SetTextPosition (TextParam text, Point p)
	Set the position of a text object. More...

bool	SDL::GetTextPosition (TextConstParam text, int x, int y)
	Get the position of a text object. More...

Point	SDL::GetTextPosition (TextParam text)
	Get the position of a text object. More...

void	SDL::SetTextWrapWidth (TextParam text, int wrap_width)
	Set whether wrapping is enabled on a text object. More...

int	SDL::GetTextWrapWidth (TextConstParam text)
	Get whether wrapping is enabled on a text object. More...

void	SDL::SetTextWrapWhitespaceVisible (TextParam text, bool visible)
	Set whether whitespace should be visible when wrapping a text object. More...

bool	SDL::TextWrapWhitespaceVisible (TextConstParam text)
	Return whether whitespace is shown when wrapping a text object. More...

void	SDL::SetTextString (TextParam text, std::string_view string)
	Set the UTF-8 text used by a text object. More...

void	SDL::InsertTextString (TextParam text, int offset, std::string_view string)
	Insert UTF-8 text into a text object. More...

void	SDL::AppendTextString (TextParam text, std::string_view string)
	Append UTF-8 text to a text object. More...

void	SDL::DeleteTextString (TextParam text, int offset, int length)
	Delete UTF-8 text from a text object. More...

void	SDL::GetTextSize (TextConstParam text, int w, int h)
	Get the size of a text object. More...

Point	SDL::GetTextSize (TextParam text)
	Get the size of a text object. More...

void	SDL::GetTextSubString (TextConstParam text, int offset, SubString *substring)
	Get the substring of a text object that surrounds a text offset. More...

void	SDL::GetTextSubStringForLine (TextConstParam text, int line, SubString *substring)
	Get the substring of a text object that contains the given line. More...

OwnArray< SubString * >	SDL::GetTextSubStringsForRange (TextConstParam text, int offset, int length)
	Get the substrings of a text object that contain a range of text. More...

void	SDL::GetTextSubStringForPoint (TextConstParam text, Point p, SubString *substring)
	Get the portion of a text string that is closest to a point. More...

void	SDL::GetPreviousTextSubString (TextConstParam text, const SubString &substring, SubString *previous)
	Get the previous substring in a text object. More...

void	SDL::GetNextTextSubString (TextConstParam text, const SubString &substring, SubString *next)
	Get the next substring in a text object. More...

void	SDL::UpdateText (TextParam text)
	Update the layout of a text object. More...

void	SDL::DestroyText (TextRaw text)
	Destroy a text object created by a text engine. More...

void	SDL::CloseFont (FontRaw font)
	Dispose of a previously-created font. More...

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

PropertiesRef	SDL::Font::GetProperties ()
	Get the properties associated with a font. More...

Uint32	SDL::Font::GetGeneration () const
	Get the font generation. More...

void	SDL::Font::AddFallback (FontParam fallback)
	Add a fallback font. More...

void	SDL::Font::RemoveFallback (FontParam fallback)
	Remove a fallback font. More...

void	SDL::Font::ClearFallbacks ()
	Remove all fallback fonts. More...

void	SDL::Font::SetSize (float ptsize)
	Set a font's size dynamically. More...

void	SDL::Font::SetSizeDPI (float ptsize, int hdpi, int vdpi)
	Set font size dynamically with target resolutions, in dots per inch. More...

float	SDL::Font::GetSize () const
	Get the size of a font. More...

void	SDL::Font::GetDPI (int hdpi, int vdpi) const
	Get font target resolutions, in dots per inch. More...

void	SDL::Font::SetStyle (FontStyleFlags style)
	Set a font's current style. More...

FontStyleFlags	SDL::Font::GetStyle () const
	Query a font's current style. More...

void	SDL::Font::SetOutline (int outline)
	Set a font's current outline. More...

int	SDL::Font::GetOutline () const
	Query a font's current outline. More...

void	SDL::Font::SetHinting (HintingFlags hinting)
	Set a font's current hinter setting. More...

int	SDL::Font::GetNumFaces () const
	Query the number of faces of a font. More...

HintingFlags	SDL::Font::GetHinting () const
	Query a font's current FreeType hinter setting. More...

void	SDL::Font::SetSDF (bool enabled)
	Enable Signed Distance Field rendering for a font. More...

bool	SDL::Font::GetSDF () const
	Query whether Signed Distance Field rendering is enabled for a font. More...

int	SDL::Font::GetWeight () const
	Query a font's weight, in terms of the lightness/heaviness of the strokes. More...

void	SDL::Font::SetWrapAlignment (HorizontalAlignment align)
	Set a font's current wrap alignment option. More...

HorizontalAlignment	SDL::Font::GetWrapAlignment () const
	Query a font's current wrap alignment option. More...

int	SDL::Font::GetHeight () const
	Query the total height of a font. More...

int	SDL::Font::GetAscent () const
	Query the offset from the baseline to the top of a font. More...

int	SDL::Font::GetDescent () const
	Query the offset from the baseline to the bottom of a font. More...

void	SDL::Font::SetLineSkip (int lineskip)
	Set the spacing between lines of text for a font. More...

int	SDL::Font::GetLineSkip () const
	Query the spacing between lines of text for a font. More...

void	SDL::Font::SetKerning (bool enabled)
	Set if kerning is enabled for a font. More...

bool	SDL::Font::GetKerning () const
	Query whether or not kerning is enabled for a font. More...

bool	SDL::Font::IsFixedWidth () const
	Query whether a font is fixed-width. More...

bool	SDL::Font::IsScalable () const
	Query whether a font is scalable or not. More...

const char *	SDL::Font::GetFamilyName () const
	Query a font's family name. More...

const char *	SDL::Font::GetStyleName () const
	Query a font's style name. More...

void	SDL::Font::SetDirection (Direction direction)
	Set the direction to be used for text shaping by a font. More...

Direction	SDL::Font::GetDirection () const
	Get the direction to be used for text shaping by a font. More...

void	SDL::Font::SetScript (Uint32 script)
	Set the script to be used for text shaping by a font. More...

Uint32	SDL::Font::GetScript () const
	Get the script used for text shaping a font. More...

static Uint32	SDL::Font::GetGlyphScript (Uint32 ch)
	Get the script used by a 32-bit codepoint. More...

void	SDL::Font::SetLanguage (StringParam language_bcp47)
	Set language to be used for text shaping by a font. More...

bool	SDL::Font::HasGlyph (Uint32 ch) const
	Check whether a glyph is provided by the font for a UNICODE codepoint. More...

Surface	SDL::Font::GetGlyphImage (Uint32 ch, ImageType *image_type) const
	Get the pixel image for a UNICODE codepoint. More...

Surface	SDL::Font::GetGlyphImageForIndex (Uint32 glyph_index, ImageType *image_type) const
	Get the pixel image for a character index. More...

void	SDL::Font::GetGlyphMetrics (Uint32 ch, int minx, int maxx, int miny, int maxy, int *advance) const
	Query the metrics (dimensions) of a font's glyph for a UNICODE codepoint. More...

int	SDL::Font::GetGlyphKerning (Uint32 previous_ch, Uint32 ch) const
	Query the kerning size between the glyphs of two UNICODE codepoints. More...

void	SDL::Font::GetStringSize (std::string_view text, int w, int h) const
	Calculate the dimensions of a rendered string of UTF-8 text. More...

void	SDL::Font::GetStringSizeWrapped (std::string_view text, int wrap_width, int w, int h) const
	Calculate the dimensions of a rendered string of UTF-8 text. More...

void	SDL::Font::MeasureString (std::string_view text, int max_width, int measured_width, size_t measured_length) const
	Calculate how much of a UTF-8 string will fit in a given width. More...

Surface	SDL::Font::RenderText_Solid (std::string_view text, Color fg) const
	Render UTF-8 text at fast quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderText_Solid_Wrapped (std::string_view text, Color fg, int wrapLength) const
	Render word-wrapped UTF-8 text at fast quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderGlyph_Solid (Uint32 ch, ColorRaw fg) const
	Render a single 32-bit glyph at fast quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderText_Shaded (std::string_view text, Color fg, Color bg) const
	Render UTF-8 text at high quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderText_Shaded_Wrapped (std::string_view text, Color fg, Color bg, int wrap_width) const
	Render word-wrapped UTF-8 text at high quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderGlyph_Shaded (Uint32 ch, ColorRaw fg, ColorRaw bg) const
	Render a single UNICODE codepoint at high quality to a new 8-bit surface. More...

Surface	SDL::Font::RenderText_Blended (std::string_view text, Color fg) const
	Render UTF-8 text at high quality to a new ARGB surface. More...

Surface	SDL::Font::RenderText_Blended_Wrapped (std::string_view text, Color fg, int wrap_width) const
	Render word-wrapped UTF-8 text at high quality to a new ARGB surface. More...

Surface	SDL::Font::RenderGlyph_Blended (Uint32 ch, ColorRaw fg) const
	Render a single UNICODE codepoint at high quality to a new ARGB surface. More...

Surface	SDL::Font::RenderText_LCD (std::string_view text, Color fg, Color bg) const
	Render UTF-8 text at LCD subpixel quality to a new ARGB surface. More...

Surface	SDL::Font::RenderText_LCD_Wrapped (std::string_view text, Color fg, Color bg, int wrap_width) const
	Render word-wrapped UTF-8 text at LCD subpixel quality to a new ARGB surface. More...

Surface	SDL::Font::RenderGlyph_LCD (Uint32 ch, ColorRaw fg, ColorRaw bg) const
	Render a single UNICODE codepoint at LCD subpixel quality to a new ARGB surface. More...

void	SDL::Text::DrawSurface (Point p, SurfaceParam surface) const
	Draw text to an SDL surface. More...

void	SDL::SurfaceTextEngine::Destroy () final
	Destroy a text engine created for drawing text on SDL surfaces. More...

void	SDL::Text::DrawRenderer (FPoint p) const
	Draw text to an SDL renderer. More...

void	SDL::RendererTextEngine::Destroy () final
	Destroy a text engine created for drawing text on an SDL renderer. More...

GPUAtlasDrawSequence *	SDL::Text::GetGPUDrawData () const
	Get the geometry data needed for drawing the text. More...

void	SDL::GPUTextEngine::Destroy () final
	Destroy a text engine created for drawing text with the SDL GPU API. More...

void	SDL::GPUTextEngine::SetGPUWinding (GPUTextEngineWinding winding)
	Sets the winding order of the vertices returned by Text.GetGPUDrawData for a particular GPU text engine. More...

GPUTextEngineWinding	SDL::GPUTextEngine::GetGPUWinding () const
	Get the winding order of the vertices returned by Text.GetGPUDrawData for a particular GPU text engine. More...

Text	SDL::TextEngine::CreateText (FontParam font, std::string_view text)
	Create a text object from UTF-8 text and a text engine. More...

PropertiesRef	SDL::Text::GetProperties () const
	Get the properties associated with a text object. More...

void	SDL::Text::SetEngine (TextEngineParam engine)
	Set the text engine used by a text object. More...

TextEngineParam	SDL::Text::GetEngine () const
	Get the text engine used by a text object. More...

bool	SDL::Text::SetFont (FontParam font)
	Set the font used by a text object. More...

FontRef	SDL::Text::GetFont () const
	Get the font used by a text object. More...

void	SDL::Text::SetDirection (Direction direction)
	Set the direction to be used for text shaping a text object. More...

Direction	SDL::Text::GetDirection () const
	Get the direction to be used for text shaping a text object. More...

void	SDL::Text::SetScript (Uint32 script)
	Set the script to be used for text shaping a text object. More...

Uint32	SDL::Text::GetScript () const
	Get the script used for text shaping a text object. More...

void	SDL::Text::SetColor (Color c)
	Set the color of a text object. More...

void	SDL::Text::SetColorFloat (FColor c)
	Set the color of a text object. More...

void	SDL::Text::GetColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Get the color of a text object. More...

Color	SDL::Text::GetColor () const
	Get the color of a text object. More...

void	SDL::Text::GetColorFloat (float r, float g, float b, float a) const
	Get the color of a text object. More...

FColor	SDL::Text::GetColorFloat () const
	Get the color of a text object. More...

bool	SDL::Text::SetPosition (Point p)
	Set the position of a text object. More...

bool	SDL::Text::GetPosition (int x, int y) const
	Get the position of a text object. More...

Point	SDL::Text::GetPosition () const
	Get the position of a text object. More...

void	SDL::Text::SetWrapWidth (int wrap_width)
	Set whether wrapping is enabled on a text object. More...

int	SDL::Text::GetWrapWidth () const
	Get whether wrapping is enabled on a text object. More...

void	SDL::Text::SetWrapWhitespaceVisible (bool visible)
	Set whether whitespace should be visible when wrapping a text object. More...

bool	SDL::Text::IsWrapWhitespaceVisible () const
	Return whether whitespace is shown when wrapping a text object. More...

void	SDL::Text::SetString (std::string_view string)
	Set the UTF-8 text used by a text object. More...

void	SDL::Text::InsertString (int offset, std::string_view string)
	Insert UTF-8 text into a text object. More...

void	SDL::Text::AppendString (std::string_view string)
	Append UTF-8 text to a text object. More...

void	SDL::Text::DeleteString (int offset, int length)
	Delete UTF-8 text from a text object. More...

void	SDL::Text::GetSize (int w, int h) const
	Get the size of a text object. More...

Point	SDL::Text::GetSize () const
	Get the size of a text object. More...

void	SDL::Text::GetSubString (int offset, SubString *substring) const
	Get the substring of a text object that surrounds a text offset. More...

void	SDL::Text::GetSubStringForLine (int line, SubString *substring) const
	Get the substring of a text object that contains the given line. More...

OwnArray< SubString * >	SDL::Text::GetSubStringsForRange (int offset, int length=-1) const
	Get the substrings of a text object that contain a range of text. More...

void	SDL::Text::GetSubStringForPoint (Point p, SubString *substring) const
	Get the portion of a text string that is closest to a point. More...

void	SDL::Text::GetPreviousSubString (const SubString &substring, SubString *previous) const
	Get the previous substring in a text object. More...

void	SDL::Text::GetNextSubString (const SubString &substring, SubString *next) const
	Get the next substring in a text object. More...

void	SDL::Text::Update ()
	Update the layout of a text object. More...

void	SDL::Text::Destroy ()
	Destroy a text object created by a text engine. More...

void	SDL::Font::Close ()
	Dispose of a previously-created font. More...

Variables
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. More...

constexpr FontStyleFlags	SDL::STYLE_STRIKETHROUGH
	Strikethrough text. More...

constexpr HintingFlags	SDL::HINTING_INVALID = TTF_HINTING_INVALID
	INVALID.

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

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.

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_INVALID
	INVALID. More...

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_LEFT
	LEFT. More...

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_CENTER
	CENTER. More...

constexpr HorizontalAlignment	SDL::HORIZONTAL_ALIGN_RIGHT
	RIGHT. More...

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.

constexpr ImageType	SDL::IMAGE_INVALID = TTF_IMAGE_INVALID
	INVALID.

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

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

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

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

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

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

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_INVALID
	INVALID. More...

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_CLOCKWISE
	CLOCKWISE. More...

constexpr GPUTextEngineWinding	SDL::GPU_TEXTENGINE_WINDING_COUNTER_CLOCKWISE
	COUNTER_CLOCKWISE. More...

constexpr int	SDL::FONT_WEIGHT_THIN
	Thin (100) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_EXTRA_LIGHT
	ExtraLight (200) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_LIGHT
	Light (300) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_NORMAL
	Normal (400) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_MEDIUM
	Medium (500) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_SEMI_BOLD
	SemiBold (600) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_BOLD
	Bold (700) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_EXTRA_BOLD
	ExtraBold (800) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_BLACK
	Black (900) named font weight value. More...

constexpr int	SDL::FONT_WEIGHT_EXTRA_BLACK
	ExtraBlack (950) named font weight value. More...

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:57

◆ 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: Font.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 Font.SetStyle or Font.GetStyle.

Since: This datatype is available since SDL_ttf 3.0.0.

See also: Font.SetStyle; Font.GetStyle

◆ GPUAtlasDrawSequence

using SDL::GPUAtlasDrawSequence = typedef TTF_GPUAtlasDrawSequence

Since: This struct is available since SDL_ttf 3.0.0.

See also: Text.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: Font.SetHinting; Font.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: Text.GetNextSubString; Text.GetPreviousSubString; Text.GetSubString; Text.GetSubStringForLine; Text.GetSubStringForPoint; Text.GetSubStringsForRange

◆ SubStringFlags

using SDL::SubStringFlags = typedef Uint32

Since: This datatype is available since SDL_ttf 3.0.0.

See also: SubString

Function Documentation

◆ AddFallback()

void SDL::Font::AddFallback ( FontParam fallback )

inline

Add a font that will be used for glyphs that are not in the current font. The fallback font should have the same size and style as the current font.

If there are multiple fallback fonts, they are used in the order added.

This updates any Text objects using this font.

Parameters

fallback the font to add as a fallback.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.ClearFallbacks; Font.RemoveFallback

◆ AddFallbackFont()

void SDL::AddFallbackFont	(	FontParam	font,
		FontParam	fallback
	)

inline

Add a font that will be used for glyphs that are not in the current font. The fallback font should have the same size and style as the current font.

If there are multiple fallback fonts, they are used in the order added.

This updates any Text objects using this font.

Parameters

font	the font to modify.
fallback	the font to add as a fallback.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.ClearFallbacks; Font.RemoveFallback

◆ AppendString()

void SDL::Text::AppendString ( std::string_view string )

inline

This function may cause the internal text representation to be rebuilt.

Parameters

string the UTF-8 text to insert.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.DeleteString; Text.InsertString; Text.SetString

◆ AppendTextString()

void SDL::AppendTextString	(	TextParam	text,
		std::string_view	string
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
string	the UTF-8 text to insert.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.DeleteString; Text.InsertString; Text.SetString

◆ ClearFallbackFonts()

void SDL::ClearFallbackFonts ( FontParam font )

inline

This updates any Text objects using this font.

Parameters

font	the font to modify.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.AddFallback; Font.RemoveFallback

◆ ClearFallbacks()

void SDL::Font::ClearFallbacks ( )

inline

This updates any Text objects using this font.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.AddFallback; Font.RemoveFallback

◆ Close()

void SDL::Font::Close ( )

inline

Call this when done with a font. This function will free any resources associated with it. It is safe to call this function on nullptr, for example on the result of a failed call to Font.Font().

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

Thread safety:: This function should not be called while any other thread is using the font.

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.Font

◆ CloseFont()

void SDL::CloseFont ( FontRaw font )

inline

Call this when done with a font. This function will free any resources associated with it. It is safe to call this function on nullptr, for example on the result of a failed call to Font.Font().

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

Parameters

font	the font to dispose of.

Thread safety:: This function should not be called while any other thread is using the font.

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.Font; Font.Font

◆ Copy()

Font SDL::Font::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.

See also: Font.Close

◆ CopyFont()

Font SDL::CopyFont ( FontParam existing_font )

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.

When done with the returned Font, use Font.Close() to dispose of it.

Parameters

existing_font the font to copy.

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.

See also: Font.Close

◆ CreateGPUTextEngine()

GPUTextEngine SDL::CreateGPUTextEngine ( GPUDeviceParam device )

inline

Parameters

device the 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: GPUTextEngine.GPUTextEngine; GPUTextEngine.Destroy; Text.GetGPUDrawData

◆ CreateGPUTextEngineWithProperties()

GPUTextEngine SDL::CreateGPUTextEngineWithProperties ( PropertiesParam props )

inline

These are the supported properties:

prop::GpuTextEngine.DEVICE_POINTER: the GPUDevice to use for creating textures and drawing text.
prop::GpuTextEngine.ATLAS_TEXTURE_SIZE_NUMBER: the size of the texture atlas

Parameters

props the properties to use.

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: GPUTextEngine.GPUTextEngine; GPUTextEngine.Destroy; Text.GetGPUDrawData

◆ CreateRendererTextEngine()

RendererTextEngine SDL::CreateRendererTextEngine ( RendererParam 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: RendererTextEngine.Destroy; Text.DrawRenderer; RendererTextEngine.RendererTextEngine

◆ CreateRendererTextEngineWithProperties()

RendererTextEngine SDL::CreateRendererTextEngineWithProperties ( PropertiesParam props )

inline

These are the supported properties:

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

Parameters

props the properties to use.

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: RendererTextEngine.RendererTextEngine; RendererTextEngine.Destroy; Text.DrawRenderer

◆ CreateSurfaceTextEngine()

SurfaceTextEngine 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: SurfaceTextEngine.Destroy; Text.DrawSurface

◆ CreateText() [1/2]

Text SDL::TextEngine::CreateText	(	FontParam	font,
		std::string_view	text
	)

inline

          nullptr.

Parameters

font	the font to render with.
text	the text to use, in UTF-8 encoding.

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

Thread safety:: This function should be called on the thread that created the font and text engine.

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.Destroy

◆ CreateText() [2/2]

Text SDL::CreateText	(	TextEngineParam	engine,
		FontParam	font,
		std::string_view	text
	)

inline

Parameters

engine	the text engine to use when creating the text object, may be nullptr.
font	the font to render with.
text	the text to use, in UTF-8 encoding.

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

Thread safety:: This function should be called on the thread that created the font and text engine.

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.Destroy

◆ DeleteString()

void SDL::Text::DeleteString	(	int	offset,
		int	length
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

offset	the offset, in bytes, from the beginning of the string if >= 0, the offset from the end of the string if < 0. Note that this does not do UTF-8 validation, so you should only delete at UTF-8 sequence boundaries.
length	the length of text to delete, in bytes, or -1 for the remainder of the string.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.InsertString; Text.SetString

◆ DeleteTextString()

void SDL::DeleteTextString	(	TextParam	text,
		int	offset,
		int	length
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
offset	the offset, in bytes, from the beginning of the string if >= 0, the offset from the end of the string if < 0. Note that this does not do UTF-8 validation, so you should only delete at UTF-8 sequence boundaries.
length	the length of text to delete, in bytes, or -1 for the remainder of the string.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.InsertString; Text.SetString

◆ Destroy() [1/4]

void SDL::Text::Destroy ( )

inline

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.Text

◆ Destroy() [2/4]

void SDL::SurfaceTextEngine::Destroy ( )

inlinefinalvirtual

All text created by this engine should be destroyed before calling this function.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: SurfaceTextEngine.SurfaceTextEngine

Implements SDL::TextEngine.

◆ Destroy() [3/4]

void SDL::RendererTextEngine::Destroy ( )

inlinefinalvirtual

All text created by this engine should be destroyed before calling this function.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: RendererTextEngine.RendererTextEngine

Implements SDL::TextEngine.

◆ Destroy() [4/4]

void SDL::GPUTextEngine::Destroy ( )

inlinefinalvirtual

All text created by this engine should be destroyed before calling this function.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GPUTextEngine

Implements SDL::TextEngine.

◆ DestroyGPUTextEngine()

void SDL::DestroyGPUTextEngine ( TextEngineRaw engine )

inline

All text created by this engine should be destroyed before calling this function.

Parameters

engine a TextEngine object created with GPUTextEngine.GPUTextEngine().

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GPUTextEngine

◆ DestroyRendererTextEngine()

void SDL::DestroyRendererTextEngine ( TextEngineRaw engine )

inline

All text created by this engine should be destroyed before calling this function.

Parameters

engine a TextEngine object created with RendererTextEngine.RendererTextEngine().

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

Since: This function is available since SDL_ttf 3.0.0.

See also: RendererTextEngine.RendererTextEngine

◆ DestroySurfaceTextEngine()

void SDL::DestroySurfaceTextEngine ( TextEngineRaw engine )

inline

All text created by this engine should be destroyed before calling this function.

Parameters

engine a TextEngine object created with SurfaceTextEngine.SurfaceTextEngine().

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

Since: This function is available since SDL_ttf 3.0.0.

See also: SurfaceTextEngine.SurfaceTextEngine

◆ DestroyText()

void SDL::DestroyText ( TextRaw text )

inline

Parameters

text	the text to destroy.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: RendererTextEngine.RendererTextEngine

◆ DrawRenderer()

void SDL::Text::DrawRenderer ( FPoint p ) const

inline

text must have been created using a TextEngine from RendererTextEngine.RendererTextEngine(), and will draw using the renderer passed to that function.

Parameters

p	the x,y coordinates in pixels, positive from the top-left edge towards the bottom-right.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: RendererTextEngine.RendererTextEngine; Text.Text

◆ DrawRendererText()

void SDL::DrawRendererText	(	TextConstParam	text,
		FPoint	p
	)

inline

text must have been created using a TextEngine from RendererTextEngine.RendererTextEngine(), and will draw using the renderer passed to that function.

Parameters

text	the text to draw.
p	the (x, y) coordinate in pixels, positive from the left edge towards the right and from the top edge towards the bottom.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: RendererTextEngine.RendererTextEngine; GPUTextEngine.GPUTextEngine

◆ DrawSurface()

void SDL::Text::DrawSurface	(	Point	p,
		SurfaceParam	surface
	)		const

inline

text must have been created using a TextEngine from SurfaceTextEngine.SurfaceTextEngine().

Parameters

p	the x,y coordinates in pixels, positive from the top-left edge towards the bottom-right.
surface	the surface to draw on.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: SurfaceTextEngine.SurfaceTextEngine; Text.Text

◆ DrawSurfaceText()

void SDL::DrawSurfaceText	(	TextConstParam	text,
		Point	p,
		SurfaceParam	surface
	)

inline

text must have been created using a TextEngine from SurfaceTextEngine.SurfaceTextEngine().

Parameters

text	the text to draw.
p	the (x, y) coordinate in pixels, positive from the left edge towards the right and from the top edge towards the bottom.
surface	the surface to draw on.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: SurfaceTextEngine.SurfaceTextEngine; Text.Text

◆ FontHasGlyph()

bool SDL::FontHasGlyph	(	FontParam	font,
		Uint32	ch
	)

inline

Parameters

font	the font to query.
ch	the codepoint to check.

Returns: true if font provides a glyph for this character, false if not.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ FontIsFixedWidth()

bool SDL::FontIsFixedWidth ( FontParam font )

inline

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

font	the font to query.

Returns: true if the font is fixed-width, false otherwise.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ FontIsScalable()

bool SDL::FontIsScalable ( FontParam font )

inline

Scalability lets us distinguish between outline and bitmap fonts.

Parameters

font	the font to query.

Returns: true if the font is scalable, false otherwise.

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: Font.SetSDF

◆ GetAscent()

int SDL::Font::GetAscent ( ) const

inline

This is a positive value, relative to the baseline.

Returns: the font's ascent.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetColor() [1/2]

Color SDL::Text::GetColor ( ) const

inline

Returns: The color in the range of 0-255 on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ GetColor() [2/2]

void SDL::Text::GetColor	(	Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a
	)		const

inline

Parameters

r	a pointer filled in with the red color value in the range of 0-255, may be nullptr.
g	a pointer filled in with the green color value in the range of 0-255, may be nullptr.
b	a pointer filled in with the blue color value in the range of 0-255, may be nullptr.
a	a pointer filled in with the alpha value in the range of 0-255, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ GetColorFloat() [1/2]

FColor SDL::Text::GetColorFloat ( ) const

inline

Returns: The color in the range of 0-1 on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ GetColorFloat() [2/2]

void SDL::Text::GetColorFloat	(	float *	r,
		float *	g,
		float *	b,
		float *	a
	)		const

inline

Parameters

r	a pointer filled in with the red color value, normally in the range of 0-1, may be nullptr.
g	a pointer filled in with the green color value, normally in the range of 0-1, may be nullptr.
b	a pointer filled in with the blue color value, normally in the range of 0-1, may be nullptr.
a	a pointer filled in with the alpha value in the range of 0-1, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ GetDescent()

int SDL::Font::GetDescent ( ) const

inline

This is a negative value, relative to the baseline.

Returns: the font's descent.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetDirection() [1/2]

Direction SDL::Font::GetDirection ( ) const

inline

This defaults to DIRECTION_INVALID if it hasn't been set.

Returns: the direction to be used for text shaping.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetDirection() [2/2]

Direction SDL::Text::GetDirection ( ) const

inline

This defaults to the direction of the font used by the text object.

Returns: the direction to be used for text shaping.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetDPI()

void SDL::Font::GetDPI	(	int *	hdpi,
		int *	vdpi
	)		const

inline

Parameters

hdpi	a pointer filled in with the target horizontal DPI.
vdpi	a pointer filled in with the target vertical DPI.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.SetSizeDPI

◆ GetEngine()

TextEngineParam SDL::Text::GetEngine ( ) const

inline

Returns: the TextEngine used by the text on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetEngine

◆ GetFamilyName()

const char * SDL::Font::GetFamilyName ( ) const

inline

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

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

Returns: the font's family name.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFont()

FontRef SDL::Text::GetFont ( ) const

inline

Returns: the Font used by the text on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetFont

◆ GetFontAscent()

int SDL::GetFontAscent ( FontParam font )

inline

This is a positive value, relative to the baseline.

Parameters

font	the font to query.

Returns: the font's ascent.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontDescent()

int SDL::GetFontDescent ( FontParam font )

inline

This is a negative value, relative to the baseline.

Parameters

font	the font to query.

Returns: the font's descent.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontDirection()

Direction SDL::GetFontDirection ( FontParam font )

inline

This defaults to DIRECTION_INVALID if it hasn't been set.

Parameters

font	the font to query.

Returns: the direction to be used for text shaping.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontDPI()

void SDL::GetFontDPI	(	FontParam	font,
		int *	hdpi,
		int *	vdpi
	)

inline

Parameters

font	the font to query.
hdpi	a pointer filled in with the target horizontal DPI.
vdpi	a pointer filled in with the target vertical DPI.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.SetSizeDPI

◆ GetFontFamilyName()

const char * SDL::GetFontFamilyName ( FontParam font )

inline

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

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

Parameters

font	the font to query.

Returns: the font's family name.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontGeneration()

Uint32 SDL::GetFontGeneration ( FontParam font )

inline

The generation is incremented each time font properties change that require rebuilding glyphs, such as style, size, etc.

Parameters

font	the font to query.

Returns: the font generation or 0 on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontHeight()

int SDL::GetFontHeight ( FontParam font )

inline

This is usually equal to point size.

Parameters

font	the font to query.

Returns: the font's height.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontHinting()

HintingFlags SDL::GetFontHinting ( FontParam font )

inline

The hinter setting is a single value:

HINTING_NORMAL
HINTING_LIGHT
HINTING_MONO
HINTING_NONE
HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 3.0.0 and later)

Parameters

font	the font to query.

Returns: the font's current hinter value, or HINTING_INVALID if the font is invalid.

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: Font.SetHinting

◆ GetFontKerning()

bool SDL::GetFontKerning ( FontParam font )

inline

Parameters

font	the font to query.

Returns: true if kerning is enabled, false otherwise.

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: Font.SetKerning

◆ GetFontLineSkip()

int SDL::GetFontLineSkip ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the font's recommended spacing.

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: Font.SetLineSkip

◆ GetFontOutline()

int SDL::GetFontOutline ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the font's current outline value.

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: Font.SetOutline

◆ GetFontProperties()

PropertiesRef SDL::GetFontProperties ( FontParam font )

inline

The following read-write properties are provided by SDL:

prop::Font.OUTLINE_LINE_CAP_NUMBER: The FT_Stroker_LineCap value used when setting the font outline, defaults to FT_STROKER_LINECAP_ROUND.
prop::Font.OUTLINE_LINE_JOIN_NUMBER: The FT_Stroker_LineJoin value used when setting the font outline, defaults to FT_STROKER_LINEJOIN_ROUND.
prop::Font.OUTLINE_MITER_LIMIT_NUMBER: The FT_Fixed miter limit used when setting the font outline, defaults to 0.

Parameters

font	the font to query.

Returns: a valid property ID on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontScript()

Uint32 SDL::GetFontScript ( FontParam font )

inline

Parameters

font	the font to query.

Returns: an ISO 15924 code or 0 if a script hasn't been set.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetFontSDF()

bool SDL::GetFontSDF ( FontParam font )

inline

Parameters

font	the font to query.

Returns: true if enabled, false otherwise.

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: Font.SetSDF

◆ GetFontSize()

float SDL::GetFontSize ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the size of the font, or 0.0f on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.SetSize; Font.SetSizeDPI

◆ GetFontStyle()

FontStyleFlags SDL::GetFontStyle ( FontParam font )

inline

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

STYLE_NORMAL (is zero)
STYLE_BOLD
STYLE_ITALIC
STYLE_UNDERLINE
STYLE_STRIKETHROUGH

Parameters

font	the font to query.

Returns: the current font style, as a set of bit flags.

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: Font.SetStyle

◆ GetFontStyleName()

const char * SDL::GetFontStyleName ( FontParam font )

inline

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

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

Parameters

font	the font to query.

Returns: the font's style name.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetFontWeight()

int SDL::GetFontWeight ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the font's current weight.

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

Since: This function is available since SDL_ttf 3.2.2.

◆ GetFontWrapAlignment()

HorizontalAlignment SDL::GetFontWrapAlignment ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the font's current wrap alignment option.

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: Font.SetWrapAlignment

◆ GetFreeTypeVersion()

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

inline

TTF.Init() should 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: TTF.Init

◆ GetGeneration()

Uint32 SDL::Font::GetGeneration ( ) const

inline

The generation is incremented each time font properties change that require rebuilding glyphs, such as style, size, etc.

Returns: the font generation or 0 on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphImage() [1/2]

Surface SDL::GetGlyphImage	(	FontParam	font,
		Uint32	ch,
		ImageType *	image_type
	)

inline

Parameters

font	the font to query.
ch	the codepoint to check.
image_type	a pointer filled in with the glyph image type, may be nullptr.

Returns: an Surface containing the glyph, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphImage() [2/2]

Surface SDL::Font::GetGlyphImage	(	Uint32	ch,
		ImageType *	image_type
	)		const

inline

Parameters

ch	the codepoint to check.
image_type	a pointer filled in with the glyph image type, may be nullptr.

Returns: an Surface containing the glyph, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphImageForIndex() [1/2]

Surface SDL::GetGlyphImageForIndex	(	FontParam	font,
		Uint32	glyph_index,
		ImageType *	image_type
	)

inline

This is useful for text engine implementations, which can call this with the glyph_index in a TTF_CopyOperation

Parameters

font	the font to query.
glyph_index	the index of the glyph to return.
image_type	a pointer filled in with the glyph image type, may be nullptr.

Returns: an Surface containing the glyph, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphImageForIndex() [2/2]

Surface SDL::Font::GetGlyphImageForIndex	(	Uint32	glyph_index,
		ImageType *	image_type
	)		const

inline

This is useful for text engine implementations, which can call this with the glyph_index in a TTF_CopyOperation

Parameters

glyph_index	the index of the glyph to return.
image_type	a pointer filled in with the glyph image type, may be nullptr.

Returns: an Surface containing the glyph, or nullptr on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphKerning() [1/2]

int SDL::GetGlyphKerning	(	FontParam	font,
		Uint32	previous_ch,
		Uint32	ch
	)

inline

Parameters

font	the font to query.
previous_ch	the previous codepoint.
ch	the current codepoint.

Returns: the kerning size between the two glyphs, in pixels.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphKerning() [2/2]

int SDL::Font::GetGlyphKerning	(	Uint32	previous_ch,
		Uint32	ch
	)		const

inline

Parameters

previous_ch	the previous codepoint.
ch	the current codepoint.

Returns: the kerning size between the two glyphs, in pixels.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphMetrics() [1/2]

void SDL::GetGlyphMetrics	(	FontParam	font,
		Uint32	ch,
		int *	minx,
		int *	maxx,
		int *	miny,
		int *	maxy,
		int *	advance
	)

inline

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

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

Parameters

font	the font to query.
ch	the codepoint to check.
minx	a pointer filled in with the minimum x coordinate of the glyph from the left edge of its bounding box. This value may be negative.
maxx	a pointer filled in with the maximum x coordinate of the glyph from the left edge of its bounding box.
miny	a pointer filled in with the minimum y coordinate of the glyph from the bottom edge of its bounding box. This value may be negative.
maxy	a pointer filled in with the maximum y coordinate of the glyph from the bottom edge of its bounding box.
advance	a pointer filled in with the distance to the next glyph from the left edge of this glyph's bounding box.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphMetrics() [2/2]

void SDL::Font::GetGlyphMetrics	(	Uint32	ch,
		int *	minx,
		int *	maxx,
		int *	miny,
		int *	maxy,
		int *	advance
	)		const

inline

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

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

Parameters

ch	the codepoint to check.
minx	a pointer filled in with the minimum x coordinate of the glyph from the left edge of its bounding box. This value may be negative.
maxx	a pointer filled in with the maximum x coordinate of the glyph from the left edge of its bounding box.
miny	a pointer filled in with the minimum y coordinate of the glyph from the bottom edge of its bounding box. This value may be negative.
maxy	a pointer filled in with the maximum y coordinate of the glyph from the bottom edge of its bounding box.
advance	a pointer filled in with the distance to the next glyph from the left edge of this glyph's bounding box.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetGlyphScript() [1/2]

Uint32 SDL::Font::GetGlyphScript ( Uint32 ch )

inlinestatic

Parameters

ch	the character code to check.

Returns: an ISO 15924 code on success, or 0 on failure; call GetError() for more information.

Thread safety:: This function is thread-safe.

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetGlyphScript() [2/2]

Uint32 SDL::GetGlyphScript ( Uint32 ch )

inline

Parameters

ch	the character code to check.

Returns: an ISO 15924 code on success, or 0 on failure; call GetError() for more information.

Thread safety:: This function is thread-safe.

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetGPUDrawData()

GPUAtlasDrawSequence * SDL::Text::GetGPUDrawData ( ) const

inline

text must have been created using a TextEngine from GPUTextEngine.GPUTextEngine().

The positive X-axis is taken towards the right and the positive Y-axis is taken upwards for both the vertex and the texture coordinates, i.e, it follows the same convention used by the SDL_GPU API. If you want to use a different coordinate system you will need to transform the vertices yourself.

If the text looks blocky use linear filtering.

Returns: a nullptr terminated linked list of GPUAtlasDrawSequence objects or nullptr if the passed text is empty or in case of failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GPUTextEngine; Text.Text

◆ GetGPUTextDrawData()

GPUAtlasDrawSequence * SDL::GetGPUTextDrawData ( TextConstParam text )

inline

text must have been created using a TextEngine from GPUTextEngine.GPUTextEngine().

The positive X-axis is taken towards the right and the positive Y-axis is taken upwards for both the vertex and the texture coordinates, i.e, it follows the same convention used by the SDL_GPU API. If you want to use a different coordinate system you will need to transform the vertices yourself.

If the text looks blocky use linear filtering.

Parameters

text	the text to draw.

Returns: a nullptr terminated linked list of GPUAtlasDrawSequence objects or nullptr if the passed text is empty or in case of failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GPUTextEngine; GPUTextEngine.GPUTextEngine

◆ GetGPUTextEngineWinding()

GPUTextEngineWinding SDL::GetGPUTextEngineWinding ( TextEngineParam engine )

inline

Parameters

engine a TextEngine object created with GPUTextEngine.GPUTextEngine().

Returns: the winding order used by the GPU text engine or GPU_TEXTENGINE_WINDING_INVALID in case of error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.SetGPUWinding

◆ GetGPUWinding()

GPUTextEngineWinding SDL::GPUTextEngine::GetGPUWinding ( ) const

inline

Returns: the winding order used by the GPU text engine or GPU_TEXTENGINE_WINDING_INVALID in case of error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.SetGPUWinding

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

◆ GetHeight()

int SDL::Font::GetHeight ( ) const

inline

This is usually equal to point size.

Returns: the font's height.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetHinting()

HintingFlags SDL::Font::GetHinting ( ) const

inline

The hinter setting is a single value:

HINTING_NORMAL
HINTING_LIGHT
HINTING_MONO
HINTING_NONE
HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 3.0.0 and later)

Returns: the font's current hinter value, or HINTING_INVALID if the font is invalid.

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: Font.SetHinting

◆ GetKerning()

bool SDL::Font::GetKerning ( ) const

inline

Returns: true if kerning is enabled, false otherwise.

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: Font.SetKerning

◆ GetLineSkip()

int SDL::Font::GetLineSkip ( ) const

inline

Returns: the font's recommended spacing.

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: Font.SetLineSkip

◆ GetNextSubString()

void SDL::Text::GetNextSubString	(	const SubString &	substring,
		SubString *	next
	)		const

inline

If called at the end of the text, this will return a zero length substring with the SUBSTRING_TEXT_END flag set.

Parameters

substring	the SubString to query.
next	a pointer filled in with the next substring.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetNextTextSubString()

void SDL::GetNextTextSubString	(	TextConstParam	text,
		const SubString &	substring,
		SubString *	next
	)

inline

If called at the end of the text, this will return a zero length substring with the SUBSTRING_TEXT_END flag set.

Parameters

text	the Text to query.
substring	the SubString to query.
next	a pointer filled in with the next substring.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetNumFaces()

int SDL::Font::GetNumFaces ( ) const

inline

Returns: the number of FreeType font faces.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetNumFontFaces()

int SDL::GetNumFontFaces ( FontParam font )

inline

Parameters

font	the font to query.

Returns: the number of FreeType font faces.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetOutline()

int SDL::Font::GetOutline ( ) const

inline

Returns: the font's current outline value.

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: Font.SetOutline

◆ GetPosition() [1/2]

Point SDL::Text::GetPosition ( ) const

inline

Returns: a Point with the offset of the upper left corner of this text in pixels on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetPosition

◆ GetPosition() [2/2]

bool SDL::Text::GetPosition	(	int *	x,
		int *	y
	)		const

inline

Parameters

x	a pointer filled in with the x offset of the upper left corner of this text in pixels, may be nullptr.
y	a pointer filled in with the y offset of the upper left corner of this text in pixels, may be nullptr.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetPosition

◆ GetPreviousSubString()

void SDL::Text::GetPreviousSubString	(	const SubString &	substring,
		SubString *	previous
	)		const

inline

If called at the start of the text, this will return a zero length substring with the SUBSTRING_TEXT_START flag set.

Parameters

substring	the SubString to query.
previous	a pointer filled in with the previous substring in the text object.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetPreviousTextSubString()

void SDL::GetPreviousTextSubString	(	TextConstParam	text,
		const SubString &	substring,
		SubString *	previous
	)

inline

If called at the start of the text, this will return a zero length substring with the SUBSTRING_TEXT_START flag set.

Parameters

text	the Text to query.
substring	the SubString to query.
previous	a pointer filled in with the previous substring in the text object.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetProperties() [1/2]

PropertiesRef SDL::Font::GetProperties ( )

inline

The following read-write properties are provided by SDL:

prop::Font.OUTLINE_LINE_CAP_NUMBER: The FT_Stroker_LineCap value used when setting the font outline, defaults to FT_STROKER_LINECAP_ROUND.
prop::Font.OUTLINE_LINE_JOIN_NUMBER: The FT_Stroker_LineJoin value used when setting the font outline, defaults to FT_STROKER_LINEJOIN_ROUND.
prop::Font.OUTLINE_MITER_LIMIT_NUMBER: The FT_Fixed miter limit used when setting the font outline, defaults to 0.

Returns: a valid property ID on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetProperties() [2/2]

PropertiesRef SDL::Text::GetProperties ( ) const

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetScript() [1/2]

Uint32 SDL::Font::GetScript ( ) const

inline

Returns: an ISO 15924 code or 0 if a script hasn't been set.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetScript() [2/2]

Uint32 SDL::Text::GetScript ( ) const

inline

This defaults to the script of the font used by the text object.

Returns: an ISO 15924 code or 0 if a script hasn't been set on either the text object or the font.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetSDF()

bool SDL::Font::GetSDF ( ) const

inline

Returns: true if enabled, false otherwise.

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: Font.SetSDF

◆ GetSize() [1/3]

float SDL::Font::GetSize ( ) const

inline

Returns: the size of the font, or 0.0f on failure; call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.SetSize; Font.SetSizeDPI

◆ GetSize() [2/3]

Point SDL::Text::GetSize ( ) const

inline

The size of the text may change when the font or font style and size change.

Returns: Point containing the size on x and y axis on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GetSize(int*,int*) if might want only one of the coordinates

◆ GetSize() [3/3]

void SDL::Text::GetSize	(	int *	w,
		int *	h
	)		const

inline

The size of the text may change when the font or font style and size change.

Parameters

w	a pointer filled in with the width of the text, in pixels, may be nullptr.
h	a pointer filled in with the height of the text, in pixels, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetStringSize() [1/2]

void SDL::GetStringSize	(	FontParam	font,
		std::string_view	text,
		int *	w,
		int *	h
	)

inline

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

Parameters

font	the font to query.
text	text to calculate, in UTF-8 encoding.
w	will be filled with width, in pixels, on return.
h	will be filled with height, in pixels, on return.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetStringSize() [2/2]

void SDL::Font::GetStringSize	(	std::string_view	text,
		int *	w,
		int *	h
	)		const

inline

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

Parameters

text	text to calculate, in UTF-8 encoding.
w	will be filled with width, in pixels, on return.
h	will be filled with height, in pixels, on return.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetStringSizeWrapped() [1/2]

void SDL::GetStringSizeWrapped	(	FontParam	font,
		std::string_view	text,
		int	wrap_width,
		int *	w,
		int *	h
	)

inline

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

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

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

Parameters

font	the font to query.
text	text to calculate, in UTF-8 encoding.
wrap_width	the maximum width or 0 to wrap on newline characters.
w	will be filled with width, in pixels, on return.
h	will be filled with height, in pixels, on return.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetStringSizeWrapped() [2/2]

void SDL::Font::GetStringSizeWrapped	(	std::string_view	text,
		int	wrap_width,
		int *	w,
		int *	h
	)		const

inline

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

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

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

Parameters

text	text to calculate, in UTF-8 encoding.
wrap_width	the maximum width or 0 to wrap on newline characters.
w	will be filled with width, in pixels, on return.
h	will be filled with height, in pixels, on return.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetStyle()

FontStyleFlags SDL::Font::GetStyle ( ) const

inline

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

STYLE_NORMAL (is zero)
STYLE_BOLD
STYLE_ITALIC
STYLE_UNDERLINE
STYLE_STRIKETHROUGH

Returns: the current font style, as a set of bit flags.

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: Font.SetStyle

◆ GetStyleName()

const char * SDL::Font::GetStyleName ( ) const

inline

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

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

Returns: the font's style name.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetSubString()

void SDL::Text::GetSubString	(	int	offset,
		SubString *	substring
	)		const

inline

If offset is less than 0, this will return a zero length substring at the beginning of the text with the SUBSTRING_TEXT_START flag set. If offset is greater than or equal to the length of the text string, this will return a zero length substring at the end of the text with the SUBSTRING_TEXT_END flag set.

Parameters

offset	a byte offset into the text string.
substring	a pointer filled in with the substring containing the offset.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetSubStringForLine()

void SDL::Text::GetSubStringForLine	(	int	line,
		SubString *	substring
	)		const

inline

If line is less than 0, this will return a zero length substring at the beginning of the text with the SUBSTRING_TEXT_START flag set. If line is greater than or equal to text->num_lines this will return a zero length substring at the end of the text with the SUBSTRING_TEXT_END flag set.

Parameters

line	a zero-based line index, in the range [0 .. text->num_lines-1].
substring	a pointer filled in with the substring containing the offset.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetSubStringForPoint()

void SDL::Text::GetSubStringForPoint	(	Point	p,
		SubString *	substring
	)		const

inline

This will return the closest substring of text to the given point.

Parameters

p	the coordinates relative to the top-left side of the text, may be outside the bounds of the text area.
substring	a pointer filled in with the closest substring of text to the given point.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetSubStringsForRange()

OwnArray< SubString * > SDL::Text::GetSubStringsForRange	(	int	offset,
		int	length = `-1`
	)		const

inline

Parameters

offset	a byte offset into the text string.
length	the length of the range being queried, in bytes, or -1 for the remainder of the string.

Returns: a nullptr terminated array of substring pointers or nullptr on failure; call GetError() for more information. This is a single allocation that should be freed with free() when it is no longer needed.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextColor() [1/2]

void SDL::GetTextColor	(	TextConstParam	text,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a
	)

inline

Parameters

text	the Text to query.
r	a pointer filled in with the red color value in the range of 0-255, may be nullptr.
g	a pointer filled in with the green color value in the range of 0-255, may be nullptr.
b	a pointer filled in with the blue color value in the range of 0-255, may be nullptr.
a	a pointer filled in with the alpha value in the range of 0-255, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ GetTextColor() [2/2]

Color SDL::GetTextColor ( TextParam text )

inline

Parameters

text	the Text to query.

Returns: The color in the range of 0-255 on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ GetTextColorFloat() [1/2]

void SDL::GetTextColorFloat	(	TextConstParam	text,
		float *	r,
		float *	g,
		float *	b,
		float *	a
	)

inline

Parameters

text	the Text to query.
r	a pointer filled in with the red color value, normally in the range of 0-1, may be nullptr.
g	a pointer filled in with the green color value, normally in the range of 0-1, may be nullptr.
b	a pointer filled in with the blue color value, normally in the range of 0-1, may be nullptr.
a	a pointer filled in with the alpha value in the range of 0-1, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ GetTextColorFloat() [2/2]

FColor SDL::GetTextColorFloat ( TextParam text )

inline

Parameters

text	the Text to query.

Returns: The color in the range of 0-1 on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ GetTextDirection()

Direction SDL::GetTextDirection ( TextConstParam text )

inline

This defaults to the direction of the font used by the text object.

Parameters

text	the text to query.

Returns: the direction to be used for text shaping.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextEngine()

TextEngineParam SDL::GetTextEngine ( TextConstParam text )

inline

Parameters

text	the Text to query.

Returns: the TextEngine used by the text on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetEngine

◆ GetTextFont()

FontRef SDL::GetTextFont ( TextConstParam text )

inline

Parameters

text	the Text to query.

Returns: the Font used by the text on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetFont

◆ GetTextPosition() [1/2]

bool SDL::GetTextPosition	(	TextConstParam	text,
		int *	x,
		int *	y
	)

inline

Parameters

text	the Text to query.
x	a pointer filled in with the x offset of the upper left corner of this text in pixels, may be nullptr.
y	a pointer filled in with the y offset of the upper left corner of this text in pixels, may be nullptr.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetPosition

◆ GetTextPosition() [2/2]

Point SDL::GetTextPosition ( TextParam text )

inline

Parameters

text	the Text to query.

Returns: a Point with the offset of the upper left corner of this text in pixels on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetPosition

◆ GetTextProperties()

PropertiesRef SDL::GetTextProperties ( TextConstParam text )

inline

Parameters

text	the Text to query.

Returns: a valid property ID on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextScript()

Uint32 SDL::GetTextScript ( TextConstParam text )

inline

This defaults to the script of the font used by the text object.

Parameters

text	the text to query.

Returns: an ISO 15924 code or 0 if a script hasn't been set on either the text object or the font.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: TagToString

◆ GetTextSize() [1/2]

void SDL::GetTextSize	(	TextConstParam	text,
		int *	w,
		int *	h
	)

inline

The size of the text may change when the font or font style and size change.

Parameters

text	the Text to query.
w	a pointer filled in with the width of the text, in pixels, may be nullptr.
h	a pointer filled in with the height of the text, in pixels, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextSize() [2/2]

Point SDL::GetTextSize ( TextParam text )

inline

The size of the text may change when the font or font style and size change.

Parameters

text	the Text to query.

Returns: Point containing the size on x and y axis on success or std::nullopt on failure; call GetError() for more information.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextSubString()

void SDL::GetTextSubString	(	TextConstParam	text,
		int	offset,
		SubString *	substring
	)

inline

If offset is less than 0, this will return a zero length substring at the beginning of the text with the SUBSTRING_TEXT_START flag set. If offset is greater than or equal to the length of the text string, this will return a zero length substring at the end of the text with the SUBSTRING_TEXT_END flag set.

Parameters

text	the Text to query.
offset	a byte offset into the text string.
substring	a pointer filled in with the substring containing the offset.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextSubStringForLine()

void SDL::GetTextSubStringForLine	(	TextConstParam	text,
		int	line,
		SubString *	substring
	)

inline

If line is less than 0, this will return a zero length substring at the beginning of the text with the SUBSTRING_TEXT_START flag set. If line is greater than or equal to text->num_lines this will return a zero length substring at the end of the text with the SUBSTRING_TEXT_END flag set.

Parameters

text	the Text to query.
line	a zero-based line index, in the range [0 .. text->num_lines-1].
substring	a pointer filled in with the substring containing the offset.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextSubStringForPoint()

void SDL::GetTextSubStringForPoint	(	TextConstParam	text,
		Point	p,
		SubString *	substring
	)

inline

This will return the closest substring of text to the given point.

Parameters

text	the Text to query.
p	the coordinates relative to the top-left side of the text, may be outside the bounds of the text area.
substring	a pointer filled in with the closest substring of text to the given point.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextSubStringsForRange()

OwnArray< SubString * > SDL::GetTextSubStringsForRange	(	TextConstParam	text,
		int	offset,
		int	length
	)

inline

Parameters

text	the Text to query.
offset	a byte offset into the text string.
length	the length of the range being queried, in bytes, or -1 for the remainder of the string.

Returns: a nullptr terminated array of substring pointers or nullptr on failure; call GetError() for more information. This is a single allocation that should be freed with free() when it is no longer needed.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ GetTextWrapWidth()

int SDL::GetTextWrapWidth ( TextConstParam text )

inline

Parameters

text	the Text to query.

Returns: maximum width in pixels or 0 if the text is being wrapped on newline characters.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetWrapWidth

◆ GetWeight()

int SDL::Font::GetWeight ( ) const

inline

Returns: the font's current weight.

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

Since: This function is available since SDL_ttf 3.2.2.

◆ GetWrapAlignment()

HorizontalAlignment SDL::Font::GetWrapAlignment ( ) const

inline

Returns: the font's current wrap alignment option.

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: Font.SetWrapAlignment

◆ GetWrapWidth()

int SDL::Text::GetWrapWidth ( ) const

inline

Returns: an int with the maximum width in pixels or 0 if the text is being wrapped on newline characters on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetWrapWidth

◆ HasGlyph()

bool SDL::Font::HasGlyph ( Uint32 ch ) const

inline

Parameters

ch	the codepoint to check.

Returns: true if font provides a glyph for this character, false if not.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ InsertString()

void SDL::Text::InsertString	(	int	offset,
		std::string_view	string
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

offset	the offset, in bytes, from the beginning of the string if >= 0, the offset from the end of the string if < 0. Note that this does not do UTF-8 validation, so you should only insert at UTF-8 sequence boundaries.
string	the UTF-8 text to insert.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.DeleteString; Text.SetString

◆ InsertTextString()

void SDL::InsertTextString	(	TextParam	text,
		int	offset,
		std::string_view	string
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
offset	the offset, in bytes, from the beginning of the string if >= 0, the offset from the end of the string if < 0. Note that this does not do UTF-8 validation, so you should only insert at UTF-8 sequence boundaries.
string	the UTF-8 text to insert.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.DeleteString; Text.SetString

◆ IsFixedWidth()

bool SDL::Font::IsFixedWidth ( ) const

inline

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.

Returns: true if the font is fixed-width, false otherwise.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ IsScalable()

bool SDL::Font::IsScalable ( ) const

inline

Scalability lets us distinguish between outline and bitmap fonts.

Returns: true if the font is scalable, false otherwise.

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: Font.SetSDF

◆ IsWrapWhitespaceVisible()

bool SDL::Text::IsWrapWhitespaceVisible ( ) const

inline

Returns: true if whitespace is shown when wrapping text, or false otherwise.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetWrapWhitespaceVisible

◆ MeasureString() [1/2]

void SDL::MeasureString	(	FontParam	font,
		std::string_view	text,
		int	max_width,
		int *	measured_width,
		size_t *	measured_length
	)

inline

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

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

Parameters

font	the font to query.
text	text to calculate, in UTF-8 encoding.
max_width	maximum width, in pixels, available for the string, or 0 for unbounded width.
measured_width	a pointer filled in with the width, in pixels, of the string that will fit, may be nullptr.
measured_length	a pointer filled in with the length, in bytes, of the string that will fit, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ MeasureString() [2/2]

void SDL::Font::MeasureString	(	std::string_view	text,
		int	max_width,
		int *	measured_width,
		size_t *	measured_length
	)		const

inline

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

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

Parameters

text	text to calculate, in UTF-8 encoding.
max_width	maximum width, in pixels, available for the string, or 0 for unbounded width.
measured_width	a pointer filled in with the width, in pixels, of the string that will fit, may be nullptr.
measured_length	a pointer filled in with the length, in bytes, of the string that will fit, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ OpenFont() [1/2]

Font SDL::OpenFont	(	IOStreamParam	src,
		float	ptsize,
		bool	closeio = `false`
	)

inline

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 closeio is true, src will be automatically closed once the font is closed. Otherwise you should keep src open until the font is closed.

When done with the returned Font, use Font.Close() to dispose of it.

Parameters

src	an IOStream to provide a font file's data.
ptsize	point size to use for the newly-opened font.
closeio	true to close `src` when the font is closed, false to leave it open.

Returns: a valid Font on success.

Exceptions

Error on failure.

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: Font.Close

◆ OpenFont() [2/2]

Font SDL::OpenFont	(	StringParam	file,
		float	ptsize
	)

inline

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 Font, use Font.Close() to dispose of it.

Parameters

file	path to font file.
ptsize	point size to use for the newly-opened font.

Returns: a valid Font on success.

Exceptions

Error on failure.

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: Font.Close

◆ OpenFontWithProperties()

Font SDL::OpenFontWithProperties ( PropertiesParam props )

inline

These are the supported properties:

prop::Font.CREATE_FILENAME_STRING: the font file to open, if an IOStream isn't being used. This is required if prop::Font.CREATE_IOSTREAM_POINTER and prop::Font.CREATE_EXISTING_FONT_POINTER aren't set.
prop::Font.CREATE_IOSTREAM_POINTER: an IOStream containing the font to be opened. This should not be closed until the font is closed. This is required if prop::Font.CREATE_FILENAME_STRING and prop::Font.CREATE_EXISTING_FONT_POINTER aren't set.
prop::Font.CREATE_IOSTREAM_OFFSET_NUMBER: the offset in the iostream for the beginning of the font, defaults to 0.
prop::Font.CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN: true if closing the font should also close the associated IOStream.
prop::Font.CREATE_SIZE_FLOAT: the point size of the font. 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.
prop::Font.CREATE_FACE_NUMBER: the face index of the font, if the font contains multiple font faces.
prop::Font.CREATE_HORIZONTAL_DPI_NUMBER: the horizontal DPI to use for font rendering, defaults to prop::Font.CREATE_VERTICAL_DPI_NUMBER if set, or 72 otherwise.
prop::Font.CREATE_VERTICAL_DPI_NUMBER: the vertical DPI to use for font rendering, defaults to prop::Font.CREATE_HORIZONTAL_DPI_NUMBER if set, or 72 otherwise.
prop::Font.CREATE_EXISTING_FONT_POINTER: an optional Font that, if set, will be used as the font data source and the initial size and style of the new font.

Parameters

props the properties to use.

Returns: a valid Font on success.

Exceptions

Error on failure.

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: Font.Close

◆ RemoveFallback()

void SDL::Font::RemoveFallback ( FontParam fallback )

inline

This updates any Text objects using this font.

Parameters

fallback the font to remove as a fallback.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.AddFallback; Font.ClearFallbacks

◆ RemoveFallbackFont()

void SDL::RemoveFallbackFont	(	FontParam	font,
		FontParam	fallback
	)

inline

This updates any Text objects using this font.

Parameters

font	the font to modify.
fallback	the font to remove as a fallback.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.AddFallback; Font.ClearFallbacks

◆ RenderGlyph_Blended() [1/2]

Surface SDL::RenderGlyph_Blended	(	FontParam	font,
		Uint32	ch,
		ColorRaw	fg
	)

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Shaded, and Font.RenderGlyph_LCD.

Parameters

font	the font to render with.
ch	the codepoint to render.
fg	the foreground color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_LCD; Font.RenderGlyph_Shaded; Font.RenderGlyph_Solid

◆ RenderGlyph_Blended() [2/2]

Surface SDL::Font::RenderGlyph_Blended	(	Uint32	ch,
		ColorRaw	fg
	)		const

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Shaded, and Font.RenderGlyph_LCD.

Parameters

ch	the codepoint to render.
fg	the foreground color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_LCD; Font.RenderGlyph_Shaded; Font.RenderGlyph_Solid

◆ RenderGlyph_LCD() [1/2]

Surface SDL::RenderGlyph_LCD	(	FontParam	font,
		Uint32	ch,
		ColorRaw	fg,
		ColorRaw	bg
	)

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Shaded, and Font.RenderGlyph_Blended.

Parameters

font	the font to render with.
ch	the codepoint to render.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_Shaded; Font.RenderGlyph_Solid

◆ RenderGlyph_LCD() [2/2]

Surface SDL::Font::RenderGlyph_LCD	(	Uint32	ch,
		ColorRaw	fg,
		ColorRaw	bg
	)		const

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Shaded, and Font.RenderGlyph_Blended.

Parameters

ch	the codepoint to render.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_Shaded; Font.RenderGlyph_Solid

◆ RenderGlyph_Shaded() [1/2]

Surface SDL::RenderGlyph_Shaded	(	FontParam	font,
		Uint32	ch,
		ColorRaw	fg,
		ColorRaw	bg
	)

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Blended, and Font.RenderGlyph_LCD.

Parameters

font	the font to render with.
ch	the codepoint to render.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_LCD; Font.RenderGlyph_Solid

◆ RenderGlyph_Shaded() [2/2]

Surface SDL::Font::RenderGlyph_Shaded	(	Uint32	ch,
		ColorRaw	fg,
		ColorRaw	bg
	)		const

inline

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

You can render at other quality levels with Font.RenderGlyph_Solid, Font.RenderGlyph_Blended, and Font.RenderGlyph_LCD.

Parameters

ch	the codepoint to render.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_LCD; Font.RenderGlyph_Solid

◆ RenderGlyph_Solid() [1/2]

Surface SDL::RenderGlyph_Solid	(	FontParam	font,
		Uint32	ch,
		ColorRaw	fg
	)

inline

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.

You can render at other quality levels with Font.RenderGlyph_Shaded, Font.RenderGlyph_Blended, and Font.RenderGlyph_LCD.

Parameters

font	the font to render with.
ch	the character to render.
fg	the foreground color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_LCD; Font.RenderGlyph_Shaded

◆ RenderGlyph_Solid() [2/2]

Surface SDL::Font::RenderGlyph_Solid	(	Uint32	ch,
		ColorRaw	fg
	)		const

inline

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.

You can render at other quality levels with Font.RenderGlyph_Shaded, Font.RenderGlyph_Blended, and Font.RenderGlyph_LCD.

Parameters

ch	the character to render.
fg	the foreground color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderGlyph_Blended; Font.RenderGlyph_LCD; Font.RenderGlyph_Shaded

◆ RenderText_Blended() [1/2]

Surface SDL::RenderText_Blended	(	FontParam	font,
		std::string_view	text,
		Color	fg
	)

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Shaded, and Font.RenderText_LCD.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD; Font.RenderText_Shaded; Font.RenderText_Solid

◆ RenderText_Blended() [2/2]

Surface SDL::Font::RenderText_Blended	(	std::string_view	text,
		Color	fg
	)		const

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Shaded, and Font.RenderText_LCD.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD; Font.RenderText_Shaded; Font.RenderText_Solid

◆ RenderText_Blended_Wrapped() [1/2]

Surface SDL::RenderText_Blended_Wrapped	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		int	wrap_width
	)

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Shaded_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid_Wrapped

◆ RenderText_Blended_Wrapped() [2/2]

Surface SDL::Font::RenderText_Blended_Wrapped	(	std::string_view	text,
		Color	fg,
		int	wrap_width
	)		const

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Shaded_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid_Wrapped

◆ RenderText_LCD() [1/2]

Surface SDL::RenderText_LCD	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		Color	bg
	)

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Shaded, and Font.RenderText_Blended.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded; Font.RenderText_Solid

◆ RenderText_LCD() [2/2]

Surface SDL::Font::RenderText_LCD	(	std::string_view	text,
		Color	fg,
		Color	bg
	)		const

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Shaded, and Font.RenderText_Blended.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded; Font.RenderText_Solid

◆ RenderText_LCD_Wrapped() [1/2]

Surface SDL::RenderText_LCD_Wrapped	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		Color	bg,
		int	wrap_width
	)

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Shaded_Wrapped, and Font.RenderText_Blended_Wrapped.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid_Wrapped

◆ RenderText_LCD_Wrapped() [2/2]

Surface SDL::Font::RenderText_LCD_Wrapped	(	std::string_view	text,
		Color	fg,
		Color	bg,
		int	wrap_width
	)		const

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Shaded_Wrapped, and Font.RenderText_Blended_Wrapped.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 32-bit, ARGB surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid_Wrapped

◆ RenderText_Shaded() [1/2]

Surface SDL::RenderText_Shaded	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		Color	bg
	)

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Blended, and Font.RenderText_LCD.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid

◆ RenderText_Shaded() [2/2]

Surface SDL::Font::RenderText_Shaded	(	std::string_view	text,
		Color	fg,
		Color	bg
	)		const

inline

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 nullptr 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 Font.RenderText_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 Font.RenderText_Solid, Font.RenderText_Blended, and Font.RenderText_LCD.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid

◆ RenderText_Shaded_Wrapped() [1/2]

Surface SDL::RenderText_Shaded_Wrapped	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		Color	bg,
		int	wrap_width
	)

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Blended_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded; Font.RenderText_Solid_Wrapped

◆ RenderText_Shaded_Wrapped() [2/2]

Surface SDL::Font::RenderText_Shaded_Wrapped	(	std::string_view	text,
		Color	fg,
		Color	bg,
		int	wrap_width
	)		const

inline

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 nullptr if there was an error.

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

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

You can render at other quality levels with Font.RenderText_Solid_Wrapped, Font.RenderText_Blended_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
bg	the background color for the text.
wrap_width	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded; Font.RenderText_Solid_Wrapped

◆ RenderText_Solid() [1/2]

Surface SDL::RenderText_Solid	(	FontParam	font,
		std::string_view	text,
		Color	fg
	)

inline

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 Font.RenderText_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 Font.RenderText_Shaded, Font.RenderText_Blended, and Font.RenderText_LCD.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD; Font.RenderText_Shaded; Font.RenderText_Solid; Font.RenderText_Solid_Wrapped

◆ RenderText_Solid() [2/2]

Surface SDL::Font::RenderText_Solid	(	std::string_view	text,
		Color	fg
	)		const

inline

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 Font.RenderText_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 Font.RenderText_Shaded, Font.RenderText_Blended, and Font.RenderText_LCD.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended; Font.RenderText_LCD; Font.RenderText_Shaded; Font.RenderText_Solid; Font.RenderText_Solid_Wrapped

◆ RenderText_Solid_Wrapped() [1/2]

Surface SDL::RenderText_Solid_Wrapped	(	FontParam	font,
		std::string_view	text,
		Color	fg,
		int	wrapLength
	)

inline

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 Font.RenderText_Shaded_Wrapped, Font.RenderText_Blended_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

font	the font to render with.
text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
wrapLength	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid

◆ RenderText_Solid_Wrapped() [2/2]

Surface SDL::Font::RenderText_Solid_Wrapped	(	std::string_view	text,
		Color	fg,
		int	wrapLength
	)		const

inline

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 Font.RenderText_Shaded_Wrapped, Font.RenderText_Blended_Wrapped, and Font.RenderText_LCD_Wrapped.

Parameters

text	text to render, in UTF-8 encoding.
fg	the foreground color for the text.
wrapLength	the maximum width of the text surface or 0 to wrap on newline characters.

Returns: a new 8-bit, palettized surface, or nullptr if there was an error.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.RenderText_Blended_Wrapped; Font.RenderText_LCD_Wrapped; Font.RenderText_Shaded_Wrapped; Font.RenderText_Solid

◆ SetColor()

void SDL::Text::SetColor ( Color c )

inline

The default text color is white (255, 255, 255, 255).

Parameters

c	the color values in the range of 0-255.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ SetColorFloat()

void SDL::Text::SetColorFloat ( FColor c )

inline

The default text color is white (1.0f, 1.0f, 1.0f, 1.0f).

Parameters

c	the color value, normally in the range of 0-1.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ SetDirection() [1/2]

void SDL::Font::SetDirection ( Direction direction )

inline

This function only supports left-to-right text shaping if SDL_ttf was not built with HarfBuzz support.

This updates any Text objects using this font.

Parameters

direction the new direction for text to flow.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetDirection() [2/2]

void SDL::Text::SetDirection ( Direction direction )

inline

This function only supports left-to-right text shaping if SDL_ttf was not built with HarfBuzz support.

Parameters

direction the new direction for text to flow.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetEngine()

void SDL::Text::SetEngine ( TextEngineParam engine )

inline

This function may cause the internal text representation to be rebuilt.

Parameters

engine the text engine to use for drawing.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetEngine

◆ SetFont()

bool SDL::Text::SetFont ( FontParam font )

inline

When a text object has a font, any changes to the font will automatically regenerate the text. If you set the font to nullptr, the text will continue to render but changes to the font will no longer affect the text.

This function may cause the internal text representation to be rebuilt.

Parameters

font	the font to use, may be nullptr.

Returns: false if the text pointer is null; otherwise, true. call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetFont

◆ SetFontDirection()

void SDL::SetFontDirection	(	FontParam	font,
		Direction	direction
	)

inline

This function only supports left-to-right text shaping if SDL_ttf was not built with HarfBuzz support.

This updates any Text objects using this font.

Parameters

font	the font to modify.
direction	the new direction for text to flow.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetFontHinting()

void SDL::SetFontHinting	(	FontParam	font,
		HintingFlags	hinting
	)

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

The hinter setting is a single value:

HINTING_NORMAL
HINTING_LIGHT
HINTING_MONO
HINTING_NONE
HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 3.0.0 and later)

Parameters

font	the font to set a new hinter setting on.
hinting	the new hinter setting.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetHinting

◆ SetFontKerning()

void SDL::SetFontKerning	(	FontParam	font,
		bool	enabled
	)

inline

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

This updates any Text objects using this font.

Parameters

font	the font to set kerning on.
enabled	true to enable kerning, false to disable.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetKerning

◆ SetFontLanguage()

void SDL::SetFontLanguage	(	FontParam	font,
		StringParam	language_bcp47
	)

inline

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

This updates any Text objects using this font.

Parameters

font	the font to specify a language for.
language_bcp47	a null-terminated string containing the desired language's BCP47 code. Or null to reset the value.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetFontLineSkip()

void SDL::SetFontLineSkip	(	FontParam	font,
		int	lineskip
	)

inline

This updates any Text objects using this font.

Parameters

font	the font to modify.
lineskip	the new line spacing for the font.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetLineSkip

◆ SetFontOutline()

void SDL::SetFontOutline	(	FontParam	font,
		int	outline
	)

inline

This uses the font properties prop::Font.OUTLINE_LINE_CAP_NUMBER, prop::Font.OUTLINE_LINE_JOIN_NUMBER, and prop::Font.OUTLINE_MITER_LIMIT_NUMBER when setting the font outline.

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

font	the font to set a new outline on.
outline	positive outline value, 0 to default.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetOutline

◆ SetFontScript()

void SDL::SetFontScript	(	FontParam	font,
		Uint32	script
	)

inline

This returns false if SDL_ttf isn't built with HarfBuzz support.

This updates any Text objects using this font.

Parameters

font	the font to modify.
script	an ISO 15924 code.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: StringToTag

◆ SetFontSDF()

void SDL::SetFontSDF	(	FontParam	font,
		bool	enabled
	)

inline

SDF is a technique that helps fonts look sharp even when scaling and rotating, and requires special shader support for display.

This works with Blended APIs, and generates the raw signed distance values in the alpha channel of the resulting texture.

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

font	the font to set SDF support on.
enabled	true to enable SDF, false to disable.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSDF

◆ SetFontSize()

void SDL::SetFontSize	(	FontParam	font,
		float	ptsize
	)

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

font	the font to resize.
ptsize	the new point size.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSize

◆ SetFontSizeDPI()

void SDL::SetFontSizeDPI	(	FontParam	font,
		float	ptsize,
		int	hdpi,
		int	vdpi
	)

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

font	the font to resize.
ptsize	the new point size.
hdpi	the target horizontal DPI.
vdpi	the target vertical DPI.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSize; TTF_GetFontSizeDPI

◆ SetFontStyle()

void SDL::SetFontStyle	(	FontParam	font,
		FontStyleFlags	style
	)

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

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

STYLE_NORMAL (is zero)
STYLE_BOLD
STYLE_ITALIC
STYLE_UNDERLINE
STYLE_STRIKETHROUGH

Parameters

font	the font to set a new style on.
style	the new style values to set, OR'd together.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetStyle

◆ SetFontWrapAlignment()

void SDL::SetFontWrapAlignment	(	FontParam	font,
		HorizontalAlignment	align
	)

inline

This updates any Text objects using this font.

Parameters

font	the font to set a new wrap alignment option on.
align	the new wrap alignment option.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetWrapAlignment

◆ SetGPUTextEngineWinding()

void SDL::SetGPUTextEngineWinding	(	TextEngineParam	engine,
		GPUTextEngineWinding	winding
	)

inline

Parameters

engine	a TextEngine object created with GPUTextEngine.GPUTextEngine().
winding	the new winding order option.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GetGPUWinding

◆ SetGPUWinding()

void SDL::GPUTextEngine::SetGPUWinding ( GPUTextEngineWinding winding )

inline

Parameters

winding the new winding order option.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: GPUTextEngine.GetGPUWinding

◆ SetHinting()

void SDL::Font::SetHinting ( HintingFlags hinting )

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

The hinter setting is a single value:

HINTING_NORMAL
HINTING_LIGHT
HINTING_MONO
HINTING_NONE
HINTING_LIGHT_SUBPIXEL (available in SDL_ttf 3.0.0 and later)

Parameters

hinting the new hinter setting.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetHinting

◆ SetKerning()

void SDL::Font::SetKerning ( bool enabled )

inline

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

This updates any Text objects using this font.

Parameters

enabled true to enable kerning, false to disable.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetKerning

◆ SetLanguage()

void SDL::Font::SetLanguage ( StringParam language_bcp47 )

inline

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

This updates any Text objects using this font.

Parameters

language_bcp47 a null-terminated string containing the desired language's BCP47 code. Or null to reset the value.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetLineSkip()

void SDL::Font::SetLineSkip ( int lineskip )

inline

This updates any Text objects using this font.

Parameters

lineskip the new line spacing for the font.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetLineSkip

◆ SetOutline()

void SDL::Font::SetOutline ( int outline )

inline

This uses the font properties prop::Font.OUTLINE_LINE_CAP_NUMBER, prop::Font.OUTLINE_LINE_JOIN_NUMBER, and prop::Font.OUTLINE_MITER_LIMIT_NUMBER when setting the font outline.

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

outline positive outline value, 0 to default.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetOutline

◆ SetPosition()

bool SDL::Text::SetPosition ( Point p )

inline

This can be used to position multiple text objects within a single wrapping text area.

This function may cause the internal text representation to be rebuilt.

Parameters

p	the x, y offset of the upper left corner of this text in pixels.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetPosition

◆ SetScript() [1/2]

void SDL::Font::SetScript ( Uint32 script )

inline

This returns false if SDL_ttf isn't built with HarfBuzz support.

This updates any Text objects using this font.

Parameters

script an ISO 15924 code.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: StringToTag

◆ SetScript() [2/2]

void SDL::Text::SetScript ( Uint32 script )

inline

This returns false if SDL_ttf isn't built with HarfBuzz support.

Parameters

script an ISO 15924 code.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: StringToTag

◆ SetSDF()

void SDL::Font::SetSDF ( bool enabled )

inline

SDF is a technique that helps fonts look sharp even when scaling and rotating, and requires special shader support for display.

This works with Blended APIs, and generates the raw signed distance values in the alpha channel of the resulting texture.

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

enabled true to enable SDF, false to disable.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSDF

◆ SetSize()

void SDL::Font::SetSize ( float ptsize )

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

ptsize the new point size.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSize

◆ SetSizeDPI()

void SDL::Font::SetSizeDPI	(	float	ptsize,
		int	hdpi,
		int	vdpi
	)

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

Parameters

ptsize	the new point size.
hdpi	the target horizontal DPI.
vdpi	the target vertical DPI.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetSize; TTF_GetFontSizeDPI

◆ SetString()

void SDL::Text::SetString ( std::string_view string )

inline

This function may cause the internal text representation to be rebuilt.

Parameters

string the UTF-8 text to use.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.DeleteString; Text.InsertString

◆ SetStyle()

void SDL::Font::SetStyle ( FontStyleFlags style )

inline

This updates any Text objects using this font, and clears already-generated glyphs, if any, from the cache.

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

STYLE_NORMAL (is zero)
STYLE_BOLD
STYLE_ITALIC
STYLE_UNDERLINE
STYLE_STRIKETHROUGH

Parameters

style the new style values to set, OR'd together.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetStyle

◆ SetTextColor()

void SDL::SetTextColor	(	TextParam	text,
		Color	c
	)

inline

The default text color is white (255, 255, 255, 255).

Parameters

text	the Text to modify.
c	the color value in the range of 0-255.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColor; Text.SetColorFloat

◆ SetTextColorFloat()

void SDL::SetTextColorFloat	(	TextParam	text,
		FColor	c
	)

inline

The default text color is white (1.0f, 1.0f, 1.0f, 1.0f).

Parameters

text	the Text to modify.
c	the color value, normally in the range of 0-1.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetColorFloat; Text.SetColor

◆ SetTextDirection()

void SDL::SetTextDirection	(	TextParam	text,
		Direction	direction
	)

inline

This function only supports left-to-right text shaping if SDL_ttf was not built with HarfBuzz support.

Parameters

text	the text to modify.
direction	the new direction for text to flow.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ SetTextEngine()

void SDL::SetTextEngine	(	TextParam	text,
		TextEngineParam	engine
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
engine	the text engine to use for drawing.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetEngine

◆ SetTextFont()

bool SDL::SetTextFont	(	TextParam	text,
		FontParam	font
	)

inline

When a text object has a font, any changes to the font will automatically regenerate the text. If you set the font to nullptr, the text will continue to render but changes to the font will no longer affect the text.

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
font	the font to use, may be nullptr.

Returns: false if the text pointer is null; otherwise, true. call GetError() for more information.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetFont

◆ SetTextPosition()

bool SDL::SetTextPosition	(	TextParam	text,
		Point	p
	)

inline

This can be used to position multiple text objects within a single wrapping text area.

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
p	the x, y offset of the upper left corner of this text in pixels.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetPosition

◆ SetTextScript()

void SDL::SetTextScript	(	TextParam	text,
		Uint32	script
	)

inline

This returns false if SDL_ttf isn't built with HarfBuzz support.

Parameters

text	the text to modify.
script	an ISO 15924 code.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: StringToTag

◆ SetTextString()

void SDL::SetTextString	(	TextParam	text,
		std::string_view	string
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
string	the UTF-8 text to use, may be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.AppendString; Text.DeleteString; Text.InsertString

◆ SetTextWrapWhitespaceVisible()

void SDL::SetTextWrapWhitespaceVisible	(	TextParam	text,
		bool	visible
	)

inline

If the whitespace is visible, it will take up space for purposes of alignment and wrapping. This is good for editing, but looks better when centered or aligned if whitespace around line wrapping is hidden. This defaults false.

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
visible	true to show whitespace when wrapping text, false to hide it.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.IsWrapWhitespaceVisible

◆ SetTextWrapWidth()

void SDL::SetTextWrapWidth	(	TextParam	text,
		int	wrap_width
	)

inline

This function may cause the internal text representation to be rebuilt.

Parameters

text	the Text to modify.
wrap_width	the maximum width in pixels, 0 to wrap on newline characters.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetWrapWidth

◆ SetWrapAlignment()

void SDL::Font::SetWrapAlignment ( HorizontalAlignment align )

inline

This updates any Text objects using this font.

Parameters

align the new wrap alignment option.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Font.GetWrapAlignment

◆ SetWrapWhitespaceVisible()

void SDL::Text::SetWrapWhitespaceVisible ( bool visible )

inline

If the whitespace is visible, it will take up space for purposes of alignment and wrapping. This is good for editing, but looks better when centered or aligned if whitespace around line wrapping is hidden. This defaults false.

This function may cause the internal text representation to be rebuilt.

Parameters

visible true to show whitespace when wrapping text, false to hide it.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.IsWrapWhitespaceVisible

◆ SetWrapWidth()

void SDL::Text::SetWrapWidth ( int wrap_width )

inline

This function may cause the internal text representation to be rebuilt.

Parameters

wrap_width the maximum width in pixels, 0 to wrap on newline characters.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.GetWrapWidth

◆ 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

◆ TextWrapWhitespaceVisible()

bool SDL::TextWrapWhitespaceVisible ( TextConstParam text )

inline

Parameters

text	the Text to query.

Returns: true if whitespace is shown when wrapping text, or false otherwise.

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

Since: This function is available since SDL_ttf 3.0.0.

See also: Text.SetWrapWhitespaceVisible

◆ Update()

void SDL::Text::Update ( )

inline

This is automatically done when the layout is requested or the text is rendered, but you can call this if you need more control over the timing of when the layout and text engine representation are updated.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

◆ UpdateText()

void SDL::UpdateText ( TextParam text )

inline

This is automatically done when the layout is requested or the text is rendered, but you can call this if you need more control over the timing of when the layout and text engine representation are updated.

Parameters

text	the Text to update.

Exceptions

Error on failure.

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

Since: This function is available since SDL_ttf 3.0.0.

TTF_SUBSTRING_TEXT_START

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SDL_TTF_VERSION

◆ SDL_TTF_VERSION_ATLEAST

Typedef Documentation

◆ Direction

◆ FontStyleFlags

◆ GPUAtlasDrawSequence

◆ GPUTextEngineWinding

◆ HintingFlags

◆ HorizontalAlignment

◆ ImageType

◆ SubString

◆ SubStringFlags

Function Documentation

◆ AddFallback()

◆ AddFallbackFont()

◆ AppendString()

◆ AppendTextString()

◆ ClearFallbackFonts()

◆ ClearFallbacks()

◆ Close()

◆ CloseFont()

◆ Copy()

◆ CopyFont()

◆ CreateGPUTextEngine()

◆ CreateGPUTextEngineWithProperties()

◆ CreateRendererTextEngine()

◆ CreateRendererTextEngineWithProperties()

◆ CreateSurfaceTextEngine()

◆ CreateText() [1/2]

◆ CreateText() [2/2]

◆ DeleteString()

◆ DeleteTextString()

◆ Destroy() [1/4]

◆ Destroy() [2/4]

◆ Destroy() [3/4]

◆ Destroy() [4/4]

◆ DestroyGPUTextEngine()

◆ DestroyRendererTextEngine()

◆ DestroySurfaceTextEngine()

◆ DestroyText()

◆ DrawRenderer()

◆ DrawRendererText()

◆ DrawSurface()

◆ DrawSurfaceText()

◆ FontHasGlyph()

◆ FontIsFixedWidth()

◆ FontIsScalable()

◆ GetAscent()

◆ GetColor() [1/2]

◆ GetColor() [2/2]

◆ GetColorFloat() [1/2]

◆ GetColorFloat() [2/2]

◆ GetDescent()

◆ GetDirection() [1/2]

◆ GetDirection() [2/2]

◆ GetDPI()

◆ GetEngine()

◆ GetFamilyName()

◆ GetFont()

◆ GetFontAscent()

◆ GetFontDescent()

◆ GetFontDirection()

◆ GetFontDPI()

◆ GetFontFamilyName()

◆ GetFontGeneration()

◆ GetFontHeight()

◆ GetFontHinting()

◆ GetFontKerning()

◆ GetFontLineSkip()

◆ GetFontOutline()

◆ GetFontProperties()

◆ GetFontScript()

◆ GetFontSDF()