@driftengine/assets 4.6.1 → 4.7.1

package/src/blendFile.ts

@@ -0,0 +1,233 @@
+/**
+ * A `.blend` file's container: its header, its blocks, and the catalogue of structures the file
+ * carries to describe its own layout.
+ *
+ * **The catalogue is what makes this readable at all.** Every `.blend` ends with a `DNA1` block
+ * listing each C struct the writing Blender knew — its fields, their types, their sizes — so a
+ * reader learns the layout *from the file* rather than hard-coding one Blender release. A mesh
+ * written by 2.79 and one written by 5.2 differ in nearly every struct, and both are read by the
+ * same code because neither is assumed.
+ *
+ * **Three container shapes are read, and anything else is refused by name.** The twelve-byte
+ * header every release before 5.0 wrote, with four- or eight-byte pointers and either byte order,
+ * and the seventeen-byte header 5.0 introduced, whose block headers carry 64-bit lengths. A file
+ * compressed with gzip (before 3.0) or zstd (3.0 on) is reported as such, and `readBlendFile`
+ * takes the decompressed bytes: decompressing is the host's capability, not this module's.
+ *
+ * What this gives up: a block whose pointer is not the start of a block is found by search, which
+ * is a binary search over every block. That is the cost of not assuming how Blender allocates.
+ */
+
+import { DrftError } from '@driftengine/drft';
+
+/** What the first bytes say, before any block is read. */
+export interface BlendHeader {
+  readonly pointerSize: 4 | 8;
+  readonly littleEndian: boolean;
+  /** The writing Blender's version, as the header spells it: 279, 405, 500. */
+  readonly version: number;
+  /** Bytes of header before the first block. */
+  readonly headerSize: number;
+  /** Bytes in each block header: 20, 24, or 32 for the 64-bit form 5.0 writes. */
+  readonly blockHeaderSize: number;
+}
+
+/** One block: a run of `count` structs of catalogue type `sdna`, at `offset` in the file. */
+export interface BlendBlock {
+  readonly code: string;
+  readonly sdna: number;
+  /** The address the struct had in the writing process, which every pointer to it names. */
+  readonly address: bigint;
+  readonly length: number;
+  readonly count: number;
+  readonly offset: number;
+}
+
+/** One field of a catalogued struct, with its offset already summed. */
+export interface DnaField {
+  /** The bare name: `*next` and `co[3]` are `next` and `co`. */
+  readonly name: string;
+  readonly type: string;
+  readonly offset: number;
+  readonly size: number;
+  readonly pointer: boolean;
+  /** Array dimensions, outermost first; empty for a scalar. */
+  readonly dims: readonly number[];
+}
+
+export interface DnaStruct {
+  readonly index: number;
+  readonly type: string;
+  readonly size: number;
+  readonly fields: ReadonlyMap<string, DnaField>;
+}
+
+/** Which compression, if any, a file's first bytes declare. */
+export type BlendCompression = 'gzip' | 'zstd' | null;
+
+/** The compression a `.blend` was saved with, by its magic, or null for a plain file. */
+export function blendCompression(bytes: Uint8Array): BlendCompression {
+  if (bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) return 'gzip';
+  if (bytes.length >= 4 && bytes[0] === 0x28 && bytes[1] === 0xb5 && bytes[2] === 0x2f) {
+    return bytes[3] === 0xfd ? 'zstd' : null;
+  }
+  return null;
+}
+
+/** Whether these bytes are an uncompressed `.blend`. */
+export function isBlend(bytes: Uint8Array): boolean {
+  const magic = 'BLENDER';
+  if (bytes.length < 12) return false;
+  for (let i = 0; i < magic.length; i++) if (bytes[i] !== magic.charCodeAt(i)) return false;
+  return true;
+}
+
+const ascii = (bytes: Uint8Array, at: number, length: number): string =>
+  String.fromCharCode(...bytes.subarray(at, at + length));
+
+/** Parse the header, refusing any shape this module has not been taught. */
+export function readBlendHeader(bytes: Uint8Array): BlendHeader {
+  if (!isBlend(bytes)) {
+    const packed = blendCompression(bytes);
+    throw new DrftError(
+      packed === null
+        ? 'blend: not a .blend file (no BLENDER magic)'
+        : `blend: this file is ${packed}-compressed and must be decompressed before it is read`,
+    );
+  }
+  const seventh = String.fromCharCode(bytes[7] ?? 0);
+  if (seventh === '-' || seventh === '_') {
+    const endian = String.fromCharCode(bytes[8] ?? 0);
+    if (endian !== 'v' && endian !== 'V') throw new DrftError(`blend: byte order "${endian}"`);
+    const pointerSize = seventh === '-' ? 8 : 4;
+    return {
+      pointerSize,
+      littleEndian: endian === 'v',
+      version: Number(ascii(bytes, 9, 3)),
+      headerSize: 12,
+      blockHeaderSize: pointerSize === 8 ? 24 : 20,
+    };
+  }
+  /* 5.0 on: `BLENDER` + header size + `-` + file format version + byte order + four digits. */
+  const headerSize = Number(ascii(bytes, 7, 2));
+  const format = Number(ascii(bytes, 10, 2));
+  const endian = String.fromCharCode(bytes[12] ?? 0);
+  if (
+    headerSize !== 17 ||
+    bytes[9] !== 0x2d ||
+    format !== 1 ||
+    (endian !== 'v' && endian !== 'V')
+  ) {
+    throw new DrftError(
+      `blend: header "${ascii(bytes, 0, 17)}" is a container layout this reader does not know`,
+    );
+  }
+  return {
+    pointerSize: 8,
+    littleEndian: endian === 'v',
+    version: Number(ascii(bytes, 13, 4)),
+    headerSize,
+    blockHeaderSize: 32,
+  };
+}
+
+/** Walk every block header up to `ENDB`. */
+export function readBlendBlocks(bytes: Uint8Array, header: BlendHeader): BlendBlock[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const le = header.littleEndian;
+  const blocks: BlendBlock[] = [];
+  let at = header.headerSize;
+  while (at + header.blockHeaderSize <= bytes.length) {
+    const code = ascii(bytes, at, 4).replace(/\0+$/, '');
+    let length: number;
+    let address: bigint;
+    let sdna: number;
+    let count: number;
+    if (header.blockHeaderSize === 32) {
+      sdna = view.getInt32(at + 4, le);
+      address = view.getBigUint64(at + 8, le);
+      length = Number(view.getBigInt64(at + 16, le));
+      count = Number(view.getBigInt64(at + 24, le));
+    } else {
+      length = view.getInt32(at + 4, le);
+      address =
+        header.pointerSize === 8
+          ? view.getBigUint64(at + 8, le)
+          : BigInt(view.getUint32(at + 8, le));
+      const rest = at + 8 + header.pointerSize;
+      sdna = view.getInt32(rest, le);
+      count = view.getInt32(rest + 4, le);
+    }
+    if (code === 'ENDB') return blocks;
+    const offset = at + header.blockHeaderSize;
+    if (length < 0 || offset + length > bytes.length) {
+      throw new DrftError(`blend: block "${code}" at ${at} runs past the end of the file`);
+    }
+    blocks.push({ code, sdna, address, length, count, offset });
+    at = offset + length;
+  }
+  throw new DrftError('blend: the file ends before its ENDB block, so it was not saved completely');
+}
+
+/** Parse the `DNA1` block into structs with every field's offset summed. */
+export function readDna(bytes: Uint8Array, block: BlendBlock, header: BlendHeader): DnaStruct[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const le = header.littleEndian;
+  let at = block.offset;
+  const end = block.offset + block.length;
+  const expect = (tag: string): void => {
+    at = block.offset + Math.ceil((at - block.offset) / 4) * 4;
+    if (ascii(bytes, at, 4) !== tag) throw new DrftError(`blend: DNA1 has no ${tag} section`);
+    at += 4;
+  };
+  const strings = (): string[] => {
+    const count = view.getInt32(at, le);
+    at += 4;
+    const out: string[] = [];
+    for (let i = 0; i < count; i++) {
+      const stop = bytes.indexOf(0, at);
+      if (stop < 0 || stop >= end) throw new DrftError('blend: DNA1 string table is truncated');
+      out.push(ascii(bytes, at, stop - at));
+      at = stop + 1;
+    }
+    return out;
+  };
+
+  expect('SDNA');
+  expect('NAME');
+  const names = strings();
+  expect('TYPE');
+  const types = strings();
+  expect('TLEN');
+  const lengths: number[] = [];
+  for (let i = 0; i < types.length; i++) lengths.push(view.getInt16(at + i * 2, le));
+  at += types.length * 2;
+  expect('STRC');
+  const count = view.getInt32(at, le);
+  at += 4;
+
+  const structs: DnaStruct[] = [];
+  for (let s = 0; s < count; s++) {
+    const typeIndex = view.getInt16(at, le);
+    const fieldCount = view.getInt16(at + 2, le);
+    at += 4;
+    const fields = new Map<string, DnaField>();
+    let offset = 0;
+    for (let f = 0; f < fieldCount; f++) {
+      const typeOf = view.getInt16(at, le);
+      const type = types[typeOf] ?? '';
+      const raw = names[view.getInt16(at + 2, le)] ?? '';
+      at += 4;
+      const pointer = raw.startsWith('*') || raw.startsWith('(*');
+      const dims = [...raw.matchAll(/\[(\d+)\]/g)].map((m) => Number(m[1]));
+      const element = pointer ? header.pointerSize : (lengths[typeOf] ?? 0);
+      const size = dims.reduce((n, d) => n * d, element);
+      const name = raw.replace(/^[(*]+/, '').replace(/[)[].*$/, '');
+      fields.set(name, { name, type, offset, size, pointer, dims });
+      offset += size;
+    }
+    const type = types[typeIndex] ?? '';
+    structs.push({ index: s, type, size: lengths[typeIndex] ?? offset, fields });
+  }
+  return structs;
+}

package/src/blendGeometry.ts

@@ -0,0 +1,263 @@
+/**
+ * A `.blend` mesh as triangle primitives, one per material slot, in glTF's conventions.
+ *
+ * **The same conversion serves every route out of a `.blend`.** `blendGltf.ts` writes these into a
+ * glTF document for `readModel`, and a bake that keeps a world's instancing calls this once per
+ * distinct mesh rather than once per object. So what a corner becomes — its position turned Y up,
+ * its UV flipped to glTF's origin, its colour linear — is decided here and nowhere else.
+ *
+ * **Vertices are shared where every attribute agrees exactly**, which is how Blender's exporter
+ * builds them, found by walking the exported copies of each source vertex rather than by hashing,
+ * so a fifty-million-corner city costs a scan rather than fifty million string keys.
+ *
+ * **Faces are triangulated as Blender does it**: a quad split from its first corner, an ngon by ear
+ * clipping in its own plane. Blender clips ears in a different order, so an ngon's diagonals can
+ * differ from Blender's; on a planar face that changes no pixel, on a bent one it changes the bend.
+ */
+
+import type { BlendMeshData } from './blendMesh.ts';
+import { POINT } from './blendMesh.ts';
+import { faceNormals } from './blendNormals.ts';
+
+/** What a material slot asks of the geometry that wears it. */
+export interface SlotNeeds {
+  /** Which colour attribute to carry as `COLOR_0`: a name, `''` for the render one, or null. */
+  readonly vertexColor: string | null;
+  /** Which UV map to carry as `TEXCOORD_0`, by name, or null for the render map. */
+  readonly uvMap: string | null;
+  /** A 3x3 affine transform applied to that map in Blender's UV space, or null. */
+  readonly uvTransform: readonly number[] | null;
+}
+
+export interface BlendPrimitive {
+  /** The material slot, or -1 where the object has none. */
+  readonly slot: number;
+  readonly positions: Float32Array;
+  readonly normals: Float32Array;
+  readonly uvs: Float32Array | null;
+  readonly colors: Float32Array | null;
+  readonly indices: Uint32Array;
+  /** The source vertex each exported vertex came from, for shape keys and weights. */
+  readonly sourceVertex: Int32Array;
+  /** The source corner each exported vertex first came from, for per-corner shape normals. */
+  readonly sourceCorner: Int32Array;
+}
+
+/** Blender Z up to glTF Y up: (x, y, z) becomes (x, z, -y). */
+export function toYUp(out: Float32Array, at: number, x: number, y: number, z: number): void {
+  out[at] = x;
+  out[at + 1] = z;
+  out[at + 2] = -y;
+}
+
+/** Triangles of one face, as corner indices, appended to `out`. */
+export function triangulateFace(
+  mesh: BlendMeshData,
+  face: number,
+  normal: readonly number[],
+  out: number[],
+): void {
+  const start = mesh.faceOffsets[face] as number;
+  const end = mesh.faceOffsets[face + 1] as number;
+  const n = end - start;
+  if (n < 3) return;
+  if (n === 3) {
+    out.push(start, start + 1, start + 2);
+    return;
+  }
+  if (n === 4) {
+    out.push(start, start + 1, start + 2, start, start + 2, start + 3);
+    return;
+  }
+  /* Project onto the face's plane, then clip ears. */
+  const [nx, ny, nz] = normal as [number, number, number];
+  const ax = Math.abs(nx);
+  const ay = Math.abs(ny);
+  const az = Math.abs(nz);
+  const drop = az >= ax && az >= ay ? 2 : ax >= ay ? 0 : 1;
+  const flip = (drop === 2 ? nz : drop === 0 ? nx : ny) < 0;
+  const p = mesh.positions;
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (let c = start; c < end; c++) {
+    const v = (mesh.cornerVerts[c] as number) * 3;
+    /* The two axes left after dropping one, in right-handed order: (y, z), (z, x) or (x, y). */
+    const a = p[v + ((drop + 1) % 3)] as number;
+    const b = p[v + ((drop + 2) % 3)] as number;
+    xs.push(flip ? b : a);
+    ys.push(flip ? a : b);
+  }
+  const ring = Array.from({ length: n }, (_, i) => i);
+  const cross = (i: number, j: number, k: number): number =>
+    ((xs[j] as number) - (xs[i] as number)) * ((ys[k] as number) - (ys[i] as number)) -
+    ((ys[j] as number) - (ys[i] as number)) * ((xs[k] as number) - (xs[i] as number));
+  const inside = (i: number, j: number, k: number, q: number): boolean =>
+    cross(i, j, q) >= 0 && cross(j, k, q) >= 0 && cross(k, i, q) >= 0;
+  let guard = 0;
+  while (ring.length > 3 && guard++ < n * n) {
+    let clipped = false;
+    for (let r = 0; r < ring.length; r++) {
+      const i = ring[(r + ring.length - 1) % ring.length] as number;
+      const j = ring[r] as number;
+      const k = ring[(r + 1) % ring.length] as number;
+      if (cross(i, j, k) <= 0) continue;
+      let blocked = false;
+      for (const q of ring) {
+        if (q !== i && q !== j && q !== k && inside(i, j, k, q)) {
+          blocked = true;
+          break;
+        }
+      }
+      if (blocked) continue;
+      out.push(start + i, start + j, start + k);
+      ring.splice(r, 1);
+      clipped = true;
+      break;
+    }
+    /* A face too bent or degenerate to clip: fan the rest, which is what remains drawable. */
+    if (!clipped) break;
+  }
+  for (let r = 1; r + 1 < ring.length; r++)
+    out.push(
+      start + (ring[0] as number),
+      start + (ring[r] as number),
+      start + (ring[r + 1] as number),
+    );
+}
+
+/** Split a mesh into one primitive per material slot it uses. */
+export function meshPrimitives(
+  mesh: BlendMeshData,
+  normals: Float32Array,
+  slots: number,
+  needs: (slot: number) => SlotNeeds,
+): BlendPrimitive[] {
+  const faces = mesh.faceOffsets.length - 1;
+  const face = faceNormals(mesh);
+  const bySlot = new Map<number, number[]>();
+  for (let f = 0; f < faces; f++) {
+    const raw = mesh.materialIndex === null ? 0 : (mesh.materialIndex[f] as number);
+    const slot = slots === 0 ? -1 : Math.max(0, Math.min(slots - 1, raw));
+    let list = bySlot.get(slot);
+    if (list === undefined) bySlot.set(slot, (list = []));
+    list.push(f);
+  }
+  const out: BlendPrimitive[] = [];
+  for (const slot of [...bySlot.keys()].sort((a, b) => a - b)) {
+    const need = slot < 0 ? { vertexColor: null, uvMap: null, uvTransform: null } : needs(slot);
+    const corners: number[] = [];
+    for (const f of bySlot.get(slot) as number[])
+      triangulateFace(
+        mesh,
+        f,
+        [face[f * 3] as number, face[f * 3 + 1] as number, face[f * 3 + 2] as number],
+        corners,
+      );
+    out.push(build(mesh, normals, slot, need, corners));
+  }
+  return out;
+}
+
+function uvLayer(mesh: BlendMeshData, name: string | null): Float32Array | null {
+  if (mesh.uvs.length === 0) return null;
+  const found = name === null ? -1 : mesh.uvs.findIndex((u) => u.name === name);
+  return (mesh.uvs[found >= 0 ? found : mesh.renderUv] ?? mesh.uvs[0])?.uv ?? null;
+}
+
+function colorLayer(
+  mesh: BlendMeshData,
+  name: string | null,
+): BlendMeshData['colors'][number] | null {
+  if (name === null || mesh.colors.length === 0) return null;
+  const found = name === '' ? -1 : mesh.colors.findIndex((c) => c.name === name);
+  return mesh.colors[found >= 0 ? found : mesh.renderColor] ?? null;
+}
+
+function build(
+  mesh: BlendMeshData,
+  normals: Float32Array,
+  slot: number,
+  need: SlotNeeds,
+  corners: number[],
+): BlendPrimitive {
+  const uv = uvLayer(mesh, need.uvMap);
+  const color = colorLayer(mesh, need.vertexColor);
+  const t = need.uvTransform;
+  const verts = mesh.positions.length / 3;
+  /* Exported copies of each source vertex, as a chain: head per vertex, next per copy. */
+  const head = new Int32Array(verts).fill(-1);
+  const next: number[] = [];
+  const corner: number[] = [];
+  const source: number[] = [];
+  const indices = new Uint32Array(corners.length);
+  const same = (a: number, b: number): boolean => {
+    for (let k = 0; k < 3; k++) if (normals[a * 3 + k] !== normals[b * 3 + k]) return false;
+    if (uv !== null) for (let k = 0; k < 2; k++) if (uv[a * 2 + k] !== uv[b * 2 + k]) return false;
+    if (color !== null && color.domain !== POINT)
+      for (let k = 0; k < 4; k++) if (color.rgba[a * 4 + k] !== color.rgba[b * 4 + k]) return false;
+    return true;
+  };
+  for (let i = 0; i < corners.length; i++) {
+    const c = corners[i] as number;
+    const v = mesh.cornerVerts[c] as number;
+    let found = -1;
+    for (let e = head[v] as number; e >= 0; e = next[e] as number) {
+      if (same(corner[e] as number, c)) {
+        found = e;
+        break;
+      }
+    }
+    if (found < 0) {
+      found = corner.length;
+      corner.push(c);
+      source.push(v);
+      next.push(head[v] as number);
+      head[v] = found;
+    }
+    indices[i] = found;
+  }
+  const count = corner.length;
+  const positions = new Float32Array(count * 3);
+  const outNormals = new Float32Array(count * 3);
+  const uvs = uv === null ? null : new Float32Array(count * 2);
+  const colors = color === null ? null : new Float32Array(count * 4);
+  const p = mesh.positions;
+  for (let e = 0; e < count; e++) {
+    const c = corner[e] as number;
+    const v = source[e] as number;
+    toYUp(positions, e * 3, p[v * 3] as number, p[v * 3 + 1] as number, p[v * 3 + 2] as number);
+    toYUp(
+      outNormals,
+      e * 3,
+      normals[c * 3] as number,
+      normals[c * 3 + 1] as number,
+      normals[c * 3 + 2] as number,
+    );
+    if (uvs !== null) {
+      let u = uv?.[c * 2] as number;
+      let w = uv?.[c * 2 + 1] as number;
+      if (t !== null) {
+        const tu = (t[0] as number) * u + (t[3] as number) * w + (t[6] as number);
+        const tv = (t[1] as number) * u + (t[4] as number) * w + (t[7] as number);
+        u = tu;
+        w = tv;
+      }
+      uvs[e * 2] = u;
+      uvs[e * 2 + 1] = 1 - w;
+    }
+    if (colors !== null && color !== null) {
+      const at = color.domain === POINT ? v : c;
+      for (let k = 0; k < 4; k++) colors[e * 4 + k] = color.rgba[at * 4 + k] as number;
+    }
+  }
+  return {
+    slot,
+    positions,
+    normals: outNormals,
+    uvs,
+    colors,
+    indices,
+    sourceVertex: Int32Array.from(source),
+    sourceCorner: Int32Array.from(corner),
+  };
+}