渲染接口边界

本页记录删除 flush() 后的实际接口形状,以及后续收敛清单。图元输入、图元像素语义与状态作用域已由核心和三个后端实现,并通过对应自动测试与目标像素验收。清单中的其余候选方案尚未成为契约。绘制顺序、坐标、颜色语义见渲染,裁剪与变换作用域的完整契约见裁剪与变换作用域。

主接口:DslRootRenderer<RP>

当前为 0 个属性、13 个方法。RP 是所属输出的绘制参数,通过 context 参数传递;核心不依赖 Minecraft、Java2D 或浏览器类型。输出范围由 root.rect 提供,默认 DSL 尺度由后端显式设置 root.scale,两者不属于 renderer 的实现面。

职责 成员 约定
四边形(无纹理) renderQuad(rect, lt, rt, lb, rb) 四角定义一个双线性场;纯色或渐变填充
四边形(带纹理) renderQuad(rect, lt, rt, lb, rb, image, uv) 双线性 tint;非空图像引用与图像像素空间 UV
三角形列表(无纹理) renderTriangles(vertices, colors) 每三顶点一个三角形;每顶点 x, y 与一个 RGBA 颜色,按重心权重插值
三角形列表(带纹理) renderTriangles(vertices, colors, image) 每顶点 x, y, u, v;非空图像引用,染色规则与四边形相同
裁剪作用域 withScissor(rect, block) 局部坐标进入时快照,精确投影求交,空裁剪失败关闭,退出或异常均恢复
变换作用域 withTransform(transform, block) 嵌套复合,退出或异常均恢复
字体入口 getFont(name?) 默认字体用 null;度量可在布局阶段查询,不需要 RP
按钮外观 renderButton(rect, highlighted, active, color) 背景,不负责按钮文字、布局或事件
槽位外观 renderSlot(rect) 物品槽背景
容器外观 renderContainer(rect) 容器背景,不负责槽位与物品布局
提示外观 renderTooltip(rect) 提示框背景;内容与定位由核心完成
屏幕外观 renderDefaultBackground(rect) 平台默认屏幕背景
物品图标 renderItem(rect, item, count, damage?, enchanted) 物品 ID、数量、耐久与附魔效果

除 getFont 外的方法都接收 RP;六个外观/物品方法还接收当前 DslScaleContext。这个尺度继承 root 并可被 withScale 局部替换,不能一律当作输出的 root.scale。

文字接口链

文字绘制没有名为 renderText 的 renderer 方法,而是:

DslRootRenderer.getFont(name)
  └─ DslFont<RP>
       ├─ lineHeight
       ├─ glyph(code): DslGlyph
       └─ renderChar(char, x, y, effectLeft, effectRight)

DslFont 要求后端提供一项属性和两个方法。renderChar 接收 RP;排版位置、字号、颜色与样式由核心给出,后端负责字形与装饰的绘制。effectLeft/effectRight 提供下划线等效果的左右边界。

charAdvance(char)、charHeight(char) 是默认实现,后端不必再提供新的入口。DslGlyph 提供 normalAdvance、boldOffset、shadowOffset 三项度量,advance(style) 为默认实现。换行、对齐、选区和编辑逻辑仍在核心,记录型后端也记录核心排好的位置。

不属于后端实现面的方法

  • fillRect、fillRectGradient、renderImage 是核心扩展函数,落到 renderQuad。
  • fillPolygon 是核心扩展函数,展开凸多边形后调用 renderTriangles。
  • ImageStrategy 的裁剪、平铺、拉伸、九宫格等策略最终使用上述图元,不是额外的 renderer 接口。
  • imageResource 只构造图像描述;本地/远程图片加载与刷新在 DslPlatformUtils,不是绘制调用。
  • 截图在 DslRootUtils.capture,输入在 DslRootInput,也不算 renderer 的绘制成员。

提交与状态的责任

核心按调用顺序表达覆盖关系,后端须产生相同的逐像素结果。三角形数组只保证在调用期间有效;延迟后端必须在返回前读取或拷贝需要的数据。状态作用域退出后,已录制绘制仍须保留当时的裁剪与变换。

公共接口没有 flush、commit、beginFrame 或 endFrame。MC 的提交边界、窗口后端的即时绘制、Web 记录器自己的帧末 Op.FLUSH 都属于后端实现。它们不能反过来成为核心控件决定批次的依据。

