Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Keep KTX2 textures GPU-compressed in the glTF addon

Nguyen Xuan Anab552a342d67
diff --git a/changes/304.md b/changes/304.md
new file mode 100644
index 00000000..1cf433de
--- /dev/null
+++ b/changes/304.md
@@ -0,0 +1 @@
+- Keep KTX2 textures GPU-compressed (closes #304). A KTX2 loader that transcodes to BC7, BC1, BC3, ASTC 4x4 or ETC2 is now accepted, and the renderer uploads each mip with `compressedTexSubImage2D`, so a 2K map takes about a quarter of the memory of RGBA8. The new `ktx2WorkerConfigFor(context)` export gives the loader the formats a context takes, and it falls back to RGBA8 where there are none. `asset.textureFormats` lists the format, size and bytes of each texture, and compressed KTX2 images count a quarter of their pixels toward `maxTexturePixels`.
diff --git a/docs/gltf.md b/docs/gltf.md
index 0c19dd99..69d1fd6f 100644
--- a/docs/gltf.md
+++ b/docs/gltf.md
@@ -160,19 +160,35 @@ A Draco loader needs `decodeDracoFile(buffer, onLoad, attributeIds, attributeTyp
```js
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+import { loadGltf, ktx2WorkerConfigFor } from '67js/addons/gltf';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
const draco = new DRACOLoader().setDecoderPath('/vendor/draco/'); // copy three/examples/jsm/libs/draco/
const ktx2 = new KTX2Loader().setTranscoderPath('/vendor/basis/'); // copy three/examples/jsm/libs/basis/
-// Transcode to RGBA8 only: the renderer uploads plain pixels, not GPU-compressed formats.
-ktx2.workerConfig = { astcSupported: false, astcHDRSupported: false, etc1Supported: false, etc2Supported: false, dxtSupported: false, bptcSupported: false, pvrtcSupported: false };
+// Transcode to a GPU-compressed format the renderer's context takes, or to RGBA8 where it takes none.
+ktx2.workerConfig = ktx2WorkerConfigFor(renderer.context);
const asset = await loadGltf('/models/car.glb', { decoders: { draco, ktx2, meshopt: MeshoptDecoder } });
```
Any subset works. Draco and KTX2 decode in browser workers. Dispose the loaders yourself when done (`draco.dispose()`, `ktx2.dispose()`).
-A KTX2 texture that decodes to a GPU-compressed format fails with a message that points back to this setting.
-KTX2 dimensions count toward `maxTexturePixels` before decoding. KTX2 images are never scaled, so a KTX2-heavy file over the budget fails.
+
+### KTX2 texture formats
+
+`ktx2WorkerConfigFor(context)` (exported next to `loadGltf`) reads the extensions of a WebGL2 context and returns the `workerConfig` for the loader. The loader then picks one format per file.
+The renderer uploads these GPU-compressed formats as they are, with `texStorage2D` and `compressedTexSubImage2D` for each mip:
+
+| Format | Needs | Bytes a texel |
+| --- | --- | --- |
+| BC7 | `EXT_texture_compression_bptc` | 1 |
+| BC1 or BC3 | `WEBGL_compressed_texture_s3tc` and `WEBGL_compressed_texture_s3tc_srgb` | 0.5 or 1 |
+| ASTC 4x4 | `WEBGL_compressed_texture_astc` | 1 |
+| ETC2 | `WEBGL_compressed_texture_etc` | 0.5 or 1 |
+
+A context with none of these, such as SwiftShader, gets RGBA8 (4 bytes a texel). Set `workerConfig` before the first load. A loader that you leave without a config throws.
+Color maps upload as sRGB and data maps as linear. A file with a partial mip chain keeps only its first level. A compressed texture cannot be exported to GLB or read by the path tracer, so transcode to RGBA8 for those.
+`asset.textureFormats` lists `{ format, width, height, colorSpace, bytes }` for each texture, with `format` set to `bc7`, `bc1-rgb`, `bc1-rgba`, `bc3`, `astc-4x4`, `etc2-rgb`, `etc2-rgba` or `rgba8`.
+KTX2 dimensions count toward `maxTexturePixels` before decoding. KTX2 images are never scaled. When the loader's `workerConfig` allows a compressed format, a KTX2 image counts a quarter of its pixels, because it takes at most one byte a texel on the GPU. A KTX2-heavy file over the budget still fails.
### Instancing limits
diff --git a/src/compressed-texture.js b/src/compressed-texture.js
new file mode 100644
index 00000000..eeb3084d
--- /dev/null
+++ b/src/compressed-texture.js
@@ -0,0 +1,99 @@
+// GPU-compressed texture formats that a KTX2 loader can hand over, and how the renderer uploads them.
+// A compressed image descriptor looks like { width, height, compressed: { glFormat, levels: [{ data, width, height }] } }.
+
+const BPTC = 'EXT_texture_compression_bptc';
+const S3TC = 'WEBGL_compressed_texture_s3tc';
+const S3TC_SRGB = 'WEBGL_compressed_texture_s3tc_srgb';
+const ASTC = 'WEBGL_compressed_texture_astc';
+const ETC2 = 'WEBGL_compressed_texture_etc';
+
+// Keyed by the linear GL enum, which is what the three.js KTX2 loader reports as the texture format.
+const FORMATS = new Map([
+ [0x8e8c, { name: 'bc7', extension: BPTC, srgbFormat: 0x8e8d, blockBytes: 16 }],
+ [0x83f0, { name: 'bc1-rgb', extension: S3TC, srgbExtension: S3TC_SRGB, srgbFormat: 0x8c4c, blockBytes: 8, strictBlocks: true }],
+ [0x83f1, { name: 'bc1-rgba', extension: S3TC, srgbExtension: S3TC_SRGB, srgbFormat: 0x8c4d, blockBytes: 8, strictBlocks: true }],
+ [0x83f3, { name: 'bc3', extension: S3TC, srgbExtension: S3TC_SRGB, srgbFormat: 0x8c4f, blockBytes: 16, strictBlocks: true }],
+ [0x93b0, { name: 'astc-4x4', extension: ASTC, srgbFormat: 0x93d0, blockBytes: 16 }],
+ [0x9274, { name: 'etc2-rgb', extension: ETC2, srgbFormat: 0x9275, blockBytes: 8 }],
+ [0x9278, { name: 'etc2-rgba', extension: ETC2, srgbFormat: 0x9279, blockBytes: 16 }],
+]);
+
+const BLOCK_SIZE = 4;
+
+function blocksFor(size) {
+ return Math.ceil(size / BLOCK_SIZE);
+}
+
+function levelBytes(width, height, blockBytes) {
+ return blocksFor(width) * blocksFor(height) * blockBytes;
+}
+
+function levelCountFor(width, height) {
+ return Math.floor(Math.log2(Math.max(width, height))) + 1;
+}
+
+/** The format entry for a three.js style compressed texture format enum, or null when 67js does not take it. */
+export function compressedFormatInfo(glFormat) {
+ return FORMATS.get(glFormat) ?? null;
+}
+
+/**
+ * Validate the mip levels of a compressed image and keep the ones a complete chain needs.
+ * A partial chain is cut to its first level, because a texture with missing mips is incomplete.
+ */
+export function describeCompressedImage(glFormat, levels, field) {
+ const info = compressedFormatInfo(glFormat);
+ if (!info) throw new Error(`${field} decoded to GPU format ${glFormat}, which 67js does not upload. Use BC7, BC1, BC3, ASTC 4x4 or ETC2, or transcode to RGBA8 (see docs/gltf.md).`);
+ if (!Array.isArray(levels) || !levels.length) throw new Error(`${field} compressed texture has no mip levels.`);
+ const [base] = levels;
+ if (info.strictBlocks && (base.width % BLOCK_SIZE || base.height % BLOCK_SIZE)) {
+ throw new Error(`${field} ${info.name} texture must have width and height in multiples of 4.`);
+ }
+ const usable = levels.length === levelCountFor(base.width, base.height) ? levels : [base];
+ for (const level of usable) {
+ if (!(level.data instanceof Uint8Array) || level.data.length !== levelBytes(level.width, level.height, info.blockBytes)) {
+ throw new Error(`${field} ${info.name} mip level data does not match its size.`);
+ }
+ }
+ const bytes = usable.reduce((sum, level) => sum + level.data.length, 0);
+ return { image: { width: base.width, height: base.height, compressed: { glFormat, name: info.name, levels: usable, bytes } }, name: info.name, bytes };
+}
+
+/** Throw when the context lacks the extension for a compressed image. Returns the internal format to upload. */
+function resolveInternalFormat(context, compressed, colorSpace) {
+ const info = compressedFormatInfo(compressed.glFormat);
+ const srgb = colorSpace !== 'linear';
+ const extension = srgb && info.srgbExtension ? info.srgbExtension : info.extension;
+ if (!context.getExtension(extension)) {
+ throw new Error(`This context lacks ${extension}, which the ${info.name} texture needs. Transcode KTX2 for this context with ktx2WorkerConfigFor(context) (see docs/gltf.md).`);
+ }
+ return srgb ? info.srgbFormat : compressed.glFormat;
+}
+
+/** Upload every mip level of a compressed image into the bound TEXTURE_2D with immutable storage. */
+export function uploadCompressedImage(context, compressed, colorSpace) {
+ const internalFormat = resolveInternalFormat(context, compressed, colorSpace);
+ const [base] = compressed.levels;
+ context.texStorage2D(context.TEXTURE_2D, compressed.levels.length, internalFormat, base.width, base.height);
+ compressed.levels.forEach((level, index) => {
+ context.compressedTexSubImage2D(context.TEXTURE_2D, index, 0, 0, level.width, level.height, internalFormat, level.data);
+ });
+}
+
+/**
+ * The KTX2Loader `workerConfig` for a WebGL2 context, so the loader transcodes to a format this context takes.
+ * Every field is false where the context lacks the extension, which makes the loader fall back to RGBA8.
+ * DXT needs the sRGB extension as well, because one KTX2 file serves color and data maps.
+ */
+export function ktx2WorkerConfigFor(context) {
+ const has = name => Boolean(context.getExtension(name));
+ return {
+ astcSupported: has(ASTC),
+ astcHDRSupported: false,
+ etc1Supported: false,
+ etc2Supported: has(ETC2),
+ dxtSupported: has(S3TC) && has(S3TC_SRGB),
+ bptcSupported: has(BPTC),
+ pvrtcSupported: false,
+ };
+}
diff --git a/src/export-textures.js b/src/export-textures.js
index 265f4fdb..b4214a8c 100644
--- a/src/export-textures.js
+++ b/src/export-textures.js
@@ -12,6 +12,7 @@ function pixelsOf(image, channel) {
if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
throw new TypeError(`GLB ${channel} needs an image with a whole width and height.`);
}
+ if (image?.compressed) throw new TypeError(`GLB ${channel} is a GPU-compressed texture, which export cannot read back. Transcode KTX2 to RGBA8 to export it.`);
if (image.data) {
if (image.data.length < width * height * 4) throw new RangeError(`GLB ${channel} image data must hold RGBA8 pixels for every texel.`);
return { width, height, pixels: image.data };
diff --git a/src/gltf-decode.js b/src/gltf-decode.js
index d8cd8050..6820a450 100644
--- a/src/gltf-decode.js
+++ b/src/gltf-decode.js
@@ -147,11 +147,11 @@ export async function decodeGltf({ document, glbBinary, resourceBytes, decoders,
let loaded;
if (isKtx2) {
const texture = await loadKtx2Image(bytes);
- loaded = { image: texture.image, isCompressedTexture: texture.isCompressedTexture === true };
+ loaded = { image: texture.image, isCompressedTexture: texture.isCompressedTexture === true, format: texture.format, mipmaps: texture.mipmaps };
releasers.push(() => texture.dispose?.());
} else {
const image = await decodeImage(bytes, mimeTypeOf(document.images[sourceIndex], bytes), imageTargets.get(sourceIndex));
- loaded = { image, isCompressedTexture: false };
+ loaded = { image, isCompressedTexture: false, format: undefined, mipmaps: undefined };
releasers.push(() => image.close?.());
}
images.set(key, loaded);
@@ -176,10 +176,12 @@ export async function decodeGltf({ document, glbBinary, resourceBytes, decoders,
if (textures.has(textureIndex)) return textures.get(textureIndex);
const definition = document.textures[textureIndex];
const sampler = document.samplers?.[definition.sampler] ?? {};
- const { image, isCompressedTexture } = await loadTextureImage(definition);
+ const { image, isCompressedTexture, format, mipmaps } = await loadTextureImage(definition);
const texture = {
image,
isCompressedTexture,
+ format,
+ mipmaps,
wrapS: sampler.wrapS ?? 10497,
wrapT: sampler.wrapT ?? 10497,
minFilter: sampler.minFilter ?? 9987,
diff --git a/src/gltf.js b/src/gltf.js
index aa0f9ba7..51b99deb 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -1,6 +1,8 @@
import { applyClip } from './gltf-animation.js';
import { GLTF_LAYER_EXTENSIONS, layerTextureReferences, materialLayersFromGltf } from './gltf-layers.js';
import { attributeFloats } from './gltf-accessors.js';
+import { describeCompressedImage } from './compressed-texture.js';
+export { ktx2WorkerConfigFor } from './compressed-texture.js';
import { decodeGltf, isLinePrimitive, textureSourceIndex } from './gltf-decode.js';
import { readPunctualLights } from './gltf-lights.js';
import { Matrix4 } from './gltf-nodes.js';
@@ -538,11 +540,12 @@ function webpImageSize(bytes, header) {
return null;
}
-function validateImage(bytes, maxImagePixels) {
+function validateImage(bytes, maxImagePixels, ktx2Weight) {
const header = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
let width;
let height;
let scalable = true;
+ let weight = 1;
if (bytes.length >= 24 && header.getUint32(0) === 0x89504e47 && header.getUint32(4) === 0x0d0a1a0a && header.getUint32(12) === 0x49484452) {
width = header.getUint32(16);
height = header.getUint32(20);
@@ -574,10 +577,21 @@ function validateImage(bytes, maxImagePixels) {
width = header.getUint32(20, true);
height = header.getUint32(24, true);
scalable = false;
+ weight = ktx2Weight;
}
if (!width || !height) throw new Error('Only valid PNG, JPEG, WebP and KTX2 texture images are supported.');
if (width * height > maxImagePixels) throw new Error('Texture image exceeds maxTextureImagePixels before decoding.');
- return { width, height, scalable };
+ return { width, height, scalable, weight };
+}
+
+/**
+ * A KTX2 image counts as a quarter of its RGBA8 size when the supplied loader will transcode to a GPU-compressed format.
+ * One byte a texel is the largest compressed size (BC7, ASTC 4x4, BC3), against four for RGBA8.
+ */
+function ktx2BudgetWeight(ktx2Loader) {
+ const support = ktx2Loader?.workerConfig;
+ const compressed = support && (support.bptcSupported || support.astcSupported || support.dxtSupported || support.etc2Supported);
+ return compressed ? 0.25 : 1;
}
function binaryChunk(data) {
@@ -648,6 +662,7 @@ async function prepareResources(document, data, dataBytes, options, limits) {
resourceBytes.set(uri, resource.bytes);
}
const imageSizes = [];
+ const ktx2Weight = ktx2BudgetWeight(options.decoders?.ktx2);
for (const image of document.images ?? []) {
let bytes = resourceBytes.get(image.uri);
if (!bytes && image.bufferView !== undefined) {
@@ -661,18 +676,18 @@ async function prepareResources(document, data, dataBytes, options, limits) {
bytes = source.subarray(offset, offset + view.byteLength);
}
if (!bytes) throw new Error('glTF image has no supported source.');
- imageSizes.push(validateImage(bytes, limits.maxTextureImagePixels));
+ imageSizes.push(validateImage(bytes, limits.maxTextureImagePixels, ktx2Weight));
}
return { resourceBytes, textureScaling: planTextureScaling(document.images ?? [], imageSizes, limits.maxTexturePixels) };
}
/**
* Fit the combined texture pixels into the budget by halving the largest images together, so equal maps stay equal.
- * KTX2 images cannot be resized before transcoding; they count toward the budget and are never scaled.
+ * KTX2 images cannot be resized before transcoding; they count toward the budget (compressed ones at their weight) and are never scaled.
*/
function planTextureScaling(imageDefinitions, imageSizes, maxTexturePixels) {
const targets = imageSizes.map(({ width, height }) => ({ width, height }));
- const totalPixels = () => targets.reduce((sum, { width, height }) => sum + width * height, 0);
+ const totalPixels = () => targets.reduce((sum, { width, height }, index) => sum + width * height * imageSizes[index].weight, 0);
while (totalPixels() > maxTexturePixels) {
const scalable = targets.filter((target, index) => imageSizes[index].scalable && target.width * target.height > 1);
if (!scalable.length) throw new Error('Texture images exceed maxTexturePixels and cannot be scaled down further.');
@@ -853,9 +868,12 @@ function convertVertexColors(attribute, vertexCount, onIgnoredVertexAlpha) {
return colors;
}
-/** KTX2 textures arrive as RGBA8 pixel data, which the renderer uploads as an ImageData. */
+/**
+ * KTX2 textures arrive either as GPU-compressed mip levels, which the renderer uploads as they are,
+ * or as RGBA8 pixel data, which it uploads as an ImageData.
+ */
function decodedTextureImage(texture, field) {
- if (texture.isCompressedTexture) throw new Error(`${field} decoded to a GPU-compressed KTX2 format. Configure the KTX2 loader to transcode to RGBA8 (see docs/gltf.md).`);
+ if (texture.isCompressedTexture) return describeCompressedImage(texture.format, texture.mipmaps, field).image;
const image = texture.image;
if (!image?.data) return image;
const { width, height, data } = image;
@@ -888,6 +906,14 @@ function textureDescriptorFor(texture, field, { colorSpace, uvChannel, uvTransfo
return descriptors.get(key);
}
+/** One entry per texture descriptor: the GPU format it uploads in, its size and bytes of GPU memory. */
+function textureFormatsOf(maps) {
+ return [...maps.values()].flatMap(descriptors => [...descriptors.values()]).map(descriptor => {
+ const { width, height, compressed } = descriptor.image;
+ return { format: compressed?.name ?? 'rgba8', width, height, colorSpace: descriptor.colorSpace, bytes: textureDescriptorInfo(descriptor).bytes };
+ });
+}
+
function convertMaterial(source, limits, maps, definition = {}) {
const unlit = Boolean(definition.extensions?.KHR_materials_unlit);
const material = {
@@ -1362,7 +1388,7 @@ export async function parseGltf(data, options = {}) {
}
return stagePose({ animation: { clip: clipIndex, time: Math.max(0, Math.min(time, clip.duration)) } }).commit();
}
- return { parts, warnings, lights, scaledTextures: textureScaling.scaledTextures, skins: skinBindings.map(binding => binding.skin), animations: gltf.animations,
+ return { parts, warnings, lights, scaledTextures: textureScaling.scaledTextures, textureFormats: textureFormatsOf(maps), skins: skinBindings.map(binding => binding.skin), animations: gltf.animations,
get nodes() { return structuredClone(nodeMetadata); }, stagePose, applyAnimation, dispose, capabilities: GLTF_CAPABILITIES };
} catch (error) {
gltf?.release();
diff --git a/src/renderer.js b/src/renderer.js
index 0a7bf999..a78101ad 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -4,6 +4,7 @@ import { postFragment, createPostFragment, POST_STEPS, skyFragment, bloomFragmen
import { fullscreenVertex, startProgram, finishProgram, compileProgram } from './gl-program.js';
import { ambientOcclusionFragment } from './ambient-occlusion.js';
import { planRenderSize, estimateTextureBytes, estimateFrameBytes } from './budget.js';
+import { uploadCompressedImage } from './compressed-texture.js';
import { applyProjection } from './camera.js';
import { resolveEffects } from './effects.js';
import { frameDiagnostics } from './frame-diagnostics.js';
@@ -337,6 +338,13 @@ export function textureDescriptorInfo(map, maximumSize = Infinity) {
const magFilter = map.magFilter ?? 9729;
if (![10497, 33071, 33648].includes(wrapS) || ![10497, 33071, 33648].includes(wrapT)) throw new Error('Unsupported texture wrap mode.');
if (![9728, 9729, 9984, 9985, 9986, 9987].includes(minFilter) || ![9728, 9729].includes(magFilter)) throw new Error('Unsupported texture filtering mode.');
+ const compressed = map.image.compressed;
+ if (compressed) {
+ // A compressed image carries its own mips and cannot be mipmapped on the GPU. One level means no mip filtering.
+ const hasMips = compressed.levels.length > 1;
+ const effectiveMinFilter = hasMips || minFilter < 9984 ? minFilter : (minFilter === 9984 || minFilter === 9986 ? 9728 : 9729);
+ return { width, height, wrapS, wrapT, minFilter: effectiveMinFilter, magFilter, mipmaps: false, bytes: compressed.bytes };
+ }
const mipmaps = minFilter >= 9984;
return { width, height, wrapS, wrapT, minFilter, magFilter, mipmaps, bytes: estimateTextureBytes(width, height, { mipmaps }) };
}
@@ -678,7 +686,8 @@ export class Renderer67 {
context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, context.NONE);
if (map) {
const info = textureDescriptorInfo(map, context.getParameter(context.MAX_TEXTURE_SIZE));
- context.texImage2D(context.TEXTURE_2D, 0, map.colorSpace === 'linear' ? context.RGBA8 : context.SRGB8_ALPHA8, context.RGBA, context.UNSIGNED_BYTE, map.image);
+ if (map.image.compressed) uploadCompressedImage(context, map.image.compressed, map.colorSpace);
+ else context.texImage2D(context.TEXTURE_2D, 0, map.colorSpace === 'linear' ? context.RGBA8 : context.SRGB8_ALPHA8, context.RGBA, context.UNSIGNED_BYTE, map.image);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, info.wrapS);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, info.wrapT);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, info.minFilter);
diff --git a/tests/compressed-texture.test.js b/tests/compressed-texture.test.js
new file mode 100644
index 00000000..bbde8b27
--- /dev/null
+++ b/tests/compressed-texture.test.js
@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { ktx2WorkerConfigFor, describeCompressedImage, uploadCompressedImage } from '../src/compressed-texture.js';
+import { Renderer67, textureDescriptorInfo } from '../src/renderer.js';
+
+const BC7 = 0x8e8c;
+const BC7_SRGB = 0x8e8d;
+const BC3 = 0x83f3;
+const ETC2_RGBA = 0x9278;
+
+/** A WebGL2 stand-in that exposes only the named extensions and records the texture calls. */
+function fakeContext(extensionNames) {
+ const calls = [];
+ return {
+ calls,
+ TEXTURE_2D: 3553,
+ getExtension: name => (extensionNames.includes(name) ? {} : null),
+ texStorage2D: (...args) => calls.push(['texStorage2D', ...args]),
+ compressedTexSubImage2D: (target, level, x, y, width, height, format, data) => calls.push(['compressedTexSubImage2D', level, width, height, format, data.length]),
+ };
+}
+
+function bc7Levels() {
+ return [8, 4, 2, 1].map(size => ({ width: size, height: size, data: new Uint8Array(Math.ceil(size / 4) ** 2 * 16) }));
+}
+
+test('the KTX2 worker config follows the extensions the context exposes', () => {
+ const none = ktx2WorkerConfigFor(fakeContext([]));
+ assert.deepEqual(Object.values(none).filter(Boolean), []);
+ const desktop = ktx2WorkerConfigFor(fakeContext(['EXT_texture_compression_bptc', 'WEBGL_compressed_texture_s3tc', 'WEBGL_compressed_texture_s3tc_srgb']));
+ assert.equal(desktop.bptcSupported, true);
+ assert.equal(desktop.dxtSupported, true);
+ assert.equal(desktop.astcSupported, false);
+ const s3tcOnly = ktx2WorkerConfigFor(fakeContext(['WEBGL_compressed_texture_s3tc']));
+ assert.equal(s3tcOnly.dxtSupported, false);
+ const mobile = ktx2WorkerConfigFor(fakeContext(['WEBGL_compressed_texture_astc', 'WEBGL_compressed_texture_etc']));
+ assert.equal(mobile.astcSupported, true);
+ assert.equal(mobile.etc2Supported, true);
+});
+
+test('a compressed image uploads each mip level into immutable storage', () => {
+ const { image } = describeCompressedImage(BC7, bc7Levels(), 'map');
+ const context = fakeContext(['EXT_texture_compression_bptc']);
+ uploadCompressedImage(context, image.compressed, 'srgb');
+ assert.deepEqual(context.calls[0], ['texStorage2D', 3553, 4, BC7_SRGB, 8, 8]);
+ assert.deepEqual(context.calls.slice(1).map(call => call.slice(0, 5)), [
+ ['compressedTexSubImage2D', 0, 8, 8, BC7_SRGB],
+ ['compressedTexSubImage2D', 1, 4, 4, BC7_SRGB],
+ ['compressedTexSubImage2D', 2, 2, 2, BC7_SRGB],
+ ['compressedTexSubImage2D', 3, 1, 1, BC7_SRGB],
+ ]);
+});
+
+test('a linear map uploads the linear format', () => {
+ const { image } = describeCompressedImage(BC7, bc7Levels(), 'normalMap');
+ const context = fakeContext(['EXT_texture_compression_bptc']);
+ uploadCompressedImage(context, image.compressed, 'linear');
+ assert.equal(context.calls[0][3], BC7);
+});
+
+test('a context without the extension refuses the upload and names it', () => {
+ const { image } = describeCompressedImage(BC7, bc7Levels(), 'map');
+ assert.throws(() => uploadCompressedImage(fakeContext([]), image.compressed, 'srgb'), /EXT_texture_compression_bptc/);
+});
+
+test('an sRGB DXT map needs the sRGB S3TC extension', () => {
+ const levels = [{ width: 4, height: 4, data: new Uint8Array(16) }];
+ const { image } = describeCompressedImage(BC3, levels, 'map');
+ assert.throws(() => uploadCompressedImage(fakeContext(['WEBGL_compressed_texture_s3tc']), image.compressed, 'srgb'), /s3tc_srgb/);
+ uploadCompressedImage(fakeContext(['WEBGL_compressed_texture_s3tc']), image.compressed, 'linear');
+});
+
+test('block compressed levels must match their size and DXT must be a multiple of four', () => {
+ assert.throws(() => describeCompressedImage(BC7, [{ width: 8, height: 8, data: new Uint8Array(10) }], 'map'), /does not match/);
+ assert.throws(() => describeCompressedImage(BC3, [{ width: 6, height: 6, data: new Uint8Array(64) }], 'map'), /multiples of 4/);
+ describeCompressedImage(ETC2_RGBA, [{ width: 6, height: 6, data: new Uint8Array(64) }], 'map');
+});
+
+test('compressed bytes feed the renderer texture budget and a single level drops mip filtering', () => {
+ const full = describeCompressedImage(BC7, bc7Levels(), 'map').image;
+ const info = textureDescriptorInfo({ image: full });
+ assert.equal(info.bytes, 112);
+ assert.equal(info.mipmaps, false);
+ assert.equal(info.minFilter, 9987);
+ const single = describeCompressedImage(BC7, bc7Levels().slice(0, 1), 'map').image;
+ assert.equal(textureDescriptorInfo({ image: single }).minFilter, 9729);
+ assert.equal(textureDescriptorInfo({ image: single, minFilter: 9984 }).minFilter, 9728);
+});
+
+test('createTexture uploads a compressed image without generating mips', () => {
+ const calls = [];
+ const context = {
+ TEXTURE_2D: 3553,
+ NONE: 0,
+ UNPACK_FLIP_Y_WEBGL: 1,
+ UNPACK_COLORSPACE_CONVERSION_WEBGL: 2,
+ MAX_TEXTURE_SIZE: 3,
+ TEXTURE_WRAP_S: 4,
+ TEXTURE_WRAP_T: 5,
+ TEXTURE_MIN_FILTER: 6,
+ TEXTURE_MAG_FILTER: 7,
+ getParameter: () => 4096,
+ createTexture: () => ({}),
+ bindTexture: () => {},
+ pixelStorei: () => {},
+ texParameteri: () => {},
+ generateMipmap: () => calls.push('generateMipmap'),
+ texImage2D: () => calls.push('texImage2D'),
+ getExtension: name => (name === 'EXT_texture_compression_bptc' ? {} : null),
+ texStorage2D: () => calls.push('texStorage2D'),
+ compressedTexSubImage2D: () => calls.push('compressedTexSubImage2D'),
+ };
+ const map = { image: describeCompressedImage(BC7, bc7Levels(), 'map').image, colorSpace: 'srgb' };
+ const renderer = { context, textures: new Map(), applyAnisotropy: () => calls.push('anisotropy') };
+ Renderer67.prototype.createTexture.call(renderer, map);
+ assert.deepEqual(calls, ['texStorage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D']);
+});
diff --git a/tests/gltf-extensions.test.js b/tests/gltf-extensions.test.js
index a6c6b3c1..c8e88c5b 100644
--- a/tests/gltf-extensions.test.js
+++ b/tests/gltf-extensions.test.js
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import test from 'node:test';
-import { BufferGeometry, DataTexture, Float32BufferAttribute } from 'three';
+import { BufferGeometry, CompressedTexture, DataTexture, Float32BufferAttribute } from 'three';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
import { parseGltf } from '../src/gltf.js';
@@ -383,3 +383,77 @@ test('KHR_texture_basisu textures arrive as RGBA8 pixels from the supplied KTX2
assert.deepEqual(Array.from(image.data), Array.from(pixels));
await assert.rejects(parseGltf(data, { decoders: { ktx2: ktx2Loader }, maxTexturePixels: 3 }), /maxTexturePixels/);
});
+
+const BPTC_RGBA = 0x8e8c;
+const ETC1_RGB = 36196;
+
+/** A CompressedTexture shaped like the KTX2Loader result: BC7 mips of a square image, 16 bytes a 4x4 block. */
+function compressedKtx2Texture(size, format = BPTC_RGBA, { levelCount = Infinity } = {}) {
+ const mipmaps = [];
+ for (let width = size; width >= 1 && mipmaps.length < levelCount; width >>= 1) {
+ const blocks = Math.ceil(width / 4) ** 2;
+ mipmaps.push({ data: new Uint8Array(blocks * 16), width, height: width });
+ }
+ return new CompressedTexture(mipmaps, size, size, format);
+}
+
+function ktx2BaseColorDocument(size) {
+ const header = new Uint8Array(80);
+ header.set([0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a]);
+ new DataView(header.buffer).setUint32(20, size, true);
+ new DataView(header.buffer).setUint32(24, size, true);
+ return triangleDocument({
+ extraChunks: [header],
+ edit: document => {
+ document.images = [{ bufferView: 2, mimeType: 'image/ktx2' }];
+ document.textures = [{ extensions: { KHR_texture_basisu: { source: 0 } } }];
+ document.materials[0].pbrMetallicRoughness.baseColorTexture = { index: 0 };
+ document.extensionsUsed = ['KHR_texture_basisu'];
+ document.extensionsRequired = ['KHR_texture_basisu'];
+ },
+ });
+}
+
+function ktx2LoaderReturning(texture, workerConfig) {
+ return { workerConfig, load: (url, onLoad) => onLoad(texture) };
+}
+
+test('KHR_texture_basisu keeps a GPU-compressed texture and records its format and bytes', async context => {
+ mockImageBitmap(context);
+ const loader = ktx2LoaderReturning(compressedKtx2Texture(8), { bptcSupported: true });
+ const asset = await parseGltf(ktx2BaseColorDocument(8), { decoders: { ktx2: loader } });
+ const { image } = asset.parts[0].material.map;
+ assert.equal(image.compressed.name, 'bc7');
+ assert.equal(image.compressed.levels.length, 4);
+ assert.equal(image.compressed.bytes, 64 + 16 + 16 + 16);
+ assert.deepEqual(asset.textureFormats, [{ format: 'bc7', width: 8, height: 8, colorSpace: 'srgb', bytes: 112 }]);
+});
+
+test('a compressed KTX2 image counts a quarter of its RGBA8 pixels toward maxTexturePixels', async context => {
+ mockImageBitmap(context);
+ const texture = compressedKtx2Texture(8);
+ const unconfigured = ktx2LoaderReturning(texture, null);
+ const configured = ktx2LoaderReturning(texture, { bptcSupported: true });
+ await assert.rejects(parseGltf(ktx2BaseColorDocument(8), { decoders: { ktx2: unconfigured }, maxTexturePixels: 20 }), /maxTexturePixels/);
+ await parseGltf(ktx2BaseColorDocument(8), { decoders: { ktx2: configured }, maxTexturePixels: 20 });
+});
+
+test('a KTX2 loader that transcoded to RGBA8 reports the rgba8 format', async context => {
+ mockImageBitmap(context);
+ const loader = ktx2LoaderReturning(new DataTexture(new Uint8Array(4 * 2 * 2), 2, 2), { bptcSupported: false });
+ const asset = await parseGltf(ktx2BaseColorDocument(2), { decoders: { ktx2: loader } });
+ assert.equal(asset.textureFormats[0].format, 'rgba8');
+});
+
+test('a compressed KTX2 texture with a partial mip chain keeps its first level', async context => {
+ mockImageBitmap(context);
+ const loader = ktx2LoaderReturning(compressedKtx2Texture(8, BPTC_RGBA, { levelCount: 2 }), { bptcSupported: true });
+ const asset = await parseGltf(ktx2BaseColorDocument(8), { decoders: { ktx2: loader } });
+ assert.equal(asset.parts[0].material.map.image.compressed.levels.length, 1);
+});
+
+test('a compressed KTX2 format 67js does not upload fails with a clear message', async context => {
+ mockImageBitmap(context);
+ const loader = ktx2LoaderReturning(compressedKtx2Texture(8, ETC1_RGB), { bptcSupported: true });
+ await assert.rejects(parseGltf(ktx2BaseColorDocument(8), { decoders: { ktx2: loader } }), /does not upload/);
+});