图元输入设计
状态:核心与 Minecraft、窗口、Web 三个后端均已实现本项契约。核心覆盖类型化数组、调用点与分配约束;MC 覆盖实际校验和顶点写入循环,窗口覆盖 Java2D 像素,Web 覆盖线协议与生产客户端函数。MC 游戏内像素和真实浏览器的完整画面仍需单独验收。
本页是当前契约。它规定四边形与三角形列表的输入、校验顺序、资源不可用时的行为,以及参数的借用期限;插值、染色、合成、透视与采样语义由渐变与合成定义,本页不重复。
接口形状
每个图元有两个重载,格式由重载固定:
context(renderParam: RP)
fun renderQuad(rect: Rect, lt: Color, rt: Color, lb: Color, rb: Color)
context(renderParam: RP)
fun renderQuad(
rect: Rect, lt: Color, rt: Color, lb: Color, rb: Color,
image: ImageHolder, uv: Rect,
)
context(renderParam: RP)
fun renderTriangles(vertices: MeasureArray, colors: ColorArray)
context(renderParam: RP)
fun renderTriangles(vertices: MeasureArray, colors: ColorArray, image: ImageHolder)
带纹理重载必须同时给出非空图片引用与 UV。ImageHolder.empty 仍是合法参数,表示没有图像可画,不表示无纹理。三角形步长由重载固定,与资源加载结果无关;不存在可空格式参数、可变 stride、offset/count、兼容旧签名、flush() 或通用渲染描述对象。fillRect、fillRectGradient、renderImage、fillPolygon 继续是核心扩展函数,落到上述四个入口。
类型化数组
公共接口使用框架类型,底层保持连续数值存储:
| 类型 | 底层存储 | 读写元素 |
|---|---|---|
MeasureArray | DoubleArray | Measure |
ColorArray | IntArray | Color |
例如调用方可以写 vertices[0] = 10.px、colors[0] = Color.RED,不必手动转 Float 或取 rgbaInt。x/y/u/v 都是 Measure;UV 仍是图像名义像素,数组封装不改变坐标空间。
公共面只有长度构造、初始化构造、size 和下标读写;底层数组不是公共 API。MeasureArray 原有的布局与集合工具保持 internal,ColorArray 不复制整套集合工具。数组构造会分配底层存储,调用方应复用;图元入口不复制、不重新包装,后端不得仅为适配新签名而复制整份临时 FloatArray 或创建逐顶点对象。热路径只用下标访问,不经过泛型集合、迭代器或可空包装。
MeasureArray 每元素从原先 Float 的 4 字节增加为 Double 的 8 字节,这是保留 Double 精度与未测量值语义的实际代价。后端消费时直接转换到自己的 Float 顶点缓冲或传输数据,不要求 GPU 或线协议使用 Double;CPU 成本需按后端实测,不承诺类型化后更快。
三角形布局
设 N = colors.size:
| 重载 | 每顶点格式 | 长度要求 |
|---|---|---|
| 无纹理 | 两个 Measure:x, y | vertices.size = 2N |
| 带纹理 | 四个 Measure:x, y, u, v | vertices.size = 4N |
两种格式都要求 N % 3 == 0。每三个顶点组成一个三角形,每顶点一个 Color,底层为 RGBA。两数组都为空是合法空绘制;不接受多余尾部、缺失颜色或不完整三角形。
结构不匹配抛 IllegalArgumentException,并且必须在查询资源或写入绘制命令之前完成检查——即使图片为空,结构错误仍须报告。长度检查使用余数与除法比较,不用 N * stride,避免整数溢出。结构检查为 O(1),由各后端入口落实,不增加公共基类。
数值有效性
结构错误与运行时不可绘制的数据分开处理:
- 位置或 UV 必须是有限数值;以 Float 消费的后端还要求转换后仍有限,双精度下有限但超出 Float 范围的值同样无效。
- 未测量值、NaN 与无穷都按无效处理,不替换为零。
- 目标矩形宽或高必须有限且为正;带纹理图片的名义宽高必须有限且为正。
- 任一必需数值无效时跳过整笔调用:不写命令,不产生可见的半笔图元;三角形列表不因单个顶点坏掉而只跳过一个三角形。
- UV 负坐标与越界本身合法,后端不得钳制。反向、退化 UV 的采样不属于输入校验,输入层既不拒绝也不改写,直接交给纹理采样。
三角形数值检查为 O(N)。即时后端必须先检查再画;录制后端可与暂存写入合并,在确认有效后再纳入可重放命令。该遍历有 CPU 成本,不能承诺检查后耗时不变。
资源不可用
带纹理重载的资源分支:
| 情况 | 行为 |
|---|---|
image.source == null,或像素尚未就绪 | 本次不画 |
| 名义尺寸非有限或不大于零 | 本次不画 |
| 标识无效、资源缺失、来源不支持、加载确认失败 | 不抛出调用方参数异常;使用后端缺图纹理,保持本次几何、UV 与顶点颜色 |
| 资源可用 | 使用图片绘制 |
缺图占位仍是纹理,不能变成纯色填充、无纹理绘制或改变顶点步长。空引用与尚未就绪不画;确认失败才显示缺图纹理,从而保留“没有图像”和“已知资源坏了”的区别。资源提供层若已经返回 ImageHolder.empty,绘制层遵循“不画”,不猜测原因;也可以显式返回替代图片。
加载、解码、上传、失败记忆和缓存淘汰都在各后端内部,不增加公共加载状态、绘制返回值或失败回调。Web 记录器保留带纹理命令与资源标识,在实际消费命令的一侧判定可用性,不能因服务器没有本地像素就编码成无纹理绘制。图元不负责同步下载或解码。
参数借用与延迟消费
rect、uv、vertices、colors 只在调用期间有效。Rect 可能是反复改写的 MutRect,后端不能假定它不可变。
后端必须在返回前消费坐标、UV 和颜色,或保存独立数据;返回后调用方可以立即复用输入。冻结的是绘制参数,不要求等待异步图片完成或复制纹理像素。延迟后端录制三角形时须拷贝所需值;renderQuad 的顶点数固定,可以存进字段。已经录制的裁剪与变换继续遵循既有作用域契约。
实现状态与验收
核心已完成:
- 公共最小
MeasureArray、ColorArray,带类型化读写、长度/初始化构造与size;原始存储和既有集合工具保持非公共。 - 四个抽象图元重载替换旧的可空签名;核心扩展、颜色控件、测试替身和调用点已迁移。
- 每个根持有自己的可复用三角形暂存数组;三角取色板直接写
Measure/Color,不生成临时 Float 或打包 Int 数组。 fillPolygon拒绝结构错误,整笔跳过非有限或 Float 转换溢出的坐标,并展开成类型化三角扇。- 接口 KDoc 固化了结构校验、数值有效性、资源分支和借用期限。
三个后端已迁移四个重载,结构校验先于资源查询,纹理格式不随资源状态改变。MC 在调用内写入池化顶点;窗口当场绘制;Web 在返回前冻结坐标、颜色、UV 和每笔名义尺寸,记录器、传输与消费者使用同一格式。
窗口与浏览器的确认失败分支使用缓存棋盘纹理,并按每笔名义尺寸映射 UV;负值和越界 UV 重复采样。窗口在颜色场采样时组合 tint 与纹理,浏览器在复用的离屏画布上生成源色,最后合成到已有 UI,避免透明 texel 修改背景。逐顶点插值、纹理染色、合成与透视的完整语义见渐变与合成;该契约已实现,并通过目标像素验收。
验收用例及边界:
| 用例 | 预期 |
|---|---|
| 无纹理、带纹理各一个三角形 | 按固定步长读取所有顶点和颜色 |
| 类型化数组构造、读写及复用 | Measure 数值/未测量位模式、Color RGBA 位模式保留;重用底层存储 |
| 两空数组 | 无绘制、无异常 |
| 多余尾部、数据不足、颜色数不匹配、非三倍顶点数 | 调用异常,未写入该笔命令 |
| 结构错误且图片为空 | 同样报告结构错误 |
| 空图片、尚未就绪 | 不新增可见像素,不出现颜色矩形或误读 UV |
| 确认失败、来源不支持、标识无效 | 不因资源错误抛出调用异常;缺图纹理按原参数绘制 |
| 带纹理数组经历未就绪、可用、失败 | 始终按四个 Measure 解释,无几何跳变 |
| NaN、无穷、Float 转换溢出、无效名义尺寸 | 跳过整笔,无部分命令或除零 |
| 合法越界 UV | 不被输入校验拒绝;按纹理环绕语义采样,不影响渐变域 |
调用返回后修改数组及 MutRect,再重放 | 已录制的几何、UV、颜色不变 |
| 填充、渐变、图片扩展及九宫格 | 保持调用落点和原有分配上限 |