micro-gl 0.1.0

package/src/3d/core/InstancedMesh.js

@@ -0,0 +1,124 @@
+import { Mesh } from './Mesh.js';
+import { srgbToLinear } from '../../math/color.js';
+import {
+  INSTANCE_COLOR_OFFSET,
+  INSTANCE_SIZE,
+} from '../constants.js';
+import { computeInstancedBounds } from './InstancedBounds.js';
+
+export { INSTANCE_SIZE } from '../constants.js';
+
+/**
+ * A Mesh drawn `count` times in one draw call. Each instance has its
+ * own transform and color, packed into `instanceData` and uploaded as
+ * an instance-step vertex buffer — thousands of copies cost one
+ * uniform upload and one drawIndexed instead of thousands.
+ *
+ * Instance transforms are local to the mesh: the mesh's own scene-graph
+ * transform applies on top, and instance colors multiply with the
+ * material's color. Write instances with `setMatrixAt`/`setColorAt` —
+ * they mark the buffer for re-upload; set `needsUpdate = true` yourself
+ * only if you write `instanceData` directly.
+ *
+ * The instance count is fixed at construction. To show fewer instances,
+ * scale the extras to zero; to grow, make a new InstancedMesh.
+ *
+ * Raycaster tests every instance transform and includes `instanceId` in
+ * instanced hits. DragControls still moves the InstancedMesh as one batch.
+ */
+export class InstancedMesh extends Mesh {
+  constructor(geometry, material, count) {
+    super(geometry, material);
+    this.isInstanced = true;
+    this.count = count;
+    this.instanceData = new Float32Array(count * INSTANCE_SIZE);
+    // Every instance starts as an identity matrix with a white color.
+    for (let i = 0; i < count; i++) {
+      const base = i * INSTANCE_SIZE;
+      this.instanceData[base] = 1;
+      this.instanceData[base + 5] = 1;
+      this.instanceData[base + 10] = 1;
+      this.instanceData[base + 15] = 1;
+      this.instanceData.fill(
+        1,
+        base + INSTANCE_COLOR_OFFSET,
+        base + INSTANCE_SIZE,
+      );
+    }
+    // Resource caches compare revisions so every renderer/device receives
+    // an edit, even after another renderer has cleared needsUpdate.
+    this._instanceRevision = 0;
+    this._boundsRevision = 0;
+    this._needsUpdate = true;
+    this._instanceBounds = null;
+    this._instanceBoundsSource = null;
+    this._instanceBoundsRevision = -1;
+    this._instanceBoundsCount = -1;
+  }
+
+  /**
+   * Mesh-local union of every transformed instance. Frustum culling remains
+   * batch-level: if this box intersects, all `count` instances draw together.
+   */
+  get bounds() {
+    const sourceBounds = this.geometry?.bounds || null;
+    if (
+      this._instanceBoundsSource !== sourceBounds ||
+      this._instanceBoundsRevision !== this._boundsRevision ||
+      this._instanceBoundsCount !== this.count
+    ) {
+      this._instanceBounds = computeInstancedBounds(
+        sourceBounds,
+        this.instanceData,
+        this.count,
+      );
+      this._instanceBoundsSource = sourceBounds;
+      this._instanceBoundsRevision = this._boundsRevision;
+      this._instanceBoundsCount = this.count;
+    }
+    return this._instanceBounds;
+  }
+
+  /** Upload hint; set true after changing `instanceData` directly. */
+  get needsUpdate() {
+    return this._needsUpdate;
+  }
+
+  set needsUpdate(value) {
+    this._needsUpdate = Boolean(value);
+    if (this._needsUpdate) {
+      this._instanceRevision++;
+      // Direct writes may have changed matrices, so conservatively invalidate.
+      this._boundsRevision++;
+    }
+  }
+
+  /** Copies a Mat4 into instance `index`'s transform. */
+  setMatrixAt(index, matrix) {
+    this.instanceData.set(matrix.elements, index * INSTANCE_SIZE);
+    this._markInstanceDataUpdated(true);
+    return this;
+  }
+
+  /**
+   * Sets instance `index`'s color from [r, g, b] or [r, g, b, a] —
+   * sRGB display values like material colors. They are stored
+   * linearized (shading happens in linear space), so write linear
+   * values if you fill `instanceData` directly instead.
+   */
+  setColorAt(index, color) {
+    const base = index * INSTANCE_SIZE + INSTANCE_COLOR_OFFSET;
+    this.instanceData[base] = srgbToLinear(color[0]);
+    this.instanceData[base + 1] = srgbToLinear(color[1]);
+    this.instanceData[base + 2] = srgbToLinear(color[2]);
+    this.instanceData[base + 3] = color.length > 3 ? color[3] : 1;
+    this._markInstanceDataUpdated(false);
+    return this;
+  }
+
+  _markInstanceDataUpdated(boundsChanged) {
+    this._needsUpdate = true;
+    this._instanceRevision++;
+    if (boundsChanged) this._boundsRevision++;
+  }
+}

