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: add Post-processing guide (PostProcessVolume + effects)

yhhf3c4d6629dc3
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 249420e18..9a9fe491f 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -55,6 +55,7 @@ export default defineConfig({
{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },
+ { label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'guides/postprocess' },
{ label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'guides/assets' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
],
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
new file mode 100644
index 000000000..ae94e2e48
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -0,0 +1,54 @@
+---
+title: Post-processing
+description: Full-screen effects via the PostProcessVolume component.
+---
+
+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.
+
+## 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 |
+
+Each effect exposes tunable uniforms (for example bloom's `threshold` and
+`intensity`) in the inspector.
+
+## Using a volume
+
+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.
+
+## Programmatic control
+
+For a custom pipeline, read the `PostProcess` resource — create a stack and bind
+it to a camera:
+
+```typescript
+import { defineSystem, Res, PostProcess } from 'esengine';
+
+const setup = defineSystem([Res(PostProcess)], (pp) => {
+ const stack = pp.createStack();
+ pp.bind(cameraEntity, stack); // pp.unbind(cameraEntity) to remove
+});
+```
+
+<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.
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
new file mode 100644
index 000000000..c0c4141d6
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -0,0 +1,49 @@
+---
+title: 后处理
+description: 通过 PostProcessVolume 组件实现全屏效果。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcessVolume` 组件——通常
+在编辑器里——启用你想要的效果,并在检视面板里调参数。
+
+## 内置效果
+
+| 效果 | 作用 |
+|------|------|
+| `bloom` | 高亮区域泛光(阈值 + 强度)|
+| `tonemap` | ACES 色调映射 |
+| `colorGrade` | 调色 |
+| `vignette` | 屏幕边缘压暗 |
+| `chromaticAberration` | RGB 色散 |
+| `blur` | 高斯模糊 |
+| `fxaa` | 快速抗锯齿 |
+| `lensDistortion` | 桶形 / 枕形畸变 |
+| `pixelate` | 像素化 |
+| `grayscale` | 去色 |
+
+每个效果都在检视面板里暴露可调 uniform(例如 bloom 的 `threshold` 与 `intensity`)。
+
+## 使用体积(Volume)
+
+加一个 `PostProcessVolume`,启用效果并设定参数。多个体积**重叠时会混合**,因此你可以
+按区域驱动效果,或在过渡中淡入。
+
+## 代码控制
+
+要自定义管线,读取 `PostProcess` 资源——创建一个 stack 并绑定到相机:
+
+```typescript
+import { defineSystem, Res, PostProcess } from 'esengine';
+
+const setup = defineSystem([Res(PostProcess)], (pp) => {
+ const stack = pp.createStack();
+ pp.bind(cameraEntity, stack); // pp.unbind(cameraEntity) 可移除
+});
+```
+
+<Aside type="note">
+ 效果按注册顺序运行并共享 ping-pong 缓冲,所以多个效果可以在一帧里叠加(例如
+ bloom → tonemap → vignette),除了各自的 pass 之外不产生额外的渲染目标开销。
+</Aside>