渲染接口边界
本页记录删除 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 驱动与其它浏览器验收,则用于确认已有契约的实现范围,不应记成接口尚未定义。