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

要进行更复杂的文本处理,请将 FontVariationTextLineTextParagraph 结合使用。

支持的字体格式:

  • 动态字体导入器: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,