micro-gl 0.1.0

package/src/index.js

@@ -0,0 +1,68 @@
+// micro-gl — a tiny WebGPU engine, in two flavors that share one canvas:
+//   src/3d/ — the perspective engine (Mat4, lights, depth buffer)
+//   src/2d/ — the flat engine (Mat3, zIndex ordering, alpha blending)
+// with src/math/ and src/core/ shared between them.
+// Import everything from this single package entry point:
+//   import { Renderer, Scene, Mesh, ... } from 'micro-gl';
+
+// --- Shared ---------------------------------------------------------------
+export { Vec3 } from './math/Vec3.js';
+export { Mat4 } from './math/Mat4.js';
+export { Frustum } from './math/Frustum.js';
+export { Vec2 } from './math/Vec2.js';
+export { Mat3 } from './math/Mat3.js';
+export { srgbToLinear, linearToSrgb } from './math/color.js';
+export { initWebGpu } from './core/initWebGpu.js';
+export { Texture } from './core/Texture.js';
+export { PointerControls, TOUCH_GESTURE } from './core/PointerControls.js';
+
+// --- 3D engine --------------------------------------------------------------
+export { Object3d } from './3d/core/Object3d.js';
+export { Raycaster } from './3d/core/Raycaster.js';
+export { Scene } from './3d/core/Scene.js';
+export { Mesh } from './3d/core/Mesh.js';
+export { InstancedMesh } from './3d/core/InstancedMesh.js';
+export { Renderer } from './3d/core/Renderer.js';
+
+export { Camera } from './3d/cameras/Camera.js';
+export { PerspectiveCamera } from './3d/cameras/PerspectiveCamera.js';
+export { OrthographicCamera } from './3d/cameras/OrthographicCamera.js';
+export { OrbitControls } from './3d/controls/OrbitControls.js';
+export { DragControls } from './3d/controls/DragControls.js';
+
+export { Geometry } from './3d/geometries/Geometry.js';
+export { BoxGeometry } from './3d/geometries/BoxGeometry.js';
+export { SphereGeometry } from './3d/geometries/SphereGeometry.js';
+export { PlaneGeometry } from './3d/geometries/PlaneGeometry.js';
+export { WireframeGeometry } from './3d/geometries/WireframeGeometry.js';
+
+export { Material, MAX_POINT_LIGHTS } from './3d/materials/Material.js';
+export { BasicMaterial } from './3d/materials/BasicMaterial.js';
+export { LambertMaterial } from './3d/materials/LambertMaterial.js';
+export { TextureMaterial } from './3d/materials/TextureMaterial.js';
+
+export { DirectionalLight } from './3d/lights/DirectionalLight.js';
+export { DirectionalShadow } from './3d/lights/DirectionalShadow.js';
+export { AmbientLight } from './3d/lights/AmbientLight.js';
+export { PointLight } from './3d/lights/PointLight.js';
+
+export { GridHelper } from './3d/helpers/GridHelper.js';
+
+// --- 2D engine --------------------------------------------------------------
+export { Object2d } from './2d/core/Object2d.js';
+export { Scene2d } from './2d/core/Scene2d.js';
+export { Shape2d } from './2d/core/Shape2d.js';
+export { InstancedShape2d } from './2d/core/InstancedShape2d.js';
+export { Renderer2d } from './2d/core/Renderer2d.js';
+
+export { Camera2d } from './2d/cameras/Camera2d.js';
+export { PanZoomControls } from './2d/controls/PanZoomControls.js';
+export { DragControls2d } from './2d/controls/DragControls2d.js';
+
+export { Geometry2d } from './2d/geometries/Geometry2d.js';
+export { RectGeometry } from './2d/geometries/RectGeometry.js';
+export { CircleGeometry } from './2d/geometries/CircleGeometry.js';
+
+export { Material2d } from './2d/materials/Material2d.js';
+export { BasicMaterial2d } from './2d/materials/BasicMaterial2d.js';
+export { SpriteMaterial2d } from './2d/materials/SpriteMaterial2d.js';

package/src/math/Frustum.js

