micro-gl 0.1.0

package/src/2d/shaders/fragments.js

@@ -0,0 +1,23 @@
+import {
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+} from '../../core/pipelineConstants.js';
+
+export const BASIC_FRAGMENT_SHADER_2D = /* wgsl */ `
+@fragment
+fn fs(input: VertexOut) -> @location(0) vec4f {
+  return objectColor(input);
+}
+`;
+
+export const SPRITE_FRAGMENT_SHADER_2D = /* wgsl */ `
+@group(${SHADER_BIND_GROUP.object}) @binding(${SHADER_BINDING.map})
+var uMap: texture_2d<f32>;
+@group(${SHADER_BIND_GROUP.object}) @binding(${SHADER_BINDING.sampler})
+var uMapSampler: sampler;
+
+@fragment
+fn fs(input: VertexOut) -> @location(0) vec4f {
+  return textureSample(uMap, uMapSampler, input.uv) * objectColor(input);
+}
+`;

package/src/2d/shaders/shared.js

@@ -0,0 +1,28 @@
+import {
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+} from '../../core/pipelineConstants.js';
+import { VERTEX_ATTRIBUTE_2D } from './vertexLayout.js';
+
+/** Uniform declarations shared by every 2D shader. */
+export const SHARED_SHADER_CHUNKS_2D = /* wgsl */ `
+struct FrameUniforms {
+  viewProjection: mat3x3f,
+};
+
+struct ObjectUniforms {
+  transform: mat3x3f,
+  color: vec4f,
+};
+
+@group(${SHADER_BIND_GROUP.frame}) @binding(${SHADER_BINDING.uniforms})
+var<uniform> uFrame: FrameUniforms;
+@group(${SHADER_BIND_GROUP.object}) @binding(${SHADER_BINDING.uniforms})
+var<uniform> uObject: ObjectUniforms;
+
+struct VertexIn {
+  @location(${VERTEX_ATTRIBUTE_2D.position}) position: vec2f,
+  @location(${VERTEX_ATTRIBUTE_2D.uv}) uv: vec2f,
+};
+
+`;

package/src/2d/shaders/vertexLayout.js

@@ -0,0 +1,74 @@
+import { VERTEX_STRIDE_2D } from '../geometries/Geometry2d.js';
+import { INSTANCE_SIZE_2D } from '../constants.js';
+import { INSTANCE_STEP_MODE } from '../../core/pipelineConstants.js';
+
+const FLOAT_BYTES = Float32Array.BYTES_PER_ELEMENT;
+const VEC2_BYTES = 2 * FLOAT_BYTES;
+const PADDED_VEC3_BYTES = 4 * FLOAT_BYTES;
+const MAT3_BYTES = 3 * PADDED_VEC3_BYTES;
+
+/** Vertex input locations shared by WGSL and the GPU buffer descriptors. */
+export const VERTEX_ATTRIBUTE_2D = Object.freeze({
+  position: 0,
+  uv: 1,
+  instanceMatrix0: 2,
+  instanceMatrix1: 3,
+  instanceMatrix2: 4,
+  instanceColor: 5,
+});
+
+export const GEOMETRY_VERTEX_BUFFER_LAYOUT_2D = Object.freeze({
+  arrayStride: VERTEX_STRIDE_2D,
+  attributes: Object.freeze([
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.position,
+      offset: 0,
+      format: 'float32x2',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.uv,
+      offset: VEC2_BYTES,
+      format: 'float32x2',
+    }),
+  ]),
+});
+
+export const INSTANCE_VERTEX_BUFFER_LAYOUT_2D = Object.freeze({
+  arrayStride: INSTANCE_SIZE_2D * FLOAT_BYTES,
+  stepMode: INSTANCE_STEP_MODE,
+  attributes: Object.freeze([
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.instanceMatrix0,
+      offset: 0,
+      format: 'float32x3',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.instanceMatrix1,
+      offset: PADDED_VEC3_BYTES,
+      format: 'float32x3',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.instanceMatrix2,
+      offset: 2 * PADDED_VEC3_BYTES,
+      format: 'float32x3',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE_2D.instanceColor,
+      offset: MAT3_BYTES,
+      format: 'float32x4',
+    }),
+  ]),
+});
+
+const STANDARD_VERTEX_BUFFERS_2D = Object.freeze([
+  GEOMETRY_VERTEX_BUFFER_LAYOUT_2D,
+]);
+const INSTANCED_VERTEX_BUFFERS_2D = Object.freeze([
+  GEOMETRY_VERTEX_BUFFER_LAYOUT_2D,
+  INSTANCE_VERTEX_BUFFER_LAYOUT_2D,
+]);
+
+/** GPU vertex buffer layouts for a regular or instanced shape pipeline. */
+export function vertexBufferLayouts2d(instanced) {
+  return instanced ? INSTANCED_VERTEX_BUFFERS_2D : STANDARD_VERTEX_BUFFERS_2D;
+}

