输出坐标与尺度
输出坐标
root 的 rect、根级鼠标位置和未经过额外几何变换的绘制坐标统一采用输出目标的像素,原点左上,Y 向下。输出目标可以是 framebuffer、canvas backing 或窗口绘图目标;其像素不必与显示器的物理像素一一对应。
Measure、Position、Rect 和图元签名不变。.px 表示当前局部坐标中的长度,以输出像素为基准;withTransform 继续负责几何映射及命中测试的逆变换。核心不乘设备像素比,也不向各个绘制调用传递 DPI。
后端负责窗口、CSS 和系统坐标到输出坐标的边界换算。输入按实际的目标与显示范围分别计算 X、Y 比例,保留可用的小数精度;不能用名义 DPR 代替实际比例。比如 canvas backing 尺寸因最小值或取整而变化后,应使用 backing 与显示范围的实际比值。
换算必须与实际绘制映射一致。窗口绘图若按真实的 Graphics2D 倍率绘制,位图边界向上取整不能改变输入倍率。例如逻辑宽 101、倍率 1.25 时,目标边界可为 127 像素,但逻辑位置 80 仍对应输出位置 100,不能按 127 / 101 换算。
裁剪使用绘制的同一套坐标映射,截图对应实际输出目标的像素尺寸。图像名义尺寸和 UV 仍处于图像自身的像素空间,规则见图元输入设计。
root 的尺度
DslRootRenderer 不再提供 guiScale。默认 DSL 尺度由输出所属的 DslRoot.scale 提供,与 root 的绘制实现分开。各平台可以保留自己的默认尺度策略。
root.scale 没有隐式的 1.0。后端在首次构建或渲染前,必须在 root 所属线程上显式设置有限且大于零的值;未初始化就读取会抛出 IllegalStateException,无效赋值抛出 IllegalArgumentException。无 renderer 的 root 也遵守此规则,需要单位尺度时应显式赋值 1.0。
屏幕可以在输出准备完成前创建和挂载,但此时不能开始构建。每帧,后端先更新 root.rect 和 root.scale,再驱动 root.component.render()。渲染帧内改写 root.scale 会抛出 IllegalStateException;正常或异常退出后,下一帧仍可更新尺度。不新增公共帧提交接口。
尺寸为零或输出最小化时,后端按空输出处理,不能把 scale = 0 当作暂停绘制的信号。
局部尺度
DslScaleContext.scale 表示一个 DSL 基准长度对应多少当前坐标单位。.scaled 将数值乘上当前尺度,.unscaled 做相反换算;已计算出的坐标不会随着尺度更新而变化。
withScale(s) 替换当前 DSL 尺度,不与父尺度自动相乘;退出或抛出异常时恢复原值。组件及延迟执行的子作用域保留声明时的局部尺度,新一帧重新构建的组件读取新一帧的 root 尺度。DslScaleContext(s) 与 withScale(s) 同样拒绝零、负数、NaN 和无穷大。
例如,无额外几何变换且 root 尺度为 2.0 时,10.px 为 10 个输出像素,10.scaled 为 20 个;withScale(3.0) 内的 10.scaled 为 30 个,退出后恢复为 20 个。整棵子树的旋转、翻转或几何缩放由 withTransform 表达。
验收
核心测试覆盖未初始化与无效尺度、无 renderer 的 root、不同 root 的独立尺度、逐帧尺度变化、延迟局部作用域的快照,以及正常与异常恢复。后端适配须验证不同设备倍率、分数与非等比输入映射、尺寸变化、绘制与裁剪对齐,以及截图尺寸;具体平台范围由各后端如实记录。