package/src/3d/core/Mesh.js

@@ -0,0 +1,26 @@
+import { Object3d } from './Object3d.js';
+
+/**
+ * A renderable object: a Geometry (the shape) combined with a Material
+ * (how the surface is shaded).
+ */
+export class Mesh extends Object3d {
+  constructor(geometry, material) {
+    super();
+    this.geometry = geometry;
+    this.material = material;
+    /** Set false to bypass camera and shadow-camera frustum culling. */
+    this.frustumCulled = true;
+    /** Whether this mesh is drawn into an enabled directional shadow map. */
+    this.castShadow = false;
+    /** Whether lit materials on this mesh are darkened by that shadow map. */
+    this.receiveShadow = false;
+    /** View-space depth, written by the renderer's transparent sort. */
+    this._viewDepth = 0;
+  }
+
+  /** Local-space bounds used for conservative renderer culling. */
+  get bounds() {
+    return this.geometry?.bounds || null;
+  }
+}

package/src/3d/core/Object3d.js

@@ -0,0 +1,101 @@
+import { Vec3 } from '../../math/Vec3.js';
+import { Mat4 } from '../../math/Mat4.js';
+import { disposeObjectGpuResources } from '../../core/objectGpuResources.js';
+
+/**
+ * Base class for everything that lives in the scene graph.
+ * Holds a transform (position / rotation / scale) and a list of children,
+ * so objects can be parented to each other like in three.js.
+ */
+export class Object3d {
+  constructor() {
+    this.position = new Vec3(0, 0, 0);
+    /** Euler angles in radians, applied in XYZ order. */
+    this.rotation = new Vec3(0, 0, 0);
+    this.scale = new Vec3(1, 1, 1);
+
+    this.parent = null;
+    this.children = [];
+    /** Invisible objects — and everything under them — are skipped by rendering and picking. */
+    this.visible = true;
+
+    this.localMatrix = new Mat4();
+    this.worldMatrix = new Mat4();
+    /** Renderer-local GPU resources, created lazily (see GpuResources). */
+    this._gpu = null;
+  }
+
+  add(child) {
+    // Adding an object to itself or to one of its own descendants would
+    // create a cycle and hang traverse/updateWorldMatrix — refuse it.
+    for (let node = this; node; node = node.parent) {
+      if (node === child) return this;
+    }
+    if (child.parent) child.parent.remove(child);
+    child.parent = this;
+    this.children.push(child);
+    return this;
+  }
+
+  remove(child) {
+    const index = this.children.indexOf(child);
+    if (index !== -1) {
+      child.parent = null;
+      this.children.splice(index, 1);
+    }
+    return this;
+  }
+
+  /** Recomputes localMatrix and worldMatrix for this object and all descendants. */
+  updateWorldMatrix() {
+    this.localMatrix.compose(this.position, this.rotation, this.scale);
+    if (this.parent) {
+      this.worldMatrix.multiplyMatrices(
+        this.parent.worldMatrix,
+        this.localMatrix,
+      );
+    } else {
+      this.worldMatrix.copy(this.localMatrix);
+    }
+    for (const child of this.children) {
+      child.updateWorldMatrix();
+    }
+  }
+
+  /** Calls `callback(object)` for this object and every descendant. */
+  traverse(callback) {
+    callback(this);
+    for (const child of this.children) {
+      child.traverse(callback);
+    }
+  }
+
+  /**
+   * Like traverse, but skips objects with `visible = false` and their
+   * whole subtree — hiding a group hides everything inside it. The
+   * renderer and raycaster walk the scene with this.
+   */
+  traverseVisible(callback) {
+    if (!this.visible) return;
+    callback(this);
+    for (const child of this.children) {
+      child.traverseVisible(callback);
+    }
+  }
+
+  /**
+   * Destroys the per-object GPU resources created by every renderer for
+   * this object and its descendants (see GpuResources), releasing memory
+   * right away instead of waiting for GC. Geometry buffers are left alone:
+   * geometries may be shared between objects. Drawing a disposed object
+   * again re-creates its resources and re-uploads its instance data.
+   */
+  dispose() {
+    this.traverse((object) => {
+      disposeObjectGpuResources(object);
+      // Re-created instance buffers must receive the CPU-side data before use.
+      if (object.isInstanced) object.needsUpdate = true;
+    });
+    return this;
+  }
+}