收敛清单

目标是支持 MC、窗口与 Web 输出,也允许无头 MC 提供内容。保留四边形与三角形列表两个基础图元(各有无纹理、带纹理两个重载)、作用域式状态和调用顺序契约;公共接口不恢复 flush()。后端排序与重放的性能优化暂缓。

按下表顺序逐项推进。每项先确定行为与职责,再作必要的接口和后端修改,更新文档、编译测试后独立提交。尚未决策的内容不能作为后端已支持的能力。

顺序 项目 状态 完成标准
1 图元参数与资源失败 已实现并通过自动测试 明确图片/UV 组合、数组格式和无效输入;资源加载结果不改变输入格式;三个后端有对应测试
2 图元像素语义 已实现并通过目标像素验收 插值、染色、透明合成与正 w 透视符合渐变与合成;完整游戏与其它浏览器集成仍需单独验收
3 状态作用域 已实现并通过目标验收 嵌套、正常与异常退出均正确恢复;延迟绘制保留调用时状态;空裁剪失败关闭、旋转/透视按精确投影求交;三个后端通过生产路径验收
4 输出尺度与坐标 已实现并通过自动测试 默认尺度归 root,显式初始化且帧内稳定;输出像素坐标、输入和裁剪使用一致换算;后端验证不同设备倍率与尺寸变化
5 外观与游戏内容归属 待设计 明确平台外观与 MC 内容的来源、支持范围和失败回退,再决定最小接口归属
6 字体度量与绘制 待设计、对齐 定义字体标识与回退、样式度量及版本更新;度量与绘制按输出配对,验证换行、选区、粗体和装饰边界

1. 图元参数与资源失败

核心已实现:renderQuad 的两个可空参数由“无纹理”和“带纹理(必填图像与 UV)”两个重载取代;三角形列表按无纹理 x, y 与带纹理 x, y, u, v 分成两个重载,使用 MeasureArray 与 ColorArray。格式由签名固定,与资源加载结果无关。

完整的结构校验、数值有效性、空/待就绪/确认失败分支、缺图纹理和借用期限见图元输入设计。核心已迁移扩展、控件、测试替身与根级暂存数组;Minecraft、窗口、Web 三个后端已实现四个重载并通过对应自动测试。图元像素与状态的生产路径验收范围见下两项;完整游戏与其它浏览器集成仍需单独验证。保留连续数组存储与四边形调用的分配约束,不引入逐顶点对象。

2. 图元像素语义

契约已批准,完整公式与验收用例见渐变与合成:四边形四角在未变换矩形上定义一个编码 sRGB、预乘浮点的双线性场,三角形按重心权重插值;纹理采样乘到预乘渐变上;最终对已有目标做一次 source-over。核心与各后端已按该契约实现,不把插值、染色或透视留给后端自由决定。

跨平台验收不预设字体抗锯齿逐像素相同;内部采样与外侧抗锯齿覆盖率分开验收。Java2D、真实 Chrome 与 MC 生产管线离屏 GPU 的共同参考用例均已通过;验收范围及限制见渐变与合成。

3. 状态作用域

共享契约已批准:withScissor 的矩形按当前局部坐标解释,进入时快照四边与完整局部到输出变换,映射四角后与已有输出裁剪求精确交集;包围盒不能替代最终覆盖。空/无效矩形、非有限或奇异变换、w <= 0 均为空裁剪并失败关闭,block 仍执行一次;两个作用域都在 finally 中恢复并原样传播异常,录制型后端保持配对 push/pop 与绘制时状态。完整规则与验收要求见裁剪与变换作用域。

核心 KDoc 与三个后端已同步,窗口生产渲染器、真实 Chrome 客户端和 MC 生产裁剪管线的离屏 GPU 对照均已通过。MC 另验证了原生着色器式绘制、目标复用、颜色与深度保留、GL 状态和重放诊断。完整游戏客户端与其它浏览器仍需单独验证;具体范围见裁剪与变换作用域。

4. 输出尺度与坐标

