图像
图像子系统只做两件事:引用一张图,以及决定这张图怎么铺到目标矩形里。真正把像素画到屏幕上仍然是后端的事。
图像引用
ImageHolder 只有三个字段:资源标识、宽度、高度。
宽高用于计算比例和定义 UV 的名义范围,不决定显示尺寸。原因是资源包可能提供任意分辨率:同样是泥土贴图,原版是 16×16,高清包可能是 64×64。若把像素尺寸当成显示尺寸,同一份 UI 在不同资源包下就会大小不一。因此约定是”按资源的名义尺寸填写,让框架按比例缩放”,与 Minecraft 对物品/方块贴图的做法一致。
目标尺寸完全由 Modifier 决定,所以图像组件没有固有尺寸——调用方必须显式给出尺寸,否则会得到零尺寸。
empty 表示”没有图像”(例如本地图片尚未加载完成时)。当前引用形式为 ImageHolder(source, width, height),其中 source 区分资源、本地文件与远程 URL;source == null 即 isEmpty,不依赖实例身份。带纹理图元对空引用与尚未就绪都不画;确认缺失、来源不支持或加载失败时使用后端的缺图纹理,并保持原几何、UV 与顶点颜色,不能退化成无纹理填充。完整契约见图元输入设计。
绘制策略
ImageStrategy 的最小契约是”把 image 按 color 画进 rect“。
绝大多数策略只关心一件事——用图像的哪一块 UV,因为目标矩形由布局决定、图像本身按比例缩放。因此有一个 UVStrategy 子接口:只需给出”目标矩形对应的 UV 矩形”,渲染调用由框架统一完成。
内建策略
| 策略 | 行为 | | — | — | | stretch | 拉满整个矩形,不保持比例 | | clip | 保持比例铺满矩形,超出部分裁掉(默认策略) | | repeat(align, scale) | 按缩放铺满,选取的 UV 由对齐方式决定 | | repeatUV(uv, scale) | 把给定 UV 平铺满矩形,最后一块按需截断 | | nineSlice(uvOuter, uvInner, scale) | 九宫格 | | stretchUV(uv) | 直接使用给定 UV | | fitIn(alignment, fillColor) | 保持比例完整放入,空余处填充底色 |
保持比例的两种做法
clip 与 fitIn 是一对:前者裁剪、后者留白。
clip 比较目标矩形与图像的比例:比例相同就直接拉伸;目标更宽时按目标比例算出一个中部横向裁切的 UV 高度;目标更高时按目标比例算出一个中部纵向裁切的 UV 宽度。裁切总是居中。
fitIn 反过来:先填一层底色,再算出保持比例后的目标子矩形,并按给定对齐方式在矩形内摆放,UV 用整张图。
两者的比例计算都带有限值检查——比例不是有限值(例如尺寸为 AUTO 导致 NaN)时直接跳过,避免产生 NaN 几何。
平铺
repeat 取的是”一块”的 UV:UV 的尺寸等于目标矩形尺寸除以缩放,起点按对齐方式偏移(LOW 从头开始、HIGH 从负的一整块开始、MID 居中)。真正的平铺由后端的纹理环绕模式完成,所以后端不得钳制越界 UV。
repeatUV 是需要在框架侧平铺的场景(九宫格边缘):它按 uv.width * scale 与 uv.height * scale 为步长遍历目标矩形,逐块绘制,并在最后一块按剩余空间等比截断 UV。因此边缘不会出现半块被压缩的失真。
repeatUV 的步长必须为正,且两端必须是数值,否则直接跳过。
九宫格
nineSlice(uvOuter, uvInner, scale) 里两个矩形的含义不同:uvOuter 是整张图的脚印(完整 UV 范围),uvInner 是中心的九宫格内区。
算法分三步:
- 求实际缩放:取”请求的缩放”与”两个方向各自能容纳的缩放”中的最小值,保证四角不会被压扁;
- 算出四角在目标矩形中的尺寸:角宽高由
uvInner与uvOuter的差乘以实际缩放得到,据此推出中心区矩形; - 遍历九宫格:对每个对齐组合,从
uvInner/uvOuter取对应的 UV 切片、从中心区 / 目标矩形取对应的目标切片,用与repeatUV相同的平铺逻辑绘制——于是中心区与四条边会自然平铺,四角只画一次。
这条路径不按贴片分配对象:贴片矩形与源矩形写进策略自己的暂存视图,renderQuad 当场把它们消费掉。一次九宫格(9 个贴片)实测约 96 B,改动前是 1224 B;剩下的那几十字节来自”通过 Rect 接口读取 Measure“的装箱,属于矩形 API 的性质而不是策略的问题。
目标矩形为空或小于千分之一像素时直接返回(后者的阈值是为了避免除零)。
组件
Image
签名接受 modifier、图像引用、策略(默认 clip)、以及必填的 id。
外观颜色在构造期按主题色求解(Color.WHITE.mixed),因此受 withColor 作用域影响。渲染时先按策略画图,如果组件处于高亮状态再叠一层半透明白(用于焦点/悬停反馈)。
Item
物品图标不由框架绘制,而是整块委托给后端的物品渲染(图标、数量、耐久条、附魔光效)。框架只负责给出矩形。
BackgroundImage
BackgroundImage 是”重复铺一张底图”的组合:把主题色压到四分之一亮,再用 repeat(缩放取当前 GUI 缩放)铺满。压暗是为了让它读起来像背景而不是前景内容。
后端契约
- UV 处于图像像素空间,允许越界;平铺依赖纹理环绕模式,后端不得钳制;
- 带纹理图元要求非空图像引用与 UV;空引用或待就绪不画,确认失败使用缺图纹理且保持原步长、UV 与顶点颜色;
- 目标矩形宽高、图片名义宽高以及坐标/UV 必须有限;图片名义尺寸不大于零或坐标经 Float 转换后溢出时跳过整笔调用;
Rect、uv、顶点数组只保证调用期间有效,延迟后端必须当场读取或复制;- 公共接口没有
flush();后端维护调用顺序和绘制时的裁剪、变换语义,自行处理提交边界; - 图像的缓存与上传完全由后端决定,框架不参与(框架每帧都会重新提交绘制请求);加载状态、失败记忆和缺图资源都由后端内部处理,不新增公共回调。
测试现状
图像策略的几何已有测试:ImageStrategyTest 用一个记录型后端逐块断言矩形与 UV,包括平铺的截断块和九宫格的四角。真实纹理内容仍然无法验证——测试用的假后端把渲染实现为空操作;资源失败分支与缺图纹理由三个后端在各自仓库验收。