The internal structure containing font information. More...

Inheritance diagram for SDL::FontBase:

[legend]

Public Member Functions
	FontBase (StringParam file, float ptsize)
	Create a font from a file, using a specified point size.

	FontBase (IOStreamBase &src, float ptsize)
	Create a font from an IOStreamBase, using a specified point size.

	FontBase (PropertiesBase &props)
	Create a font with the specified properties.

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

PropertiesRef	GetProperties ()
	Get the properties associated with a font.

Uint32	GetGeneration () const
	Get the font generation.

void	AddFallback (FontBase &fallback)
	Add a fallback font.

void	RemoveFallback (FontBase &fallback)
	Remove a fallback font.

void	ClearFallbacks ()
	Remove all fallback fonts.

void	SetSize (float ptsize)
	Set a font's size dynamically.

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

float	GetSize () const
	Get the size of a font.

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

void	SetStyle (FontStyleFlags style)
	Set a font's current style.

FontStyleFlags	GetStyle () const
	Query a font's current style.

void	SetOutline (int outline)
	Set a font's current outline.

int	GetOutline () const
	Query a font's current outline.

void	SetHinting (HintingFlags hinting)
	Set a font's current hinter setting.

int	GetNumFaces () const
	Query the number of faces of a font.

HintingFlags	GetHinting () const
	Query a font's current FreeType hinter setting.

void	SetSDF (bool enabled)
	Enable Signed Distance Field rendering for a font.

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

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

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

HorizontalAlignment	GetWrapAlignment () const
	Query a font's current wrap alignment option.

int	GetHeight () const
	Query the total height of a font.

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

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

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

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

void	SetKerning (bool enabled)
	Set if kerning is enabled for a font.

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

bool	IsFixedWidth () const
	Query whether a font is fixed-width.

bool	IsScalable () const
	Query whether a font is scalable or not.

const char *	GetFamilyName () const
	Query a font's family name.

const char *	GetStyleName () const
	Query a font's style name.

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

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

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

Uint32	GetScript () const
	Get the script used for text shaping a font.

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

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

SurfaceRef	GetGlyphImage (Uint32 ch, ImageType *image_type=nullptr) const
	Get the pixel image for a UNICODE codepoint.

SurfaceRef	GetGlyphImageForIndex (Uint32 glyph_index, ImageType *image_type=nullptr) const
	Get the pixel image for a character index.

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

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

Point	GetStringSize (std::string_view text) const
	Calculate the dimensions of a rendered string of UTF-8 text.

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

Point	GetStringSizeWrapped (std::string_view text, int wrap_width) const
	Calculate the dimensions of a rendered string of UTF-8 text.

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

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

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

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

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

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

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

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

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

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

