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 linear-light pipeline - colorSpace: 'linear' renders physically
esengine112f21cd5080
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 1bd1919a3..4a6bb4708 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -43,6 +43,9 @@ const STEPS = Number(process.env.ESTELLA_VERIFY_STEPS) || 30;// ESTELLA_VERIFY_BACKEND=webgpu runs the same scene + assertions on the WebGPU// backend (needs a real adapter — local runs; CI runners have none).const BACKEND = process.env.ESTELLA_VERIFY_BACKEND === 'webgpu' ? 'webgpu' : 'webgl2';+// 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' : '';// Headless / GPU-less (CI) WebGL2 falls back to SwiftShader; harmless with a GPU.app.commandLine.appendSwitch('enable-unsafe-swiftshader');@@ -102,7 +105,7 @@ app.whenReady().then(async () => {let server;try {server = await serveDist();- const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}`;+ const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}`;// useContentSize: the capture rectangle must be the page area, not the// outer frame (the same trap the parity runner documents).diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 0e069b0fb..1bfc6ceef 100644--- a/desktop/src/engine/EngineHost.ts+++ b/desktop/src/engine/EngineHost.ts@@ -420,6 +420,7 @@ class EngineHostImpl {width: number;height: number;backend?: 'webgl2' | 'webgpu';+ colorSpace?: 'gamma' | 'linear';}): Promise<void> {if (this.booted) return;this.booted = true;@@ -432,6 +433,7 @@ class EngineHostImpl {runLoop: false,loadInitialScene: false,backend: size.backend,+ colorSpace: size.colorSpace,});} catch (err) {this.swallowUnwind(err);@@ -444,7 +446,10 @@ class EngineHostImpl {// does neither — it advances frames via tick() and loads scenes on demand.private async bootCore(canvas: HTMLCanvasElement,- opts: { runLoop: boolean; loadInitialScene: boolean; backend?: 'webgl2' | 'webgpu' },+ opts: {+ runLoop: boolean; loadInitialScene: boolean;+ backend?: 'webgl2' | 'webgpu'; colorSpace?: 'gamma' | 'linear';+ },) {const backend = opts.backend ?? 'webgl2';this.activeBackend = backend;@@ -539,6 +544,7 @@ class EngineHostImpl {const app = createWebApp(module, {backend,+ colorSpace: opts.colorSpace,canvasSelector: `#${canvas.id}`,glContextHandle: glHandle,getViewportSize: () => ({ width: canvas.width, height: canvas.height }),diff --git a/desktop/src/headless.ts b/desktop/src/headless.tsindex a7a7da772..c3c27b24d 100644--- a/desktop/src/headless.ts+++ b/desktop/src/headless.ts@@ -34,8 +34,9 @@ const params = new URLSearchParams(location.search);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;window.__estellaHeadless = {- ready: EngineHost.bootHeadless({ width, height, backend }),+ ready: EngineHost.bootHeadless({ width, height, backend, colorSpace }),api: EditorControlSurface,};diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 959788fae..1930c09ac 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1670,6 +1670,7 @@ world: World```backend: "webgl2" | "webgpu" | undefinedcanvasSelector: string | undefined+colorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined@@ -2155,6 +2156,7 @@ renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => vorenderer_replayToDrawCall: (drawCallIndex: number) => voidrenderer_resize: (width: number, height: number) => voidrenderer_setClearColor: (r: number, g: number, b: number, a: number) => void+renderer_setColorSpace: ((linear: number) => void) | undefinedrenderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => voidrenderer_setEntityStencilMask: (entity: number, refValue: number) => voidrenderer_setEntityStencilTest: (entity: number, refValue: number) => void@@ -6992,6 +6994,7 @@ static prototype: WeChatSocket```backend: "webgl2" | "webgpu" | undefinedcanvasSelector: string | undefined+colorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d05d246bd..ffb3b9142 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1665,6 +1665,7 @@ world: World```backend: "webgl2" | "webgpu" | undefinedcanvasSelector: string | undefined+colorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefined@@ -2150,6 +2151,7 @@ renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => vorenderer_replayToDrawCall: (drawCallIndex: number) => voidrenderer_resize: (width: number, height: number) => voidrenderer_setClearColor: (r: number, g: number, b: number, a: number) => void+renderer_setColorSpace: ((linear: number) => void) | undefinedrenderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => voidrenderer_setEntityStencilMask: (entity: number, refValue: number) => voidrenderer_setEntityStencilTest: (entity: number, refValue: number) => void@@ -6987,6 +6989,7 @@ static prototype: WeChatSocket```backend: "webgl2" | "webgpu" | undefinedcanvasSelector: string | undefined+colorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedglContextHandle: number | undefinedplugins: Plugin[] | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 2d14a7c45..3c04b86c7 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -318,6 +318,7 @@ renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => vorenderer_replayToDrawCall: (drawCallIndex: number) => voidrenderer_resize: (width: number, height: number) => voidrenderer_setClearColor: (r: number, g: number, b: number, a: number) => void+renderer_setColorSpace: ((linear: number) => void) | undefinedrenderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => voidrenderer_setEntityStencilMask: (entity: number, refValue: number) => voidrenderer_setEntityStencilTest: (entity: number, refValue: number) => voiddiff --git a/sdk/src/app.ts b/sdk/src/app.tsindex 39e3ea0b2..79c882662 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -23,6 +23,7 @@ import type { SceneConfig } from './sceneManager';import { SceneManager } from './sceneManager';import { sceneManagerPlugin } from './scenePlugin';import { getDefaultContext } from './context';+import { setLinearColorSpace } from './env';import { seedEngineComponents } from './component';import { cameraPlugin } from './camera/CameraPlugin';import { PhysicsRuntime } from './physics/PhysicsRuntime';@@ -1023,6 +1024,13 @@ export interface WebAppOptions {* setting (Project Settings → Rendering); change later via Renderer.setYSortLayers.*/ySortLayers?: number;+ /**+ * Project color space (Project Settings → Rendering). 'linear' renders in+ * linear light: sRGB decode on sample, linear blending in sRGB-format+ * intermediates, and an explicit linear→sRGB encode in the final blit.+ * Must be declared at app creation — shaders compile against it.+ */+ colorSpace?: 'gamma' | 'linear';}export function createWebApp(module: ESEngineModule, options?: WebAppOptions): App {@@ -1036,6 +1044,11 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): Aapp.connectCpp(cppRegistry, module, { strict: true });+ // BEFORE renderer init: shader compilation reads the color-space global.+ // Always applied (realm reloads must reset a prior session's mode too).+ setLinearColorSpace(options?.colorSpace === 'linear');+ module.renderer_setColorSpace?.(options?.colorSpace === 'linear' ? 1 : 0);+if (options?.backend === 'webgpu') {const size = options.getViewportSize?.() ?? { width: 800, height: 600 };if (!module.initRendererWebGPU(options.canvasSelector ?? '#canvas', size.width, size.height)) {diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex c26b25863..e7617e1b6 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';+import { linearColorSpace } from '../../env';import { platformCreateCanvas, platformCreateImage } from '../../platform';import { decodeImageBitmap } from '../imageDecode';import { requireResourceManager } from '../../resourceManager';@@ -270,7 +271,11 @@ export class TextureLoader implements AssetLoader<TextureResult> {gl.bindTexture(gl.TEXTURE_2D, texture);gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flip ? 1 : 0);gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, 0);- gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img as any);+ // Linear pipeline: color textures store sRGB-encoded — the sampler+ // linearizes in hardware. (Data textures opt out via the importer's+ // sRGB flag once wired; until then all image textures are color.)+ const internalFormat = linearColorSpace() ? gl.SRGB8_ALPHA8 : gl.RGBA;+ gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, gl.RGBA, gl.UNSIGNED_BYTE, img as any);gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, glMinFilter);gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, glMagFilter);gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, glWrap);diff --git a/sdk/src/env.ts b/sdk/src/env.tsindex aecd95622..66d6a1e6a 100644--- a/sdk/src/env.ts+++ b/sdk/src/env.ts@@ -64,3 +64,19 @@ export function isFxEditPreview(): boolean {export function fxPreviewOrPlayMode(): boolean {return fxEditPreview || playModeOnly();}++// =============================================================================+// Color space (project rendering.colorSpace)+// =============================================================================++let linearColor = false;++/** Declared at app creation, before textures upload / shaders compile. */+export function setLinearColorSpace(linear: boolean): void {+ linearColor = linear;+}++/** Whether the renderer runs the linear-light pipeline this session. */+export function linearColorSpace(): boolean {+ return linearColor;+}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 609f7ecc8..3f0de0293 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -352,6 +352,7 @@ export interface ESEngineModule {renderer_setViewport(x: number, y: number, w: number, h: number): void;/** Bitmask of layers 0..31 that y-sort within the layer (top-down occlusion). */renderer_setYSortLayers?(mask: number): void;+ renderer_setColorSpace?(linear: number): void;renderer_setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;// Clip Rect APIdiff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 91db460a9..771f4568d 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -2,6 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team#include "RendererBindings.hpp"+#include "../resource/ShaderParser.hpp"#include "ActiveContext.hpp"#include "BoundarySpan.hpp"#include "../renderer/GfxDevice.hpp"@@ -550,6 +551,14 @@ void renderer_setYSortLayers(u32 mask) {if (auto* frame = g_renderFrame) frame->setYSortLayers(mask);}+void renderer_setColorSpace(u32 linear) {+ // Valid pre-init: the global reaches every later shader compile, and+ // RenderFrame::init adopts it. A live frame applies immediately (editor+ // realms reset it per session, mirroring renderer_setYSortLayers).+ resource::ShaderParser::setLinearColorSpace(linear != 0);+ if (auto* frame = g_renderFrame) frame->setColorSpace(linear != 0);+}+void renderer_diagnose() {if (!g_initialized) {ES_LOG_ERROR("[Diagnose] Renderer not initialized");diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 4c3d7dc2a..b79df8214 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -103,6 +103,8 @@ f64 renderer_getTextureBytes();void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a);void renderer_setViewport(i32 x, i32 y, i32 w, i32 h);void renderer_setYSortLayers(u32 mask);+/** Project colorSpace: 1 = linear-light rendering (set before shaders compile). */+void renderer_setColorSpace(u32 linear);void renderer_diagnose();void renderer_setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h);void renderer_clearEntityClipRect(u32 entity);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 714ef0831..c5440466f 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -653,6 +653,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_setClearColor", &esengine::renderer_setClearColor);emscripten::function("renderer_setViewport", &esengine::renderer_setViewport);emscripten::function("renderer_setYSortLayers", &esengine::renderer_setYSortLayers);+ emscripten::function("renderer_setColorSpace", &esengine::renderer_setColorSpace);emscripten::function("renderer_setEntityClipRect", &esengine::renderer_setEntityClipRect);emscripten::function("renderer_clearEntityClipRect", &esengine::renderer_clearEntityClipRect);emscripten::function("renderer_clearAllClipRects", &esengine::renderer_clearAllClipRects);diff --git a/src/esengine/data/shaders/batch.esshader b/src/esengine/data/shaders/batch.esshaderindex 7bbb3258f..3e67af3ef 100644--- a/src/esengine/data/shaders/batch.esshader+++ b/src/esengine/data/shaders/batch.esshader@@ -67,6 +67,13 @@ void main() {else if (v_texIndex == 5) texColor = texture(u_textures[5], v_texCoord);else if (v_texIndex == 6) texColor = texture(u_textures[6], v_texCoord);else texColor = texture(u_textures[7], v_texCoord);+#ifdef ES_LINEAR+ // Vertex colors are authored sRGB; the sampled texel is already linear+ // (sRGB texture formats decode in hardware). Alpha is coverage — never encoded.+ vec4 tint = vec4(srgbToLinear(v_color.rgb), v_color.a);+#else+ vec4 tint = v_color;+#endif#ifdef SDF// The glyph atlas stores a signed distance in the alpha channel (RGB = 1).// Distance ÷ fwidth = screen px from the edge; the ±0.5px clamp is exactly@@ -74,13 +81,13 @@ void main() {float dist = texColor.a;float screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);float coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);- fragColor = vec4(v_color.rgb, v_color.a * coverage);+ fragColor = vec4(tint.rgb, tint.a * coverage);#elif defined(LIT)// Flat normal; the tinted color is the albedo. Normal maps need a material.- vec4 base = texColor * v_color;+ vec4 base = texColor * tint;fragColor = vec4(applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);#else- fragColor = texColor * v_color;+ fragColor = texColor * tint;#endif}#pragma end@@ -159,18 +166,23 @@ struct VSOut {else if (idx == 5) { texColor = textureSampleLevel(t5, s5, v.v_texCoord, 0.0); }else if (idx == 6) { texColor = textureSampleLevel(t6, s6, v.v_texCoord, 0.0); }else { texColor = textureSampleLevel(t7, s7, v.v_texCoord, 0.0); }+#ifdef ES_LINEAR+ let tint = vec4f(srgbToLinear(v.v_color.rgb), v.v_color.a);+#else+ let tint = v.v_color;+#endif#ifdef SDF// Same coverage math as the GLSL stage; fwidth here is in uniform control// flow (main scope), which WGSL requires of derivative builtins.let dist = texColor.a;let screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);let coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);- return vec4f(v.v_color.rgb, v.v_color.a * coverage);+ return vec4f(tint.rgb, tint.a * coverage);#elif defined(LIT)- let base = texColor * v.v_color;+ let base = texColor * tint;return vec4f(applyLighting2D(base.rgb, vec3f(0.0, 0.0, 1.0), v.v_worldPos), base.a);#else- return texColor * v.v_color;+ return texColor * tint;#endif}#pragma enddiff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshaderindex 056128a31..a218823e5 100644--- a/src/esengine/data/shaders/blit.esshader+++ b/src/esengine/data/shaders/blit.esshader@@ -10,12 +10,24 @@ uniform sampler2D u_texture;out vec4 fragColor;void main() {- fragColor = texture(u_texture, v_texCoord);+ vec4 c = texture(u_texture, v_texCoord);+#ifdef ES_LINEAR+ // The one mandatory OETF: the chain upstream is linear (sRGB attachments+ // decode on sample), the canvas backbuffer is plain UNORM.+ fragColor = vec4(linearToSrgb(c.rgb), c.a);+#else+ fragColor = c;+#endif}#pragma end#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {- return textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ let c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+#ifdef ES_LINEAR+ return vec4f(linearToSrgb(c.rgb), c.a);+#else+ return c;+#endif}#pragma enddiff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cppindex b8233074a..5c589d0e0 100644--- a/src/esengine/renderer/PostProcessPipeline.cpp+++ b/src/esengine/renderer/PostProcessPipeline.cpp@@ -66,11 +66,17 @@ void PostProcessPipeline::init(u32 width, u32 height) {}void PostProcessPipeline::ensureFBOs() {+ // Linear mode stores intermediates sRGB-encoded: 8-bit precision stays+ // perceptually uniform while blending happens in linear light (hardware+ // EOTF/OETF at the attachment boundary).+ const GfxPixelFormat interFmt =+ linear_output_ ? GfxPixelFormat::SRGB8_ALPHA8 : GfxPixelFormat::RGBA8;if (!fboOriginalCreated_) {FramebufferSpec origSpec;origSpec.width = width_;origSpec.height = height_;origSpec.depthStencil = false;+ origSpec.colorFormat = interFmt;fboOriginal_ = Framebuffer::create(device_, origSpec);if (!fboOriginal_) {@@ -86,6 +92,7 @@ void PostProcessPipeline::ensureFBOs() {spec.width = width_;spec.height = height_;spec.depthStencil = false;+ spec.colorFormat = interFmt;fboA_ = Framebuffer::create(device_, spec);fboB_ = Framebuffer::create(device_, spec);@@ -298,7 +305,7 @@ FramebufferHandle PostProcessPipeline::currentSceneFBO() const {}void PostProcessPipeline::begin(const f32* clearColor) {- if (!initialized_ || inFrame_ || bypass_) return;+ if (!initialized_ || inFrame_ || (bypass_ && !linear_output_)) return;ensureFBOs();if (!fboOriginalCreated_) return;@@ -306,6 +313,14 @@ void PostProcessPipeline::begin(const f32* clearColor) {RenderPassDesc pass{fboOriginal_->handle(), /*clearColor=*/true, /*clearDepth=*/true};if (clearColor) {for (int i = 0; i < 4; ++i) pass.clearColorValue[i] = clearColor[i];+ if (linear_output_) {+ // Authored sRGB -> linear; the sRGB attachment re-encodes on store.+ for (int i = 0; i < 3; ++i) {+ const f32 v = pass.clearColorValue[i];+ pass.clearColorValue[i] =+ v <= 0.04045f ? v / 12.92f : std::pow((v + 0.055f) / 1.055f, 2.4f);+ }+ }}device_.beginRenderPass(pass);device_.setViewport(0, 0, width_, height_);@@ -315,7 +330,7 @@ void PostProcessPipeline::begin(const f32* clearColor) {}void PostProcessPipeline::end() {- if (!initialized_ || !inFrame_ || bypass_) return;+ if (!initialized_ || !inFrame_ || (bypass_ && !linear_output_)) return;auto* device = &device_;@@ -504,6 +519,7 @@ void PostProcessPipeline::ensureScreenFBO() {if (screenFBOCreated_) return;FramebufferSpec spec;+ spec.colorFormat = linear_output_ ? GfxPixelFormat::SRGB8_ALPHA8 : GfxPixelFormat::RGBA8;spec.width = width_;spec.height = height_;spec.depthStencil = false;diff --git a/src/esengine/renderer/PostProcessPipeline.hpp b/src/esengine/renderer/PostProcessPipeline.hppindex 2a0569f1e..21fe6ef6f 100644--- a/src/esengine/renderer/PostProcessPipeline.hpp+++ b/src/esengine/renderer/PostProcessPipeline.hpp@@ -173,6 +173,14 @@ public:*/void setBypass(bool bypass) { bypass_ = bypass; }+ /**+ * @brief Linear-light mode: sRGB-format intermediates (hardware linear+ * blending) and an always-engaged capture+blit whose final pass+ * carries the linear->sRGB encode. Overrides bypass.+ */+ void setLinearOutput(bool linear) { linear_output_ = linear; }+ bool linearOutput() const { return linear_output_; }+/*** @brief Checks if bypass mode is enabled*/@@ -274,6 +282,7 @@ private:bool fboOriginalCreated_ = false;bool inFrame_ = false;bool bypass_ = false;+ bool linear_output_ = false;u32 currentFBO_ = 0;TextureHandle sceneTexture_ = TextureHandle::Invalid;diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cppindex 79d3cf640..21eb8084d 100644--- a/src/esengine/renderer/RenderFrame.cpp+++ b/src/esengine/renderer/RenderFrame.cpp@@ -19,6 +19,8 @@namespace esengine {+glm::vec3 srgbToLinearCpu(const glm::vec3& c);+void GpuTimer::begin(GfxDevice& device) {if (state_ == 0) {// Lazy probe: the device reports timer support by whether it can create a query.@@ -128,8 +130,13 @@ void RenderFrame::init(u32 width, u32 height) {// state_tracker_ is inited once by EstellaContext (its owner); flush()/replay// reset() it each frame, so no per-RenderFrame init is needed here.+ // Adopt the boot-declared color space before any shader compiles below —+ // renderer_setColorSpace may run before this frame exists (pre-init).+ linear_color_ = resource::ShaderParser::linearColorSpace();+#ifdef ES_ENABLE_POSTPROCESSpost_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_);+ post_process_->setLinearOutput(linear_color_);post_process_->init(width, height);#endif@@ -199,8 +206,12 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Hclip_state_.clear();#ifdef ES_ENABLE_POSTPROCESS+ // Linear mode keeps the capture+blit engaged even with zero passes: the+ // final blit is where the mandatory linear->sRGB encode lives (the WebGL2+ // canvas framebuffer cannot be made sRGB).bool usePostProcess = post_process_ && post_process_->isInitialized() &&- !post_process_->isBypassed() && post_process_->getPassCount() > 0;+ ((!post_process_->isBypassed() && post_process_->getPassCount() > 0)+ || linear_color_);#elsebool usePostProcess = false;#endif@@ -211,9 +222,13 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::HRenderPassDesc pass{};pass.clearColor = clear.color;pass.clearDepth = clear.depth;- pass.clearColorValue[0] = clear.colorValue.r;- pass.clearColorValue[1] = clear.colorValue.g;- pass.clearColorValue[2] = clear.colorValue.b;+ // Authored clear colors are sRGB; the linear frame clears in linear light.+ const glm::vec3 clearRgb = linear_color_+ ? srgbToLinearCpu({clear.colorValue.r, clear.colorValue.g, clear.colorValue.b})+ : glm::vec3{clear.colorValue.r, clear.colorValue.g, clear.colorValue.b};+ pass.clearColorValue[0] = clearRgb.r;+ pass.clearColorValue[1] = clearRgb.g;+ pass.clearColorValue[2] = clearRgb.b;pass.clearColorValue[3] = clear.colorValue.a;pass.clearX = clear.x;pass.clearY = clear.y;@@ -324,8 +339,12 @@ void RenderFrame::end() {}#ifdef ES_ENABLE_POSTPROCESS+ // Linear mode keeps the capture+blit engaged even with zero passes: the+ // final blit is where the mandatory linear->sRGB encode lives (the WebGL2+ // canvas framebuffer cannot be made sRGB).bool usePostProcess = post_process_ && post_process_->isInitialized() &&- !post_process_->isBypassed() && post_process_->getPassCount() > 0;+ ((!post_process_->isBypassed() && post_process_->getPassCount() > 0)+ || linear_color_);#elsebool usePostProcess = false;#endif@@ -574,7 +593,10 @@ void RenderFrame::collectLights(ecs::Registry& registry) {if (!light.enabled || light.intensity <= 0.0f) continue;const auto type = static_cast<ecs::Light2DType>(light.type);- const glm::vec3 rgb{light.color}; // color.a is unused; intensity carries the strength+ // color.a is unused; intensity carries the strength. Authored sRGB ->+ // linear when the frame lights in linear space.+ const glm::vec3 rgb = linear_color_ ? srgbToLinearCpu(glm::vec3{light.color})+ : glm::vec3{light.color};if (type == ecs::Light2DType::Ambient) {lights.addAmbient(rgb * light.intensity);continue;@@ -647,6 +669,21 @@ void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {}}+glm::vec3 srgbToLinearCpu(const glm::vec3& c) {+ auto conv = [](f32 v) {+ return v <= 0.04045f ? v / 12.92f : std::pow((v + 0.055f) / 1.055f, 2.4f);+ };+ return {conv(c.r), conv(c.g), conv(c.b)};+}++void RenderFrame::setColorSpace(bool linear) {+ linear_color_ = linear;+ resource::ShaderParser::setLinearColorSpace(linear);+#ifdef ES_ENABLE_POSTPROCESS+ if (post_process_) post_process_->setLinearOutput(linear);+#endif+}+u32 RenderFrame::initBatchShader() {// The default (featureless) batch program; seeds the variant cache.return batchProgram({});diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex 509b656df..d08e0d42c 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -159,6 +159,16 @@ public:/// Layers (bits 0..31) that sort by world Y within the layer — see DrawList::setYSortMask.void setYSortLayers(u32 mask) { draw_list_.setYSortMask(mask); }+ /**+ * @brief Switch the frame to linear-light rendering (project colorSpace).+ * @details Sets the global ES_LINEAR shader input, linearizes CPU-side+ * authored colors (lights, clears), and forces the post-process+ * capture+blit so the final OETF encode always runs. Call before+ * shaders compile; a later flip requires a reload.+ */+ void setColorSpace(bool linear);+ bool linearColor() const { return linear_color_; }+void replayToDrawCall(i32 stopAtDrawCall);const u8* getSnapshotPixels() const { return snapshot_pixels_.data(); }u32 getSnapshotSize() const { return static_cast<u32>(snapshot_pixels_.size()); }@@ -254,6 +264,7 @@ private:std::unordered_map<std::string, u32> batch_variants_;TransientBufferPool pool_;DrawList draw_list_;+ bool linear_color_ = false;ClipState clip_state_;std::vector<std::unique_ptr<RenderTypePlugin>> plugins_;diff --git a/src/esengine/renderer/ShaderEmbeds.generated.hpp b/src/esengine/renderer/ShaderEmbeds.generated.hppindex cfb721057..0b8aa0d14 100644--- a/src/esengine/renderer/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/ShaderEmbeds.generated.hpp@@ -71,6 +71,13 @@ void main() {else if (v_texIndex == 5) texColor = texture(u_textures[5], v_texCoord);else if (v_texIndex == 6) texColor = texture(u_textures[6], v_texCoord);else texColor = texture(u_textures[7], v_texCoord);+#ifdef ES_LINEAR+ // Vertex colors are authored sRGB; the sampled texel is already linear+ // (sRGB texture formats decode in hardware). Alpha is coverage — never encoded.+ vec4 tint = vec4(srgbToLinear(v_color.rgb), v_color.a);+#else+ vec4 tint = v_color;+#endif#ifdef SDF// The glyph atlas stores a signed distance in the alpha channel (RGB = 1).// Distance ÷ fwidth = screen px from the edge; the ±0.5px clamp is exactly@@ -78,13 +85,13 @@ void main() {float dist = texColor.a;float screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);float coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);- fragColor = vec4(v_color.rgb, v_color.a * coverage);+ fragColor = vec4(tint.rgb, tint.a * coverage);#elif defined(LIT)// Flat normal; the tinted color is the albedo. Normal maps need a material.- vec4 base = texColor * v_color;+ vec4 base = texColor * tint;fragColor = vec4(applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);#else- fragColor = texColor * v_color;+ fragColor = texColor * tint;#endif}#pragma end@@ -163,18 +170,23 @@ struct VSOut {else if (idx == 5) { texColor = textureSampleLevel(t5, s5, v.v_texCoord, 0.0); }else if (idx == 6) { texColor = textureSampleLevel(t6, s6, v.v_texCoord, 0.0); }else { texColor = textureSampleLevel(t7, s7, v.v_texCoord, 0.0); }+#ifdef ES_LINEAR+ let tint = vec4f(srgbToLinear(v.v_color.rgb), v.v_color.a);+#else+ let tint = v.v_color;+#endif#ifdef SDF// Same coverage math as the GLSL stage; fwidth here is in uniform control// flow (main scope), which WGSL requires of derivative builtins.let dist = texColor.a;let screenPxDist = (dist - 0.5) / max(fwidth(dist), 1e-6);let coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);- return vec4f(v.v_color.rgb, v.v_color.a * coverage);+ return vec4f(tint.rgb, tint.a * coverage);#elif defined(LIT)- let base = texColor * v.v_color;+ let base = texColor * tint;return vec4f(applyLighting2D(base.rgb, vec3f(0.0, 0.0, 1.0), v.v_worldPos), base.a);#else- return texColor * v.v_color;+ return texColor * tint;#endif}#pragma end@@ -192,13 +204,25 @@ uniform sampler2D u_texture;out vec4 fragColor;void main() {- fragColor = texture(u_texture, v_texCoord);+ vec4 c = texture(u_texture, v_texCoord);+#ifdef ES_LINEAR+ // The one mandatory OETF: the chain upstream is linear (sRGB attachments+ // decode on sample), the canvas backbuffer is plain UNORM.+ fragColor = vec4(linearToSrgb(c.rgb), c.a);+#else+ fragColor = c;+#endif}#pragma end#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {- return textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ let c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+#ifdef ES_LINEAR+ return vec4f(linearToSrgb(c.rgb), c.a);+#else+ return c;+#endif}#pragma end)esshader";diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex f04e459e8..0359089bc 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -593,6 +593,14 @@ std::string wgslMaterialTextureDecls(const ParsedShader& parsed) {// block matches renderer/LightConstants.hpp on both backends. sampleNormal// takes the de-combined texture+sampler pair and samples mip 0 explicitly,// keeping calls legal in non-uniform control flow.+const char* kColorHelpersWGSL = R"(fn srgbToLinear(c : vec3f) -> vec3f {+ return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3f(2.4)), step(vec3f(0.04045), c));+}+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));+}+)";+const char* kLit2DHeaderWGSL = R"(struct Light2D { posDir : vec4f, color : vec4f, spot : vec4f, shadow : vec4f };struct LightConstants {u_ambient : vec4f,@@ -821,6 +829,7 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,if (stage == ShaderStage::Fragment) {inject(wgslMaterialTextureDecls(parsed));if (lit) inject(kLit2DHeaderWGSL);+ inject(kColorHelpersWGSL);}assembled << bodyIt->second;@@ -832,11 +841,25 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,} // namespace+bool ShaderParser::s_linearColor = false;++void ShaderParser::setLinearColorSpace(bool linear) { s_linearColor = linear; }+bool ShaderParser::linearColorSpace() { return s_linearColor; }+ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& parsed,ShaderStage stage,const std::string& platform,- const std::vector<std::string>& features,+ const std::vector<std::string>& featuresIn,ShaderTargetLanguage target) {+ // The color space is a process-global compile input: every shader — batch+ // variants, plugin shaders, blit, materials, post effects — sees the same+ // ES_LINEAR world with no per-call-site wiring. It must be set before the+ // renderer compiles shaders; flipping it later requires a reload.+ std::vector<std::string> features = featuresIn;+ if (s_linearColor+ && std::find(features.begin(), features.end(), "ES_LINEAR") == features.end()) {+ features.push_back("ES_LINEAR");+ }if (target == ShaderTargetLanguage::WGSL) {return assembleWGSLStage(parsed, stage, features);}@@ -863,6 +886,21 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p++headerLines;}+ // sRGB transfer helpers, available to every fragment stage in both modes —+ // authored bodies branch on ES_LINEAR. Exact piecewise IEC 61966-2-1, so the+ // CPU-side conversions (light/clear colors) match bit-for-bit within fp32.+ if (stage == ShaderStage::Fragment) {+ static const char* kColorHelpers =+ "highp vec3 srgbToLinear(highp vec3 c) {\n"+ " return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(0.04045, c));\n"+ "}\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";+ assembled << kColorHelpers;+ headerLines += countNewlines(kColorHelpers);+ }+// Engine-owned frame block, injected into every stage (identical in both, so the// program links). u_time = (elapsed s, delta s, 0, 0); u_viewport = canvas// (w, h, 1/w, 1/h) in pixels; binding 3 (Shader::compile).diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hppindex 2ca36288e..7cead5f29 100644--- a/src/esengine/resource/ShaderParser.hpp+++ b/src/esengine/resource/ShaderParser.hpp@@ -278,6 +278,16 @@ public:*/static std::string variantKey(const std::vector<std::string>& features);+ /**+ * @brief Process-global color-space mode. When linear, every assembled+ * stage compiles with ES_LINEAR defined (GLSL #define / WGSL+ * assembly-time preprocessor). Set BEFORE the renderer compiles+ * shaders; flipping later requires a reload. Variant caches must+ * fold linearColorSpace() into their keys if they can outlive a flip.+ */+ static void setLinearColorSpace(bool linear);+ static bool linearColorSpace();+/*** @brief Like assembleStage, but also reports the line count of the* assembled prefix (version + variant + sharedCode).@@ -333,6 +343,10 @@ private:static ShaderPropertyType stringToPropertyType(const std::string& typeStr);static std::string trim(const std::string& str);++private:+ static bool s_linearColor;+};} // namespace esengine::resource