FontFile¶

Inherits: Font < Resource < RefCounted < Object

Font source data and prerendered glyph cache, imported from dynamic or bitmap font.

Description¶

FontFile contains a set of glyphs to represent Unicode characters imported from a font file, as well as a cache of rasterized glyphs, and a set of fallback Fonts to use.

Use FontVariation to access specific OpenType variation of the font, create simulated bold / slanted version, and draw lines of text.

For more complex text processing, use FontVariation in conjunction with TextLine or TextParagraph.

Supported font formats:

Dynamic font importer: TrueType (.ttf), TrueType collection (.ttc), OpenType (.otf), OpenType collection (.otc), WOFF (.woff), WOFF2 (.woff2), Type 1 (.pfb, .pfm).
Bitmap font importer: AngelCode BMFont (.fnt, .font), text and binary (version 3) format variants.
Monospace image font importer: All supported image formats.

Note: A character is a symbol that represents an item (letter, digit etc.) in an abstract way.

Note: A glyph is a bitmap or shape used to draw a one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source.

Note: If a none of the font data sources contain glyphs for a character used in a string, the character in question will be replaced with a box displaying its hexadecimal code.

var f = load("res://BarlowCondensed-Bold.ttf")
$"Label".set("custom_fonts/font", f)
$"Label".set("custom_fonts/font_size", 64)

var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf");
GetNode("Label").Set("custom_fonts/font", f);
GetNode("Label").Set("custom_font_sizes/font_size", 64);

Properties¶

bool	antialiased	`true`
PackedByteArray	data	`PackedByteArray()`
Font[]	fallbacks	`[]`
int	fixed_size	`0`
String	font_name	`""`
FontStyle	font_style	`0`
bool	force_autohinter	`false`
bool	generate_mipmaps	`false`
Hinting	hinting	`1`
int	msdf_pixel_range	`16`
int	msdf_size	`48`
bool	multichannel_signed_distance_field	`false`
Dictionary	opentype_feature_overrides	`{}`
float	oversampling	`0.0`
String	style_name	`""`
SubpixelPositioning	subpixel_positioning	`1`

Methods¶

