3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// 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: { levels, bytes, minFilter(filter), upload(context) } }.
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 hasPositiveIntegerSize(level) {
return Number.isInteger(level?.width) && Number.isInteger(level?.height) && level.width >= 1 && level.height >= 1;
}
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 Crucible 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, colorSpace) {
const info = compressedFormatInfo(glFormat);
if (!info) throw new Error(`${field} decoded to GPU format ${glFormat}, which Crucible 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 (!hasPositiveIntegerSize(base)) {
throw new Error(`${field} ${info.name} texture base level must have a whole width and height of at least 1, got ${base?.width}x${base?.height}.`);
}
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];
usable.forEach((level, index) => {
if (!hasPositiveIntegerSize(level)) throw new Error(`${field} ${info.name} mip level ${index} is missing or has no whole width and height; pass { width, height, data } for every level.`);
const expectedWidth = Math.max(1, base.width >> index);
const expectedHeight = Math.max(1, base.height >> index);
if (level.width !== expectedWidth || level.height !== expectedHeight) {
throw new Error(`${field} ${info.name} mip level ${index} is ${level.width}x${level.height}, but a chain from ${base.width}x${base.height} needs ${expectedWidth}x${expectedHeight}.`);
}
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);
const srgb = colorSpace !== 'linear';
const extension = srgb && info.srgbExtension ? info.srgbExtension : info.extension;
const internalFormat = srgb ? info.srgbFormat : glFormat;
return { width: base.width, height: base.height, compressed: { name: info.name, levels: usable, bytes, minFilter: minFilterFor(usable.length), upload: context => uploadLevels(context, usable, internalFormat, extension) } };
}
// A single level cannot be mip filtered. Odd filter enums are the linear ones.
function minFilterFor(levelCount) {
return minFilter => (levelCount === 1 && minFilter >= 9984 ? 9728 + (minFilter & 1) : minFilter);
}
/** Upload every mip level into the bound TEXTURE_2D with immutable storage. */
function uploadLevels(context, levels, internalFormat, extension) {
if (!context.getExtension(extension)) {
throw new Error(`This context lacks ${extension}, which the compressed texture needs. Transcode KTX2 for this context with ktx2WorkerConfigFor(context) (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);
});
}
/**
* 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,
};
}