SDL::Font Class Reference

The internal structure containing font information. More...

Inheritance diagram for SDL::Font:

Public Member Functions
constexpr	Font ()=default
	Default ctor.
constexpr	Font (const FontRaw resource)
	Constructs from FontParam. More...
constexpr	Font (const Font &other)=delete
	Copy constructor.
constexpr	Font (Font &&other)
	Move constructor.
constexpr	Font (const FontRef &other)=delete
constexpr	Font (FontRef &&other)=delete
	Font (StringParam file, float ptsize)
	Create a font from a file, using a specified point size. More...
	Font (IOStreamParam src, float ptsize, bool closeio=false)
	Create a font from an IOStream, using a specified point size. More...
	Font (PropertiesParam props)
	Create a font with the specified properties. More...
	~Font ()
	Destructor.
Font &	operator= (Font other)
	Assignment operator.
constexpr FontRaw	get () const
	Retrieves underlying FontRaw.
constexpr FontRaw	release ()
	Retrieves underlying FontRaw and clear this.
constexpr auto	operator<=> (const Font &other) const =default
	Comparison.
constexpr bool	operator== (std::nullptr_t _) const
	Comparison.
constexpr	operator bool () const
	Converts to bool.
constexpr	operator FontParam () const
	Converts to FontParam.
void	Close ()
	Dispose of a previously-created font. More...
Font	Copy () const
	Create a copy of an existing font. More...
PropertiesRef	GetProperties ()
	Get the properties associated with a font. More...
Uint32	GetGeneration () const
	Get the font generation. More...
void	AddFallback (FontParam fallback)
	Add a fallback font. More...
void	RemoveFallback (FontParam fallback)
	Remove a fallback font. More...
void	ClearFallbacks ()
	Remove all fallback fonts. More...
void	SetSize (float ptsize)
	Set a font's size dynamically. More...
void	SetSizeDPI (float ptsize, int hdpi, int vdpi)
	Set font size dynamically with target resolutions, in dots per inch. More...
float	GetSize () const
	Get the size of a font. More...
void	GetDPI (int *hdpi, int *vdpi) const
	Get font target resolutions, in dots per inch. More...
void	SetStyle (FontStyleFlags style)
	Set a font's current style. More...
FontStyleFlags	GetStyle () const
	Query a font's current style. More...
void	SetOutline (int outline)
	Set a font's current outline. More...
int	GetOutline () const
	Query a font's current outline. More...
void	SetHinting (HintingFlags hinting)
	Set a font's current hinter setting. More...
int	GetNumFaces () const
	Query the number of faces of a font. More...
HintingFlags	GetHinting () const
	Query a font's current FreeType hinter setting. More...
void	SetSDF (bool enabled)
	Enable Signed Distance Field rendering for a font. More...
bool	GetSDF () const
	Query whether Signed Distance Field rendering is enabled for a font. More...
int	GetWeight () const
	Query a font's weight, in terms of the lightness/heaviness of the strokes. More...
void	SetWrapAlignment (HorizontalAlignment align)
	Set a font's current wrap alignment option. More...
HorizontalAlignment	GetWrapAlignment () const
	Query a font's current wrap alignment option. More...
int	GetHeight () const
	Query the total height of a font. More...
int	GetAscent () const
	Query the offset from the baseline to the top of a font. More...
int	GetDescent () const
	Query the offset from the baseline to the bottom of a font. More...
void	SetLineSkip (int lineskip)
	Set the spacing between lines of text for a font. More...
int	GetLineSkip () const
	Query the spacing between lines of text for a font. More...
void	SetKerning (bool enabled)
	Set if kerning is enabled for a font. More...
bool	GetKerning () const
	Query whether or not kerning is enabled for a font. More...
bool	IsFixedWidth () const
	Query whether a font is fixed-width. More...
bool	IsScalable () const
	Query whether a font is scalable or not. More...
const char *	GetFamilyName () const
	Query a font's family name. More...
const char *	GetStyleName () const
	Query a font's style name. More...
void	SetDirection (Direction direction)
	Set the direction to be used for text shaping by a font. More...
Direction	GetDirection () const
	Get the direction to be used for text shaping by a font. More...
void	SetScript (Uint32 script)
	Set the script to be used for text shaping by a font. More...
Uint32	GetScript () const
	Get the script used for text shaping a font. More...
void	SetLanguage (StringParam language_bcp47)
	Set language to be used for text shaping by a font. More...
bool	HasGlyph (Uint32 ch) const
	Check whether a glyph is provided by the font for a UNICODE codepoint. More...
Surface	GetGlyphImage (Uint32 ch, ImageType *image_type) const
	Get the pixel image for a UNICODE codepoint. More...
Surface	GetGlyphImageForIndex (Uint32 glyph_index, ImageType *image_type) const
	Get the pixel image for a character index. More...
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. More...
int	GetGlyphKerning (Uint32 previous_ch, Uint32 ch) const
	Query the kerning size between the glyphs of two UNICODE codepoints. More...
Point	GetStringSize (std::string_view text) const
	Calculate the dimensions of a rendered string of UTF-8 text. More...
void	GetStringSize (std::string_view text, int *w, int *h) const
	Calculate the dimensions of a rendered string of UTF-8 text. More...
Point	GetStringSizeWrapped (std::string_view text, int wrap_width) const
	Calculate the dimensions of a rendered string of UTF-8 text. More...
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. More...
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. More...
Surface	RenderText_Solid (std::string_view text, Color fg) const
	Render UTF-8 text at fast quality to a new 8-bit surface. More...
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. More...
Surface	RenderGlyph_Solid (Uint32 ch, ColorRaw fg) const
	Render a single 32-bit glyph at fast quality to a new 8-bit surface. More...
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. More...
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. More...
Surface	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	RenderText_Blended (std::string_view text, Color fg) const
	Render UTF-8 text at high quality to a new ARGB surface. More...
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. More...
Surface	RenderGlyph_Blended (Uint32 ch, ColorRaw fg) const
	Render a single UNICODE codepoint at high quality to a new ARGB surface. More...
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. More...
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. More...
Surface	RenderGlyph_LCD (Uint32 ch, ColorRaw fg, ColorRaw bg) const
	Render a single UNICODE codepoint at LCD subpixel quality to a new ARGB surface. More...

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

Detailed Description

Opaque data!

Category:

Resource

Constructor & Destructor Documentation

Font() [1/4]

constexpr SDL::Font::Font ( const FontRaw  resource )

inlineexplicitconstexpr

Parameters

resource

a FontRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

Font() [2/4]

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

Font() [3/4]

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

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.

Postcondition

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

Font() [4/4]

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

Postcondition

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

Member Function Documentation

GetStringSize()

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

GetStringSizeWrapped()

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

---

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

• SDL3pp/SDL3pp_ttf.h