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(rc6): KTX2 compressed-texture loader architecture (Batch C1)

esenginec3873287af69
diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.ts
new file mode 100644
index 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.ts
index 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) => TextureImportSettin
export 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.ts
new file mode 100644
index 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);
+ });
+});