Class reference
FontFile
Inherits Font
Holds font source data and prerendered glyph cache, imported from a dynamic or a 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 a shape used to draw one or more characters in a context-dependent manner. Glyph indices are bound to the specific font data source. Note: If 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.add_theme_font_override("font", f)
$Label.add_theme_font_size_override("font_size", 64)
var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf");
GetNode("Label").AddThemeFontOverride("font", f);
GetNode("Label").AddThemeFontSizeOverride("font_size", 64);
Properties
bool allow_system_fallback = true
bool allow_system_fallback = trueIf set to true, system fonts can be automatically used as fallbacks.
int antialiasing = 1
int antialiasing = 1Font anti-aliasing mode.
PackedByteArray data = PackedByteArray()
PackedByteArray data = PackedByteArray()Contents of the dynamic font source file.
bool disable_embedded_bitmaps = true
bool disable_embedded_bitmaps = trueIf set to true, embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property).
int fixed_size = 0
int fixed_size = 0Font size, used only for the bitmap fonts.
int fixed_size_scale_mode = 0
int fixed_size_scale_mode = 0Scaling mode, used only for the bitmap fonts with fixed_size greater than zero.
String font_name = ""
String font_name = ""Font family name.
int font_stretch = 100
int font_stretch = 100Font stretch amount, compared to a normal width. A percentage value between 50% and 200%.
int font_style = 0
int font_style = 0Font style flags.
int font_weight = 400
int font_weight = 400Weight (boldness) of the font. A value in the 100...999 range, normal font weight is 400, bold font weight is 700.
bool force_autohinter = false
bool force_autohinter = falseIf set to true, auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only (MSDF fonts don't support hinting).
bool generate_mipmaps = false
bool generate_mipmaps = falseIf set to true, generate mipmaps for the font textures.
int hinting = 1
int hinting = 1Font hinting mode. Used by dynamic fonts only.
bool keep_rounding_remainders = true
bool keep_rounding_remainders = trueIf set to true, when aligning glyphs to the pixel boundaries rounding remainders are accumulated to ensure more uniform glyph distribution. This setting has no effect if subpixel positioning is enabled.
bool modulate_color_glyphs = false
bool modulate_color_glyphs = falseIf set to true, color modulation is applied when drawing colored glyphs, otherwise it's applied to the monochrome glyphs only.
int msdf_pixel_range = 16
int msdf_pixel_range = 16The width of the range around the shape between the minimum and maximum representable signed distance. If using font outlines, msdf_pixel_range must be set to at least twice the size of the largest font outline. The default msdf_pixel_range value of 16 allows outline sizes up to 8 to look correct.
int msdf_size = 48
int msdf_size = 48Source font size used to generate MSDF textures. Higher values allow for more precision, but are slower to render and require more memory. Only increase this value if you notice a visible lack of precision in glyph rendering.
bool multichannel_signed_distance_field = false
bool multichannel_signed_distance_field = falseIf set to true, glyphs of all sizes are rendered using single multichannel signed distance field (MSDF) generated from the dynamic font vector data. Since this approach does not rely on rasterizing the font every time its size changes, this allows for resizing the font in real-time without any performance penalty. Text will also not look grainy for Controls that are scaled down (or for Label3Ds viewed from a long distance). As a downside, font hinting is not available with MSDF. The lack of font hinting may result in less crisp and less readable fonts at small sizes. Note: If using font outlines, msdf_pixel_range must be set to at least twice the size of the largest font outline. Note: MSDF font rendering does not render glyphs with overlapping shapes correctly. Overlapping shapes are not valid per the OpenType standard, but are still commonly found in many font files, especially those converted by Google Fonts. To avoid issues with overlapping glyphs, consider downloading the font file directly from the type foundry instead of relying on Google Fonts.
Dictionary opentype_feature_overrides = {}
Dictionary opentype_feature_overrides = {}Font OpenType feature set override.
float oversampling = 0.0
float oversampling = 0.0If set to a positive value, overrides the oversampling factor of the viewport this font is used in. See Viewport.oversampling. This value doesn't override the [code skip-lint]oversampling[/code] parameter of [code skip-lint]draw_*[/code] methods.
String style_name = ""
String style_name = ""Font style name.
int subpixel_positioning = 1
int subpixel_positioning = 1Font glyph subpixel positioning mode. Subpixel positioning provides shaper text and better kerning for smaller font sizes, at the cost of higher memory usage and lower font rasterization speed. Use TextServer.SUBPIXEL_POSITIONING_AUTO to automatically enable it based on the font size.
Methods
void clear_cache()
Removes all font cache entries.
void clear_glyphs(int cache_index, Vector2i size)
int cache_index, Vector2i size)Removes all 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 clear_kerning_map(int cache_index, int size)
int cache_index, int size)Removes all kerning overrides.
void clear_size_cache(int cache_index)
int cache_index)Removes all font sizes from the cache entry.
void clear_textures(int cache_index, Vector2i size)
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
float get_cache_ascent(int cache_index, int size) constReturns the font ascent (number of pixels above the baseline).
int get_cache_count() const
int get_cache_count() constReturns number of the font cache entries.
float get_cache_descent(int cache_index, int size) const
float get_cache_descent(int cache_index, int size) constReturns the font descent (number of pixels below the baseline).
float get_cache_scale(int cache_index, int size) const
float get_cache_scale(int cache_index, int size) constReturns scaling factor of the color bitmap font.
float get_cache_underline_position(int cache_index, int size) const
float get_cache_underline_position(int cache_index, int size) constReturns pixel offset of the underline below the baseline.
float get_cache_underline_thickness(int cache_index, int size) const
float get_cache_underline_thickness(int cache_index, int size) constReturns thickness of the underline in pixels.
int get_char_from_glyph_index(int size, int glyph_index) const
int get_char_from_glyph_index(int size, int glyph_index) constReturns character code associated with glyph_index, or 0 if glyph_index is invalid. See get_glyph_index().
float get_embolden(int cache_index) const
float get_embolden(int cache_index) constReturns embolden strength, if is not equal to zero, emboldens the font outlines. Negative values reduce the outline thickness.
float get_extra_baseline_offset(int cache_index) const
float get_extra_baseline_offset(int cache_index) constReturns extra baseline offset (as a fraction of font height).
int get_extra_spacing(int cache_index, int spacing) const
int get_extra_spacing(int cache_index, int spacing) constReturns spacing for spacing in pixels (not relative to the font size).
int get_face_index(int cache_index) const
int get_face_index(int cache_index) constReturns an active face index in the TrueType / OpenType collection.
Vector2 get_glyph_advance(int cache_index, int size, int glyph) const
Vector2 get_glyph_advance(int cache_index, int size, int glyph) constReturns 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
int get_glyph_index(int size, int char, int variation_selector) constReturns the glyph index of a char, optionally modified by the variation_selector.
PackedInt32Array get_glyph_list(int cache_index, Vector2i size) const
PackedInt32Array get_glyph_list(int cache_index, Vector2i size) constReturns list of rendered glyphs in the cache entry.
Vector2 get_glyph_offset(int cache_index, Vector2i size, int glyph) const
Vector2 get_glyph_offset(int cache_index, Vector2i size, int glyph) constReturns glyph offset from the baseline.
Vector2 get_glyph_size(int cache_index, Vector2i size, int glyph) const
Vector2 get_glyph_size(int cache_index, Vector2i size, int glyph) constReturns glyph size.
int get_glyph_texture_idx(int cache_index, Vector2i size, int glyph) const
int get_glyph_texture_idx(int cache_index, Vector2i size, int glyph) constReturns index of the cache texture containing the glyph.
Rect2 get_glyph_uv_rect(int cache_index, Vector2i size, int glyph) const
Rect2 get_glyph_uv_rect(int cache_index, Vector2i size, int glyph) constReturns rectangle in the cache texture containing the glyph.
Vector2 get_kerning(int cache_index, int size, Vector2i glyph_pair) const
Vector2 get_kerning(int cache_index, int size, Vector2i glyph_pair) constReturns kerning for the pair of glyphs.
Vector2i[] get_kerning_list(int cache_index, int size) const
int cache_index, int size) constReturns list of the kerning overrides.
bool get_language_support_override(String language) const
bool get_language_support_override(String language) constReturns true if support override is enabled for the language.
PackedStringArray get_language_support_overrides() const
PackedStringArray get_language_support_overrides() constReturns list of language support overrides.
bool get_script_support_override(String script) const
bool get_script_support_override(String script) constReturns true if support override is enabled for the script.
PackedStringArray get_script_support_overrides() const
PackedStringArray get_script_support_overrides() constReturns list of script support overrides.
Vector2i[] get_size_cache_list(int cache_index) const
int cache_index) constReturns 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
int get_texture_count(int cache_index, Vector2i size) constReturns number of textures used by font cache entry.
Image get_texture_image(int cache_index, Vector2i size, int texture_index) const
Image get_texture_image(int cache_index, Vector2i size, int texture_index) constReturns a copy of the font cache texture image.
PackedInt32Array get_texture_offsets(int cache_index, Vector2i size, int texture_index) const
PackedInt32Array get_texture_offsets(int cache_index, Vector2i size, int texture_index) constReturns a copy of the array containing glyph packing data.
Transform2D get_transform(int cache_index) const
Transform2D get_transform(int cache_index) constReturns 2D transform, applied to the font outlines, can be used for slanting, flipping and rotating glyphs.
Dictionary get_variation_coordinates(int cache_index) const
Dictionary get_variation_coordinates(int cache_index) constReturns variation coordinates for the specified font cache entry. See Font.get_supported_variation_list() for more info.
int load_bitmap_font(String path)
int 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.
int load_dynamic_font(String path)
int 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)
int cache_index)Removes specified font cache entry.
void remove_glyph(int cache_index, Vector2i size, int 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)
int cache_index, int size, Vector2i glyph_pair)Removes kerning override for the pair of glyphs.
void remove_language_support_override(String language)
String language)Remove language support override.
void remove_script_support_override(String script)
String script)Removes script support override.
void remove_size_cache(int cache_index, Vector2i size)
int cache_index, Vector2i size)Removes specified font size from the cache entry.
void remove_texture(int cache_index, Vector2i size, int texture_index)
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)
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)
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)
int cache_index, int size, float ascent)Sets the font ascent (number of pixels above the baseline).
void set_cache_descent(int cache_index, int size, float descent)
int cache_index, int size, float descent)Sets the font descent (number of pixels below the baseline).
void set_cache_scale(int cache_index, int size, float scale)
int cache_index, int size, float scale)Sets scaling factor of the color bitmap font.
void set_cache_underline_position(int cache_index, int size, float underline_position)
int cache_index, int size, float underline_position)Sets pixel offset of the underline below the baseline.
void set_cache_underline_thickness(int cache_index, int size, float underline_thickness)
int cache_index, int size, float underline_thickness)Sets thickness of the underline in pixels.
void set_embolden(int cache_index, float strength)
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_extra_baseline_offset(int cache_index, float baseline_offset)
int cache_index, float baseline_offset)Sets extra baseline offset (as a fraction of font height).
void set_extra_spacing(int cache_index, int spacing, int value)
int cache_index, int spacing, int value)Sets the spacing for spacing to value in pixels (not relative to the font size).
void set_face_index(int cache_index, int 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)
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)
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)
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)
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)
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)
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)
String language, bool supported)Adds override for Font.is_language_supported().
void set_script_support_override(String script, bool supported)
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)
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)
int cache_index, Vector2i size, int texture_index, PackedInt32Array offset)Sets array containing glyph packing data.
void set_transform(int cache_index, Transform2D 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)
int cache_index, Dictionary variation_coordinates)Sets variation coordinates for the specified font cache entry. See Font.get_supported_variation_list() for more info.