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.

feat(renderer): the post chain goes HDR under linear - bright lights bloom

yhhd8d21b2c8f25
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2d5f1db1e..813944f19 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -287,6 +287,24 @@ jobs:
ESTELLA_VERIFY_MANIFEST=/scenes/srgb-midtone.textures.json \
ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 \
'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[128,128,128],"tol":6}]'
+ # Post-process chain guards — bloom's first CI pixel coverage. The gamma
+ # scene pins the LDR multi-pass chain; the linear scene is the HDR
+ # discriminator: threshold 1.5 sits above anything an 8-bit chain can
+ # store, so glow OUTSIDE the sprite (x=0.64) proves over-range light
+ # survived the float intermediates — the same scene blooms NOTHING in
+ # gamma mode.
+ run_scene bloom-ldr \
+ ESTELLA_VERIFY_PLAY=1 \
+ ESTELLA_VERIFY_SCENE=/scenes/bloom-ldr.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/bloom-ldr.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.61,"y":0.5,"rgb":[0,130,0],"tol":35},{"x":0.70,"y":0.5,"rgb":[0,32,0],"tol":25},{"x":0.85,"y":0.5,"rgb":[0,0,0],"tol":12}]'
+ run_scene hdr-bloom \
+ ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_COLORSPACE=linear \
+ ESTELLA_VERIFY_SCENE=/scenes/hdr-bloom.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/hdr-bloom.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[0,255,0],"tol":25},{"x":0.64,"y":0.5,"rgb":[0,255,0],"tol":35},{"x":0.85,"y":0.5,"rgb":[0,0,0],"tol":12}]'
# The SAME pixel assertions on the WebGPU backend — Dawn renders through the
# bundled SwiftShader Vulkan (--use-webgpu-adapter=swiftshader), so a GPU-less
@@ -354,3 +372,18 @@ jobs:
ESTELLA_VERIFY_MANIFEST=/scenes/srgb-midtone.textures.json \
ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 \
'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[128,128,128],"tol":6}]'
+ # Bloom on the second backend — measured byte-identical to GL after the
+ # bind-group eviction fix (stale-id aliasing silently zeroed the WGSL
+ # chain's params); these scenes keep that regression impossible to miss.
+ run_scene webgpu-bloom-ldr \
+ ESTELLA_VERIFY_PLAY=1 \
+ ESTELLA_VERIFY_SCENE=/scenes/bloom-ldr.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/bloom-ldr.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.61,"y":0.5,"rgb":[0,130,0],"tol":35},{"x":0.70,"y":0.5,"rgb":[0,32,0],"tol":25},{"x":0.85,"y":0.5,"rgb":[0,0,0],"tol":12}]'
+ run_scene webgpu-hdr-bloom \
+ ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_COLORSPACE=linear \
+ ESTELLA_VERIFY_SCENE=/scenes/hdr-bloom.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/hdr-bloom.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[0,255,0],"tol":25},{"x":0.64,"y":0.5,"rgb":[0,255,0],"tol":35},{"x":0.85,"y":0.5,"rgb":[0,0,0],"tol":12}]'
diff --git a/desktop/public/scenes/bloom-ldr.esscene b/desktop/public/scenes/bloom-ldr.esscene
new file mode 100644
index 000000000..39587402e
--- /dev/null
+++ b/desktop/public/scenes/bloom-ldr.esscene
@@ -0,0 +1,75 @@
+{
+ "version": "1.0",
+ "name": "HDR Bloom",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "LitQuad",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 120, "y": 120 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "HotGreenLight",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 0,
+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "intensity": 6,
+ "radius": 400
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "PostProcess",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ {
+ "type": "PostProcessVolume",
+ "data": {
+ "isGlobal": true,
+ "priority": 0,
+ "weight": 1,
+ "blendDistance": 0,
+ "shape": "box",
+ "size": { "x": 5, "y": 5 },
+ "effects": [
+ {
+ "type": "bloom",
+ "enabled": true,
+ "uniforms": { "u_threshold": 0.2, "u_intensity": 2, "u_radius": 3 }
+ }
+ ]
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/bloom-ldr.textures.json b/desktop/public/scenes/bloom-ldr.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/bloom-ldr.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/hdr-bloom.esscene b/desktop/public/scenes/hdr-bloom.esscene
new file mode 100644
index 000000000..2470b322a
--- /dev/null
+++ b/desktop/public/scenes/hdr-bloom.esscene
@@ -0,0 +1,75 @@
+{
+ "version": "1.0",
+ "name": "HDR Bloom",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "LitQuad",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 120, "y": 120 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "HotGreenLight",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 0,
+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "intensity": 6,
+ "radius": 400
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "PostProcess",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ {
+ "type": "PostProcessVolume",
+ "data": {
+ "isGlobal": true,
+ "priority": 0,
+ "weight": 1,
+ "blendDistance": 0,
+ "shape": "box",
+ "size": { "x": 5, "y": 5 },
+ "effects": [
+ {
+ "type": "bloom",
+ "enabled": true,
+ "uniforms": { "u_threshold": 1.5, "u_intensity": 2, "u_radius": 3 }
+ }
+ ]
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/hdr-bloom.textures.json b/desktop/public/scenes/hdr-bloom.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/hdr-bloom.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/guides/lighting.mdx
index cfdbc2824..02289de5c 100644
--- a/docs/astro/src/content/docs/guides/lighting.mdx
+++ b/docs/astro/src/content/docs/guides/lighting.mdx
@@ -183,6 +183,11 @@ black, and overlapping lights add like light instead of paint. Unlit art round-t
unchanged — decode followed by encode is an identity — so switching does not repaint
your sprites; the difference shows wherever colors mix.
+Linear mode is also the door to **HDR**: where float render targets are available
+(WebGPU always; WebGL2 with `EXT_color_buffer_float`), the post-process chain runs in
+half-float, so a light with `intensity` above 1 pushes real over-range energy into
+[bloom and tonemap](/docs/guides/postprocess/) — bright lights glow.
+
Enable it in **Project Settings → Rendering → Color space → Linear**. Shaders compile
against the mode, so it is fixed at engine boot — the editor prompts for a reload. The
setting rides the project manifest: the viewport, Play, and every export — web, desktop,
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/guides/postprocess.mdx
index ceb4b0b46..27e289c34 100644
--- a/docs/astro/src/content/docs/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/guides/postprocess.mdx
@@ -34,6 +34,26 @@ so adding them changes nothing until you dial them in. A few are visible the mom
you add them — `grayscale` (full desaturation), `vignette`, `bloom`, `outline`, and
`tonemap` (the ACES curve always applies) — so enable those only when you want them.
+## HDR (linear color space)
+
+When the project renders in the **linear color space** (see
+[Lighting](/docs/guides/lighting/)), the effect chain runs in **half-float HDR**
+wherever float render targets are available — always on WebGPU, and on WebGL2 with
+the near-universal `EXT_color_buffer_float`. Light accumulation past `1.0` (a
+`Light2D` with `intensity` above 1) then *survives* into the chain instead of
+clamping at the 8-bit store:
+
+- **`bloom` with `threshold` above 1** blooms only over-range energy — bright
+ lights glow while ordinary LDR art stays crisp. This is the classic "emissive
+ glow" setup: crank a light's `intensity`, set `threshold` ≈ 1.2–1.5.
+- **`tonemap`** receives true HDR input, so the ACES curve rolls off highlights
+ instead of shaping already-clamped values.
+- Without a tonemap pass, over-range values simply clip at the final
+ linear→sRGB encode — fine for subtle glow, harsh for large over-exposure.
+
+In gamma mode (or without float-target support) the chain is LDR and behaves as
+before; a `threshold` above ~0.75 then never fires.
+
## Using a `PostProcessVolume`
Add a `PostProcessVolume`, enable effects, and set their parameters. Volumes
diff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
index 1a9cebfea..2f8b9137d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
@@ -175,6 +175,10 @@ cmds.spawn()
物理正确的混合改变的是光的*叠加方式*:衰减不再压向死黑,多盏灯的重叠像光一样相加而不是像颜料。
不受光的美术资源经解码再编码是恒等回环——切换不会"重画"你的精灵;差异只出现在颜色相互混合的地方。
+线性模式也是 **HDR** 的入口:只要浮点渲染目标可用(WebGPU 恒可用;WebGL2 有
+`EXT_color_buffer_float`),后处理链就跑在半浮点上——`intensity` 大于 1 的灯把真正的超范围
+能量推进 [bloom 与 tonemap](/docs/zh-cn/guides/postprocess/),亮光会发辉光。
+
在 **项目设置 → 渲染 → 色彩空间 → 线性** 启用。着色器按该模式编译,所以它在引擎启动时定死——
编辑器会提示重新加载。设置随项目清单走:视口、运行预览和所有导出——web、桌面、微信、playable——
启动同一条管线。纯代码项目在创建应用时传入:
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 d84f2194b..3211f3b92 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
@@ -31,6 +31,21 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
`lutGrade`),加进去不调参不改画面。少数一加就可见——`grayscale`(完全去色)、`vignette`、
`bloom`、`outline`、`tonemap`(ACES 曲线恒生效)——这些只在你需要时才启用。
+## HDR(线性色彩空间)
+
+当项目以**线性色彩空间**渲染时(见[光照](/docs/zh-cn/guides/lighting/)),只要浮点渲染目标
+可用——WebGPU 恒可用,WebGL2 上是几乎无处不在的 `EXT_color_buffer_float`——效果链就跑在
+**半浮点 HDR** 上。超过 `1.0` 的光照累积(`intensity` 大于 1 的 `Light2D`)会*存活*进效果链,
+而不是在 8 位存储处被压平:
+
+- **`threshold` 大于 1 的 `bloom`** 只让超范围能量泛光——亮光发辉光,普通 LDR 美术保持锐利。
+ 这就是经典的"自发光辉光"配方:拉高灯的 `intensity`,把 `threshold` 设在约 1.2–1.5。
+- **`tonemap`** 收到真正的 HDR 输入,ACES 曲线得以收卷高光,而不是对已压平的值做整形。
+- 不加 tonemap 时,超范围值在最终的线性→sRGB 编码处直接截断——轻微辉光没问题,大面积过曝会显得生硬。
+
+伽马模式(或无浮点目标能力)下效果链仍是 LDR,行为与从前一致;此时 `threshold` 超过约 0.75
+就永远不会触发。
+
## 使用 `PostProcessVolume`
加一个 `PostProcessVolume`,启用效果,设置参数。体积**在重叠处混合**,所以你可以按区域驱动
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 0f90208d9..f863c502e 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -65,7 +65,9 @@ registerEffect({
label: 'Bloom',
factory: () => postProcessEffects.createBloomExtract(),
uniforms: [
- { name: 'u_threshold', label: 'Threshold', min: 0, max: 1, step: 0.01, defaultValue: 0.4 },
+ // Threshold reaches past 1: under the linear pipeline's HDR intermediates
+ // only over-range energy (bright lights) blooms, leaving LDR art crisp.
+ { name: 'u_threshold', label: 'Threshold', min: 0, max: 2, step: 0.01, defaultValue: 0.4 },
{ name: 'u_intensity', label: 'Intensity', min: 0, max: 5, step: 0.1, defaultValue: 1.5 },
{ name: 'u_radius', label: 'Radius', min: 0.5, max: 5, step: 0.1, defaultValue: 1 },
],
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 578717e95..ee243166d 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -203,7 +203,7 @@ void main() {
const source = `#pragma shader "PP Bloom Extract"
#pragma version 300 es
#pragma domain PostProcess
-#pragma param u_threshold float default(0.4) range(0,1)
+#pragma param u_threshold float default(0.4) range(0,2)
#pragma fragment
precision highp float;
diff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cpp
index 5c589d0e0..961c6f196 100644
--- a/src/esengine/renderer/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/PostProcessPipeline.cpp
@@ -65,18 +65,32 @@ void PostProcessPipeline::init(u32 width, u32 height) {
initialized_ = true;
}
+GfxPixelFormat PostProcessPipeline::interFormat() const {
+ if (!linear_output_) return GfxPixelFormat::RGBA8;
+ // Linear mode is HDR when float targets are renderable: half-float
+ // intermediates let light accumulation exceed 1.0, so bloom's bright-pass
+ // and tonemap see real over-range energy instead of values crushed at the
+ // 8-bit store. Without the capability (WebGL2 sans EXT_color_buffer_float),
+ // sRGB-encoded 8-bit keeps the linear pipeline correct at LDR precision.
+ return device_.supportsFloatTargets() ? GfxPixelFormat::RGBA16F
+ : GfxPixelFormat::SRGB8_ALPHA8;
+}
+
void PostProcessPipeline::ensureFBOs() {
- // Linear mode stores intermediates sRGB-encoded: 8-bit precision stays
- // perceptually uniform while blending happens in linear light (hardware
- // EOTF/OETF at the attachment boundary).
- const GfxPixelFormat interFmt =
- linear_output_ ? GfxPixelFormat::SRGB8_ALPHA8 : GfxPixelFormat::RGBA8;
+ const GfxPixelFormat interFmt = interFormat();
if (!fboOriginalCreated_) {
FramebufferSpec origSpec;
origSpec.width = width_;
origSpec.height = height_;
origSpec.depthStencil = false;
origSpec.colorFormat = interFmt;
+ // Bilinear intermediates: fullscreen passes sample at texel centers
+ // (where LINEAR == NEAREST), but Kawase blur deliberately samples at
+ // half-texel offsets — with NEAREST those land ON texel boundaries,
+ // whose rounding is backend-dependent (GL vs Dawn diverged visibly).
+ // LINEAR makes the tap a well-defined 2x2 average — the actual Kawase
+ // algorithm — identical on every backend.
+ origSpec.linearFilter = true;
fboOriginal_ = Framebuffer::create(device_, origSpec);
if (!fboOriginal_) {
@@ -84,6 +98,11 @@ void PostProcessPipeline::ensureFBOs() {
return;
}
fboOriginalCreated_ = true;
+ if (linear_output_) {
+ ES_LOG_INFO("PostProcess intermediates: {}",
+ interFmt == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"
+ : "SRGB8_ALPHA8 (LDR linear)");
+ }
}
if (fbosCreated_) return;
@@ -93,6 +112,7 @@ void PostProcessPipeline::ensureFBOs() {
spec.height = height_;
spec.depthStencil = false;
spec.colorFormat = interFmt;
+ spec.linearFilter = true; // see origSpec above — the blur chain needs bilinear taps
fboA_ = Framebuffer::create(device_, spec);
fboB_ = Framebuffer::create(device_, spec);
@@ -519,10 +539,14 @@ void PostProcessPipeline::ensureScreenFBO() {
if (screenFBOCreated_) return;
FramebufferSpec spec;
- spec.colorFormat = linear_output_ ? GfxPixelFormat::SRGB8_ALPHA8 : GfxPixelFormat::RGBA8;
+ // The multi-camera composition surface carries scene values too — same
+ // format + filter story as the capture/ping-pong chain (HDR in
+ // linear+float mode; bilinear for the blur taps).
+ spec.colorFormat = interFormat();
spec.width = width_;
spec.height = height_;
spec.depthStencil = false;
+ spec.linearFilter = true;
screenFBO_ = Framebuffer::create(device_, spec);
if (!screenFBO_) {
diff --git a/src/esengine/renderer/PostProcessPipeline.hpp b/src/esengine/renderer/PostProcessPipeline.hpp
index 21fe6ef6f..d5c4b9d72 100644
--- a/src/esengine/renderer/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/PostProcessPipeline.hpp
@@ -254,6 +254,8 @@ public:
private:
PostProcessPass* findPass(const std::string& name);
+ /** Intermediate/capture attachment format for the active pipeline mode. */
+ GfxPixelFormat interFormat() const;
void ensureFBOs();
void ensureScreenQuad();
void drawScreenQuad();