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(postfx): the intermediate format is a decision the frame commits to

esengine2e0a8d0039af
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 76f73681d..9c7fcf30e 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -29,7 +29,7 @@ env:
test_registry_ondestroy test_view_api_matrix
test_shader_device test_draw_params test_texture_fb test_buffer_device
test_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_format
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_aot_host test_aot_conformance
test_frame_lifecycle
diff --git a/desktop b/desktop
index 7a258faa0..c18a973dc 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 7a258faa0d65dd625cfca3e1c4ac5986dc4d4eae
+Subproject commit c18a973dcae3b99c3d044e4202332bc0ecbce87a
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.md
index 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): GridLayoutProvider
static 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) => void
createStack: () => PostProcessStack
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
+hdrFormat: () => HdrFormat | null
init: (width: number, height: number) => boolean
isInitialized: () => boolean
msaaCapability: () => { effective: number; max: number; }
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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): GridLayoutProvider
static 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) => void
createStack: () => PostProcessStack
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
+hdrFormat: () => HdrFormat | null
init: (width: number, height: number) => boolean
isInitialized: () => boolean
msaaCapability: () => { effective: number; max: number; }
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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): GridLayoutProvider
static 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) => void
createStack: () => PostProcessStack
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
+hdrFormat: () => HdrFormat | null
init: (width: number, height: number) => boolean
isInitialized: () => boolean
msaaCapability: () => { effective: number; max: number; }
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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): GridLayoutProvider
static 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) => void
createStack: () => PostProcessStack
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
+hdrFormat: () => HdrFormat | null
init: (width: number, height: number) => boolean
isInitialized: () => boolean
msaaCapability: () => { effective: number; max: number; }
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 99f8bb985..0c1027f28 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -326,6 +326,8 @@ postprocess_effectiveMsaaSamples: (() => number) | undefined
postprocess_end: () => void
postprocess_endScreenCapture: () => void
postprocess_executeScreenPasses: () => void
+postprocess_hdrFormat: ((outPtr: number) => number) | undefined
+postprocess_hdrFormatNames: (() => string) | undefined
postprocess_init: (width: number, height: number) => boolean
postprocess_isInitialized: () => boolean
postprocess_maxMsaaSamples: (() => number) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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): GridLayoutProvider
static 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) => void
createStack: () => PostProcessStack
end: () => void
getStack: (camera: Entity) => PostProcessStack | null
+hdrFormat: () => HdrFormat | null
init: (width: number, height: number) => boolean
isInitialized: () => boolean
msaaCapability: () => { effective: number; max: number; }
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.cpp
index 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.hpp
index 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.cpp
index 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.cpp
index 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.hpp
index 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.hpp
new file mode 100644
index 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 esengine
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 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_variant
diff --git a/tests/renderer/test_hdr_format.cpp b/tests/renderer/test_hdr_format.cpp
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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',