FontFile

继承： Font < Resource < RefCounted < Object

保存从动态字体或位图字体导入的字体源数据和预渲染字形缓存。

描述

FontFile包含了一组字形，代表从字体文件中导入的 Unicode 字符，还包含了光栅化字形的缓存，以及一组备用的回退Font。

要访问字体的 OpenType 变体，创建模拟的粗体/斜体版本，或者绘制文本行，请使用FontVariation。

要进行更复杂的文本处理，请将FontVariation与TextLine或TextParagraph结合使用。

支持的字体格式：

  • 动态字体导入器：TrueType（.ttf）、TrueType 合集（.ttc）、OpenType（.otf）、OpenType 合集（.otc）、WOFF（.woff）、WOFF2（.woff2）、Type 1（.pfb，.pfm）。

  • 位图字体导入器：AngelCode BMFont（.fnt，.font），支持文本和二进制（版本 3）格式变体。

  • 等宽图像字体导入器：所有支持的图像格式。

注意：字符是一种表示某个项目（字母、数字等）的抽象符号。

注意：字形是一种位图或形状，用于根据上下文绘制一个或多个字符。字形索引绑定的是某个字体数据源。

注意：如果所有字体数据源都不包含字符串中某个字符的字形，那么该字符就会被替换为一个中间是对应十六进制码的方框。

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

属性

bool

allow_system_fallback

true

FontAntialiasing

antialiasing

1

PackedByteArray

data

PackedByteArray()

bool

disable_embedded_bitmaps

true

int

fixed_size

0

FixedSizeScaleMode

fixed_size_scale_mode

0

String

font_name

""

int

font_stretch

100

BitField[FontStyle]

font_style

0

int

font_weight

400

bool

force_autohinter

false

bool

generate_mipmaps

false

Hinting

hinting

1

bool

keep_rounding_remainders

true

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

方法

void

clear_cache()

void

clear_glyphs(cache_index: int, size: Vector2i)

void

clear_kerning_map(cache_index: int, size: int)

void

clear_size_cache(cache_index: int)

void

clear_textures(cache_index: int, size: Vector2i)

float

get_cache_ascent(cache_index: int, size: int) const

int

get_cache_count() const

float

get_cache_descent(cache_index: int, size: int) const

float

get_cache_scale(cache_index: int, size: int) const

float

get_cache_underline_position(cache_index: int, size: int) const

float

get_cache_underline_thickness(cache_index: int, size: int) const

int

get_char_from_glyph_index(size: int, glyph_index: int) const

float

get_embolden(cache_index: int) const

float

get_extra_baseline_offset(cache_index: int) const

int

get_extra_spacing(cache_index: int, spacing: SpacingType) const

int

get_face_index(cache_index: int) const

Vector2

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

int

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

PackedInt32Array

get_glyph_list(cache_index: int, size: Vector2i) const

Vector2

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

Vector2

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

int

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

Rect2

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

Vector2

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

Array[Vector2i]

get_kerning_list(cache_index: int, size: int) const

bool

get_language_support_override(language: String) const

PackedStringArray

get_language_support_overrides() const

bool

get_script_support_override(script: String) const

PackedStringArray

get_script_support_overrides() const

Array[Vector2i]

get_size_cache_list(cache_index: int) const

int

get_texture_count(cache_index: int, size: Vector2i) const

Image

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

PackedInt32Array

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

Transform2D

get_transform(cache_index: int) const

Dictionary

get_variation_coordinates(cache_index: int) const

Error

load_bitmap_font(path: String)

Error

load_dynamic_font(path: String)

void

remove_cache(cache_index: int)

void

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

void

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

void

remove_language_support_override(language: String)

void

remove_script_support_override(script: String)

void

remove_size_cache(cache_index: int, size: Vector2i)

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

set_embolden(cache_index: int, strength: float)

void

set_extra_baseline_offset(cache_index: int, baseline_offset: float)

void

set_extra_spacing(cache_index: int, spacing: SpacingType, value: int)

void

set_face_index(cache_index: int, face_index: int)

void

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

void

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

void

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

void

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

void

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

void

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

void

set_language_support_override(language: String, supported: bool)