void	clear_cache ( )
void	clear_glyphs ( int cache_index, Vector2i size )
void	clear_kerning_map ( int cache_index, int size )
void	clear_size_cache ( int cache_index )
void	clear_textures ( int cache_index, Vector2i size )
float	get_cache_ascent ( int cache_index, int size ) const
int	get_cache_count ( ) const
float	get_cache_descent ( int cache_index, int size ) const
float	get_cache_scale ( int cache_index, int size ) const
float	get_cache_underline_position ( int cache_index, int size ) const
float	get_cache_underline_thickness ( int cache_index, int size ) const
float	get_embolden ( int cache_index ) const
int	get_face_index ( int cache_index ) const
Vector2	get_glyph_advance ( int cache_index, int size, int glyph ) const
int	get_glyph_index ( int size, int char, int variation_selector ) const
Array	get_glyph_list ( int cache_index, Vector2i size ) const
Vector2	get_glyph_offset ( int cache_index, Vector2i size, int glyph ) const
Vector2	get_glyph_size ( int cache_index, Vector2i size, int glyph ) const
int	get_glyph_texture_idx ( int cache_index, Vector2i size, int glyph ) const
Rect2	get_glyph_uv_rect ( int cache_index, Vector2i size, int glyph ) const
Vector2	get_kerning ( int cache_index, int size, Vector2i glyph_pair ) const
Array	get_kerning_list ( int cache_index, int size ) const
bool	get_language_support_override ( String language ) const
PackedStringArray	get_language_support_overrides ( ) const
bool	get_script_support_override ( String script ) const
PackedStringArray	get_script_support_overrides ( ) const
Array	get_size_cache_list ( int cache_index ) const
int	get_texture_count ( int cache_index, Vector2i size ) const
Image	get_texture_image ( int cache_index, Vector2i size, int texture_index ) const
PackedInt32Array	get_texture_offsets ( int cache_index, Vector2i size, int texture_index ) const
Transform2D	get_transform ( int cache_index ) const
Dictionary	get_variation_coordinates ( int cache_index ) const
Error	load_bitmap_font ( String path )
Error	load_dynamic_font ( String path )
void	remove_cache ( int cache_index )
void	remove_glyph ( int cache_index, Vector2i size, int glyph )
void	remove_kerning ( int cache_index, int size, Vector2i glyph_pair )
void	remove_language_support_override ( String language )
void	remove_script_support_override ( String script )
void	remove_size_cache ( int cache_index, Vector2i size )
void	remove_texture ( int cache_index, Vector2i size, int texture_index )
void	render_glyph ( int cache_index, Vector2i size, int index )
void	render_range ( int cache_index, Vector2i size, int start, int end )
void	set_cache_ascent ( int cache_index, int size, float ascent )
void	set_cache_descent ( int cache_index, int size, float descent )
void	set_cache_scale ( int cache_index, int size, float scale )
void	set_cache_underline_position ( int cache_index, int size, float underline_position )
void	set_cache_underline_thickness ( int cache_index, int size, float underline_thickness )
void	set_embolden ( int cache_index, float strength )
void	set_face_index ( int cache_index, int face_index )
void	set_glyph_advance ( int cache_index, int size, int glyph, Vector2 advance )
void	set_glyph_offset ( int cache_index, Vector2i size, int glyph, Vector2 offset )
void	set_glyph_size ( int cache_index, Vector2i size, int glyph, Vector2 gl_size )
void	set_glyph_texture_idx ( int cache_index, Vector2i size, int glyph, int texture_idx )
void	set_glyph_uv_rect ( int cache_index, Vector2i size, int glyph, Rect2 uv_rect )
void	set_kerning ( int cache_index, int size, Vector2i glyph_pair, Vector2 kerning )
void	set_language_support_override ( String language, bool supported )
void	set_script_support_override ( String script, bool supported )
void	set_texture_image ( int cache_index, Vector2i size, int texture_index, Image image )
void	set_texture_offsets ( int cache_index, Vector2i size, int texture_index, PackedInt32Array offset )
void	set_transform ( int cache_index, Transform2D transform )
void	set_variation_coordinates ( int cache_index, Dictionary variation_coordinates )

Property Descriptions¶

bool antialiased

Default	`true`
Setter	set_antialiased(value)
Getter	is_antialiased()

If set to true, font 8-bit anitialiased glyph rendering is supported and enabled.

PackedByteArray data

Default	`PackedByteArray()`
Setter	set_data(value)
Getter	get_data()

Contents of the dynamic font source file.

Font[] fallbacks

Default	`[]`
Setter	set_fallbacks(value)
Getter	get_fallbacks()

Array of fallback Fonts.

int fixed_size

Default	`0`
Setter	set_fixed_size(value)
Getter	get_fixed_size()

Font size, used only for the bitmap fonts.

String font_name

Default	`""`
Setter	set_font_name(value)
Getter	get_font_name()

Font family name.

FontStyle font_style

Default	`0`
Setter	set_font_style(value)
Getter	get_font_style()

Font style flags, see FontStyle.

bool force_autohinter

Default	`false`
Setter	set_force_autohinter(value)
Getter	is_force_autohinter()

If set to true, auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only.

bool generate_mipmaps

Default	`false`
Setter	set_generate_mipmaps(value)
Getter	get_generate_mipmaps()

If set to true, generate mipmaps for the font textures.

Hinting hinting

Default	`1`
Setter	set_hinting(value)
Getter	get_hinting()

Font hinting mode. Used by dynamic fonts only.

int msdf_pixel_range

Default	`16`
Setter	set_msdf_pixel_range(value)
Getter	get_msdf_pixel_range()

The width of the range around the shape between the minimum and maximum representable signed distance.

int msdf_size

Default	`48`
Setter	set_msdf_size(value)
Getter	get_msdf_size()

Source font size used to generate MSDF textures.

bool multichannel_signed_distance_field

Default	`false`
Setter	set_multichannel_signed_distance_field(value)
Getter	is_multichannel_signed_distance_field()

If set to true, glyphs of all sizes are rendered using single multichannel signed distance field generated from the dynamic font vector data.

