SFML 3.1.0
Loading...
Searching...
No Matches
Classes | Public Member Functions | Friends | List of all members
sf::Font Class Reference
Graphics module

Class for loading and manipulating character fonts. More...

`#include <SFML/Graphics/Font.hpp>`

## Classes
struct | Info
| Holds various information about a font. More...

## Public Member Functions
| Font ()=default
| Default constructor.
| Font (const std::filesystem::path &filename)
| Construct the font from a file.
| Font (const void *data, std::size_t sizeInBytes)
| Construct the font from a file in memory.
| Font (InputStream &stream)
| Construct the font from a custom stream.
bool | openFromFile (const std::filesystem::path &filename)
| Open the font from a file.
bool | openFromMemory (const void *data, std::size_t sizeInBytes)
| Open the font from a file in memory.
bool | openFromStream (InputStream &stream)
| Open the font from a custom stream.
const Info & | getInfo () const
| Get the font information.
const Glyph & | getGlyphById (std::uint32_t id, unsigned int characterSize, bool bold, float outlineThickness=0) const
| Retrieve a glyph of the font by glyph ID.
const Glyph & | getGlyph (char32_t codePoint, unsigned int characterSize, bool bold, float outlineThickness=0) const
| Retrieve a glyph of the font.
bool | hasGlyph (char32_t codePoint) const
| Determine if this font has a glyph representing the requested code point.
float | getKerning (std::uint32_t first, std::uint32_t second, unsigned int characterSize, bool bold=false) const
| Get the kerning offset of two glyphs.
float | getKerning (char32_t first, char32_t second, unsigned int characterSize, bool bold=false) const
| Get the kerning offset of two glyphs.
float | getAscent (unsigned int characterSize) const
| Get the ascent.
float | getDescent (unsigned int characterSize) const
| Get the descent.
float | getLineSpacing (unsigned int characterSize) const
| Get the line spacing.
float | getUnderlinePosition (unsigned int characterSize) const
| Get the position of the underline.
float | getUnderlineThickness (unsigned int characterSize) const
| Get the thickness of the underline.
const Texture & | getTexture (unsigned int characterSize) const
| Retrieve the texture containing the loaded glyphs of a certain size.
void | setSmooth (bool smooth)
| Enable or disable the smooth filter.
bool | isSmooth () const
| Tell whether the smooth filter is enabled or not.

## Friends
class | Text

## Detailed Description

Class for loading and manipulating character fonts.

Fonts can be opened from a file, from memory or from a custom stream, and supports the most common types of fonts.

See the openFromFile function for the complete list of supported formats.

Once it is opened, a sf::Font instance provides three types of information about the font:

- Global metrics, such as the line spacing
- Per-glyph metrics, such as bounding box or kerning
- Pixel representation of glyphs

Fonts alone are not very useful: they hold the font data but cannot make anything useful of it. To do so you need to use the sf::Text class, which is able to properly output text with several options such as character size, style, color, position, rotation, etc. This separation allows more flexibility and better performances: indeed a sf::Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a sf::Text is a lightweight object which can combine the glyphs data and metrics of a sf::Font to display any text on a render target. Note that it is also possible to bind several sf::Text instances to the same sf::Font.

It is important to note that the sf::Text instance doesn't copy the font that it uses, it only keeps a reference to it. Thus, a sf::Font must not be destructed while it is used by a sf::Text (i.e. never write a function that uses a local sf::Font instance for creating a text).

Usage example:

// Open a new font
const sf::Font font("arial.ttf");
// Create a text which uses our font
sf::Text text1(font);
text1.setCharacterSize(30);
text1.setStyle(sf::Text::Regular);
// Create another text using the same font, but with different parameters
sf::Text text2(font);
text2.setCharacterSize(50);
text2.setStyle(sf::Text::Italic);
sf::Font
Class for loading and manipulating character fonts.
Definition Font.hpp:58
sf::Text
Graphical text that can be drawn to a render target.
Definition Text.hpp:61
sf::Text::Regular
@ Regular
Regular characters, no style.
Definition Text.hpp:69
sf::Text::Italic
@ Italic
Italic characters.
Definition Text.hpp:71

Apart from opening font files, and passing them to instances of sf::Text, you should normally not have to deal directly with this class. However, it may be useful to access the font metrics or rasterized glyphs for advanced usage.

Note that if the font is a bitmap font, it is not scalable, thus not all requested sizes will be available to use. This needs to be taken into consideration when using sf::Text. If you need to display text of a certain size, make sure the corresponding bitmap font that supports that size is used.

See also
  sf::Text

Definition at line 57 of file Font.hpp.

## Constructor & Destructor Documentation

## ◆ Font() [1/4]

sf::Font::Font | ( |  | ) |
| default

Default constructor.

Construct an empty font that does not contain any glyphs.

