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）是一种位图或形状，用于根据上下文绘制一个或多个字符。字形索引绑定的是某个字体数据源。

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

GDScriptC#

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

教程

• 运行时文件加载与保存

属性

方法

属性说明

bool allow_system_fallback = true

• void set_allow_system_fallback ( bool value )

• bool is_allow_system_fallback ( )

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

FontAntialiasing antialiasing = 1

• void set_antialiasing ( FontAntialiasing value )

• FontAntialiasing get_antialiasing ( )

字体抗锯齿模式。

PackedByteArray data = PackedByteArray()

• void set_data ( PackedByteArray value )

• PackedByteArray get_data ( )

动态字体源文件的内容。

int fixed_size = 0

• void set_fixed_size ( int value )

• int get_fixed_size ( )

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

FixedSizeScaleMode fixed_size_scale_mode = 0

• void set_fixed_size_scale_mode ( FixedSizeScaleMode value )

• FixedSizeScaleMode get_fixed_size_scale_mode ( )

缩放模式，只有 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

• void set_hinting ( Hinting value )

• Hinting get_hinting ( )

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

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

• void set_subpixel_positioning ( SubpixelPositioning value )

• SubpixelPositioning get_subpixel_positioning ( )

字体字形的子像素定位模式。子像素定位为较小的字体提供了更清晰的文本和更好的字距调整，但代价是更高的内存占用和更低的字体光栅化速度。使用 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。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.