package/src/2d/shaders/vertexStages.js

@@ -0,0 +1,59 @@
+import { SHARED_SHADER_CHUNKS_2D } from './shared.js';
+import { VERTEX_ATTRIBUTE_2D } from './vertexLayout.js';
+
+/** Shared chunks plus the regular shape vertex stage. Append a fragment stage. */
+export const SHAPE_SHADER_PREFIX =
+  SHARED_SHADER_CHUNKS_2D +
+  /* wgsl */ `
+struct VertexOut {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+};
+
+@vertex
+fn vs(input: VertexIn) -> VertexOut {
+  var out: VertexOut;
+  let p = uFrame.viewProjection * uObject.transform * vec3f(input.position, 1.0);
+  out.position = vec4f(p.xy, 0.0, 1.0);
+  out.uv = input.uv;
+  return out;
+}
+
+fn objectColor(input: VertexOut) -> vec4f {
+  return uObject.color;
+}
+`;
+
+/** Shared chunks plus the per-instance shape vertex stage. Append a fragment stage. */
+export const INSTANCED_SHAPE_SHADER_PREFIX =
+  SHARED_SHADER_CHUNKS_2D +
+  /* wgsl */ `
+struct InstanceIn {
+  @location(${VERTEX_ATTRIBUTE_2D.instanceMatrix0}) im0: vec3f,
+  @location(${VERTEX_ATTRIBUTE_2D.instanceMatrix1}) im1: vec3f,
+  @location(${VERTEX_ATTRIBUTE_2D.instanceMatrix2}) im2: vec3f,
+  @location(${VERTEX_ATTRIBUTE_2D.instanceColor}) color: vec4f,
+};
+
+struct VertexOut {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) color: vec4f,
+};
+
+@vertex
+fn vs(input: VertexIn, instance: InstanceIn) -> VertexOut {
+  var out: VertexOut;
+  let instanceMatrix = mat3x3f(instance.im0, instance.im1, instance.im2);
+  let p = uFrame.viewProjection * uObject.transform * instanceMatrix
+    * vec3f(input.position, 1.0);
+  out.position = vec4f(p.xy, 0.0, 1.0);
+  out.uv = input.uv;
+  out.color = instance.color;
+  return out;
+}
+
+fn objectColor(input: VertexOut) -> vec4f {
+  return input.color * uObject.color;
+}
+`;

package/src/3d/cameras/Camera.js