@@ -0,0 +1,143 @@
+const PLANE_COMPONENTS = 4;
+const PLANE_COUNT = 6;
+const PLANE_EPSILON = 1e-12;
+const INTERSECTION_EPSILON = 1e-6;
+const PLANE_INDEX = Object.freeze({
+  left: 0,
+  right: 1,
+  bottom: 2,
+  top: 3,
+  near: 4,
+  far: 5,
+});
+
+const IDENTITY_ELEMENTS = Object.freeze([
+  1, 0, 0, 0,
+  0, 1, 0, 0,
+  0, 0, 1, 0,
+  0, 0, 0, 1,
+]);
+
+/**
+ * Six clipping planes extracted from a WebGPU view-projection matrix.
+ * WebGPU depth is 0..w, so its near plane is `z >= 0` rather than the
+ * OpenGL-style `z + w >= 0`.
+ */
+export class Frustum {
+  constructor() {
+    /** Packed normalized planes: x, y, z, constant. */
+    this.planes = new Float32Array(PLANE_COUNT * PLANE_COMPONENTS);
+    this.valid = false;
+  }
+
+  /** Replaces the planes from a column-major view-projection matrix. */
+  setFromViewProjectionMatrix(matrix) {
+    const e = matrix?.elements;
+    if (!e || e.length < 16) {
+      this.valid = false;
+      return this;
+    }
+
+    this.valid = true;
+    // Clip-space inequalities: x/y in -w..w and z in 0..w.
+    this._setPlane(
+      PLANE_INDEX.left,
+      e[3] + e[0],
+      e[7] + e[4],
+      e[11] + e[8],
+      e[15] + e[12],
+    );
+    this._setPlane(
+      PLANE_INDEX.right,
+      e[3] - e[0],
+      e[7] - e[4],
+      e[11] - e[8],
+      e[15] - e[12],
+    );
+    this._setPlane(
+      PLANE_INDEX.bottom,
+      e[3] + e[1],
+      e[7] + e[5],
+      e[11] + e[9],
+      e[15] + e[13],
+    );
+    this._setPlane(
+      PLANE_INDEX.top,
+      e[3] - e[1],
+      e[7] - e[5],
+      e[11] - e[9],
+      e[15] - e[13],
+    );
+    this._setPlane(PLANE_INDEX.near, e[2], e[6], e[10], e[14]);
+    this._setPlane(
+      PLANE_INDEX.far,
+      e[3] - e[2],
+      e[7] - e[6],
+      e[11] - e[10],
+      e[15] - e[14],
+    );
+    return this;
+  }
+
+  /**
+   * Tests a local-space axis-aligned box after `transform` is applied.
+   * Invalid data fails open (visible) so culling never hides an object merely
+   * because a custom matrix or dynamic geometry cannot be bounded safely.
+   */
+  intersectsBox(bounds, transform = null) {
+    if (!this.valid) return true;
+    const min = bounds?.min;
+    const max = bounds?.max;
+    if (!min || !max || min.length < 3 || max.length < 3) return true;
+
+    for (let axis = 0; axis < 3; axis++) {
+      if (min[axis] > max[axis]) return false;
+      if (!Number.isFinite(min[axis]) || !Number.isFinite(max[axis])) {
+        return true;
+      }
+    }
+
+    const e = transform?.elements || IDENTITY_ELEMENTS;
+    if (e.length < 16) return true;
+    for (let i = 0; i < 16; i++) {
+      if (!Number.isFinite(e[i])) return true;
+    }
+
+    const planes = this.planes;
+    for (let offset = 0; offset < planes.length; offset += PLANE_COMPONENTS) {
+      const px = planes[offset];
+      const py = planes[offset + 1];
+      const pz = planes[offset + 2];
+      const pw = planes[offset + 3];
+
+      // Transform the world-space plane into box-local space with M^T. The
+      // positive local vertex gives the box's greatest signed plane distance.
+      const qx = e[0] * px + e[1] * py + e[2] * pz + e[3] * pw;
+      const qy = e[4] * px + e[5] * py + e[6] * pz + e[7] * pw;
+      const qz = e[8] * px + e[9] * py + e[10] * pz + e[11] * pw;
+      const qw = e[12] * px + e[13] * py + e[14] * pz + e[15] * pw;
+      const x = qx >= 0 ? max[0] : min[0];
+      const y = qy >= 0 ? max[1] : min[1];
+      const z = qz >= 0 ? max[2] : min[2];
+      const distance = qx * x + qy * y + qz * z + qw;
+      if (!Number.isFinite(distance)) return true;
+      if (distance < -INTERSECTION_EPSILON) return false;
+    }
+    return true;
+  }
+
+  _setPlane(index, x, y, z, constant) {
+    const length = Math.hypot(x, y, z);
+    if (!Number.isFinite(length) || length <= PLANE_EPSILON) {
+      this.valid = false;
+      return;
+    }
+    const offset = index * PLANE_COMPONENTS;
+    const inverseLength = 1 / length;
+    this.planes[offset] = x * inverseLength;
+    this.planes[offset + 1] = y * inverseLength;
+    this.planes[offset + 2] = z * inverseLength;
+    this.planes[offset + 3] = constant * inverseLength;
+    if (!Number.isFinite(this.planes[offset + 3])) this.valid = false;
+  }
+}

package/src/math/Mat3.js