Surface	RenderGlyph_Blended (Uint32 ch, Color fg) const
	Render a single UNICODE codepoint at high quality to a new ARGB surface.

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

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

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

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< TTF_Font * >
constexpr	Resource (TTF_Font * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr TTF_Font *	get () const
	Return contained resource;.

constexpr TTF_Font *	release (TTF_Font * newResource={})
	Return contained resource and empties or replace value.

constexpr const TTF_Font *	operator-> () const
	Access to fields.

constexpr TTF_Font *	operator-> ()
	Access to fields.

Static Public Member Functions
static Uint32	GetGlyphScript (Uint32 ch)
	Get the script used by a 32-bit codepoint.

Detailed Description

Category:: Resource

See also: Font; FontRef

Constructor & Destructor Documentation

◆ FontBase() [1/3]

SDL::FontBase::FontBase	(	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.

Parameters

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

Postcondition: a valid FontBase 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.

◆ FontBase() [2/3]

SDL::FontBase::FontBase	(	IOStreamBase &	src,
		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.

Parameters

src	an IOStreamBase to provide a font file's data.
ptsize	point size to use for the newly-opened font.

Postcondition: a valid FontBase 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.

◆ FontBase() [3/3]

SDL::FontBase::FontBase ( PropertiesBase & props )

inline

These are the supported properties:

prop::Font.CREATE_FILENAME_STRING: the font file to open, if an IOStreamBase isn't being used. This is required if prop::Font.CREATE_IOSTREAM_POINTER and prop::Font.CREATE_EXISTING_FONT aren't set.
prop::Font.CREATE_IOSTREAM_POINTER: an IOStreamBase 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 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 IOStreamBase.
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: an optional FontBase 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.

Postcondition: a valid FontBase 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.

Member Function Documentation

◆ AddFallback()

void SDL::FontBase::AddFallback ( FontBase & 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 TextBase 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: FontBase.ClearFallbacks; FontBase.RemoveFallback

◆ ClearFallbacks()

void SDL::FontBase::ClearFallbacks ( )

inline

This updates any TextBase 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: FontBase.AddFallback; FontBase.RemoveFallback

◆ GetAscent()

int SDL::FontBase::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.

◆ GetDescent()

int SDL::FontBase::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()

Direction SDL::FontBase::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.

◆ GetDPI()

void SDL::FontBase::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: FontBase.SetSizeDPI

◆ GetFamilyName()

const char * SDL::FontBase::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 destroyed.

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.

◆ GetGeneration()

Uint32 SDL::FontBase::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()

SurfaceRef SDL::FontBase::GetGlyphImage	(	Uint32	ch,
		ImageType *	image_type = `nullptr`
	)		const

inline

Parameters

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

Returns: an SurfaceBase 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()

SurfaceRef SDL::FontBase::GetGlyphImageForIndex	(	Uint32	glyph_index,
		ImageType *	image_type = `nullptr`
	)		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 SurfaceRef 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()

int SDL::FontBase::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()

void SDL::FontBase::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()

static Uint32 SDL::FontBase::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

◆ GetHeight()

int SDL::FontBase::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::FontBase::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: FontBase.SetHinting

◆ GetKerning()

bool SDL::FontBase::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: FontBase.SetKerning

◆ GetLineSkip()

int SDL::FontBase::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: FontBase.SetLineSkip

◆ GetNumFaces()

int SDL::FontBase::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.

◆ GetOutline()

int SDL::FontBase::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: FontBase.SetOutline

◆ GetProperties()

PropertiesRef SDL::FontBase::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.

◆ GetScript()

Uint32 SDL::FontBase::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

◆ GetSDF()

bool SDL::FontBase::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: FontBase.SetSDF

◆ GetSize()

float SDL::FontBase::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: FontBase.SetSize; FontBase.SetSizeDPI

◆ GetStringSize() [1/2]

Point SDL::FontBase::GetStringSize ( std::string_view text ) 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.

Returns: return a Point with the width, height.

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::FontBase::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]

Point SDL::FontBase::GetStringSizeWrapped	(	std::string_view	text,
		int	wrap_width
	)		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.

Returns: return a Point with the width, height on success.

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

◆ GetStyleName()

const char * SDL::FontBase::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 destroyed.

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.

◆ GetWeight()

int SDL::FontBase::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::FontBase::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: FontBase.SetWrapAlignment

◆ HasGlyph()

bool SDL::FontBase::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.

◆ IsFixedWidth()

bool SDL::FontBase::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::FontBase::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: FontBase.SetSDF

◆ MeasureString()

void SDL::FontBase::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.

◆ RemoveFallback()

void SDL::FontBase::RemoveFallback ( FontBase & fallback )

inline

This updates any TextBase 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: FontBase.AddFallback; FontBase.ClearFallbacks

◆ RenderGlyph_Blended()

Surface SDL::FontBase::RenderGlyph_Blended	(	Uint32	ch,
		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.

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 FontBase.RenderGlyph_Solid, FontBase.RenderGlyph_Shaded, and FontBase.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: FontBase.RenderGlyph_LCD; FontBase.RenderGlyph_Shaded; FontBase.RenderGlyph_Solid

◆ RenderGlyph_LCD()

Surface SDL::FontBase::RenderGlyph_LCD	(	Uint32	ch,
		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.

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 FontBase.RenderGlyph_Solid, FontBase.RenderGlyph_Shaded, and FontBase.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: FontBase.RenderGlyph_Blended; FontBase.RenderGlyph_Shaded; FontBase.RenderGlyph_Solid

◆ RenderGlyph_Shaded()

Surface SDL::FontBase::RenderGlyph_Shaded	(	Uint32	ch,
		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.

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 FontBase.RenderGlyph_Solid, FontBase.RenderGlyph_Blended, and FontBase.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: FontBase.RenderGlyph_Blended; FontBase.RenderGlyph_LCD; FontBase.RenderGlyph_Solid

◆ RenderGlyph_Solid()

Surface SDL::FontBase::RenderGlyph_Solid	(	Uint32	ch,
		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.

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 FontBase.RenderGlyph_Shaded, FontBase.RenderGlyph_Blended, and FontBase.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: FontBase.RenderGlyph_Blended; FontBase.RenderGlyph_LCD; FontBase.RenderGlyph_Shaded

◆ RenderText_Blended()

Surface SDL::FontBase::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 FontBase.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 FontBase.RenderText_Solid, FontBase.RenderText_Shaded, and FontBase.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: FontBase.RenderText_Blended_Wrapped; FontBase.RenderText_LCD; FontBase.RenderText_Shaded; FontBase.RenderText_Solid

◆ RenderText_Blended_Wrapped()

Surface SDL::FontBase::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 FontBase.RenderText_Solid_Wrapped, FontBase.RenderText_Shaded_Wrapped, and FontBase.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: FontBase.RenderText_Blended; FontBase.RenderText_LCD_Wrapped; FontBase.RenderText_Shaded_Wrapped; FontBase.RenderText_Solid_Wrapped

◆ RenderText_LCD()

Surface SDL::FontBase::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 FontBase.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 FontBase.RenderText_Solid, FontBase.RenderText_Shaded, and FontBase.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: FontBase.RenderText_Blended; FontBase.RenderText_LCD_Wrapped; FontBase.RenderText_Shaded; FontBase.RenderText_Solid

◆ RenderText_LCD_Wrapped()

Surface SDL::FontBase::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 FontBase.RenderText_Solid_Wrapped, FontBase.RenderText_Shaded_Wrapped, and FontBase.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: FontBase.RenderText_Blended_Wrapped; FontBase.RenderText_LCD; FontBase.RenderText_Shaded_Wrapped; FontBase.RenderText_Solid_Wrapped

◆ RenderText_Shaded()

Surface SDL::FontBase::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 FontBase.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 FontBase.RenderText_Solid, FontBase.RenderText_Blended, and FontBase.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: FontBase.RenderText_Blended; FontBase.RenderText_LCD; FontBase.RenderText_Shaded_Wrapped; FontBase.RenderText_Solid

◆ RenderText_Shaded_Wrapped()

Surface SDL::FontBase::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 FontBase.RenderText_Solid_Wrapped, FontBase.RenderText_Blended_Wrapped, and FontBase.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: FontBase.RenderText_Blended_Wrapped; FontBase.RenderText_LCD_Wrapped; FontBase.RenderText_Shaded; FontBase.RenderText_Solid_Wrapped

◆ RenderText_Solid()

Surface SDL::FontBase::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 FontBase.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 FontBase.RenderText_Shaded, FontBase.RenderText_Blended, and FontBase.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: FontBase.RenderText_Blended; FontBase.RenderText_LCD; FontBase.RenderText_Shaded; FontBase.RenderText_Solid; FontBase.RenderText_Solid_Wrapped

◆ RenderText_Solid_Wrapped()

Surface SDL::FontBase::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 FontBase.RenderText_Shaded_Wrapped, FontBase.RenderText_Blended_Wrapped, and FontBase.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: FontBase.RenderText_Blended_Wrapped; FontBase.RenderText_LCD_Wrapped; FontBase.RenderText_Shaded_Wrapped; FontBase.RenderText_Solid

◆ SetDirection()

void SDL::FontBase::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 TextBase 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.

◆ SetHinting()

void SDL::FontBase::SetHinting ( HintingFlags hinting )

inline

This updates any TextBase 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: FontBase.GetHinting

◆ SetKerning()

void SDL::FontBase::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 TextBase 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: FontBase.GetKerning

◆ SetLanguage()

void SDL::FontBase::SetLanguage ( StringParam language_bcp47 )

inline

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

This updates any TextBase 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::FontBase::SetLineSkip ( int lineskip )

inline

This updates any TextBase 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: FontBase.GetLineSkip

◆ SetOutline()

void SDL::FontBase::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 TextBase 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: FontBase.GetOutline

◆ SetScript()

void SDL::FontBase::SetScript ( Uint32 script )

inline

This returns false if SDL_ttf isn't built with HarfBuzz support.

This updates any TextBase 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

◆ SetSDF()

void SDL::FontBase::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 TextBase 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: FontBase.GetSDF

◆ SetSize()

void SDL::FontBase::SetSize ( float ptsize )

inline

This updates any TextBase 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: FontBase.GetSize

◆ SetSizeDPI()

void SDL::FontBase::SetSizeDPI	(	float	ptsize,
		int	hdpi,
		int	vdpi
	)

inline

This updates any TextBase 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: FontBase.GetSize; TTF_GetFontSizeDPI

◆ SetStyle()

void SDL::FontBase::SetStyle ( FontStyleFlags style )

inline

This updates any TextBase 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: FontBase.GetStyle

◆ SetWrapAlignment()

void SDL::FontBase::SetWrapAlignment ( HorizontalAlignment align )

inline

This updates any TextBase 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: FontBase.GetWrapAlignment

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_ttf.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FontBase() [1/3]

◆ FontBase() [2/3]

◆ FontBase() [3/3]

Member Function Documentation

◆ AddFallback()

◆ ClearFallbacks()

◆ GetAscent()

◆ GetDescent()

◆ GetDirection()

◆ GetDPI()

◆ GetFamilyName()

◆ GetGeneration()

◆ GetGlyphImage()

◆ GetGlyphImageForIndex()

◆ GetGlyphKerning()

◆ GetGlyphMetrics()

◆ GetGlyphScript()

◆ GetHeight()

◆ GetHinting()

◆ GetKerning()

◆ GetLineSkip()

◆ GetNumFaces()

◆ GetOutline()

◆ GetProperties()

◆ GetScript()

◆ GetSDF()

◆ GetSize()

◆ GetStringSize() [1/2]

◆ GetStringSize() [2/2]

◆ GetStringSizeWrapped() [1/2]

◆ GetStringSizeWrapped() [2/2]

◆ GetStyle()

◆ GetStyleName()

◆ GetWeight()

◆ GetWrapAlignment()

◆ HasGlyph()

◆ IsFixedWidth()

◆ IsScalable()

◆ MeasureString()

◆ RemoveFallback()

◆ RenderGlyph_Blended()

◆ RenderGlyph_LCD()

◆ RenderGlyph_Shaded()

◆ RenderGlyph_Solid()

◆ RenderText_Blended()

◆ RenderText_Blended_Wrapped()

◆ RenderText_LCD()

◆ RenderText_LCD_Wrapped()

◆ RenderText_Shaded()

◆ RenderText_Shaded_Wrapped()

◆ RenderText_Solid()

◆ RenderText_Solid_Wrapped()

◆ SetDirection()

◆ SetHinting()

◆ SetKerning()

◆ SetLanguage()

◆ SetLineSkip()

◆ SetOutline()

◆ SetScript()

◆ SetSDF()

◆ SetSize()

◆ SetSizeDPI()

◆ SetStyle()

◆ SetWrapAlignment()