Skip to content

3D engine that AI agents drive

12.2 KB
Raw Blame
import { forEachChunk } from './cooperative.js';

export const COMPONENT_TYPES = {
  5120: Int8Array,
  5121: Uint8Array,
  5122: Int16Array,
  5123: Uint16Array,
  5125: Uint32Array,
  5126: Float32Array,
};
const SPARSE_INDEX_COMPONENT_TYPES = [5121, 5123, 5125];
const COMPONENT_COUNTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
const NORMALIZATION_DIVISORS = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };

// Only the four integer types scale; a normalized flag on a float or 32-bit integer accessor changes nothing, as in three.js.
function divisorOf(attribute) {
  return attribute.normalized ? NORMALIZATION_DIVISORS[attribute.componentType] ?? 1 : 1;
}

function fillFloats(attribute, values, divisor, from, to) {
  for (let index = from; index < to; index++) {
    const value = attribute.array[index];
    values[index] = divisor === 1 ? value : Math.max(value / divisor, -1);
  }
}

/** Float values of an attribute, with normalized integers scaled into zero to one or minus one to one. */
export function attributeFloats(attribute) {
  const length = attribute.count * attribute.itemSize;
  const values = new Float32Array(length);
  fillFloats(attribute, values, divisorOf(attribute), 0, length);
  return values;
}

/** The same values as attributeFloats, converted a chunk at a time with `checkpoint()` between chunks so a large attribute does not block the page. */
export async function attributeFloatsInSlices(attribute, checkpoint) {
  const length = attribute.count * attribute.itemSize;
  const values = new Float32Array(length);
  const divisor = divisorOf(attribute);
  await forEachChunk(length, checkpoint, (from, to) => fillFloats(attribute, values, divisor, from, to));
  return values;
}

const MATRIX_COLUMNS = { MAT2: 2, MAT3: 3, MAT4: 4 };

/** Matrix columns as [tight bytes, stored bytes]: the glTF spec pads each MAT2 or MAT3 column to a multiple of 4 bytes. */
function columnBytesOf(accessor) {
  const tight = MATRIX_COLUMNS[accessor.type] * COMPONENT_TYPES[accessor.componentType].BYTES_PER_ELEMENT;
  return [tight, Math.ceil(tight / 4) * 4];
}

function elementBytesOf(accessor) {
  const columns = MATRIX_COLUMNS[accessor.type];
  if (columns) return columns * columnBytesOf(accessor)[1];
  return COMPONENT_TYPES[accessor.componentType].BYTES_PER_ELEMENT * COMPONENT_COUNTS[accessor.type];
}

function removeColumnPadding(packed, accessor) {
  const columns = MATRIX_COLUMNS[accessor.type];
  const [tightBytes, storedBytes] = columnBytesOf(accessor);
  if (!columns || tightBytes === storedBytes) return packed;
  const tight = new Uint8Array(accessor.count * columns * tightBytes);
  for (let column = 0; column < accessor.count * columns; column++) {
    tight.set(packed.subarray(column * storedBytes, column * storedBytes + tightBytes), column * tightBytes);
  }
  return tight;
}

/** The distance between elements of a buffer view: its byteStride, which must hold one element and be a multiple of 4. */
function strideOf(view, elementBytes, viewIndex) {
  if (!view.byteStride) return elementBytes;
  if (!Number.isInteger(view.byteStride) || view.byteStride < elementBytes) {
    throw new Error(`Invalid glTF bufferViews[${viewIndex}].byteStride ${view.byteStride}: an accessor element needs ${elementBytes} bytes. Fix: use a byteStride of at least ${elementBytes} that is a multiple of 4.`);
  }
  if (view.byteStride % 4 !== 0) {
    throw new Error(`Invalid glTF bufferViews[${viewIndex}].byteStride ${view.byteStride}: it must be a multiple of 4. Fix: round it up to ${Math.ceil(view.byteStride / 4) * 4}.`);
  }
  return view.byteStride;
}

function checkElementsFit(source, offset, stride, count, elementBytes) {
  if (!Number.isSafeInteger(offset) || offset < 0) {
    throw new Error(`Invalid glTF byteOffset ${JSON.stringify(offset)}: it must be a non-negative integer. Fix: use an offset from 0 up to the buffer view length.`);
  }
  if (count > 0 && offset + (count - 1) * stride + elementBytes > source.length) {
    throw new Error('glTF accessor exceeds its buffer view.');
  }
}