@@ -0,0 +1,66 @@
+import { Object3d } from '../core/Object3d.js';
+import { Vec3 } from '../../math/Vec3.js';
+import { Mat4 } from '../../math/Mat4.js';
+
+/**
+ * Base class for cameras. Set `position`, call `lookAt(...)` to aim it,
+ * and the renderer takes care of the rest (it keeps `aspect` in sync
+ * with the canvas and refreshes the matrices every frame).
+ *
+ * Subclasses implement `updateProjectionMatrix()` and must call it once
+ * at the end of their constructor.
+ *
+ * Note: for simplicity a camera derives its orientation from
+ * position + target (not from `rotation`), and is expected to be a
+ * direct child of the scene (or unparented).
+ */
+export class Camera extends Object3d {
+  /**
+   * @param {number} aspect width / height
+   */
+  constructor(aspect = 1, near = 0.1, far = 1000) {
+    super();
+    this.aspect = aspect;
+    this.near = near;
+    this.far = far;
+
+    this.up = new Vec3(0, 1, 0);
+    this.target = new Vec3(0, 0, 0);
+
+    this.projectionMatrix = new Mat4();
+    this.viewMatrix = new Mat4();
+    this.viewProjectionMatrix = new Mat4();
+  }
+
+  /** Aims the camera at a point. Accepts a Vec3 or (x, y, z). */
+  lookAt(x, y, z) {
+    if (typeof x === 'object') {
+      this.target.copy(x);
+    } else {
+      this.target.set(x, y, z);
+    }
+    return this;
+  }
+
+  updateProjectionMatrix() {
+    throw new Error('Camera subclasses must implement updateProjectionMatrix');
+  }
+
+  /** Called by the renderer every frame. */
+  updateMatrices() {
+    this.updateProjectionMatrix();
+    this.worldMatrix.targetTo(this.position, this.target, this.up);
+    this.viewMatrix.copy(this.worldMatrix).invert();
+    this.viewProjectionMatrix.multiplyMatrices(
+      this.projectionMatrix,
+      this.viewMatrix,
+    );
+
+    // The scene graph was updated before the camera replaced its TRS world
+    // matrix with the look-at orientation. Refresh camera-mounted objects so
+    // they inherit the final camera basis (for example, a HUD or headlight).
+    for (const child of this.children) {
+      child.updateWorldMatrix();
+    }
+  }
+}

package/src/3d/cameras/OrthographicCamera.js

@@ -0,0 +1,35 @@
+import { Camera } from './Camera.js';
+
+/**
+ * An orthographic camera: objects keep the same size regardless of
+ * distance.
+ *
+ * The view volume is defined by `size` (half the visible height in
+ * world units) and `aspect`. Increase `zoom` to magnify.
+ */
+export class OrthographicCamera extends Camera {
+  /**
+   * @param {number} size   half of the visible height in world units
+   * @param {number} aspect width / height
+   */
+  constructor(size = 5, aspect = 1, near = 0.1, far = 1000) {
+    super(aspect, near, far);
+    this.isOrthographic = true;
+    this.size = size;
+    this.zoom = 1;
+    this.updateProjectionMatrix();
+  }
+
+  updateProjectionMatrix() {
+    const halfH = this.size / this.zoom;
+    const halfW = halfH * this.aspect;
+    this.projectionMatrix.orthographic(
+      -halfW,
+      halfW,
+      -halfH,
+      halfH,
+      this.near,
+      this.far,
+    );
+  }
+}

package/src/3d/cameras/PerspectiveCamera.js

@@ -0,0 +1,25 @@
+import { Camera } from './Camera.js';
+
+/**
+ * A perspective camera: distant objects appear smaller, like a real lens.
+ */
+export class PerspectiveCamera extends Camera {
+  /**
+   * @param {number} fov    vertical field of view in degrees
+   * @param {number} aspect width / height
+   */
+  constructor(fov = 60, aspect = 1, near = 0.1, far = 1000) {
+    super(aspect, near, far);
+    this.fov = fov;
+    this.updateProjectionMatrix();
+  }
+
+  updateProjectionMatrix() {
+    this.projectionMatrix.perspective(
+      (this.fov * Math.PI) / 180,
+      this.aspect,
+      this.near,
+      this.far,
+    );
+  }
+}

package/src/3d/constants.js

@@ -0,0 +1,18 @@
+/** Point-light array length shared by CPU uniform writers and WGSL. */
+export const MAX_POINT_LIGHTS = 4;
+
+/** Floats occupied by an instance's mat4 transform. */
+export const INSTANCE_MATRIX_COMPONENTS = 16;
+
+/** Float offset at which an instance's rgba color starts. */
+export const INSTANCE_COLOR_OFFSET = INSTANCE_MATRIX_COMPONENTS;
+
+/** Floats per instance: a mat4 followed by an rgba color. */
+export const INSTANCE_SIZE = INSTANCE_MATRIX_COMPONENTS + 4;
+
+/** Sampled depth format used by directional shadow maps. */
+export const DIRECTIONAL_SHADOW_DEPTH_FORMAT = 'depth32float';
+
+/** A shadow map is always rendered without MSAA. */
+export const SHADOW_SAMPLE_COUNT = 1;
+

