Struct sfml::graphics::Font

#[repr(C)]
pub struct Font { /* private fields */ }

Type for loading and manipulating character fonts.

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

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

Once it is loaded, a 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 Text type, 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 Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a Text is a lightweight object which can combine the glyphs data and metrics of a Font to display any text on a render target. Note that it is also possible to bind several Text instances to the same Font.

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

Apart from loading font files, and passing them to instances of Text, you should normally not have to deal directly with this type. 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 Text. If you need to display text of a certain size, make sure the corresponding bitmap font that supports that size is used.

Implementations

impl Font

pub fn kerning(&self, first: u32, second: u32, character_size: u32) -> f32

Get the kerning value corresponding to a given pair of characters in a font

Arguments

• first - Unicode code point of the first character
• second - Unicode code point of the second character
• characterSize - Character size, in pixels

Return the kerning offset, in pixels

Usage Example

let kerning = font.kerning(0, 0, 32);
assert_eq!(kerning, 0.);

pub fn line_spacing(&self, character_size: u32) -> f32

Get the line spacing value

Arguments

• characterSize - Character size, in pixels

Return the line spacing, in pixels

Usage Example

let line_spacing = font.line_spacing(32);
assert_eq!(line_spacing, 35.);

pub fn glyph(
    &self,
    codepoint: u32,
    character_size: u32,
    bold: bool,
    outline_thickness: f32
) -> Glyph

Get a glyph in a font

Arguments

• codePoint - Unicode code point of the character to get
• characterSize - Character size, in pixels
• bold - Retrieve the bold version or the regular one?

Return the corresponding glyph

Usage Example

let glyph = font.glyph(41, 32, false, 5.);
assert_eq!(glyph.bounds(), Rect::new(0., -23., 17., 39.));

pub fn info(&self) -> Info

Returns the font information.

Usage Example

let font = Font::from_file("examples/resources/sansation.ttf").unwrap();
let font_info = font.info();
assert_eq!(font_info.family, "Sansation");

pub fn underline_position(&self, character_size: u32) -> f32

Returns the position of the underline.

Usage Example

let underline_position = font.underline_position(32);
assert_eq!(underline_position, 3.734375);

pub fn underline_thickness(&self, character_size: u32) -> f32

Returns the thickness of the underline.

Usage Example

let underline_thickness = font.underline_thickness(32);
assert_eq!(underline_thickness, 2.34375);

pub fn from_file(filename: &str) -> Option<SfBox<Self>>

Load 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 know 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 Font object loads a new font or is destroyed.

Usage Example

let font = match Font::from_file("examples/resources/sansation.ttf") {
    Some(font) => font,
    None => {
        panic!("Failed to read font file!");
    }
};

pub unsafe fn from_stream<T: Read + Seek>(stream: &mut T) -> Option<SfBox<Self>>

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

Safety

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

Returns

True if loading succeeded, false if it failed

See also

Font::from_file, Font::from_memory

pub unsafe fn from_memory(memory: &[u8]) -> Option<SfBox<Self>>

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

Safety

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

Returns

True if loading succeeded, false if it failed

See also Font::from_file, Font::from_stream

pub fn texture(&self, character_size: u32) -> &Texture

Get the texture containing the glyphs of a given size in a font

Arguments

• character_size - Character size, in pixels

Usage Example

let texture = font.texture(32);
assert_eq!(texture.size(), Vector2::new(128, 128));

Trait Implementations

impl Debug for Font

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ToOwned for Font

type Owned = SfBox<Font>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.