void

set_script_support_override(script: String, supported: bool)

void

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

void

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

void

set_transform(cache_index: int, transform: Transform2D)

void

set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary)

属性说明

bool allow_system_fallback = true 🔗

  • void set_allow_system_fallback(value: bool)

  • bool is_allow_system_fallback()

如果设置为true，系统字体可以自动用作后备。

FontAntialiasing antialiasing = 1 🔗

字体防混淆现象模式。

PackedByteArray data = PackedByteArray() 🔗

动态字体源文件的内容。

注意: 返回的数组是被 复制 的，对它的任何修改都不会更新原始属性的值。有关更多详细信息，请参阅 PackedByteArray 。

bool disable_embedded_bitmaps = true 🔗

  • void set_disable_embedded_bitmaps(value: bool)

  • bool get_disable_embedded_bitmaps()

如果设置为true，则禁用嵌入字体位图加载（仅位图和彩色字体忽略此属性）。

int fixed_size = 0 🔗

  • void set_fixed_size(value: int)

  • int get_fixed_size()

字体大小，仅用于位图字体。

FixedSizeScaleMode fixed_size_scale_mode = 0 🔗

缩放模式，仅用于fixed_size大于零的位图字体。

String font_name = "" 🔗

字体名称。

int font_stretch = 100 🔗

  • void set_font_stretch(value: int)

  • int get_font_stretch()

字体拉伸量，与正常宽度相比。50%和200%之间的百分比值。

BitField[FontStyle] font_style = 0 🔗

字体样式标志，请参阅FontStyle。

int font_weight = 400 🔗

  • void set_font_weight(value: int)

  • int get_font_weight()

字体的重量（粗体）。100…999范围内的值，正常字体权重为400，粗体字体权重为700。

bool force_autohinter = false 🔗

  • void set_force_autohinter(value: bool)

  • bool is_force_autohinter()

如果设置为true，则支持自动提示，并且优先于字体内置提示。仅由动态字体使用（MSDF字体不支持提示）。

bool generate_mipmaps = false 🔗

  • void set_generate_mipmaps(value: bool)

  • bool get_generate_mipmaps()

如果设置为true，则为字体纹理生成mipmap。

Hinting hinting = 1 🔗

字体提示模式。仅由动态字体使用。

bool keep_rounding_remainders = true 🔗

  • void set_keep_rounding_remainders(value: bool)

  • bool get_keep_rounding_remainders()

如果设置为true，则在将字形与像素边界对齐时，会累积舍入余数以确保字形分布更均匀。如果启用子像素定位，此设置无效。

int msdf_pixel_range = 16 🔗

  • void set_msdf_pixel_range(value: int)

  • int get_msdf_pixel_range()

形状周围最小和最大可表示符号距离之间的范围的宽度。如果使用字体轮廓，msdf_pixel_range必须设置为最大字体轮廓大小的至少两倍。16的默认msdf_pixel_range值允许最大8的轮廓大小看起来正确。

int msdf_size = 48 🔗

  • void set_msdf_size(value: int)

  • int get_msdf_size()

用于生成MSDF纹理的源字体大小。较高的值允许更高的精度，但渲染速度较慢，需要更多内存。只有在您注意到字形渲染明显缺乏精度时才会增加此值。

bool multichannel_signed_distance_field = false 🔗

  • void set_multichannel_signed_distance_field(value: bool)

  • bool is_multichannel_signed_distance_field()

如果设置为true，则使用从动态字体矢量数据生成的单个多通道有符号距离字段（MSDF）呈现所有大小的字形。由于这种方法不依赖于每次字体大小变化时都光栅化字体，因此可以实时调整字体大小，而不会影响性能。对于按比例缩小的Controls（或从远距离查看的TextRenders），文本也不会看起来很粗糙。缺点是，MSDF不提供字体提示。缺少字体提示可能会导致小尺寸字体不清晰且可读性较差。

注意：如果使用字体轮廓，msdf_pixel_range必须设置为最大字体轮廓大小的至少两倍。