// Tightly packed elements are one block of bytes. Uint8Array.prototype.slice copies even when `source` is a Node Buffer, whose own slice is a view.
function copyTightly(source, offset, count, elementBytes) {
  return Uint8Array.prototype.slice.call(source, offset, offset + count * elementBytes);
}

function copyStridedRange(source, offset, stride, elementBytes, packed, from, to) {
  for (let element = from; element < to; element++) {
    const start = offset + element * stride;
    packed.set(source.subarray(start, start + elementBytes), element * elementBytes);
  }
}

function copyElements(source, offset, stride, count, elementBytes) {
  checkElementsFit(source, offset, stride, count, elementBytes);
  if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);
  const packed = new Uint8Array(count * elementBytes);
  copyStridedRange(source, offset, stride, elementBytes, packed, 0, count);
  return packed;
}

async function copyElementsInSlices(source, offset, stride, count, elementBytes, checkpoint) {
  checkElementsFit(source, offset, stride, count, elementBytes);
  if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);
  const packed = new Uint8Array(count * elementBytes);
  await forEachChunk(count, checkpoint, (from, to) => copyStridedRange(source, offset, stride, elementBytes, packed, from, to));
  return packed;
}

/** Sparse substitution needs a whole-number count of 1 up to the accessor count, and an indices and a values block. */
function checkSparseShape(accessor) {
  const { count, indices, values } = accessor.sparse;
  if (!Number.isInteger(count) || count < 1 || count > accessor.count || !indices || !values) {
    throw new Error(`Invalid glTF sparse: it needs indices, values and a whole count from 1 to ${accessor.count}.`);
  }
}

/**
 * Indices of meshopt views that hold no elements (count 0) and that nothing reads: every accessor on them is empty. Other tools write
 * such views for a mesh that simplified to nothing. A view that a non-empty accessor, a sparse accessor or an image reads is not listed,
 * so it still fails with the count error instead of producing a short array.
 */
export function unreadEmptyMeshoptViews(document) {
  const empty = new Set();
  (document.bufferViews ?? []).forEach((view, index) => {
    if (view?.extensions?.EXT_meshopt_compression?.count === 0) empty.add(index);
  });
  if (!empty.size) return empty;
  for (const accessor of document.accessors ?? []) {
    if (accessor.count === 0 && !accessor.sparse) continue;
    empty.delete(accessor.bufferView);
    empty.delete(accessor.sparse?.indices?.bufferView);
    empty.delete(accessor.sparse?.values?.bufferView);
  }
  for (const image of document.images ?? []) empty.delete(image.bufferView);
  return empty;
}

/**
 * Reads accessors as tightly packed typed arrays, with sparse substitution and meshopt buffer views.
 * `bufferBytes(index)` returns the bytes of a glTF buffer. `meshoptDecoder` replaces the built-in decoder of compressed views.
 */
