@ringozz/godot 4.7.2-626 → 4.7.2-639

package/src/web-image.ts

@@ -2,152 +2,329 @@
  Copyright (c) Vladimir Davidovich. All rights reserved.
 ***********************************************************************/
 
-// Web-only: decode the embedded PNG/WebP blobs of a `.ctex` CompressedTexture2D
-// container with the browser's `createImageBitmap`, and rebuild the container as
-// a raw RGBA8 `DATA_FORMAT_IMAGE` ctex — so no image codec runs in wasm on web.
-// Anything that isn't a PNG/WebP-embedded ctex is returned unchanged.
+// 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.
 //
-// The mipmap blobs are codec-decoded **concurrently** (Promise.all), then
-// rasterized serially into one reused OffscreenCanvas, so wall time is dominated
-// by the full-res level's decode instead of the serial sum of every level.
+// Exposes the container/format helpers, `pickGodotFormats` (probing the WebGL2
+// extensions GLES3 checks) 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 CTEX_MAGIC = 'GST2';
-const DATA_FORMAT_IMAGE = 0;
 const DATA_FORMAT_PNG = 1;
 const DATA_FORMAT_WEBP = 2;
+
+// `Image::Format` targets we emit (`core/io/image.h`). Only BC7 and ASTC: both
+// are 4x4/16-byte formats, which is why the size math needs no format table.
+export const FORMAT_BPTC_RGBA = 22;
+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
 
-// Outer header: magic(4) version(4) w(4) h(4) df(4) mipmap_limit(4) reserved(12).
-const OUTER_HEADER_SIZE = 36;
-// Sub-header: data_format(4) w(2) h(2) mipmaps(4) format(4).
-const SUB_HEADER_OFFSET = OUTER_HEADER_SIZE;
-const SUB_HEADER_SIZE = 16;
-const BLOB_TABLE_OFFSET = SUB_HEADER_OFFSET + SUB_HEADER_SIZE;
-
-// One encoded mipmap's byte range inside the container, plus the RGBA
-// dimensions its decoded pixels must have (`w>>i` clamped to 1).
-interface MipEntry {
-	offset: number;
-	size: number;
+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 decodeBitmap(blob: Uint8Array<ArrayBuffer>, type: string): Promise<ImageBitmap> {
-	return createImageBitmap(new Blob([blob], { type }), {
-		colorSpaceConversion: 'none',
-		premultiplyAlpha: 'none',
-	});
-}
-
-// Rasterizes an ImageBitmap into a raw RGBA8 buffer, 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);
+function isLayered(bytes: Uint8Array): boolean {
+	return bytes.length >= OUTER_HEADER_SIZE && bytes[3] === MAGIC_LAYERED;
 }
 
 /**
- * Decodes the embedded PNG/WebP blobs of a `.ctex` file with the browser's
- * `createImageBitmap` and rebuilds it as a raw RGBA8 (`DATA_FORMAT_IMAGE`)
- * container. Non-ctex bytes, streamable textures, and `DATA_FORMAT_IMAGE` /
- * `DATA_FORMAT_BASIS_UNIVERSAL` containers are returned unchanged. Throws if an
- * embedded blob 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`). Mip levels are
- * decoded concurrently; the returned container's pixel data is ordered largest
- * to smallest, matching the input blob table.
+ * 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 async function decodeCtex(bytes: Uint8Array): Promise<Uint8Array> {
+export function parseCtex(bytes: Uint8Array): CtexLayer[] | null {
 	if (
-		typeof createImageBitmap !== 'function' ||
-		bytes.length < SUB_HEADER_OFFSET + SUB_HEADER_SIZE ||
-		String.fromCharCode(...bytes.subarray(0, 4)) !== CTEX_MAGIC
+		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 bytes;
+		return null;
 	}
 	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 	if (dv.getUint32(16, true) & FORMAT_BIT_STREAM) {
-		return bytes; // streamable layout differs; leave it to the engine
+		return null; // streamable layout differs; leave it to the engine
 	}
-	const dataFormat = dv.getUint32(SUB_HEADER_OFFSET, true);
-	if (dataFormat !== DATA_FORMAT_PNG && dataFormat !== DATA_FORMAT_WEBP) {
-		return bytes; // raw and BASIS_UNIVERSAL containers pass through
+	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;
 	}
-	const w = dv.getUint16(SUB_HEADER_OFFSET + 4, true);
-	const h = dv.getUint16(SUB_HEADER_OFFSET + 6, true);
-	const mipmaps = dv.getUint32(SUB_HEADER_OFFSET + 8, true);
-	const type = dataFormat === DATA_FORMAT_WEBP ? 'image/webp' : 'image/png';
+	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;
+}
 
-	// Phase 1: bounds-check the blob table so every level's byte range is known
-	// before any decode starts (a malformed container fails fast, no decode).
-	const mips: MipEntry[] = [];
-	let ofs = BLOB_TABLE_OFFSET;
-	for (let i = 0; i <= mipmaps; i++) {
-		if (ofs + 4 > bytes.length) {
-			throw new Error(`web-image: truncated ctex at mipmap ${i}`);
+// Bytes of one `DATA_FORMAT_IMAGE` image body: sub-header + tightly packed
+// levels. RGBA8 is 4 bytes/pixel; BC7/ASTC are 16-byte 4x4 blocks 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 = rgba8 ? RGBA8_PIXEL_SIZE : 16;
+	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. Godot's Compatibility (GLES3) renderer is what the web
+// wasm build uses, and it only uploads a compressed format natively when the
+// matching GL extension is present; this build compiles in NO decompressors, so
+// a format the device can't upload breaks the texture rather than degrading.
+// It selects formats for layered/3D textures exactly as for 2D — the
+// `astc_layered_supported`/`astc_3d_supported` flags it computes are only used
+// to derive `astc_supported`/`astc_hdr_supported` — so this probe covers texture
+// arrays and cubemaps too.
+// ---------------------------------------------------------------------------
+
+/**
+ * Compressed `Image::Format` targets for an RGBA texture, best first, filtered
+ * to what the running device can actually upload. A list because the encoder may
+ * also reject a format the browser exposes (e.g. spark skips BC on iOS); the
+ * caller walks it until one is encodable.
+ */
+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 [];
+	}
+	const formats: number[] = [];
+	try {
+		const exts = new Set(gl.getSupportedExtensions() ?? []);
+		if (exts.has('EXT_texture_compression_bptc')) {
+			formats.push(FORMAT_BPTC_RGBA);
 		}
-		const size = dv.getUint32(ofs, true);
-		ofs += 4;
-		if (ofs + size > bytes.length) {
-			throw new Error(`web-image: truncated ctex blob at mipmap ${i}`);
+		if (exts.has('WEBGL_compressed_texture_astc')) {
+			formats.push(FORMAT_ASTC_4x4);
 		}
-		mips.push({ offset: ofs, size, width: Math.max(w >> i, 1), height: Math.max(h >> i, 1) });
-		ofs += size;
+	} finally {
+		// Don't retain the probe context for the page's lifetime.
+		gl.getExtension('WEBGL_lose_context')?.loseContext();
 	}
+	return formats;
+}
+
+/**
+ * Transforms fetched `.ctex` bytes into replacement bytes, or `null` to decline
+ * (staging then keeps the raw RGBA8 decode). Produced by `transcoder*.ts` and
+ * installed by `load.ts`'s staging.
+ */
+export type CtexTranscoder = (bytes: Uint8Array) => Promise<Uint8Array | null>;
 
