图像
ImageHolder
用来在前端和后端之间传递一个图像的引用。
source:图像从哪来,见下节的四种来源;width、height:图像的宽高,以1.px为单位,渲染时用来计算纹理 uv。
三种来源,互不混淆
sealed interface ImageSource {
data class Resource(val location: String) // "minecraft:textures/block/dirt.png"
data class LocalFile(val file: File)
data class Remote(val url: String) // http:// 或 https://
}
它们是三种类型而不是三种字符串前缀,所以不可能互相冒充:一个资源定位不可能被当成本地文件。解析由后端做 when(source),不需要猜前缀。
“没有图像”不是来源的一种,而是 ImageHolder.empty(source == null)。本地/远程图片还没读完时也是 empty——空引用与尚未就绪都不画。带纹理绘制一旦拿到非空 holder,而后端确认标识无效、资源缺失、来源不支持或加载失败,不会抛出调用方参数异常,而是用后端的缺图纹理按原几何、UV 与顶点颜色绘制;也可以由资源层显式换成占位资源。它不会退化成无纹理填充。加载状态与失败记忆都在后端内部,公共接口没有加载回调。
Resource 的 namespace:path 与 Remote 的 http(s):// 不在构造时校验:这些字符串可能来自配置文件、输入框或服务器,写错不该抛异常。解析不出来的资源由后端显示它自己的占位——Minecraft 显示紫黑方块;读不到的本地文件/网络图片可以返回 ImageHolder.empty,什么都不画。
画不出来是降级,不是崩溃。
资源图像
imageResource("minecraft:textures/block/dirt.png", 16.px, 16.px)
即使使用了高清材质包、dirt.png 实际是 64×64,这里也应该写 16.px:宽高只是用来计算渲染 uv。
本地图像
val holder = localImage(file) // 页面体里可以调
这个函数应当立即返回:文件还没读完时返回 ImageHolder.empty,之后再次调用会给出真正的holder(带 ImageSource.LocalFile 和真实尺寸)。
不要缓存返回值——缓存会把”首帧还没读完”变成”永远为空”。
本地文件变了以后,在事件处理器里(例如clickable { })调用reloadLocalImage(file)刷新缓存。它没有返回值,也不能写在页面体里:它要求DslExecuteContext,而渲染上下文不提供,写在那儿编译不过。
网络图像
val holder = remoteImage("https://example.com/icon.png")
规则与本地图像相同:立即返回,empty 表示还没下载完,再调用即可。remoteImage 没有默认实现——每个后端自己决定:没有 http 能力时应当返回 empty(页面照常渲染,只是这张图不显示),而不是抛异常。
内容变了、或者上次下载失败想重试,就在事件处理器里调 reloadRemoteImage(url):同样没有返回值,同样不能写在页面体里。
渲染策略
ImageStrategy中有裁切、重复、拉伸等多种策略。使用时注意一些策略参数中的uv:Rect参数应当为相对于ImageHolder的矩形。例如如果我想渲染dirt的左上1/4,应该传入uv为Rect(0.px,0.px,8.px,8.px)。
nineSlice的uvInner是中心一块的矩形,uvOuter是整体占据的矩形。