## ◆ Font() [2/4]

sf::Font::Font | ( | const std::filesystem::path & | filename | ) |
| explicit

Construct the font from a file.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function knows nothing about the standard fonts installed on the user's system, thus you can't load them directly.

Warning
  SFML cannot preload all the font data in this function, so the file has to remain accessible until the sf::Font object opens a new font or is destroyed.

Parameters

  filename | Path of the font file to open

Exceptions

  sf::Exception | if opening was unsuccessful

See also
  openFromFile, openFromMemory, openFromStream

## ◆ Font() [3/4]

sf::Font::Font | ( | const void * | data,
|  | std::size_t | sizeInBytes )

Construct the font from a file in memory.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning
  SFML cannot preload all the font data in this function, so the buffer pointed by data has to remain valid until the sf::Font object opens a new font or is destroyed.

Parameters

  data | Pointer to the file data in memory
  sizeInBytes | Size of the data to load, in bytes

Exceptions

  sf::Exception | if loading was unsuccessful

See also
  openFromFile, openFromMemory, openFromStream

## ◆ Font() [4/4]

sf::Font::Font | ( | InputStream & | stream | ) |
| explicit

Construct the font from a custom stream.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Warning: SFML cannot preload all the font data in this function, so the contents of stream have to remain valid as long as the font is used.

Warning
  SFML cannot preload all the font data in this function, so the stream has to remain accessible until the sf::Font object opens a new font or is destroyed.

Parameters

  stream | Source stream to read from

Exceptions

  sf::Exception | if loading was unsuccessful

See also
  openFromFile, openFromMemory, openFromStream

## Member Function Documentation

## ◆ getAscent()

float sf::Font::getAscent | ( | unsigned int | characterSize | ) | const
| nodiscard

Get the ascent.

The ascent is the largest distance between the baseline and the top of all glyphs in the font.

Be aware that there is no uniform definition of how the ascent is calculated. It can vary from font to font.

Parameters

  characterSize | Reference character size

Returns
  Ascent, in pixels

## ◆ getDescent()

float sf::Font::getDescent | ( | unsigned int | characterSize | ) | const
| nodiscard

Get the descent.

The descent is the largest distance between the baseline and the bottom of all glyphs in the font.

Be aware that there is no uniform definition of how the descent is calculated. It can vary from font to font.

The descent shares the same coordinate system as the ascent. This means that it will be negative for distances below the baseline.

Parameters

  characterSize | Reference character size

Returns
  Descent, in pixels

## ◆ getGlyph()

const Glyph & sf::Font::getGlyph | ( | char32_t | codePoint,
|  | unsigned int | characterSize,
|  | bool | bold,
|  | float | outlineThickness = 0 ) const
| nodiscard

Retrieve a glyph of the font.

If the font is a bitmap font, not all character sizes might be available. If the glyph is not available at the requested size, an empty glyph is returned.

You may want to use hasGlyph to determine if the glyph exists before requesting it. If the glyph does not exist, a font specific default is returned.

Be aware that using a negative value for the outline thickness will cause distorted rendering.

Parameters

  codePoint | Unicode code point of the character to get
  characterSize | Reference character size
  bold | Retrieve the bold version or the regular one?
  outlineThickness | Thickness of outline (when != 0 the glyph will not be filled)

Returns
  The glyph corresponding to codePoint and characterSize

## ◆ getGlyphById()

const Glyph & sf::Font::getGlyphById | ( | std::uint32_t | id,
|  | unsigned int | characterSize,
|  | bool | bold,
|  | float | outlineThickness = 0 ) const
| nodiscard

Retrieve a glyph of the font by glyph ID.

If the font is a bitmap font, not all character sizes might be available. If the glyph is not available at the requested size, an empty glyph is returned.

This function is only useful for getting the glyphs returned in the data from calling shape.

Be aware that using a negative value for the outline thickness will cause distorted rendering.

Parameters

  id | ID of the glyph to get
  characterSize | Reference character size
  bold | Retrieve the bold version or the regular one?
  outlineThickness | Thickness of outline (when != 0 the glyph will not be filled)

Returns
  The glyph corresponding to id and characterSize

## ◆ getInfo()

const Info & sf::Font::getInfo | ( |  | ) | const
| nodiscard

Get the font information.

Returns
  A structure that holds the font information

## ◆ getKerning() [1/2]

float sf::Font::getKerning | ( | char32_t | first,
|  | char32_t | second,
|  | unsigned int | characterSize,
|  | bool | bold = false ) const
| nodiscard

Get the kerning offset of two glyphs.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more "natural". For example, the pair "AV" have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

Parameters

  first | Unicode code point of the first character
  second | Unicode code point of the second character
  characterSize | Reference character size
  bold | Retrieve the bold version or the regular one?

Returns
  Kerning value for first and second, in pixels