-	// Phase 2: codec-decode all levels concurrently — the dominant cost now
-	// overlaps instead of summing. Views (not copies) go into the Blob, which
-	// materializes them once.
-	// `decodeBitmap` feeds the Blob ctor, which needs an ArrayBuffer-backed view.
-	const bitmaps = await Promise.all(
-		mips.map((m) => decodeBitmap(bytes.subarray(m.offset, m.offset + m.size) as Uint8Array<ArrayBuffer>, type)),
+/**
+ * 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' },
 	);
+}
 
-	// Phase 3: validate dimensions and rasterize serially into one shared
-	// canvas; close() on an already-closed bitmap is a no-op, so a throw
-	// mid-loop still releases every bitmap via the finally.
-	const levels: Uint8Array[] = new Array(mips.length);
-	const canvas = new OffscreenCanvas(w, h);
+// 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 {
-		for (let i = 0; i < mips.length; i++) {
+		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 !== mips[i].width || bmp.height !== mips[i].height) {
-				throw new Error(
-					`web-image: mipmap ${i} decoded as ${bmp.width}x${bmp.height}, expected ${mips[i].width}x${mips[i].height}`,
-				);
+			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}`);
 			}
-			levels[i] = rasterize(canvas, bmp);
+			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();
 		}
 	}
+}
 
-	const dataSize = levels.reduce((n, level) => n + level.length, 0);
-	const out = new Uint8Array(BLOB_TABLE_OFFSET + dataSize);
-	out.set(bytes.subarray(0, OUTER_HEADER_SIZE)); // outer header verbatim
-	const odv = new DataView(out.buffer);
-	odv.setUint32(SUB_HEADER_OFFSET, DATA_FORMAT_IMAGE, true);
-	odv.setUint16(SUB_HEADER_OFFSET + 4, w, true);
-	odv.setUint16(SUB_HEADER_OFFSET + 6, h, true);
-	odv.setUint32(SUB_HEADER_OFFSET + 8, mipmaps, true);
-	odv.setUint32(SUB_HEADER_OFFSET + 12, FORMAT_RGBA8, true);
-	let p = BLOB_TABLE_OFFSET;
-	for (const level of levels) {
-		out.set(level, p);
-		p += level.length;
+// 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');
 	}
-	return out;
+	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);
 }