@es3d/es3d 0.0.0-stage → 1.0.0

package/src/render/geometry-pool.js

@@ -0,0 +1,149 @@
+// Shared vertex / index buffers.
+//
+// All meshes (every geometry, every level of detail, wireframe edge lists and
+// normal-visualisation lines) are packed into ONE interleaved vertex array and
+// ONE 32-bit index array. Indices are stored pre-offset (absolute), so a draw
+// is just (firstIndex, indexCount). No per-draw buffer binding, and no base
+// vertex. That keeps the WebGL2 and WebGPU paths the same.
+//
+// The pool is CPU-side; backends upload the ranges appended since their last
+// sync (or everything after a reallocation).
+
+export const VERTEX_FLOATS = 8; // position xyz, normal xyz, uv
+export const VERTEX_BYTES = VERTEX_FLOATS * 4;
+
+export class GeometryPool {
+  constructor(vertexCapacity = 1 << 16, indexCapacity = 1 << 17) {
+    this.vertices = new Float32Array(vertexCapacity * VERTEX_FLOATS);
+    this.indices = new Uint32Array(indexCapacity);
+    this.vertexCount = 0;
+    this.indexCount = 0;
+    this.ranges = new Map(); // key object -> {firstIndex, indexCount}
+    this.edgeRanges = new Map();
+    this.normalRanges = new Map();
+    // dirty tracking for incremental uploads
+    this.generation = 0; // bumps on reallocation
+    this.uploadedVertices = 0;
+    this.uploadedIndices = 0;
+  }
+
+  reset() {
+    this.vertexCount = 0;
+    this.indexCount = 0;
+    this.ranges.clear();
+    this.edgeRanges.clear();
+    this.normalRanges.clear();
+    this.generation++;
+    this.uploadedVertices = 0;
+    this.uploadedIndices = 0;
+  }
+
+  get byteSize() {
+    return this.vertexCount * VERTEX_BYTES + this.indexCount * 4;
+  }
+
+  ensure(extraV, extraI) {
+    let grew = false;
+    if ((this.vertexCount + extraV) * VERTEX_FLOATS > this.vertices.length) {
+      let cap = this.vertices.length / VERTEX_FLOATS;
+      while (cap < this.vertexCount + extraV) cap *= 2;
+      const v = new Float32Array(cap * VERTEX_FLOATS);
+      v.set(this.vertices.subarray(0, this.vertexCount * VERTEX_FLOATS));
+      this.vertices = v;
+      grew = true;
+    }
+    if (this.indexCount + extraI > this.indices.length) {
+      let cap = this.indices.length;
+      while (cap < this.indexCount + extraI) cap *= 2;
+      const i = new Uint32Array(cap);
+      i.set(this.indices.subarray(0, this.indexCount));
+      this.indices = i;
+      grew = true;
+    }
+    if (grew) {
+      this.generation++;
+      this.uploadedVertices = 0;
+      this.uploadedIndices = 0;
+    }
+  }
+
+  appendVertices(mesh) {
+    const n = mesh.vertexCount;
+    const base = this.vertexCount;
+    const v = this.vertices;
+    const p = mesh.positions, nr = mesh.normals, t = mesh.uvs;
+    let o = base * VERTEX_FLOATS;
+    for (let i = 0; i < n; i++) {
+      v[o] = p[i * 3];
+      v[o + 1] = p[i * 3 + 1];
+      v[o + 2] = p[i * 3 + 2];
+      v[o + 3] = nr[i * 3];
+      v[o + 4] = nr[i * 3 + 1];
+      v[o + 5] = nr[i * 3 + 2];
+      v[o + 6] = t[i * 2];
+      v[o + 7] = t[i * 2 + 1];
+      o += VERTEX_FLOATS;
+    }
+    this.vertexCount += n;
+    return base;
+  }
+
+  appendIndices(src, base) {
+    const first = this.indexCount;
+    const dst = this.indices;
+    for (let i = 0; i < src.length; i++) dst[first + i] = src[i] + base;
+    this.indexCount += src.length;
+    return first;
+  }
+
+  /** Range of a mesh's primitives (triangles or lines). */
+  meshRange(mesh) {
+    let r = this.ranges.get(mesh);
+    if (r) return r;
+    this.ensure(mesh.vertexCount, mesh.indices.length);
+    const base = this.appendVertices(mesh);
+    const first = this.appendIndices(mesh.indices, base);
+    r = { firstIndex: first, indexCount: mesh.indices.length, baseVertex: base, kind: mesh.kind };
+    this.ranges.set(mesh, r);
+    return r;
+  }
+
+  /** Line range with the unique edges of a mesh (wireframe). */
+  edgeRange(mesh) {
+    let r = this.edgeRanges.get(mesh);
+    if (r) return r;
+    const base = this.meshRange(mesh).baseVertex;
+    const edges = mesh.edges();
+    this.ensure(0, edges.length);
+    const first = this.appendIndices(edges, base);
+    r = { firstIndex: first, indexCount: edges.length, kind: 'lines' };
+    this.edgeRanges.set(mesh, r);
+    return r;
+  }
+
+  /** Line range visualising vertex normals (uv.x = 0 at the base, 1 at the tip). */
+  normalRange(mesh) {
+    let r = this.normalRanges.get(mesh);
+    if (r) return r;
+    const lines = mesh.normalLines();
+    r = this.meshRange(lines);
+    this.normalRanges.set(mesh, r);
+    return r;
+  }
+
+  /** Pending upload ranges since the last sync. */
+  pending() {
+    return {
+      full: this.uploadedVertices === 0 && this.uploadedIndices === 0,
+      vertexStart: this.uploadedVertices,
+      vertexEnd: this.vertexCount,
+      indexStart: this.uploadedIndices,
+      indexEnd: this.indexCount,
+    };
+  }
+
+  markUploaded() {
+    this.uploadedVertices = this.vertexCount;
+    this.uploadedIndices = this.indexCount;
+  }
+}

