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.

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.mdx
index 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 stack
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);
// Bind to a camera entity
PostProcess.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:
```typescript
const 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>
+
### Blur
9-tap Gaussian blur. Higher `u_intensity` increases the blur spread:
@@ -122,8 +140,8 @@ Darkens the screen edges:
```typescript
const 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:
```typescript
import { Material, PostProcess } from 'esengine';
@@ -284,9 +302,14 @@ function setPaused(paused: boolean) {
```typescript
// Main camera — bloom + vignette
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)` | 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.mdx
index 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 方案质量更高:
```typescript
const 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);
```typescript
const 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
-编写自定义片段着色器。顶点着色器使用固定的全屏四边形 — 你只需编写片段着色器:
+编写自定义片段着色器。顶点着色器使用固定的全屏三角形 — 你只需编写片段着色器:
```typescript
import { 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()` | 创建灰度效果着色器 |