Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(renderer): the linear-light pipeline - colorSpace: 'linear' renders physically

esengine112f21cd5080
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 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.ts
index 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.ts
index 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.md
index 959788fae..1930c09ac 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1670,6 +1670,7 @@ world: World
```
backend: "webgl2" | "webgpu" | undefined
canvasSelector: string | undefined
+colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
@@ -2155,6 +2156,7 @@ renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => vo
renderer_replayToDrawCall: (drawCallIndex: number) => void
renderer_resize: (width: number, height: number) => void
renderer_setClearColor: (r: number, g: number, b: number, a: number) => void
+renderer_setColorSpace: ((linear: number) => void) | undefined
renderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => void
renderer_setEntityStencilMask: (entity: number, refValue: number) => void
renderer_setEntityStencilTest: (entity: number, refValue: number) => void
@@ -6992,6 +6994,7 @@ static prototype: WeChatSocket
```
backend: "webgl2" | "webgpu" | undefined
canvasSelector: string | undefined
+colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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" | undefined
canvasSelector: string | undefined
+colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
@@ -2150,6 +2151,7 @@ renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => vo
renderer_replayToDrawCall: (drawCallIndex: number) => void
renderer_resize: (width: number, height: number) => void
renderer_setClearColor: (r: number, g: number, b: number, a: number) => void
+renderer_setColorSpace: ((linear: number) => void) | undefined
renderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => void
renderer_setEntityStencilMask: (entity: number, refValue: number) => void
renderer_setEntityStencilTest: (entity: number, refValue: number) => void
@@ -6987,6 +6989,7 @@ static prototype: WeChatSocket
```
backend: "webgl2" | "webgpu" | undefined
canvasSelector: string | undefined
+colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
glContextHandle: number | undefined
plugins: Plugin[] | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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) => vo
renderer_replayToDrawCall: (drawCallIndex: number) => void
renderer_resize: (width: number, height: number) => void
renderer_setClearColor: (r: number, g: number, b: number, a: number) => void
+renderer_setColorSpace: ((linear: number) => void) | undefined
renderer_setEntityClipRect: (entity: number, x: number, y: number, w: number, h: number) => void
renderer_setEntityStencilMask: (entity: number, refValue: number) => void
renderer_setEntityStencilTest: (entity: number, refValue: number) => void
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 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): A
app.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.ts
index 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 Team
import 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.ts
index 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.ts
index 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 API
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 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.hpp
index 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.cpp
index 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.esshader
index 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 end
diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshader
index 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 end
diff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cpp
index 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.hpp
index 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.cpp
index 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_POSTPROCESS
post_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::H
clip_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_);
#else
bool usePostProcess = false;
#endif
@@ -211,9 +222,13 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::H
RenderPassDesc 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_);
#else
bool 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.hpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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