package/src/render/lighting.js

@@ -0,0 +1,149 @@
+// Packing of per-frame uniforms (camera, environment and lights) into the
+// layout shared by the GLSL uniform block and the WGSL uniform struct:
+//
+//   mat4 viewProj; mat4 view; vec4 cameraPos(time); vec4 sky(envIntensity);
+//   vec4 ground(exposure); vec4 params(lightCount, normalLength, lineBias, viewportH);
+//   vec4 lightPos[16]   xyz = position, w = type (0 dir, 1 point, 2 spot, 3 ambient, 4 hemisphere)
+//   vec4 lightDir[16]   xyz = direction, w = range
+//   vec4 lightColor[16] rgb = color * intensity, w = cos(outer cone)
+//   vec4 lightExtra[16] x = cos(inner cone), yzw = hemisphere ground color
+
+import { colorToLinear } from '../format/colors.js';
+
+export const MAX_LIGHTS = 16;
+export const FRAME_FLOATS = 48 + MAX_LIGHTS * 16;
+export const FRAME_BYTES = FRAME_FLOATS * 4;
+
+const TYPE_CODE = { directional: 0, point: 1, spot: 2, ambient: 3, hemisphere: 4 };
+
+/** Lights used when a document defines none: a key and a fill light. */
+// Light intensity convention: a white directional light of intensity 1 lights a
+// white diffuse surface it faces head-on to full brightness (radiance * PI in the shader).
+export const DEFAULT_LIGHTS = [
+  { type: 'directional', color: [1.1, 1.08, 1.04], direction: norm([-0.45, -0.85, -0.35]), position: [0, 0, 0], range: 0, outer: 0, inner: 0, ground: [0, 0, 0] },
+  { type: 'directional', color: [0.22, 0.25, 0.32], direction: norm([0.6, -0.2, 0.75]), position: [0, 0, 0], range: 0, outer: 0, inner: 0, ground: [0, 0, 0] },
+];
+
+function norm(v) {
+  const l = Math.hypot(v[0], v[1], v[2]) || 1;
+  return [v[0] / l, v[1] / l, v[2] / l];
+}
+
+/**
+ * @returns {{data: Float32Array, lightCount: number, truncated: number}}
+ */
+export function packFrameUniforms(out, { viewProj, view, cameraPos, time, environment, lights, normalLength = 0.1, lineBias = 0.0015, viewportHeight = 1 }) {
+  out.fill(0);
+  out.set(viewProj, 0);
+  out.set(view, 16);
+  out[32] = cameraPos[0];
+  out[33] = cameraPos[1];
+  out[34] = cameraPos[2];
+  out[35] = time || 0;
+  const sky = colorToLinear(environment.sky);
+  const ground = colorToLinear(environment.ground);
+  out[36] = sky[0];
+  out[37] = sky[1];
+  out[38] = sky[2];
+  out[39] = environment.intensity;
+  out[40] = ground[0];
+  out[41] = ground[1];
+  out[42] = ground[2];
+  out[43] = environment.exposure;
+  const list = lights && lights.length ? lights : DEFAULT_LIGHTS;
+  const count = Math.min(list.length, MAX_LIGHTS);
+  out[44] = count;
+  out[45] = normalLength;
+  out[46] = lineBias;
+  out[47] = viewportHeight;
+  for (let i = 0; i < count; i++) {
+    const l = list[i];
+    const p = 48 + i * 4;
+    const d = 48 + MAX_LIGHTS * 4 + i * 4;
+    const c = 48 + MAX_LIGHTS * 8 + i * 4;
+    const e = 48 + MAX_LIGHTS * 12 + i * 4;
+    out[p] = l.position[0];
+    out[p + 1] = l.position[1];
+    out[p + 2] = l.position[2];
+    out[p + 3] = TYPE_CODE[l.type] ?? 0;
+    out[d] = l.direction[0];
+    out[d + 1] = l.direction[1];
+    out[d + 2] = l.direction[2];
+    out[d + 3] = l.range || 0;
+    out[c] = l.color[0];
+    out[c + 1] = l.color[1];
+    out[c + 2] = l.color[2];
+    out[c + 3] = l.outer || 0;
+    // smoothstep needs edge0 < edge1: keep the inner cone strictly inside the outer one
+    out[e] = Math.max(l.inner || 0, (l.outer || 0) + 1e-4);
+    out[e + 1] = l.ground ? l.ground[0] : 0;
+    out[e + 2] = l.ground ? l.ground[1] : 0;
+    out[e + 3] = l.ground ? l.ground[2] : 0;
+  }
+  return { data: out, lightCount: count, truncated: Math.max(0, list.length - MAX_LIGHTS), usedDefaults: !(lights && lights.length) };
+}
+
+/**
+ * The light types of packed frame uniforms, in order, as a short key ("0,0",
+ * "0,1,2"): the light setup that mesh shaders are specialised for.
+ */
+export function lightTypes(frameData) {
+  const n = Math.round(frameData[44]);
+  let key = '';
+  for (let i = 0; i < n; i++) key += (i ? ',' : '') + Math.round(frameData[48 + i * 4 + 3]);
+  return key;
+}
+
+/** Material uniform block: baseColor, emissive(normalScale), params(metallic, roughness, flags), uvScale, overlay color. */
+export const MATERIAL_FLOATS = 20;
+
+export const MAT_FLAG_MAP = 1;
+export const MAT_FLAG_NORMAL_MAP = 2;
+export const MAT_FLAG_DOUBLE_SIDED = 4;
+export const MAT_FLAG_UNLIT = 8;
+export const MAT_FLAG_OVERLAY = 16;
+export const MAT_FLAG_MR_MAP = 32;
+export const MAT_FLAG_OCCLUSION = 64;
+export const MAT_FLAG_EMISSIVE_MAP = 128;
+export const MAT_FLAG_ALPHA_MASK = 256;
+
+export function packMaterial(out, m, { hasMap = false, hasNormalMap = false, hasMrMap = false, hasOcclusionMap = false, hasEmissiveMap = false, doubleSided = false } = {}) {
+  out.fill(0);
+  out[0] = m.baseColor[0];
+  out[1] = m.baseColor[1];
+  out[2] = m.baseColor[2];
+  out[3] = m.alphaMode === 'opaque' ? 1 : m.opacity;
+  out[4] = m.emissive[0];
+  out[5] = m.emissive[1];
+  out[6] = m.emissive[2];
+  out[7] = m.normalScale;
+  out[8] = m.metallic;
+  out[9] = m.roughness;
+  out[10] =
+    (hasMap ? MAT_FLAG_MAP : 0) |
+    (hasNormalMap ? MAT_FLAG_NORMAL_MAP : 0) |
+    (doubleSided ? MAT_FLAG_DOUBLE_SIDED : 0) |
+    (m.unlit ? MAT_FLAG_UNLIT : 0) |
+    (hasMrMap ? MAT_FLAG_MR_MAP : 0) |
+    (hasOcclusionMap ? MAT_FLAG_OCCLUSION : 0) |
+    (hasEmissiveMap ? MAT_FLAG_EMISSIVE_MAP : 0) |
+    (m.alphaMode === 'mask' ? MAT_FLAG_ALPHA_MASK : 0);
+  out[11] = m.alphaCutoff ?? 0.5;
+  out[12] = m.uvScale[0];
+  out[13] = m.uvScale[1];
+  out[14] = m.occlusionStrength ?? 1;
+  return out;
+}
+
+/** Uniforms for debug line overlays (sRGB color, drawn unlit). */
+export function packOverlay(out, rgba) {
+  out.fill(0);
+  out[16] = rgba[0];
+  out[17] = rgba[1];
+  out[18] = rgba[2];
+  out[19] = rgba[3];
+  out[10] = MAT_FLAG_OVERLAY;
+  out[12] = 1;
+  out[13] = 1;
+  return out;
+}

