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 frame has an output transform, and one definition of the curve
yhhf8883c7b98f0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 pinthrough `ESTELLA_VERIFY_COUNTERS`, and the new gate `mesh-cost` pins them: ninediff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 3b758892e..5536e1348 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2222,6 +2222,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefined@@ -5795,6 +5796,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => void@@ -8547,7 +8549,7 @@ duration: number | undefinedkeepPersistent: boolean | undefinedonComplete: (() => void) | undefinedonStart: (() => void) | undefined-transition: "fade" | "none" | undefined+transition: "none" | "fade" | undefined```## Tween — const @experimental@@ -9186,6 +9188,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c546e5f8c..b2e1ded91 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -2230,6 +2230,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefined@@ -5978,6 +5979,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => void@@ -8740,7 +8742,7 @@ duration: number | undefinedkeepPersistent: boolean | undefinedonComplete: (() => void) | undefinedonStart: (() => void) | undefined-transition: "fade" | "none" | undefined+transition: "none" | "fade" | undefined```## Tween — const @experimental@@ -9379,6 +9381,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex fb3e5a935..8ee2eff90 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2217,6 +2217,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefined@@ -5790,6 +5791,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => void@@ -8542,7 +8544,7 @@ duration: number | undefinedkeepPersistent: boolean | undefinedonComplete: (() => void) | undefinedonStart: (() => void) | undefined-transition: "fade" | "none" | undefined+transition: "none" | "fade" | undefined```## Tween — const @experimental@@ -9181,6 +9183,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d62e6ad19..542fc04f4 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -2217,6 +2217,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefined@@ -6035,6 +6036,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => void@@ -8787,7 +8789,7 @@ duration: number | undefinedkeepPersistent: boolean | undefinedonComplete: (() => void) | undefinedonStart: (() => void) | undefined-transition: "fade" | "none" | undefined+transition: "none" | "fade" | undefined```## Tween — const @experimental@@ -9432,6 +9434,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => booleanpostprocess_isInitialized: () => booleanpostprocess_resize: (width: number, height: number) => voidpostprocess_setBypass: (bypass: boolean) => void+postprocess_setOutputTransform: ((transform: number) => void) | undefinedpostprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => voidpostprocess_setPassTexture: (passName: string, uniform: string, textureHandle: number) => voidpostprocess_setScreenUniformFloat: (passName: string, uniform: string, value: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex e30a5c271..4c083707c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2217,6 +2217,7 @@ world: WorldcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefined@@ -5797,6 +5798,7 @@ isInitialized: () => booleanresize: (width: number, height: number) => voidscreenStack: PostProcessStack | nullsetBypass: (bypass: boolean) => void+setOutputTransform: (transform: OutputTransform) => voidsetOutputViewport: (x: number, y: number, w: number, h: number) => voidsetScreenStack: (stack: PostProcessStack | null) => voidshutdown: () => void@@ -8549,7 +8551,7 @@ duration: number | undefinedkeepPersistent: boolean | undefinedonComplete: (() => void) | undefinedonStart: (() => void) | undefined-transition: "fade" | "none" | undefined+transition: "none" | "fade" | undefined```## Tween — const @experimental@@ -9208,6 +9210,7 @@ static prototype: WeChatSocketcolorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined+outputTransform: OutputTransform | undefinedplugins: Plugin[] | undefinedrandomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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, rescoimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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.hppindex 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.cppindex 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.esshaderindex 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_LINEARreturn vec4f(linearToSrgb(c.rgb), c.a);#elsediff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 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: thediff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 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.hppindex 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_LINEARreturn vec4f(linearToSrgb(c.rgb), c.a);#elsediff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 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.tsindex 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.mjsindex 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.mjsindex 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}]" } },