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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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.mdxindex 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.tsindex 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.tsindex 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-texeldiff --git a/sdk/tests/postprocess.test.ts b/sdk/tests/postprocess.test.tsindex 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.tsindex 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);});