Ebitengine Kage 着色器配方手册:坐标归一化、寻址模式与采样技巧实战

原创2026-10-01 14:30:591,748 阅读
文章标签:游戏开发图形学音频处理跨平台3D渲染

Ebitengine Kage 着色器配方手册:坐标归一化、寻址模式与采样技巧实战

导读

本文是 Ebitengine Kage 着色语言(//kage:unit pixels 像素单位 + atlas 相对坐标)的实战配方集,对应仓库 skills/writing-kage-shaders/reference/recipes.md,是 skills/writing-kage-shaders/SKILL.md 的配套代码库。文中每个代码片段都假设使用像素单位、面向 atlas 相对坐标编写,可直接复制到你的 .kage 文件(或带 //go:build ignore 的 .go 文件)中运行。读完本文,你将掌握:在 atlas 坐标系下正确归一化坐标、把效果锚定到"被绘制的区域"而非"整张目标图像"、跨多个源图像采样与拉伸、手工实现 clamp/repeat 寻址与双线性插值、像素化、可分离模糊、预乘 alpha 与无分支选择器,以及一套不依赖 GPU 的调试方法。

前置知识:像素单位与 atlas 相对坐标

所有配方都以两条约定为前提,缺一不可:

  1. 像素单位:文件顶部必须有独立的 //kage:unit pixels 指令(通常放在 package main 上方,一行恰好一次)。省略它将进入遗留的 texel 单位,此时 src0Pos 以及所有 origin/size 值都变成整张 atlas 纹理的 texel(0..1 跨越整张 atlas,而不是你的图像),且源图像尺寸不同时 DrawTrianglesShader/DrawRectShader 会 panic。
  2. atlas 相对坐标:Ebitengine 中每个 *ebiten.Image 都是更大内部纹理(atlas)上的一个子矩形。Kage 拿到手的 dstPos、src0Pos 是这张 atlas 上的绝对像素位置,既不是图像内相对坐标,也不是 0..1 UV。Ebitengine 提供三组内置函数描述这些区域(源码生成于 internal/graphics/shader.go):
区域 原点 尺寸 整张纹理尺寸
目标图像 imageDstOrigin() imageDstSize() imageDstTextureSize()
源图像 N(0..3) imageSrcNOrigin() imageSrcNSize() imageSrcNTextureSize()

注意这些区域描述的是整张图像,而不是某次绘制调用覆盖的范围(DrawRectShader 的矩形、三角形扇等只是它的子区域)。因此 dstPos.xy - imageDstOrigin() 是"图像局部"坐标,imageDstSize() 也不是绘制的范围。

归一化:把坐标映射到 0..1

把坐标转成 0..1 UV 的正确写法是"先减原点、再除尺寸",从 0..1 转回可采样位置则是逆运算"乘尺寸、加原点":

// Destination position, normalized to 0..1 over the destination image.
func dstUV(dstPos vec4) vec2 {
	return (dstPos.xy - imageDstOrigin()) / imageDstSize()
}

// Source position, normalized to 0..1 over source image 0.
func srcUV(src0Pos vec2) vec2 {
	return (src0Pos - imageSrc0Origin()) / imageSrc0Size()
}

// The inverse: a 0..1 coordinate back to a samplable position on source 0.
func src0PosOf(uv vec2) vec2 {
	return uv*imageSrc0Size() + imageSrc0Origin()
}

最常见的移植 bug 就是直接 dstPos.xy / imageDstSize()——图像一旦落在 atlas 的非原点位置,UV 就会被原点偏移。

两个 source 助手的先决条件:

  • imageSrc0Size() 在 DrawTrianglesShader 且 Images[0] == nil 时是零——此时 SrcX/SrcY 未经转换直接到达着色器,没有任何源区域被设置,所以归一化会除以零。这种情况下请把尺寸作为 uniform 传进去。
  • DrawRectShader 则相反:在像素单位下它会把源区域 0 合成为被绘制的矩形,因此即使不带图像也是安全的。

dstUV 的陷阱:它没有上述前置条件,但它归一化的是整张目标图像,而不是正在绘制的区域。从 Shadertoy 移植的 fragCoord/iResolution 几乎总是指后者。两者只有在绘制覆盖整张目标图像时才一致;一旦有 GeoM 平移、矩形小于图像、或绘制到子图像目标,两者就分道扬镳——而且画面不会"破",只是效果被锚定到图像而不是四边形上。

归一化到"被绘制的区域"

对 DrawRectShader 来说,上面的 srcUV 已经是绘制区域坐标:源区域 0 恰好横跨被绘制的矩形——有图像时它是该图像边界(必须与矩形尺寸一致);Images[0] == nil 时像素单位合成 (0,0)-(width,height)。无论哪种情况,src0Pos 都从区域原点运行到原点加尺寸,横跨整个四边形,因此 srcUV 就是矩形上的 0..1。它也不受 GeoM 影响:旋转或缩放绘制会移动 dstPos,但矩形自身坐标不变——这正是为全屏四边形编写的着色器所期望的行为。

// fragCoord/iResolution, over the drawn rectangle.
func drawnUV(src0Pos vec2) vec2 {
	return (src0Pos - imageSrc0Origin()) / imageSrc0Size()
}

// fragCoord itself, in pixels from the rectangle's top-left corner.
func drawnPos(src0Pos vec2) vec2 {
	return src0Pos - imageSrc0Origin()
}

而 DrawTrianglesShader 没有可恢复的"绘制矩形",映射由顶点 SrcX/SrcY 决定。当 Images[0] == nil 时,SrcX/SrcY 未经转换直达着色器——往里面写 0 和 1,src0Pos 本身就是 UV,着色器里完全不需要归一化。

当效果真的锚定在目标空间时(例如围绕移动四边形的暗角 vignette),把绘制的 origin 和 size 作为 uniform 传入,用它们归一化 dstPos。没有任何内置函数报告它们:imageDstOrigin/imageDstSize 只描述目标图像。对应地,SKILL.md 与 skills/writing-kage-shaders/reference/porting-to-kage.md 中的坐标对照表也都标注了 † 号,提醒"仅当绘制覆盖整张目标图像时成立"。

变换一个坐标:减原点 → 变换 → 加原点

任何非平移操作(除法、floor(p/cell)*cell 像素化、mod 平铺、旋转矩阵、镜像)都必须先在 origin 相对空间里做。绕图像中心旋转:

func rotateAroundCenter(src0Pos vec2, angle float) vec2 {
	p := src0Pos - imageSrc0Origin() - imageSrc0Size()/2
	s, c := sin(angle), cos(angle)
	p = vec2(p.x*c-p.y*s, p.x*s+p.y*c)
	return p + imageSrc0Size()/2 + imageSrc0Origin()
}

先减去原点再减去半尺寸,把坐标系移到图像中心;旋转后按原样加回。

采样另一张源图像

四个源槽共享图像 0 的坐标空间,所以直接把 src0Pos 原样传过去即可,无论各图像尺寸如何:

func Fragment(dstPos vec4, src0Pos vec2, color vec4) vec4 {
	return imageSrc0At(src0Pos) * imageSrc1AtFromSrc0Pos(src0Pos).a
}

imageSrcNAtFromSrc0Pos 和 imageSrcNUnsafeAtFromSrc0Pos(N ≥ 1)是 v2.10 新增的。imageSrcNAt 与 imageSrcNUnsafeAt 是它们改名前的同名函数,仍然可用但自 v2.10 起弃用——仓库 internal/legacyshader/deprecated.go 中的注释即为证。函数名的后缀就是规则:它们接收图像 0 坐标空间里的位置。底层实现(internal/graphics/shader.go)会重定位:取 pos - imageSrc0Origin() + imageSrcNOrigin(),并且 imageSrcNAtFromSrc0Pos 在越界时返回 vec4(0)。因此图像 0 的像素 (x, y) 与图像 N 的像素 (x, y) 对齐,尺寸不同无需修正;图像 N 比图像 0 小时,越界处直接返回 vec4(0)。

想要把图像 1 拉伸覆盖整张图像 0(而不是逐像素对齐),就在图像 0 的空间里归一化、按图像 1 的尺寸缩放,并加回图像 0 的原点。结果仍是图像 0 空间中的位置,这正是 imageSrc1AtFromSrc0Pos 所需的:

func src0PosForStretchedSrc1(src0Pos vec2) vec2 {
	uv := (src0Pos - imageSrc0Origin()) / imageSrc0Size()
	return uv*imageSrc1Size() + imageSrc0Origin()
}

经典错误是这里加 imageSrc1Origin()——原点是函数内部自己加的,再加一次等于把 atlas 偏移算了两次,会采样到 atlas 上无关的部分。imageSrcNOrigin()(N ≥ 1)几乎从不出现在采样表达式里;imageSrc0Origin() 才是那个重要的原点。

寻址模式:clamp 与 repeat

imageSrc0At 和 imageSrcNAtFromSrc0Pos 在图像外返回 vec4(0)(等价于 clamp-to-zero)。想要另外两种行为需自己实现:

// Clamp to edge.
func clampToEdge(pos vec2) vec2 {
	const epsilon = 0.001
	origin := imageSrc0Origin()
	return clamp(pos, origin, origin+imageSrc0Size()-vec2(epsilon))
}

// Repeat.
func repeat(pos vec2) vec2 {
	origin := imageSrc0Origin()
	return mod(pos-origin, imageSrc0Size()) + origin
}

两者都产生"证明在区域内"的位置——这正是 imageSrc0UnsafeAt 的前置条件:它跳过边界检查,在区域外结果是未定义的(可能是 atlas 的 padding、相邻图像的像素、零或其他东西,取决于位置和后端)。所以 unsafe 形式只应在 clamp 或 wrap 之后使用。repeat 的 mod(pos-origin, size) + origin 与 Ebitengine 内置的 adjustSrcPosForAddressRepeat(见 internal/builtinshader/defs.go)如出一辙,可以互相印证。

注意 clampToEdge 钳制到图像区域 [origin, origin+size),钳制到 origin 的坐标会让第一个采样点落在 origin-0.5,实际在图像之外——这是钳制区域,不是钳制纹素中心(见下节)。

双线性采样

Kage 的采样永远是最近邻:没有线性过滤、没有 mipmap、没有 wrap 模式——ebiten.Filter/ebiten.Address 只作用于 DrawImage/DrawTriangles,不作用于自定义着色器。绘制放大时需手工插值:

func bilinearAt(pos vec2) vec4 {
	p := pos - vec2(0.5)
	f := fract(p)
	base := floor(p) + vec2(0.5)
	tl := imageSrc0At(base)
	tr := imageSrc0At(base + vec2(1, 0))
	bl := imageSrc0At(base + vec2(0, 1))
	br := imageSrc0At(base + vec2(1, 1))
	return mix(mix(tl, tr, f.x), mix(bl, br, f.x), f.y)
}

四个 tap 都用 imageSrc0At 会在图像边缘表现为 clamp-to-zero:距边界半个像素内,一两个 tap 落到区域外、贡献 vec4(0),放大时就会出现暗边或透明边。要 clamp-to-edge 或 repeat,就对每个 tap 施加寻址变换,这同时让每个 tap 都"证明在区域内":

func bilinearClampedAt(pos vec2) vec4 {
	p := pos - vec2(0.5)
	f := fract(p)
	base := floor(p) + vec2(0.5)
	tl := imageSrc0UnsafeAt(clampToEdge(base))
	tr := imageSrc0UnsafeAt(clampToEdge(base + vec2(1, 0)))
	bl := imageSrc0UnsafeAt(clampToEdge(base + vec2(0, 1)))
	br := imageSrc0UnsafeAt(clampToEdge(base + vec2(1, 1)))
	return mix(mix(tl, tr, f.x), mix(bl, br, f.x), f.y)
}

把 clampToEdge 换成 repeat 就是平铺(wrapping)。

另一种钳制思路:先对传入的 pos 钳制一次、再派生出 tap,也能得到 clamp-to-edge——但只能钳制到纹素中心范围 [origin+0.5, origin+size-0.5],而不是 clampToEdge 算的那个区域范围:

func clampToTexelCenters(pos vec2) vec2 {
	origin := imageSrc0Origin()
	return clamp(pos, origin+vec2(0.5), origin+imageSrc0Size()-vec2(0.5))
}

这样内部插值得以保留,最远边缘处每对 tap 的第二个采样点恰好落在最后一个中心外一个纹素的位置,权重精确为零。此时配对输入钳制要配 imageSrc0At——它的 vec4(0) 在权重为零时无害;不要配 imageSrc0UnsafeAt,未定义值乘零不必等于零。

像素化(Pixelation)

固定单元大小,取每个单元中心的颜色:

const CellSize = 12.0

func Fragment(dstPos vec4, src0Pos vec2, color vec4) vec4 {
	origin := imageSrc0Origin()
	cell := floor((src0Pos-origin)/CellSize)*CellSize + vec2(CellSize/2)
	return imageSrc0At(cell + origin)
}

对整个单元取平均需要循环,且循环界必须是常量(Kage 只接受常量界的 for):

const CellSize = 12.0

func Fragment(dstPos vec4, src0Pos vec2, color vec4) vec4 {
	origin := imageSrc0Origin()
	cell := floor((src0Pos-origin)/CellSize) * CellSize
	var acc vec4
	for y := 0.0; y < CellSize; y++ {
		for x := 0.0; x < CellSize; x++ {
			acc += imageSrc0At(cell + vec2(x, y) + origin)
		}
	}
	return acc / (CellSize * CellSize)
}

此处 CellSize 必须是整数值,否则循环次数和除数不一致。

由 uniform 控制的循环次数

Kage 没有 uniform 控制的循环界。技巧是:循环到常量上界、在 uniform 处 break。

var CellSize float

const MaxCellSize = 32.0

func Fragment(dstPos vec4, src0Pos vec2, color vec4) vec4 {
	// Flooring keeps cells on an integer grid: a fractional size puts adjacent
	// cell origins at fractional positions, so neighbouring cells sample
	// overlapping texels under nearest sampling. Clamping keeps the divisor
	// non-zero and the loop bound within the constant's reach.
	size := floor(clamp(CellSize, 1, MaxCellSize))
	origin := imageSrc0Origin()
	cell := floor((src0Pos-origin)/size) * size
	var acc vec4
	var n float
	for y := 0.0; y < MaxCellSize; y++ {
		if y >= size {
			break
		}
		for x := 0.0; x < MaxCellSize; x++ {
			if x >= size {
				break
			}
			acc += imageSrc0At(cell + vec2(x, y) + origin)
			n++
		}
	}
	return acc / n
}

floor 让单元落在整数网格上:分数尺寸会让相邻单元原点落在分数位置,最近邻采样下相邻单元会采样到重叠的纹素;clamp 保证除数非零、循环界在常量可达范围内。size 量化后 n 恒等于 size*size,但计数仍然值得保留——如果去掉 floor 以允许平滑动画的单元尺寸,循环每轴会跑 ceil(size) 次,此时 n 依然正确。注意那种情况下单元会重叠,网格不再对齐纹素。

可分离核(水平模糊)

整像素偏移不需要原点运算,因为原点会抵消:imageSrc0At(src0Pos + vec2(1, 0)) 就是相邻纹素。只有缩放坐标才需要"减-变换-加"三明治。

const Radius = 4

func blurH(pos vec2) vec4 {
	var acc vec4
	var weight float
	for i := -Radius; i <= Radius; i++ {
		w := 1.0 - abs(float(i))/(Radius+1)
		acc += imageSrc0At(pos+vec2(float(i), 0)) * w
		weight += w
	}
	return acc / weight
}

三角形权重核,归一化保证亮度不变;垂直方向对称实现即可组合成可分离模糊。

预乘 alpha

Ebitengine 处处使用预乘 alpha,着色器也不例外:采样返回预乘颜色;你返回的 vec4 必须预乘(逐分量 rgb ≤ a),没有任何东西帮你 clamp,非法颜色会渲染成过亮、洗白的混合结果。

// Fade: scale the whole vector, never the alpha alone. Scaling all four
// components commutes with premultiplication, so this matches what the
// straight-alpha equivalent would produce.
func fade(clr vec4, t float) vec4 {
	return clr * t
}

// Round-trip to straight alpha, needed by any operation that does not commute
// with premultiplication — gamma among them — and by `mix` between samples
// whose alphas differ. Addition needs each input converted as well, but
// converting is not the whole fix: `+` defines no output alpha, so the port
// must also reproduce whatever policy the original used.
func withStraightRGB(clr vec4) vec4 {
	rgb := clr.rgb / max(clr.a, 1e-6)
	rgb = pow(rgb, vec3(1.0/2.2)) // whatever the computation is
	return vec4(rgb*clr.a, clr.a)
}

// A color written as 0..255 channels, premultiplied.
func rgba8(r, g, b, a float) vec4 {
	return vec4(r/255*(a/255), g/255*(a/255), b/255*(a/255), a/255)
}

要点:淡入淡出要缩放整个向量(clr * t),绝不只缩放 alpha;换算回直通 alpha 后再计算、再预乘回去,除法要防零(max(clr.a, 1e-6))。mix 看似线性,但在预乘值上它按预乘空间插值——只有当两个 alpha 相等时才与直通 RGB 结果一致,而且它也不是 source-over 合成。+ 连"alpha 相等"这个例外都没有:它没有自己的输出 alpha 策略,必须连同原效果的输出 alpha 策略一起复刻。判断某个 RGB 运算能否留在预乘空间,标准是它是否与预乘可交换(F(a*rgb) == a*F(rgb)):缩放整个向量可以,恒定逐通道 tint(alpha 因子为 1)可以,min/max 对零这类正齐次运算也可以;gamma、带固定枢轴的对比度曲线、多数 pow 指数、对固定非零值的阈值都不行。HSV 与 HSL 要分别判断——HSV 中色相/饱和度在正缩放下不变、只有明度携带缩放,只动色相饱和度的运算可交换;HSL 的饱和度在 L < 0.5 时是 (max-min)/(max+min)(缩放不变)、L ≥ 0.5 时是 (max-min)/(2-max-min)(固定白点导致缩放依赖),常见的 min(s*k, 1) 足以破坏可交换性。没有确证等价就转换。

无分支选择器

当分支会在波前(wavefront)内大面积发散时有用;短分支用普通 if 即可。

func whenGreaterOrEqual(a, b float) float { return step(b, a) }
func whenLess(a, b float) float           { return 1 - step(b, a) }
func whenEqual(a, b float) float          { return 1 - abs(sign(a-b)) }

// Pick a when sel is 0, b when sel is 1.
func pick(a, b vec4, sel float) vec4 {
	return mix(a, b, sel)
}

step(b, a) 在 a >= b 时返回 1;mix(a, b, sel) 在 sel 为 0/1 时精确选出 a/b。

调试:把坐标当作颜色

移植任何效果之前,先把坐标作为颜色返回并观察结果。正确的目标渐变应该是:目标图像的左上角为黑、向右变红、向下变绿——如果绘制只覆盖该图像的一部分,渐变横跨整张图像,绘制区域只显示其中一片。

func Fragment(dstPos vec4, src0Pos vec2, color vec4) vec4 {
	uv := (dstPos.xy - imageDstOrigin()) / imageDstSize()
	return vec4(uv, 0, 1)
}

如果渐变偏移、被裁剪,或图像只在某些尺寸下看起来正确,就是某个原点丢失了。用 src0Pos/imageSrc0* 替换可同样地检查源侧。这也呼应 SKILL.md 的移植流程:"先移植坐标处理并单独验证(返回 vec4(dstUV, 0, 1),确认图像上出现干净的红/绿渐变),再移植效果本体"——几乎所有"效果偏移/平铺错误/只在图像恰好是整张 atlas 时正常"的 bug 都是丢了一个原点。

无 GPU 的编译验证

写完配方后用普通 go test 即可验证编译,ebiten.NewShader 不需要 GPU、窗口或显示器:

package shaders_test

import (
	"os"
	"testing"

	"github.com/hajimehoshi/ebiten/v2"
)

func TestShaderCompiles(t *testing.T) {
	src, err := os.ReadFile("effect.kage")
	if err != nil {
		t.Fatal(err)
	}
	if _, err := ebiten.NewShader(src); err != nil {
		t.Fatal(err)
	}
}

错误按 line:column: message 报告。两个限制:这只验证 Kage 本身,GLSL/HLSL/MSL 转换发生在图形驱动首次使用时,后端级拒绝(递归、驱动特定限制)要到绘制时才会暴露;它也无法捕捉"结果错误"——那需要配合 skills/run-ebitengine-app-headless 无头渲染并逐像素比对。.kage 文件不需要 build 约束,Go 工具链会忽略该扩展名;//go:build ignore 只用于以 .go 扩展名保存 Kage 源码的场景(本仓库 examples/shader 即如此),让 Go 工具跳过它。

结语

这套配方围绕一个核心思想展开:在 atlas 相对坐标系中,先减原点、变换、再加回原点。无论是 0..1 归一化、绘制区域坐标、旋转、跨图像采样、clamp/repeat 寻址、双线性插值还是像素化单元计算,全部建立在这一惯例之上。调试用的颜色渐变则提供了验证它的最快手段。想系统了解坐标模型与逐结构移植对照,请阅读 skills/writing-kage-shaders/SKILL.md 与 skills/writing-kage-shaders/reference/porting-to-kage.md。

登录后查看全文
ebiten