@ringozz/godot 4.7.2-657 → 4.7.2-661

package/src/web-image.ts

@@ -1,388 +1,388 @@
-/**********************************************************************
- Copyright (c) Vladimir Davidovich. All rights reserved.
-***********************************************************************/
-
-// Web-only compressed-texture (`ctex`) handling. Two container layouts share the
-// same per-image body (`sub-header + level-size table + payloads`):
-//  - `GST2` `CompressedTexture2D` (`.ctex`): one body.
-//  - `GSTL` `CompressedTexture2DArray` / `Cubemap` / `CubemapArray`
-//    (`.ctexarray` / `.ccube` / `.ccubearray`): N bodies of identical geometry.
-// `CompressedTexture3D` (`.ctex3d`) has its own layout and is not handled, and
-// the outer headers are the same size for both (`magic + 8 x u32`), which is why
-// a single parse/allocate pair covers everything — a container is just a list of
-// layers.
-//
-// Exposes the container/format helpers, `pickGodotFormats` (the driver's
-// compressed-format list) and `decodeCtex` — the default staging path, which
-// decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
-// container so no image codec runs in wasm. The optional compressed-transcode
-// hook lives in load.ts.
-
-// Both container layouts share the outer header (magic + 8 x u32) and the
-// per-image sub-header, so an image body's data starts at a fixed offset.
-const OUTER_HEADER_SIZE = 36;
-const SUB_HEADER_SIZE = 16;
-
-const DATA_FORMAT_PNG = 1;
-const DATA_FORMAT_WEBP = 2;
-
-// `Image::Format` targets we emit (`core/io/image.h`). Every compressed target
-// is a 4x4 block format; they differ only in bytes per block, so the size math
-// is a small table rather than a per-format switch.
-export const FORMAT_DXT1 = 17; // BC1
-export const FORMAT_RGTC_R = 20; // BC4
-export const FORMAT_RGTC_RG = 21; // BC5
-export const FORMAT_BPTC_RGBA = 22; // BC7
-export const FORMAT_ETC2_R11 = 26; // EAC R
-export const FORMAT_ETC2_RG11 = 28; // EAC RG
-export const FORMAT_ETC2_RGB8 = 30;
-export const FORMAT_ASTC_4x4 = 35;
-
-// Image-body data starts here: outer header + sub-header.
-export const BLOB_TABLE_OFFSET = OUTER_HEADER_SIZE + SUB_HEADER_SIZE;
-
-const DATA_FORMAT_IMAGE = 0;
-const FORMAT_RGBA8 = 5;
-const RGBA8_PIXEL_SIZE = 4;
-
-const FORMAT_BIT_STREAM = 1 << 22;
-const MAGIC_LAYERED = 0x4c; // 'GSTL'; 'GST2' (0x32) is the single-image layout
-
-// Bytes per 4x4 block for each compressed target; RGBA8 is 4 bytes/pixel.
-const BLOCK_BYTES: Record<number, number> = {
-	[FORMAT_DXT1]: 8,
-	[FORMAT_ETC2_RGB8]: 8,
-	[FORMAT_ETC2_R11]: 8,
-	[FORMAT_RGTC_R]: 8,
-	[FORMAT_RGTC_RG]: 16,
-	[FORMAT_ETC2_RG11]: 16,
-	[FORMAT_BPTC_RGBA]: 16,
-	[FORMAT_ASTC_4x4]: 16,
-};
-
-/**
- * Bytes per 4x4 block of a compressed `Image::Format` target (RGBA8 reports 4,
- * its bytes per pixel). Unknown formats fall back to a 16-byte block.
- */
-export function blockBytes(format: number): number {
-	return format === FORMAT_RGBA8 ? RGBA8_PIXEL_SIZE : (BLOCK_BYTES[format] ?? 16);
-}
-
-export interface CtexLayer {
-	/** `DATA_FORMAT_PNG` (1) / `DATA_FORMAT_WEBP` (2). */
-	dataFormat: number;
-	width: number;
-	height: number;
-	/** Highest mipmap index (total levels = `mipmaps + 1`). */
-	mipmaps: number;
-	/** Per-level payload byte ranges, level 0 first. */
-	levels: { offset: number; size: number }[];
-}
-
-function isLayered(bytes: Uint8Array): boolean {
-	return bytes.length >= OUTER_HEADER_SIZE && bytes[3] === MAGIC_LAYERED;
-}
-
-/**
- * Parses a container into its layers — one for `GST2` (`.ctex`), N for `GSTL`
- * (`.ctexarray`/`.ccube`/`.ccubearray`), in order. Returns `null` for anything
- * else: non-ctex bytes, a streamable container, or payloads that aren't
- * PNG/WebP-embedded (raw / BASIS / VRAM containers pass through untouched), or
- * layers of differing geometry. Throws on a truncated level table so a malformed
- * file fails loudly rather than decoding garbage.
- */
-export function parseCtex(bytes: Uint8Array): CtexLayer[] | null {
-	if (
-		bytes.length < OUTER_HEADER_SIZE + SUB_HEADER_SIZE ||
-		bytes[0] !== 0x47 || // 'G'
-		bytes[1] !== 0x53 || // 'S'
-		bytes[2] !== 0x54 || // 'T'
-		(bytes[3] !== 0x32 && bytes[3] !== MAGIC_LAYERED)
-	) {
-		return null;
-	}
-	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
-		return null; // streamable layout differs; leave it to the engine
-	}
-	const count = isLayered(bytes) ? dv.getUint32(8, true) : 1;
-	const layers: CtexLayer[] = [];
-	let offset = OUTER_HEADER_SIZE;
-	for (let i = 0; i < count; i++) {
-		if (offset + SUB_HEADER_SIZE > bytes.length) {
-			return null;
-		}
-		const dataFormat = dv.getUint32(offset, true);
-		if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
-			return null;
-		}
-		const width = dv.getUint16(offset + 4, true);
-		const height = dv.getUint16(offset + 6, true);
-		const mipmaps = dv.getUint32(offset + 8, true);
-		const levels: { offset: number; size: number }[] = [];
-		let p = offset + SUB_HEADER_SIZE;
-		for (let level = 0; level <= mipmaps; level++) {
-			if (p + 4 > bytes.length) {
-				throw new Error(`web-image: truncated ctex at mipmap ${level}`);
-			}
-			const size = dv.getUint32(p, true);
-			p += 4;
-			if (p + size > bytes.length) {
-				throw new Error(`web-image: truncated ctex blob at mipmap ${level}`);
-			}
-			levels.push({ offset: p, size });
-			p += size;
-		}
-		const first = layers[0];
-		if (first && (width !== first.width || height !== first.height || mipmaps !== first.mipmaps)) {
-			return null; // texture arrays need uniform layer geometry
-		}
-		layers.push({ dataFormat, width, height, mipmaps, levels });
-		offset = p;
-	}
-	return count === 0 ? null : layers;
-}
-
-/** Dimensions of a mipmap level (`max(dim >> level, 1)`). */
-export function mipLevelDimensions(width: number, height: number, level: number): [number, number] {
-	return [Math.max(width >> level, 1), Math.max(height >> level, 1)];
-}
-
-/** Number of levels in the full mip chain down to 1×1 (>= 1). */
-export function mipChainLength(width: number, height: number): number {
-	let levels = 1;
-	while (width > 1 || height > 1) {
-		width = Math.max(1, width >> 1);
-		height = Math.max(1, height >> 1);
-		levels++;
-	}
-	return levels;
-}
-
-// Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
-// levels. RGBA8 is 4 bytes/pixel; compressed targets are 4x4 blocks (8 or 16
-// bytes) whose dimensions round up, matching `Image::_get_dst_image_size`.
-function bodySize(width: number, height: number, mipmaps: number, format: number): number {
-	const rgba8 = format === FORMAT_RGBA8;
-	const block = rgba8 ? 1 : 4;
-	const bytesPerBlock = blockBytes(format);
-	let dataSize = 0;
-	for (let level = 0; level <= mipmaps; level++) {
-		const [w, h] = mipLevelDimensions(width, height, level);
-		dataSize += Math.ceil(w / block) * Math.ceil(h / block) * bytesPerBlock;
-	}
-	return SUB_HEADER_SIZE + dataSize;
-}
-
-/**
- * Allocates a `.ctex` with `count` identical `DATA_FORMAT_IMAGE` bodies (one
- * array, no intermediate copies), reporting `stride` — bytes per body, so layer
- * `i`'s data goes at `BLOB_TABLE_OFFSET + i * stride`. The outer header is kept
- * verbatim (the layer count / layered type are the container's, not ours),
- * except that `GST2` also carries the image dimensions there, which are patched.
- */
-export function allocateCtex(
-	source: Uint8Array,
-	count: number,
-	width: number,
-	height: number,
-	mipmaps: number,
-	format: number,
-): { bytes: Uint8Array; stride: number } {
-	const stride = bodySize(width, height, mipmaps, format);
-	const bytes = new Uint8Array(OUTER_HEADER_SIZE + count * stride);
-	bytes.set(source.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim (version/flags)
-	const dv = new DataView(bytes.buffer);
-	if (!isLayered(source)) {
-		dv.setUint32(8, width, true); // GST2 outer width
-		dv.setUint32(12, height, true); // GST2 outer height
-	}
-	for (let i = 0; i < count; i++) {
-		const offset = OUTER_HEADER_SIZE + i * stride;
-		dv.setUint32(offset, DATA_FORMAT_IMAGE, true);
-		dv.setUint16(offset + 4, width, true);
-		dv.setUint16(offset + 6, height, true);
-		dv.setUint32(offset + 8, mipmaps, true);
-		dv.setUint32(offset + 12, format, true);
-	}
-	return { bytes, stride };
-}
-
-// ---------------------------------------------------------------------------
-// Capability probing. GLES3 uploads a compressed format only when its config
-// reports it supported, and this build compiles in NO decompressors, so a format
-// the device can't upload breaks the texture rather than degrading. Ask the
-// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
-// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
-// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
-// layered differ — `_texture_set_data` force-decompresses them for
-// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
-// ---------------------------------------------------------------------------
-
-// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
-// encoder can emit; only the unsigned-normal variants (their siblings share it).
-const GL_TO_GODOT_FORMAT: Record<number, number> = {
-	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
-	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
-	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
-	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
-	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
-	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
-	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
-	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
-};
-
-/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
-const PROBED_EXTENSIONS = [
-	'EXT_texture_compression_bptc',
-	'EXT_texture_compression_rgtc',
-	'WEBGL_compressed_texture_s3tc',
-	'WEBGL_compressed_texture_astc',
-	'WEBGL_compressed_texture_etc',
-];
-
-/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
-export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
-	const formats = new Set<number>();
-	for (let i = 0; i < glFormats.length; i++) {
-		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
-		if (godot !== undefined) {
-			formats.add(godot);
-		}
-	}
-	return [...formats];
-}
-
-/**
- * Compressed `Image::Format` targets the running device can upload. A list
- * because the encoder may also reject a format the browser exposes (e.g. spark
- * skips BC on iOS); the caller intersects it with spark's supported set, and
- * order here is not significant (the encoder has its own preference chain).
- */
-export function pickGodotFormats(): number[] {
-	let gl: WebGL2RenderingContext | null = null;
-	try {
-		// Prefer a DOM canvas (works everywhere WebGL2 does); fall back to
-		// OffscreenCanvas for worker contexts.
-		const canvas =
-			typeof document !== 'undefined'
-				? document.createElement('canvas')
-				: typeof OffscreenCanvas !== 'undefined'
-					? new OffscreenCanvas(1, 1)
-					: null;
-		gl = (canvas?.getContext('webgl2', {
-			antialias: false,
-			depth: false,
-			stencil: false,
-			alpha: false,
-		}) ?? null) as WebGL2RenderingContext | null;
-	} catch {
-		gl = null;
-	}
-	if (!gl) {
-		return [];
-	}
-	try {
-		for (const name of PROBED_EXTENSIONS) {
-			gl.getExtension(name);
-		}
-		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
-	} finally {
-		// Don't retain the probe context for the page's lifetime.
-		gl.getExtension('WEBGL_lose_context')?.loseContext();
-	}
-}
-
-/**
- * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
- * (staging then keeps the raw RGBA8 decode). `path` is the resource path being
- * staged, so a platform transcoder can pick a block format from the file name.
- * Produced by `transcoder*.ts` and installed by `load.ts`'s staging.
- */
-export type CtexTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
-
-/**
- * Decodes the embedded PNG/WebP payloads of a `.ctex` with the browser's
- * `createImageBitmap` and rebuilds it as raw RGBA8 (`DATA_FORMAT_IMAGE`) — for
- * `GST2` and for each layer of a `GSTL` array/cubemap. Non-ctex bytes,
- * streamable containers, and `DATA_FORMAT_IMAGE` / `DATA_FORMAT_BASIS_UNIVERSAL`
- * containers are returned unchanged. Throws if an embedded payload can't be
- * decoded or its dimensions don't match the expected mipmap layout, so a
- * would-be undecodable texture fails loudly at materialize time. A no-op outside
- * browsers (no `createImageBitmap`). Levels are decoded concurrently and written
- * straight into the output container (no per-level array).
- */
-export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
-	if (typeof createImageBitmap !== 'function') {
-		return bytes;
-	}
-	const layers = parseCtex(bytes);
-	if (!layers) {
-		return bytes;
-	}
-	const { width, height, mipmaps } = layers[0];
-	const { bytes: out, stride } = allocateCtex(bytes, layers.length, width, height, mipmaps, FORMAT_RGBA8);
-	for (let i = 0; i < layers.length; i++) {
-		await rasterizeLevels(bytes, layers[i], out, BLOB_TABLE_OFFSET + i * stride);
-	}
-	return out;
-}
-
-/**
- * Decodes one PNG/WebP payload into an `ImageBitmap` (level 0 for an encoder,
- * every level for {@link decodeCtex}). Pixel values are handed over unchanged
- * (`colorSpaceConversion`/`premultiplyAlpha` off).
- */
-export function payloadBitmap(
-	bytes: Uint8Array,
-	dataFormat: number,
-	level: { offset: number; size: number },
-): Promise<ImageBitmap> {
-	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
-	// The Blob ctor needs an ArrayBuffer-backed view.
-	return createImageBitmap(
-		new Blob([bytes.subarray(level.offset, level.offset + level.size) as Uint8Array<ArrayBuffer>], { type }),
-		{ colorSpaceConversion: 'none', premultiplyAlpha: 'none' },
-	);
-}
-
-// Decodes a layer's PNG/WebP levels and rasterizes them into `out` at
-// `outOffset`, reusing one canvas across levels.
-async function rasterizeLevels(bytes: Uint8Array, layer: CtexLayer, out: Uint8Array, outOffset: number): Promise<void> {
-	const { width, height } = layer;
-	const bitmaps = await Promise.all(layer.levels.map((l) => payloadBitmap(bytes, layer.dataFormat, l)));
-	const canvas = new OffscreenCanvas(width, height);
-	try {
-		let p = outOffset;
-		for (let i = 0; i < bitmaps.length; i++) {
-			const [lw, lh] = mipLevelDimensions(width, height, i);
-			const bmp = bitmaps[i];
-			if (bmp.width !== lw || bmp.height !== lh) {
-				throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${lw}x${lh}`);
-			}
-			out.set(rasterize(canvas, bmp), p);
-			p += lw * lh * RGBA8_PIXEL_SIZE;
-		}
-	} finally {
-		// close() on an already-closed bitmap is a no-op.
-		for (const bmp of bitmaps) {
-			bmp.close();
-		}
-	}
-}
-
-// Rasterizes an ImageBitmap into a raw RGBA8 view, drawing into the caller's
-// shared canvas (resized per level) so one canvas serves every mipmap.
-function rasterize(canvas: OffscreenCanvas, bmp: ImageBitmap): Uint8Array {
-	const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
-		| OffscreenCanvasRenderingContext2D
-		| null;
-	if (!ctx) {
-		throw new Error('web-image: no 2d context for OffscreenCanvas');
-	}
-	canvas.width = bmp.width;
-	canvas.height = bmp.height;
-	ctx.drawImage(bmp, 0, 0);
-	const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
-	return new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength);
-}
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+// Web-only compressed-texture (`ctex`) handling. Two container layouts share the
+// same per-image body (`sub-header + level-size table + payloads`):
+//  - `GST2` `CompressedTexture2D` (`.ctex`): one body.
+//  - `GSTL` `CompressedTexture2DArray` / `Cubemap` / `CubemapArray`
+//    (`.ctexarray` / `.ccube` / `.ccubearray`): N bodies of identical geometry.
+// `CompressedTexture3D` (`.ctex3d`) has its own layout and is not handled, and
+// the outer headers are the same size for both (`magic + 8 x u32`), which is why
+// a single parse/allocate pair covers everything — a container is just a list of
+// layers.
+//
+// Exposes the container/format helpers, `pickGodotFormats` (the driver's
+// compressed-format list) and `decodeCtex` — the default staging path, which
+// decodes the PNG/WebP payloads with the browser and rebuilds a raw RGBA8
+// container so no image codec runs in wasm. The optional compressed-transcode
+// hook lives in load.ts.
+
+// Both container layouts share the outer header (magic + 8 x u32) and the
+// per-image sub-header, so an image body's data starts at a fixed offset.
+const OUTER_HEADER_SIZE = 36;
+const SUB_HEADER_SIZE = 16;
+
+const DATA_FORMAT_PNG = 1;
+const DATA_FORMAT_WEBP = 2;
+
+// `Image::Format` targets we emit (`core/io/image.h`). Every compressed target
+// is a 4x4 block format; they differ only in bytes per block, so the size math
+// is a small table rather than a per-format switch.
+export const FORMAT_DXT1 = 17; // BC1
+export const FORMAT_RGTC_R = 20; // BC4
+export const FORMAT_RGTC_RG = 21; // BC5
+export const FORMAT_BPTC_RGBA = 22; // BC7
+export const FORMAT_ETC2_R11 = 26; // EAC R
+export const FORMAT_ETC2_RG11 = 28; // EAC RG
+export const FORMAT_ETC2_RGB8 = 30;
+export const FORMAT_ASTC_4x4 = 35;
+
+// Image-body data starts here: outer header + sub-header.
+export const BLOB_TABLE_OFFSET = OUTER_HEADER_SIZE + SUB_HEADER_SIZE;
+
+const DATA_FORMAT_IMAGE = 0;
+const FORMAT_RGBA8 = 5;
+const RGBA8_PIXEL_SIZE = 4;
+
+const FORMAT_BIT_STREAM = 1 << 22;
+const MAGIC_LAYERED = 0x4c; // 'GSTL'; 'GST2' (0x32) is the single-image layout
+
+// Bytes per 4x4 block for each compressed target; RGBA8 is 4 bytes/pixel.
+const BLOCK_BYTES: Record<number, number> = {
+	[FORMAT_DXT1]: 8,
+	[FORMAT_ETC2_RGB8]: 8,
+	[FORMAT_ETC2_R11]: 8,
+	[FORMAT_RGTC_R]: 8,
+	[FORMAT_RGTC_RG]: 16,
+	[FORMAT_ETC2_RG11]: 16,
+	[FORMAT_BPTC_RGBA]: 16,
+	[FORMAT_ASTC_4x4]: 16,
+};
+
+/**
+ * Bytes per 4x4 block of a compressed `Image::Format` target (RGBA8 reports 4,
+ * its bytes per pixel). Unknown formats fall back to a 16-byte block.
+ */
+export function blockBytes(format: number): number {
+	return format === FORMAT_RGBA8 ? RGBA8_PIXEL_SIZE : (BLOCK_BYTES[format] ?? 16);
+}
+
+export interface CtexLayer {
+	/** `DATA_FORMAT_PNG` (1) / `DATA_FORMAT_WEBP` (2). */
+	dataFormat: number;
+	width: number;
+	height: number;
+	/** Highest mipmap index (total levels = `mipmaps + 1`). */
+	mipmaps: number;
+	/** Per-level payload byte ranges, level 0 first. */
+	levels: { offset: number; size: number }[];
+}
+
+function isLayered(bytes: Uint8Array): boolean {
+	return bytes.length >= OUTER_HEADER_SIZE && bytes[3] === MAGIC_LAYERED;
+}
+
+/**
+ * Parses a container into its layers — one for `GST2` (`.ctex`), N for `GSTL`
+ * (`.ctexarray`/`.ccube`/`.ccubearray`), in order. Returns `null` for anything
+ * else: non-ctex bytes, a streamable container, or payloads that aren't
+ * PNG/WebP-embedded (raw / BASIS / VRAM containers pass through untouched), or
+ * layers of differing geometry. Throws on a truncated level table so a malformed
+ * file fails loudly rather than decoding garbage.
+ */
+export function parseCtex(bytes: Uint8Array): CtexLayer[] | null {
+	if (
+		bytes.length < OUTER_HEADER_SIZE + SUB_HEADER_SIZE ||
+		bytes[0] !== 0x47 || // 'G'
+		bytes[1] !== 0x53 || // 'S'
+		bytes[2] !== 0x54 || // 'T'
+		(bytes[3] !== 0x32 && bytes[3] !== MAGIC_LAYERED)
+	) {
+		return null;
+	}
+	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
+		return null; // streamable layout differs; leave it to the engine
+	}
+	const count = isLayered(bytes) ? dv.getUint32(8, true) : 1;
+	const layers: CtexLayer[] = [];
+	let offset = OUTER_HEADER_SIZE;
+	for (let i = 0; i < count; i++) {
+		if (offset + SUB_HEADER_SIZE > bytes.length) {
+			return null;
+		}
+		const dataFormat = dv.getUint32(offset, true);
+		if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
+			return null;
+		}
+		const width = dv.getUint16(offset + 4, true);
+		const height = dv.getUint16(offset + 6, true);
+		const mipmaps = dv.getUint32(offset + 8, true);
+		const levels: { offset: number; size: number }[] = [];
+		let p = offset + SUB_HEADER_SIZE;
+		for (let level = 0; level <= mipmaps; level++) {
+			if (p + 4 > bytes.length) {
+				throw new Error(`web-image: truncated ctex at mipmap ${level}`);
+			}
+			const size = dv.getUint32(p, true);
+			p += 4;
+			if (p + size > bytes.length) {
+				throw new Error(`web-image: truncated ctex blob at mipmap ${level}`);
+			}
+			levels.push({ offset: p, size });
+			p += size;
+		}
+		const first = layers[0];
+		if (first && (width !== first.width || height !== first.height || mipmaps !== first.mipmaps)) {
+			return null; // texture arrays need uniform layer geometry
+		}
+		layers.push({ dataFormat, width, height, mipmaps, levels });
+		offset = p;
+	}
+	return count === 0 ? null : layers;
+}
+
+/** Dimensions of a mipmap level (`max(dim >> level, 1)`). */
+export function mipLevelDimensions(width: number, height: number, level: number): [number, number] {
+	return [Math.max(width >> level, 1), Math.max(height >> level, 1)];
+}
+
+/** Number of levels in the full mip chain down to 1×1 (>= 1). */
+export function mipChainLength(width: number, height: number): number {
+	let levels = 1;
+	while (width > 1 || height > 1) {
+		width = Math.max(1, width >> 1);
+		height = Math.max(1, height >> 1);
+		levels++;
+	}
+	return levels;
+}
+
+// Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
+// levels. RGBA8 is 4 bytes/pixel; compressed targets are 4x4 blocks (8 or 16
+// bytes) whose dimensions round up, matching `Image::_get_dst_image_size`.
+function bodySize(width: number, height: number, mipmaps: number, format: number): number {
+	const rgba8 = format === FORMAT_RGBA8;
+	const block = rgba8 ? 1 : 4;
+	const bytesPerBlock = blockBytes(format);
+	let dataSize = 0;
+	for (let level = 0; level <= mipmaps; level++) {
+		const [w, h] = mipLevelDimensions(width, height, level);
+		dataSize += Math.ceil(w / block) * Math.ceil(h / block) * bytesPerBlock;
+	}
+	return SUB_HEADER_SIZE + dataSize;
+}
+
+/**
+ * Allocates a `.ctex` with `count` identical `DATA_FORMAT_IMAGE` bodies (one
+ * array, no intermediate copies), reporting `stride` — bytes per body, so layer
+ * `i`'s data goes at `BLOB_TABLE_OFFSET + i * stride`. The outer header is kept
+ * verbatim (the layer count / layered type are the container's, not ours),
+ * except that `GST2` also carries the image dimensions there, which are patched.
+ */
+export function allocateCtex(
+	source: Uint8Array,
+	count: number,
+	width: number,
+	height: number,
+	mipmaps: number,
+	format: number,
+): { bytes: Uint8Array; stride: number } {
+	const stride = bodySize(width, height, mipmaps, format);
+	const bytes = new Uint8Array(OUTER_HEADER_SIZE + count * stride);
+	bytes.set(source.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim (version/flags)
+	const dv = new DataView(bytes.buffer);
+	if (!isLayered(source)) {
+		dv.setUint32(8, width, true); // GST2 outer width
+		dv.setUint32(12, height, true); // GST2 outer height
+	}
+	for (let i = 0; i < count; i++) {
+		const offset = OUTER_HEADER_SIZE + i * stride;
+		dv.setUint32(offset, DATA_FORMAT_IMAGE, true);
+		dv.setUint16(offset + 4, width, true);
+		dv.setUint16(offset + 6, height, true);
+		dv.setUint32(offset + 8, mipmaps, true);
+		dv.setUint32(offset + 12, format, true);
+	}
+	return { bytes, stride };
+}
+
+// ---------------------------------------------------------------------------
+// Capability probing. GLES3 uploads a compressed format only when its config
+// reports it supported, and this build compiles in NO decompressors, so a format
+// the device can't upload breaks the texture rather than degrading. Ask the
+// driver (`COMPRESSED_TEXTURE_FORMATS`) rather than reading extension names:
+// Chrome on Windows lists no ETC2/EAC and rejects those uploads, while
+// `config.cpp` would still route one to it. RGTC arrays are the one place 2D and
+// layered differ — `_texture_set_data` force-decompresses them for
+// `TEXTURE_2D_ARRAY`, gated here on `Image::can_decompress("s3tc")`.
+// ---------------------------------------------------------------------------
+
+// `CompressedTexture` GL enums -> Godot `Image::Format`, for the targets the
+// encoder can emit; only the unsigned-normal variants (their siblings share it).
+const GL_TO_GODOT_FORMAT: Record<number, number> = {
+	0x83f0: FORMAT_DXT1, // COMPRESSED_RGB_S3TC_DXT1_EXT
+	0x8dbb: FORMAT_RGTC_R, // COMPRESSED_RED_RGTC1_EXT
+	0x8dbd: FORMAT_RGTC_RG, // COMPRESSED_RED_GREEN_RGTC2_EXT
+	0x8e8c: FORMAT_BPTC_RGBA, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+	0x9270: FORMAT_ETC2_R11, // COMPRESSED_R11_EAC
+	0x9272: FORMAT_ETC2_RG11, // COMPRESSED_RG11_EAC
+	0x9274: FORMAT_ETC2_RGB8, // COMPRESSED_RGB8_ETC2
+	0x93b0: FORMAT_ASTC_4x4, // COMPRESSED_RGBA_ASTC_4x4_KHR
+};
+
+/** Enabled before reading the list — a browser may only list a format once its extension is enabled. */
+const PROBED_EXTENSIONS = [
+	'EXT_texture_compression_bptc',
+	'EXT_texture_compression_rgtc',
+	'WEBGL_compressed_texture_s3tc',
+	'WEBGL_compressed_texture_astc',
+	'WEBGL_compressed_texture_etc',
+];
+
+/** The Godot targets among a driver's `COMPRESSED_TEXTURE_FORMATS` list, in list order and deduplicated (pure). */
+export function godotFormatsFor(glFormats: ArrayLike<number>): number[] {
+	const formats = new Set<number>();
+	for (let i = 0; i < glFormats.length; i++) {
+		const godot = GL_TO_GODOT_FORMAT[glFormats[i]!];
+		if (godot !== undefined) {
+			formats.add(godot);
+		}
+	}
+	return [...formats];
+}
+
+/**
+ * Compressed `Image::Format` targets the running device can upload. A list
+ * because the encoder may also reject a format the browser exposes (e.g. spark
+ * skips BC on iOS); the caller intersects it with spark's supported set, and
+ * order here is not significant (the encoder has its own preference chain).
+ */
+export function pickGodotFormats(): number[] {
+	let gl: WebGL2RenderingContext | null = null;
+	try {
+		// Prefer a DOM canvas (works everywhere WebGL2 does); fall back to
+		// OffscreenCanvas for worker contexts.
+		const canvas =
+			typeof document !== 'undefined'
+				? document.createElement('canvas')
+				: typeof OffscreenCanvas !== 'undefined'
+					? new OffscreenCanvas(1, 1)
+					: null;
+		gl = (canvas?.getContext('webgl2', {
+			antialias: false,
+			depth: false,
+			stencil: false,
+			alpha: false,
+		}) ?? null) as WebGL2RenderingContext | null;
+	} catch {
+		gl = null;
+	}
+	if (!gl) {
+		return [];
+	}
+	try {
+		for (const name of PROBED_EXTENSIONS) {
+			gl.getExtension(name);
+		}
+		return godotFormatsFor(gl.getParameter(gl.COMPRESSED_TEXTURE_FORMATS) as ArrayLike<number>);
+	} finally {
+		// Don't retain the probe context for the page's lifetime.
+		gl.getExtension('WEBGL_lose_context')?.loseContext();
+	}
+}
+
+/**
+ * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
+ * (staging then keeps the raw RGBA8 decode). `path` is the resource path being
+ * staged, so a platform transcoder can pick a block format from the file name.
+ * Produced by `transcoder*.ts` and installed by `load.ts`'s staging.
+ */
+export type CtexTranscoder = (bytes: Uint8Array, path: string) => Promise<Uint8Array | null>;
+
+/**
+ * Decodes the embedded PNG/WebP payloads of a `.ctex` with the browser's
+ * `createImageBitmap` and rebuilds it as raw RGBA8 (`DATA_FORMAT_IMAGE`) — for
+ * `GST2` and for each layer of a `GSTL` array/cubemap. Non-ctex bytes,
+ * streamable containers, and `DATA_FORMAT_IMAGE` / `DATA_FORMAT_BASIS_UNIVERSAL`
+ * containers are returned unchanged. Throws if an embedded payload can't be
+ * decoded or its dimensions don't match the expected mipmap layout, so a
+ * would-be undecodable texture fails loudly at materialize time. A no-op outside
+ * browsers (no `createImageBitmap`). Levels are decoded concurrently and written
+ * straight into the output container (no per-level array).
+ */
+export async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+	if (typeof createImageBitmap !== 'function') {
+		return bytes;
+	}
+	const layers = parseCtex(bytes);
+	if (!layers) {
+		return bytes;
+	}
+	const { width, height, mipmaps } = layers[0];
+	const { bytes: out, stride } = allocateCtex(bytes, layers.length, width, height, mipmaps, FORMAT_RGBA8);
+	for (let i = 0; i < layers.length; i++) {
+		await rasterizeLevels(bytes, layers[i], out, BLOB_TABLE_OFFSET + i * stride);
+	}
+	return out;
+}
+
+/**
+ * Decodes one PNG/WebP payload into an `ImageBitmap` (level 0 for an encoder,
+ * every level for {@link decodeCtex}). Pixel values are handed over unchanged
+ * (`colorSpaceConversion`/`premultiplyAlpha` off).
+ */
+export function payloadBitmap(
+	bytes: Uint8Array,
+	dataFormat: number,
+	level: { offset: number; size: number },
+): Promise<ImageBitmap> {
+	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
+	// The Blob ctor needs an ArrayBuffer-backed view.
+	return createImageBitmap(
+		new Blob([bytes.subarray(level.offset, level.offset + level.size) as Uint8Array<ArrayBuffer>], { type }),
+		{ colorSpaceConversion: 'none', premultiplyAlpha: 'none' },
+	);
+}
+
+// Decodes a layer's PNG/WebP levels and rasterizes them into `out` at
+// `outOffset`, reusing one canvas across levels.
+async function rasterizeLevels(bytes: Uint8Array, layer: CtexLayer, out: Uint8Array, outOffset: number): Promise<void> {
+	const { width, height } = layer;
+	const bitmaps = await Promise.all(layer.levels.map((l) => payloadBitmap(bytes, layer.dataFormat, l)));
+	const canvas = new OffscreenCanvas(width, height);
+	try {
+		let p = outOffset;
+		for (let i = 0; i < bitmaps.length; i++) {
+			const [lw, lh] = mipLevelDimensions(width, height, i);
+			const bmp = bitmaps[i];
+			if (bmp.width !== lw || bmp.height !== lh) {
+				throw new Error(`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${lw}x${lh}`);
+			}
+			out.set(rasterize(canvas, bmp), p);
+			p += lw * lh * RGBA8_PIXEL_SIZE;
+		}
+	} finally {
+		// close() on an already-closed bitmap is a no-op.
+		for (const bmp of bitmaps) {
+			bmp.close();
+		}
+	}
+}
+
+// Rasterizes an ImageBitmap into a raw RGBA8 view, drawing into the caller's
+// shared canvas (resized per level) so one canvas serves every mipmap.
+function rasterize(canvas: OffscreenCanvas, bmp: ImageBitmap): Uint8Array {
+	const ctx = canvas.getContext('2d', { colorSpace: 'srgb', willReadFrequently: true }) as
+		| OffscreenCanvasRenderingContext2D
+		| null;
+	if (!ctx) {
+		throw new Error('web-image: no 2d context for OffscreenCanvas');
+	}
+	canvas.width = bmp.width;
+	canvas.height = bmp.height;
+	ctx.drawImage(bmp, 0, 0);
+	const img = ctx.getImageData(0, 0, bmp.width, bmp.height);
+	return new Uint8Array(img.data.buffer, img.data.byteOffset, img.data.byteLength);
+}