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
docs: update post-processing guide for multi-pass bloom and new APIs
esengine01150ec4f23e
diff --git a/docs/astro/src/content/docs/guides/post-processing.mdx b/docs/astro/src/content/docs/guides/post-processing.mdxindex 7e92c1aef..0bc9c39e6 100644--- a/docs/astro/src/content/docs/guides/post-processing.mdx+++ b/docs/astro/src/content/docs/guides/post-processing.mdx@@ -14,9 +14,9 @@ import { PostProcess } from 'esengine';// Create an effect stackconst fx = PostProcess.createStack();-fx.addPass('bloom', PostProcess.createBloom());-fx.setUniform('bloom', 'u_threshold', 0.8);-fx.setUniform('bloom', 'u_intensity', 1.5);+fx.addPass('vignette', PostProcess.createVignette());+fx.setUniform('vignette', 'u_intensity', 0.6);+fx.setUniform('vignette', 'u_softness', 0.5);// Bind to a camera entityPostProcess.bind(cameraEntity, fx);@@ -52,6 +52,7 @@ PostProcess.bind(cameraEntity, fx);|--------|-------------|| `addPass(name, shader)` | Append a named pass || `removePass(name)` | Remove a pass by name |+| `clearPasses()` | Remove all passes || `setEnabled(name, enabled)` | Enable or disable a pass || `setUniform(pass, name, value)` | Set a float uniform || `setUniformVec4(pass, name, value)` | Set a vec4 uniform |@@ -81,9 +82,11 @@ PostProcess.unbind(cameraEntity);| Method | Effect | Uniforms ||--------|--------|----------|-| `createBloom()` | Bright-pixel glow | `u_threshold` — brightness cutoff, `u_intensity` — glow strength, `u_radius` — blur spread |+| `createBloomExtract()` | Bloom: extract bright pixels | `u_threshold` (0–1) — brightness cutoff |+| `createBloomKawase(iteration)` | Bloom: Kawase blur pass | `u_radius` — blur spread, `u_resolution` (auto) |+| `createBloomComposite()` | Bloom: recombine with scene | `u_intensity` — glow strength, `u_sceneTexture` (auto) || `createBlur()` | Gaussian blur | `u_intensity` — blur spread |-| `createVignette()` | Darkened edges | `u_intensity` — radius, `u_softness` — falloff |+| `createVignette()` | Darkened edges | `u_intensity` (0–1) — effect strength, `u_softness` (0–1) — falloff || `createGrayscale()` | Desaturation | `u_intensity` (0–1) — blend ratio || `createChromaticAberration()` | RGB channel offset | `u_intensity` — offset amount |@@ -93,17 +96,32 @@ PostProcess.unbind(cameraEntity);### Bloom-Extracts bright pixels, blurs them, and adds them back. Good for glowing lights and HDR-like effects:+Bloom uses a multi-pass pipeline: extract bright pixels, apply several Kawase blur iterations, then composite the result back onto the scene. This produces higher-quality results than a single-pass approach:```typescriptconst fx = PostProcess.createStack();-fx.addPass('bloom', PostProcess.createBloom());-fx.setUniform('bloom', 'u_threshold', 0.8); // brightness cutoff-fx.setUniform('bloom', 'u_intensity', 1.5); // glow strength-fx.setUniform('bloom', 'u_radius', 4.0); // blur spread++// 1. Extract bright pixels+fx.addPass('bloom_extract', PostProcess.createBloomExtract());+fx.setUniform('bloom_extract', 'u_threshold', 0.4);++// 2. Kawase blur (multiple iterations for wider, smoother blur)+for (let i = 0; i < 5; i++) {+ fx.addPass(`bloom_kawase_${i}`, PostProcess.createBloomKawase(i));+ fx.setUniform(`bloom_kawase_${i}`, 'u_radius', 1.0);+}++// 3. Composite bloom back onto the original scene+fx.addPass('bloom_composite', PostProcess.createBloomComposite());+fx.setUniform('bloom_composite', 'u_intensity', 1.5);+PostProcess.bind(cameraEntity, fx);```+<Aside type="tip">+ The engine automatically binds the original scene texture to `u_sceneTexture` (texture unit 1) so the composite pass can blend bloom with the unprocessed scene.+</Aside>+### Blur9-tap Gaussian blur. Higher `u_intensity` increases the blur spread:@@ -122,8 +140,8 @@ Darkens the screen edges:```typescriptconst fx = PostProcess.createStack();fx.addPass('vignette', PostProcess.createVignette());-fx.setUniform('vignette', 'u_intensity', 0.8);-fx.setUniform('vignette', 'u_softness', 0.4);+fx.setUniform('vignette', 'u_intensity', 0.6);+fx.setUniform('vignette', 'u_softness', 0.5);PostProcess.bind(cameraEntity, fx);```@@ -222,7 +240,7 @@ Effects are visible in both the Scene View and the Game View. The component data## Custom Pass-Write a custom fragment shader. The vertex shader uses a fixed full-screen quad — you only write the fragment shader:+Write a custom fragment shader. The vertex shader uses a fixed full-screen triangle — you only write the fragment shader:```typescriptimport { Material, PostProcess } from 'esengine';@@ -284,9 +302,14 @@ function setPaused(paused: boolean) {```typescript// Main camera — bloom + vignetteconst mainFx = PostProcess.createStack();-mainFx.addPass('bloom', PostProcess.createBloom());+mainFx.addPass('bloom_extract', PostProcess.createBloomExtract());+mainFx.setUniform('bloom_extract', 'u_threshold', 0.4);+for (let i = 0; i < 5; i++) {+ mainFx.addPass(`bloom_kawase_${i}`, PostProcess.createBloomKawase(i));+}+mainFx.addPass('bloom_composite', PostProcess.createBloomComposite());+mainFx.setUniform('bloom_composite', 'u_intensity', 1.5);mainFx.addPass('vignette', PostProcess.createVignette());-mainFx.setUniform('bloom', 'u_threshold', 0.7);mainFx.setUniform('vignette', 'u_intensity', 0.6);PostProcess.bind(mainCamera, mainFx);@@ -310,7 +333,11 @@ PostProcess.bind(minimapCamera, minimapFx);| `PostProcess.init(width, height)` | Initialize the pipeline (called automatically) || `PostProcess.shutdown()` | Shut down the pipeline || `PostProcess.resize(width, height)` | Update framebuffer size (called automatically) |-| `PostProcess.createBloom()` | Create a bloom effect shader |+| `PostProcess.begin()` | Begin capturing the scene for post-processing |+| `PostProcess.end()` | End capture and execute all effect passes |+| `PostProcess.createBloomExtract()` | Create bloom brightness extraction shader |+| `PostProcess.createBloomKawase(iteration)` | Create bloom Kawase blur shader for a given iteration |+| `PostProcess.createBloomComposite()` | Create bloom composite shader || `PostProcess.createBlur()` | Create a blur effect shader || `PostProcess.createVignette()` | Create a vignette effect shader || `PostProcess.createGrayscale()` | Create a grayscale effect shader |diff --git a/docs/astro/src/content/docs/zh/guides/post-processing.mdx b/docs/astro/src/content/docs/zh/guides/post-processing.mdxindex 5adf70c42..68cfbf741 100644--- a/docs/astro/src/content/docs/zh/guides/post-processing.mdx+++ b/docs/astro/src/content/docs/zh/guides/post-processing.mdx@@ -14,9 +14,9 @@ import { PostProcess } from 'esengine';// 创建效果栈const fx = PostProcess.createStack();-fx.addPass('bloom', PostProcess.createBloom());-fx.setUniform('bloom', 'u_threshold', 0.8);-fx.setUniform('bloom', 'u_intensity', 1.5);+fx.addPass('vignette', PostProcess.createVignette());+fx.setUniform('vignette', 'u_intensity', 0.6);+fx.setUniform('vignette', 'u_softness', 0.5);// 绑定到相机实体PostProcess.bind(cameraEntity, fx);@@ -52,6 +52,7 @@ PostProcess.bind(cameraEntity, fx);|------|------|| `addPass(name, shader)` | 追加一个命名 pass || `removePass(name)` | 按名称移除 pass |+| `clearPasses()` | 移除所有 pass || `setEnabled(name, enabled)` | 启用或禁用 pass || `setUniform(pass, name, value)` | 设置 float uniform || `setUniformVec4(pass, name, value)` | 设置 vec4 uniform |@@ -81,9 +82,11 @@ PostProcess.unbind(cameraEntity);| 方法 | 效果 | Uniform ||------|------|---------|-| `createBloom()` | 亮像素辉光 | `u_threshold` — 亮度截断, `u_intensity` — 辉光强度, `u_radius` — 模糊扩散 |+| `createBloomExtract()` | 辉光:提取亮像素 | `u_threshold` (0–1) — 亮度截断 |+| `createBloomKawase(iteration)` | 辉光:Kawase 模糊 pass | `u_radius` — 模糊扩散, `u_resolution`(自动) |+| `createBloomComposite()` | 辉光:合成回原图 | `u_intensity` — 辉光强度, `u_sceneTexture`(自动) || `createBlur()` | 高斯模糊 | `u_intensity` — 模糊扩散 |-| `createVignette()` | 暗角 | `u_intensity` — 半径, `u_softness` — 衰减 |+| `createVignette()` | 暗角 | `u_intensity` (0–1) — 效果强度, `u_softness` (0–1) — 衰减 || `createGrayscale()` | 去饱和 | `u_intensity` (0–1) — 混合比例 || `createChromaticAberration()` | RGB 通道偏移 | `u_intensity` — 偏移量 |@@ -93,17 +96,32 @@ PostProcess.unbind(cameraEntity);### 辉光 (Bloom)-提取亮像素、模糊后叠加回原图。适合发光灯效和类 HDR 效果:+Bloom 使用多 pass 管线:提取亮像素、多次 Kawase 模糊迭代、最后合成回原图。比单 pass 方案质量更高:```typescriptconst fx = PostProcess.createStack();-fx.addPass('bloom', PostProcess.createBloom());-fx.setUniform('bloom', 'u_threshold', 0.8); // 亮度截断-fx.setUniform('bloom', 'u_intensity', 1.5); // 辉光强度-fx.setUniform('bloom', 'u_radius', 4.0); // 模糊扩散++// 1. 提取亮像素+fx.addPass('bloom_extract', PostProcess.createBloomExtract());+fx.setUniform('bloom_extract', 'u_threshold', 0.4);++// 2. Kawase 模糊(多次迭代产生更宽、更平滑的模糊)+for (let i = 0; i < 5; i++) {+ fx.addPass(`bloom_kawase_${i}`, PostProcess.createBloomKawase(i));+ fx.setUniform(`bloom_kawase_${i}`, 'u_radius', 1.0);+}++// 3. 将辉光合成回原始场景+fx.addPass('bloom_composite', PostProcess.createBloomComposite());+fx.setUniform('bloom_composite', 'u_intensity', 1.5);+PostProcess.bind(cameraEntity, fx);```+<Aside type="tip">+ 引擎会自动将原始场景纹理绑定到 `u_sceneTexture`(纹理单元 1),合成 pass 可以将辉光与未处理的场景混合。+</Aside>+### 模糊 (Blur)9 次采样高斯模糊。`u_intensity` 越大模糊越强:@@ -122,8 +140,8 @@ PostProcess.bind(cameraEntity, fx);```typescriptconst fx = PostProcess.createStack();fx.addPass('vignette', PostProcess.createVignette());-fx.setUniform('vignette', 'u_intensity', 0.8);-fx.setUniform('vignette', 'u_softness', 0.4);+fx.setUniform('vignette', 'u_intensity', 0.6);+fx.setUniform('vignette', 'u_softness', 0.5);PostProcess.bind(cameraEntity, fx);```@@ -222,7 +240,7 @@ Volume 允许空间后处理 — 当相机进入指定区域时激活效果。## 自定义 Pass-编写自定义片段着色器。顶点着色器使用固定的全屏四边形 — 你只需编写片段着色器:+编写自定义片段着色器。顶点着色器使用固定的全屏三角形 — 你只需编写片段着色器:```typescriptimport { Material, PostProcess } from 'esengine';@@ -284,9 +302,14 @@ function setPaused(paused: boolean) {```typescript// 主相机 — 辉光 + 暗角const mainFx = PostProcess.createStack();-mainFx.addPass('bloom', PostProcess.createBloom());+mainFx.addPass('bloom_extract', PostProcess.createBloomExtract());+mainFx.setUniform('bloom_extract', 'u_threshold', 0.4);+for (let i = 0; i < 5; i++) {+ mainFx.addPass(`bloom_kawase_${i}`, PostProcess.createBloomKawase(i));+}+mainFx.addPass('bloom_composite', PostProcess.createBloomComposite());+mainFx.setUniform('bloom_composite', 'u_intensity', 1.5);mainFx.addPass('vignette', PostProcess.createVignette());-mainFx.setUniform('bloom', 'u_threshold', 0.7);mainFx.setUniform('vignette', 'u_intensity', 0.6);PostProcess.bind(mainCamera, mainFx);@@ -310,7 +333,11 @@ PostProcess.bind(minimapCamera, minimapFx);| `PostProcess.init(width, height)` | 初始化管线(自动调用) || `PostProcess.shutdown()` | 关闭管线 || `PostProcess.resize(width, height)` | 更新帧缓冲尺寸(自动调用) |-| `PostProcess.createBloom()` | 创建辉光效果着色器 |+| `PostProcess.begin()` | 开始捕获场景用于后处理 |+| `PostProcess.end()` | 结束捕获并执行所有效果 pass |+| `PostProcess.createBloomExtract()` | 创建辉光亮度提取着色器 |+| `PostProcess.createBloomKawase(iteration)` | 创建辉光 Kawase 模糊着色器 |+| `PostProcess.createBloomComposite()` | 创建辉光合成着色器 || `PostProcess.createBlur()` | 创建模糊效果着色器 || `PostProcess.createVignette()` | 创建暗角效果着色器 || `PostProcess.createGrayscale()` | 创建灰度效果着色器 |