Godot TextServerExtension 深入解析:自定义文本服务插件基类与 150+ 虚拟方法全指南
Godot TextServerExtension 深入解析:自定义文本服务插件基类与 150+ 虚拟方法全指南
导读
TextServerExtension 是 Godot Engine 中所有外部自定义文本服务(TextServer)实现的基类,它把字体管理、复杂文本排版(shaping)、BiDi 双向文本、文本测量与绘制、断行断词、字符与数字本地化等能力抽象为一套约 150 个带下划线前缀的虚拟方法(virtual methods)。本文以 classes/class_textserverextension.rst 的完整类参考为主线,结合仓库中 TextServer、TextServerAdvanced、TextServerDummy、TextServerFallback 等兄弟类文档与国际化教程,系统讲解该基类的继承关系、方法分组、必需实现(required)与可选实现(virtual)的边界,以及每个核心虚拟方法的签名与语义,帮助你理解甚至独立实现一个自定义 TextServer 插件。
TextServerExtension 在 Godot 文本体系中的位置
继承链与兄弟类
TextServerExtension 处于 Godot 文本服务体系的中间层,其继承关系如下:
TextServerExtension
└── TextServer <── RefCounted <── Object
从继承链可以看出,TextServerExtension 本身继承自 TextServer(后者又继承自 RefCounted 与 Object)。TextServer 是“面向使用者的 API 接口”,而 TextServerExtension 是“面向实现者的插件基类”。按照官方类参考的说明,外部 TextServer 实现应当继承自 TextServerExtension,而不是直接实现 TextServer。
在 Godot 官方代码库中,已经存在三个基于该基类的内置实现(见 class_textserverextension.rst 的 "Inherited By" 列表):
| 实现类 | 特点 | 文档来源 |
|---|---|---|
TextServerAdvanced |
Godot 默认主接口,基于 HarfBuzz、ICU 与 SIL Graphite,支持 BiDi、复杂文本布局与上下文相关的 OpenType 特性 | classes/class_textserveradvanced.rst |
TextServerFallback |
回退实现,处理大量文本时更快,但不支持 BiDi 与复杂文本布局;不属于官方二进制的默认组成,需以 module_text_server_fb_enabled=yes 编译启用 |
classes/class_textserverfallback.rst |
TextServerDummy |
不渲染文本、不管理字体的空实现,用于节省内存或做 GUI 文本渲染性能对比 | classes/class_textserverdummy.rst |
与父类 TextServer 的分工
TextServer 被官方描述为“管理字体与渲染文本的服务接口(server interface)”,同时官方明确提示:
这是一个底层 API,建议优先考虑使用
TextLine、TextParagraph和Font类,而不是直接操作该接口。
而获取当前激活 TextServer 实例的标准方式是:
var ts = TextServerManager.get_primary_interface()
var ts = TextServerManager.GetPrimaryInterface();
也就是说:上层控件(Label、RichTextLabel、LineEdit 等)通过 TextServer 的公开方法使用文本能力,而这些公开方法在底层会调用 TextServerExtension 提供的虚拟方法。因此,自定义文本服务的核心工作,就是把 TextServer 接口中对应的方法以带下划线前缀的虚拟方法形式逐一实现。
方法总览:分组与“必需 / 可选”语义
本类参考中列出的方法都带有 |virtual| 标记,其中一部分额外带有 |required| 标记。这两个标记的含义如下:
- virtual:该方法通常需要用户覆写才有效果;
- required:扩展该基类时必须覆写;
- const:该方法没有副作用,不会修改实例的成员变量。
从方法命名与功能上,全部虚拟方法可以划分为以下几大分组:
- 服务生命周期与能力声明:
_cleanup、_get_name、_get_short_name、_get_features、_has_feature、_free_rid、_has; - 字体资源创建与缓存管理:
_create_font、_create_font_linked_variation、_font_clear_*、_font_remove_*、_font_get_size_cache_list等; - 字体属性读写:
_font_get/set_ascent、_font_get/set_descent、_font_get/set_weight、_font_get/set_style、_font_get/set_name、_font_get/set_spacing、_font_get/set_kerning等; - 字形(Glyph)栅格化与绘制:
_font_render_glyph、_font_render_range、_font_draw_glyph、_font_draw_glyph_outline、_font_get_glyph_*等; - 字形纹理图集(texture atlas)管理:
_font_set/get_texture_image、_font_get_texture_count、_font_get_glyph_uv_rect、_font_get_glyph_texture_rid等; - 复杂文本排版(shaping)缓冲区:
_create_shaped_text、_shaped_text_add_string、_shaped_text_add_object、_shaped_text_shape、_shaped_get_*(run/span 查询)等; - 排版结果查询与绘制:
_shaped_text_get_glyphs、_shaped_text_get_size、_shaped_text_get_ascent/descent、_shaped_text_draw、_shaped_text_draw_outline等; - 断行、断词与对齐:
_shaped_text_get_line_breaks、_shaped_text_get_word_breaks、_shaped_text_fit_to_width、_shaped_text_tab_align、_shaped_text_overrun_trim_to_width等; - 文本编辑辅助:
_shaped_text_hit_test_position、_shaped_text_get_carets、_shaped_text_get_selection、_shaped_text_substr、_shaped_text_duplicate等; - Unicode / 本地化支持:
_string_to_lower/upper/title、_string_get_character_breaks、_string_get_word_breaks、_format_number、_parse_number、_strip_diacritics、_spoof_check、_is_confusable等; - 支持数据(break iterator 数据库)管理:
_get_support_data、_load_support_data、_save_support_data等。
服务生命周期与能力声明(required 核心)
一个自定义 TextServer 插件必须首先声明“我是谁、我能做什么、如何管理资源”,这些方法大多带 |required| 标记:
_get_name()→ String(required):返回服务器接口的名称,如 "Advanced"。_get_short_name()→ String(virtual):返回接口的短名。按约定应为snake_case的小写字符串。_get_features()→ int(required):返回文本服务器支持的 feature 位掩码,具体取值参见TextServer.Feature枚举。- `_has_feature(feature: Feature) → bool(required):查询服务器是否支持某个特定 feature。
_cleanup()(virtual):在文本服务器被注销(unregister)之前调用,用于释放全局资源。- `_free_rid(rid: RID)(required):释放本 TextServer 创建的任意对象(字体、排版缓冲区等)。
- **
_has(rid: RID) → bool(required)**:判断给定的rid` 是否为本文本服务器拥有的有效资源。
以官方实现为参照:TextServerDummy 就是这些生命周期方法的极端例子——它“不渲染文本、不管理字体”,通过 TextServerManager.find_interface("Dummy") 获取后在不需要文本渲染时切换到主接口以节省内存:
var dummy_text_server = TextServerManager.find_interface("Dummy")
if dummy_text_server != null:
TextServerManager.set_primary_interface(dummy_text_server)
字体缓存体系:从创建到属性读写
字体资源创建
- `_create_font() → RID(required):创建一个新的、空的字体缓存条目(font cache entry)资源,返回其 RID。
- `_create_font_linked_variation(font_rid: RID) → RID(virtual):基于已有字体创建一个变体(variation),该变体复用同一个字形缓存与字体数据。文档特别注明:可选实现,仅当字体支持额外的间距或基线偏移时才需要。
字体缓存的分层结构
TextServerExtension 的字体体系是一个典型的“缓存 + 尺寸 + 纹理图集”结构:
- 每个字体 RID 对应一个 cache entry;
- 每个 cache entry 可以包含 多个字号(size)与描边尺寸(outline size),每个尺寸是一个
Vector2i(x 为字号、y 为描边尺寸); - 每个尺寸对应一组 字形(glyph)信息 与一组 纹理图集(texture atlas)。
对应的方法组包括:
| 操作 | 方法 |
|---|---|
| 移除全部已渲染字形 | _font_clear_glyphs(font_rid, size: Vector2i)(required) |
| 移除全部字号 | _font_clear_size_cache(font_rid)(required) |
| 移除全部纹理 | _font_clear_textures(font_rid, size: Vector2i)(required) |
| 移除单个字形 | _font_remove_glyph(font_rid, size: Vector2i, glyph)(required) |
| 移除单个字号 | _font_remove_size_cache(font_rid, size: Vector2i)(required) |
| 移除单个纹理 | _font_remove_texture(font_rid, size: Vector2i, texture_index)(required) |
| 列出缓存中的字号 | _font_get_size_cache_list(font_rid) → Array[Vector2i](required) |
| 获取缓存统计信息 | _font_get_size_cache_info(font_rid) → Array[Dictionary],每项包含 size_px(字号)、viewport_oversampling(视口过采样因子)、glyphs(已渲染字形数)、textures(纹理数)、textures_size(纹理数据字节数) |
字体度量与风格属性
字体度量(metrics)是排版正确性的基础,以下方法成对出现且多为 required:
_font_get_ascent(font_rid, size) / _font_set_ascent(...):基线以上的像素数;_font_get_descent(font_rid, size) / _font_set_descent(...):基线以下的像素数;_font_get_underline_position / _font_set_underline_position:下划线相对基线的像素偏移;_font_get_underline_thickness / _font_set_underline_thickness:下划线像素厚度;_font_get_scale / _font_set_scale:彩色位图字体的缩放因子;_font_get_fixed_size / _font_set_fixed_size:位图字体固定字号。若大于 0,则所有字号共用同一 cache entry;_font_get_fixed_size_scale_mode / _font_set_fixed_size_scale_mode:位图字体缩放模式,仅当fixed_size > 0时生效。
风格类属性大多为非 required 的可选实现:
_font_get/set_name:字体族名;_font_get/set_style(FontStyle 位掩码)与_font_get/set_style_name:字体风格;_font_get/set_weight:字重(粗度),取值100...999,常规为400,粗体为700;_font_get/set_stretch:相对常规宽度的拉伸百分比,范围50%...200%;_font_get/set_embolden:加粗强度,非零时加粗轮廓,负值减薄;_font_get/set_antialiasing、_font_get/set_hinting、_font_get/set_subpixel_positioning:渲染质量相关(动态字体专用);_font_get/set_transform:应用于字体轮廓的 2D 变换,可用于斜切、翻转与旋转字形;_font_get/set_baseline_offset:额外基线偏移(以字体高度比例表示);_font_get/set_spacing(SpacingType):按像素设置的字间距(不随字号缩放)。
语言与文字系统支持查询
- `_font_has_char(font_rid, char) → bool(required):查询字体是否包含某个 Unicode 字符;
- `_font_get_supported_chars(font_rid) → String(required):返回字体中全部可用字符组成的字符串;
- `_font_get_supported_glyphs(font_rid) → PackedInt32Array(required):返回字体全部字形索引;
_font_is_language_supported(font_rid, language) → bool:按 ISO 639 语言码查询支持情况;_font_is_script_supported(font_rid, script) → bool:按 ISO 15924 文字码查询支持情况;_font_set_language_support_override / _font_set_script_support_override:为上述查询添加覆盖(override);_font_get_face_count / _font_get_face_index / _font_set_face_index:TrueType/OpenType 集合(collection)中的 face 数量与激活 face 索引;_font_get_ot_name_strings:返回 OpenType 字体名称字符串字典(本地化字体名、版本、描述、许可证、示例文本等);_font_supported_feature_list/_font_supported_variation_list:返回支持的 OpenType feature / variation 坐标字典;_font_get/set_variation_coordinates:可变字体(variable font)的 variation 坐标;_font_get/set_opentype_feature_overrides:OpenType feature 集合覆盖。
字形索引与字距(Kerning)
- `_font_get_glyph_index(font_rid, size, char, variation_selector) → int(required):返回字符(可附带变体选择符)对应的字形索引;
- **
_font_get_char_from_glyph_index(font_rid, size, glyph_index) → int(required)**:反向映射,无效索引返回0`; _font_get/set_kerning(font_rid, size, glyph_pair: Vector2i):查询/设置某字形对(glyph pair)的字距;_font_get_kerning_list/_font_clear_kerning_map/_font_remove_kerning:管理全部字距覆盖项。
字形栅格化与纹理图集(glyph rasterization & texture atlas)
文本渲染性能的关键在于字形如何被栅格化并打包进纹理图集。TextServerExtension 将“渲染到缓存”与“从缓存绘制”分离:
渲染(写入缓存):
_font_render_glyph(font_rid, size: Vector2i, index):将指定字形栅格化到字体缓存纹理中;_font_render_range(font_rid, size: Vector2i, start, end):将一段字符范围批量栅格化到缓存纹理。
字形信息读取(required 为主):
_font_get_glyph_list(font_rid, size: Vector2i) → PackedInt32Array:缓存条目中已渲染字形的列表;_font_get_glyph_advance(font_rid, size, glyph) → Vector2:下一个字形的偏移(advance);_font_get_glyph_offset(font_rid, size: Vector2i, glyph) → Vector2:字形相对基线的偏移;_font_get_glyph_size(font_rid, size: Vector2i, glyph) → Vector2:字形尺寸;_font_get_glyph_texture_idx / _font_get_glyph_texture_rid:字形所在缓存纹理的索引 / RID;_font_get_glyph_uv_rect(font_rid, size: Vector2i, glyph) → Rect2:字形在缓存纹理中的 UV 矩形;_font_get_glyph_contours(font_rid, size, index) → Dictionary:字形轮廓曲线数据(可用于矢量缩放)。
纹理管理:
_font_get/set_texture_image(font_rid, size: Vector2i, texture_index) → Image(required):读写缓存纹理图像数据;_font_get_texture_count(font_rid, size: Vector2i) → int(required):缓存条目使用的纹理数量;_font_get/set_texture_offsets(font_rid, size, texture_index) → PackedInt32Array:字形打包(packing)数据。
绘制(读出缓存):
_font_draw_glyph(font_rid, canvas, size, pos, index, color, oversampling)(required, const):将单个字形绘制到 canvas item 的指定位置。若oversampling > 0则用作字体过采样因子,否则使用视口过采样设置;_font_draw_glyph_outline(...)(required, const):同上,但绘制的是outline_size大小的字形描边。
渲染模式选项:
_font_set_multichannel_signed_distance_field(font_rid, msdf: bool):启用 MSDF(多通道有符号距离场)渲染。启用后所有字号共用同一张由矢量数据生成的 MSDF 纹理,可在任意缩放比例下保持清晰、且字号变化时无需 CPU 重新栅格化;缺点是 MSDF 模式下没有字体 hinting,小字号可能不够清晰锐利。配套方法有_font_get/set_msdf_size(生成 MSDF 纹理的源字号)与_font_get/set_msdf_pixel_range(最小/最大可表示有符号距离之间的范围宽度);_font_set_generate_mipmaps/_font_get_generate_mipmaps:字体纹理 mipmap 生成开关;_font_set_disable_embedded_bitmaps/_font_get_disable_embedded_bitmaps:禁用字体内嵌位图;_font_set_allow_system_fallback/_font_get_allow_system_fallback(即_font_is_allow_system_fallback):是否允许自动使用系统字体作为回退,配套_font_clear_system_fallback_cache()释放自动加载的系统字体;_font_set_force_autohinter/_font_is_force_autohinter:是否优先使用自动 hinting 而非字体内置 hinting;_font_set_keep_rounding_remainders/_font_get_keep_rounding_remainders:字形对齐像素边界时是否累积舍入余数以获得更均匀的字形分布;启用亚像素定位时此设置无效;_font_set_modulate_color_glyphs/_font_is_modulate_color_glyphs:是否对彩色字形应用颜色调制(否则仅对单色字形调制);- 颜色面板:
_font_get_palette_count、_font_get_palette_name、_font_get_palette_colors、_font_get/set_palette_custom_colors(空数组表示重置覆盖,使用Color(0, 0, 0, 0)保留预定义面板中该位置的原始颜色)、_font_get/set_used_palette; - 过采样引用计数:
_font_get_global_oversampling/_font_set_global_oversampling管理全服务器共享的过采样因子;_reference_oversampling_level(oversampling)与_unreference_oversampling_level(oversampling)由Viewport调用维护每个过采样级别的引用计数,当计数归零时释放对应字体缓存——文档明确提醒“不应直接调用”。
复杂文本排版缓冲区:Shaped Text 全流程
TextServerExtension 的核心能力是把字符串排版成可测量的字形序列。流程如下:
- 创建缓冲区:
_create_shaped_text(direction: Direction, orientation: Orientation) → RID(required); - 添加内容:
_shaped_text_add_string(shaped, text, fonts: Array[RID], size, opentype_features: Dictionary, language, meta) → bool(required)添加文本 span;_shaped_text_add_object(shaped, key, size, inline_align, length, baseline) → bool(required)添加内联对象(如 RichTextLabel 中的图标),对象在文本中以length个对象替换字符表示,key必须唯一; - 执行 shaping:
_shaped_text_shape(shaped) → bool(required),若缓冲区尚未排版则执行排版; - 查询结果:通过
_shaped_get_*与_shaped_text_get_*系列读取字形、run、span、尺寸与度量; - 绘制:
_shaped_text_draw(...)/_shaped_text_draw_outline(...)输出到 canvas item。
span 与 run 的区别
- span:通过
_shaped_text_add_string/_shaped_text_add_object添加的、带有字体与元数据的源文本片段。_shaped_get_span_count()(required)返回 span 数量,_shaped_get_span_text、_shaped_get_span_meta、_shaped_get_span_object、_shaped_get_span_embedded_object分别读取其源文本、元数据与内嵌对象;_shaped_set_span_update_font(shaped, index, fonts, size, opentype_features)(required)可在不改变文本的情况下更换 span 的字体、字号与 OpenType 特性; - run:排版后的视觉顺序片段。
_shaped_get_run_count()返回 run 数量,_shaped_get_run_direction、_shaped_get_run_font_rid、_shaped_get_run_font_size、_shaped_get_run_language、_shaped_get_run_glyph_range、_shaped_get_run_range、_shaped_get_run_text、_shaped_get_run_object分别查询每个 run 的方向、字体、字号、语言、字形范围、源文本范围、源文本与内嵌对象。
字形与测量查询(required 为主)
_shaped_text_get_glyph_count/_shaped_text_get_glyphs(const Glyph*,按视觉顺序)与_shaped_text_sort_logical(const Glyph*,按逻辑顺序);_shaped_text_get_size → Vector2、_shaped_text_get_width → float(横排为宽度、竖排为高度);_shaped_text_get_ascent / _shaped_text_get_descent:横排时表示基线上/下方像素数,竖排时表示基线左/右侧像素数;_shaped_text_get_range → Vector2i:子串缓冲区在父缓冲区中的字符范围;_shaped_text_get_parent → RID:子串来源的父缓冲区;_shaped_text_get_direction、_shaped_text_get_inferred_direction(由 BiDi 算法推断的方向)、_shaped_text_get_dominant_direction_in_range、_shaped_text_get_orientation;_shaped_text_get_spacing、_shaped_text_get_underline_position、_shaped_text_get_underline_thickness、_shaped_text_get_trim_pos(overrun 裁剪位置)。
内联对象管理
_shaped_text_get_object_glyph、_shaped_text_get_object_range、_shaped_text_get_object_rect、_shaped_text_get_objects、_shaped_text_has_object、_shaped_text_resize_object(均 required)。
断行、断词、对齐与裁剪
_shaped_text_get_line_breaks(shaped, width, start, break_flags) → PackedInt32Array:按宽度断行,返回每行字符范围;_shaped_text_get_line_breaks_adv(shaped, width: PackedFloat32Array, start, once, break_flags):按多列宽度断行断列,返回每个片段范围;_shaped_text_get_word_breaks(shaped, grapheme_flags, skip_grapheme_flags) → PackedInt32Array:断词;_shaped_text_fit_to_width(shaped, width, justification_flags) → float:两端对齐到指定宽度,返回新的文本宽度;_shaped_text_tab_align(shaped, tab_stops: PackedFloat32Array) → float:按制表位对齐;_shaped_text_overrun_trim_to_width(shaped, width, trim_flags):超宽文本裁剪(配合_shaped_text_get_custom_ellipsis/_shaped_text_set_custom_ellipsis自定义省略号字符,以及_shaped_text_get_custom_punctuation/_shaped_text_set_custom_punctuation自定义断词标点);_shaped_text_update_breaks(shaped) → bool:更新断点,由默认断行函数调用;_shaped_text_update_justification_ops(shaped) → bool:更新对齐点,由默认对齐函数调用。
编辑与命中测试
_shaped_text_get_carets(shaped, position, r_caret: CaretInfo*):返回字符偏移position处光标的形状(1 像素宽的矩形),用于双向文本的光标绘制;_shaped_text_hit_test_position(shaped, coord) → int:基线像素偏移对应的光标字符偏移,总是返回有效位置;_shaped_text_hit_test_grapheme(shaped, coord) → int:命中测试到字素(grapheme)索引,未命中返回-1;_shaped_text_get_selection(shaped, start, end) → PackedVector2Array:指定字符范围的选区矩形;_shaped_text_get_character_breaks、_shaped_text_closest_character_pos、_shaped_text_next_character_pos、_shaped_text_prev_character_pos:复合字符边界与前后导航;_shaped_text_next_grapheme_pos、_shaped_text_prev_grapheme_pos、_shaped_text_get_grapheme_bounds:字素级导航与边界;_shaped_text_substr(shaped, start, length) → RID(required):取子串排版缓冲区(含内联对象);_shaped_text_duplicate(shaped) → RID(required):复制排版缓冲区;_shaped_text_clear(shaped)(required):清空缓冲区;_shaped_text_is_ready(shaped) → bool(required):缓冲区是否成功排版。
方向与 BiDi
_shaped_text_set_direction:设置期望方向,若为TextServer.DIRECTION_AUTO则根据缓冲区内容与当前 locale 自动检测;_shaped_text_set_orientation:设置期望朝向(横排/竖排);_shaped_text_set_bidi_override(shaped, override: Array):为结构化文本覆盖 BiDi 算法;_parse_structured_text(parser_type: StructuredTextParser, args: Array, text) → Array<a href="https://link.gitcode.com/i/4050952ed48f07b68af1699511ab53ea" target="_blank">Vector3i]:BiDi 算法覆盖函数的默认实现。这与 [tutorials/i18n/internationalizing_gods.rst 中“结构化文本 BiDi 覆盖”一节介绍的机制对应——Unicode BiDi 算法对文件名、URI、邮箱地址、正则表达式、源码这类“高层级顺序”的文本无能为力,而结构化文本解析器把文本按段落拆分后逐段应用 BiDi,从而保证目录名等片段在任意语言下正确显示并保持顺序;_shaped_text_set_preserve_control(shaped, enabled):是否显示控制字符;_shaped_text_set_preserve_invalid(shaped, enabled):是否将无效字符显示为十六进制码(配合_draw_hex_code_box与_get_hex_code_box_size,后者返回无效字符替身“十六进制码盒子”的尺寸)。
Unicode 处理与本地化支持方法
_string_to_lower(string, language)/_string_to_upper/_string_to_title:语言感知的大小写/标题转换;_string_get_character_breaks(string, language) → PackedInt32Array:复合字符边界;_string_get_word_breaks(string, language, chars_per_line) → PackedInt32Array:断词边界,返回数组元素是单词起止偏移,因此长度恒为偶数;_strip_diacritics(string):去除变音符(diacritics);_is_valid_identifier(string) → bool:字符串是否为合法标识符;_is_valid_letter(unicode) → bool:Unicode 码点是否为合法字母(该方法的官方描述暂缺,可由实现补充);_is_locale_right_to_left(locale) → bool:locale 是否为从右到左;_is_locale_using_support_data(locale) → bool:该 locale 的断行/断词是否需要文本服务器支持数据;_spoof_check(string) → bool:字符串是否疑似欺骗性文本(混淆阅读者);_is_confusable(string, dict: PackedStringArray) → int:返回dict中第一个与string视觉上易混淆的字符串索引,无则返回-1;_format_number(number, language)/_parse_number(number, language):西方阿拉伯数字(0..9)与给定语言数字系统之间的转换。文档标注两者已弃用,应改用TranslationServer.format_number()/TranslationServer.parse_number()。language为空时使用当前激活 locale。国际化教程中也给出了对应的使用方式:tutorials/i18n/internationalizing_games.rst 中提到 ProgressBar、SpinBox 等控件会自动使用本地化数字系统,其他控件则调用TextServer.format_number/parse_number进行转换;_percent_sign(language) → String:已弃用,改用TranslationServer.get_percent_sign();_name_to_tag(name) → int/_tag_to_name(tag) → String:OpenType feature/variation/script/language 可读名称与 OpenType tag 之间的双向转换。
支持数据(Support Data):断行断词数据库
部分语言不使用空格书写(如日语、泰语),其断行断词依赖 ICU 的规则与词典型 break iterator 数据。相关虚拟方法:
_get_support_data() → PackedByteArray:返回默认 TextServer 数据库(如 ICU break iterators 与词典);_get_support_data_filename() → String:返回该数据库文件名;_get_support_data_info() → String:返回数据库描述;_load_support_data(filename) → bool:从文件加载可选数据库;_save_support_data(filename) → bool:将数据库保存到文件。
这与国际化教程中“Adding break iterator data to exported project”一节相呼应:ICU 规则与词典型断行数据默认不包含在导出的项目中,需要在 Project > Project Settings > General > Internationalization > Locale 中启用 Include Text Server Data 后再导出,该数据约 4 MB。
自定义 TextServer 插件的实现要点
综合以上方法分组,实现一个自定义 TextServer 插件时需要特别关注以下几点:
- required 方法必须全部实现:
_create_font、_create_shaped_text、_font_clear_glyphs、_font_clear_size_cache、_font_clear_textures、_font_get_ascent/descent/scale/fixed_size/fixed_size_scale_mode、_font_get_glyph_*、_font_has_char、_font_get_supported_chars/glyphs、_font_render_glyph、_font_set_*(字形相关)、_free_rid、_get_features、_get_name、_has、_has_feature、_shaped_get_span_*、_shaped_text_add_*、_shaped_text_shape、_shaped_text_*的查询/管理方法等,都属于必需实现集合; - 非 required 的 virtual 方法按能力声明取舍:例如
_create_font_linked_variation仅在字体支持额外间距或基线偏移时需要;BiDi、断行、本地化等能力可通过_get_features/_has_feature声明,未声明的能力对应方法可以保持默认行为; - RID 资源管理是核心:所有字体与排版缓冲区都以
RID为句柄,_has与_free_rid必须能正确校验与释放这些资源,否则会造成资源泄漏; - 性能关键路径:字形栅格化结果缓存在字体 cache entry 的纹理图集中,
_font_render_glyph的批量渲染(_font_render_range)与过采样引用计数机制直接决定文本渲染的 CPU/GPU 开销;MSDF 模式则把“字号变化时的重栅格化成本”转移到 GPU 采样上,适合需要平滑缩放的场景; - 与上层 API 协同:默认情况下开发者应使用
TextLine、TextParagraph、Font等高层类,自定义 TextServer 插件通过TextServerManager注册为主接口后即可被这些高层类透明使用。官方现有的TextServerFallback(更快但无 BiDi/复杂排版)与TextServerDummy(完全不渲染,用于省内存与性能对比)是实现范例与测试基准。
延伸阅读
- 父类 API:
TextServer的全部公开方法见 classes/class_textserver.rst,其 "Inherited By" 指向本类; - 官方实现参考:TextServerAdvanced(默认主接口,HarfBuzz + ICU + SIL Graphite)、TextServerFallback、TextServerDummy;
- 实际应用场景:国际化教程 中的结构化文本 BiDi 覆盖、断行数据导出与数字本地化章节,可直接验证本文介绍的多组方法在真实项目中的用法。