Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(postprocess): outline — full-screen Sobel ink edges

yhh8738150de86e
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
index b4151bf91..ceb4b0b46 100644
--- a/docs/astro/src/content/docs/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -24,14 +24,15 @@ several can stack in one frame at no extra target cost beyond the passes.
| `fxaa` | Fast anti-aliasing | `intensity` |
| `lensDistortion` | Barrel / pincushion warp | `strength`, `zoom` |
| `pixelate` | Block quantization | `pixelSize` |
+| `outline` | Ink-edge outlines (Sobel edge darkening) | `intensity`, `threshold`, `thickness` |
| `grayscale` | Desaturate | `intensity` |
The uniform names above are the friendly labels; **in code they are `u_`-prefixed**
(`u_intensity`, `u_exposure`, …). Most effects are identity at their defaults
(`colorGrade`, `blur`, `chromaticAberration`, `fxaa`, `lensDistortion`, `lutGrade`),
so adding them changes nothing until you dial them in. A few are visible the moment
-you add them — `grayscale` (full desaturation), `vignette`, `bloom`, and `tonemap`
-(the ACES curve always applies) — so enable those only when you want them.
+you add them — `grayscale` (full desaturation), `vignette`, `bloom`, `outline`, and
+`tonemap` (the ACES curve always applies) — so enable those only when you want them.
## Using a `PostProcessVolume`
diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
index 2db1c6f43..d84f2194b 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -23,12 +23,13 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
| `fxaa` | 快速抗锯齿 | `intensity` |
| `lensDistortion` | 桶形 / 枕形畸变 | `strength`、`zoom` |
| `pixelate` | 块状量化 | `pixelSize` |
+| `outline` | 墨线描边(Sobel 边缘压暗) | `intensity`、`threshold`、`thickness` |
| `grayscale` | 去色 | `intensity` |
上面是友好标签;**在代码里它们带 `u_` 前缀**(`u_intensity`、`u_exposure`……)。多数效果
在默认值下是恒等(`colorGrade`、`blur`、`chromaticAberration`、`fxaa`、`lensDistortion`、
`lutGrade`),加进去不调参不改画面。少数一加就可见——`grayscale`(完全去色)、`vignette`、
-`bloom`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。
+`bloom`、`outline`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。
## 使用 `PostProcessVolume`
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 107b6443a..0f90208d9 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -158,6 +158,17 @@ registerEffect({
],
});
+registerEffect({
+ type: 'outline',
+ label: 'Outline',
+ factory: () => postProcessEffects.createOutline(),
+ uniforms: [
+ { name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 1 },
+ { name: 'u_threshold', label: 'Threshold', min: 0, max: 1, step: 0.01, defaultValue: 0.2 },
+ { name: 'u_thickness', label: 'Thickness', min: 0.5, max: 4, step: 0.5, defaultValue: 1 },
+ ],
+});
+
registerEffect({
type: 'lutGrade',
label: 'LUT Grade',
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 26e042b34..578717e95 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -619,6 +619,74 @@ void main() {
return Material.compileShader(source);
},
+ createOutline(): ShaderHandle {
+ // Ink-edge outline: Sobel edge detection on scene luma, darkening edge
+ // pixels toward black — the classic full-screen 2D ink look.
+ // u_intensity 0 is an exact no-op; u_threshold gates the edge magnitude
+ // (higher = only hard silhouettes); u_thickness is the Sobel tap offset
+ // in device pixels (via the injected u_viewport).
+ const source = `#pragma shader "PP Outline"
+#pragma version 300 es
+#pragma domain PostProcess
+#pragma param u_intensity float default(1) range(0,1)
+#pragma param u_threshold float default(0.2) range(0,1)
+#pragma param u_thickness float default(1) range(0.5,4)
+
+#pragma fragment
+precision highp float;
+
+in vec2 v_texCoord;
+uniform sampler2D u_texture;
+out vec4 fragColor;
+
+float lum(vec2 offset) {
+ return dot(texture(u_texture, v_texCoord + offset).rgb, vec3(0.299, 0.587, 0.114));
+}
+
+void main() {
+ vec4 src = texture(u_texture, v_texCoord);
+ vec2 px = vec2(u_thickness) / u_viewport.xy;
+ float tl = lum(vec2(-px.x, px.y));
+ float tt = lum(vec2( 0.0, px.y));
+ float tr = lum(vec2( px.x, px.y));
+ float ll = lum(vec2(-px.x, 0.0));
+ float rr = lum(vec2( px.x, 0.0));
+ float bl = lum(vec2(-px.x, -px.y));
+ float bb = lum(vec2( 0.0, -px.y));
+ float br = lum(vec2( px.x, -px.y));
+ float gx = (tr + 2.0 * rr + br) - (tl + 2.0 * ll + bl);
+ float gy = (tl + 2.0 * tt + tr) - (bl + 2.0 * bb + br);
+ float edge = clamp((sqrt(gx * gx + gy * gy) - u_threshold) * 4.0, 0.0, 1.0);
+ fragColor = vec4(mix(src.rgb, vec3(0.0), edge * u_intensity), src.a);
+}
+#pragma end
+
+#pragma fragment wgsl
+fn lum(uv : vec2f) -> f32 {
+ return dot(textureSampleLevel(t0, s0, uv, 0.0).rgb, vec3f(0.299, 0.587, 0.114));
+}
+
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+ let px = vec2f(mc.u_thickness) / tc.u_viewport.xy;
+ let tl = lum(v.v_texCoord + vec2f(-px.x, px.y));
+ let tt = lum(v.v_texCoord + vec2f( 0.0, px.y));
+ let tr = lum(v.v_texCoord + vec2f( px.x, px.y));
+ let ll = lum(v.v_texCoord + vec2f(-px.x, 0.0));
+ let rr = lum(v.v_texCoord + vec2f( px.x, 0.0));
+ let bl = lum(v.v_texCoord + vec2f(-px.x, -px.y));
+ let bb = lum(v.v_texCoord + vec2f( 0.0, -px.y));
+ let br = lum(v.v_texCoord + vec2f( px.x, -px.y));
+ let gx = (tr + 2.0 * rr + br) - (tl + 2.0 * ll + bl);
+ let gy = (tl + 2.0 * tt + tr) - (bl + 2.0 * bb + br);
+ let edge = clamp((sqrt(gx * gx + gy * gy) - mc.u_threshold) * 4.0, 0.0, 1.0);
+ return vec4f(mix(src.rgb, vec3f(0.0), edge * mc.u_intensity), src.a);
+}
+#pragma end
+`;
+ return Material.compileShader(source);
+ },
+
createPixelate(): ShaderHandle {
// Snaps sampling to a grid of u_pixelSize-device-pixel blocks — the
// canonical retro/mosaic 2D look. u_pixelSize <= 1 samples per-texel
diff --git a/sdk/tests/postprocess.test.ts b/sdk/tests/postprocess.test.ts
index c4288d46f..9f5a745ad 100644
--- a/sdk/tests/postprocess.test.ts
+++ b/sdk/tests/postprocess.test.ts
@@ -393,9 +393,10 @@ describe('PostProcess API', () => {
postProcessEffects.createFxaa();
postProcessEffects.createLensDistortion();
postProcessEffects.createPixelate();
+ postProcessEffects.createOutline();
const calls = (Material.compileShader as ReturnType<typeof vi.fn>).mock.calls;
- expect(calls.length).toBe(13);
+ expect(calls.length).toBe(14);
for (const c of calls) {
const src = c[0] as string;
expect(src).toContain('#pragma domain PostProcess');
@@ -460,11 +461,23 @@ describe('PostProcess API', () => {
expect(handle).toBe(42);
});
- it('registers all four effects with matching factories and labels', () => {
+ it('should create a Sobel outline shader with intensity/threshold/thickness', () => {
+ const handle = postProcessEffects.createOutline();
+ const src = lastSource();
+ expect(src).toContain('#pragma param u_intensity float');
+ expect(src).toContain('#pragma param u_threshold float');
+ expect(src).toContain('#pragma param u_thickness float');
+ // Rec.601 luma weights — guards the edge-detection identity.
+ expect(src).toContain('0.587');
+ expect(handle).toBe(42);
+ });
+
+ it('registers the extended effects with matching factories and labels', () => {
expect(getEffectDef('tonemap')?.label).toBe('Tonemap (ACES)');
expect(getEffectDef('fxaa')?.label).toBe('FXAA');
expect(getEffectDef('lensDistortion')?.label).toBe('Lens Distortion');
expect(getEffectDef('pixelate')?.label).toBe('Pixelate');
+ expect(getEffectDef('outline')?.label).toBe('Outline');
});
it('uses identity defaults where the effect is meant to be tuned up from off', () => {
@@ -477,6 +490,8 @@ describe('PostProcess API', () => {
// FXAA full strength by default; pixelate visibly chunky so it reads as on.
expect(def('fxaa')).toEqual({ u_intensity: 1 });
expect(def('pixelate')).toEqual({ u_pixelSize: 4 });
+ // Outline visible when added (intensity 1); 0 is an exact no-op.
+ expect(def('outline')).toEqual({ u_intensity: 1, u_threshold: 0.2, u_thickness: 1 });
});
});
diff --git a/sdk/tests/shader-twins.test.ts b/sdk/tests/shader-twins.test.ts
index 25290e68b..b77ee4c0c 100644
--- a/sdk/tests/shader-twins.test.ts
+++ b/sdk/tests/shader-twins.test.ts
@@ -53,7 +53,7 @@ describe('embedded .esshader structure', () => {
it('found the filter, effect and grid sources', () => {
expect(CASES.filter((c) => c.name.startsWith('filters.ts')).length).toBe(1);
expect(CASES.filter((c) => c.name.startsWith('spriteFilter.ts')).length).toBe(2);
- expect(CASES.filter((c) => c.name.startsWith('postProcessEffects.ts')).length).toBe(13);
+ expect(CASES.filter((c) => c.name.startsWith('postProcessEffects.ts')).length).toBe(14);
expect(CASES.filter((c) => c.name.startsWith('editorGridRenderer.ts')).length).toBe(1);
});