3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Reads and writes the glTF material extensions that map onto the material layers of material-layers.js.
import { MATERIAL_LAYER_DEFAULTS, MATERIAL_LAYER_SCALAR_RANGES, validateMaterialLayers } from './material-layers.js';
export const GLTF_LAYER_EXTENSIONS = Object.freeze([
'KHR_materials_clearcoat',
'KHR_materials_transmission',
'KHR_materials_volume',
'KHR_materials_ior',
'KHR_materials_dispersion',
'KHR_materials_specular',
'KHR_materials_sheen',
'KHR_materials_anisotropy',
'KHR_materials_iridescence',
]);
// Each row: extension, then the glTF property that feeds each material field.
const IMPORT_RULES = Object.freeze([
['KHR_materials_clearcoat', { clearcoat: 'clearcoatFactor', clearcoatRoughness: 'clearcoatRoughnessFactor' }],
['KHR_materials_transmission', { transmission: 'transmissionFactor' }],
['KHR_materials_volume', { thickness: 'thicknessFactor', attenuationDistance: 'attenuationDistance', attenuationColor: 'attenuationColor' }],
['KHR_materials_ior', { ior: 'ior' }],
['KHR_materials_dispersion', { dispersion: 'dispersion' }],
['KHR_materials_specular', { specular: 'specularFactor', specularColor: 'specularColorFactor' }],
['KHR_materials_sheen', { sheenColor: 'sheenColorFactor', sheenRoughness: 'sheenRoughnessFactor' }],
['KHR_materials_anisotropy', { anisotropy: 'anisotropyStrength', anisotropyRotation: 'anisotropyRotation' }],
// Without a thickness texture the film is as thick as the maximum, so the minimum is not kept.
['KHR_materials_iridescence', { iridescence: 'iridescenceFactor', iridescenceIor: 'iridescenceIor', iridescenceThickness: 'iridescenceThicknessMaximum' }],
]);
// Texture slots inside the layer extensions. Each row: the extension, the glTF property and the texture's colour space.
// The property is also the key under material.layerMaps, the GLSL sampler and the shader feature (material-layer-shaders.js).
// Slots without shader code (transmissionTexture, the iridescence and specular textures) are not read: a factor is used.
export const LAYER_TEXTURE_SLOTS = Object.freeze([
['KHR_materials_clearcoat', 'clearcoatTexture', 'linear'],
['KHR_materials_clearcoat', 'clearcoatRoughnessTexture', 'linear'],
['KHR_materials_clearcoat', 'clearcoatNormalTexture', 'linear'],
['KHR_materials_anisotropy', 'anisotropyTexture', 'linear'],
['KHR_materials_sheen', 'sheenColorTexture', 'srgb'],
['KHR_materials_sheen', 'sheenRoughnessTexture', 'linear'],
]);
/** The texture references a material definition makes inside its layer extensions: [glTF property, reference, colour space]. */
export function layerTextureReferences(definition) {
const references = [];
for (const [extensionName, property, colorSpace] of LAYER_TEXTURE_SLOTS) {
const reference = definition?.extensions?.[extensionName]?.[property];
if (reference) references.push([property, reference, colorSpace]);
}
return references;
}
const MAXIMUM_IOR = MATERIAL_LAYER_SCALAR_RANGES.ior[1];
// glTF allows any ior of 1 or more (exporters write 1000 for a mirror), so a high value is kept at the top of the range instead of refusing the file.
/** One warning per material whose KHR_materials_ior is above the supported range and was kept at its top. */
export function clampedIorWarnings(document) {
const warnings = [];
document.materials?.forEach((definition, index) => {
const ior = definition?.extensions?.KHR_materials_ior?.ior;
if (typeof ior === 'number' && ior > MAXIMUM_IOR) warnings.push(`The ior of material ${index} is ${ior}; it was set to ${MAXIMUM_IOR}.`);
});
return warnings;
}
/** Layer fields of one glTF material definition, validated, as a plain object to spread onto a material. */
export function materialLayersFromGltf(definition) {
const layers = {};
for (const [extensionName, properties] of IMPORT_RULES) {
const extension = definition?.extensions?.[extensionName];
if (!extension) continue;
for (const [field, property] of Object.entries(properties)) {
if (extension[property] !== undefined) layers[field] = extension[property];
}
}
if (typeof layers.ior === 'number') layers.ior = layers.ior === 0 ? 1 : Math.min(layers.ior, MAXIMUM_IOR);
validateMaterialLayers(layers);
return layers;
}
function differsFromDefault(field, value) {
return JSON.stringify(value) !== JSON.stringify(MATERIAL_LAYER_DEFAULTS[field]);
}
function extensionProperties(material, properties) {
const written = {};
for (const [field, property] of Object.entries(properties)) {
if (material[field] === undefined || !differsFromDefault(field, material[field])) continue;
written[property] = Array.isArray(material[field]) ? [...material[field]] : material[field];
}
return written;
}
/** The KHR_materials_* objects a material needs, keyed by extension name; empty when it uses no layer. */
export function gltfExtensionsFromLayers(material) {
validateMaterialLayers(material);
const extensions = {};
for (const [extensionName, properties] of IMPORT_RULES) {
const written = extensionProperties(material, properties);
if (Object.keys(written).length > 0) extensions[extensionName] = written;
}
return extensions;
}