Extra2D/tools/msdf_font_builder/README.md

MSDF Font Builder

将 TTF 字体转换为 MSDF PNG 图集的离线构建工具。

直接集成 msdfgen 库，无需外部依赖。

构建

xmake build msdf_font_builder

使用方法

# 基本用法
msdf_font_builder -i font.ttf -o font.msdf.png

# 指定字符集
msdf_font_builder -i font.ttf -o font.msdf.png -c "ABCabc123"

# 使用字符集文件
msdf_font_builder -i font.ttf -o font.msdf.png -f charset.txt

# 自定义参数
msdf_font_builder -i font.ttf -o font.msdf.png -s 64 -r 6.0 -w 4096 -h 4096

命令行选项

选项	说明	默认值
-i, --input	输入 TTF 字体文件	必需
-o, --output	输出 PNG 图集路径	必需
-c, --charset	字符集字符串	ASCII 可打印字符
-f, --charset-file	字符集文件路径	-
-s, --size	字体大小（像素）	48
-r, --range	像素范围	4.0
-w, --width	图集宽度	2048
-h, --height	图集高度	2048

输出格式

生成的 PNG 文件包含嵌入的元数据（存储在 tEXt chunk 中）：

{
  "size": 48,
  "pxRange": 4.0,
  "lineHeight": 60,
  "baseline": 12,
  "atlas": { "width": 2048, "height": 2048 },
  "glyphs": [...]
}

在 Extra2D 中使用

#include <extra2d/asset/font_asset.h>
#include <extra2d/render/text_renderer.h>

auto font = assetService->load<FontAsset>("font.msdf.png");

TextRenderer renderer;
renderer.init();
renderer.begin(projection);
renderer.drawText(font.get(), U"Hello, World!", 100, 100, { .fontSize = 32.0f });
renderer.end();

工作流程

构建时: TTF ──► msdfgen 库 ──► MSDF PNG (内嵌 JSON 元数据)
运行时: FontLoader ──► FontAsset ──► TextRenderer