注意：MSDF字体渲染不能正确渲染具有重叠形状的字形。根据OpenType标准，重叠形状无效，但在许多字体文件中仍然很常见，尤其是那些由Google Fonts转换的字体文件。为了避免重叠字形的问题，请考虑直接从字体铸造厂下载字体文件，而不是依赖Google Fonts。

Dictionary opentype_feature_overrides = {} 🔗

  • void set_opentype_feature_overrides(value: Dictionary)

  • Dictionary get_opentype_feature_overrides()

字体OpenType功能集覆盖。

float oversampling = 0.0 🔗

  • void set_oversampling(value: float)

  • float get_oversampling()

字体过采样因子。如果设置为0.0，则使用全局过采样因子。仅由动态字体使用（MSDF字体忽略过采样）。

String style_name = "" 🔗

  • void set_font_style_name(value: String)

  • String get_font_style_name()

字体样式名称。

SubpixelPositioning subpixel_positioning = 1 🔗

字体字形亚像素定位模式。亚像素定位为较小的字体大小提供整形文本和更好的字距调整，代价是更高的内存使用和更低的字体光栅化速度。使用TextServer.SUBPIXEL_POSITIONING_AUTO根据字体大小自动启用它。

方法说明

void clear_cache() 🔗

删除所有字体缓存条目。

void clear_glyphs(cache_index: int, size: Vector2i) 🔗

从缓存条目中删除所有呈现的字形信息。

注意：此功能不会删除与字形关联的纹理，使用remove_texture()手动删除它们。

void clear_kerning_map(cache_index: int, size: int) 🔗

删除所有字距调整覆盖。

void clear_size_cache(cache_index: int) 🔗

从缓存条目中删除所有字体大小。

void clear_textures(cache_index: int, size: Vector2i) 🔗

从字体缓存条目中删除所有纹理。

注意：此功能不会删除与纹理关联的字形，使用remove_glyph()手动删除它们。

float get_cache_ascent(cache_index: int, size: int) const 🔗

返回字体上升（基线上方的像素数）。

int get_cache_count() const 🔗

返回字体缓存条目的编号。

float get_cache_descent(cache_index: int, size: int) const 🔗

返回字体下降（基线以下的像素数）。

float get_cache_scale(cache_index: int, size: int) const 🔗

返回颜色位图字体的缩放因子。

float get_cache_underline_position(cache_index: int, size: int) const 🔗

返回基线下方下划线的像素偏移量。

float get_cache_underline_thickness(cache_index: int, size: int) const 🔗

返回下划线的粗细（以像素为单位）。

int get_char_from_glyph_index(size: int, glyph_index: int) const 🔗

返回与glyph_index关联的字符代码，如果glyph_index无效，则返回0。参见get_glyph_index()。

float get_embolden(cache_index: int) const 🔗

返回加粗强度，如果不等于零，则加粗字体轮廓。负值减少轮廓厚度。

float get_extra_baseline_offset(cache_index: int) const 🔗

返回额外的基线偏移量（作为字体高度的一小部分）。

int get_extra_spacing(cache_index: int, spacing: SpacingType) const 🔗

返回spacing（参见SpacingType）的行间距，以像素为单位（与字体大小无关）。

int get_face_index(cache_index: int) const 🔗

返回TrueType/OpenType集合中的活动面部索引。

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

返回字形前进（下一个字形的偏移量）。

注意：字形提前量与基本字形提前量相同，不保存。

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

返回char的字形索引，可选择由variation_selector修改。

PackedInt32Array get_glyph_list(cache_index: int, size: Vector2i) const 🔗

返回缓存条目中呈现的字形列表。

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

返回与基线的字形偏移量。

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

返回字形大小。

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

返回包含字形的缓存纹理的索引。

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

返回包含字形的缓存纹理中的矩形。

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

返回这对字形的字距调整。

Array[Vector2i] get_kerning_list(cache_index: int, size: int) const 🔗

返回字距覆盖的列表。

bool get_language_support_override(language: String) const 🔗

如果为language启用了支持覆盖，则返回true。

PackedStringArray get_language_support_overrides() const 🔗

返回语言支持覆盖列表。

bool get_script_support_override(script: String) const 🔗

