class SF::Font
- SF::Font
- Reference
- Object
Overview
Class 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 #load_from_file
function for the complete list of supported formats.
Once it is loaded, 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:
# Load a new font from file
font = SF::Font.from_file("arial.ttf")
# Create a text which uses our font
text1 = SF::Text.new("text", font, 30)
# Create another text using the same font, but with different parameters
text2 = SF::Text.new
text2.font = font
text2.character_size = 50
text2.style = SF::Text::Italic
Apart from loading 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
Defined in:
graphics/obj.crConstructors
-
.from_file(*args, **kwargs) : self
Shorthand for
font = Font.new; font.load_from_file(...); font
-
.from_memory(*args, **kwargs) : self
Shorthand for
font = Font.new; font.load_from_memory(...); font
-
.from_stream(*args, **kwargs) : self
Shorthand for
font = Font.new; font.load_from_stream(...); font
-
.new
Default constructor
Instance Method Summary
-
#dup : Font
Returns a shallow copy of this object.
-
#finalize
Destructor
-
#get_glyph(code_point : Int, character_size : Int, bold : Bool, outline_thickness : Number = 0) : Glyph
Retrieve a glyph of the font
-
#get_kerning(first : Int, second : Int, character_size : Int) : Float32
Get the kerning offset of two glyphs
-
#get_line_spacing(character_size : Int) : Float32
Get the line spacing
-
#get_texture(character_size : Int) : Texture
Retrieve the texture containing the loaded glyphs of a certain size
-
#get_underline_position(character_size : Int) : Float32
Get the position of the underline
-
#get_underline_thickness(character_size : Int) : Float32
Get the thickness of the underline
-
#info : Font::Info
Get the font information
-
#load_from_file(filename : String) : Bool
Load the font from a file
-
#load_from_memory(data : Slice) : Bool
Load the font from a file in memory
-
#load_from_stream(stream : InputStream) : Bool
Load the font from a custom stream
Constructor Detail
Instance Method Detail
Returns a shallow copy of this object.
This allocates a new object and copies the contents of
self
into it.
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.
Be aware that using a negative value for the outline thickness will cause distorted rendering.
- code_point - Unicode code point of the character to get
- character_size - Reference character size
- bold - Retrieve the bold version or the regular one?
- outline_thickness - Thickness of outline (when != 0 the glyph will not be filled)
Returns: The glyph corresponding to code_point and character_size
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.
- first - Unicode code point of the first character
- second - Unicode code point of the second character
- character_size - Reference character size
Returns: Kerning value for first and second, in pixels
Get the line spacing
Line spacing is the vertical offset to apply between two consecutive lines of text.
- character_size - Reference character size
Returns: Line spacing, in pixels
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
.
- character_size - Reference character size
Returns: Texture containing the glyphs of the requested size
Get the position of the underline
Underline position is the vertical offset to apply between the baseline and the underline.
- character_size - Reference character size
Returns: Underline position, in pixels
See also: underline_thickness
Get the thickness of the underline
Underline thickness is the vertical size of the underline.
- character_size - Reference character size
Returns: Underline thickness, in pixels
See also: underline_position
Get the font information
Returns: A structure that holds the font information
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 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 loads a new font or is destroyed.
- filename - Path of the font file to load
Returns: True if loading succeeded, false if it failed
See also: #load_from_memory
, #load_from_stream
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.
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 loads a new font or
is destroyed.
- data - Slice containing the file data in memory
Returns: True if loading succeeded, false if it failed
See also: #load_from_file
, #load_from_stream
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.
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 loads a new font or is destroyed.
- stream - Source stream to read from
Returns: True if loading succeeded, false if it failed
See also: #load_from_file
, #load_from_memory