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
feat(renderer): the post chain goes HDR under linear - bright lights bloom
yhhd8d21b2c8f25
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.mdxindex 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-tunchanged — decode followed by encode is an identity — so switching does not repaintyour 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 compileagainst the mode, so it is fixed at engine boot — the editor prompts for a reload. Thesetting 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.mdxindex 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 momyou 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. Volumesdiff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/guides/lighting.mdxindex 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.mdxindex 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.tsindex 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.tsindex 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 fragmentprecision highp float;diff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cppindex 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 tapsfboA_ = 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.hppindex 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();