3D engine that AI agents drive
Keep compressed texture formats out of core: generic upload hook in the renderer
Nguyen Xuan An1985258e2c64
diff --git a/src/compressed-texture.js b/src/compressed-texture.jsindex eeb3084d..1ff9d5f7 100644--- a/src/compressed-texture.js+++ b/src/compressed-texture.js@@ -1,5 +1,5 @@-// 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 }] } }.+// GPU-compressed texture formats that a KTX2 loader can hand over. Only the glTF addon imports this file.+// It hands the renderer a generic image: { width, height, compressed: { internalFormat, extension, levels: [{ data, width, height }], bytes } }.const BPTC = 'EXT_texture_compression_bptc';const S3TC = 'WEBGL_compressed_texture_s3tc';@@ -41,7 +41,7 @@ export function compressedFormatInfo(glFormat) {* 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) {+export function describeCompressedImage(glFormat, levels, field, colorSpace) {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.`);@@ -56,28 +56,10 @@ export function describeCompressedImage(glFormat, levels, field) {}}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);- });+ const internalFormat = srgb ? info.srgbFormat : glFormat;+ return { width: base.width, height: base.height, compressed: { internalFormat, extension, name: info.name, levels: usable, bytes } };}/**diff --git a/src/gltf.js b/src/gltf.jsindex 51b99deb..971da74b 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -872,8 +872,8 @@ function convertVertexColors(attribute, vertexCount, onIgnoredVertexAlpha) {* 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) return describeCompressedImage(texture.format, texture.mipmaps, field).image;+function decodedTextureImage(texture, field, colorSpace) {+ if (texture.isCompressedTexture) return describeCompressedImage(texture.format, texture.mipmaps, field, colorSpace);const image = texture.image;if (!image?.data) return image;const { width, height, data } = image;@@ -887,7 +887,7 @@ function textureDescriptorFor(texture, field, { colorSpace, uvChannel, uvTransfoconst descriptors = maps.get(texture);const key = `${colorSpace}:${uvChannel}:${uvTransform ?? ''}`;if (!descriptors.has(key)) {- const image = decodedTextureImage(texture, field);+ const image = decodedTextureImage(texture, field, colorSpace);if (!image || image.width * image.height > limits.maxTextureImagePixels) throw new Error(`${field} image is missing or exceeds maxTextureImagePixels.`);const descriptor = {image,diff --git a/src/renderer.js b/src/renderer.jsindex a78101ad..885e9a98 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -4,7 +4,6 @@ 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';@@ -340,10 +339,9 @@ export function textureDescriptorInfo(map, maximumSize = Infinity) {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 };+ // Precompressed mips come with the image and cannot be generated. A single level drops mip filtering (odd enums are linear).+ const singleLevel = compressed.levels.length === 1 && minFilter >= 9984;+ return { width, height, wrapS, wrapT, minFilter: singleLevel ? 9728 + (minFilter & 1) : minFilter, magFilter, mipmaps: false, bytes: compressed.bytes };}const mipmaps = minFilter >= 9984;return { width, height, wrapS, wrapT, minFilter, magFilter, mipmaps, bytes: estimateTextureBytes(width, height, { mipmaps }) };@@ -674,6 +672,14 @@ export class Renderer67 {context.texParameterf(target, extension.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(MAX_TEXTURE_ANISOTROPY, supported));}+ /** Upload precompressed mips ({ internalFormat, extension, levels }) into the bound texture. */+ uploadCompressedLevels({ internalFormat, extension, levels }) {+ const context = this.context;+ if (!context.getExtension(extension)) throw new Error(`This context lacks ${extension}, which the compressed texture needs (see docs/gltf.md).`);+ context.texStorage2D(context.TEXTURE_2D, levels.length, internalFormat, levels[0].width, levels[0].height);+ levels.forEach((level, index) => context.compressedTexSubImage2D(context.TEXTURE_2D, index, 0, 0, level.width, level.height, internalFormat, level.data));+ }+createTexture(map) {if (this.textures.has(map)) return this.textures.get(map);const context = this.context;@@ -686,7 +692,7 @@ export class Renderer67 {context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, context.NONE);if (map) {const info = textureDescriptorInfo(map, context.getParameter(context.MAX_TEXTURE_SIZE));- if (map.image.compressed) uploadCompressedImage(context, map.image.compressed, map.colorSpace);+ if (map.image.compressed) this.uploadCompressedLevels(map.image.compressed);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);diff --git a/tests/compressed-texture.test.js b/tests/compressed-texture.test.jsindex bbde8b27..d59e1411 100644--- a/tests/compressed-texture.test.js+++ b/tests/compressed-texture.test.js@@ -1,6 +1,6 @@import assert from 'node:assert/strict';import test from 'node:test';-import { ktx2WorkerConfigFor, describeCompressedImage, uploadCompressedImage } from '../src/compressed-texture.js';+import { ktx2WorkerConfigFor, describeCompressedImage } from '../src/compressed-texture.js';import { Renderer67, textureDescriptorInfo } from '../src/renderer.js';const BC7 = 0x8e8c;@@ -20,6 +20,10 @@ function fakeContext(extensionNames) {};}+function uploadLevels(context, image) {+ Renderer67.prototype.uploadCompressedLevels.call({ context }, image.compressed);+}+function bc7Levels() {return [8, 4, 2, 1].map(size => ({ width: size, height: size, data: new Uint8Array(Math.ceil(size / 4) ** 2 * 16) }));}@@ -39,9 +43,9 @@ test('the KTX2 worker config follows the extensions the context exposes', () =>});test('a compressed image uploads each mip level into immutable storage', () => {- const { image } = describeCompressedImage(BC7, bc7Levels(), 'map');+ const image = describeCompressedImage(BC7, bc7Levels(), 'map', 'srgb');const context = fakeContext(['EXT_texture_compression_bptc']);- uploadCompressedImage(context, image.compressed, 'srgb');+ uploadLevels(context, image);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],@@ -52,22 +56,23 @@ test('a compressed image uploads each mip level into immutable storage', () => {});test('a linear map uploads the linear format', () => {- const { image } = describeCompressedImage(BC7, bc7Levels(), 'normalMap');+ const image = describeCompressedImage(BC7, bc7Levels(), 'normalMap', 'linear');const context = fakeContext(['EXT_texture_compression_bptc']);- uploadCompressedImage(context, image.compressed, 'linear');+ uploadLevels(context, image);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/);+ const image = describeCompressedImage(BC7, bc7Levels(), 'map', 'srgb');+ assert.throws(() => uploadLevels(fakeContext([]), image), /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');+ const srgb = describeCompressedImage(BC3, levels, 'map', 'srgb');+ assert.throws(() => uploadLevels(fakeContext(['WEBGL_compressed_texture_s3tc']), srgb), /s3tc_srgb/);+ const linear = describeCompressedImage(BC3, levels, 'map', 'linear');+ uploadLevels(fakeContext(['WEBGL_compressed_texture_s3tc']), linear);});test('block compressed levels must match their size and DXT must be a multiple of four', () => {@@ -77,12 +82,12 @@ test('block compressed levels must match their size and DXT must be a multiple o});test('compressed bytes feed the renderer texture budget and a single level drops mip filtering', () => {- const full = describeCompressedImage(BC7, bc7Levels(), 'map').image;+ const full = describeCompressedImage(BC7, bc7Levels(), 'map', 'srgb');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;+ const single = describeCompressedImage(BC7, bc7Levels().slice(0, 1), 'map', 'srgb');assert.equal(textureDescriptorInfo({ image: single }).minFilter, 9729);assert.equal(textureDescriptorInfo({ image: single, minFilter: 9984 }).minFilter, 9728);});@@ -110,8 +115,8 @@ test('createTexture uploads a compressed image without generating mips', () => {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') };+ const map = { image: describeCompressedImage(BC7, bc7Levels(), 'map', 'srgb'), colorSpace: 'srgb' };+ const renderer = { context, textures: new Map(), applyAnisotropy: () => calls.push('anisotropy'), uploadCompressedLevels: Renderer67.prototype.uploadCompressedLevels };Renderer67.prototype.createTexture.call(renderer, map);assert.deepEqual(calls, ['texStorage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D', 'compressedTexSubImage2D']);});