Dictionary opentype_feature_overrides

Default	`{}`
Setter	set_opentype_feature_overrides(value)
Getter	get_opentype_feature_overrides()

Font OpenType feature set override.

float oversampling

Default	`0.0`
Setter	set_oversampling(value)
Getter	get_oversampling()

Font oversampling factor, if set to 0.0 global oversampling factor is used instead. Used by dynamic fonts only.

String style_name

Default	`""`
Setter	set_font_style_name(value)
Getter	get_font_style_name()

Font style name.

SubpixelPositioning subpixel_positioning

Default	`1`
Setter	set_subpixel_positioning(value)
Getter	get_subpixel_positioning()

Font glyph sub-pixel positioning mode. Subpixel positioning provides shaper text and better kerning for smaller font sizes, at the cost of memory usage and font rasterization speed. Use TextServer.SUBPIXEL_POSITIONING_AUTO to automatically enable it based on the font size.

Method Descriptions¶

void clear_cache ( )

Removes all font cache entries.

void clear_glyphs ( int cache_index, Vector2i size )

Removes all rendered glyphs information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use remove_texture to remove them manually.

void clear_kerning_map ( int cache_index, int size )

Removes all kerning overrides.

void clear_size_cache ( int cache_index )

Removes all font sizes from the cache entry

void clear_textures ( int cache_index, Vector2i size )

Removes all textures from font cache entry.

Note: This function will not remove glyphs associated with the texture, use remove_glyph to remove them manually.

float get_cache_ascent ( int cache_index, int size ) const

Returns the font ascent (number of pixels above the baseline).

int get_cache_count ( ) const

Returns number of the font cache entries.

float get_cache_descent ( int cache_index, int size ) const

float get_cache_scale ( int cache_index, int size ) const

float get_cache_underline_position ( int cache_index, int size ) const

float get_cache_underline_thickness ( int cache_index, int size ) const

float get_embolden ( int cache_index ) const

Returns embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.

int get_face_index ( int cache_index ) const

Recturns an active face index in the TrueType / OpenType collection.

Vector2 get_glyph_advance ( int cache_index, int size, int glyph ) const

Returns glyph advance (offset of the next glyph).

Note: Advance for glyphs outlines is the same as the base glyph advance and is not saved.

int get_glyph_index ( int size, int char, int variation_selector ) const

Returns the glyph index of a char, optionally modified by the variation_selector.

Array get_glyph_list ( int cache_index, Vector2i size ) const

Returns list of rendered glyphs in the cache entry.

Vector2 get_glyph_offset ( int cache_index, Vector2i size, int glyph ) const

Returns glyph offset from the baseline.

Vector2 get_glyph_size ( int cache_index, Vector2i size, int glyph ) const

Returns glyph size.

int get_glyph_texture_idx ( int cache_index, Vector2i size, int glyph ) const

Returns index of the cache texture containing the glyph.

Rect2 get_glyph_uv_rect ( int cache_index, Vector2i size, int glyph ) const

Returns rectangle in the cache texture containing the glyph.

Vector2 get_kerning ( int cache_index, int size, Vector2i glyph_pair ) const

Returns kerning for the pair of glyphs.

Array get_kerning_list ( int cache_index, int size ) const

Returns list of the kerning overrides.

bool get_language_support_override ( String language ) const

Returns true if support override is enabled for the language.

PackedStringArray get_language_support_overrides ( ) const

Returns list of language support overrides.

bool get_script_support_override ( String script ) const

Returns true if support override is enabled for the script.

PackedStringArray get_script_support_overrides ( ) const

Returns list of script support overrides.

Array get_size_cache_list ( int cache_index ) const

Returns list of the font sizes in the cache. Each size is Vector2i with font size and outline size.

int get_texture_count ( int cache_index, Vector2i size ) const

Returns number of textures used by font cache entry.

Image get_texture_image ( int cache_index, Vector2i size, int texture_index ) const

Returns a copy of the font cache texture image.

PackedInt32Array get_texture_offsets ( int cache_index, Vector2i size, int texture_index ) const