如果为script启用了支持覆盖，则返回true。

PackedStringArray get_script_support_overrides() const 🔗

返回脚本支持覆盖列表。

Array[Vector2i] get_size_cache_list(cache_index: int) const 🔗

返回缓存中字体大小的列表。每个大小是Vector2i，带有字体大小和轮廓大小。

int get_texture_count(cache_index: int, size: Vector2i) const 🔗

返回字体缓存条目使用的纹理数量。

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

返回字体缓存纹理图像的副本。

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

返回包含字形打包数据的数组副本。

Transform2D get_transform(cache_index: int) const 🔗

返回2D变换，应用于字体轮廓，可用于倾斜、翻转和旋转字形。

Dictionary get_variation_coordinates(cache_index: int) const 🔗

返回指定字体缓存项的变化坐标。有关详细信息，请参阅Font.get_supported_variation_list()。

Error load_bitmap_font(path: String) 🔗

从文件path加载AngelCode BMFont（. fnt，.font）位图字体。

警告：此方法应仅在编辑器中使用，或者在您需要在运行时加载外部字体的情况下使用，例如位于user：//目录中的字体。

Error load_dynamic_font(path: String) 🔗

从文件path加载TrueType（. ttf）、OpenType（.otf）、WOFF（.woff）、WOFF2（.woff2）或Type 1（.pfb、.pfm）动态字体。

警告：此方法应仅在编辑器中使用，或者在您需要在运行时加载外部字体的情况下使用，例如位于user：//目录中的字体。

void remove_cache(cache_index: int) 🔗

删除指定的字体缓存条目。

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

从缓存条目中删除指定的呈现字形信息。

注意：此功能不会删除与字形关联的纹理，使用remove_texture()手动删除它们。

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

删除字形对的字距覆盖。

void remove_language_support_override(language: String) 🔗

删除语言支持覆盖。

void remove_script_support_override(script: String) 🔗

删除脚本支持覆盖。

void remove_size_cache(cache_index: int, size: Vector2i) 🔗

从缓存条目中删除指定的字体大小。

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

从缓存条目中删除指定的纹理。

注意：此函数不会删除与纹理关联的字形。使用remove_glyph()手动删除它们。

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

将指定的字形呈现到字体缓存纹理中。

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

将字符范围呈现到字体缓存纹理。

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

设置字体上升（基线上方的像素数）。

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

设置字体下降（基线以下的像素数）。

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

设置颜色位图字体的比例因子。

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

设置基线下方下划线的像素偏移量。

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

设置下划线的粗细（以像素为单位）。

void set_embolden(cache_index: int, strength: float) 🔗

设置加粗强度，如果不等于零，则加粗字体轮廓。负值减少轮廓厚度。

void set_extra_baseline_offset(cache_index: int, baseline_offset: float) 🔗

设置额外的基线偏移量（作为字体高度的一小部分）。

void set_extra_spacing(cache_index: int, spacing: SpacingType, value: int) 🔗

将spacing（参见SpacingType）的行间距设置为value（以像素为单位）（与字体大小无关）。

void set_face_index(cache_index: int, face_index: int) 🔗

在TrueType/OpenType集合中设置活动面部索引。

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

设置字形前进（下一个字形的偏移量）。

注意：字形提前量与基本字形提前量相同，不保存。

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

设置字形与基线的偏移量。

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

设置字形大小。

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

设置包含字形的缓存纹理的索引。

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

在包含字形的缓存纹理中设置矩形。

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

设置字形对的字距。

void set_language_support_override(language: String, supported: bool) 🔗

添加Font.is_language_supported()的覆盖。

void set_script_support_override(script: String, supported: bool) 🔗

添加Font.is_script_supported()的覆盖。

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

设置字体缓存纹理图像。

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

设置包含字形打包数据的数组。

void set_transform(cache_index: int, transform: Transform2D) 🔗

设置2D变换，应用于字体轮廓，可用于倾斜、翻转和旋转字形。

void set_variation_coordinates(cache_index: int, variation_coordinates: Dictionary) 🔗

设置指定字体缓存项的变化坐标。有关详细信息，请参阅Font.get_supported_variation_list()。