Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
TextServer¶
继承: RefCounted < Object
字体管理和文本渲染的服务器接口。
描述¶
TextServer 是用于管理字体和渲染文本的 API 后端。
方法¶
枚举¶
enum FontAntialiasing:
FontAntialiasing FONT_ANTIALIASING_NONE = 0
字体字形栅格化为 1 位的位图。
FontAntialiasing FONT_ANTIALIASING_GRAY = 1
字体字形栅格化为 8 位的灰度抗锯齿位图。
FontAntialiasing FONT_ANTIALIASING_LCD = 2
字体字形针对 LCD 屏幕栅格化。
LCD 次像素布局由项目设置 gui/theme/lcd_subpixel_layout
的值决定。
LCD 次像素抗锯齿模式仅适用于在 2D 中渲染横向、无缩放的文本。
enum FontLCDSubpixelLayout:
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_NONE = 0
未知或不支持的次像素布局,禁用 LCD 次像素抗锯齿。
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_HRGB = 1
水平 RGB 次像素布局。
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_HBGR = 2
水平 BGR 次像素布局。
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_VRGB = 3
垂直 RGB 次像素布局。
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_VBGR = 4
垂直 BGR 次像素布局。
FontLCDSubpixelLayout FONT_LCD_SUBPIXEL_LAYOUT_MAX = 5
代表 FontLCDSubpixelLayout 枚举的大小。
enum Direction:
Direction DIRECTION_AUTO = 0
文本的书写方向由根据内容和当前区域设置确定。
Direction DIRECTION_LTR = 1
文本从左至右书写。
Direction DIRECTION_RTL = 2
文本从右至左书写。
Direction DIRECTION_INHERITED = 3
文本的书写方向与基础字符串书写方向一致。仅用于 BiDi 覆盖。
enum Orientation:
Orientation ORIENTATION_HORIZONTAL = 0
文本水平书写。
Orientation ORIENTATION_VERTICAL = 1
从左至右的文本从上到下书写。
从右至左的文本从下到上书写。
flags JustificationFlag:
JustificationFlag JUSTIFICATION_NONE = 0
不两端对齐文本。
JustificationFlag JUSTIFICATION_KASHIDA = 1
通过添加和移除 Kashida 来两端对齐文本。
JustificationFlag JUSTIFICATION_WORD_BOUND = 2
通过更改单词之间空格的宽度来两端对齐文本。
JustificationFlag JUSTIFICATION_TRIM_EDGE_SPACES = 4
从两端对齐的文本中移除前缀和后缀的空格。
JustificationFlag JUSTIFICATION_AFTER_LAST_TAB = 8
仅对最后一个制表符之后的文本应用两端对齐。
JustificationFlag JUSTIFICATION_CONSTRAIN_ELLIPSIS = 16
使用省略号对修剪行应用对齐。
JustificationFlag JUSTIFICATION_SKIP_LAST_LINE = 32
段落中的最后一行不应用两端对齐。
JustificationFlag JUSTIFICATION_SKIP_LAST_LINE_WITH_VISIBLE_CHARS = 64
段落中存在可见字符的最后一行不应用两端对齐(优先于 JUSTIFICATION_SKIP_LAST_LINE)。
JustificationFlag JUSTIFICATION_DO_NOT_SKIP_SINGLE_LINE = 128
始终对只有一行的段落应用两端对齐(忽略 JUSTIFICATION_SKIP_LAST_LINE 和 JUSTIFICATION_SKIP_LAST_LINE_WITH_VISIBLE_CHARS)。
enum AutowrapMode:
AutowrapMode AUTOWRAP_OFF = 0
自动换行已禁用。
AutowrapMode AUTOWRAP_ARBITRARY = 1
让文本在节点的边界矩形内自动换行,允许在任意位置断行,在空间非常有限的情况下非常有用。
AutowrapMode AUTOWRAP_WORD = 2
让文本在节点的边界矩形内自动换行,允许在单词之间进行软换行。
AutowrapMode AUTOWRAP_WORD_SMART = 3
行为与 AUTOWRAP_WORD 类似,但如果一行的大小无法放下该单词,则会强制断开该单词。
flags LineBreakFlag:
LineBreakFlag BREAK_NONE = 0
不换行。
LineBreakFlag BREAK_MANDATORY = 1
在强制换行符处换行(例如 "\n"
)。
LineBreakFlag BREAK_WORD_BOUND = 2
在单词之间换行。
LineBreakFlag BREAK_GRAPHEME_BOUND = 4
在任何不相连的字素之间换行。
LineBreakFlag BREAK_ADAPTIVE = 8
只应与 BREAK_WORD_BOUND 一起使用,如果不可能在单词之间换行,则在任何不相连的字素之间换行。
LineBreakFlag BREAK_TRIM_EDGE_SPACES = 16
移除每一行头尾的空格。
enum VisibleCharactersBehavior:
VisibleCharactersBehavior VC_CHARS_BEFORE_SHAPING = 0
塑形前截断文本。例如,增加 Label.visible_characters 或 RichTextLabel.visible_characters 的值在视觉上会与输入该文本等价。
VisibleCharactersBehavior VC_CHARS_AFTER_SHAPING = 1
显示映射到文本开头的前 Label.visible_characters 或 RichTextLabel.visible_characters 个字符的字形。
VisibleCharactersBehavior VC_GLYPHS_AUTO = 2
显示字形数量由 Label.visible_ratio 或 RichTextLabel.visible_ratio 决定,从左至右计数还是从右至左计数由 Control.layout_direction 的值决定。
VisibleCharactersBehavior VC_GLYPHS_LTR = 3
显示字形数量由 Label.visible_ratio 或 RichTextLabel.visible_ratio 决定,从左侧开始计数。
VisibleCharactersBehavior VC_GLYPHS_RTL = 4
显示字形数量由 Label.visible_ratio 或 RichTextLabel.visible_ratio 决定,从右侧开始计数。
enum OverrunBehavior:
OverrunBehavior OVERRUN_NO_TRIMMING = 0
不执行文本修剪。
OverrunBehavior OVERRUN_TRIM_CHAR = 1
逐字符修剪文本。
OverrunBehavior OVERRUN_TRIM_WORD = 2
逐单词修剪文本。
OverrunBehavior OVERRUN_TRIM_ELLIPSIS = 3
逐字符修剪文本,并通过添加省略号来表示部分文本已隐藏。
OverrunBehavior OVERRUN_TRIM_WORD_ELLIPSIS = 4
逐单词修剪文本,并通过添加省略号来表示部分文本已隐藏。
flags TextOverrunFlag:
TextOverrunFlag OVERRUN_NO_TRIM = 0
不执行修剪。
TextOverrunFlag OVERRUN_TRIM = 1
当文本超过给定宽度时,修剪文本。
TextOverrunFlag OVERRUN_TRIM_WORD_ONLY = 2
逐词修剪文本,而不是逐字素修剪文本。
TextOverrunFlag OVERRUN_ADD_ELLIPSIS = 4
决定是否应在文本末尾添加省略号。
TextOverrunFlag OVERRUN_ENFORCE_ELLIPSIS = 8
决定是否应在文本末尾强制添加省略号,该省略号无法被隐藏。
TextOverrunFlag OVERRUN_JUSTIFICATION_AWARE = 16
在尝试修剪文本之前考虑文本是否对齐(请参阅 JustificationFlag)。
flags GraphemeFlag:
GraphemeFlag GRAPHEME_IS_VALID = 1
字素由字体支持,并且可以被绘制。
GraphemeFlag GRAPHEME_IS_RTL = 2
字素是从右至左或从下至上书写的一部分。
GraphemeFlag GRAPHEME_IS_VIRTUAL = 4
字素不是源文本的一部分,而是通过两端对齐过程添加的。
GraphemeFlag GRAPHEME_IS_SPACE = 8
字素是空白字符。
GraphemeFlag GRAPHEME_IS_BREAK_HARD = 16
字素是强制换行点(例如 "\n"
)。
GraphemeFlag GRAPHEME_IS_BREAK_SOFT = 32
字素是可选换行点(例如空格)。
GraphemeFlag GRAPHEME_IS_TAB = 64
字素是制表符。
GraphemeFlag GRAPHEME_IS_ELONGATION = 128
字素是 Kashida。
GraphemeFlag GRAPHEME_IS_PUNCTUATION = 256
字素是标点符号。
GraphemeFlag GRAPHEME_IS_UNDERSCORE = 512
字素是下划线字符。
GraphemeFlag GRAPHEME_IS_CONNECTED = 1024
字素与前一个字素相连。在这个字素之前换行是不安全的。
GraphemeFlag GRAPHEME_IS_SAFE_TO_INSERT_TATWEEL = 2048
在这个字素之前插入 U+0640 以进行伸长是安全的。
GraphemeFlag GRAPHEME_IS_EMBEDDED_OBJECT = 4096
字素是内嵌对象的对象替换字符。
enum Hinting:
Hinting HINTING_NONE = 0
禁用字体提示(更平滑但不那么清晰)。
Hinting HINTING_LIGHT = 1
使用浅色字体提示模式。
Hinting HINTING_NORMAL = 2
使用默认的字体微调模式(更锐利,但平滑度更低)。
注意:此处的微调模式会改变字形的水平和垂直度量。应用于等宽字体时,可能会让部分字形的宽度发生变化。
enum SubpixelPositioning:
SubpixelPositioning SUBPIXEL_POSITIONING_DISABLED = 0
将字形的水平位置舍入至整数像素大小,每个字形光栅化一次。
SubpixelPositioning SUBPIXEL_POSITIONING_AUTO = 1
将字形的水平位置根据字体大小进行舍入。
如果字体大小小于等于 SUBPIXEL_POSITIONING_ONE_QUARTER_MAX_SIZE,则舍入至四分之一像素大小。
如果字体大小小于等于 SUBPIXEL_POSITIONING_ONE_HALF_MAX_SIZE,则舍入至二分之一像素大小。
如果是更大的字体,则舍入至整数像素大小。
SubpixelPositioning SUBPIXEL_POSITIONING_ONE_HALF = 2
将字形的水平位置舍入至像素大小的一半,每个字形最多光栅化两次。
SubpixelPositioning SUBPIXEL_POSITIONING_ONE_QUARTER = 3
将字形的水平位置舍入至像素大小的四分之一,每个字形最多光栅化四次。
SubpixelPositioning SUBPIXEL_POSITIONING_ONE_HALF_MAX_SIZE = 20
在 SUBPIXEL_POSITIONING_AUTO 模式下,次像素定位时使用二分之一像素大小的最大字体大小。
SubpixelPositioning SUBPIXEL_POSITIONING_ONE_QUARTER_MAX_SIZE = 16
在 SUBPIXEL_POSITIONING_AUTO 模式下,次像素定位时使用四分之一像素大小的最大字体大小。
enum Feature:
Feature FEATURE_SIMPLE_LAYOUT = 1
TextServer 支持简单排版。
Feature FEATURE_BIDI_LAYOUT = 2
TextServer 支持双向排版。
Feature FEATURE_VERTICAL_LAYOUT = 4
TextServer 支持垂直布局。
Feature FEATURE_SHAPING = 8
TextServer 支持复杂文本塑形。
Feature FEATURE_KASHIDA_JUSTIFICATION = 16
TextServer 支持使用 kashida 进行两端对齐。
Feature FEATURE_BREAK_ITERATORS = 32
TextServer 支持复杂断行/断词规则(例如基于字典)。
Feature FEATURE_FONT_BITMAP = 64
TextServer 支持加载位图字体。
Feature FEATURE_FONT_DYNAMIC = 128
TextServer 支持加载动态字体(TrueType、OpeType 等)。
Feature FEATURE_FONT_MSDF = 256
TextServer 支持多通道有符号距离场动态字体的渲染。
Feature FEATURE_FONT_SYSTEM = 512
TextServer 支持加载系统字体。
Feature FEATURE_FONT_VARIABLE = 1024
TextServer 支持可变字体。
Feature FEATURE_CONTEXT_SENSITIVE_CASE_CONVERSION = 2048
TextServer 支持依赖于区域设置、上下文敏感的大小写转换。
Feature FEATURE_USE_SUPPORT_DATA = 4096
TextServer 的某些功能需要外部数据文件,见 load_support_data。
Feature FEATURE_UNICODE_IDENTIFIERS = 8192
TextServer 支持 UAX #31 标识符验证,见 is_valid_identifier。
Feature FEATURE_UNICODE_SECURITY = 16384
TextServer 支持基于 Unicode 技术报告 #36 和 Unicode 技术标准 #39 的欺骗检测功能。
enum ContourPointTag:
ContourPointTag CONTOUR_CURVE_TAG_ON = 1
轮廓点在曲线上。
ContourPointTag CONTOUR_CURVE_TAG_OFF_CONIC = 0
轮廓点不在曲线上,而是作为圆锥(二次)贝塞尔曲线的控制点。
ContourPointTag CONTOUR_CURVE_TAG_OFF_CUBIC = 2
轮廓点不在曲线上,而是作为三次贝塞尔曲线的控制点。
enum SpacingType:
SpacingType SPACING_GLYPH = 0
每个字形的间距。
SpacingType SPACING_SPACE = 1
空格字符的间距。
SpacingType SPACING_TOP = 2
行顶部的间距。
SpacingType SPACING_BOTTOM = 3
行底部的间距。
SpacingType SPACING_MAX = 4
代表 SpacingType 枚举的大小。
flags FontStyle:
FontStyle FONT_BOLD = 1
字体为粗体。
FontStyle FONT_ITALIC = 2
字体为斜体(italic)或伪斜体(oblique)。
FontStyle FONT_FIXED_WIDTH = 4
字体中有等宽字符。
enum StructuredTextParser:
StructuredTextParser STRUCTURED_TEXT_DEFAULT = 0
使用默认的 Unicode BiDi 算法。
StructuredTextParser STRUCTURED_TEXT_URI = 1
URI 的 BiDi 覆盖。
StructuredTextParser STRUCTURED_TEXT_FILE = 2
文件路径的 BiDi 覆盖。
StructuredTextParser STRUCTURED_TEXT_EMAIL = 3
电子邮件的 BiDi 覆盖。
StructuredTextParser STRUCTURED_TEXT_LIST = 4
列表的 BiDi 覆盖。结构化文本选项:列表分隔符 String。
StructuredTextParser STRUCTURED_TEXT_GDSCRIPT = 5
GDScript 的 BiDi 覆盖。
StructuredTextParser STRUCTURED_TEXT_CUSTOM = 6
用户定义的结构化文本 BiDi 覆盖函数。
enum FixedSizeScaleMode:
FixedSizeScaleMode FIXED_SIZE_SCALE_DISABLE = 0
位图字体未被缩放。
FixedSizeScaleMode FIXED_SIZE_SCALE_INTEGER_ONLY = 1
位图字体被缩放至字体固定大小的最接近整数倍。这是像素艺术字体的推荐选项。
FixedSizeScaleMode FIXED_SIZE_SCALE_ENABLED = 2
位图字体被缩放为任意(分数)大小。这是非像素艺术字体的推荐选项。
方法说明¶
RID create_font ( )
新建空的字体缓存条目资源。要释放生成的资源,请使用 free_rid 方法。
RID create_font_linked_variation ( RID font_rid )
创建一个新的已有的字体变体,该字体重用相同的字形缓存和字体数据。要释放生成的资源,请使用 free_rid 方法。
RID create_shaped_text ( Direction direction=0, Orientation orientation=0 )
使用给定的方向 direction
和朝向 orientation
新建缓冲区,用于复杂排版。要释放生成的缓冲区,请使用 free_rid方法。
注意:如果服务器不支持 FEATURE_BIDI_LAYOUT 特性,则会忽略方向(TextServerAdvanced 支持)。
注意:如果服务器不支持 FEATURE_VERTICAL_LAYOUT 特性,则会忽略朝向(TextServerAdvanced 支持)。
void draw_hex_code_box ( RID canvas, int size, Vector2 pos, int index, Color color ) const
绘制显示字符十六进制码的框。用于替换缺失的字符。
void font_clear_glyphs ( RID font_rid, Vector2i size )
从缓存条目中移除所有的渲染字形信息。
注意:该函数不会移除与字形关联的纹理,请使用 font_remove_texture 手动移除。
void font_clear_kerning_map ( RID font_rid, int size )
移除所有字距调整覆盖。
void font_clear_size_cache ( RID font_rid )
从缓存条目中移除所有的字体大小。
void font_clear_textures ( RID font_rid, Vector2i size )
从字体缓存条目中移除所有的纹理。
注意:该函数不会移除与纹理关联的字形,请使用 font_remove_glyph 手动移除。
void font_draw_glyph ( RID font_rid, RID canvas, int size, Vector2 pos, int index, Color color=Color(1, 1, 1, 1) ) const
在画布项中某个位置绘制单个字形,使用的字体为 font_rid
,大小为 size
。
注意:字形索引是特定于字体的,请使用 shaped_text_get_glyphs 或 font_get_glyph_index 返回的字形索引。
注意:如果有待渲染的字形,调用这个函数可能会触发纹理缓存的更新。
void font_draw_glyph_outline ( RID font_rid, RID canvas, int size, int outline_size, Vector2 pos, int index, Color color=Color(1, 1, 1, 1) ) const
在画布项中某个位置绘制单个字形轮廓,使用的字体为 font_rid
,大小为 size
。
注意:字形索引是特定于字体的,请使用 shaped_text_get_glyphs 或 font_get_glyph_index 返回的字形索引。
注意:如果有待渲染的字形,调用这个函数可能会触发纹理缓存的更新。
FontAntialiasing font_get_antialiasing ( RID font_rid ) const
返回字体的抗锯齿模式。
float font_get_ascent ( RID font_rid, int size ) const
返回字体的上升幅度(超出基线的像素数)。
int font_get_char_from_glyph_index ( RID font_rid, int size, int glyph_index ) const
返回与 glyph_index
关联的字符码,如果 glyph_index
无效则返回 0
。见 font_get_glyph_index。
float font_get_descent ( RID font_rid, int size ) const
返回字体的减少量(低于基线的像素数)。
float font_get_embolden ( RID font_rid ) const
返回字体的加粗力度。
int font_get_face_count ( RID font_rid ) const
返回 TrueType / OpenType 集合中的字体数。
int font_get_face_index ( RID font_rid ) const
返回 TrueType / OpenType 集合中的活动字体索引。
int font_get_fixed_size ( RID font_rid ) const
返回位图字体的固定大小。
FixedSizeScaleMode font_get_fixed_size_scale_mode ( RID font_rid ) const
返回位图字体的缩放模式。
bool font_get_generate_mipmaps ( RID font_rid ) const
如果启用了字体纹理 mipmap 生成,则返回 true
。
float font_get_global_oversampling ( ) const
返回字体过采样系数,由 TextServer 中的所有字体共享。
Vector2 font_get_glyph_advance ( RID font_rid, int size, int glyph ) const
返回字形前进量(下一个字形的偏移量)。
注意:字形轮廓的前进量,与基础字形的前进量相同,不会被保存。
Dictionary font_get_glyph_contours ( RID font, int size, int index ) const
将字形的轮廓线轮廓返回为具有以下内容的 Dictionary:
points
- PackedVector3Array,包含轮廓点。x
和 y
是点坐标。z
是点的类型,使用 ContourPointTag 值。
contours
- PackedInt32Array,包含每个轮廓端点的索引。
orientation
- bool,轮廓方向。如果为 true
,则顺时针轮廓必须被填充。
int font_get_glyph_index ( RID font_rid, int size, int char, int variation_selector ) const
返回 char
的字形索引,可以选择由 variation_selector
进行修改。见 font_get_char_from_glyph_index。
PackedInt32Array font_get_glyph_list ( RID font_rid, Vector2i size ) const
返回缓存条目中的已渲染字形列表。
Vector2 font_get_glyph_offset ( RID font_rid, Vector2i size, int glyph ) const
返回字形的基线偏移量。
Vector2 font_get_glyph_size ( RID font_rid, Vector2i size, int glyph ) const
返回该字形的大小。
int font_get_glyph_texture_idx ( RID font_rid, Vector2i size, int glyph ) const
返回包含该字形的缓存纹理的索引。
RID font_get_glyph_texture_rid ( RID font_rid, Vector2i size, int glyph ) const
返回包含字形的缓存纹理的资源 ID。
注意:如果有待渲染的字形,调用此函数可能会触发纹理缓存的更新。
Vector2 font_get_glyph_texture_size ( RID font_rid, Vector2i size, int glyph ) const
返回包含字形的缓存纹理的大小。
注意:如果有待渲染的字形,调用此函数可能会触发纹理缓存的更新。
Rect2 font_get_glyph_uv_rect ( RID font_rid, Vector2i size, int glyph ) const
返回包含该字形的缓存纹理中的矩形。
Hinting font_get_hinting ( RID font_rid ) const
返回字体微调模式。仅用于动态字体。
Vector2 font_get_kerning ( RID font_rid, int size, Vector2i glyph_pair ) const
返回字形对的字距调整。
Vector2i[] font_get_kerning_list ( RID font_rid, int size ) const
返回字距调整覆盖的列表。
bool font_get_language_support_override ( RID font_rid, String language )
如果为 language
启用了支持覆盖,则返回 true
。
PackedStringArray font_get_language_support_overrides ( RID font_rid )
返回语言支持覆盖的列表。
int font_get_msdf_pixel_range ( RID font_rid ) const
返回最小和最大可表示有符号距离之间形状周围范围的宽度。
int font_get_msdf_size ( RID font_rid ) const
返回用于生成 MSDF 纹理的源字体大小。
String font_get_name ( RID font_rid ) const
返回字体家族名称。
Dictionary font_get_opentype_feature_overrides ( RID font_rid ) const
返回字体 OpenType 特性集覆盖。
Dictionary font_get_ot_name_strings ( RID font_rid ) const
返回 OpenType 字体名称字符串的 Dictionary(本地化的字体名称、版本、描述、许可信息、示例文本等)。
float font_get_oversampling ( RID font_rid ) const
返回字体过采样系数,如果设置为 0.0
,则使用全局过采样系数。仅由动态字体使用。
float font_get_scale ( RID font_rid, int size ) const
返回颜色位图字体的缩放系数。
bool font_get_script_support_override ( RID font_rid, String script )
如果为 script
启用了支持覆盖,则返回 true
。
PackedStringArray font_get_script_support_overrides ( RID font_rid )
返回文字支持覆盖的列表。
Vector2i[] font_get_size_cache_list ( RID font_rid ) const
返回缓存中字体大小的列表。每个大小都是由字体大小和轮廓大小组成的 Vector2i。
int font_get_spacing ( RID font_rid, SpacingType spacing ) const
返回 spacing
(见 SpacingType)的间距,单位为像素(与字体大小无关)。
int font_get_stretch ( RID font_rid ) const
返回与正常宽度相比的字体拉伸量。一个介于 50%
和 200%
之间的百分比值。
BitField<FontStyle> font_get_style ( RID font_rid ) const
返回字体样式标志,见 FontStyle。
String font_get_style_name ( RID font_rid ) const
返回字体样式名称。
SubpixelPositioning font_get_subpixel_positioning ( RID font_rid ) const
返回字体的次像素字形定位模式。
String font_get_supported_chars ( RID font_rid ) const
返回包含字体中所有可用字符的字符串。
int font_get_texture_count ( RID font_rid, Vector2i size ) const
返回字体缓存条目所使用的纹理数。
Image font_get_texture_image ( RID font_rid, Vector2i size, int texture_index ) const
返回字体缓存纹理图像数据。
PackedInt32Array font_get_texture_offsets ( RID font_rid, Vector2i size, int texture_index ) const
返回包含字形打包数据的数组。
Transform2D font_get_transform ( RID font_rid ) const
返回应用于字体轮廓的 2D 变换。
float font_get_underline_position ( RID font_rid, int size ) const
返回基线下方下划线的像素偏移。
float font_get_underline_thickness ( RID font_rid, int size ) const
返回下划线的粗细度,单位为像素。
Dictionary font_get_variation_coordinates ( RID font_rid ) const
返回指定字体缓存条目的变体坐标。详见 font_supported_variation_list。
int font_get_weight ( RID font_rid ) const
返回该字体的字重(粗度)。一个在 100...999
范围内的值,正常字体字重为 400
,粗体字体字重为 700
。
bool font_has_char ( RID font_rid, int char ) const
如果该字体中包含 Unicode 字符 char
,则返回 true
。
bool font_is_allow_system_fallback ( RID font_rid ) const
如果可以自动使用系统字体作为回退字体,则返回 true
。
bool font_is_force_autohinter ( RID font_rid ) const
如果自动提示被支持且优先于字体内置提示,则返回 true
。仅由动态字体使用。
bool font_is_language_supported ( RID font_rid, String language ) const
如果该字体支持给定的语言(ISO 639 代码),则返回 true
。
bool font_is_multichannel_signed_distance_field ( RID font_rid ) const
如果使用从动态字体矢量数据生成的单个多通道有符号距离场渲染所有大小的字形,则返回 true
。
bool font_is_script_supported ( RID font_rid, String script ) const
如果字体支持给定的文字(ISO 15924 代码),则返回 true
。
void font_remove_glyph ( RID font_rid, Vector2i size, int glyph )
从缓存条目中移除指定的渲染字形信息。
注意:这个函数不会移除与字形相关的纹理,请使用 font_remove_texture 手动移除。
void font_remove_kerning ( RID font_rid, int size, Vector2i glyph_pair )
移除字形对的字距调整覆盖。
void font_remove_language_support_override ( RID font_rid, String language )
移除语言支持覆盖。
void font_remove_script_support_override ( RID font_rid, String script )
移除文字支持覆盖。
void font_remove_size_cache ( RID font_rid, Vector2i size )
从缓存条目中移除指定的字体大小。
void font_remove_texture ( RID font_rid, Vector2i size, int texture_index )
从缓存条目中移除指定纹理。
注意:这个函数不会移除与纹理关联的字形,请使用 font_remove_glyph 手动移除。
void font_render_glyph ( RID font_rid, Vector2i size, int index )
将指定的字符渲染到字体缓存纹理。
void font_render_range ( RID font_rid, Vector2i size, int start, int end )
将范围内的字符渲染到字体缓存纹理。
void font_set_allow_system_fallback ( RID font_rid, bool allow_system_fallback )
如果设置为 true
,则可以自动将系统字体作为回退使用。
void font_set_antialiasing ( RID font_rid, FontAntialiasing antialiasing )
使用字体抗锯齿模式。
void font_set_ascent ( RID font_rid, int size, float ascent )
设置字体的升部(基线上方的像素数)。
void font_set_data ( RID font_rid, PackedByteArray data )
设置字体源数据,例如动态字体的源文件内容。
void font_set_descent ( RID font_rid, int size, float descent )
设置字体的降部(基线下方的像素数)。
void font_set_embolden ( RID font_rid, float strength )
设置字体的加粗强度。如果 strength
不等于零,则会加粗字体轮廓。负值会减小轮廓的粗细度。
void font_set_face_index ( RID font_rid, int face_index )
在 TrueType / OpenType 集合中设置活动字体索引。
void font_set_fixed_size ( RID font_rid, int fixed_size )
设置位图字体的固定大小。如果设置为大于零的值,则会为所有字体大小使用相同的缓存条目。
void font_set_fixed_size_scale_mode ( RID font_rid, FixedSizeScaleMode fixed_size_scale_mode )
设置位图字体缩放模式。仅当 fixed_size
大于零时才使用该属性。
void font_set_force_autohinter ( RID font_rid, bool force_autohinter )
如果设置为 true
,则优先使用自动微调,而不是字体的内置微调。
void font_set_generate_mipmaps ( RID font_rid, bool generate_mipmaps )
如果设置为 true
,则启用字体纹理 mipmap 生成。
void font_set_global_oversampling ( float oversampling )
设置过采样系数,由 TextServer 中的所有字体共享。
注意:显示服务器可能自动更改这个值。
void font_set_glyph_advance ( RID font_rid, int size, int glyph, Vector2 advance )
设置字形前进量(下一个字形的偏移量)。
注意:字形轮廓的前进量与基础字形的前进量相同,不会被保存。
void font_set_glyph_offset ( RID font_rid, Vector2i size, int glyph, Vector2 offset )
设置字形相对于基线的偏移量。
void font_set_glyph_size ( RID font_rid, Vector2i size, int glyph, Vector2 gl_size )
设置字形的大小。
void font_set_glyph_texture_idx ( RID font_rid, Vector2i size, int glyph, int texture_idx )
设置包含该字形的缓存纹理的索引。
void font_set_glyph_uv_rect ( RID font_rid, Vector2i size, int glyph, Rect2 uv_rect )
设置包含该字形的缓存纹理中,该字形的矩形区域。
void font_set_hinting ( RID font_rid, Hinting hinting )
设置字体微调模式。仅由动态字体使用。
void font_set_kerning ( RID font_rid, int size, Vector2i glyph_pair, Vector2 kerning )
设置字形对的字距调整。
void font_set_language_support_override ( RID font_rid, String language, bool supported )
为 font_is_language_supported 添加覆盖。
void font_set_msdf_pixel_range ( RID font_rid, int msdf_pixel_range )
设置最小和最大可表示有符号距离之间形状周围范围的宽度。
void font_set_msdf_size ( RID font_rid, int msdf_size )
设置用于生成 MSDF 纹理的源字体大小。
void font_set_multichannel_signed_distance_field ( RID font_rid, bool msdf )
如果设置为 true
,则所有大小的字形都使用同一个从动态字体向量数据生成的多通道带符号距离场进行渲染。MSDF 渲染能够使用任意缩放系数显示字体,字体不会变得模糊,字体大小的改变也不会消耗 CPU 的性能(因为字体不再需要在 CPU 上进行光栅化)。缺点是MSDF 无法使用字体微调。缺少字体微调时,锐度可能降低,较小的字体可能不易阅读。
注意:MSDF 字体渲染无法正确渲染存在形状重叠的字形。重叠的形状在 OpenType 标准中是无效的,但在很多字体文件中仍然很常见,尤其是经过 Google Fonts 转换后的那些。要避免形状重叠带来的问题,请考虑直接从字体厂商下载字体文件,不要依赖 Google Fonts。
void font_set_name ( RID font_rid, String name )
设置该字体的家族名称。
void font_set_opentype_feature_overrides ( RID font_rid, Dictionary overrides )
设置字体 OpenType 特性集覆盖。
void font_set_oversampling ( RID font_rid, float oversampling )
设置字体的过采样系数,如果设置为 0.0
,则会改用全局过采样系数。仅由动态字体使用。
void font_set_scale ( RID font_rid, int size, float scale )
设置彩色位图字体的缩放系数。
void font_set_script_support_override ( RID font_rid, String script, bool supported )
为 font_is_script_supported 添加覆盖。
void font_set_spacing ( RID font_rid, SpacingType spacing, int value )
将 spacing
的间距(见 SpacingType)设置为 value
,单位为像素(与字体大小无关)。
void font_set_stretch ( RID font_rid, int weight )
设置字体相对于普通宽度的拉伸量,是在 50%
和 200%
之间的百分比值。
注意:这个值仅用于匹配字体,不会影响字体的渲染。请改用 font_set_face_index、font_set_variation_coordinates 或 font_set_transform。
void font_set_style ( RID font_rid, BitField<FontStyle> style )
设置字体样式标志,见 FontStyle。
注意:这个值仅用于匹配字体,不会影响字体的渲染。请改用 font_set_face_index、font_set_variation_coordinates、font_set_embolden 或 font_set_transform。
void font_set_style_name ( RID font_rid, String name )
设置字体的样式名称。
void font_set_subpixel_positioning ( RID font_rid, SubpixelPositioning subpixel_positioning )
设置字体的次像素字形定位模式。
void font_set_texture_image ( RID font_rid, Vector2i size, int texture_index, Image image )
设置字体的缓存纹理图像数据。
void font_set_texture_offsets ( RID font_rid, Vector2i size, int texture_index, PackedInt32Array offset )
设置包含字形打包数据的数组。
void font_set_transform ( RID font_rid, Transform2D transform )
设置应用于字体轮廓的 2D 变换,可用于倾斜、翻转和旋转字形。
例如,要通过倾斜来模拟斜体字体,请应用以下变换 Transform2D(1.0, slant, 0.0, 1.0, 0.0, 0.0)
。
void font_set_underline_position ( RID font_rid, int size, float underline_position )
设置基线下方下划线的像素偏移。
void font_set_underline_thickness ( RID font_rid, int size, float underline_thickness )
设置下划线的粗细度,单位为像素。
void font_set_variation_coordinates ( RID font_rid, Dictionary variation_coordinates )
为指定的字体缓存条目设置变体坐标。详见 font_supported_variation_list。
void font_set_weight ( RID font_rid, int weight )
设置字体的字重(粗度)。字重是在 100...999
范围内的值,普通字重为 400
,粗体字重为 700
。
注意:这个值仅用于匹配字体,不会影响字体的渲染。请改用 font_set_face_index、font_set_variation_coordinates、font_set_embolden 或 font_set_transform。
Dictionary font_supported_feature_list ( RID font_rid ) const
返回支持的 OpenType 特性的字典。
Dictionary font_supported_variation_list ( RID font_rid ) const
返回支持的 OpenType 变体坐标的字典。
String format_number ( String number, String language="" ) const
将数字从阿拉伯数字(0..9)转换为 language
语言的记数系统。
如果省略 language
,则会使用激活的区域设置。
void free_rid ( RID rid )
释放由该 TextServer 创建的某个对象。
int get_features ( ) const
返回文本服务器的功能,见 Feature。
Vector2 get_hex_code_box_size ( int size, int index ) const
返回替换字符的大小(在无效字符处绘制的带十六进制字符代码的框)。
String get_name ( ) const
返回该服务器接口的名称。
String get_support_data_filename ( ) const
返回默认的 TextServer 数据库(例如 ICU 中断迭代器和字典)文件名。
String get_support_data_info ( ) const
返回 TextServer 数据库(例如 ICU 中断迭代器和字典)的描述。
如果 rid
是该文本服务器拥有的有效资源,则返回 true
。
bool has_feature ( Feature feature ) const
如果服务器支持某个功能,则返回 true
。
int is_confusable ( String string, PackedStringArray dict ) const
返回 dict
中可能与 string
发生视觉混淆的第一个字符串的索引,如果没有找到则返回 -1
。
注意:这个方法不检测不可见字符,要进行欺骗性检测,请与 spoof_check 结合使用。
注意:如果该服务器不支持 FEATURE_UNICODE_SECURITY 特性,则始终返回 -1
。
bool is_locale_right_to_left ( String locale ) const
如果区域设置为从右至左,则返回 true
。
bool is_valid_identifier ( String string ) const
如果 string
为有效的标识符,则返回 true
。
如果文字服务器支持 FEATURE_UNICODE_IDENTIFIERS 特性,则有效的标识符必须:
遵循 C 范式。
开头是 XID_Start 类的 Unicode 字符或
"_"
。其他位置可以包含 XID_Continue 类的 Unicode 字符。
仅使用 UAX #31 推荐的文字(允许混合文字)。
如果不支持 FEATURE_UNICODE_IDENTIFIERS 特性,则有效的标识符必须:
开头是 XID_Start 类的 Unicode 字符或
"_"
。其他位置可以包含 XID_Continue 类的 Unicode 字符。
bool load_support_data ( String filename )
加载可选的 TextServer 数据库(例如 ICU 断字迭代器和字典)。
注意:这个函数应该在使用任何其他 TextServer 函数之前调用,否则不会起任何作用。
int name_to_tag ( String name ) const
将特性、变体、文字、语言的可读名称转换为 OpenType 标记。
String parse_number ( String number, String language="" ) const
将数字 number
从 language
的记数系统转换为阿拉伯数字(0..9)。
Vector3i[] parse_structured_text ( StructuredTextParser parser_type, Array args, String text ) const
BiDi 算法覆盖函数的默认实现。有关详细信息,请参阅 StructuredTextParser。
String percent_sign ( String language="" ) const
返回语言 language
中使用的百分比符号。
bool save_support_data ( String filename ) const
将可选的 TextServer 数据库(例如 ICU 断字迭代器和字典)保存到文件中。
注意:这个函数在导出项目时会用到,用于包含 TextServer 数据库。
int shaped_get_span_count ( RID shaped ) const
返回使用 shaped_text_add_string 或 shaped_text_add_object 添加的文本区间的数量。
Variant shaped_get_span_meta ( RID shaped, int index ) const
返回文本区间的元数据。
void shaped_set_span_update_font ( RID shaped, int index, RID[] fonts, int size, Dictionary opentype_features={} )
在不更改文本的情况下,更改文本区间的字体、字体大小和 OpenType 功能。
bool shaped_text_add_object ( RID shaped, Variant key, Vector2 size, InlineAlignment inline_align=5, int length=1, float baseline=0.0 )
向文本缓冲中添加内联对象,key
必须唯一。在文本中,对象使用 length
个对象替换字符表示。
bool shaped_text_add_string ( RID shaped, String text, RID[] fonts, int size, Dictionary opentype_features={}, String language="", Variant meta=null )
添加文本区间和字体,将其绘制到文本缓冲中。
void shaped_text_clear ( RID rid )
清空文本缓冲(移除文本和内联对象)。
int shaped_text_closest_character_pos ( RID shaped, int pos ) const
返回距离 pos
最近的组合字符位置。
void shaped_text_draw ( RID shaped, RID canvas, Vector2 pos, float clip_l=-1, float clip_r=-1, Color color=Color(1, 1, 1, 1) ) const
在画布项的给定位置绘制塑形后的文本,颜色为 color
。pos
指定的是基线的最左侧(横向排版)或基线的最顶部(纵向排版)。
void shaped_text_draw_outline ( RID shaped, RID canvas, Vector2 pos, float clip_l=-1, float clip_r=-1, int outline_size=1, Color color=Color(1, 1, 1, 1) ) const
在画布项的给定位置绘制塑形后的文本轮廓,颜色为 color
。pos
指定的是基线的最左侧(横向排版)或基线的最顶部(纵向排版)。
float shaped_text_fit_to_width ( RID shaped, float width, BitField<JustificationFlag> justification_flags=3 )
两端对齐文本以适合指定宽度,返回新的文本宽度。
float shaped_text_get_ascent ( RID shaped ) const
返回文本上高(水平布局基线上方的像素数,或垂直布局基线左侧的像素数)。
注意:如果某些字形偏离基线,则总体上高可能高于字体上高。
Dictionary shaped_text_get_carets ( RID shaped, int position ) const
返回与文本中字符偏移 position
对应的文本光标的形状。返回的光标形状是宽度为 1 像素的矩形。
PackedInt32Array shaped_text_get_character_breaks ( RID shaped ) const
返回组合字符边界的数组。
String shaped_text_get_custom_punctuation ( RID shaped ) const
返回自定义标点字符列表,用于断字。如果被设置为空字符串,则使用服务的默认值。
float shaped_text_get_descent ( RID shaped ) const
返回文本下深(水平布局基线下方的像素数,或垂直布局基线右侧的像素数)。
注意:如果某些字形偏离基线,则总体下深可能高于字体下深。
Direction shaped_text_get_direction ( RID shaped ) const
返回文本的方向。
Direction shaped_text_get_dominant_direction_in_range ( RID shaped, int start, int end ) const
返回文本范围内的主要书写方向。
int shaped_text_get_ellipsis_glyph_count ( RID shaped ) const
返回省略号中的字形数。
Dictionary[] shaped_text_get_ellipsis_glyphs ( RID shaped ) const
返回省略号中的字形数组。
int shaped_text_get_ellipsis_pos ( RID shaped ) const
返回省略号的位置。
int shaped_text_get_glyph_count ( RID shaped ) const
返回缓冲区中的字形数。
Dictionary[] shaped_text_get_glyphs ( RID shaped ) const
返回字形数组,按视觉顺序排序。
Vector2 shaped_text_get_grapheme_bounds ( RID shaped, int pos ) const
将复合字符的边界返回为距行首的偏移量。
Direction shaped_text_get_inferred_direction ( RID shaped ) const
返回由 BiDi 算法推断的文本书写方向。
PackedInt32Array shaped_text_get_line_breaks ( RID shaped, float width, int start=0, BitField<LineBreakFlag> break_flags=3 ) const
对文本进行断行,返回每一行的字符范围。
PackedInt32Array shaped_text_get_line_breaks_adv ( RID shaped, PackedFloat32Array width, int start=0, bool once=true, BitField<LineBreakFlag> break_flags=3 ) const
将文本拆分为行和列。返回每段的字符范围。
Rect2 shaped_text_get_object_rect ( RID shaped, Variant key ) const
返回内联对象的边界矩形。
Array shaped_text_get_objects ( RID shaped ) const
返回内联对象的数组。
Orientation shaped_text_get_orientation ( RID shaped ) const
返回文本朝向。
RID shaped_text_get_parent ( RID shaped ) const
返回子字符串源自哪个父缓冲区。
bool shaped_text_get_preserve_control ( RID shaped ) const
如果文本缓冲区被配置为显示控制字符,则返回 true
。
bool shaped_text_get_preserve_invalid ( RID shaped ) const
如果文本缓冲区被配置为在无效字符处显示十六进制代码,则返回 true
。
注意:如果设置为 false
,则在无效字符处不显示任何内容。
Vector2i shaped_text_get_range ( RID shaped ) const
返回父缓冲区中子字符串缓冲区的字符范围。
PackedVector2Array shaped_text_get_selection ( RID shaped, int start, int end ) const
返回用于指定字符范围的选区矩形。
Vector2 shaped_text_get_size ( RID shaped ) const
返回该文本的大小。
int shaped_text_get_spacing ( RID shaped, SpacingType spacing ) const
返回字形或行之间添加的额外间距,单位为像素。
int shaped_text_get_trim_pos ( RID shaped ) const
返回超出修剪的位置。
float shaped_text_get_underline_position ( RID shaped ) const
返回基线下方下划线的像素偏移。
float shaped_text_get_underline_thickness ( RID shaped ) const
返回下划线的粗细度。
float shaped_text_get_width ( RID shaped ) const
返回文本的宽度(对于水平排版)或高度(对于垂直排版)。
PackedInt32Array shaped_text_get_word_breaks ( RID shaped, BitField<GraphemeFlag> grapheme_flags=264 ) const
将文本分解成单词并返回字符范围的数组。请使用 grapheme_flags
来设置哪些字符会被用于分解(见 GraphemeFlag)。
bool shaped_text_has_visible_chars ( RID shaped ) const
如果文本缓冲区存在可显示字符,则返回 true
。
int shaped_text_hit_test_grapheme ( RID shaped, float coords ) const
返回字素的索引,该字素位于基线上指定像素偏移的位置,如果没有找到,则返回 -1
。
int shaped_text_hit_test_position ( RID shaped, float coords ) const
返回基线处指定像素偏移处的文本光标的偏移量。该函数始终返回一个有效位置。
bool shaped_text_is_ready ( RID shaped ) const
如果缓冲区成功塑形,则返回 true
。
int shaped_text_next_character_pos ( RID shaped, int pos ) const
返回距离 pos
最近的组合字符结束位置。
int shaped_text_next_grapheme_pos ( RID shaped, int pos ) const
返回距离 pos
最近的字素结束位置。
void shaped_text_overrun_trim_to_width ( RID shaped, float width=0, BitField<TextOverrunFlag> overrun_trim_flags=0 )
如果文本超出给定宽度,则修剪文本。
int shaped_text_prev_character_pos ( RID shaped, int pos ) const
返回距离 pos
最近的组合字符开始位置。
int shaped_text_prev_grapheme_pos ( RID shaped, int pos ) const
返回距离 pos
最近的字素开始位置。
bool shaped_text_resize_object ( RID shaped, Variant key, Vector2 size, InlineAlignment inline_align=5, float baseline=0.0 )
设置嵌入对象的新大小和对齐方式。
void shaped_text_set_bidi_override ( RID shaped, Array override )
覆盖用于结构化文本的 BiDi。
覆盖范围应覆盖完整的源文本而没有重叠。BiDi 算法将分别被用于每个范围。
void shaped_text_set_custom_punctuation ( RID shaped, String punct )
设置自定义标点字符列表,用于断字。如果被设置为空字符串,则使用服务的默认值。
void shaped_text_set_direction ( RID shaped, Direction direction=0 )
设置所需的文本方向。如果设置为 DIRECTION_AUTO,方向将根据缓冲区的内容和当前的区域设置来检测。
注意:如果服务器不支持 FEATURE_BIDI_LAYOUT 特性,则方向会被忽略(TextServerAdvanced 支持)。
void shaped_text_set_orientation ( RID shaped, Orientation orientation=0 )
设置所需的文本排版方向。
注意:如果服务不支持 FEATURE_VERTICAL_LAYOUT 功能(由 TextServerAdvanced 支持),则排版方向将被忽略。
void shaped_text_set_preserve_control ( RID shaped, bool enabled )
如果设置为 true
,则文本缓冲区将显示控制字符。
void shaped_text_set_preserve_invalid ( RID shaped, bool enabled )
如果设置为 true
,则文本缓冲区会将无效字符显示为十六进制代码,否则不显示任何内容。
void shaped_text_set_spacing ( RID shaped, SpacingType spacing, int value )
设置字形之间或行与行之间添加的额外像素间距。
bool shaped_text_shape ( RID shaped )
形状缓冲区(如果未整形)。如果字符串整形成功,则返回 true
。
注意:无需手动调用该函数,只要请求其任何输出数据,缓冲区就会自动被整形。
Dictionary[] shaped_text_sort_logical ( RID shaped )
按逻辑顺序返回文本字形。
RID shaped_text_substr ( RID shaped, int start, int length ) const
返回 shaped
文本缓冲区中字符串的子字符串的文本缓冲区(包括内联对象)。
float shaped_text_tab_align ( RID shaped, PackedFloat32Array tab_stops )
将塑形文本与给定的制表位对齐。
bool spoof_check ( String string ) const
如果 string
可能造成读者的混淆,则返回 true
。
注意:如果服务器不支持 FEATURE_UNICODE_SECURITY 特性,则始终返回 false
。
PackedInt32Array string_get_character_breaks ( String string, String language="" ) const
返回组合字符边界的数组。
var ts = TextServerManager.get_primary_interface()
print(ts.string_get_word_breaks("Test ❤️🔥 Test")) # 输出 [1, 2, 3, 4, 5, 9, 10, 11, 12, 13, 14]
PackedInt32Array string_get_word_breaks ( String string, String language="", int chars_per_line=0 ) const
返回分词边界的数组。返回数组中的元素是单词的起点和终点偏移量。因此,该数组的长度始终为偶数。
chars_per_line
大于零时,返回的是分行边界。
var ts = TextServerManager.get_primary_interface()
print(ts.string_get_word_breaks("Godot Engine")) # 输出 [0, 5, 6, 12]
print(ts.string_get_word_breaks("Godot Engine", "en", 5)) # 输出 [0, 5, 6, 11, 11, 12]
String string_to_lower ( String string, String language="" ) const
返回转换为小写的字符串。
注意:如果服务器支持 FEATURE_CONTEXT_SENSITIVE_CASE_CONVERSION 特性(TextServerAdvanced 支持),则大小写取决于区域设置,并且对上下文敏感。
注意:得到的字符串可能比原来的更长,也可能更短。
String string_to_upper ( String string, String language="" ) const
返回转换为大写的字符串。
注意:如果服务器支持 FEATURE_CONTEXT_SENSITIVE_CASE_CONVERSION 特性(TextServerAdvanced 支持),则大小写取决于区域设置,并且对上下文敏感。
注意:得到的字符串可能比原来的更长,也可能更短。
String strip_diacritics ( String string ) const
从字符串中剥离变音符号。
注意:得到的字符串可能比原来的更长,也可能更短。
String tag_to_name ( int tag ) const
将 OpenType 标签转换为可读的特性、变体、文字或语言的名称。