Returns a copy of the array containing the first free pixel in the each column of texture. Should be the same size as texture width or empty.

Transform2D get_transform ( int cache_index ) const

Returns 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs.

Dictionary get_variation_coordinates ( int cache_index ) const

Returns variation coordinates for the specified font cache entry. See Font.get_supported_variation_list for more info.

Error load_bitmap_font ( String path )

Loads an AngelCode BMFont (.fnt, .font) bitmap font from file path.

Warning: This method should only be used in the editor or in cases when you need to load external fonts at run-time, such as fonts located at the user:// directory.

Error load_dynamic_font ( String path )

Loads a TrueType (.ttf), OpenType (.otf), WOFF (.woff), WOFF2 (.woff2) or Type 1 (.pfb, .pfm) dynamic font from file path.

Warning: This method should only be used in the editor or in cases when you need to load external fonts at run-time, such as fonts located at the user:// directory.

void remove_cache ( int cache_index )

Removes specified font cache entry.

void remove_glyph ( int cache_index, Vector2i size, int glyph )

Removes specified rendered glyph information from the cache entry.

Note: This function will not remove textures associated with the glyphs, use remove_texture to remove them manually.

void remove_kerning ( int cache_index, int size, Vector2i glyph_pair )

Removes kerning override for the pair of glyphs.

void remove_language_support_override ( String language )

Remove language support override.

void remove_script_support_override ( String script )

Removes script support override.

void remove_size_cache ( int cache_index, Vector2i size )

Removes specified font size from the cache entry.

void remove_texture ( int cache_index, Vector2i size, int texture_index )

Removes specified texture from the cache entry.

Note: This function will not remove glyphs associated with the texture. Remove them manually using remove_glyph.

void render_glyph ( int cache_index, Vector2i size, int index )

Renders specified glyph to the font cache texture.

void render_range ( int cache_index, Vector2i size, int start, int end )

Renders the range of characters to the font cache texture.

void set_cache_ascent ( int cache_index, int size, float ascent )

void set_cache_descent ( int cache_index, int size, float descent )

void set_cache_scale ( int cache_index, int size, float scale )

void set_cache_underline_position ( int cache_index, int size, float underline_position )

void set_cache_underline_thickness ( int cache_index, int size, float underline_thickness )

void set_embolden ( int cache_index, float strength )

Sets embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.

void set_face_index ( int cache_index, int face_index )

Sets an active face index in the TrueType / OpenType collection.

void set_glyph_advance ( int cache_index, int size, int glyph, Vector2 advance )

Sets glyph advance (offset of the next glyph).

Note: Advance for glyphs outlines is the same as the base glyph advance and is not saved.

void set_glyph_offset ( int cache_index, Vector2i size, int glyph, Vector2 offset )

Sets glyph offset from the baseline.

void set_glyph_size ( int cache_index, Vector2i size, int glyph, Vector2 gl_size )

Sets glyph size.

void set_glyph_texture_idx ( int cache_index, Vector2i size, int glyph, int texture_idx )

Sets index of the cache texture containing the glyph.

void set_glyph_uv_rect ( int cache_index, Vector2i size, int glyph, Rect2 uv_rect )

Sets rectangle in the cache texture containing the glyph.

void set_kerning ( int cache_index, int size, Vector2i glyph_pair, Vector2 kerning )

Sets kerning for the pair of glyphs.

void set_language_support_override ( String language, bool supported )

Adds override for Font.is_language_supported.

void set_script_support_override ( String script, bool supported )

Adds override for Font.is_script_supported.

void set_texture_image ( int cache_index, Vector2i size, int texture_index, Image image )

Sets font cache texture image.

void set_texture_offsets ( int cache_index, Vector2i size, int texture_index, PackedInt32Array offset )

Sets array containing the first free pixel in the each column of texture. Should be the same size as texture width or empty (for the fonts without dynamic glyph generation support).

void set_transform ( int cache_index, Transform2D transform )

Sets 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs.

void set_variation_coordinates ( int cache_index, Dictionary variation_coordinates )

Sets variation coordinates for the specified font cache entry. See Font.get_supported_variation_list for more info.