Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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）格式变体。

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

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

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

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

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

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

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 ( 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

int

get_char_from_glyph_index ( int size, int glyph_index ) const

float

get_embolden ( int cache_index ) const

int

get_extra_spacing ( int cache_index, SpacingType spacing ) 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

PackedInt32Array

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

Vector2i[]

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

Vector2i[]

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_extra_spacing ( int cache_index, SpacingType spacing, int value )

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 )

属性说明

bool allow_system_fallback = true

  • void set_allow_system_fallback ( bool value )

  • bool is_allow_system_fallback ( )

如果设置为 true，则可以自动将系统字体作为回退使用。

FontAntialiasing antialiasing = 1

字体抗锯齿模式。

PackedByteArray data = PackedByteArray()

动态字体源文件的内容。

int fixed_size = 0

  • void set_fixed_size ( int value )

  • int get_fixed_size ( )

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

FixedSizeScaleMode fixed_size_scale_mode = 0

缩放模式，只有 fixed_size 大于零的位图字体会使用。

String font_name = ""

  • void set_font_name ( String value )

  • String get_font_name ( )

字体家族名称。

int font_stretch = 100

  • void set_font_stretch ( int value )

  • int get_font_stretch ( )

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

BitField<FontStyle> font_style = 0

  • void set_font_style ( BitField<FontStyle> value )

  • BitField<FontStyle> get_font_style ( )

字体样式标志，见 FontStyle。

int font_weight = 400

  • void set_font_weight ( int value )

  • int get_font_weight ( )

该字体的字重（粗度）。一个在 100...999 范围内的值，正常字体字重为 400，粗体字体字重为 700。

bool force_autohinter = false

  • void set_force_autohinter ( bool value )

  • bool is_force_autohinter ( )

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

bool generate_mipmaps = false

  • void set_generate_mipmaps ( bool value )

  • bool get_generate_mipmaps ( )

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

Hinting hinting = 1

字体微调模式。仅由动态字体使用。

int msdf_pixel_range = 16

  • void set_msdf_pixel_range ( int value )

  • int get_msdf_pixel_range ( )

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

int msdf_size = 48

  • void set_msdf_size ( int value )

  • int get_msdf_size ( )

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

bool multichannel_signed_distance_field = false

  • void set_multichannel_signed_distance_field ( bool value )

  • bool is_multichannel_signed_distance_field ( )

如果被设置为 true，则所有大小的字形进行渲染时，都使用从动态字体矢量数据中生成的单个多通道带符号距离场（MSDF）。由于这种方法不依赖于在每次字体大小发生变化时，对字体进行栅格化，因此可以实时调整字体大小而不会造成任何性能损失。对于按比例缩小的 Control（或从远距离查看的 Label3D），文本也不会看起来有颗粒感。有一个缺点，MSDF 不提供字体提示。缺少字体提示可能会导致大小较小的字体的清晰度和可读性较差。

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

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

Dictionary opentype_feature_overrides = {}

  • void set_opentype_feature_overrides ( Dictionary value )

  • Dictionary get_opentype_feature_overrides ( )

字体 OpenType 特性集覆盖。

float oversampling = 0.0

  • void set_oversampling ( float value )

  • float get_oversampling ( )

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

String style_name = ""

  • void set_font_style_name ( String value )

  • String get_font_style_name ( )

字体样式名称。

SubpixelPositioning subpixel_positioning = 1

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

方法说明

void clear_cache ( )

移除所有字体缓存条目。

void clear_glyphs ( int cache_index, Vector2i size )

从字体缓存条目中，移除所有渲染的字形信息。

注意：该函数不会移除与字形相关的纹理，请使用 remove_texture 手动移除它们。

void clear_kerning_map ( int cache_index, int size )

移除所有字距调整覆盖。

void clear_size_cache ( int cache_index )

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

void clear_textures ( int cache_index, Vector2i size )

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

注意：该函数不会移除与纹理相关的字形，请使用 remove_glyph 手动移除它们。

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

返回下划线的粗细度，单位为像素。

int get_char_from_glyph_index ( int size, int glyph_index ) const

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

float get_embolden ( int cache_index ) const

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

int get_extra_spacing ( int cache_index, SpacingType spacing ) const

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

int get_face_index ( int cache_index ) const

返回 TrueType / OpenType 集合中的活动字体索引。

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

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

注意：字形轮廓的前进量，与基础字形的前进量相同，不会被保存。

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

返回 char 的字形索引，可以用 variation_selector 修改。

PackedInt32Array 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

返回字形对的字距调整。

Vector2i[] get_kerning_list ( int cache_index, int size ) const

返回字距调整覆盖的列表。

bool get_language_support_override ( String language ) const

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

PackedStringArray get_language_support_overrides ( ) const

返回语言支持覆盖的列表。

bool get_script_support_override ( String script ) const

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

PackedStringArray get_script_support_overrides ( ) const

返回文字支持覆盖的列表。

Vector2i[] get_size_cache_list ( int cache_index ) const

返回缓存中字体大小的列表。每个大小都是由字体大小和轮廓大小组成的 Vector2i。

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

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

Dictionary get_variation_coordinates ( int cache_index ) const

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

Error load_bitmap_font ( String path )

从文件 path 中加载一个 AngelCode BMFont (.fnt, .font) 位图字体。

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

Error load_dynamic_font ( String path )

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

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

void remove_cache ( int cache_index )

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

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

从缓存条目中移除指定的渲染的字形信息。

注意：该函数不会移除与字形相关的纹理，请使用 remove_texture 手动移除它们。

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 )

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

注意：该函数不会移除与纹理相关的字形，请使用 remove_glyph 手动移除它们。

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_extra_spacing ( int cache_index, SpacingType spacing, int value )

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

void set_face_index ( int cache_index, int face_index )

在 TrueType / OpenType 集合中设置活动字体索引。

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 )

为 Font.is_language_supported 添加覆盖。

void set_script_support_override ( String script, bool supported )

为 Font.is_script_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 )

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

void set_variation_coordinates ( int cache_index, Dictionary variation_coordinates )

为指定的字体缓存条目设置变体坐标。有关详细信息，请参阅 Font.get_supported_variation_list。