Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.js
index 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.js
index 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, uvTransfo
const 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.js
index a78101ad..885e9a98 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -4,7 +4,6 @@ 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';
@@ -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.js
index 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']);
});