export function createAccessorReader(document, bufferBytes, meshoptDecoder) {
  const viewCache = new Map();

  function plainViewBytes(view) {
    const source = bufferBytes(view.buffer);
    const offset = view.byteOffset ?? 0;
    const length = view.byteLength;
    if (!source || !Number.isSafeInteger(length) || length < 0 || offset < 0 || offset + length > source.length) {
      throw new Error('glTF buffer view exceeds its buffer.');
    }
    return source.subarray(offset, offset + length);
  }

  /** Decode every meshopt view before any accessor is read, so reading stays synchronous. The decoder loads only for a file that has one. */
  async function prepare() {
    const views = document.bufferViews ?? [];
    if (!views.some(view => view.extensions?.EXT_meshopt_compression)) return;
    const { decodeMeshoptViews } = await import('./gltf-meshopt.js');
    const skippedViews = unreadEmptyMeshoptViews(document);
    for (const [index, bytes] of await decodeMeshoptViews(views, bufferBytes, meshoptDecoder, skippedViews)) viewCache.set(index, bytes);
  }

  function viewBytes(index) {
    const view = document.bufferViews?.[index];
    if (!view) throw new Error('Invalid glTF buffer view index.');
    if (!viewCache.has(index)) viewCache.set(index, plainViewBytes(view));
    return viewCache.get(index);
  }

  function planAccessor(index) {
    const accessor = document.accessors?.[index];
    if (!accessor) throw new Error('Invalid glTF accessor index.');
    const ArrayType = COMPONENT_TYPES[accessor.componentType];
    if (!ArrayType) throw new Error('Unsupported glTF accessor component type.');
    const elementBytes = elementBytesOf(accessor);
    const stride = accessor.bufferView === undefined ? 0 : strideOf(document.bufferViews[accessor.bufferView], elementBytes, accessor.bufferView);
    return { accessor, ArrayType, itemSize: COMPONENT_COUNTS[accessor.type], elementBytes, stride };
  }

  function finishAccessor({ accessor, ArrayType, itemSize }, packed) {
    const array = new ArrayType(removeColumnPadding(packed, accessor).buffer);
    if (accessor.sparse) applySparse(accessor, array, itemSize);
    return { array, itemSize, count: accessor.count, normalized: accessor.normalized === true, componentType: accessor.componentType };
  }

  function readAccessor(index) {
    const plan = planAccessor(index);
    const { accessor, elementBytes, stride } = plan;
    const packed = accessor.bufferView === undefined
      ? new Uint8Array(accessor.count * elementBytes)
      : copyElements(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes);
    return finishAccessor(plan, packed);
  }

  /** The same accessor as readAccessor, copied a chunk at a time with `checkpoint()` between chunks. */
  async function readAccessorInSlices(index, checkpoint) {
    const plan = planAccessor(index);
    const { accessor, elementBytes, stride } = plan;
    const packed = accessor.bufferView === undefined
      ? new Uint8Array(accessor.count * elementBytes)
      : await copyElementsInSlices(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes, checkpoint);
    return finishAccessor(plan, packed);
  }

  function applySparse(accessor, array, itemSize, elementCount = accessor.count) {
    checkSparseShape(accessor);
    const { count, indices, values } = accessor.sparse;
    const IndexType = SPARSE_INDEX_COMPONENT_TYPES.includes(indices.componentType) ? COMPONENT_TYPES[indices.componentType] : null;
    if (!IndexType) throw new Error(`Unsupported sparse index component type ${indices.componentType}. Fix: use 5121, 5123 or 5125 (unsigned byte, short or int).`);
    const indexBytes = copyElements(viewBytes(indices.bufferView), indices.byteOffset ?? 0, IndexType.BYTES_PER_ELEMENT, count, IndexType.BYTES_PER_ELEMENT);
    const sparseIndices = new IndexType(indexBytes.buffer);
    const itemBytes = array.BYTES_PER_ELEMENT * itemSize;
    const valueBytes = copyElements(viewBytes(values.bufferView), values.byteOffset ?? 0, itemBytes, count, itemBytes);
    const sparseValues = new array.constructor(valueBytes.buffer);
    for (let item = 0; item < count; item++) {
      if (sparseIndices[item] >= elementCount) throw new Error('Sparse accessor index is out of range.');
      array.set(sparseValues.subarray(item * itemSize, (item + 1) * itemSize), sparseIndices[item] * itemSize);
    }
  }

  /**
   * Applies the sparse block of an accessor to data that did not come from its buffer view, such as a Draco-decoded attribute.
   * KHR_draco_mesh_compression only replaces the accessor's bufferView and byteOffset, so sparse still substitutes on top.
   */
  function applySparseToDecoded(index, attribute) {
    const accessor = document.accessors?.[index];
    if (!accessor?.sparse) return;
    const ArrayType = COMPONENT_TYPES[accessor.componentType];
    if (attribute.array.constructor !== ArrayType) {
      throw new Error(`Accessor ${index} has a sparse block but its Draco data decoded as ${attribute.array.constructor.name}, not ${ArrayType?.name}. Fix: make the accessor componentType match the compressed attribute.`);
    }
    applySparse(accessor, attribute.array, attribute.itemSize, attribute.count);
  }

  return { prepare, readAccessor, readAccessorInSlices, viewBytes, applySparseToDecoded };
}