package/src/render/orbit-controls.js

@@ -0,0 +1,237 @@
+// Mouse / touch camera controls: orbit (left drag), pan (right or middle drag,
+// or shift + left drag), zoom (wheel or pinch). Works for perspective and
+// orthographic cameras. A document's <controls> element (scene.controls) can
+// limit them and make the camera collide with the scene: see configure().
+
+import { constrainCamera } from '../scene/camera-constraints.js';
+
+export class OrbitControls {
+  /**
+   * @param {HTMLElement} element
+   * @param {import('./camera.js').Camera} camera
+   */
+  constructor(element, camera) {
+    this.el = element;
+    this.camera = camera;
+    this.enabled = true;
+    this.enableZoom = true;
+    this.enablePan = true;
+    this.limits = null; // scene.controls: distance, angle and target limits, collision
+    this.world = null; // () => ({scene, meshOf, isVisible}) for collision
+    this.rotateSpeed = 0.006;
+    this.zoomSpeed = 0.0015;
+    this.onChange = null;
+    this.onClick = null; // (x, y, event) for picking
+    this.onDoubleClick = null;
+    this.pointers = new Map();
+    this.mode = null;
+    this.moved = 0;
+    this.last = null;
+    this.pinch = null;
+
+    this._down = (e) => this.pointerDown(e);
+    this._move = (e) => this.pointerMove(e);
+    this._up = (e) => this.pointerUp(e);
+    this._wheel = (e) => this.wheel(e);
+    this._ctx = (e) => e.preventDefault();
+    this._dbl = (e) => {
+      if (this.onDoubleClick) {
+        const r = this.el.getBoundingClientRect();
+        this.onDoubleClick(e.clientX - r.left, e.clientY - r.top, e);
+      }
+    };
+    element.addEventListener('pointerdown', this._down);
+    element.addEventListener('pointermove', this._move);
+    element.addEventListener('pointerup', this._up);
+    element.addEventListener('pointercancel', this._up);
+    element.addEventListener('wheel', this._wheel, { passive: false });
+    element.addEventListener('contextmenu', this._ctx);
+    element.addEventListener('dblclick', this._dbl);
+    element.style.touchAction = 'none';
+  }
+
+  dispose() {
+    const el = this.el;
+    el.removeEventListener('pointerdown', this._down);
+    el.removeEventListener('pointermove', this._move);
+    el.removeEventListener('pointerup', this._up);
+    el.removeEventListener('pointercancel', this._up);
+    el.removeEventListener('wheel', this._wheel);
+    el.removeEventListener('contextmenu', this._ctx);
+    el.removeEventListener('dblclick', this._dbl);
+  }
+
+  /**
+   * Apply a document's <controls> (scene.controls, or null for free orbiting).
+   * @param {object|null} spec
+   * @param {{world?: () => object, ignoreMode?: boolean}} [opts] world supplies the
+   *   scene for collision; ignoreMode keeps dragging on (an editor previewing limits).
+   */
+  configure(spec, opts = {}) {
+    this.limits = spec;
+    if (opts.world) this.world = opts.world;
+    const mode = spec ? spec.mode : 'orbit';
+    this.enabled = opts.ignoreMode || mode === 'orbit';
+    this.enableZoom = !spec || spec.zoom !== false;
+    this.enablePan = !spec || spec.pan !== false;
+    // a canvas that does not orbit must let touch scrolling through to the page
+    this.el.style.touchAction = this.enabled ? 'none' : 'auto';
+  }
+
+  changed() {
+    if (this.onChange) this.onChange();
+  }
+
+  /** Camera state before a manipulation, for constrain(). */
+  snapshot() {
+    return { position: this.camera.position.slice(), target: this.camera.target.slice() };
+  }
+
+  /** Enforce limits and collision after a manipulation that started at `prev`. */
+  constrain(prev) {
+    if (!this.limits) return;
+    const world = this.limits.collide && this.world ? this.world() : null;
+    constrainCamera(prev, this.camera, this.limits, world);
+  }
+
+  pointerDown(e) {
+    if (!this.enabled) return;
+    this.el.setPointerCapture(e.pointerId);
+    this.pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    this.moved = 0;
+    if (this.pointers.size === 2) {
+      const [a, b] = [...this.pointers.values()];
+      this.pinch = { d: Math.hypot(a.x - b.x, a.y - b.y), cx: (a.x + b.x) / 2, cy: (a.y + b.y) / 2 };
+      this.mode = 'pinch';
+      return;
+    }
+    if (e.button === 2 || e.button === 1 || e.shiftKey || e.ctrlKey || e.metaKey) this.mode = 'pan';
+    else this.mode = 'orbit';
+    this.last = { x: e.clientX, y: e.clientY };
+  }
+
+  pointerMove(e) {
+    if (!this.enabled || !this.pointers.has(e.pointerId)) return;
+    this.pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    const prev = this.snapshot();
+    if (this.mode === 'pinch' && this.pointers.size >= 2) {
+      const [a, b] = [...this.pointers.values()];
+      const d = Math.hypot(a.x - b.x, a.y - b.y);
+      const cx = (a.x + b.x) / 2, cy = (a.y + b.y) / 2;
+      if (this.pinch.d > 0 && this.enableZoom) this.zoom(this.pinch.d / Math.max(d, 1));
+      if (this.enablePan) this.pan(cx - this.pinch.cx, cy - this.pinch.cy);
+      this.pinch = { d, cx, cy };
+      this.moved += 10;
+      this.constrain(prev);
+      this.changed();
+      return;
+    }
+    if (!this.last) return;
+    const dx = e.clientX - this.last.x;
+    const dy = e.clientY - this.last.y;
+    this.last = { x: e.clientX, y: e.clientY };
+    this.moved += Math.abs(dx) + Math.abs(dy);
+    if (this.mode === 'orbit') this.orbit(dx, dy);
+    else if (this.mode === 'pan' && this.enablePan) this.pan(dx, dy);
+    this.constrain(prev);
+    this.changed();
+  }
+
+  pointerUp(e) {
+    if (!this.pointers.has(e.pointerId)) return;
+    this.pointers.delete(e.pointerId);
+    try {
+      this.el.releasePointerCapture(e.pointerId);
+    } catch {
+      // pointer capture may already be released
+    }
+    if (this.pointers.size === 0) {
+      if (this.moved < 4 && this.onClick && e.button === 0) {
+        const r = this.el.getBoundingClientRect();
+        this.onClick(e.clientX - r.left, e.clientY - r.top, e);
+      }
+      this.mode = null;
+      this.last = null;
+      this.pinch = null;
+    } else if (this.pointers.size === 1) {
+      const p = [...this.pointers.values()][0];
+      this.mode = 'orbit';
+      this.last = { x: p.x, y: p.y };
+      this.pinch = null;
+    }
+  }
+
+  wheel(e) {
+    // without zoom the wheel scrolls the page
+    if (!this.enabled || !this.enableZoom) return;
+    e.preventDefault();
+    const delta = e.deltaMode === 1 ? e.deltaY * 33 : e.deltaMode === 2 ? e.deltaY * 400 : e.deltaY;
+    const prev = this.snapshot();
+    this.zoom(Math.exp(delta * this.zoomSpeed));
+    this.constrain(prev);
+    this.changed();
+  }
+
+  orbit(dx, dy) {
+    const c = this.camera;
+    const off = [c.position[0] - c.target[0], c.position[1] - c.target[1], c.position[2] - c.target[2]];
+    const r = Math.hypot(off[0], off[1], off[2]) || 1e-6;
+    let theta = Math.atan2(off[0], off[2]);
+    let phi = Math.acos(Math.max(-1, Math.min(1, off[1] / r)));
+    theta -= dx * this.rotateSpeed;
+    phi -= dy * this.rotateSpeed;
+    phi = Math.max(0.001, Math.min(Math.PI - 0.001, phi));
+    c.position = [
+      c.target[0] + r * Math.sin(phi) * Math.sin(theta),
+      c.target[1] + r * Math.cos(phi),
+      c.target[2] + r * Math.sin(phi) * Math.cos(theta),
+    ];
+    c.up = [0, 1, 0];
+  }
+
+  pan(dx, dy) {
+    const c = this.camera;
+    const h = this.el.clientHeight || 1;
+    const dist = c.distance;
+    const unitsPerPixel = c.type === 'orthographic' ? c.orthoHeight / h : (2 * dist * Math.tan(((c.fov / 2) * Math.PI) / 180)) / h;
+    // camera basis
+    const f = [c.target[0] - c.position[0], c.target[1] - c.position[1], c.target[2] - c.position[2]];
+    const fl = Math.hypot(...f) || 1;
+    f[0] /= fl; f[1] /= fl; f[2] /= fl;
+    let right = [f[1] * c.up[2] - f[2] * c.up[1], f[2] * c.up[0] - f[0] * c.up[2], f[0] * c.up[1] - f[1] * c.up[0]];
+    const rl = Math.hypot(...right) || 1;
+    right = right.map((v) => v / rl);
+    const up = [right[1] * f[2] - right[2] * f[1], right[2] * f[0] - right[0] * f[2], right[0] * f[1] - right[1] * f[0]];
+    const mx = -dx * unitsPerPixel, my = dy * unitsPerPixel;
+    for (let k = 0; k < 3; k++) {
+      const d = right[k] * mx + up[k] * my;
+      c.position[k] += d;
+      c.target[k] += d;
+    }
+  }
+
+  zoom(factor) {
+    const c = this.camera;
+    if (c.type === 'orthographic') {
+      c.orthoHeight = Math.max(1e-4, c.orthoHeight * factor);
+      return;
+    }
+    const off = [c.position[0] - c.target[0], c.position[1] - c.target[1], c.position[2] - c.target[2]];
+    const r = Math.hypot(...off);
+    const nr = Math.max(1e-4, r * factor);
+    for (let k = 0; k < 3; k++) c.position[k] = c.target[k] + (off[k] / (r || 1)) * nr;
+  }
+
+  /** Move the orbit centre to a point, keeping the viewing direction. */
+  focus(point) {
+    const c = this.camera;
+    const prev = this.snapshot();
+    const d = [point[0] - c.target[0], point[1] - c.target[1], point[2] - c.target[2]];
+    for (let k = 0; k < 3; k++) {
+      c.target[k] += d[k];
+      c.position[k] += d[k];
+    }
+    this.constrain(prev);
+    this.changed();
+  }
+}