契约已批准,完整规则见输出坐标与尺度。renderer 的 guiScale 已删除;后端在首次构建前显式设置 root.scale,它没有隐式的 1.0。尺度必须有限且大于零;未初始化的读取失败,渲染帧内不能改写,后端可在下一帧前更新。withScale 替换当前 DSL 尺度,普通 .px 与已经计算的坐标不随之变化,几何变换仍由 withTransform 表达。

无额外几何变换时,root 范围、绘制与根级鼠标统一采用输出目标像素,原点左上、Y 向下。窗口、CSS 与设备倍率换算由后端处理,使用实际目标与显示范围的 X、Y 比例,不新增公共 DPR 或帧提交接口。图像名义尺寸与 UV 继续采用独立的图像像素空间。

核心已覆盖未初始化与无效尺度、不同 root、局部覆盖、延迟作用域、逐帧变化及异常恢复。三个后端已完成适配并通过对应自动测试,覆盖实际倍率、尺寸变化、绘制与输入及裁剪对齐、截图尺寸;窗口另验证小数与非等比倍率下的实际绘制,Web 验证画布失效后的按钮释放,MC 验证静止指针的重新映射。完整游戏客户端及其它驱动、浏览器仍需单独验收,具体范围由各后端开发文档记录。

5. 外观与游戏内容归属

已确认:同一 renderer 同时要求通用绘制、五种外观和 MC 物品图标。MC 的按钮与默认背景使用游戏纹理;窗口绘制自己的控件外观,物品可使用读到的图标或占位,附魔效果采用替代外观;Web 记录外观和物品操作供客户端绘制。接口尚未明确这些输出应复现 MC 内容还是采用平台外观,当前方法上的 MC 风格说明也不足以定义一致的验收标准。

待定:

  • 外观由平台、主题还是游戏内容提供;控件状态、边框和装饰尺寸如何服从局部 DSL 尺度。
  • 无头 MC、窗口和 Web 如何获得物品图标及资源包/模组内容;现有物品 ID、数量、耐久和附魔参数承诺表达哪些效果。
  • 未知物品、未就绪内容、确认失败,以及数量和耐久的无效值各采用什么行为;替代外观是否属于允许的正常输出。

先确定这些行为与来源,再决定是否拆分绘制、外观、游戏内容接口。单纯搬移方法不会减少后端必须实现的能力;也不预设每笔绘制增加能力查询或跨后端分支。验收需覆盖同一控件在各输出上的约定外观、内容不可用时的回退,以及局部尺度下的装饰布局。

6. 字体度量与绘制

已确认:MC 与 Web 忽略字体名,窗口将其解释为字体家族。DslFont<RP> 同时提供度量和绘制,DslGlyph 以普通 advance 加粗体偏移描述字宽。窗口绘制使用 AWT 粗体和取整后的字号,度量仍按普通字宽加固定偏移及线性字号换算;文字装饰也需要核对 effectLeft/effectRight 的使用。Web 度量可从估算值切换到客户端报告值,目前字体度量表和版本是后端共享对象,未按输出和字体区分。

待定:

  • 字体标识的含义、默认字体与缺字回退,以及字体不可用或尚未加载时采用什么度量和绘制。
  • 普通、粗体、斜体、字号和装饰的度量规则;确定哪些值进入布局,哪些只影响字形外观,保证绘制位置与换行、选区、光标一致。
  • 字体或度量版本变化后,哪些缓存与布局需要更新;浏览器客户端报告须与所属输出、字体及对应版本配对,不能让一个输出的度量替代另一输出。

若拆分度量与绘制,必须保持两者配对,避免无头布局与最终输出使用不同字体。验收需覆盖默认与指定字体、缺字回退、客户端度量到达后的重新布局,以及粗体、分数字号和装饰边界。完整文字塑形另行评估,不作为本轮完成条件。

实现优化与验收余项

第 4 项已完成核心与后端适配;第 5、6 项仍是接口设计工作。MC 已为像素覆盖等价的小数轴对齐裁剪实现 scissor 快速路径,精度不确定时保留精确路径。裁剪目标复制、排序与重放效率属于后端实现问题,不要求恢复公共 flush() 或新增帧提交接口;其中排序与重放优化继续暂缓。完整 Minecraft 的字体/物品集成、其它 GPU 驱动与其它浏览器验收,则用于确认已有契约的实现范围,不应记成接口尚未定义。


This site uses Just the Docs, a documentation theme for Jekyll.