package/src/3d/core/Pipelines.js

@@ -0,0 +1,125 @@
+import {
+  DEFAULT_DEPTH_COMPARE,
+  INDEX_FORMAT,
+  SHADER_ENTRY_POINT,
+  STRAIGHT_ALPHA_BLEND,
+  isStripTopology,
+} from '../../core/pipelineConstants.js';
+import {
+  createMaterialPipelineLayouts,
+} from '../../core/createMaterialPipelineLayouts.js';
+import {
+  DEPTH_FORMAT,
+  SINGLE_SAMPLE_COUNT,
+} from '../../core/rendererConfig.js';
+import { materialUsesMap } from '../../core/materialResources.js';
+import { vertexBufferLayouts } from '../shaders/vertexLayout.js';
+
+/**
+ * Compiles and caches the render pipelines for materials, and owns the
+ * bind group / pipeline layouts every shader shares (the
+ * @group(0) / @group(1) uniform interface in Material).
+ *
+ * A pipeline is keyed by composed shader source + pipeline state (topology,
+ * cull mode, front face, textured / instanced / transparent or not):
+ * each combination compiles once and is shared by every material
+ * instance that matches. Transparent variants alpha-blend like the 2D
+ * pipelines and don't write the depth buffer (the renderer draws them
+ * after the opaque meshes, sorted back-to-front).
+ */
+export class Pipelines {
+  constructor(device, format, sampleCount = SINGLE_SAMPLE_COUNT) {
+    this.device = device;
+    this.format = format;
+    /** MSAA sample count of the renderer's color/depth targets. */
+    this.sampleCount = sampleCount;
+    // composed WGSL -> Map of pipeline-state key -> GPURenderPipeline
+    this._cache = new Map();
+    // WGSL source -> GPUShaderModule, so pipeline variants that share a
+    // shader (e.g. the same material at another topology) compile once.
+    this._modules = new Map();
+
+    Object.assign(
+      this,
+      createMaterialPipelineLayouts(
+        device,
+        GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+        { shadows: true },
+      ),
+    );
+  }
+
+  /** The render pipeline for a material's shader and fixed-function state. */
+  pipelineFor(material, instanced = false) {
+    const { topology, cullMode, frontFace } = material;
+    const shaderCode = instanced
+      ? material.instancedShaderCode
+      : material.shaderCode;
+    let variants = this._cache.get(shaderCode);
+    if (!variants) {
+      variants = new Map();
+      this._cache.set(shaderCode, variants);
+    }
+    const textured = materialUsesMap(material);
+    const transparent = !!material.transparent;
+    const stateKey = `${topology}|${cullMode}|${frontFace}|${textured}|${instanced}|${transparent}`;
+    let pipeline = variants.get(stateKey);
+    if (!pipeline) {
+      pipeline = this._build(material, shaderCode, {
+        textured,
+        instanced,
+        transparent,
+      });
+      variants.set(stateKey, pipeline);
+    }
+    return pipeline;
+  }
+
+  _moduleFor(code) {
+    let module = this._modules.get(code);
+    if (!module) {
+      module = this.device.createShaderModule({ code });
+      this._modules.set(code, module);
+    }
+    return module;
+  }
+
+  _build(material, shaderCode, { textured, instanced, transparent }) {
+    const { topology, cullMode, frontFace } = material;
+    const primitive = { topology, cullMode, frontFace };
+    // Indexed draws on strip topologies must declare the index format
+    // up front; the renderer always uses uint32 indices.
+    if (isStripTopology(topology)) {
+      primitive.stripIndexFormat = INDEX_FORMAT;
+    }
+    const buffers = vertexBufferLayouts(instanced);
+    const target = { format: this.format };
+    if (transparent) {
+      target.blend = STRAIGHT_ALPHA_BLEND;
+    }
+    const module = this._moduleFor(shaderCode);
+    return this.device.createRenderPipeline({
+      layout: textured ? this.texturedPipelineLayout : this.pipelineLayout,
+      vertex: {
+        module,
+        entryPoint: SHADER_ENTRY_POINT.vertex,
+        buffers,
+      },
+      fragment: {
+        module,
+        entryPoint: SHADER_ENTRY_POINT.fragment,
+        targets: [target],
+      },
+      primitive,
+      multisample: { count: this.sampleCount },
+      depthStencil: {
+        format: DEPTH_FORMAT,
+        // Transparent meshes test against the depth buffer (opaque
+        // things still hide them) but don't write it: they draw last,
+        // back-to-front, and shouldn't mask each other.
+        depthWriteEnabled: !transparent,
+        depthCompare: DEFAULT_DEPTH_COMPARE,
+      },
+    });
+  }
+}

