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(postfx): the intermediate format is a decision the frame commits to
esengine2e0a8d0039af
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 76f73681d..9c7fcf30e 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -29,7 +29,7 @@ env:test_registry_ondestroy test_view_api_matrixtest_shader_device test_draw_params test_texture_fb test_buffer_devicetest_compressed_format test_batch_builder test_boundary_span test_webgpu_device- test_clip_depth test_shadow_atlas test_particle_shapes test_lod_selection+ test_clip_depth test_shadow_atlas test_particle_shapes test_lod_selection test_hdr_formattest_text_edit test_render_graph test_device_loss test_physics_interpolationtest_bitmap_font test_texture_cache test_aot_host test_aot_conformancetest_frame_lifecyclediff --git a/desktop b/desktopindex 7a258faa0..c18a973dc 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 7a258faa0d65dd625cfca3e1c4ac5986dc4d4eae+Subproject commit c18a973dcae3b99c3d044e4202332bc0ecbce87adiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 1e754c0b8..b02d437c8 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 113,"beta": 91,- "experimental": 1801,+ "experimental": 1802,"deprecated": 3},- "total": 2005,+ "total": 2006,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c232324ba..92276c7f2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1637 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1638 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3851,6 +3851,15 @@ static new (opts: GridLayoutOptions): GridLayoutProviderstatic prototype: GridLayoutProvider```+## HdrFormat — interface @experimental+```+effective: string+fellBack: boolean+linear: boolean+reason: string+requested: string+```+## HeadlessAppOptions — interface @experimental```plugins: Plugin[] | undefined@@ -6283,6 +6292,7 @@ bind: (camera: Entity, stack: PostProcessStack) => voidcreateStack: () => PostProcessStackend: () => voidgetStack: (camera: Entity) => PostProcessStack | null+hdrFormat: () => HdrFormat | nullinit: (width: number, height: number) => booleanisInitialized: () => booleanmsaaCapability: () => { effective: number; max: number; }diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 0f9f8fd46..34bd72241 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 89 beta · 1656 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1657 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3859,6 +3859,15 @@ static new (opts: GridLayoutOptions): GridLayoutProviderstatic prototype: GridLayoutProvider```+## HdrFormat — interface @experimental+```+effective: string+fellBack: boolean+linear: boolean+reason: string+requested: string+```+## HeadlessAppOptions — interface @experimental```plugins: Plugin[] | undefined@@ -6466,6 +6475,7 @@ bind: (camera: Entity, stack: PostProcessStack) => voidcreateStack: () => PostProcessStackend: () => voidgetStack: (camera: Entity) => PostProcessStack | null+hdrFormat: () => HdrFormat | nullinit: (width: number, height: number) => booleanisInitialized: () => booleanmsaaCapability: () => { effective: number; max: number; }diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex b93400cf5..e69a4aa7c 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 86 beta · 1636 experimental · 3 deprecated+Symbols: 113 public · 86 beta · 1637 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3846,6 +3846,15 @@ static new (opts: GridLayoutOptions): GridLayoutProviderstatic prototype: GridLayoutProvider```+## HdrFormat — interface @experimental+```+effective: string+fellBack: boolean+linear: boolean+reason: string+requested: string+```+## HeadlessAppOptions — interface @experimental```plugins: Plugin[] | undefined@@ -6278,6 +6287,7 @@ bind: (camera: Entity, stack: PostProcessStack) => voidcreateStack: () => PostProcessStackend: () => voidgetStack: (camera: Entity) => PostProcessStack | null+hdrFormat: () => HdrFormat | nullinit: (width: number, height: number) => booleanisInitialized: () => booleanmsaaCapability: () => { effective: number; max: number; }diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d1b491564..eb9e69ed3 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1658 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1659 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3846,6 +3846,15 @@ static new (opts: GridLayoutOptions): GridLayoutProviderstatic prototype: GridLayoutProvider```+## HdrFormat — interface @experimental+```+effective: string+fellBack: boolean+linear: boolean+reason: string+requested: string+```+## HeadlessAppOptions — interface @experimental```plugins: Plugin[] | undefined@@ -6524,6 +6533,7 @@ bind: (camera: Entity, stack: PostProcessStack) => voidcreateStack: () => PostProcessStackend: () => voidgetStack: (camera: Entity) => PostProcessStack | null+hdrFormat: () => HdrFormat | nullinit: (width: number, height: number) => booleanisInitialized: () => booleanmsaaCapability: () => { effective: number; max: number; }diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 99f8bb985..0c1027f28 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -326,6 +326,8 @@ postprocess_effectiveMsaaSamples: (() => number) | undefinedpostprocess_end: () => voidpostprocess_endScreenCapture: () => voidpostprocess_executeScreenPasses: () => void+postprocess_hdrFormat: ((outPtr: number) => number) | undefined+postprocess_hdrFormatNames: (() => string) | undefinedpostprocess_init: (width: number, height: number) => booleanpostprocess_isInitialized: () => booleanpostprocess_maxMsaaSamples: (() => number) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex cf54415d6..4fbd4868c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1648 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1649 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3846,6 +3846,15 @@ static new (opts: GridLayoutOptions): GridLayoutProviderstatic prototype: GridLayoutProvider```+## HdrFormat — interface @experimental+```+effective: string+fellBack: boolean+linear: boolean+reason: string+requested: string+```+## HeadlessAppOptions — interface @experimental```plugins: Plugin[] | undefined@@ -6285,6 +6294,7 @@ bind: (camera: Entity, stack: PostProcessStack) => voidcreateStack: () => PostProcessStackend: () => voidgetStack: (camera: Entity) => PostProcessStack | null+hdrFormat: () => HdrFormat | nullinit: (width: number, height: number) => booleanisInitialized: () => booleanmsaaCapability: () => { effective: number; max: number; }diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 826b283d8..9dad62425 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -152,6 +152,7 @@ export {PostProcessAPI,PostProcessStack,type OutputTransform,+ type HdrFormat,type EffectDef,type EffectUniformDef,getEffectDef,diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 9820faf9a..4b9a57e24 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -91,6 +91,8 @@ export interface NativeEngineApi {postprocess_end?(): void;postprocess_endScreenCapture?(): void;postprocess_executeScreenPasses?(): void;+ postprocess_hdrFormat?(outPtr: number): number;+ postprocess_hdrFormatNames?(): string;postprocess_init?(width: number, height: number): boolean;postprocess_isInitialized?(): boolean;postprocess_maxMsaaSamples?(): number;@@ -343,6 +345,8 @@ export function createNativeEngineApi(bind('postprocess_end', 'es_postprocess_end', false);bind('postprocess_endScreenCapture', 'es_postprocess_endScreenCapture', false);bind('postprocess_executeScreenPasses', 'es_postprocess_executeScreenPasses', false);+ bind('postprocess_hdrFormat', 'es_postprocess_hdrFormat', false);+ bind('postprocess_hdrFormatNames', 'es_postprocess_hdrFormatNames', false);bind('postprocess_init', 'es_postprocess_init', false);bind('postprocess_isInitialized', 'es_postprocess_isInitialized', false);bind('postprocess_maxMsaaSamples', 'es_postprocess_maxMsaaSamples', false);diff --git a/sdk/src/postprocess.ts b/sdk/src/postprocess.tsindex bbd799634..423e69f9b 100644--- a/sdk/src/postprocess.ts+++ b/sdk/src/postprocess.ts@@ -6,6 +6,7 @@ export {PostProcessStack,outputTransformCode,type OutputTransform,+ type HdrFormat,postProcessEffects,initPostProcessAPI,shutdownPostProcessAPI,diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.tsindex 13d051cb4..68dfb1246 100644--- a/sdk/src/postprocess/PostProcessAPI.ts+++ b/sdk/src/postprocess/PostProcessAPI.ts@@ -35,6 +35,25 @@ class PostProcessBridge extends WasmBridge<NonNullable<EngineApi>> {const bridge = new PostProcessBridge();let module: PostProcessCore | null = null;+/** Four floats the committed format decision is read back through. */+let hdrPtr = 0;++/**+ * The format one frame committed its intermediates to. @experimental+ *+ * `fellBack` is `requested !== effective`, stated so a reader does not have to+ * compare two strings to learn whether anything gave way — and `linear` is what+ * separates a granted ask from no ask at all, which the pair alone cannot say.+ */+export interface HdrFormat {+ requested: string;+ effective: string;+ /** Why they differ; `none` when they do not. */+ reason: string;+ /** Whether the project asked for a linear pipeline this frame. */+ linear: boolean;+ fellBack: boolean;+}/*** @internal Wired by the engine plugins — not part of the public API.@@ -45,6 +64,8 @@ let module: PostProcessCore | null = null;export function initPostProcessAPI(engine: NonNullable<EngineApi>): void {bridge.connect(engine);module = bridge.module as PostProcessCore;+ const heap = engine as unknown as { _malloc?(n: number): number };+ if (!hdrPtr && typeof heap._malloc === 'function') hdrPtr = heap._malloc(4 * 4);}/** @internal Wired by the engine plugins — not part of the public API. */@@ -57,6 +78,10 @@ export function shutdownPostProcessAPI(): void {handleWasmError(e, 'PostProcess.shutdown');}}+ if (hdrPtr && module) {+ (module as unknown as { _free?(p: number): void })._free?.(hdrPtr);+ hdrPtr = 0;+ }bridge.disconnect();module = null;}@@ -297,6 +322,36 @@ export class PostProcessAPI {}}+ /**+ * The format decision the last frame COMMITTED to. @experimental+ *+ * The frame's own answer, not the device asked again. `linear` false is a+ * project that never asked for HDR, which is not a fallback. The names come+ * from the engine — a second spelling of the enum's order is drift.+ */+ hdrFormat(): HdrFormat | null {+ try {+ const m = getModule() as unknown as {+ postprocess_hdrFormat?(p: number): number;+ postprocess_hdrFormatNames?(): string;+ };+ if (!m.postprocess_hdrFormat || !m.postprocess_hdrFormatNames || !hdrPtr) return null;+ if (!m.postprocess_hdrFormat(hdrPtr)) return null;+ const heap = (bridge.module as unknown as { HEAPF32?: Float32Array }).HEAPF32;+ if (!heap) return null;+ const f = heap.subarray(hdrPtr >> 2, (hdrPtr >> 2) + 4);+ const [requested, effective, reason] = m.postprocess_hdrFormatNames().split('|');+ return {+ requested: requested ?? '', effective: effective ?? '',+ reason: reason ?? 'none', linear: f[3] === 1,+ fellBack: (requested ?? '') !== (effective ?? ''),+ };+ } catch (e) {+ handleWasmError(e, 'PostProcess.hdrFormat');+ return null;+ }+ }+begin(): void {try {getModule().postprocess_begin();diff --git a/sdk/src/postprocess/index.ts b/sdk/src/postprocess/index.tsindex 6bdd7db19..fff5866a2 100644--- a/sdk/src/postprocess/index.ts+++ b/sdk/src/postprocess/index.ts@@ -4,7 +4,7 @@ export { PostProcessStack } from './PostProcessStack';export type { PassConfig } from './PostProcessStack';export { PostProcess, PostProcessAPI, initPostProcessAPI, shutdownPostProcessAPI, syncStackToWasm } from './PostProcessAPI';export { outputTransformCode } from './PostProcessAPI';-export type { OutputTransform } from './PostProcessAPI';+export type { OutputTransform, HdrFormat } from './PostProcessAPI';export { postProcessEffects } from './postProcessEffects';export { POSTPROCESS_VERTEX } from './shaders';export {diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex b0dbbd9c7..6f945b7c4 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -403,6 +403,8 @@ export interface ESEngineModule {postprocess_setMsaaSamples(samples: number): void;postprocess_effectiveMsaaSamples?(): number;postprocess_maxMsaaSamples?(): number;+ postprocess_hdrFormat?(outPtr: number): number;+ postprocess_hdrFormatNames?(): string;postprocess_setUniformFloat(passName: string, uniform: string, value: number): void;postprocess_setPassTexture(passName: string, uniform: string, textureHandle: number): void;postprocess_setUniformVec4(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cppindex 2b50cb5f5..dd3ad6a4d 100644--- a/src/esengine/bindings/PostProcessBindings.cpp+++ b/src/esengine/bindings/PostProcessBindings.cpp@@ -4,6 +4,7 @@#include "PostProcessBindings.hpp"#include "ActiveContext.hpp"+#include "BoundarySpan.hpp"#include "../renderer/rhi/GfxDevice.hpp"#include "../renderer/frame/PostProcessPipeline.hpp"#include "../renderer/frame/RenderContext.hpp"@@ -77,6 +78,26 @@ u32 postprocess_maxMsaaSamples() {return g_device ? g_device->maxSamples() : 0u;}+i32 postprocess_hdrFormat(uintptr_t outPtr) {+ auto* out = boundarySpanMut<f32>(outPtr, 4, "postprocess_hdrFormat.out");+ if (!out) return 0;+ for (u32 i = 0; i < 4; ++i) out[i] = 0.0f;+ if (!g_postProcessPipeline) return 0;+ const HdrFormatDecision& d = g_postProcessPipeline->hdrFormat();+ out[0] = static_cast<f32>(static_cast<u8>(d.requested));+ out[1] = static_cast<f32>(static_cast<u8>(d.effective));+ out[2] = static_cast<f32>(static_cast<u8>(d.refusal));+ out[3] = d.linear ? 1.0f : 0.0f;+ return 1;+}++std::string postprocess_hdrFormatNames() {+ if (!g_postProcessPipeline) return {};+ const HdrFormatDecision& d = g_postProcessPipeline->hdrFormat();+ return std::string(pixelFormatName(d.requested)) + '|' + pixelFormatName(d.effective)+ + '|' + hdrRefusalName(d.refusal);+}+void postprocess_setPassScale(const std::string& passName, f32 scale) {if (g_postProcessPipeline) {g_postProcessPipeline->setPassScale(passName, scale);diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hppindex c605c0558..f354e9b83 100644--- a/src/esengine/bindings/PostProcessBindings.hpp+++ b/src/esengine/bindings/PostProcessBindings.hpp@@ -20,6 +20,21 @@ void postprocess_setMsaaSamples(u32 samples);/// only saying both tells a typo from a machine. 0 = nothing here can answer.u32 postprocess_effectiveMsaaSamples();u32 postprocess_maxMsaaSamples();++/**+ * @brief The format decision the last frame COMMITTED to, into four floats at+ * @p outPtr: requested, effective, refusal, linear.+ *+ * @details The frame's own answer, not the capability re-asked. `linear` false is+ * a project that never asked for HDR, which is not a fallback. Returns 0+ * before a frame has committed a format.+ */+i32 postprocess_hdrFormat(uintptr_t outPtr);++/** @brief The last committed decision as words: "requested|effective|reason".+ * Empty before a frame has committed one. The names come from the engine so no+ * reader has to hold a second spelling of the format enum's order. */+std::string postprocess_hdrFormatNames();/** Draw a pass at a fraction of the chain size; the next pass upsamples it. */void postprocess_setPassScale(const std::string& passName, f32 scale);void postprocess_setUniformFloat(const std::string& passName,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 5dfc5b2b9..462774828 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -576,6 +576,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("postprocess_setMsaaSamples", &esengine::postprocess_setMsaaSamples);emscripten::function("postprocess_effectiveMsaaSamples", &esengine::postprocess_effectiveMsaaSamples);emscripten::function("postprocess_maxMsaaSamples", &esengine::postprocess_maxMsaaSamples);+ emscripten::function("postprocess_hdrFormat", &esengine::postprocess_hdrFormat);+ emscripten::function("postprocess_hdrFormatNames", &esengine::postprocess_hdrFormatNames);emscripten::function("postprocess_setUniformFloat", &esengine::postprocess_setUniformFloat);emscripten::function("postprocess_setUniformVec4", &esengine::postprocess_setUniformVec4);emscripten::function("postprocess_setPassTexture", &esengine::postprocess_setPassTexture);diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex bff013902..abf0c5bbd 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -101,15 +101,18 @@ resource::ShaderHandle PostProcessPipeline::outputShader() {return tonemapShader_;}+/**+ * The format this frame committed to — read, never re-derived: begin() and+ * declareChain() both build targets, and a colour-space flip between them would+ * give one frame two formats.+ */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;+ return frame_format_.effective;+}++/** Take the format decision for the frame about to be built. */+void PostProcessPipeline::commitFormat() {+ frame_format_ = decideHdrFormat(linear_output_, device_.supportsFloatTargets());}void PostProcessPipeline::ensureGraph() {@@ -118,6 +121,7 @@ void PostProcessPipeline::ensureGraph() {// frame's from construction and this is a no-op.ownedGraph_ = makeUnique<rg::RenderGraph>(device_);graph_ = ownedGraph_.get();+ commitFormat();if (linear_output_) {ES_LOG_INFO("PostProcess intermediates: {}",interFormat() == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"@@ -370,6 +374,11 @@ void PostProcessPipeline::begin(const f32* clearColor) {ensureGraph();if (!graph_) return;+ // The frame's format is taken HERE, before its first resource exists, and+ // every target built between here and end() reads it. A policy flip lands on+ // the next frame rather than halfway through this one.+ commitFormat();+// The graph opens HERE and not at end(), because the scene target is its// first resource and the scene is drawn before any pass can be declared.graph_->begin(width_, height_);@@ -617,7 +626,12 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Res}void PostProcessPipeline::ensureScreenFBO() {- if (screenFBOCreated_) return;+ // This one PERSISTS across frames, so a colour-space change leaves it holding+ // the format it was made under while the chain has moved on. Remade when it+ // no longer matches.+ if (screenFBOCreated_ && screenFBOFormat_ == interFormat()) return;+ screenFBO_.reset();+ screenFBOCreated_ = false;FramebufferSpec spec;// The multi-camera composition surface carries scene values too — same@@ -635,6 +649,7 @@ void PostProcessPipeline::ensureScreenFBO() {return;}+ screenFBOFormat_ = spec.colorFormat;screenFBOCreated_ = true;}diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex eebba5f43..b6c6dcb09 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -17,6 +17,7 @@#include "../../math/Math.hpp"#include "../rhi/Framebuffer.hpp"#include "../graph/RenderGraph.hpp"+#include "../store/HdrFormat.hpp"#include <glm/glm.hpp>#include <string>@@ -273,6 +274,15 @@ public:*/void setLinearOutput(bool linear) { linear_output_ = linear; }+ /**+ * @brief What this frame's intermediates were asked to be and allowed to be.+ *+ * @details The committed decision, not a re-derivation: an editor explaining+ * why a linear project is running at 8-bit has to agree with the+ * targets the frame actually made.+ */+ const HdrFormatDecision& hdrFormat() const { return frame_format_; }+/*** @brief Whether the scene target needs a depth attachment.*@@ -368,6 +378,7 @@ private:PostProcessPass* findPass(const std::string& name);/** Intermediate/capture attachment format for the active pipeline mode. */GfxPixelFormat interFormat() const;+ void commitFormat();/** The shape of every target in a chain, the scene target included. */rg::TargetDesc chainTarget(bool withDepth) const;rg::TargetDesc blitSourceTarget(bool withDepth) const;@@ -409,6 +420,10 @@ private:bool inFrame_ = false;bool bypass_ = false;bool linear_output_ = false;+ /// The format this frame committed to; see commitFormat().+ HdrFormatDecision frame_format_{};+ /// What screenFBO_ was created with, so a policy change can be noticed.+ GfxPixelFormat screenFBOFormat_ = GfxPixelFormat::RGBA8;bool scene_needs_depth_ = false;/// What the PROJECT asked for (policy). 4 matches what a browser gives its/// own drawing buffer, which is the quality a chain-less frame always had.diff --git a/src/esengine/renderer/store/HdrFormat.hpp b/src/esengine/renderer/store/HdrFormat.hppnew file mode 100644index 000000000..45d286b29--- /dev/null+++ b/src/esengine/renderer/store/HdrFormat.hpp@@ -0,0 +1,90 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file HdrFormat.hpp+ * @brief What a linear project ASKED its intermediates to be, and what the+ * device let them be.+ *+ * @details The choice was a function nobody kept the answer to: it read the+ * colour-space flag and the device's float capability every time it was+ * asked. So a project set to linear on a backend without renderable+ * float targets ran the whole chain at 8-bit precision, correctly, and+ * with nothing anywhere recording that it had.+ */+#pragma once++#include "../../core/Types.hpp"+#include "../rhi/GfxEnums.hpp"++namespace esengine {++/** @brief Why the effective format is not the requested one. */+enum class HdrRefusal : u8 {+ None = 0,+ /// The device cannot render to a float target (WebGL2 without+ /// EXT_color_buffer_float). sRGB-encoded 8-bit keeps the linear pipeline+ /// correct and takes its over-range headroom away.+ FloatTargetsUnsupported,+};++/** @brief The refusal as a word, for a log line and for a reader. */+inline const char* hdrRefusalName(HdrRefusal why) {+ switch (why) {+ case HdrRefusal::FloatTargetsUnsupported: return "float targets unsupported";+ case HdrRefusal::None: break;+ }+ return "none";+}++/**+ * @brief A pixel format as a word.+ *+ * @details Named HERE rather than mirrored in TypeScript: the enum crosses as a+ * bare number, and a second spelling of its ORDER is what+ * check-enum-twins exists to refuse. A reader that wants to show the+ * format asks for the word.+ */+inline const char* pixelFormatName(GfxPixelFormat format) {+ switch (format) {+ case GfxPixelFormat::RGB8: return "RGB8";+ case GfxPixelFormat::RGBA8: return "RGBA8";+ case GfxPixelFormat::SRGB8_ALPHA8: return "SRGB8_ALPHA8";+ case GfxPixelFormat::RGBA16F: return "RGBA16F";+ case GfxPixelFormat::DepthComponent24: return "DepthComponent24";+ case GfxPixelFormat::Depth24Stencil8: return "Depth24Stencil8";+ }+ return "unknown";+}++/**+ * @brief The format decision one frame committed to.+ *+ * @details `requested == effective` covers both a granted ask and no ask at all;+ * `linear` is what tells them apart. A gamma project is not a fallback,+ * and calling it one warns every project that never wanted HDR.+ */+struct HdrFormatDecision {+ GfxPixelFormat requested = GfxPixelFormat::RGBA8;+ GfxPixelFormat effective = GfxPixelFormat::RGBA8;+ HdrRefusal refusal = HdrRefusal::None;+ /// Whether the project asked for a linear pipeline at all this frame.+ bool linear = false;+};++/**+ * @brief What a linear project asks for, and what @p supportsFloatTargets grants.+ *+ * @details Pure, so the three cases hold without a device. Called once where the+ * frame COMMITS: two targets in one frame disagreeing about their format+ * is a chain sampling a texture that is not the one it wrote.+ */+inline HdrFormatDecision decideHdrFormat(bool linearOutput, bool supportsFloatTargets) {+ if (!linearOutput) return {GfxPixelFormat::RGBA8, GfxPixelFormat::RGBA8, HdrRefusal::None, false};+ if (supportsFloatTargets) {+ return {GfxPixelFormat::RGBA16F, GfxPixelFormat::RGBA16F, HdrRefusal::None, true};+ }+ return {GfxPixelFormat::RGBA16F, GfxPixelFormat::SRGB8_ALPHA8,+ HdrRefusal::FloatTargetsUnsupported, true};+}++} // namespace esenginediff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txtindex 3824bfc60..e6100c450 100644--- a/tests/CMakeLists.txt+++ b/tests/CMakeLists.txt@@ -216,6 +216,13 @@ target_include_directories(test_shadow_atlas PRIVATE)add_test(NAME test_shadow_atlas COMMAND test_shadow_atlas)+add_executable(test_hdr_format renderer/test_hdr_format.cpp)+target_include_directories(test_hdr_format PRIVATE+ ${CMAKE_SOURCE_DIR}/src+ ${CMAKE_SOURCE_DIR}/third_party/glm+)+add_test(NAME test_hdr_format COMMAND test_hdr_format)+# Texture path cache: compiles ResourceManager.cpp against MockGfxDevice and asserts# which requests avoided an upload. A shipped build decodes in the host and registers# an id, so acquireTextureByPath is the only place that decision is made.@@ -238,6 +245,7 @@ target_include_directories(test_texture_cache PRIVATE)add_test(NAME test_texture_cache COMMAND test_texture_cache)+# Shader variant (feature-permutation) system (RC7-6). Compiles ShaderParser.cpp# directly — no GL/engine link — and checks #pragma feature parsing + #define injection.add_executable(test_shader_variantdiff --git a/tests/renderer/test_hdr_format.cpp b/tests/renderer/test_hdr_format.cppnew file mode 100644index 000000000..83219519d--- /dev/null+++ b/tests/renderer/test_hdr_format.cpp@@ -0,0 +1,61 @@+// What a linear project asked its intermediates to be, and what the device let+// them be. Three cases, not two: a gamma project getting RGBA8 is not a+// fallback, and calling it one warns every project that never wanted HDR.++#include "esengine/renderer/store/HdrFormat.hpp"++#include <cstdio>++using namespace esengine;++static int g_failures = 0;+#define CHECK(cond, msg) \+ do { \+ if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; } \+ else { std::printf("ok: %s\n", msg); } \+ } while (0)++int main() {+ // No linear pipeline: nothing asked for HDR, so nothing gave way.+ const HdrFormatDecision gamma = decideHdrFormat(/*linear=*/false, /*float=*/false);+ CHECK(gamma.requested == GfxPixelFormat::RGBA8, "a gamma project asks for RGBA8");+ CHECK(gamma.effective == GfxPixelFormat::RGBA8, "and gets it");+ CHECK(gamma.refusal == HdrRefusal::None,+ "and is NOT a fallback — a device that cannot do what nobody asked for refused nothing");+ CHECK(!gamma.linear, "and did not ask for a linear pipeline");++ // The same device, with the capability it lacks now irrelevant.+ const HdrFormatDecision gammaOnCapable = decideHdrFormat(false, true);+ CHECK(gammaOnCapable.effective == GfxPixelFormat::RGBA8 &&+ gammaOnCapable.refusal == HdrRefusal::None,+ "a capable device does not push HDR onto a project that asked for none");++ // Asked and granted.+ const HdrFormatDecision hdr = decideHdrFormat(true, true);+ CHECK(hdr.requested == GfxPixelFormat::RGBA16F, "a linear project asks for half-float");+ CHECK(hdr.effective == GfxPixelFormat::RGBA16F, "and a capable device gives it");+ CHECK(hdr.refusal == HdrRefusal::None, "with nothing to explain");+ CHECK(hdr.linear, "and it did ask for a linear pipeline");++ // Asked and not granted — the case that ran silently.+ const HdrFormatDecision fell = decideHdrFormat(true, false);+ CHECK(fell.requested == GfxPixelFormat::RGBA16F, "the ask is the same");+ CHECK(fell.effective == GfxPixelFormat::SRGB8_ALPHA8,+ "and sRGB-encoded 8-bit keeps the linear pipeline correct at LDR precision");+ CHECK(fell.refusal == HdrRefusal::FloatTargetsUnsupported,+ "and the reason is the device's, named");+ CHECK(fell.requested != fell.effective,+ "asked and got differ, which is the whole fact a reader needs");+ CHECK(fell.linear, "and the project did ask");++ // The one thing a reader must never have to infer: whether an equal pair is+ // a granted ask or no ask at all. `requested` alone cannot say it; `linear`+ // is what separates them.+ CHECK(gamma.requested == gamma.effective && hdr.requested == hdr.effective,+ "both non-fallback cases have requested == effective");+ CHECK(gamma.linear != hdr.linear,+ "and only `linear` tells a granted ask from no ask at all");++ std::printf(g_failures ? "\n%d check(s) failed\n" : "\nall HDR format claims hold\n", g_failures);+ return g_failures == 0 ? 0 : 1;+}diff --git a/tools/check-hdr-format.mjs b/tools/check-hdr-format.mjsnew file mode 100644index 000000000..9b3b082c7--- /dev/null+++ b/tools/check-hdr-format.mjs@@ -0,0 +1,85 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-hdr-format.mjs — the frame commits to an intermediate format, and+ * one reader answers for it.+ *+ * test_hdr_format holds the three cases apart. This holds the wiring: the+ * decision taken once per frame, every target reading THAT, and the panel and+ * the tool being one reader rather than two. begin() and declareChain() both+ * build targets, so a format re-derived per call can differ between them.+ */+import { readFileSync, existsSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const PIPE = 'src/esengine/renderer/frame/PostProcessPipeline.cpp';+const SURFACE = 'desktop/src/engine/EditorControlSurface.ts';+const SETTINGS = 'desktop/src/settings/projectSettings.ts';++const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');+const problems = [];+const pipe = read(PIPE);++// 1. The decision is TAKEN, once, where the frame commits to its resources.+if (!/void PostProcessPipeline::commitFormat\(\)/.test(pipe)) {+ problems.push(`${PIPE} no longer commits a format — the choice is a question re-asked, and two`+ + ' targets in one frame may answer it differently');+}+if (!/commitFormat\(\);[\s\S]{0,400}graph_->begin\(/.test(pipe)) {+ problems.push(`${PIPE} does not commit the format before the graph opens — begin() creates the`+ + ' scene target and declareChain() creates the rest, so a policy flip between them would give'+ + ' one frame two formats');+}++// 2. Every target reads the committed value, not the capability again.+const inter = /GfxPixelFormat PostProcessPipeline::interFormat\(\) const \{([\s\S]*?)\n\}/.exec(pipe);+if (!inter) {+ problems.push(`${PIPE}: interFormat has moved — this gate reads its body`);+} else if (/supportsFloatTargets|linear_output_/.test(inter[1])) {+ problems.push(`${PIPE}: interFormat derives the format again instead of returning the frame's`+ + ' committed decision — which is the state that let one frame hold two answers');+}++// 3. The persistent screen FBO is not exempt. Every other target is rebuilt by+// the graph each frame; this one outlives the policy that made it.+if (!/screenFBOFormat_ == interFormat\(\)/.test(pipe)) {+ problems.push(`${PIPE}: ensureScreenFBO no longer checks the format it was made with — a`+ + ' colour-space change leaves it holding the old one while the chain has moved on');+}++if (!existsSync(path.join(ROOT, 'desktop', 'src'))) {+ if (problems.length === 0) {+ console.log('check-hdr-format: no editor checkout — the frame commits, the reader was not judged.');+ process.exit(0);+ }+} else {+ // 4. One reader, and it reads the frame rather than the device.+ if (!/post\.hdrFormat\(\)/.test(read(SURFACE))) {+ problems.push(`${SURFACE} no longer reads the committed decision (PostProcess.hdrFormat)`);+ }+ const settings = read(SETTINGS);+ if (!/EditorControlSurface\.hdrFormat\(\)/.test(settings)) {+ problems.push(`${SETTINGS} no longer asks the surface — a second call is a second reader, and`+ + ' the behavioural check exercises only the one the tool goes through');+ }+ if (/supportsFloatTargets/.test(settings)) {+ problems.push(`${SETTINGS} consults the device capability — the effective format is the frame's`+ + ' answer to read back, not one to work out from what the device can do');+ }+ // A project that asked for nothing did not fall back, and saying it did puts a+ // warning in front of every gamma project.+ if (!/seen\.linear/.test(settings)) {+ problems.push(`${SETTINGS} no longer separates "asked and was refused" from "never asked" —`+ + ' requested === effective covers both, and only `linear` tells them apart');+ }+}++if (problems.length) {+ console.error(`check-hdr-format: ${problems.length} problem(s)`);+ for (const p of problems) console.error(` - ${p}`);+ process.exit(1);+}+console.log('check-hdr-format: the frame commits one format, every target reads it, and the panel'+ + ' and the tool read it through one method.');diff --git a/tools/gates.mjs b/tools/gates.mjsindex e2cbd51a7..f903ed85d 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -191,6 +191,7 @@ export const GATES = [{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },{ id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },{ id: 'light-cap', run: 'node tools/check-light-cap.mjs' },+ { id: 'hdr-format', run: 'node tools/check-hdr-format.mjs' },{ id: 'decision-inventory', run: 'node tools/check-decision-inventory.mjs', needs: 'editor' },{ id: 'mutator-parity', run: 'node tools/check-mutator-parity.mjs', needs: 'editor' },{ id: 'version-authority', run: 'node tools/check-version-authority.mjs', needs: 'editor' },diff --git a/tools/lib/runtimeDecisions.mjs b/tools/lib/runtimeDecisions.mjsindex a8670e2a6..550a3df6a 100644--- a/tools/lib/runtimeDecisions.mjs+++ b/tools/lib/runtimeDecisions.mjs@@ -98,14 +98,10 @@ export const DECISIONS = [id: 'postfx.hdrFormat',what: 'Whether a linear-colour project got half-float intermediates or was quietly kept at LDR precision.',kind: 'request-vs-capability',- owner: { path: 'src/esengine/renderer/frame/PostProcessPipeline.cpp', probe: /supportsFloatTargets\(\) \? GfxPixelFormat::RGBA16F/ },- runtime: { has: false, owed: 'the fallback is taken inside interFormat() and recorded nowhere' },- editor: {- has: false,- owed: 'Project Settings offers colorSpace: linear and never says the device could not carry it; '- + 'bloom and tonemap then see values crushed at the 8-bit store',- },- agent: { has: false, owed: 'nothing to read' },+ owner: { path: 'src/esengine/renderer/store/HdrFormat.hpp', probe: /inline HdrFormatDecision decideHdrFormat/ },+ runtime: { has: true, cite: { path: 'src/esengine/renderer/frame/PostProcessPipeline.cpp', probe: /void PostProcessPipeline::commitFormat/ } },+ editor: { has: true, cite: { path: 'desktop/src/settings/projectSettings.ts', probe: /EditorControlSurface\.hdrFormat\(\)/ } },+ agent: { has: true, cite: { path: 'desktop/shared/toolCatalog.mjs', probe: /'get_hdr_format'/ } },},{id: 'texture.compressedFormat',