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(rc6): KTX2 compressed-texture loader architecture (Batch C1)
esenginec3873287af69
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.tsnew file mode 100644index 000000000..6a4359f42--- /dev/null+++ b/sdk/src/asset/compressed.ts@@ -0,0 +1,211 @@+/**+ * Compressed-texture loading (KTX2 / Basis Universal) — RC6 Batch C.+ *+ * Decoded textures stay GPU-compressed in VRAM (4–8× smaller than RGBA8), the key+ * constraint on mobile. The actual transcode is done by a wasm side-module behind+ * the {@link BasisTranscoder} seam (Batch C3); this module owns the device+ * capability probe, the format choice, and the WebGL upload — all testable without+ * the wasm.+ *+ * Upload is JS-direct (`gl.compressedTexImage2D`) to mirror the existing+ * `TextureLoader` PNG path, and because WebGL compressed-texture extensions must be+ * enabled JS-side via `getExtension`. The C++ `GfxDevice::compressedTexImage2D`+ * entry (RC6-A) backs the non-WebGL2 fallback path instead.+ */+import type { ESEngineModule } from '../wasm';+import { requireResourceManager } from '../resourceManager';++// =============================================================================+// Format vocabulary+// =============================================================================++/**+ * GPU compressed formats the transcoder can target, mirroring the C+++ * `GfxCompressedFormat`. ASTC is best quality/size, ETC2 is the WebGL2 baseline,+ * S3TC covers desktop GPUs.+ */+export enum CompressedTextureFormat {+ ETC2_RGBA8 = 'etc2-rgba8',+ ASTC_4x4 = 'astc-4x4',+ S3TC_DXT5 = 's3tc-dxt5',+}++const KTX2_IDENTIFIER = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];++/** True if `bytes` begins with the 12-byte KTX2 file identifier. */+export function isKtx2(bytes: Uint8Array): boolean {+ if (bytes.length < KTX2_IDENTIFIER.length) return false;+ for (let i = 0; i < KTX2_IDENTIFIER.length; i++) {+ if (bytes[i] !== KTX2_IDENTIFIER[i]) return false;+ }+ return true;+}++// =============================================================================+// Transcoder seam+// =============================================================================++export interface TranscodeResult {+ readonly width: number;+ readonly height: number;+ /** GPU-ready compressed block data for the requested format. */+ readonly data: Uint8Array;+}++export interface RgbaResult {+ readonly width: number;+ readonly height: number;+ /** width*height*4 RGBA8 bytes. */+ readonly data: Uint8Array;+}++/**+ * Decodes a KTX2/Basis container into GPU-ready bytes. The concrete implementation+ * is a wasm side-module (Batch C3) injected behind this interface, so the loader+ * decision logic stays unit-testable without it.+ */+export interface BasisTranscoder {+ /** Transcode to a device-supported compressed format, or null if it cannot. */+ transcode(ktx2: Uint8Array, target: CompressedTextureFormat): TranscodeResult | null;+ /** Decode to uncompressed RGBA8 — the universal fallback. */+ transcodeToRgba(ktx2: Uint8Array): RgbaResult | null;+}++// =============================================================================+// Device capability probe+// =============================================================================++// 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 }+interface S3tcExt { readonly COMPRESSED_RGBA_S3TC_DXT5_EXT: number }++export interface CompressedTextureSupport {+ readonly astc: AstcExt | null;+ readonly etc: EtcExt | null;+ readonly s3tc: S3tcExt | null;+}++/**+ * Probes — and, crucially, *enables* — the WebGL compressed-texture extensions.+ * `getExtension` is the only way to turn an extension on, so this must run before+ * any `compressedTexImage2D` with a non-core format.+ */+export function detectCompressedTextureSupport(gl: WebGL2RenderingContext): CompressedTextureSupport {+ return {+ 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,+ };+}++/** Best available target in quality/size order: ASTC > ETC2 > S3TC. null = none. */+export function chooseTargetFormat(support: CompressedTextureSupport): CompressedTextureFormat | null {+ if (support.astc) return CompressedTextureFormat.ASTC_4x4;+ if (support.etc) return CompressedTextureFormat.ETC2_RGBA8;+ if (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 {+ switch (fmt) {+ case CompressedTextureFormat.ASTC_4x4:+ return support.astc ? support.astc.COMPRESSED_RGBA_ASTC_4x4_KHR : null;+ case CompressedTextureFormat.ETC2_RGBA8:+ return support.etc ? support.etc.COMPRESSED_RGBA8_ETC2_EAC : null;+ case CompressedTextureFormat.S3TC_DXT5:+ return support.s3tc ? support.s3tc.COMPRESSED_RGBA_S3TC_DXT5_EXT : null;+ }+ return null;+}++// =============================================================================+// Upload+// =============================================================================++export interface CompressedUploadOptions {+ readonly filter?: 'linear' | 'nearest';+ readonly wrap?: 'repeat' | 'clamp' | 'mirror';+}++export interface UploadedTexture {+ readonly handle: number;+ readonly width: number;+ readonly height: number;+}++function applyParams(gl: WebGL2RenderingContext, opts?: CompressedUploadOptions): void {+ // Single-level textures: never select a mipmap min-filter (would be incomplete).+ const mag = opts?.filter === 'nearest' ? gl.NEAREST : gl.LINEAR;+ const min = mag;+ const wrap =+ opts?.wrap === 'clamp' ? gl.CLAMP_TO_EDGE :+ opts?.wrap === 'mirror' ? gl.MIRRORED_REPEAT :+ gl.REPEAT;+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, min);+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, mag);+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);+ gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);+}++function registerGlTexture(module: ESEngineModule, texture: WebGLTexture, width: number, height: number): number {+ const glObj = module.GL;+ const id = glObj.getNewId(glObj.textures);+ glObj.textures[id] = texture;+ return requireResourceManager().registerExternalTexture(id, width, height);+}++/** Upload pre-transcoded compressed blocks via `gl.compressedTexImage2D`. */+export function uploadCompressedTexture(+ gl: WebGL2RenderingContext, module: ESEngineModule,+ support: CompressedTextureSupport, fmt: CompressedTextureFormat,+ t: TranscodeResult, opts?: CompressedUploadOptions,+): UploadedTexture {+ const internalFormat = glInternalFormat(support, fmt);+ 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');+ gl.bindTexture(gl.TEXTURE_2D, texture);+ gl.compressedTexImage2D(gl.TEXTURE_2D, 0, internalFormat, t.width, t.height, 0, t.data);+ applyParams(gl, opts);+ return { handle: registerGlTexture(module, texture, t.width, t.height), width: t.width, height: t.height };+}++/** Fallback: upload decoded RGBA8 via `gl.texImage2D`. */+export function uploadRgbaTexture(+ gl: WebGL2RenderingContext, module: ESEngineModule, r: RgbaResult, opts?: CompressedUploadOptions,+): UploadedTexture {+ const texture = gl.createTexture();+ if (!texture) throw new Error('rgba upload: gl.createTexture failed');+ 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);+ applyParams(gl, opts);+ return { handle: registerGlTexture(module, texture, r.width, r.height), width: r.width, height: r.height };+}++// =============================================================================+// Orchestration (the compressed-vs-fallback decision — the testable core)+// =============================================================================++/**+ * Load a KTX2 buffer into a GPU texture: prefer a device-supported compressed+ * format, fall back to RGBA8 when none is available or the compressed transcode+ * fails. Throws only if even the RGBA decode fails (a corrupt/unsupported file).+ */+export function loadCompressedTexture(+ gl: WebGL2RenderingContext, module: ESEngineModule,+ transcoder: BasisTranscoder, bytes: Uint8Array, opts?: CompressedUploadOptions,+): UploadedTexture {+ const support = detectCompressedTextureSupport(gl);+ const target = chooseTargetFormat(support);+ if (target !== null) {+ const t = transcoder.transcode(bytes, target);+ if (t) return uploadCompressedTexture(gl, module, support, target, t, opts);+ // transcode to the chosen format failed → fall through to RGBA.+ }+ const rgba = transcoder.transcodeToRgba(bytes);+ if (!rgba) throw new Error('BasisTranscoder failed to decode KTX2 (compressed and RGBA paths both failed)');+ return uploadRgbaTexture(gl, module, rgba, opts);+}diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex 90972f42b..31a7898b9 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -3,6 +3,7 @@ import { platformCreateCanvas, platformCreateImage } from '../../platform';import { requireResourceManager } from '../../resourceManager';import type { ESEngineModule } from '../../wasm';import { withMalloc } from '../../wasmScratch';+import { isKtx2, loadCompressedTexture, type BasisTranscoder } from '../compressed';/*** Texture import-time settings. Applied when the GL texture is first uploaded,@@ -20,9 +21,16 @@ export type TextureImportSettingsResolver = (ref: string) => TextureImportSettinexport class TextureLoader implements AssetLoader<TextureResult> {readonly type = 'texture';- readonly extensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'];+ readonly extensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.ktx2'];private module_: ESEngineModule;+ /**+ * Basis transcoder for KTX2 assets, injected by the basis plugin (Batch C3).+ * Null until registered — KTX2 loads then error with a clear message rather+ * than silently falling back.+ */+ private transcoder_: BasisTranscoder | null = null;+ setTranscoder(t: BasisTranscoder | null): void { this.transcoder_ = t; }private canvas_: HTMLCanvasElement | OffscreenCanvas | null = null;private ctx_: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null = null;/**@@ -83,11 +91,34 @@ export class TextureLoader implements AssetLoader<TextureResult> {private async loadWithFlip(path: string, ctx: LoadContext, flip: boolean, settings?: TextureImportSettings,): Promise<TextureResult> {+ if (path.toLowerCase().endsWith('.ktx2')) {+ return this.loadCompressed(path, ctx, settings);+ }const url = ctx.backend.resolveUrl(ctx.catalog.getBuildPath(path));const img = await this.loadImage(url);return this.createTextureFromImage(img, flip, settings);}+ /**+ * Load a KTX2 (Basis) compressed texture: fetch the container, transcode to a+ * device-supported GPU format (or RGBA8 fallback), and upload. KTX2 carries its+ * own orientation, so the `flip` flag does not apply.+ */+ private async loadCompressed(+ path: string, ctx: LoadContext, settings?: TextureImportSettings,+ ): Promise<TextureResult> {+ const buf = await ctx.backend.fetchBinary(ctx.catalog.getBuildPath(path));+ const bytes = new Uint8Array(buf);+ if (!isKtx2(bytes)) throw new Error(`TextureLoader: ${path} is not a KTX2 file`);+ const gl = this.getWebGL2Context();+ if (!gl) throw new Error('TextureLoader: KTX2 textures require a WebGL2 context');+ if (!this.transcoder_) {+ throw new Error('TextureLoader: no Basis transcoder registered (load the basis module before KTX2 assets)');+ }+ const r = loadCompressedTexture(gl, this.module_, this.transcoder_, bytes, settings);+ return { handle: r.handle, width: r.width, height: r.height };+ }+private loadImage(src: string): Promise<HTMLImageElement | ImageBitmap> {return new Promise((resolve, reject) => {const img = platformCreateImage();diff --git a/sdk/tests/compressed-texture.test.ts b/sdk/tests/compressed-texture.test.tsnew file mode 100644index 000000000..88ff827b0--- /dev/null+++ b/sdk/tests/compressed-texture.test.ts@@ -0,0 +1,142 @@+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';+import { initResourceManager, shutdownResourceManager } from '../src/resourceManager';+import {+ isKtx2,+ chooseTargetFormat,+ glInternalFormat,+ detectCompressedTextureSupport,+ loadCompressedTexture,+ uploadCompressedTexture,+ CompressedTextureFormat,+ 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 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.s3tc) exts['WEBGL_compressed_texture_s3tc'] = { COMPRESSED_RGBA_S3TC_DXT5_EXT: DXT5 };+ return {+ TEXTURE_2D: 0x0de1, RGBA: 0x1908, UNSIGNED_BYTE: 0x1401,+ 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),+ createTexture: vi.fn(() => ({}) as WebGLTexture),+ bindTexture: vi.fn(),+ compressedTexImage2D: vi.fn(),+ texImage2D: vi.fn(),+ texParameteri: vi.fn(),+ };+}++function makeModule() {+ return { GL: { getNewId: vi.fn(() => 7), textures: {} as Record<number, WebGLTexture> } };+}++function makeTranscoder(over: Partial<BasisTranscoder> = {}): BasisTranscoder {+ return {+ transcode: vi.fn(() => ({ width: 4, height: 4, data: new Uint8Array(8) })),+ transcodeToRgba: vi.fn(() => ({ width: 4, height: 4, data: new Uint8Array(4 * 4 * 4) })),+ ...over,+ };+}++const KTX2_HEADER = new Uint8Array([0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0]);++let registerExternalTexture: ReturnType<typeof vi.fn>;+beforeEach(() => {+ registerExternalTexture = vi.fn(() => 42);+ initResourceManager({ registerExternalTexture } as never);+});+afterEach(() => shutdownResourceManager());++describe('KTX2 detection', () => {+ it('matches the 12-byte identifier', () => {+ expect(isKtx2(KTX2_HEADER)).toBe(true);+ });+ it('rejects non-KTX2 / short buffers', () => {+ expect(isKtx2(new Uint8Array([0x89, 0x50, 0x4e, 0x47]))).toBe(false);+ expect(isKtx2(new Uint8Array(4))).toBe(false);+ });+});++describe('format capability selection', () => {+ it('prefers ASTC > ETC2 > S3TC', () => {+ expect(chooseTargetFormat(detectCompressedTextureSupport(makeGl({ astc: true, etc: true, s3tc: true }) as never)))+ .toBe(CompressedTextureFormat.ASTC_4x4);+ expect(chooseTargetFormat(detectCompressedTextureSupport(makeGl({ etc: true, s3tc: true }) as never)))+ .toBe(CompressedTextureFormat.ETC2_RGBA8);+ expect(chooseTargetFormat(detectCompressedTextureSupport(makeGl({ s3tc: true }) as never)))+ .toBe(CompressedTextureFormat.S3TC_DXT5);+ });+ it('returns null when no compressed extension is available', () => {+ expect(chooseTargetFormat(detectCompressedTextureSupport(makeGl() as never))).toBeNull();+ });+ it('maps each format to its enabling extension constant', () => {+ const s = detectCompressedTextureSupport(makeGl({ astc: true, etc: true, s3tc: true }) as never);+ expect(glInternalFormat(s, CompressedTextureFormat.ASTC_4x4)).toBe(ASTC);+ expect(glInternalFormat(s, CompressedTextureFormat.ETC2_RGBA8)).toBe(ETC2);+ expect(glInternalFormat(s, CompressedTextureFormat.S3TC_DXT5)).toBe(DXT5);+ });+});++describe('loadCompressedTexture', () => {+ it('uploads compressed when the device supports a format', () => {+ const gl = makeGl({ astc: true });+ const mod = makeModule();+ const transcoder = makeTranscoder();+ const r = loadCompressedTexture(gl as never, mod as never, transcoder, KTX2_HEADER);++ expect(transcoder.transcode).toHaveBeenCalledWith(KTX2_HEADER, CompressedTextureFormat.ASTC_4x4);+ expect(transcoder.transcodeToRgba).not.toHaveBeenCalled();+ expect(gl.compressedTexImage2D).toHaveBeenCalledTimes(1);+ // internalformat arg = the ASTC extension constant+ expect(gl.compressedTexImage2D.mock.calls[0][2]).toBe(ASTC);+ expect(gl.texImage2D).not.toHaveBeenCalled();+ expect(registerExternalTexture).toHaveBeenCalledWith(7, 4, 4);+ expect(r).toEqual({ handle: 42, width: 4, height: 4 });+ });++ it('falls back to RGBA8 when no compressed format is supported', () => {+ const gl = makeGl(); // no extensions+ const transcoder = makeTranscoder();+ const r = loadCompressedTexture(gl as never, makeModule() as never, transcoder, KTX2_HEADER);++ expect(transcoder.transcode).not.toHaveBeenCalled();+ expect(transcoder.transcodeToRgba).toHaveBeenCalledOnce();+ expect(gl.compressedTexImage2D).not.toHaveBeenCalled();+ expect(gl.texImage2D).toHaveBeenCalledTimes(1);+ expect(r.handle).toBe(42);+ });++ it('falls back to RGBA8 when the compressed transcode fails', () => {+ const gl = makeGl({ etc: true });+ const transcoder = makeTranscoder({ transcode: vi.fn(() => null) });+ loadCompressedTexture(gl as never, makeModule() as never, transcoder, KTX2_HEADER);++ expect(transcoder.transcode).toHaveBeenCalledOnce();+ expect(transcoder.transcodeToRgba).toHaveBeenCalledOnce();+ expect(gl.texImage2D).toHaveBeenCalledTimes(1);+ });++ it('throws when both compressed and RGBA decode fail', () => {+ const gl = makeGl({ astc: true });+ 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);+ });+});++describe('uploadCompressedTexture', () => {+ it('throws if the chosen format has no enabling extension', () => {+ const gl = makeGl(); // ASTC not enabled+ const support = detectCompressedTextureSupport(gl as never);+ expect(() =>+ uploadCompressedTexture(gl as never, makeModule() as never, support, CompressedTextureFormat.ASTC_4x4,+ { width: 4, height: 4, data: new Uint8Array(8) }),+ ).toThrow(/internalformat/i);+ });+});