图像

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是整体占据的矩形。


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