图元输入设计

状态:核心与 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、颜色不变
填充、渐变、图片扩展及九宫格 保持调用落点和原有分配上限

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