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.mdnew file mode 100644index 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.mdindex 0c19dd99..69d1fd6f 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -160,19 +160,35 @@ A Draco loader needs `decodeDracoFile(buffer, onLoad, attributeIds, attributeTyp```jsimport { 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 limitsdiff --git a/src/compressed-texture.js b/src/compressed-texture.jsnew file mode 100644index 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.jsindex 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.jsindex 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.jsindex 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, uvTransforeturn 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.jsindex 0a7bf999..a78101ad 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -4,6 +4,7 @@ import { postFragment, createPostFragment, POST_STEPS, skyFragment, bloomFragmenimport { 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.jsnew file mode 100644index 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.jsindex 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 KTX2assert.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/);+});