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): color textures upload sRGB under the linear pipeline

yhh7a2210cd6ff9
diff --git a/desktop/public/scenes/srgb-midtone.esscene b/desktop/public/scenes/srgb-midtone.esscene
new file mode 100644
index 000000000..4d5a0ac36
--- /dev/null
+++ b/desktop/public/scenes/srgb-midtone.esscene
@@ -0,0 +1,28 @@
+{
+ "version": "1.0",
+ "name": "sRGB Midtone Roundtrip",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "MidGray",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Sprite", "data": { "size": { "x": 300, "y": 300 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "texture": "@uuid:5d6b1a2e-90c4-4f7a-8b3d-2f81c0a4e5f6" } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/srgb-midtone.png b/desktop/public/scenes/srgb-midtone.png
new file mode 100644
index 000000000..e4a9637a7
Binary files /dev/null and b/desktop/public/scenes/srgb-midtone.png differ
diff --git a/desktop/public/scenes/srgb-midtone.textures.json b/desktop/public/scenes/srgb-midtone.textures.json
new file mode 100644
index 000000000..f0adc78c2
--- /dev/null
+++ b/desktop/public/scenes/srgb-midtone.textures.json
@@ -0,0 +1,3 @@
+{
+ "5d6b1a2e-90c4-4f7a-8b3d-2f81c0a4e5f6": "/scenes/srgb-midtone.png"
+}
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.ts
index 4c4dc1c90..cdce90da7 100644
--- a/sdk/src/asset/compressed.ts
+++ b/sdk/src/asset/compressed.ts
@@ -88,15 +88,25 @@ export interface BasisTranscoder {
// =============================================================================
// Minimal shapes for the extension constants we read — robust to lib.dom not
-// typing every getExtension overload (some omit the ETC one).
-interface AstcExt { readonly COMPRESSED_RGBA_ASTC_4x4_KHR: number }
-interface EtcExt { readonly COMPRESSED_RGBA8_ETC2_EAC: number }
+// typing every getExtension overload (some omit the ETC one). The ASTC/ETC
+// extensions expose their sRGB variants on the same object; S3TC splits sRGB
+// into a separate extension (WEBGL_compressed_texture_s3tc_srgb).
+interface AstcExt {
+ readonly COMPRESSED_RGBA_ASTC_4x4_KHR: number;
+ readonly COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR: number;
+}
+interface EtcExt {
+ readonly COMPRESSED_RGBA8_ETC2_EAC: number;
+ readonly COMPRESSED_SRGB8_ALPHA8_ETC2_EAC: number;
+}
interface S3tcExt { readonly COMPRESSED_RGBA_S3TC_DXT5_EXT: number }
+interface S3tcSrgbExt { readonly COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT: number }
export interface CompressedTextureSupport {
readonly astc: AstcExt | null;
readonly etc: EtcExt | null;
readonly s3tc: S3tcExt | null;
+ readonly s3tcSrgb: S3tcSrgbExt | null;
}
/**
@@ -109,25 +119,41 @@ export function detectCompressedTextureSupport(gl: WebGL2RenderingContext): Comp
astc: gl.getExtension('WEBGL_compressed_texture_astc') as AstcExt | null,
etc: gl.getExtension('WEBGL_compressed_texture_etc') as EtcExt | null,
s3tc: gl.getExtension('WEBGL_compressed_texture_s3tc') as S3tcExt | null,
+ s3tcSrgb: gl.getExtension('WEBGL_compressed_texture_s3tc_srgb') as S3tcSrgbExt | null,
};
}
-/** Best available target in quality/size order: ASTC > ETC2 > S3TC. null = none. */
-export function chooseTargetFormat(support: CompressedTextureSupport): CompressedTextureFormat | null {
+/**
+ * Best available target in quality/size order: ASTC > ETC2 > S3TC. null = none.
+ * With `srgb` (linear pipeline) a format only qualifies when its sRGB variant is
+ * uploadable — S3TC needs the separate s3tc_srgb extension; ASTC/ETC2 sRGB ride
+ * the same extension as their UNORM twins. The transcoded block data is
+ * identical either way; only the sampling interpretation differs.
+ */
+export function chooseTargetFormat(
+ support: CompressedTextureSupport, srgb = false,
+): CompressedTextureFormat | null {
if (support.astc) return CompressedTextureFormat.ASTC_4x4;
if (support.etc) return CompressedTextureFormat.ETC2_RGBA8;
- if (support.s3tc) return CompressedTextureFormat.S3TC_DXT5;
+ if (srgb ? support.s3tcSrgb : support.s3tc) return CompressedTextureFormat.S3TC_DXT5;
return null;
}
/** WebGL `internalformat` enum for a chosen format, from its enabling extension. */
-export function glInternalFormat(support: CompressedTextureSupport, fmt: CompressedTextureFormat): number | null {
+export function glInternalFormat(
+ support: CompressedTextureSupport, fmt: CompressedTextureFormat, srgb = false,
+): number | null {
switch (fmt) {
case CompressedTextureFormat.ASTC_4x4:
- return support.astc ? support.astc.COMPRESSED_RGBA_ASTC_4x4_KHR : null;
+ if (!support.astc) return null;
+ return srgb ? support.astc.COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR
+ : support.astc.COMPRESSED_RGBA_ASTC_4x4_KHR;
case CompressedTextureFormat.ETC2_RGBA8:
- return support.etc ? support.etc.COMPRESSED_RGBA8_ETC2_EAC : null;
+ if (!support.etc) return null;
+ return srgb ? support.etc.COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
+ : support.etc.COMPRESSED_RGBA8_ETC2_EAC;
case CompressedTextureFormat.S3TC_DXT5:
+ if (srgb) return support.s3tcSrgb ? support.s3tcSrgb.COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT : null;
return support.s3tc ? support.s3tc.COMPRESSED_RGBA_S3TC_DXT5_EXT : null;
}
return null;
@@ -140,6 +166,8 @@ export function glInternalFormat(support: CompressedTextureSupport, fmt: Compres
export interface CompressedUploadOptions {
readonly filter?: 'linear' | 'nearest';
readonly wrap?: 'repeat' | 'clamp' | 'mirror';
+ /** Linear pipeline: store sRGB-encoded so the sampler linearizes in hardware. */
+ readonly srgb?: boolean;
}
export interface UploadedTexture {
@@ -187,7 +215,7 @@ export function uploadCompressedTexture(
support: CompressedTextureSupport, fmt: CompressedTextureFormat,
t: TranscodeResult, opts?: CompressedUploadOptions,
): UploadedTexture {
- const internalFormat = glInternalFormat(support, fmt);
+ const internalFormat = glInternalFormat(support, fmt, opts?.srgb ?? false);
if (internalFormat == null) throw new Error(`compressed upload: no GL internalformat for ${fmt}`);
const texture = gl.createTexture();
if (!texture) throw new Error('compressed upload: gl.createTexture failed');
@@ -214,7 +242,10 @@ export function uploadRgbaTexture(
if (!texture) throw new Error('rgba upload: gl.createTexture failed');
try {
gl.bindTexture(gl.TEXTURE_2D, texture);
- gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, r.width, r.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, r.data);
+ // Linear pipeline: the decoded pixels are sRGB-encoded color, same as
+ // the PNG path — store them in an sRGB format so sampling linearizes.
+ const internalFormat = opts?.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA;
+ gl.texImage2D(gl.TEXTURE_2D, 0, internalFormat, r.width, r.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, r.data);
applyParams(gl, opts);
} catch (err) {
// Release the GL texture if the upload throws — don't leak it.
@@ -238,7 +269,7 @@ export function loadCompressedTexture(
transcoder: BasisTranscoder, bytes: Uint8Array, opts?: CompressedUploadOptions,
): UploadedTexture {
const support = detectCompressedTextureSupport(gl);
- const target = chooseTargetFormat(support);
+ const target = chooseTargetFormat(support, opts?.srgb ?? false);
if (target !== null) {
const t = transcoder.transcode(bytes, target);
if (t) return uploadCompressedTexture(gl, module, support, target, t, opts);
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index e7617e1b6..f3d79df2c 100644
--- a/sdk/src/asset/loaders/TextureLoader.ts
+++ b/sdk/src/asset/loaders/TextureLoader.ts
@@ -192,7 +192,10 @@ export class TextureLoader implements AssetLoader<TextureResult> {
if (!transcoder) {
throw new Error('TextureLoader: no Basis transcoder available (basis side module missing — KTX2 assets need it)');
}
- const r = loadCompressedTexture(gl, this.module_, transcoder, bytes, settings);
+ // KTX2 payloads are color, like the PNG path: linear mode wants the
+ // sRGB variant of whatever compressed format the device supports.
+ const r = loadCompressedTexture(gl, this.module_, transcoder, bytes,
+ { ...settings, srgb: linearColorSpace() });
return { handle: r.handle, width: r.width, height: r.height };
}
diff --git a/sdk/tests/compressed-texture.test.ts b/sdk/tests/compressed-texture.test.ts
index 1f45d7983..22ababb89 100644
--- a/sdk/tests/compressed-texture.test.ts
+++ b/sdk/tests/compressed-texture.test.ts
@@ -13,17 +13,26 @@ import {
type BasisTranscoder,
} from '../src/asset/compressed';
-const ASTC = 0x93b0; // COMPRESSED_RGBA_ASTC_4x4_KHR
-const ETC2 = 0x9278; // COMPRESSED_RGBA8_ETC2_EAC
-const DXT5 = 0x83f3; // COMPRESSED_RGBA_S3TC_DXT5_EXT
-
-function makeGl(support: { astc?: boolean; etc?: boolean; s3tc?: boolean } = {}) {
+const ASTC = 0x93b0; // COMPRESSED_RGBA_ASTC_4x4_KHR
+const ETC2 = 0x9278; // COMPRESSED_RGBA8_ETC2_EAC
+const DXT5 = 0x83f3; // COMPRESSED_RGBA_S3TC_DXT5_EXT
+const ASTC_SRGB = 0x93d0; // COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR
+const ETC2_SRGB = 0x9279; // COMPRESSED_SRGB8_ALPHA8_ETC2_EAC
+const DXT5_SRGB = 0x8c4f; // COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT
+const SRGB8_ALPHA8 = 0x8c43;
+
+function makeGl(support: { astc?: boolean; etc?: boolean; s3tc?: boolean; s3tcSrgb?: boolean } = {}) {
const exts: Record<string, unknown> = {};
- if (support.astc) exts['WEBGL_compressed_texture_astc'] = { COMPRESSED_RGBA_ASTC_4x4_KHR: ASTC };
- if (support.etc) exts['WEBGL_compressed_texture_etc'] = { COMPRESSED_RGBA8_ETC2_EAC: ETC2 };
+ if (support.astc) exts['WEBGL_compressed_texture_astc'] = {
+ COMPRESSED_RGBA_ASTC_4x4_KHR: ASTC, COMPRESSED_SRGB8_ALPHA8_ASTC_4x4_KHR: ASTC_SRGB,
+ };
+ if (support.etc) exts['WEBGL_compressed_texture_etc'] = {
+ COMPRESSED_RGBA8_ETC2_EAC: ETC2, COMPRESSED_SRGB8_ALPHA8_ETC2_EAC: ETC2_SRGB,
+ };
if (support.s3tc) exts['WEBGL_compressed_texture_s3tc'] = { COMPRESSED_RGBA_S3TC_DXT5_EXT: DXT5 };
+ if (support.s3tcSrgb) exts['WEBGL_compressed_texture_s3tc_srgb'] = { COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT: DXT5_SRGB };
return {
- TEXTURE_2D: 0x0de1, RGBA: 0x1908, UNSIGNED_BYTE: 0x1401,
+ TEXTURE_2D: 0x0de1, RGBA: 0x1908, UNSIGNED_BYTE: 0x1401, SRGB8_ALPHA8,
NEAREST: 0x2600, LINEAR: 0x2601, CLAMP_TO_EDGE: 0x812f, MIRRORED_REPEAT: 0x8370, REPEAT: 0x2901,
TEXTURE_MIN_FILTER: 0x2801, TEXTURE_MAG_FILTER: 0x2800, TEXTURE_WRAP_S: 0x2802, TEXTURE_WRAP_T: 0x2803,
getExtension: vi.fn((n: string) => exts[n] ?? null),
@@ -84,6 +93,21 @@ describe('format capability selection', () => {
expect(glInternalFormat(s, CompressedTextureFormat.ETC2_RGBA8)).toBe(ETC2);
expect(glInternalFormat(s, CompressedTextureFormat.S3TC_DXT5)).toBe(DXT5);
});
+ it('srgb maps to the sRGB variant constants (linear pipeline)', () => {
+ const s = detectCompressedTextureSupport(
+ makeGl({ astc: true, etc: true, s3tc: true, s3tcSrgb: true }) as never);
+ expect(glInternalFormat(s, CompressedTextureFormat.ASTC_4x4, true)).toBe(ASTC_SRGB);
+ expect(glInternalFormat(s, CompressedTextureFormat.ETC2_RGBA8, true)).toBe(ETC2_SRGB);
+ expect(glInternalFormat(s, CompressedTextureFormat.S3TC_DXT5, true)).toBe(DXT5_SRGB);
+ });
+ it('srgb S3TC requires the separate s3tc_srgb extension', () => {
+ // Base s3tc alone cannot upload sRGB DXT blocks: no target, no internalformat.
+ const s = detectCompressedTextureSupport(makeGl({ s3tc: true }) as never);
+ expect(chooseTargetFormat(s, true)).toBeNull();
+ expect(glInternalFormat(s, CompressedTextureFormat.S3TC_DXT5, true)).toBeNull();
+ const withSrgb = detectCompressedTextureSupport(makeGl({ s3tc: true, s3tcSrgb: true }) as never);
+ expect(chooseTargetFormat(withSrgb, true)).toBe(CompressedTextureFormat.S3TC_DXT5);
+ });
});
describe('loadCompressedTexture', () => {
@@ -130,6 +154,19 @@ describe('loadCompressedTexture', () => {
const transcoder = makeTranscoder({ transcode: vi.fn(() => null), transcodeToRgba: vi.fn(() => null) });
expect(() => loadCompressedTexture(gl as never, makeModule() as never, transcoder, KTX2_HEADER)).toThrow(/failed to decode/i);
});
+
+ it('srgb uploads the sRGB internalformat of the chosen format', () => {
+ const gl = makeGl({ astc: true });
+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER, { srgb: true });
+ expect(gl.compressedTexImage2D.mock.calls[0][2]).toBe(ASTC_SRGB);
+ });
+
+ it('srgb RGBA fallback stores SRGB8_ALPHA8', () => {
+ const gl = makeGl(); // no compressed support → RGBA path
+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER, { srgb: true });
+ expect(gl.texImage2D).toHaveBeenCalledTimes(1);
+ expect(gl.texImage2D.mock.calls[0][2]).toBe(SRGB8_ALPHA8);
+ });
});
describe('uploadCompressedTexture', () => {
diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cpp
index 2213bf178..d19022b44 100644
--- a/src/esengine/bindings/ResourceManagerBindings.cpp
+++ b/src/esengine/bindings/ResourceManagerBindings.cpp
@@ -3,6 +3,7 @@
#include "ResourceManagerBindings.hpp"
#include "BoundarySpan.hpp"
+#include "../resource/ShaderParser.hpp"
#include "../resource/TextureMetadata.hpp"
#include "../text/BitmapFont.hpp"
#include "../core/Types.hpp"
@@ -12,17 +13,29 @@
namespace esengine {
+namespace {
+
+/**
+ * Pixel uploads crossing the JS boundary are color images (decoded PNGs, spine
+ * atlases, glyph atlases, tileset collages) — the same "all image textures are
+ * color" contract the SDK's raw-GL upload path applies. Linear mode stores them
+ * sRGB-encoded so the sampler linearizes in hardware, on both backends.
+ */
+TextureFormat boundaryTextureFormat(i32 format) {
+ if (format == 0) return TextureFormat::RGB8;
+ if (resource::ShaderParser::linearColorSpace()) return TextureFormat::SRGB8A8;
+ return TextureFormat::RGBA8;
+}
+
+} // namespace
+
u32 rm_createTexture(resource::ResourceManager& rm, u32 width, u32 height,
uintptr_t pixelsPtr, u32 pixelsLen, i32 format, bool flipY) {
const u8* pixels = boundarySpan<u8>(pixelsPtr, pixelsLen, "rm_createTexture");
if (!pixels) return 0;
ConstSpan<u8> pixelSpan(pixels, pixelsLen);
- TextureFormat texFormat = TextureFormat::RGBA8;
- if (format == 0) texFormat = TextureFormat::RGB8;
- else if (format == 1) texFormat = TextureFormat::RGBA8;
-
- auto handle = rm.createTexture(width, height, pixelSpan, texFormat, flipY);
+ auto handle = rm.createTexture(width, height, pixelSpan, boundaryTextureFormat(format), flipY);
return handle.id();
}
@@ -32,9 +45,7 @@ u32 rm_createTextureEx(resource::ResourceManager& rm, u32 width, u32 height,
const u8* pixels = pixelsPtr ? boundarySpan<u8>(pixelsPtr, pixelsLen, "rm_createTextureEx") : nullptr;
if (pixelsPtr && !pixels) return 0;
- TextureFormat texFormat = TextureFormat::RGBA8;
- if (format == 0) texFormat = TextureFormat::RGB8;
- else if (format == 1) texFormat = TextureFormat::RGBA8;
+ const TextureFormat texFormat = boundaryTextureFormat(format);
TextureSpecification spec;
spec.width = width;
@@ -59,7 +70,7 @@ u32 rm_createTextureEx(resource::ResourceManager& rm, u32 width, u32 height,
auto* texture = rm.getTexture(handle);
if (texture && pixels) {
- const u64 required = static_cast<u64>(width) * height * (texFormat == TextureFormat::RGBA8 ? 4 : 3);
+ const u64 required = static_cast<u64>(width) * height * (texFormat == TextureFormat::RGB8 ? 3 : 4);
if (pixelsLen < required) {
ES_LOG_ERROR("rm_createTextureEx: pixel buffer {} < required {}; upload skipped",
pixelsLen, required);