@driftengine/assets 4.6.1 → 4.7.1

package/dist/blendGltf.js

@@ -0,0 +1,545 @@
+/**
+ * A `.blend` as a glTF document in memory, so that `readModel` reads it through the glTF reader.
+ *
+ * **Why glTF in the middle.** Blender's own exporter writes glTF, and the baker hands a file it
+ * cannot read directly to that exporter. Building the same document here means the two routes share
+ * every step after it — materials, textures, skins, lights, the flattening into world space — and
+ * so cannot drift apart on any of them. It also makes Blender's export of a fixture an independent
+ * check on this one: the two documents should say the same thing.
+ *
+ * **What it refuses** it lists in `refusals`, and `readBlend` declines the whole file: a modifier,
+ * a constraint, a rig, a curve. Half a scene is worse than an error, because nobody can see what is
+ * missing. **What it approximates** — a node graph glTF cannot hold, animation it does not read —
+ * it lists in `approximations` and draws anyway, as Blender's exporter would.
+ */
+import { invert, multiply } from './blendMatrix.js';
+import { readBlendMesh } from './blendMesh.js';
+import { cornerNormals } from './blendNormals.js';
+import { meshPrimitives } from './blendGeometry.js';
+import { readBlendSurface } from './blendMaterial.js';
+import { judgeModifiers } from './blendModifiers.js';
+import { OB_ARMATURE, OB_LAMP, OB_MESH, placeObjects } from './blendScene.js';
+/** Blender Z up to glTF Y up, and back: the basis change Blender's exporter applies. */
+const Z_TO_Y = [1, 0, 0, 0, 0, 0, -1, 0, 0, 1, 0, 0, 0, 0, 0, 1];
+const Y_TO_Z = [1, 0, 0, 0, 0, 0, 1, 0, 0, -1, 0, 0, 0, 0, 0, 1];
+/** A light shines down its local -Z in Blender and in glTF; this keeps it shining the same way. */
+const LIGHT_CORRECTION = [1, 0, 0, 0, 0, 0, -1, 0, 0, 1, 0, 0, 0, 0, 0, 1];
+const WATTS_TO_LUMENS = 683;
+/** `Light.mode`'s bit for a colour taken from a temperature, read off a fixture that sets it. */
+const LA_USE_TEMPERATURE = 1 << 24;
+const KEYBLOCK_MUTE = 1;
+/** Accessors and buffer views over one growing binary chunk. */
+class Builder {
+    doc;
+    chunks = [];
+    length = 0;
+    constructor(doc) {
+        this.doc = { ...doc, accessors: [], bufferViews: [] };
+    }
+    view(bytes) {
+        const pad = (4 - (this.length % 4)) % 4;
+        if (pad > 0)
+            this.push(new Uint8Array(pad));
+        const index = this.doc.bufferViews.length;
+        this.doc.bufferViews.push({ buffer: 0, byteOffset: this.length, byteLength: bytes.length });
+        this.push(bytes);
+        return index;
+    }
+    accessor(data, type) {
+        const width = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 }[type];
+        const view = this.view(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+        const index = this.doc.accessors.length;
+        this.doc.accessors.push({
+            bufferView: view,
+            componentType: data instanceof Uint32Array ? 5125 : 5126,
+            count: data.length / width,
+            type,
+        });
+        return index;
+    }
+    finish() {
+        const out = new Uint8Array(this.length);
+        let at = 0;
+        for (const chunk of this.chunks) {
+            out.set(chunk, at);
+            at += chunk.length;
+        }
+        this.doc.buffers = [{ byteLength: this.length }];
+        return out;
+    }
+    push(bytes) {
+        this.chunks.push(bytes);
+        this.length += bytes.length;
+    }
+}
+/** The bytes a packed image holds, or null where it lives in a file beside the `.blend`. */
+export function packedImage(image) {
+    const packed = image.has('packedfiles')
+        ? image.list('packedfiles')[0]?.deref('packedfile')
+        : null;
+    const file = packed ?? (image.has('packedfile') ? image.deref('packedfile') : null);
+    if (file === null || file === undefined)
+        return null;
+    const data = file.raw('data');
+    return data === null ? null : data.subarray(0, file.int('size'));
+}
+/**
+ * Whether an image stores one channel: a grey PNG, or a JPEG of one component. An image that is not
+ * packed cannot be looked at here and is taken to be grey, which is what a scalar map usually is.
+ */
+export function isGreyImage(image) {
+    const bytes = packedImage(image);
+    if (bytes === null)
+        return true;
+    if (bytes[0] === 0x89 && bytes[1] === 0x50)
+        return bytes[25] === 0 || bytes[25] === 4;
+    if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+        for (let at = 2; at + 9 < bytes.length;) {
+            if (bytes[at] !== 0xff)
+                return false;
+            const marker = bytes[at + 1];
+            const length = (bytes[at + 2] << 8) | bytes[at + 3];
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc)
+                return bytes[at + 9] === 1;
+            at += 2 + length;
+        }
+    }
+    return false;
+}
+/** A packed image's media type, from its first bytes. */
+export function imageMime(bytes) {
+    if (bytes[0] === 0x89 && bytes[1] === 0x50)
+        return 'image/png';
+    if (bytes[0] === 0xff && bytes[1] === 0xd8)
+        return 'image/jpeg';
+    if (bytes[0] === 0x52 && bytes[8] === 0x57 && bytes[9] === 0x45)
+        return 'image/webp';
+    return null;
+}
+/** Where an unpacked image lives, relative to the `.blend` when Blender wrote it that way. */
+export function imagePath(image) {
+    const path = image.string('name');
+    return path.startsWith('//') ? path.slice(2) : path;
+}
+/** Build the document. */
+export function blendToGltf(blend, options = {}) {
+    const refusals = [];
+    const approximations = [];
+    const warnings = [];
+    const notes = [];
+    const only = options.only;
+    const placed = only === undefined
+        ? placeObjects(blend, refusals, () => null)
+        : [
+            {
+                object: only,
+                name: only.idName(),
+                kind: only.int('type'),
+                world: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+                parent: -1,
+            },
+        ];
+    const builder = new Builder({
+        asset: { version: '2.0', generator: 'DriftEngine .blend reader' },
+    });
+    const doc = builder.doc;
+    doc.nodes = [];
+    doc.meshes = [];
+    doc.materials = [];
+    doc.textures = [];
+    doc.images = [];
+    const lights = [];
+    const used = new Set();
+    const imageIndex = new Map();
+    const textureOf = (image) => {
+        const known = imageIndex.get(image.offset);
+        if (known !== undefined)
+            return known;
+        const bytes = packedImage(image);
+        const name = image.idName();
+        const source = image.int('source');
+        if (bytes === null && source === 4)
+            approximations.push(`image "${name}" is generated by Blender and not packed, so it is drawn without`);
+        if (source === 6)
+            approximations.push(`image "${name}" is tiled across UDIMs, and only its first tile is read`);
+        const entry = { name };
+        if (options.imageUri !== undefined)
+            entry.uri = options.imageUri(image);
+        else if (bytes !== null) {
+            const mime = imageMime(bytes);
+            if (mime === null)
+                approximations.push(`image "${name}" is in a format the engine does not decode, which Blender's exporter converts`);
+            entry.bufferView = builder.view(bytes);
+            entry.mimeType = mime ?? 'application/octet-stream';
+        }
+        else
+            entry.uri = imagePath(image).split('/').map(encodeURIComponent).join('/');
+        const index = doc.images.length;
+        doc.images.push(entry);
+        doc.textures.push({ source: index });
+        imageIndex.set(image.offset, index);
+        return index;
+    };
+    const surfaces = new Map();
+    const materialIndex = new Map();
+    const surfaceOf = (material) => {
+        let surface = surfaces.get(material.offset);
+        if (surface === undefined) {
+            surface = readBlendSurface(material, blend.header.version);
+            surfaces.set(material.offset, surface);
+            warnings.push(...surface.approximations);
+        }
+        return surface;
+    };
+    const gltfMaterial = (material) => {
+        const known = materialIndex.get(material.offset);
+        if (known !== undefined)
+            return known;
+        const json = surfaceToGltf(surfaceOf(material), textureOf, approximations);
+        const index = doc.materials.length;
+        doc.materials.push(json);
+        materialIndex.set(material.offset, index);
+        if (json.extensions !== undefined)
+            for (const name of Object.keys(json.extensions))
+                used.add(name);
+        return index;
+    };
+    const meshCache = new Map();
+    const worlds = placed.map((p) => {
+        const world = multiply(multiply(Z_TO_Y, p.world), Y_TO_Z);
+        return p.kind === OB_LAMP ? multiply(world, LIGHT_CORRECTION) : world;
+    });
+    placed.forEach((p, i) => {
+        const node = { name: p.name };
+        const parentWorld = p.parent >= 0 ? worlds[p.parent] : null;
+        node['matrix'] =
+            parentWorld === null ? worlds[i] : multiply(invert(parentWorld), worlds[i]);
+        if (p.kind === OB_ARMATURE)
+            refusals.push(`"${p.name}" is an armature, and the direct reader does not read rigs yet`);
+        if (p.object.has('adt') && p.object.ptr('adt') !== 0n)
+            approximations.push(`"${p.name}" is animated, and the direct reader draws the frame it was saved on`);
+        if (p.kind === OB_MESH) {
+            const mesh = meshOf(p, blend, refusals, warnings, gltfMaterial, builder, meshCache);
+            if (mesh !== null)
+                node['mesh'] = mesh;
+        }
+        else if (p.kind === OB_LAMP) {
+            const light = lightOf(p, warnings);
+            if (light !== null) {
+                node['extensions'] = { KHR_lights_punctual: { light: lights.length } };
+                lights.push(light);
+            }
+        }
+        doc.nodes.push(node);
+    });
+    placed.forEach((p, i) => {
+        if (p.parent < 0)
+            return;
+        const parent = doc.nodes[p.parent];
+        parent['children'] = [...(parent['children'] ?? []), i];
+    });
+    doc.scenes = [{ nodes: placed.map((p, i) => (p.parent < 0 ? i : -1)).filter((i) => i >= 0) }];
+    doc.scene = 0;
+    if (lights.length > 0) {
+        doc.extensions = { KHR_lights_punctual: { lights } };
+        used.add('KHR_lights_punctual');
+    }
+    if (used.size > 0)
+        doc.extensionsUsed = [...used];
+    notes.push(`blend: Blender ${blend.header.version}, ${placed.length} objects, ${doc.meshes.length} meshes, ${doc.materials.length} materials.`);
+    return {
+        doc,
+        binary: builder.finish(),
+        refusals: [...new Set(refusals)],
+        approximations: [...new Set(approximations)],
+        warnings: [...new Set(warnings)],
+        notes,
+    };
+}
+function meshOf(p, blend, refusals, approximations, gltfMaterial, builder, cache) {
+    const data = p.object.deref('data');
+    if (data === null)
+        return null;
+    const verdict = judgeModifiers(p.object);
+    refusals.push(...verdict.refusals);
+    if (verdict.refusals.length > 0)
+        return null;
+    const slots = materialSlots(p.object, data);
+    const key = `${data.offset}:${verdict.splitAngle}:${slots.map((s) => s?.offset ?? 0).join(',')}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const mesh = readBlendMesh(blend, data);
+    const normals = cornerNormals(mesh, verdict.splitAngle ?? mesh.autoSmooth);
+    const surfaces = slots.map((material) => material === null ? null : readBlendSurface(material, blend.header.version));
+    const primitives = meshPrimitives(mesh, normals, slots.length, (slot) => {
+        const surface = surfaces[slot] ?? null;
+        return {
+            vertexColor: surface?.vertexColor ?? null,
+            uvMap: surface?.uvMap ?? null,
+            uvTransform: surface?.uvTransform ?? null,
+        };
+    });
+    const keys = shapeKeys(data, mesh.positions.length / 3);
+    if (keys.some((k) => k.vgroup !== ''))
+        approximations.push(`mesh "${mesh.name}" has a shape key limited to a vertex group, which glTF cannot limit`);
+    const gltfPrimitives = primitives.map((primitive) => {
+        const attributes = {
+            POSITION: builder.accessor(primitive.positions, 'VEC3'),
+            NORMAL: builder.accessor(primitive.normals, 'VEC3'),
+        };
+        if (primitive.uvs !== null)
+            attributes['TEXCOORD_0'] = builder.accessor(primitive.uvs, 'VEC2');
+        if (primitive.colors !== null)
+            attributes['COLOR_0'] = builder.accessor(primitive.colors, 'VEC4');
+        const out = {
+            attributes,
+            indices: builder.accessor(primitive.indices, 'SCALAR'),
+            mode: 4,
+        };
+        const material = primitive.slot >= 0 ? slots[primitive.slot] : null;
+        if (material !== null && material !== undefined)
+            out['material'] = gltfMaterial(material);
+        if (keys.length > 0) {
+            out['targets'] = keys.map((key) => {
+                const delta = new Float32Array(primitive.positions.length);
+                const normalDelta = new Float32Array(primitive.positions.length);
+                const shaped = cornerNormals({ ...mesh, positions: key.positions }, verdict.splitAngle ?? mesh.autoSmooth);
+                for (let e = 0; e < primitive.sourceVertex.length; e++) {
+                    const v = primitive.sourceVertex[e];
+                    const c = primitive.sourceCorner[e];
+                    const d = [0, 1, 2].map((k) => key.positions[v * 3 + k] - key.reference[v * 3 + k]);
+                    delta.set([d[0], d[2], -d[1]], e * 3);
+                    const n = [0, 1, 2].map((k) => shaped[c * 3 + k] - normals[c * 3 + k]);
+                    normalDelta.set([n[0], n[2], -n[1]], e * 3);
+                }
+                return {
+                    POSITION: builder.accessor(delta, 'VEC3'),
+                    NORMAL: builder.accessor(normalDelta, 'VEC3'),
+                };
+            });
+        }
+        return out;
+    });
+    const meshes = builder.doc.meshes;
+    const entry = { name: mesh.name, primitives: gltfPrimitives };
+    if (keys.length > 0) {
+        entry['weights'] = keys.map((k) => k.weight);
+        entry['extras'] = { targetNames: keys.map((k) => k.name) };
+    }
+    meshes.push(entry);
+    cache.set(key, meshes.length - 1);
+    return meshes.length - 1;
+}
+/** An object's material slots: the object's own material where its slot says so, else the mesh's. */
+export function materialSlots(object, mesh) {
+    const count = Math.max(object.int('totcol'), mesh.int('totcol'));
+    const own = object.int('totcol') > 0 ? object.pointers('mat', object.int('totcol')) : [];
+    const shared = mesh.int('totcol') > 0 ? mesh.pointers('mat', mesh.int('totcol')) : [];
+    const bits = object.int('totcol') > 0 ? object.raw('matbits') : null;
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        const useObject = bits !== null && (bits[i] ?? 0) !== 0;
+        const address = useObject ? own[i] : shared[i];
+        out.push(address === undefined || address === 0n
+            ? null
+            : (useObject ? object : mesh).file.at(address, (useObject ? object : mesh).scope));
+    }
+    return out;
+}
+/** The mesh's shape keys other than its basis, each with the key it is relative to. */
+function shapeKeys(mesh, verts) {
+    const key = mesh.deref('key');
+    if (key === null)
+        return [];
+    const blocks = key.list('block');
+    const read = (block) => {
+        const raw = block.raw('data');
+        const out = new Float32Array(verts * 3);
+        if (raw === null)
+            return out;
+        const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+        const le = block.file.header.littleEndian;
+        for (let i = 0; i < Math.min(verts * 3, raw.length / 4); i++)
+            out[i] = view.getFloat32(i * 4, le);
+        return out;
+    };
+    const basis = key.ptr('refkey');
+    const out = [];
+    const cache = new Map();
+    const data = (index) => {
+        let found = cache.get(index);
+        if (found === undefined)
+            cache.set(index, (found = read(blocks[index])));
+        return found;
+    };
+    blocks.forEach((block, index) => {
+        if (block.offset === key.file.at(basis, key.scope)?.offset)
+            return;
+        if ((block.int('flag') & KEYBLOCK_MUTE) !== 0)
+            return;
+        const relative = Math.max(0, Math.min(blocks.length - 1, block.int('relative')));
+        if (relative === index)
+            return;
+        out.push({
+            name: block.string('name'),
+            weight: block.float('curval'),
+            positions: data(index),
+            reference: data(relative),
+            vgroup: block.string('vgroup'),
+        });
+    });
+    return out;
+}
+function lightOf(p, warnings) {
+    const lamp = p.object.deref('data');
+    if (lamp === null)
+        return null;
+    const type = lamp.int('type');
+    const exposure = lamp.has('exposure') ? 2 ** lamp.float('exposure') : 1;
+    let color = [lamp.float('r'), lamp.float('g'), lamp.float('b')];
+    if (lamp.has('mode') &&
+        lamp.has('temperature') &&
+        (lamp.int('mode') & LA_USE_TEMPERATURE) !== 0) {
+        const warmth = blackbody(lamp.float('temperature'));
+        color = color.map((c, i) => c * warmth[i]);
+    }
+    if (type === 1)
+        return {
+            type: 'directional',
+            name: p.name,
+            color,
+            intensity: lamp.float('energy') * WATTS_TO_LUMENS * exposure,
+        };
+    const intensity = (lamp.float('energy') / (4 * Math.PI)) * WATTS_TO_LUMENS * exposure;
+    if (type === 0)
+        return { type: 'point', name: p.name, color, intensity };
+    if (type === 2) {
+        const outer = lamp.float('spotsize') / 2;
+        return {
+            type: 'spot',
+            name: p.name,
+            color,
+            intensity,
+            spot: { innerConeAngle: outer - outer * lamp.float('spotblend'), outerConeAngle: outer },
+        };
+    }
+    warnings.push(`light "${p.name}" is an area light, which glTF cannot express, so it is left out`);
+    return null;
+}
+/**
+ * The colour of a black body at `kelvin`, in linear Rec. 709, scaled to unit luminance: what
+ * Blender multiplies a light's colour by when the light takes its colour from a temperature.
+ *
+ * Planck's law through the CIE 1931 observer, by the multi-lobe fit of Wyman, Sloan and Shirley.
+ * **Within 1% of Blender's table, not equal to it**: Blender's is fitted per range to its own colour
+ * configuration, and at 3000 K reads (1.771, 0.844, 0.272) where this reads (1.752, 0.850, 0.271).
+ */
+export function blackbody(kelvin) {
+    const lobe = (x, mean, left, right) => {
+        const t = (x - mean) * (x < mean ? left : right);
+        return Math.exp(-0.5 * t * t);
+    };
+    const h = 6.62607015e-34;
+    const c = 2.99792458e8;
+    const k = 1.380649e-23;
+    const t = Math.min(40000, Math.max(800, kelvin));
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    for (let nm = 360; nm <= 830; nm++) {
+        const m = nm * 1e-9;
+        const radiance = (2 * h * c * c) / m ** 5 / (Math.exp((h * c) / (m * k * t)) - 1);
+        x +=
+            radiance *
+                (1.056 * lobe(nm, 599.8, 0.0264, 0.0323) +
+                    0.362 * lobe(nm, 442.0, 0.0624, 0.0374) -
+                    0.065 * lobe(nm, 501.1, 0.049, 0.0382));
+        y +=
+            radiance *
+                (0.821 * lobe(nm, 568.8, 0.0213, 0.0247) + 0.286 * lobe(nm, 530.9, 0.0613, 0.0322));
+        z +=
+            radiance *
+                (1.217 * lobe(nm, 437.0, 0.0845, 0.0278) + 0.681 * lobe(nm, 459.0, 0.0385, 0.0725));
+    }
+    const r = 3.2404542 * x - 1.5371385 * y - 0.4985314 * z;
+    const g = -0.969266 * x + 1.8760108 * y + 0.041556 * z;
+    const b = 0.0556434 * x - 0.2040259 * y + 1.0572252 * z;
+    const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    return [r / luminance, g / luminance, b / luminance];
+}
+/** A surface as a glTF material, packing what glTF packs and naming what it cannot. */
+function surfaceToGltf(surface, texture, approximations) {
+    const note = (what) => {
+        approximations.push(`material "${surface.name}": ${what}`);
+    };
+    const pbr = {
+        baseColorFactor: [...surface.baseColor, surface.alpha],
+        metallicFactor: surface.metallic,
+        roughnessFactor: surface.roughness,
+    };
+    const out = {
+        name: surface.name,
+        pbrMetallicRoughness: pbr,
+    };
+    if (surface.baseColorMap !== null)
+        pbr['baseColorTexture'] = { index: texture(surface.baseColorMap.image) };
+    if (surface.alphaMap !== null &&
+        (surface.alphaMap.channel !== 'a' ||
+            surface.alphaMap.image.offset !== surface.baseColorMap?.image.offset)) {
+        note('its alpha comes from a different image than its colour, which glTF cannot hold apart');
+    }
+    const packed = [surface.roughnessMap, surface.metallicMap].filter((m) => m !== null);
+    if (packed.length > 0) {
+        const image = packed[0].image;
+        if (packed.some((m) => m.image.offset !== image.offset))
+            note('its roughness and metallic come from two images, and glTF packs them into one');
+        /* A grey image has the same value in every channel, so which one a socket reads changes nothing. */
+        const grey = isGreyImage(image);
+        if (!grey && surface.roughnessMap !== null && surface.roughnessMap.channel !== 'g')
+            note(`its roughness is read from the ${surface.roughnessMap.channel} channel where glTF reads green`);
+        if (!grey && surface.metallicMap !== null && surface.metallicMap.channel !== 'b')
+            note(`its metallic is read from the ${surface.metallicMap.channel} channel where glTF reads blue`);
+        /* A map for one of the pair only: glTF multiplies the other's factor by the same image, so the
+           pair is exact only where that other factor is zero. */
+        if (surface.metallicMap === null && surface.metallic !== 0)
+            note('its roughness has a map and its metallic does not, and glTF multiplies one image into both');
+        pbr['metallicRoughnessTexture'] = { index: texture(image) };
+    }
+    if (surface.occlusionMap !== null)
+        out['occlusionTexture'] = { index: texture(surface.occlusionMap.image) };
+    if (surface.normalMap !== null)
+        out['normalTexture'] = {
+            index: texture(surface.normalMap.image),
+            scale: surface.normalStrength,
+        };
+    const emitted = surface.emission.map((c) => c * surface.emissionStrength);
+    if ((surface.emissionMap !== null || emitted.some((c) => c > 0)) &&
+        surface.emissionStrength > 0) {
+        if (Math.max(...emitted) > 1) {
+            out['emissiveFactor'] = [...surface.emission];
+            out.extensions = {
+                ...out.extensions,
+                KHR_materials_emissive_strength: { emissiveStrength: surface.emissionStrength },
+            };
+        }
+        else
+            out['emissiveFactor'] = emitted;
+        if (surface.emissionMap !== null)
+            out['emissiveTexture'] = { index: texture(surface.emissionMap.image) };
+    }
+    if (surface.transmission > 0)
+        out.extensions = {
+            ...out.extensions,
+            KHR_materials_transmission: { transmissionFactor: surface.transmission },
+        };
+    if (surface.alphaMode !== 'OPAQUE')
+        out['alphaMode'] = surface.alphaMode;
+    if (surface.alphaMode === 'MASK' && surface.alphaCutoff !== 0.5)
+        out['alphaCutoff'] = surface.alphaCutoff;
+    if (surface.doubleSided)
+        out['doubleSided'] = true;
+    if (surface.extras !== null)
+        out['extras'] = surface.extras;
+    return out;
+}

package/dist/blendMaterial.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What a `.blend` material's node graph says each surface channel is: a value, or a channel of an
+ * image times a value.
+ *
+ * **One reading, two consumers.** `blendGltf.ts` turns a `BlendSurface` into a glTF material, the
+ * way Blender's glTF exporter would; a bake that composes its own images reads the same surface
+ * and can pack channels glTF cannot, such as roughness and metallic drawn from two images. So the
+ * graph is walked once, here, into channels, and what glTF can and cannot hold is decided later.
+ *
+ * **The patterns are the ones Blender itself writes**, because those are the graphs real files
+ * carry: Blender's glTF importer builds exactly this wiring — an image straight into a socket, a
+ * Separate Color between an image and roughness, metallic or occlusion, a Math Multiply for a
+ * factor, a Normal Map node, a Mapping node for a texture transform, and a "glTF Material Output"
+ * group for occlusion — and so does a person wiring a Principled BSDF by hand. Reroutes are
+ * walked through. A city assembled from imported assets used nothing else in 1,809 materials.
+ *
+ * **What it cannot read it names**, in `approximations`, and uses the socket's own value: a
+ * procedural texture, a Mix Shader, a math chain, a bump node.
+ *
+ * Old files mean what Blender makes of them now: a material saved before 4.2 has its blend mode
+ * from `blend_method`, which is what Blender converts on opening, and one with no node tree is its
+ * viewport colour, metallic and roughness.
+ */
+import type { BlendStruct } from './blendData.ts';
+/** A channel of an image, as a socket reads it. */
+export interface ChannelSource {
+    readonly image: BlendStruct;
+    /** `rgb` for a colour socket; one channel for a scalar socket. */
+    readonly channel: 'rgb' | 'r' | 'g' | 'b' | 'a';
+}
+/** A material's surface, channel by channel. Factors multiply the map where there is one. */
+export interface BlendSurface {
+    readonly name: string;
+    readonly baseColor: [number, number, number];
+    readonly baseColorMap: ChannelSource | null;
+    readonly alpha: number;
+    readonly alphaMap: ChannelSource | null;
+    readonly alphaMode: 'OPAQUE' | 'BLEND' | 'MASK';
+    readonly alphaCutoff: number;
+    /** The colour attribute the base colour is multiplied by: a name, `''` for the render one. */
+    readonly vertexColor: string | null;
+    readonly metallic: number;
+    readonly metallicMap: ChannelSource | null;
+    readonly roughness: number;
+    readonly roughnessMap: ChannelSource | null;
+    readonly occlusionMap: ChannelSource | null;
+    readonly normalMap: ChannelSource | null;
+    readonly normalStrength: number;
+    readonly emission: [number, number, number];
+    readonly emissionStrength: number;
+    readonly emissionMap: ChannelSource | null;
+    readonly transmission: number;
+    readonly doubleSided: boolean;
+    /** The UV map the maps read, by name, or null for the render map. */
+    readonly uvMap: string | null;
+    /** A 3x3 affine transform of that map, column-major, in Blender's UV space, or null. */
+    readonly uvTransform: number[] | null;
+    readonly extras: Record<string, unknown> | null;
+    /**
+     * What glTF cannot say about this material by either route: a procedural texture, a Mix Shader,
+     * a math chain. Blender's exporter loses these too, so they are warnings and not a reason to ask it.
+     */
+    readonly approximations: readonly string[];
+}
+/** Read one material's surface. */
+export declare function readBlendSurface(material: BlendStruct, version: number): BlendSurface;
+/** An ID's custom properties that are plain values, for glTF's `extras`. */
+export declare function customProperties(id: BlendStruct): Record<string, unknown> | null;