Index · Object → RefCounted → Resource → Font → FontFile

FontFile

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

Class 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)

Properties

var allow_system_fallback: bool = true

If set to true, system fonts can be automatically used as fallbacks.

var antialiasing: TextServer.FontAntialiasing = 1

Font anti-aliasing mode.

var data: PackedByteArray = PackedByteArray()

Contents of the dynamic font source file.

var disable_embedded_bitmaps: bool = true

If set to true, embedded font bitmap loading is disabled (bitmap-only and color fonts ignore this property).

var fixed_size: int = 0

Font size, used only for the bitmap fonts.

var fixed_size_scale_mode: TextServer.FixedSizeScaleMode = 0

Scaling mode, used only for the bitmap fonts with fixed_size greater than zero.

var font_name: String = ""

Font family name.

var font_stretch: int = 100

Font stretch amount, compared to a normal width. A percentage value between 50% and 200%.

var font_style: TextServer.FontStyle = 0

Font style flags.

var font_weight: int = 400

Weight (boldness) of the font. A value in the 100...999 range, normal font weight is 400, bold font weight is 700.

var force_autohinter: bool = false

If 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).

var generate_mipmaps: bool = false

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

var hinting: TextServer.Hinting = 1

Font hinting mode. Used by dynamic fonts only.

var keep_rounding_remainders: bool = true

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

var modulate_color_glyphs: bool = false

If set to true, color modulation is applied when drawing colored glyphs, otherwise it's applied to the monochrome glyphs only.

var msdf_pixel_range: int = 16

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

var msdf_size: int = 48

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

var multichannel_signed_distance_field: bool = false

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

var opentype_feature_overrides: Dictionary = {}

Font OpenType feature set override.

var oversampling: float = 0.0

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

var style_name: String = ""

Font style name.

var subpixel_positioning: TextServer.SubpixelPositioning = 1

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

Inherited from Font (1)
var fallbacks: Font[] = []
Inherited from Resource (4)

Methods

func clear_cache() -> void

Removes all font cache entries.

func clear_glyphs(cache_index: int, size: Vector2i) -> void

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.

func clear_kerning_map(cache_index: int, size: int) -> void

Removes all kerning overrides.

func clear_size_cache(cache_index: int) -> void

Removes all font sizes from the cache entry.

func clear_textures(cache_index: int, size: Vector2i) -> void

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.

func get_cache_ascent(cache_index: int, size: int) -> float

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

func get_cache_count() -> int

Returns number of the font cache entries.

func get_cache_descent(cache_index: int, size: int) -> float

Returns the font descent (number of pixels below the baseline).

func get_cache_scale(cache_index: int, size: int) -> float

Returns scaling factor of the color bitmap font.

func get_cache_underline_position(cache_index: int, size: int) -> float

Returns pixel offset of the underline below the baseline.

func get_cache_underline_thickness(cache_index: int, size: int) -> float

Returns thickness of the underline in pixels.

func get_char_from_glyph_index(size: int, glyph_index: int) -> int

Returns character code associated with glyph_index, or 0 if glyph_index is invalid. See get_glyph_index().

func get_embolden(cache_index: int) -> float

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

func get_extra_baseline_offset(cache_index: int) -> float

Returns extra baseline offset (as a fraction of font height).

func get_extra_spacing(cache_index: int, spacing: TextServer.SpacingType) -> int

Returns spacing for spacing in pixels (not relative to the font size).

func get_face_index(cache_index: int) -> int

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

func get_glyph_advance(cache_index: int, size: int, glyph: int) -> Vector2

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.

func get_glyph_index(size: int, char: int, variation_selector: int) -> int

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

func get_glyph_list(cache_index: int, size: Vector2i) -> PackedInt32Array

Returns list of rendered glyphs in the cache entry.

func get_glyph_offset(cache_index: int, size: Vector2i, glyph: int) -> Vector2

Returns glyph offset from the baseline.

func get_glyph_size(cache_index: int, size: Vector2i, glyph: int) -> Vector2

Returns glyph size.

func get_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int) -> int

Returns index of the cache texture containing the glyph.

func get_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int) -> Rect2

Returns rectangle in the cache texture containing the glyph.

func get_kerning(cache_index: int, size: int, glyph_pair: Vector2i) -> Vector2

Returns kerning for the pair of glyphs.

func get_kerning_list(cache_index: int, size: int) -> Vector2i[]

Returns list of the kerning overrides.

func get_language_support_override(language: String) -> bool

Returns true if support override is enabled for the language.

func get_language_support_overrides() -> PackedStringArray

Returns list of language support overrides.

func get_script_support_override(script: String) -> bool

Returns true if support override is enabled for the script.

func get_script_support_overrides() -> PackedStringArray

Returns list of script support overrides.

func get_size_cache_list(cache_index: int) -> Vector2i[]

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

func get_texture_count(cache_index: int, size: Vector2i) -> int

Returns number of textures used by font cache entry.

func get_texture_image(cache_index: int, size: Vector2i, texture_index: int) -> Image

Returns a copy of the font cache texture image.

func get_texture_offsets(cache_index: int, size: Vector2i, texture_index: int) -> PackedInt32Array

Returns a copy of the array containing glyph packing data.

func get_transform(cache_index: int) -> Transform2D

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

func get_variation_coordinates(cache_index: int) -> Dictionary

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

func load_bitmap_font(path: String) -> Error

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.

