freetype读取.ttf元数据需先用ft_new_face加载，再通过ft_is_sfnt确认格式，调用ft_get_sfnt_name_count/ft_get_sfnt_name提取name表并按platform_id+encoding_id转utf-8，用ft_load_sfnt_table读os/2表获取weight/width等数值型属性，不可直接解析文件头。
如何用FreeType读取.ttf文件的基本元数据
FreeType是解析TrueType字体最可靠的选择，它不依赖系统API，跨平台且能直接读取.ttf文件二进制结构。关键不是“渲染文字”，而是调用FT_Load_Sfnt_Table和FT_Get_Sfnt_Name这类SFNT专用接口——TrueType属于SFNT字体家族（与OpenType共享结构），必须走这条路才能拿到版权、字体名、版本号等真实嵌入信息。
常见错误是误用FT_Load_Char或只调用FT_Load_Glyph，这些函数加载的是字形数据，完全不包含元数据。另一个坑是没检查FT_IS_SFNT(face)就硬调SFNT函数，对非SFNT字体（如Bitmap或Type1）会返回FT_Err_Invalid_Argument。
- 先用
FT_New_Face加载.ttf路径，确保返回FT_Err_Ok - 立即用
FT_IS_SFNT(face)确认是否为SFNT格式（TrueType/OpenType都满足） - 调用
FT_Get_Sfnt_Name_Count获取名称表条目数，再循环用FT_Get_Sfnt_Name提取每条记录 - 注意
name->platform_id和name->encoding_id组合决定编码方式（如platform=3+encoding=1表示Windows Unicode）
如何安全提取字体名称（name表）并转UTF-8
TrueType的name表里存着多个语言/平台的字体名，比如英文名、中文名、PostScript名，但它们以原始字节存储，没有统一编码标识。FreeType不自动做字符集转换，必须自己根据name->platform_id和name->encoding_id判断编码，再用对应逻辑转成UTF-8字符串。
最容易踩的坑是直接把name->string当C字符串打印——它可能含null字节，且可能是Big Endian UTF-16（platform=3, encoding=1时）。Windows平台下常见错误是忽略字节序，导致中文显示为乱码或空字符串。
- platform=0（Unicode）：encoding=0/1/2/3对应不同Unicode变体，string是UTF-16BE，需逐字节交换后转UTF-8
- platform=3（Windows）：encoding=1表示UTF-16LE，直接按小端解析；encoding=0表示Symbol，通常不用
- platform=1（Macintosh）：encoding=0表示Mac Roman，需查表映射（可用
iconv或轻量级映射表） - 务必检查
name->string_len，它是字节数，不是字符数；UTF-16下长度要除以2才是码点数
如何读取TrueType的OpenType特性（如weight、width、style）
字体粗细（weight）、宽度（width）、斜体（italic）等信息不在name表里，而是藏在OS/2表的usWeightClass、usWidthClass字段，以及post表的italicAngle。这些值是数值型，需要查规范映射为人话——比如usWeightClass=400对应Normal，=700对应Bold。
很多工具直接显示“Bold”却没说明来源，导致用户误以为是name表里的字符串。实际上，name表里的“Bold”只是显示用标签，而OS/2表的usWeightClass才是CSS font-weight的依据。漏读OS/2表会导致无法正确分类字体。
- 用
FT_Load_Sfnt_Table(face, FT_SFNT_OS2, 0, nullptr, &len)先查OS/2表是否存在（len > 0） - 分配缓冲区，再次调用
FT_Load_Sfnt_Table读取完整OS/2表二进制，解析前8字节得到usWeightClass（offset 0x4）和usWidthClass（offset 0x10） - post表中的
italicAngle在偏移0x12（16位有符号整数，单位是度×65536，需除以65536.0） - 注意：某些免费字体OS/2表缺失或字段为0，此时应回退到name表中“Style”字符串的启发式匹配（如含“Bold”、“Italic”字样）
为什么直接读.ttf文件头不可靠
有人试图跳过FreeType，直接用fread读.ttf文件前几个字节解析head表或name表——这几乎必然失败。TrueType是复杂二进制格式：表偏移由table directory动态定位，name表内容被压缩（name记录指向字符串存储区，该区可能在任意位置），且存在校验和、字节序、版本兼容性等隐式约束。
典型错误包括：硬编码name表起始偏移（实际由offset table决定）、忽略checksum验证导致读到损坏数据、把Big Endian字段当Little Endian解析。FreeType内部已处理所有这些细节，自行解析等于重写一个不稳定子集。
- FreeType的
FT_Open_Face支持内存buffer加载，无需文件IO，适合嵌入式或资源受限场景 - 若必须最小化依赖，可考虑
hb_font_get_glyph_name（HarfBuzz）作为备选，但它不提供OS/2表访问，元数据能力弱于FreeType - 调试时用
ftdump -a font.ttf命令行工具验证解析结果，比手写解析器快得多
真正麻烦的不是读取，而是处理各种字体厂商的实现差异：有些把中文名塞进platform=3 encoding=1，有些塞进platform=1；有些OS/2表故意填0，有些name表缺“Preferred Family”字段。FreeType给你原始砖块，怎么砌墙得自己定规则。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