## ◆ getKerning() [2/2]

float sf::Font::getKerning | ( | std::uint32_t | first,
|  | std::uint32_t | second,
|  | unsigned int | characterSize,
|  | bool | bold = false ) const
| nodiscard

Get the kerning offset of two glyphs.

Deprecated
  Use the getKerning(char32_t, char32_t, unsigned int, bool) overload instead.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more "natural". For example, the pair "AV" have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

Parameters

  first | Unicode code point of the first character
  second | Unicode code point of the second character
  characterSize | Reference character size
  bold | Retrieve the bold version or the regular one?

Returns
  Kerning value for first and second, in pixels

## ◆ getLineSpacing()

float sf::Font::getLineSpacing | ( | unsigned int | characterSize | ) | const
| nodiscard

Get the line spacing.

Line spacing is the vertical offset to apply between two consecutive lines of text.

Parameters

  characterSize | Reference character size

Returns
  Line spacing, in pixels

## ◆ getTexture()

const Texture & sf::Font::getTexture | ( | unsigned int | characterSize | ) | const
| nodiscard

Retrieve the texture containing the loaded glyphs of a certain size.

The contents of the returned texture changes as more glyphs are requested, thus it is not very relevant. It is mainly used internally by sf::Text.

Parameters

  characterSize | Reference character size

Returns
  Texture containing the glyphs of the requested size

## ◆ getUnderlinePosition()

float sf::Font::getUnderlinePosition | ( | unsigned int | characterSize | ) | const
| nodiscard

Get the position of the underline.

Underline position is the vertical offset to apply between the baseline and the underline.

Parameters

  characterSize | Reference character size

Returns
  Underline position, in pixels

See also
  getUnderlineThickness

## ◆ getUnderlineThickness()

float sf::Font::getUnderlineThickness | ( | unsigned int | characterSize | ) | const
| nodiscard

Get the thickness of the underline.

Underline thickness is the vertical size of the underline.

Parameters

  characterSize | Reference character size

Returns
  Underline thickness, in pixels

See also
  getUnderlinePosition

## ◆ hasGlyph()

bool sf::Font::hasGlyph | ( | char32_t | codePoint | ) | const
| nodiscard

Determine if this font has a glyph representing the requested code point.

Most fonts only include a very limited selection of glyphs from specific Unicode subsets, like Latin, Cyrillic, or Asian characters.

While code points without representation will return a font specific default character, it might be useful to verify whether specific code points are included to determine whether a font is suited to display text in a specific language.

Parameters

  codePoint | Unicode code point to check

Returns
  true if the codepoint has a glyph representation, false otherwise

## ◆ isSmooth()

bool sf::Font::isSmooth | ( |  | ) | const
| nodiscard

Tell whether the smooth filter is enabled or not.

Returns
  true if smoothing is enabled, false if it is disabled

See also
  setSmooth

## ◆ openFromFile()

bool sf::Font::openFromFile | ( | const std::filesystem::path & | filename | ) |
| nodiscard

Open the font from a file.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function knows nothing about the standard fonts installed on the user's system, thus you can't load them directly.

Warning
  SFML cannot preload all the font data in this function, so the file has to remain accessible until the sf::Font object opens a new font or is destroyed.

Parameters

  filename | Path of the font file to load

Returns
  true if opening succeeded, false if it failed

See also
  openFromMemory, openFromStream

## ◆ openFromMemory()

bool sf::Font::openFromMemory | ( | const void * | data,
|  | std::size_t | sizeInBytes )
| nodiscard

Open the font from a file in memory.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning
  SFML cannot preload all the font data in this function, so the buffer pointed by data has to remain valid until the sf::Font object opens a new font or is destroyed.

Parameters

  data | Pointer to the file data in memory
  sizeInBytes | Size of the data to load, in bytes

Returns
  true if opening succeeded, false if it failed

See also
  openFromFile, openFromStream

## ◆ openFromStream()

bool sf::Font::openFromStream | ( | InputStream & | stream | ) |
| nodiscard

Open the font from a custom stream.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning
  SFML cannot preload all the font data in this function, so the stream has to remain accessible until the sf::Font object opens a new font or is destroyed.

Parameters

  stream | Source stream to read from

Returns
  true if opening succeeded, false if it failed

See also
  openFromFile, openFromMemory

## ◆ setSmooth()

void sf::Font::setSmooth | ( | bool | smooth | ) |

Enable or disable the smooth filter.

When the filter is activated, the font appears smoother so that pixels are less noticeable. However if you want the font to look exactly the same as its source file, you should disable it. The smooth filter is enabled by default.

Parameters

  smooth | true to enable smoothing, false to disable it

See also
  isSmooth

## Friends And Related Symbol Documentation

## ◆ Text

friend class Text
| friend

Definition at line 446 of file Font.hpp.

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

- Font.hpp