package/src/3d/controls/DragControls.js

@@ -0,0 +1,168 @@
+import { Raycaster } from '../core/Raycaster.js';
+import { Vec3 } from '../../math/Vec3.js';
+import { Mat4 } from '../../math/Mat4.js';
+
+const _parentInverse = new Mat4();
+const _worldPos = new Vec3();
+const PARALLEL_PLANE_EPSILON = 1e-9;
+
+/**
+ * Lets the user pick meshes with the pointer and drag them around.
+ * Dragged objects slide on a camera-facing plane through the point
+ * where they were grabbed, so they follow the cursor exactly.
+ *
+ * Assign the callbacks to react to interaction:
+ *   onSelect(mesh | null)  selection changed (click on object / empty space)
+ *   onDragStart(mesh), onDrag(mesh), onDragEnd(mesh)
+ *
+ * Disable your camera controls in onDragStart / re-enable in onDragEnd
+ * so orbiting doesn't fight the drag. If you switch the active camera,
+ * update `controls.camera` too.
+ */
+export class DragControls {
+  /**
+   * @param {Mesh[]} objects meshes that can be selected and dragged
+   */
+  constructor(objects, camera, domElement) {
+    this.objects = objects;
+    this.camera = camera;
+    this.domElement = domElement;
+    /** Set to false to ignore input; it also pauses an in-progress drag. */
+    this.enabled = true;
+    this.selected = null;
+
+    this.onSelect = null;
+    this.onDragStart = null;
+    this.onDrag = null;
+    this.onDragEnd = null;
+
+    this._raycaster = new Raycaster();
+    this._dragging = false;
+    this._activePointerId = null;
+    this._grabPoint = new Vec3(); // world point where the object was grabbed
+    this._grabOffset = new Vec3(); // object world position - grab point
+    this._planeNormal = new Vec3();
+
+    this._onPointerDown = this._handlePointerDown.bind(this);
+    this._onPointerMove = this._handlePointerMove.bind(this);
+    this._onPointerUp = this._handlePointerUp.bind(this);
+
+    domElement.addEventListener('pointerdown', this._onPointerDown);
+    domElement.addEventListener('pointermove', this._onPointerMove);
+    domElement.addEventListener('pointerup', this._onPointerUp);
+    domElement.addEventListener('pointercancel', this._onPointerUp);
+  }
+
+  _handlePointerDown(event) {
+    const orbitGesture = event.button !== 0 || event.altKey;
+    if (!this.enabled || orbitGesture || this._activePointerId !== null) return;
+
+    const hit = this._pick(event);
+    if (!hit) {
+      this._select(null);
+      return;
+    }
+
+    this._select(hit.object);
+    this._dragging = true;
+    this._activePointerId = event.pointerId;
+    this.domElement.setPointerCapture(event.pointerId);
+
+    // Drag on the camera-facing plane through the grab point.
+    const cameraMatrix = this.camera.worldMatrix.elements;
+    this._planeNormal.set(cameraMatrix[8], cameraMatrix[9], cameraMatrix[10]);
+    this._grabPoint.copy(hit.point);
+    const objectMatrix = hit.object.worldMatrix.elements;
+    this._grabOffset
+      .set(objectMatrix[12], objectMatrix[13], objectMatrix[14])
+      .sub(hit.point);
+
+    if (this.onDragStart) this.onDragStart(hit.object);
+  }
+
+  _handlePointerMove(event) {
+    if (
+      !this.enabled ||
+      !this._dragging ||
+      !this.selected ||
+      event.pointerId !== this._activePointerId
+    ) {
+      return;
+    }
+
+    const point = this._intersectDragPlane(event);
+    if (!point) return;
+
+    // New world position, then into the parent's local space.
+    _worldPos.copy(point).add(this._grabOffset);
+    const parent = this.selected.parent;
+    if (parent) {
+      if (!_parentInverse.copy(parent.worldMatrix).tryInvert()) return;
+      _worldPos.applyMat4(_parentInverse);
+    }
+    this.selected.position.copy(_worldPos);
+    if (this.onDrag) this.onDrag(this.selected);
+  }
+
+  _handlePointerUp(event) {
+    if (!this._dragging || event.pointerId !== this._activePointerId) return;
+    this._finishDrag();
+  }
+
+  _finishDrag() {
+    const pointerId = this._activePointerId;
+    this._dragging = false;
+    this._activePointerId = null;
+    if (
+      pointerId !== null &&
+      this.domElement.hasPointerCapture(pointerId)
+    ) {
+      this.domElement.releasePointerCapture(pointerId);
+    }
+    if (this.onDragEnd) this.onDragEnd(this.selected);
+  }
+
+  _select(mesh) {
+    if (mesh === this.selected) return;
+    this.selected = mesh;
+    if (this.onSelect) this.onSelect(mesh);
+  }
+
+  _ray(e) {
+    const rect = this.domElement.getBoundingClientRect();
+    const ndcX = ((e.clientX - rect.left) / rect.width) * 2 - 1;
+    const ndcY = 1 - ((e.clientY - rect.top) / rect.height) * 2;
+    return this._raycaster.setFromCamera(ndcX, ndcY, this.camera);
+  }
+
+  _pick(e) {
+    const hits = this._ray(e).intersectObjects(this.objects);
+    return hits.length > 0 ? hits[0] : null;
+  }
+
+  /** Where the pointer ray crosses the drag plane, or null if parallel. */
+  _intersectDragPlane(e) {
+    const ray = this._ray(e);
+    const n = this._planeNormal;
+    const denom = n.dot(ray.direction);
+    if (Math.abs(denom) < PARALLEL_PLANE_EPSILON) return null;
+    const t =
+      (n.x * (this._grabPoint.x - ray.origin.x) +
+        n.y * (this._grabPoint.y - ray.origin.y) +
+        n.z * (this._grabPoint.z - ray.origin.z)) /
+      denom;
+    return new Vec3(
+      ray.origin.x + ray.direction.x * t,
+      ray.origin.y + ray.direction.y * t,
+      ray.origin.z + ray.direction.z * t,
+    );
+  }
+
+  dispose() {
+    if (this._dragging) this._finishDrag();
+    this.domElement.removeEventListener('pointerdown', this._onPointerDown);
+    this.domElement.removeEventListener('pointermove', this._onPointerMove);
+    this.domElement.removeEventListener('pointerup', this._onPointerUp);
+    this.domElement.removeEventListener('pointercancel', this._onPointerUp);
+  }
+}

