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): color textures upload sRGB under the linear pipeline
yhh7a2210cd6ff9
diff --git a/desktop/public/scenes/srgb-midtone.esscene b/desktop/public/scenes/srgb-midtone.esscenenew file mode 100644index 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.pngnew file mode 100644index 000000000..e4a9637a7Binary files /dev/null and b/desktop/public/scenes/srgb-midtone.png differdiff --git a/desktop/public/scenes/srgb-midtone.textures.json b/desktop/public/scenes/srgb-midtone.textures.jsonnew file mode 100644index 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.tsindex 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): Compastc: 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: Compresexport 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.tsindex 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.tsindex 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.cppindex 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);