func load_dynamic_font(path: String) -> Error

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.

func remove_cache(cache_index: int) -> void

Removes specified font cache entry.

func remove_glyph(cache_index: int, size: Vector2i, glyph: int) -> void

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.

func remove_kerning(cache_index: int, size: int, glyph_pair: Vector2i) -> void

Removes kerning override for the pair of glyphs.

func remove_language_support_override(language: String) -> void

Remove language support override.

func remove_script_support_override(script: String) -> void

Removes script support override.

func remove_size_cache(cache_index: int, size: Vector2i) -> void

Removes specified font size from the cache entry.

func remove_texture(cache_index: int, size: Vector2i, texture_index: int) -> void

Removes specified texture from the cache entry.

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

func render_glyph(cache_index: int, size: Vector2i, index: int) -> void

Renders specified glyph to the font cache texture.

func render_range(cache_index: int, size: Vector2i, start: int, end: int) -> void

Renders the range of characters to the font cache texture.

func set_cache_ascent(cache_index: int, size: int, ascent: float) -> void

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

func set_cache_descent(cache_index: int, size: int, descent: float) -> void

Sets the font descent (number of pixels below the baseline).

func set_cache_scale(cache_index: int, size: int, scale: float) -> void

Sets scaling factor of the color bitmap font.

func set_cache_underline_position(cache_index: int, size: int, underline_position: float) -> void

Sets pixel offset of the underline below the baseline.

func set_cache_underline_thickness(cache_index: int, size: int, underline_thickness: float) -> void

Sets thickness of the underline in pixels.

func set_embolden(cache_index: int, strength: float) -> void

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

func set_extra_baseline_offset(cache_index: int, baseline_offset: float) -> void

Sets extra baseline offset (as a fraction of font height).

func set_extra_spacing(cache_index: int, spacing: TextServer.SpacingType, value: int) -> void

Sets the spacing for spacing to value in pixels (not relative to the font size).

func set_face_index(cache_index: int, face_index: int) -> void

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

func set_glyph_advance(cache_index: int, size: int, glyph: int, advance: Vector2) -> void

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.

func set_glyph_offset(cache_index: int, size: Vector2i, glyph: int, offset: Vector2) -> void

Sets glyph offset from the baseline.

func set_glyph_size(cache_index: int, size: Vector2i, glyph: int, gl_size: Vector2) -> void

Sets glyph size.

func set_glyph_texture_idx(cache_index: int, size: Vector2i, glyph: int, texture_idx: int) -> void

Sets index of the cache texture containing the glyph.

func set_glyph_uv_rect(cache_index: int, size: Vector2i, glyph: int, uv_rect: Rect2) -> void

Sets rectangle in the cache texture containing the glyph.

func set_kerning(cache_index: int, size: int, glyph_pair: Vector2i, kerning: Vector2) -> void

Sets kerning for the pair of glyphs.

func set_language_support_override(language: String, supported: bool) -> void

Adds override for Font.is_language_supported().

func set_script_support_override(script: String, supported: bool) -> void

Adds override for Font.is_script_supported().

func set_texture_image(cache_index: int, size: Vector2i, texture_index: int, image: Image) -> void

Sets font cache texture image.

func set_texture_offsets(cache_index: int, size: Vector2i, texture_index: int, offset: PackedInt32Array) -> void

Sets array containing glyph packing data.

func set_transform(cache_index: int, transform: Transform2D) -> void

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

func set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary) -> void

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

Inherited from Font (35)
func draw_char(canvas_item: RID, pos: Vector2, char: int, font_size: int, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> float
func draw_char_outline(canvas_item: RID, pos: Vector2, char: int, font_size: int, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> float
func draw_multiline_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multiline_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_string(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_string_outline(canvas_item: RID, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func find_variation(variation_coordinates: Dictionary, face_index: int = 0, strength: float = 0.0, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), spacing_top: int = 0, spacing_bottom: int = 0, spacing_space: int = 0, spacing_glyph: int = 0, baseline_offset: float = 0.0, palette_index: int = 0, custom_colors: PackedColorArray = PackedColorArray()) -> RID
func get_ascent(font_size: int = 16) -> float
func get_char_size(char: int, font_size: int) -> Vector2
func get_descent(font_size: int = 16) -> float
func get_height(font_size: int = 16) -> float
func get_multiline_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0) -> Vector2
func get_palette_name(index: int) -> String
func get_rids() -> RID[]
func get_string_size(text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0) -> Vector2
func get_underline_position(font_size: int = 16) -> float
func get_underline_thickness(font_size: int = 16) -> float
func has_char(char: int) -> bool
func is_language_supported(language: String) -> bool
func set_cache_capacity(single_line: int, multi_line: int) -> void
Inherited from Resource (18)
func _get_rid() -> RID
func _reset_state() -> void
func _set_path_cache(path: String) -> void
func _setup_local_to_scene() -> void
func copy_from_resource(resource: Resource) -> Error
func duplicate(deep: bool = false) -> Resource
func duplicate_deep(deep_subresources_mode: Resource.DeepDuplicateMode = 1) -> Resource
func emit_changed() -> void
func get_rid() -> RID
func is_built_in() -> bool
func reset_state() -> void
func set_id_for_path(path: String, id: String) -> void
func set_path_cache(path: String) -> void
func setup_local_to_scene() -> void
func take_over_path(path: String) -> void
Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Resource (2)
signal changed()
Inherited from Object (2)