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: rewrite the Post-processing guide to the complete-reference template

yhhecdf5f31bd39
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
index 1cb8292bb..641c4ea05 100644
--- a/docs/astro/src/content/docs/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -1,42 +1,53 @@
---
title: Post-processing
-description: Full-screen effects via the PostProcessVolume component.
+description: The complete guide to full-screen effects — the PostProcessVolume component, the built-in effect library, and the programmatic PostProcess API.
---
import { Aside } from '@astrojs/starlight/components';
Estella runs full-screen post-processing through ping-pong framebuffers. Add a
-`PostProcessVolume` component — usually in the editor — enable the effects you
-want, and tune their parameters in the inspector.
+`PostProcessVolume` component, enable the effects you want, and tune their
+parameters — in the editor or in code. Effects share the ping-pong buffers, so
+several can stack in one frame at no extra target cost beyond the passes.
## Built-in effects
-| Effect | What it does |
-|--------|--------------|
-| `bloom` | Glow on bright areas (threshold + intensity) |
-| `tonemap` | ACES tonemapping |
-| `colorGrade` | Color grading |
-| `vignette` | Darkened screen edges |
-| `chromaticAberration` | RGB fringing |
-| `blur` | Gaussian blur |
-| `fxaa` | Fast anti-aliasing |
-| `lensDistortion` | Barrel / pincushion distortion |
-| `pixelate` | Pixelation |
-| `grayscale` | Desaturate |
+| Effect | What it does | Key uniforms |
+|---|---|---|
+| `bloom` | Glow on bright areas | `threshold`, `intensity` |
+| `tonemap` | ACES filmic tonemapping | `exposure` |
+| `colorGrade` | Exposure / contrast / saturation / white balance | `exposure`, `contrast`, `saturation`, `temperature`, `tint` |
+| `vignette` | Darkened screen edges | `intensity`, `radius` |
+| `chromaticAberration` | RGB fringing | `intensity` |
+| `blur` | Gaussian blur | `radius` |
+| `fxaa` | Fast anti-aliasing | `intensity` |
+| `lensDistortion` | Barrel / pincushion warp | `strength`, `zoom` |
+| `pixelate` | Block quantization | `pixelSize` |
+| `grayscale` | Desaturate | — |
-Each effect exposes tunable uniforms (for example bloom's `threshold` and
-`intensity`) in the inspector.
+Every effect is a no-op at its default values, so adding one to a stack doesn't
+change the image until you dial it in.
-## Using a volume
+## Using a `PostProcessVolume`
-Add a `PostProcessVolume`, enable the effects, and set their parameters. Volumes
-**blend where they overlap**, so you can drive effects by area or fade them in
-over a transition.
+Add a `PostProcessVolume`, enable effects, and set their parameters. Volumes
+**blend where they overlap**, so you can drive effects by area (a "underwater"
+volume) or fade them in over a transition.
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `effects` | list | `[]` | `{ type, enabled, uniforms }` per effect. |
+| `isGlobal` | boolean | `true` | Apply everywhere vs. only inside the volume shape. |
+| `shape` | `'box' \| 'sphere'` | `'box'` | Bounds shape for a local volume. |
+| `size` | Vec2 | `{5, 5}` | Volume extents (local volumes). |
+| `priority` | number | `0` | Higher-priority volumes win where they overlap. |
+| `weight` | number | `1` | Blend weight, 0..1 (fade the whole volume). |
+| `blendDistance` | number | `0` | Falloff distance at the volume edge. |
## Programmatic control
-For a custom pipeline, read the `PostProcess` resource — create a stack and bind
-it to a camera:
+For a custom pipeline, read the `PostProcess` resource — create a stack, tune it,
+and bind it to a camera:
```typescript
import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
@@ -44,13 +55,37 @@ import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
for (const [camera] of q) {
const stack = pp.createStack();
+ stack.setEnabled('bloom', true)
+ .setUniform('bloom', 'intensity', 1.2)
+ .setUniform('bloom', 'threshold', 0.8);
pp.bind(camera, stack); // pp.unbind(camera) to remove
}
});
```
+| Method | Description |
+|---|---|
+| `PostProcess.createStack()` | Create an effect stack. |
+| `PostProcess.bind(camera, stack)` | Attach a stack to a camera. |
+| `PostProcess.unbind(camera)` | Remove the camera's stack. |
+| `stack.setEnabled(name, on)` | Enable/disable an effect (chainable). |
+| `stack.setUniform(pass, uniform, value)` | Set an effect parameter (chainable). |
+
+## Best practices
+
+- **Order matters** — effects run in registration order and share the buffers, so
+ a sensible chain is bloom → tonemap → color grade → vignette.
+- **Use volumes for locality** (an area's mood) and the `PostProcess` API for a
+ fixed camera pipeline.
+- **Fade with `weight`** on a volume for smooth transitions instead of toggling.
+- **Keep the stack short** on low-end/mobile — each pass is a full-screen draw.
+
<Aside type="note">
- Effects run in registration order and share the ping-pong buffers, so several
- can stack in one frame (e.g. bloom → tonemap → vignette) at no extra target
- cost beyond the passes themselves.
+ Effects are pure-GLSL and data-driven from a registry, so the editor and runtime
+ share one list — there's no hard-coded effect set to drift.
</Aside>
+
+## See also
+
+- [Materials & Shaders](/docs/guides/material/) — per-object shaders (a separate path).
+- [Camera](/docs/guides/camera/) — bind a stack per camera.
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 174cb60a8..efd4cb840 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -1,38 +1,49 @@
---
title: 后处理
-description: 通过 PostProcessVolume 组件实现全屏效果。
+description: 全屏效果的完整指南——PostProcessVolume 组件、内置效果库,以及程序化的 PostProcess API。
---
import { Aside } from '@astrojs/starlight/components';
-Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcessVolume` 组件——通常
-在编辑器里——启用你想要的效果,并在检视面板里调参数。
+Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcessVolume` 组件,启用你要的
+效果,并调节它们的参数——在编辑器里或用代码。效果共享 ping-pong 缓冲,所以多个可以在一帧里
+叠加,除各遍(pass)本身外没有额外的目标开销。
## 内置效果
-| 效果 | 作用 |
-|------|------|
-| `bloom` | 高亮区域泛光(阈值 + 强度)|
-| `tonemap` | ACES 色调映射 |
-| `colorGrade` | 调色 |
-| `vignette` | 屏幕边缘压暗 |
-| `chromaticAberration` | RGB 色散 |
-| `blur` | 高斯模糊 |
-| `fxaa` | 快速抗锯齿 |
-| `lensDistortion` | 桶形 / 枕形畸变 |
-| `pixelate` | 像素化 |
-| `grayscale` | 去色 |
+| 效果 | 作用 | 关键 uniform |
+|---|---|---|
+| `bloom` | 亮部辉光 | `threshold`、`intensity` |
+| `tonemap` | ACES filmic 色调映射 | `exposure` |
+| `colorGrade` | 曝光 / 对比度 / 饱和度 / 白平衡 | `exposure`、`contrast`、`saturation`、`temperature`、`tint` |
+| `vignette` | 屏幕边缘变暗 | `intensity`、`radius` |
+| `chromaticAberration` | RGB 色散 | `intensity` |
+| `blur` | 高斯模糊 | `radius` |
+| `fxaa` | 快速抗锯齿 | `intensity` |
+| `lensDistortion` | 桶形 / 枕形畸变 | `strength`、`zoom` |
+| `pixelate` | 块状量化 | `pixelSize` |
+| `grayscale` | 去色 | — |
-每个效果都在检视面板里暴露可调 uniform(例如 bloom 的 `threshold` 与 `intensity`)。
+每个效果在默认值下都是恒等(no-op),所以把它加进栈里、在你调参之前不会改变画面。
-## 使用体积(Volume)
+## 使用 `PostProcessVolume`
-加一个 `PostProcessVolume`,启用效果并设定参数。多个体积**重叠时会混合**,因此你可以
-按区域驱动效果,或在过渡中淡入。
+加一个 `PostProcessVolume`,启用效果,设置参数。体积**在重叠处混合**,所以你可以按区域驱动
+效果(比如一个"水下"体积),或在过渡中淡入。
-## 代码控制
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `effects` | list | `[]` | 每个效果的 `{ type, enabled, uniforms }`。 |
+| `isGlobal` | boolean | `true` | 全局应用 vs 仅在体积形状内。 |
+| `shape` | `'box' \| 'sphere'` | `'box'` | 局部体积的边界形状。 |
+| `size` | Vec2 | `{5, 5}` | 体积范围(局部体积)。 |
+| `priority` | number | `0` | 重叠处优先级高者胜。 |
+| `weight` | number | `1` | 混合权重,0..1(淡化整个体积)。 |
+| `blendDistance` | number | `0` | 体积边缘的衰减距离。 |
-要自定义管线,读取 `PostProcess` 资源——创建一个 stack 并绑定到相机:
+## 程序化控制
+
+自定义管线时,读 `PostProcess` 资源——创建一个栈、调参,并绑定到相机:
```typescript
import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
@@ -40,12 +51,34 @@ import { defineSystem, Query, Res, Camera, PostProcess } from 'esengine';
const setup = defineSystem([Query(Camera), Res(PostProcess)], (q, pp) => {
for (const [camera] of q) {
const stack = pp.createStack();
- pp.bind(camera, stack); // pp.unbind(camera) 可移除
+ stack.setEnabled('bloom', true)
+ .setUniform('bloom', 'intensity', 1.2)
+ .setUniform('bloom', 'threshold', 0.8);
+ pp.bind(camera, stack); // pp.unbind(camera) to remove
}
});
```
+| 方法 | 说明 |
+|---|---|
+| `PostProcess.createStack()` | 创建一个效果栈。 |
+| `PostProcess.bind(camera, stack)` | 把栈附加到相机。 |
+| `PostProcess.unbind(camera)` | 移除相机的栈。 |
+| `stack.setEnabled(name, on)` | 启用/禁用一个效果(可链式)。 |
+| `stack.setUniform(pass, uniform, value)` | 设置一个效果参数(可链式)。 |
+
+## 最佳实践
+
+- **顺序有讲究**——效果按注册顺序运行并共享缓冲,合理的链是 bloom → tonemap → 调色 → vignette。
+- **用体积做局部**(某区域的氛围),用 `PostProcess` API 做固定的相机管线。
+- 过渡时**用 `weight` 淡化**体积,而不是硬开关。
+- 低端/移动端**让栈保持简短**——每一遍都是一次全屏绘制。
+
<Aside type="note">
- 效果按注册顺序运行并共享 ping-pong 缓冲,所以多个效果可以在一帧里叠加(例如
- bloom → tonemap → vignette),除了各自的 pass 之外不产生额外的渲染目标开销。
+ 效果是纯 GLSL、由注册表数据驱动的,所以编辑器和运行时共用一份列表——没有会漂移的硬编码效果集。
</Aside>
+
+## 参见
+
+- [材质与着色器](/docs/zh-cn/guides/material/) —— 逐物体着色器(独立的路径)。
+- [相机](/docs/zh-cn/guides/camera/) —— 为每个相机绑定一个栈。