font 模块性能与渲染修复

[Gu-ZT]

1. 字形布局缓存（P0）

【ac15602】 每帧对相同文本重复计算码点→字形查询、UV计算、按页面分桶及新建对象。改为 (atlasKey, text, scale) 缓存 SdfTextLayout 结果，消除重复
CPU 开销。配额满时驱逐半数条目。

---

2. 异步字形创建 + 虚拟线程（P0）

【ac15602, 2f61da7, 5079f4b】 原来渲染线程同步调用 createGlyph()，CJK 文本可能阻塞多帧。改为：

• 未就绪字形返回 null，异步入队后台创建
• pendingGlyphs 集合防止重复创建请求
• 字形创建用 synchronized 图集级互斥，纹理上传用 synchronized 页面级互斥
• → 虚拟线程执行器 (Executors.newThreadPerTaskExecutor(Thread.ofVirtual()...)) 替代单线程平台线程池
• 失败 Future 自动重试，防止瞬态错误永久禁用图集
• Mod 初始化时预构建基础字体 + BOLD/ITALIC/BOLD|ITALIC 样式变体图集，避免首帧阻塞

---

3. 纹理上传顺序修复（关键 Bug）

【b5457d6, c6fe2cb】 SdfTextRenderer.flushFormattedSegment() 和 drawStringWithAtlas() 中 SdfTextLayout.fromAtlas() 在
SdfAtlasTexture.ensureUploaded() 之前调用，导致 PageQuads 捕获 null 的 atlasTexture，布局被缓存后文字永久不可见。改为先上传再计算布局。

---

4. 纹理上传竞态条件修复（关键 Bug）

【7ec5af5】 版本号替代哈希后引入的竞态：uploadPage 在 synchronized (page) 块外读版本号，在后面清除 dirty
。若后台线程在中间创建了新字形（version++、dirty=true），dirty 被错误覆盖为 false，下一帧跳过上传。修复：

• 版本号读取、图片快照、dirty 清除三者移入 synchronized (page) 块内原子执行
• ensureUploaded 增加版本号比对兜底 (entry.version != page.version.get())，即使 dirty 竞态被覆盖也能检测到变更

---

5. 版本号替代图像哈希（P1）

【718ebf3】 SdfGlyphPage 用 AtomicInteger version 替代 int hash。updateHash() 从遍历 1,048,576 像素的 hashImage() 改为
version.incrementAndGet()。SdfAtlasTexture.uploadPage() 和 PageEntry 全部改用版本号比较。已删除 hashImage() 方法。

---

6. Y 轴基线位置修正

【8b4aedf】 旧代码把渲染 API 的 y 当作 baseline 处理 (quadY = y - ascent*scale)，但 Minecraft vanilla 约定 y = 文字顶部。去掉 ascent
减法 → quadY = y，使 SDF 文字与同屏 vanilla 文字在垂直方向对齐。

---

7. API 状态注解

【82e470d】 为所有类添加适当的 API 可见性标记：

注解	类
@Beta	SdfTextRenderer, GuiGraphicsExtractorExtension, ALFont, FontManager
@ApiStatus.Internal	ALFPipelines, SdfGlyphAtlas, SdfGlyphPage, SdfAtlasTexture, SdfTextLayout, SdfTextRenderState, GuiGraphicsExtractorMixin, FontConfigScreen, FontTestScreen, Dropdown, AnvilLibFontData, AnvilLibFontConfigManager

---

8. 日志优化

【c6fe2cb】 SdfGlyphAtlas 用 @Slf4j 替换手动 LoggerFactory.getLogger()，将 "Starting SDF atlas build" 降为 debug
级别，删除每帧打印的 "SDF atlas build done" 冗余日志。

---

9. 下拉菜单修复

【2b11adb】 Dropdown.calcMaxHeight() 末尾加 (maxHeight / getHeight()) * getHeight() 向下取整到行高倍数，消除列表底部空白区域。

[github-actions]

🌿 Roseau API Breaking Change Report

Module	Status	Breaking Changes
codec	✅ Compatible	0
collision	✅ Compatible	0
config	✅ Compatible	0
font	🔴 BC detected	1
integration	✅ Compatible	0
moveable-entity-block	✅ Compatible	0
multiblock	✅ Compatible	0
network	✅ Compatible	0
recipe	✅ Compatible	0
registrum	✅ Compatible	0
rendering	✅ Compatible	0
space-select	✅ Compatible	0
sync	✅ Compatible	0
util	✅ Compatible	0
wheel	✅ Compatible	0
main	✅ Compatible	0

🔴 font — 1 breaking change(s)

dev/anvilcraft/lib/v2/font/sdf/SdfAtlasTexture.java:104

dev.anvilcraft.lib.v2.font.sdf.SdfAtlasTexture
dev.anvilcraft.lib.v2.font.sdf.SdfAtlasTexture.hashImage(java.awt.image.BufferedImage)
EXECUTABLE_REMOVED
✗ binary-breaking
✗ source-breaking

Full CSVs: see the Artifacts section of this workflow run.