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 frame has an output transform, and one definition of the curve

yhhf8883c7b98f0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41fb99798..59c7f6db8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,35 @@ published separately; it ships inside the editor.
### Added
+- **A frame has an output transform, and it belongs to the pipeline.**
+ `PostProcess.setOutputTransform('aces')` — or `outputTransform` in a project's
+ `createWebApp` options — puts the ACES filmic curve on the way out: once, last,
+ after the effects (which want scene values) and before the OETF (which is a
+ transfer function, not a look). It rides in the blit that was always going to
+ run, so it costs no extra full-screen pass, and it engages the capture on its
+ own — a project that asks for a curve gets one with an empty effect stack.
+
+ **ACES now has one definition.** `acesFilmic()` joins `srgbToLinear` /
+ `linearToSrgb` in the helpers every fragment stage is given, in GLSL and in
+ WGSL, and the standalone `tonemap` post effect calls it instead of carrying its
+ own copy of the constants. Two spellings of one curve was one edit from two
+ different curves. The effect stays: it is the manual placement, with an
+ exposure. Carry that OR the output transform, never both — the curve is not
+ idempotent.
+
+ **The default is `none`, and that is a decision, not caution.** The obvious rule
+ — tonemap whenever the pipeline is linear — is wrong, and the suite already
+ says why: `linear-midtone` exists to prove 0.502 sRGB survives the linear round
+ trip and comes back 128. A standing filmic curve destroys exactly that. Linear
+ light is not the same claim as HDR scene radiance, and flat content wants the
+ round trip.
+
+ Measured on that one scene, all four values hand-derived: no transform reads
+ 128, ACES in gamma reads 157, ACES in linear reads 154 (0.502 → 0.2158 linear →
+ 0.3242 through the curve → encoded), and applying it twice would read 182. Gates
+ `output-aces` and `output-aces-linear`, both backends, agreeing to the value —
+ which is also what says the WGSL twin of the curve is the same curve.
+
- **The 3D path can be held to what it COST, not just to what it drew.**
`render.meshes` and `render.triangles` join the counters a pixel gate can pin
through `ESTELLA_VERIFY_COUNTERS`, and the new gate `mesh-cost` pins them: nine
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3b758892e..5536e1348 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2222,6 +2222,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
@@ -5795,6 +5796,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
@@ -8547,7 +8549,7 @@ duration: number | undefined
keepPersistent: boolean | undefined
onComplete: (() => void) | undefined
onStart: (() => void) | undefined
-transition: "fade" | "none" | undefined
+transition: "none" | "fade" | undefined
```
## Tween — const @experimental
@@ -9186,6 +9188,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c546e5f8c..b2e1ded91 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2230,6 +2230,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
@@ -5978,6 +5979,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
@@ -8740,7 +8742,7 @@ duration: number | undefined
keepPersistent: boolean | undefined
onComplete: (() => void) | undefined
onStart: (() => void) | undefined
-transition: "fade" | "none" | undefined
+transition: "none" | "fade" | undefined
```
## Tween — const @experimental
@@ -9379,6 +9381,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index fb3e5a935..8ee2eff90 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2217,6 +2217,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
@@ -5790,6 +5791,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
@@ -8542,7 +8544,7 @@ duration: number | undefined
keepPersistent: boolean | undefined
onComplete: (() => void) | undefined
onStart: (() => void) | undefined
-transition: "fade" | "none" | undefined
+transition: "none" | "fade" | undefined
```
## Tween — const @experimental
@@ -9181,6 +9183,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d62e6ad19..542fc04f4 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2217,6 +2217,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
@@ -6035,6 +6036,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
@@ -8787,7 +8789,7 @@ duration: number | undefined
keepPersistent: boolean | undefined
onComplete: (() => void) | undefined
onStart: (() => void) | undefined
-transition: "fade" | "none" | undefined
+transition: "none" | "fade" | undefined
```
## Tween — const @experimental
@@ -9432,6 +9434,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 5554ff669..97ac62291 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -323,6 +323,7 @@ postprocess_init: (width: number, height: number) => boolean
postprocess_isInitialized: () => boolean
postprocess_resize: (width: number, height: number) => void
postprocess_setBypass: (bypass: boolean) => void
+postprocess_setOutputTransform: ((transform: number) => void) | undefined
postprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => void
postprocess_setPassTexture: (passName: string, uniform: string, textureHandle: number) => void
postprocess_setScreenUniformFloat: (passName: string, uniform: string, value: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e30a5c271..4c083707c 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2217,6 +2217,7 @@ world: World
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
@@ -5797,6 +5798,7 @@ isInitialized: () => boolean
resize: (width: number, height: number) => void
screenStack: PostProcessStack | null
setBypass: (bypass: boolean) => void
+setOutputTransform: (transform: OutputTransform) => void
setOutputViewport: (x: number, y: number, w: number, h: number) => void
setScreenStack: (stack: PostProcessStack | null) => void
shutdown: () => void
@@ -8549,7 +8551,7 @@ duration: number | undefined
keepPersistent: boolean | undefined
onComplete: (() => void) | undefined
onStart: (() => void) | undefined
-transition: "fade" | "none" | undefined
+transition: "none" | "fade" | undefined
```
## Tween — const @experimental
@@ -9208,6 +9210,7 @@ static prototype: WeChatSocket
colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
+outputTransform: OutputTransform | undefined
plugins: Plugin[] | undefined
randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 0514707a8..88d4acedd 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -10,6 +10,7 @@ import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, resco
import { ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';
import { EventRegistry, type EventDef } from '../ecs/event';
import type { ESEngineModule, CppRegistry } from '../wasm';
+import type { OutputTransform } from '../postprocess/PostProcessAPI';
import type { BridgeConnectOptions } from '../ecs/bridge/BuiltinBridge';
import { UICameraInfo } from '../ui/core/ui-camera-info';
import { inputPlugin, Input } from '../input/input';
@@ -1423,6 +1424,13 @@ export interface WebAppOptions {
* Must be declared at app creation — shaders compile against it.
*/
colorSpace?: 'gamma' | 'linear';
+ /**
+ * The curve the frame applies on its way to the display, once and last. `aces`
+ * engages the capture the way an effect does, so a scene that asks for one goes
+ * through the graph even with an empty stack. Declared by the host for now — it
+ * is not yet a field of the project manifest. See {@link OutputTransform}.
+ */
+ outputTransform?: OutputTransform;
/**
* Seed the engine's randomness so this run reproduces — a replay, a bug
* report, a pixel assertion. Absent, every run differs, which is what a
@@ -1486,6 +1494,10 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
// reloads, so a fresh App must reset a prior session's y-sort state too.
module.renderer_setYSortLayers?.((options?.ySortLayers ?? 0) >>> 0);
module.renderer_setDepthLayers?.((options?.depthLayers ?? 0) >>> 0);
+ // After the renderer, not with the colour space above it: the post-process
+ // pipeline is created by the renderer, and a curve declared before it exists
+ // reaches nothing.
+ module.postprocess_setOutputTransform?.(options?.outputTransform === 'aces' ? 1 : 0);
app.addPlugin(corePlugin);
app.setPipeline(new RenderPipeline());
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 849127695..f4430f74e 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -93,6 +93,7 @@ export interface NativeEngineApi {
postprocess_isInitialized?(): boolean;
postprocess_resize?(width: number, height: number): void;
postprocess_setBypass?(bypass: boolean): void;
+ postprocess_setOutputTransform?(transform: number): void;
postprocess_setOutputViewport?(x: number, y: number, w: number, h: number): void;
postprocess_setPassTexture?(passName: string, uniform: string, textureHandle: number): void;
postprocess_setScreenUniformFloat?(passName: string, uniform: string, value: number): void;
@@ -318,6 +319,7 @@ export function createNativeEngineApi(
bind('postprocess_isInitialized', 'es_postprocess_isInitialized', false);
bind('postprocess_resize', 'es_postprocess_resize', false);
bind('postprocess_setBypass', 'es_postprocess_setBypass', false);
+ bind('postprocess_setOutputTransform', 'es_postprocess_setOutputTransform', false);
bind('postprocess_setOutputViewport', 'es_postprocess_setOutputViewport', false);
bind('postprocess_setPassTexture', 'es_postprocess_setPassTexture', false);
bind('postprocess_setScreenUniformFloat', 'es_postprocess_setScreenUniformFloat', false);
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index 1ba3c2428..ca359771e 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -18,7 +18,8 @@ type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
| 'postprocess_isInitialized' | 'postprocess_begin' | 'postprocess_end'
| 'postprocess_clearPasses' | 'postprocess_addPass' | 'postprocess_setPassTexture'
| 'postprocess_setUniformFloat' | 'postprocess_setUniformVec4'
- | 'postprocess_setBypass' | 'postprocess_setOutputViewport'
+ | 'postprocess_setBypass' | 'postprocess_setOutputTransform'
+ | 'postprocess_setOutputViewport'
| 'postprocess_beginScreenCapture' | 'postprocess_endScreenCapture'
| 'postprocess_executeScreenPasses' | 'postprocess_addScreenPass'
| 'postprocess_clearScreenPasses' | 'postprocess_setScreenUniformFloat'
@@ -128,6 +129,16 @@ export function syncStackToWasm(stack: PostProcessStack, force = false): void {
* B2b-3a: a single default instance is exported to keep call sites unchanged;
* B2b-3b flips this to a per-App `defineResource` injected into the pipeline.
*/
+/**
+ * The curve a frame applies on its way to the display — the pipeline's, not an
+ * effect a stack happens to hold, so it runs once and last. `none` leaves values
+ * alone, which is the exact round trip flat content wants; `aces` maps radiance
+ * above 1 down a filmic shoulder, which is what a lit 3D scene needs.
+ *
+ * @public
+ */
+export type OutputTransform = 'none' | 'aces';
+
export class PostProcessAPI {
readonly state = new PostProcessState();
@@ -217,6 +228,21 @@ export class PostProcessAPI {
}
}
+ /**
+ * The curve the frame applies on its way to the display.
+ *
+ * Applied to whatever the chain produced, so it also engages the capture: a
+ * project that asks for a curve gets one with an empty stack. See
+ * {@link OutputTransform} for which to want.
+ */
+ setOutputTransform(transform: OutputTransform): void {
+ try {
+ getModule().postprocess_setOutputTransform(transform === 'aces' ? 1 : 0);
+ } catch (e) {
+ handleWasmError(e, 'PostProcess.setOutputTransform');
+ }
+ }
+
begin(): void {
try {
getModule().postprocess_begin();
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 7f41e19b0..81160080c 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -418,10 +418,9 @@ void main() {
},
createTonemap(): ShaderHandle {
- // ACES filmic curve (Narkowicz approximation) — maps HDR/linear scene
- // radiance into a display range with a filmic shoulder/toe. Unlike the
- // grade/blur effects this always reshapes the curve (that is the point of
- // tonemapping); only the exposure pre-multiply is identity at its default.
+ // The manual tonemap: the same acesFilmic() every fragment stage is given,
+ // at a point of the stack's choosing and with an exposure. Carry this OR
+ // PostProcess.setOutputTransform — the curve is not idempotent.
const source = `#pragma shader "PP Tonemap"
#pragma version 300 es
#pragma domain PostProcess
@@ -434,36 +433,18 @@ in vec2 v_texCoord;
uniform sampler2D u_texture;
out vec4 fragColor;
-vec3 aces(vec3 x) {
- const float a = 2.51;
- const float b = 0.03;
- const float c = 2.43;
- const float d = 0.59;
- const float e = 0.14;
- return clamp((x * (a * x + b)) / (x * (c * x + d) + e), 0.0, 1.0);
-}
-
void main() {
vec4 src = texture(u_texture, v_texCoord);
vec3 c = src.rgb * exp2(u_exposure);
- fragColor = vec4(aces(c), src.a);
+ fragColor = vec4(acesFilmic(c), src.a);
}
#pragma end
#pragma fragment wgsl
-fn aces(x : vec3f) -> vec3f {
- let a = 2.51;
- let b = 0.03;
- let c = 2.43;
- let d = 0.59;
- let e = 0.14;
- return clamp((x * (a * x + b)) / (x * (c * x + d) + e), vec3f(0.0), vec3f(1.0));
-}
-
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
let src = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
let c = src.rgb * exp2(mc.u_exposure);
- return vec4f(aces(c), src.a);
+ return vec4f(acesFilmic(c), src.a);
}
#pragma end
`;
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 8dd801261..4871fcabe 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -383,6 +383,9 @@ export interface ESEngineModule {
postprocess_end(): void;
postprocess_isInitialized(): boolean;
postprocess_setBypass(bypass: boolean): void;
+ /** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic.
+ * Absent on an engine built before the output transform existed. */
+ postprocess_setOutputTransform?(transform: number): void;
postprocess_clearPasses(): void;
postprocess_setOutputViewport(x: number, y: number, w: number, h: number): void;
postprocess_beginScreenCapture(): void;
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index 486b3324e..7d234540a 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -117,6 +117,14 @@ void postprocess_setBypass(bool bypass) {
}
}
+void postprocess_setOutputTransform(u32 transform) {
+ if (!g_postProcessPipeline) return;
+ // An unknown value is the identity, not a guess: a project built against a
+ // newer curve list must not get a different one silently.
+ g_postProcessPipeline->setOutputTransform(transform == 1 ? OutputTransform::ACES
+ : OutputTransform::None);
+}
+
void postprocess_clearPasses() {
if (g_postProcessPipeline) {
g_postProcessPipeline->clearPasses();
diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hpp
index c2b7e141f..12bf27075 100644
--- a/src/esengine/bindings/PostProcessBindings.hpp
+++ b/src/esengine/bindings/PostProcessBindings.hpp
@@ -23,6 +23,8 @@ void postprocess_begin();
void postprocess_end();
bool postprocess_isInitialized();
void postprocess_setBypass(bool bypass);
+/** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic. */
+void postprocess_setOutputTransform(u32 transform);
void postprocess_clearPasses();
void postprocess_setOutputViewport(u32 x, u32 y, u32 w, u32 h);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 3da872a2c..f90bcb2b8 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -570,6 +570,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("postprocess_end", &esengine::postprocess_end);
emscripten::function("postprocess_isInitialized", &esengine::postprocess_isInitialized);
emscripten::function("postprocess_setBypass", &esengine::postprocess_setBypass);
+ emscripten::function("postprocess_setOutputTransform", &esengine::postprocess_setOutputTransform);
emscripten::function("postprocess_clearPasses", &esengine::postprocess_clearPasses);
emscripten::function("postprocess_setOutputViewport", &esengine::postprocess_setOutputViewport);
emscripten::function("postprocess_beginScreenCapture", &esengine::postprocess_beginScreenCapture);
diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshader
index a218823e5..a26355d87 100644
--- a/src/esengine/data/shaders/blit.esshader
+++ b/src/esengine/data/shaders/blit.esshader
@@ -11,6 +11,12 @@ out vec4 fragColor;
void main() {
vec4 c = texture(u_texture, v_texCoord);
+#ifdef ES_TONEMAP
+ // The output transform: scene radiance can exceed 1.0 on an HDR target,
+ // and this is the one place a chain maps it down. Before the OETF, which
+ // is a transfer function and not a look.
+ c = vec4(acesFilmic(c.rgb), c.a);
+#endif
#ifdef ES_LINEAR
// The one mandatory OETF: the chain upstream is linear (sRGB attachments
// decode on sample), the canvas backbuffer is plain UNORM.
@@ -23,7 +29,10 @@ void main() {
#pragma fragment wgsl
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
- let c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+ var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+#ifdef ES_TONEMAP
+ c = vec4f(acesFilmic(c.rgb), c.a);
+#endif
#ifdef ES_LINEAR
return vec4f(linearToSrgb(c.rgb), c.a);
#else
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 21e37ddf9..4a01bd99e 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -47,16 +47,7 @@ void PostProcessPipeline::init(u32 width, u32 height) {
width_ = width;
height_ = height;
- // The pass-through copy, authored as blit.esshader (WGSL twin included).
- // No loose non-sampler uniforms, so the DrawParams rewrite has nothing to
- // lift; u_texture seeds via setUniform (GLSL-only, guarded there).
- const auto target = resourceManager_.preferredShaderTarget();
- auto parsed = resource::ShaderParser::parse(ShaderEmbeds::BLIT);
- blitShader_ = resourceManager_.createShader(
- resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", {}, target),
- resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", {}, target),
- /*rewriteLoose=*/false,
- resourceManager_.preferredShaderLanguage());
+ blitShader_ = compileBlit({});
if (!blitShader_.isValid()) {
ES_LOG_ERROR("PostProcessPipeline: Failed to create blit shader");
return;
@@ -65,6 +56,39 @@ void PostProcessPipeline::init(u32 width, u32 height) {
initialized_ = true;
}
+/**
+ * A variant of blit.esshader, which is the chain's last pass in every mode.
+ *
+ * No loose non-sampler uniforms, so the DrawParams rewrite has nothing to lift;
+ * u_texture seeds via setUniform (GLSL-only, guarded there). ES_LINEAR is not
+ * passed here — the parser adds it from the process-global colour space.
+ */
+resource::ShaderHandle PostProcessPipeline::compileBlit(const std::vector<std::string>& features) {
+ const auto target = resourceManager_.preferredShaderTarget();
+ auto parsed = resource::ShaderParser::parse(ShaderEmbeds::BLIT);
+ return resourceManager_.createShader(
+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features, target),
+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features, target),
+ /*rewriteLoose=*/false,
+ resourceManager_.preferredShaderLanguage());
+}
+
+/**
+ * The blit the current output transform needs. Compiled on first use rather
+ * than at init: a project that never asks for a curve never pays for one.
+ */
+resource::ShaderHandle PostProcessPipeline::outputShader() {
+ if (output_transform_ != OutputTransform::ACES) return blitShader_;
+ if (!tonemapShader_.isValid()) {
+ tonemapShader_ = compileBlit({"ES_TONEMAP"});
+ if (!tonemapShader_.isValid()) {
+ ES_LOG_ERROR("PostProcessPipeline: no ES_TONEMAP blit; output stays untonemapped");
+ return blitShader_;
+ }
+ }
+ return tonemapShader_;
+}
+
GfxPixelFormat PostProcessPipeline::interFormat() const {
if (!linear_output_) return GfxPixelFormat::RGBA8;
// Linear mode is HDR when float targets are renderable: half-float
@@ -129,6 +153,10 @@ void PostProcessPipeline::shutdown() {
if (blitShader_.isValid()) {
resourceManager_.releaseShader(blitShader_);
}
+ if (tonemapShader_.isValid()) {
+ resourceManager_.releaseShader(tonemapShader_);
+ tonemapShader_ = resource::ShaderHandle{};
+ }
initialized_ = false;
ES_LOG_INFO("PostProcessPipeline shutdown");
@@ -286,7 +314,7 @@ FramebufferHandle PostProcessPipeline::currentSceneFBO() const {
}
void PostProcessPipeline::begin(const f32* clearColor) {
- if (!initialized_ || inFrame_ || (bypass_ && !linear_output_)) return;
+ if (!isEngaged() || inFrame_) return;
ensureGraph();
if (!graph_) return;
@@ -320,7 +348,9 @@ void PostProcessPipeline::begin(const f32* clearColor) {
}
void PostProcessPipeline::end() {
- if (!initialized_ || !inFrame_ || (bypass_ && !linear_output_)) return;
+ // Gated on inFrame_ alone, not on isEngaged(): whatever begin() opened has
+ // to be resolved even if the answer changed underneath in between.
+ if (!initialized_ || !inFrame_) return;
auto* device = &device_;
@@ -447,7 +477,7 @@ void PostProcessPipeline::setOutputViewport(u32 x, u32 y, u32 w, u32 h) {
}
void PostProcessPipeline::blitPass() {
- Shader* shader = resourceManager_.getShader(blitShader_);
+ Shader* shader = resourceManager_.getShader(outputShader());
if (!shader) return;
// The output rect is the one thing a pass does not get from its target: the
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index 2325b501d..a5d031a23 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -33,6 +33,19 @@ namespace resource {
class ResourceManager;
}
+/**
+ * @brief What the last pass of a chain does to scene values on the way out.
+ *
+ * @details A tonemap is the OUTPUT transform, not an effect: it runs exactly once
+ * and last — after the effects, which want scene values, and before the
+ * OETF, which is a transfer function. `None` by default: a flat frame in
+ * linear light wants an exact round trip, and a filmic curve is not one.
+ */
+enum class OutputTransform : u8 {
+ None = 0, ///< Encode only. Values above 1 clip, which is what LDR content means.
+ ACES = 1, ///< Narkowicz ACES filmic curve, for a scene that carries HDR radiance.
+};
+
/**
* @brief Post-processing pass configuration
*/
@@ -155,13 +168,15 @@ public:
/**
* @brief Whether the scene goes through the graph or straight to the surface.
*
- * @details Two things engage it: effects to run, or the linear pipeline, whose
+ * @details Three things engage it: effects to run, the linear pipeline (whose
* final pass carries an encode a WebGL2 canvas framebuffer cannot do
- * for itself. One predicate because RenderFrame asked at both ends of
- * the frame, and two copies is one edit from a capture never resolved.
+ * for itself), or an output transform. One predicate because everyone
+ * asks at both ends of a frame, and two copies of it is one edit away
+ * from a capture that is opened and never resolved.
*/
bool isEngaged() const {
- return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_);
+ return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_
+ || output_transform_ != OutputTransform::None);
}
/**
@@ -189,6 +204,16 @@ public:
void setSceneNeedsDepth(bool needs) { scene_needs_depth_ = needs; }
bool linearOutput() const { return linear_output_; }
+ /**
+ * @brief The curve the final pass applies to scene values.
+ *
+ * @details Costs nothing when the chain is already engaged — the blit was
+ * always going to run — so this is a variant of that shader rather
+ * than a pass of its own.
+ */
+ void setOutputTransform(OutputTransform transform) { output_transform_ = transform; }
+ OutputTransform outputTransform() const { return output_transform_; }
+
/**
* @brief Checks if bypass mode is enabled
*/
@@ -274,8 +299,13 @@ private:
/// Declares one chain onto an already-begun graph and runs it, ending in the
/// output target. @p scene is the resource the first effect reads.
void runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene);
- /// The chain's last pass: the copy into the output target's viewport.
+ /// The chain's last pass: the output transform, then the copy into the
+ /// output target's viewport.
void blitPass();
+ /// The blit variant the current output transform needs, compiled on demand.
+ resource::ShaderHandle outputShader();
+ /// One variant of blit.esshader, by feature.
+ resource::ShaderHandle compileBlit(const std::vector<std::string>& features);
/// Frees a pass's GPU-side param UBO (clearPasses/shutdown).
void releasePassResources(PostProcessPass& pass);
@@ -287,6 +317,8 @@ private:
VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;
BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;
resource::ShaderHandle blitShader_;
+ /// The ES_TONEMAP variant of the same file. Invalid until a chain asks for it.
+ resource::ShaderHandle tonemapShader_;
std::vector<PostProcessPass> passes_;
u32 width_ = 0;
@@ -296,6 +328,7 @@ private:
bool bypass_ = false;
bool linear_output_ = false;
bool scene_needs_depth_ = false;
+ OutputTransform output_transform_ = OutputTransform::None;
/// The graph resource the scene is drawn into, live between begin() and end().
rg::ResourceId sceneResource_ = rg::kNoResource;
TextureHandle sceneTexture_ = TextureHandle::Invalid;
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 70af399a1..15c65d1a1 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -242,6 +242,12 @@ out vec4 fragColor;
void main() {
vec4 c = texture(u_texture, v_texCoord);
+#ifdef ES_TONEMAP
+ // The output transform: scene radiance can exceed 1.0 on an HDR target,
+ // and this is the one place a chain maps it down. Before the OETF, which
+ // is a transfer function and not a look.
+ c = vec4(acesFilmic(c.rgb), c.a);
+#endif
#ifdef ES_LINEAR
// The one mandatory OETF: the chain upstream is linear (sRGB attachments
// decode on sample), the canvas backbuffer is plain UNORM.
@@ -254,7 +260,10 @@ void main() {
#pragma fragment wgsl
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
- let c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+ var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);
+#ifdef ES_TONEMAP
+ c = vec4f(acesFilmic(c.rgb), c.a);
+#endif
#ifdef ES_LINEAR
return vec4f(linearToSrgb(c.rgb), c.a);
#else
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index aa4b5886d..b1ca6a917 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -805,6 +805,9 @@ const char* kColorHelpersWGSL = R"(fn srgbToLinear(c : vec3f) -> vec3f {
fn linearToSrgb(c : vec3f) -> vec3f {
return mix(c * 12.92, 1.055 * pow(c, vec3f(1.0 / 2.4)) - 0.055, step(vec3f(0.0031308), c));
}
+fn acesFilmic(x : vec3f) -> vec3f {
+ return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3f(0.0), vec3f(1.0));
+}
)";
const char* kLitHeaderWGSL = R"(struct Light { posDir : vec4f, color : vec4f, spot : vec4f, shadow : vec4f, shadowMap : vec4f };
@@ -1421,6 +1424,12 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
"}\n"
"highp vec3 linearToSrgb(highp vec3 c) {\n"
" return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, c));\n"
+ "}\n"
+ // The display curve, one definition for every stage that needs it:
+ // Narkowicz ACES. A tonemap is the OUTPUT transform, so a chain that
+ // carries one applies it once, in the pass that also encodes.
+ "highp vec3 acesFilmic(highp vec3 x) {\n"
+ " return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), 0.0, 1.0);\n"
"}\n";
assembled << kColorHelpers;
headerLines += countNewlines(kColorHelpers);
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 446eb2e20..413f36008 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -37,6 +37,7 @@ const width = Number(params.get('w')) || 1280;
const height = Number(params.get('h')) || 720;
const backend = params.get('backend') === 'webgpu' ? 'webgpu' : 'webgl2';
const colorSpace = params.get('colorSpace') === 'linear' ? 'linear' : undefined;
+const outputTransform = params.get('outputTransform') === 'aces' ? 'aces' : undefined;
const seedParam = params.get('seed');
const randomSeed = seedParam !== null && Number.isFinite(Number(seedParam)) ? Number(seedParam) : undefined;
const depthLayers = Number(params.get('depthLayers')) || undefined;
@@ -123,6 +124,7 @@ async function boot(): Promise<void> {
app = createWebApp(module, {
renderSurface,
colorSpace,
+ outputTransform,
randomSeed,
depthLayers,
getViewportSize: () => ({ width: canvas!.width, height: canvas!.height }),
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index d53b47a6c..97de06282 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -25,6 +25,7 @@
* ESTELLA_VERIFY_PICK hit-test a viewport point, asserting the entity (JSON)
* ESTELLA_VERIFY_ORBIT turn the editor eye before capture ("yaw,pitch" degrees)
* ESTELLA_VERIFY_COUNTERS engine counters the drawn frame must report (JSON)
+ * ESTELLA_VERIFY_OUTPUT_TRANSFORM the frame's output curve ("aces")
* ESTELLA_VERIFY_TIMEOUT_MS how long this run may take before it reports one
*/
import { app, BrowserWindow } from 'electron';
@@ -71,6 +72,9 @@ const BACKEND = process.env.ESTELLA_VERIFY_BACKEND === 'webgpu' ? 'webgpu' : 'we
// ESTELLA_VERIFY_COLORSPACE=linear boots the linear-light pipeline (sRGB decode
// + linear blending + final OETF) — point expectations must be linear-derived.
const COLORSPACE = process.env.ESTELLA_VERIFY_COLORSPACE === 'linear' ? 'linear' : '';
+// ESTELLA_VERIFY_OUTPUT_TRANSFORM=aces boots the project output transform, which
+// is a curve on the way out and engages the capture on its own.
+const OUTPUT_TRANSFORM = process.env.ESTELLA_VERIFY_OUTPUT_TRANSFORM === 'aces' ? 'aces' : '';
// A scene whose emitters roll dice has no constant to assert until the run is
// seeded; the engine seeds itself from the clock when nobody says otherwise.
const SEED = process.env.ESTELLA_VERIFY_SEED ?? '';
@@ -170,7 +174,7 @@ app.whenReady().then(async () => {
let server;
try {
server = await serveHost(DIST);
- const url = `http://127.0.0.1:${server.address().port}/${PAGE}?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}${SEED ? `&seed=${SEED}` : ''}`;
+ const url = `http://127.0.0.1:${server.address().port}/${PAGE}?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${OUTPUT_TRANSFORM ? `&outputTransform=${OUTPUT_TRANSFORM}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}${SEED ? `&seed=${SEED}` : ''}`;
// useContentSize: the capture rectangle must be the page area, not the
// outer frame (the same trap the parity runner documents).
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index e7c08a2c9..4dafb7721 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -201,6 +201,14 @@ export const SCENES = [
// Linear-light pipeline (colorSpace: 'linear'). The lit falloff moves 52 to 125 (perceptually-uniform light); the mid-gray texture must ROUND-TRIP exactly (sRGB store → hw decode → blit encode = identity) — a missing sRGB upload variant would read ~187, so tol 6 is a hard discriminator.
{ id: "linear-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-point.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-point.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,254,0],\"tol\":25},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,125,0],\"tol\":25}]" } },
{ id: "linear-midtone", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_SCENE: "/scenes/srgb-midtone.esscene", 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}]" } },
+ // The output transform on the scene whose whole subject is one known value:
+ // 0.502 sRGB in, 157 out, with the capture engaged by the curve alone — no
+ // effects, no linear mode. Hand-derived, so a wrong shoulder is a wrong number.
+ { id: "output-aces", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/srgb-midtone.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/srgb-midtone.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_OUTPUT_TRANSFORM: "aces", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[157,157,157],\"tol\":4}]" } },
+ // The same curve in linear light: 0.502 decodes to 0.2158, ACES maps it to
+ // 0.3242, the OETF encodes that to 154. Applied ONCE — twice would read 182,
+ // and linear-midtone beside this one reads 128 with no transform at all.
+ { id: "output-aces-linear", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/srgb-midtone.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/srgb-midtone.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_OUTPUT_TRANSFORM: "aces", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[154,154,154],\"tol\":4}]" } },
// 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.
{ id: "bloom-ldr", tier: "pr", webgpu: true, env: { 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}]" } },
{ id: "hdr-bloom", tier: "pr", webgpu: true, env: { 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}]" } },