package/src/3d/core/RayIntersection.js

@@ -0,0 +1,184 @@
+import { forEachIndexedTriangle } from '../../core/indexedTriangles.js';
+import { VERTEX_SIZE } from '../geometries/Geometry.js';
+
+const POSITION_COMPONENTS = 3;
+const PARALLEL_TRIANGLE_EPSILON = 1e-12;
+const BARYCENTRIC_EPSILON = 1e-7;
+
+/**
+ * Returns the nearest local indexed-triangle hit distance, or `null`.
+ * `direction` intentionally remains unnormalized: when it came from an
+ * inverse-transformed unit world ray, the returned value is a world distance.
+ */
+export function intersectIndexedGeometry(
+  origin,
+  direction,
+  geometry,
+  topology,
+  maxDistance,
+) {
+  if (!intersectsBounds(origin, direction, geometry.bounds, maxDistance)) {
+    return null;
+  }
+
+  let nearestDistance = maxDistance;
+  let hit = false;
+  forEachIndexedTriangle(geometry.indices, topology, (a, b, c) => {
+    const distance = intersectTriangle(
+      origin,
+      direction,
+      geometry.vertices,
+      a,
+      b,
+      c,
+      nearestDistance,
+    );
+    if (distance === null) return false;
+    nearestDistance = distance;
+    hit = true;
+    return distance === 0;
+  });
+  return hit ? nearestDistance : null;
+}
+
+/** Segment-vs-AABB broad phase over the ray interval [0, maxDistance]. */
+export function intersectsBounds(origin, direction, bounds, maxDistance) {
+  const min = bounds?.min;
+  const max = bounds?.max;
+  if (!hasFiniteBounds(min, max)) return false;
+
+  let near = 0;
+  let far = maxDistance;
+  for (let axis = 0; axis < POSITION_COMPONENTS; axis++) {
+    const component = componentAt(direction, axis);
+    const start = componentAt(origin, axis);
+    if (component === 0) {
+      if (start < min[axis] || start > max[axis]) return false;
+      continue;
+    }
+
+    let entry = (min[axis] - start) / component;
+    let exit = (max[axis] - start) / component;
+    if (entry > exit) [entry, exit] = [exit, entry];
+    near = Math.max(near, entry);
+    far = Math.min(far, exit);
+    if (near > far) return false;
+  }
+  return far >= 0 && near <= maxDistance;
+}
+
+function intersectTriangle(
+  origin,
+  direction,
+  vertices,
+  indexA,
+  indexB,
+  indexC,
+  maxDistance,
+) {
+  const offsetA = vertexOffset(vertices, indexA);
+  const offsetB = vertexOffset(vertices, indexB);
+  const offsetC = vertexOffset(vertices, indexC);
+  if (offsetA < 0 || offsetB < 0 || offsetC < 0) return null;
+
+  const ax = vertices[offsetA];
+  const ay = vertices[offsetA + 1];
+  const az = vertices[offsetA + 2];
+  const edge1x = vertices[offsetB] - ax;
+  const edge1y = vertices[offsetB + 1] - ay;
+  const edge1z = vertices[offsetB + 2] - az;
+  const edge2x = vertices[offsetC] - ax;
+  const edge2y = vertices[offsetC + 1] - ay;
+  const edge2z = vertices[offsetC + 2] - az;
+  if (
+    !Number.isFinite(ax) ||
+    !Number.isFinite(ay) ||
+    !Number.isFinite(az) ||
+    !Number.isFinite(edge1x) ||
+    !Number.isFinite(edge1y) ||
+    !Number.isFinite(edge1z) ||
+    !Number.isFinite(edge2x) ||
+    !Number.isFinite(edge2y) ||
+    !Number.isFinite(edge2z)
+  ) {
+    return null;
+  }
+
+  const px = direction.y * edge2z - direction.z * edge2y;
+  const py = direction.z * edge2x - direction.x * edge2z;
+  const pz = direction.x * edge2y - direction.y * edge2x;
+  const determinant = edge1x * px + edge1y * py + edge1z * pz;
+  const determinantScale =
+    Math.hypot(edge1x, edge1y, edge1z) *
+    Math.hypot(edge2x, edge2y, edge2z) *
+    Math.hypot(direction.x, direction.y, direction.z);
+  if (
+    !Number.isFinite(determinantScale) ||
+    determinantScale === 0 ||
+    Math.abs(determinant) <=
+      determinantScale * PARALLEL_TRIANGLE_EPSILON
+  ) {
+    return null;
+  }
+
+  const inverseDeterminant = 1 / determinant;
+  const tx = origin.x - ax;
+  const ty = origin.y - ay;
+  const tz = origin.z - az;
+  const u = (tx * px + ty * py + tz * pz) * inverseDeterminant;
+  if (u < -BARYCENTRIC_EPSILON || u > 1 + BARYCENTRIC_EPSILON) {
+    return null;
+  }
+
+  const qx = ty * edge1z - tz * edge1y;
+  const qy = tz * edge1x - tx * edge1z;
+  const qz = tx * edge1y - ty * edge1x;
+  const v =
+    (direction.x * qx + direction.y * qy + direction.z * qz) *
+    inverseDeterminant;
+  if (
+    v < -BARYCENTRIC_EPSILON ||
+    u + v > 1 + BARYCENTRIC_EPSILON
+  ) {
+    return null;
+  }
+
+  const distance =
+    (edge2x * qx + edge2y * qy + edge2z * qz) * inverseDeterminant;
+  if (
+    !Number.isFinite(distance) ||
+    distance < 0 ||
+    distance > maxDistance
+  ) {
+    return null;
+  }
+  return distance;
+}
+
+function vertexOffset(vertices, index) {
+  if (!Number.isInteger(index)) return -1;
+  const offset = index * VERTEX_SIZE;
+  return index >= 0 && offset + POSITION_COMPONENTS <= vertices.length
+    ? offset
+    : -1;
+}
+
+function hasFiniteBounds(min, max) {
+  if (!min || !max || min.length < 3 || max.length < 3) return false;
+  for (let axis = 0; axis < POSITION_COMPONENTS; axis++) {
+    if (
+      !Number.isFinite(min[axis]) ||
+      !Number.isFinite(max[axis]) ||
+      min[axis] > max[axis]
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function componentAt(vector, axis) {
+  if (axis === 0) return vector.x;
+  if (axis === 1) return vector.y;
+  return vector.z;
+}