package/src/3d/controls/OrbitControls.js

@@ -0,0 +1,125 @@
+import {
+  PointerControls,
+  TOUCH_GESTURE,
+} from '../../core/PointerControls.js';
+
+const DEFAULT_POLAR_ANGLE = Math.PI / 2;
+const DIRECTION_EPSILON = 1e-12;
+const POLE_TILT_EPSILON = 1e-4;
+const DEGREES_TO_HALF_RADIANS = Math.PI / 360;
+
+/**
+ * Mouse / touch controls that orbit a camera around a target point.
+ * Alt + left-drag to rotate, right-drag to pan, scroll (or pinch-zoom
+ * trackpad) to dolly in and out. A right-click without dragging still
+ * opens the browser context menu. On touch screens: one-finger drag
+ * orbits, two-finger drag pans, pinch zooms.
+ *
+ * The gesture plumbing lives in PointerControls; this class is the
+ * orbit math. Call `controls.update()` once per frame before rendering.
+ */
+export class OrbitControls extends PointerControls {
+  constructor(camera, domElement) {
+    super(domElement);
+    this.camera = camera;
+    this.singleTouchGesture = TOUCH_GESTURE.ROTATE;
+
+    // Shares the camera's target so lookAt stays in sync.
+    this.target = camera.target;
+
+    this.minRadius = 0.5;
+    this.maxRadius = 100;
+    this.minZoom = 0.1;
+    this.maxZoom = 20;
+    this.minPhi = 0.05;
+    this.maxPhi = Math.PI - 0.05;
+
+    // Spherical coordinates derived from the camera's starting position.
+    const dx = camera.position.x - this.target.x;
+    const dy = camera.position.y - this.target.y;
+    const dz = camera.position.z - this.target.z;
+    const initialRadius = Math.hypot(dx, dy, dz);
+    this.radius = Math.min(
+      Math.max(initialRadius, this.minRadius),
+      this.maxRadius,
+    );
+    this.theta = Math.atan2(dx, dz);
+    this.phi =
+      initialRadius > DIRECTION_EPSILON
+        ? Math.acos(Math.min(Math.max(dy / initialRadius, -1), 1))
+        : DEFAULT_POLAR_ANGLE;
+  }
+
+  /**
+   * Half the height of the view volume at the target's distance,
+   * in world units.
+   */
+  _visibleHalfHeight() {
+    return this.camera.isOrthographic
+      ? this.camera.size / this.camera.zoom
+      : this.radius * Math.tan(this.camera.fov * DEGREES_TO_HALF_RADIANS);
+  }
+
+  _rotate(rx, ry) {
+    this.theta -= rx;
+    this.phi = Math.min(Math.max(this.phi - ry, this.minPhi), this.maxPhi);
+  }
+
+  /**
+   * Moves the target along the camera's screen-space axes so the scene
+   * follows the cursor (1 pixel of drag = 1 pixel on screen).
+   */
+  _pan(dx, dy) {
+    const e = this.camera.worldMatrix.elements;
+    const worldPerPixel =
+      (2 * this._visibleHalfHeight()) / this.domElement.clientHeight;
+    // Columns 0 and 1 of the world matrix are the camera's right/up axes.
+    this.target.x -= (e[0] * dx - e[4] * dy) * worldPerPixel;
+    this.target.y -= (e[1] * dx - e[5] * dy) * worldPerPixel;
+    this.target.z -= (e[2] * dx - e[6] * dy) * worldPerPixel;
+  }
+
+  _zoom(factor, ndcX, ndcY) {
+    const halfHBefore = this._visibleHalfHeight();
+    if (this.camera.isOrthographic) {
+      // Dollying doesn't change apparent size in ortho; scale the
+      // camera's zoom instead.
+      this.camera.zoom /= factor;
+      this.camera.zoom = Math.min(
+        Math.max(this.camera.zoom, this.minZoom),
+        this.maxZoom,
+      );
+    } else {
+      this.radius *= factor;
+      this.radius = Math.min(
+        Math.max(this.radius, this.minRadius),
+        this.maxRadius,
+      );
+    }
+
+    // Zoom toward the cursor: shift the target so the world point
+    // under the pointer stays under it as the view scales.
+    const dh = halfHBefore - this._visibleHalfHeight();
+    const ox = ndcX * dh * this.camera.aspect;
+    const oy = ndcY * dh;
+    const m = this.camera.worldMatrix.elements;
+    this.target.x += m[0] * ox + m[4] * oy;
+    this.target.y += m[1] * ox + m[5] * oy;
+    this.target.z += m[2] * ox + m[6] * oy;
+  }
+
+  /** Applies the current orbit state to the camera. Call once per frame. */
+  update() {
+    // Keep an imperceptible tilt so that even at phi = 0 (straight
+    // top-down) the camera's screen orientation follows theta, letting
+    // the view spin around the vertical axis.
+    const phi = Math.max(this.phi, POLE_TILT_EPSILON);
+    const sinPhi = Math.sin(phi);
+    this.camera.position.set(
+      this.target.x + this.radius * sinPhi * Math.sin(this.theta),
+      this.target.y + this.radius * Math.cos(phi),
+      this.target.z + this.radius * sinPhi * Math.cos(this.theta),
+    );
+    this.camera.lookAt(this.target);
+  }
+}