@@ -0,0 +1,165 @@
+/**
+ * A 3x3 matrix for 2D affine transforms (translation, rotation, scale).
+ *
+ * Stored column-major with each column padded to 4 floats — the exact
+ * layout WebGPU expects for a `mat3x3f` inside a uniform buffer, so
+ * `elements` (12 floats) can be uploaded directly.
+ *
+ * Logical layout:      `elements` indices:
+ *   | a  c  tx |         | 0  4   8 |
+ *   | b  d  ty |         | 1  5   9 |
+ *   | 0  0  1  |         | 2  6  10 |   (3, 7 and 11 are padding)
+ */
+export class Mat3 {
+  constructor() {
+    this.elements = new Float32Array(12);
+    this.identity();
+  }
+
+  identity() {
+    const e = this.elements;
+    e.fill(0);
+    e[0] = e[5] = e[10] = 1;
+    return this;
+  }
+
+  copy(m) {
+    this.elements.set(m.elements);
+    return this;
+  }
+
+  /** this = this * m */
+  multiply(m) {
+    return this.multiplyMatrices(this, m);
+  }
+
+  /** this = m * this */
+  premultiply(m) {
+    return this.multiplyMatrices(m, this);
+  }
+
+  /** this = a * b (safe even when this === a or this === b) */
+  multiplyMatrices(a, b) {
+    const ae = a.elements;
+    const be = b.elements;
+    const te = this.elements;
+
+    const a11 = ae[0],
+      a12 = ae[4],
+      a13 = ae[8];
+    const a21 = ae[1],
+      a22 = ae[5],
+      a23 = ae[9];
+    const a31 = ae[2],
+      a32 = ae[6],
+      a33 = ae[10];
+
+    const b11 = be[0],
+      b12 = be[4],
+      b13 = be[8];
+    const b21 = be[1],
+      b22 = be[5],
+      b23 = be[9];
+    const b31 = be[2],
+      b32 = be[6],
+      b33 = be[10];
+
+    te[0] = a11 * b11 + a12 * b21 + a13 * b31;
+    te[4] = a11 * b12 + a12 * b22 + a13 * b32;
+    te[8] = a11 * b13 + a12 * b23 + a13 * b33;
+
+    te[1] = a21 * b11 + a22 * b21 + a23 * b31;
+    te[5] = a21 * b12 + a22 * b22 + a23 * b32;
+    te[9] = a21 * b13 + a22 * b23 + a23 * b33;
+
+    te[2] = a31 * b11 + a32 * b21 + a33 * b31;
+    te[6] = a31 * b12 + a32 * b22 + a33 * b32;
+    te[10] = a31 * b13 + a32 * b23 + a33 * b33;
+
+    return this;
+  }
+
+  makeTranslation(x, y) {
+    this.identity();
+    const e = this.elements;
+    e[8] = x;
+    e[9] = y;
+    return this;
+  }
+
+  makeRotation(angle) {
+    this.identity();
+    const c = Math.cos(angle),
+      s = Math.sin(angle);
+    const e = this.elements;
+    e[0] = c;
+    e[4] = -s;
+    e[1] = s;
+    e[5] = c;
+    return this;
+  }
+
+  makeScale(x, y) {
+    this.identity();
+    const e = this.elements;
+    e[0] = x;
+    e[5] = y;
+    return this;
+  }
+
+  /**
+   * Builds a transform from position, rotation (radians) and scale:
+   * this = T * R * S. Small enough in 2D to write out directly.
+   */
+  compose(position, rotation, scale) {
+    const c = Math.cos(rotation),
+      s = Math.sin(rotation);
+    const e = this.elements;
+    e.fill(0);
+    e[0] = c * scale.x;
+    e[1] = s * scale.x;
+    e[4] = -s * scale.y;
+    e[5] = c * scale.y;
+    e[8] = position.x;
+    e[9] = position.y;
+    e[10] = 1;
+    return this;
+  }
+
+  /**
+   * Inverts the matrix, assuming it is affine (bottom row 0 0 1), and
+   * throws when no inverse exists. Every matrix this engine composes is affine.
+   */
+  invert() {
+    if (!this.tryInvert()) {
+      throw new RangeError('Cannot invert a singular Mat3');
+    }
+    return this;
+  }
+
+  /**
+   * Attempts to invert this affine matrix without changing it when it is
+   * singular. Returns whether the inverse was written.
+   */
+  tryInvert() {
+    const e = this.elements;
+    const a = e[0],
+      b = e[1],
+      c = e[4],
+      d = e[5],
+      tx = e[8],
+      ty = e[9];
+
+    let det = a * d - b * c;
+    if (det === 0 || !Number.isFinite(det)) return false;
+    det = 1 / det;
+
+    e[0] = d * det;
+    e[1] = -b * det;
+    e[4] = -c * det;
+    e[5] = a * det;
+    e[8] = (c * ty - d * tx) * det;
+    e[9] = (b * tx - a * ty) * det;
+    return true;
+  }
+}