trid3d 0.0.0-stage → 0.1.0

package/trid/render/draw.js

@@ -0,0 +1,146 @@
+import { localToWorld, worldToCamera, cameraToScreen, clipNear, DEFAULT_NEAR } from "../math/transform.js";
+
+/**
+ * Clears the entire canvas with a solid background color.
+ * This should usually be called once per frame before drawing.
+ *
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
+ * @param {number} w - Canvas width
+ * @param {number} h - Canvas height
+ * @param {string} color - Background color (CSS color)
+ */
+export function clear(ctx, w, h, color) {
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, w, h);
+}
+
+/**
+ * Draws a square point centered at a given 2D position.
+ * Useful for debugging or drawing vertices.
+ *
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
+ * @param {{x:number, y:number}} p - Screen-space point
+ * @param {string} color - Point color
+ * @param {number} size - Width/height of the square (default: 20)
+ */
+export function point(ctx, p, color, size = 20) {
+  ctx.fillStyle = color;
+  ctx.fillRect(
+    p.x - size / 2,
+    p.y - size / 2,
+    size,
+    size
+  );
+}
+
+/**
+ * Draws a straight line between two 2D screen-space points.
+ *
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
+ * @param {{x:number, y:number}} p1 - Start point
+ * @param {{x:number, y:number}} p2 - End point
+ * @param {string} color - Line color
+ * @param {number} width - Line thickness (default: 4)
+ */
+export function line(ctx, p1, p2, color, width = 4) {
+  ctx.lineWidth = width;
+  ctx.strokeStyle = color;
+
+  ctx.beginPath();
+  ctx.moveTo(p1.x, p1.y);
+  ctx.lineTo(p2.x, p2.y);
+  ctx.stroke();
+}
+
+/**
+ * Turns edge definitions into pairs of vertex indices.
+ *
+ * - An edge with 2 indices is a single segment: [a, b]
+ * - An edge with 3+ indices is a closed loop: the last index
+ *   connects back to the first
+ *
+ * @param {number[][]} edges - Edge definitions using vertex indices
+ * @returns {Generator<[number, number]>} Index pairs to connect
+ */
+export function* edgeSegments(edges) {
+  for (const e of edges) {
+    const closed = e.length > 2;
+    const count = closed ? e.length : e.length - 1;
+    for (let i = 0; i < count; i++) {
+      yield [e[i], e[(i + 1) % e.length]];
+    }
+  }
+}
+
+/**
+ * Draws a wireframe object by connecting projected vertices
+ * using index-based edge definitions.
+ *
+ * Each edge is defined as an array of vertex indices.
+ * A 2-index edge is a single segment; with 3 or more indices,
+ * consecutive indices are connected and the last index
+ * connects back to the first (closed loop).
+ *
+ * This function assumes:
+ * - `points2` indices match the original vertex order
+ * - All points are already in screen space
+ *
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
+ * @param {{x:number, y:number}[]} points2 - 2D screen-space points
+ * @param {number[][]} edges - Edge definitions using vertex indices
+ * All segments go into one path and are stroked once.
+ *
+ * @param {string} color - Stroke color
+ * @param {number} width - Line thickness (default: 4)
+ */
+export function drawWireframe(ctx, points2, edges, color, width = 4) {
+  ctx.lineWidth = width;
+  ctx.strokeStyle = color;
+
+  ctx.beginPath();
+  for (const [i, j] of edgeSegments(edges)) {
+    ctx.moveTo(points2[i].x, points2[i].y);
+    ctx.lineTo(points2[j].x, points2[j].y);
+  }
+  ctx.stroke();
+}
+
+/**
+ * Draws a mesh instance by applying its transform and rendering
+ * its wireframe representation.
+ *
+ * Segments are clipped against the camera's near plane, so parts
+ * of the mesh behind the camera are not drawn. All segments go
+ * into one path and are stroked once.
+ *
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context
+ * @param {{
+ *   mesh:{ vertices:{x:number,y:number,z:number}[], edges:number[][] },
+ *   pos:{x:number,y:number,z:number},
+ *   rot:{x:number,y:number,z:number},
+ *   scale:{x:number,y:number,z:number}
+ * }} inst - Mesh instance
+ * @param {import("../math/transform.js").Camera} camera - Camera settings
+ * @param {number} w - Canvas width
+ * @param {number} h - Canvas height
+ * @param {string} color - Wireframe color
+ * @param {number} lineWidth - Wireframe width
+ */
+export function drawInstance(ctx, inst, camera, w, h, color, lineWidth = 3) {
+  const near = camera.near ?? DEFAULT_NEAR;
+  const ptsCam = inst.mesh.vertices.map(v => worldToCamera(localToWorld(v, inst), camera));
+
+  ctx.lineWidth = lineWidth;
+  ctx.strokeStyle = color;
+
+  ctx.beginPath();
+  for (const [i, j] of edgeSegments(inst.mesh.edges)) {
+    const seg = clipNear(ptsCam[i], ptsCam[j], near);
+    if (!seg) continue;
+    const a = cameraToScreen(seg[0], camera, w, h);
+    const b = cameraToScreen(seg[1], camera, w, h);
+    ctx.moveTo(a.x, a.y);
+    ctx.lineTo(b.x, b.y);
+  }
+  ctx.stroke();
+}

package/trid/render/effects.js

@@ -0,0 +1,265 @@
+/**
+ * Effects: small shaders that change how a material looks.
+ *
+ * A material can have a list of them, applied in order. Each one gets
+ * the color so far and the `Surface` being drawn, and returns a new color:
+ *
+ *   material: { fill: "#8ab4f8", effects: [toon({ steps: 3 }), rim()] }
+ *
+ * An effect is a plain object:
+ * - `glsl`: GLSL code defining `vec4 effect(vec4 color, Surface s)` (WebGL renderer)
+ * - `canvas`: optional `(color, s, uniforms) => color` run once per face
+ *   by the canvas renderer; colors are [r, g, b, a] from 0 to 1
+ * - `uniforms`: optional settings used by the code, like `{ uPower: 2 }`.
+ *   Change them at any time; they're read every frame.
+ *   Numbers are `float`, [x, y] / [x, y, z] / [x, y, z, w] are `vec2..4`,
+ *   CSS color strings are `vec4` colors, `true` / `false` are `float` 1 / 0.
+ *
+ * The built-in effects below are written exactly that way.
+ */
+
+/**
+ * What an effect knows about the point being drawn. GLSL fields and
+ * the canvas renderer's `s` object have the same names.
+ *
+ * @typedef {Object} Surface
+ * @property {number[]} base - The material's fill color [r, g, b, a], times the texture's color
+ * @property {{u,v}} uv - Texture coordinates (0, 0 when the mesh has none)
+ * @property {{x,y,z}} normal - Unit normal, in world space, facing the camera's side
+ * @property {{x,y,z}} position - World position
+ * @property {{x,y,z}} local - Position in the mesh's own space
+ * @property {{x,y,z}} view - Unit direction from the point to the camera
+ * @property {{x,y,z}} lightDir - Unit direction light comes from
+ * @property {number} diffuse - How much the point faces the light (0..1)
+ * @property {number} light - Brightness Trid used: ambient + (1 - ambient) × diffuse
+ * @property {number} ambient - The scene's ambient level
+ * @property {number} depth - Distance to the camera
+ * @property {number} time - Seconds since the renderer started
+ * @property {number[]} background - The scene's background color [r, g, b, a]
+ */
+
+/** The GLSL declaration of `Surface`, shared by every effect. */
+export const SURFACE_GLSL = `
+struct Surface {
+  vec4 base;
+  vec2 uv;
+  vec3 normal;
+  vec3 position;
+  vec3 local;
+  vec3 view;
+  vec3 lightDir;
+  float diffuse;
+  float light;
+  float ambient;
+  float depth;
+  float time;
+  vec4 background;
+};
+`;
+
+/**
+ * Cartoon look: the light comes in a few hard steps instead of a smooth fade.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.steps=3] - Number of brightness levels
+ */
+export function toon({ steps = 3 } = {}) {
+  return {
+    name: "toon",
+    uniforms: { uSteps: steps },
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  float level = min(floor(s.diffuse * uSteps), uSteps - 1.0) / max(uSteps - 1.0, 1.0);
+  float b = s.ambient + (1.0 - s.ambient) * level;
+  return vec4(s.base.rgb * b, color.a);
+}`,
+    canvas: (color, s, u) => {
+      const level = Math.min(Math.floor(s.diffuse * u.uSteps), u.uSteps - 1) / Math.max(u.uSteps - 1, 1);
+      const b = s.ambient + (1 - s.ambient) * level;
+      return [s.base[0] * b, s.base[1] * b, s.base[2] * b, color[3]];
+    },
+  };
+}
+
+/**
+ * A glow along the edges, where the surface turns away from the camera.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.color="#ffffff"] - Glow color
+ * @param {number} [opts.power=2] - Higher = thinner glow
+ * @param {number} [opts.strength=1] - How bright the glow is
+ */
+export function rim({ color = "#ffffff", power = 2, strength = 1 } = {}) {
+  return {
+    name: "rim",
+    uniforms: { uRimColor: color, uPower: power, uStrength: strength },
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  float edge = pow(1.0 - max(0.0, dot(s.normal, s.view)), uPower) * uStrength;
+  return vec4(color.rgb + uRimColor.rgb * edge, color.a);
+}`,
+    canvas: (c, s, u) => {
+      const n = s.normal, v = s.view;
+      const edge = Math.pow(1 - Math.max(0, n.x * v.x + n.y * v.y + n.z * v.z), u.uPower) * u.uStrength;
+      const r = s.rgba(u.uRimColor);
+      return [c[0] + r[0] * edge, c[1] + r[1] * edge, c[2] + r[2] * edge, c[3]];
+    },
+  };
+}
+
+/**
+ * A glow along the border of each face, using the texture coordinates
+ * (0 and 1 are a face's edges). Made for boxy shapes, where `rim` barely
+ * shows. Needs texture coordinates: built-in shapes have them.
+ *
+ * WebGL only: the canvas renderer runs effects once per face, at its center,
+ * which is never near a border.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.color="#ffe08a"] - Glow color
+ * @param {number} [opts.width=0.08] - Thickness, as a fraction of the face (0.08 = 8%)
+ * @param {number} [opts.strength=1] - How bright the glow is
+ */
+export function edgeGlow({ color = "#ffe08a", width = 0.08, strength = 1 } = {}) {
+  return {
+    name: "edgeGlow",
+    uniforms: { uGlowColor: color, uWidth: width, uStrength: strength },
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  vec2 d = min(fract(s.uv), 1.0 - fract(s.uv)); // distance to the nearest face border
+  float edge = 1.0 - smoothstep(0.0, uWidth, min(d.x, d.y));
+  return vec4(color.rgb + uGlowColor.rgb * edge * uStrength, color.a);
+}`,
+  };
+}
+
+/** Ignores the light: the object shows its fill color everywhere, like it glows. */
+export function unlit() {
+  return {
+    name: "unlit",
+    uniforms: {},
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  return s.base;
+}`,
+    canvas: (color, s) => s.base.slice(),
+  };
+}
+
+/**
+ * Color that changes along an axis, like a sky or terrain by height.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.from="#E9806E"] - Color at `min`
+ * @param {string} [opts.to="#8ab4f8"] - Color at `max`
+ * @param {"x"|"y"|"z"} [opts.axis="y"] - Direction of the change
+ * @param {number} [opts.min=-0.5] - Where `from` is fully reached
+ * @param {number} [opts.max=0.5] - Where `to` is fully reached
+ * @param {"local"|"world"} [opts.space="local"] - Measure in the mesh's own space (moves with it) or in the world
+ * @param {boolean} [opts.lit=true] - Keep the shading from the light
+ */
+export function gradient({
+  from = "#E9806E", to = "#8ab4f8", axis = "y", min = -0.5, max = 0.5, space = "local", lit = true,
+} = {}) {
+  const k = { x: 0, y: 1, z: 2 }[axis] ?? 1;
+  const p = space === "world" ? "position" : "local";
+  return {
+    name: "gradient",
+    uniforms: { uFrom: from, uTo: to, uMin: min, uMax: max, uLit: lit },
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  float t = clamp((s.${p}[${k}] - uMin) / (uMax - uMin), 0.0, 1.0);
+  vec3 c = mix(uFrom.rgb, uTo.rgb, t);
+  return vec4(c * mix(1.0, s.light, uLit), color.a);
+}`,
+    canvas: (color, s, u) => {
+      const v = s[p][axis] ?? s[p].y;
+      const t = Math.min(1, Math.max(0, (v - u.uMin) / (u.uMax - u.uMin)));
+      const a = s.rgba(u.uFrom), b = s.rgba(u.uTo);
+      const l = u.uLit ? s.light : 1;
+      return [0, 1, 2].map((i) => (a[i] + (b[i] - a[i]) * t) * l).concat(color[3]);
+    },
+  };
+}
+
+/**
+ * Fades objects into a color with distance.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.near=1] - Distance where the fog starts
+ * @param {number} [opts.far=5] - Distance where it's fully fog
+ * @param {string} [opts.color] - Fog color (default: the scene's background)
+ */
+export function fog({ near = 1, far = 5, color } = {}) {
+  return {
+    name: "fog",
+    uniforms: { uNearFog: near, uFarFog: far, uFogColor: color ?? "#000000", uOwnColor: color != null },
+    glsl: `
+vec4 effect(vec4 color, Surface s) {
+  float t = smoothstep(uNearFog, uFarFog, s.depth);
+  vec3 c = mix(s.background.rgb, uFogColor.rgb, uOwnColor);
+  return vec4(mix(color.rgb, c, t), color.a);
+}`,
+    canvas: (color, s, u) => {
+      let t = Math.min(1, Math.max(0, (s.depth - u.uNearFog) / (u.uFarFog - u.uNearFog)));
+      t = t * t * (3 - 2 * t);
+      const c = u.uOwnColor ? s.rgba(u.uFogColor) : s.background;
+      return [0, 1, 2].map((i) => color[i] + (c[i] - color[i]) * t).concat(color[3]);
+    },
+  };
+}
+
+// --- Used by the renderers ---
+
+/** GLSL type of a uniform value, or null if it can't be one. */
+export function uniformType(value) {
+  if (typeof value === "number" || typeof value === "boolean") return "float";
+  if (typeof value === "string") return "vec4";
+  if (Array.isArray(value) && value.length >= 2 && value.length <= 4) return "vec" + value.length;
+  if (value && typeof value === "object" && "x" in value) return "vec3";
+  return null;
+}
+
+/**
+ * Joins a material's effects into GLSL. Each effect's `effect` function,
+ * helper functions and uniforms get a numbered suffix, so the same effect
+ * can be used twice and two effects can use the same names.
+ *
+ * @param {Object[]} effects
+ * @returns {{ code:string, calls:string, uniforms:{ effect:number, name:string, glslName:string, type:string }[] }}
+ */
+export function buildEffects(effects) {
+  let code = "";
+  let calls = "";
+  const uniforms = [];
+
+  effects.forEach((e, i) => {
+    let src = e.glsl ?? "vec4 effect(vec4 color, Surface s) { return color; }";
+    const rename = new Map();
+
+    for (const [name, value] of Object.entries(e.uniforms ?? {})) {
+      const type = uniformType(value);
+      if (!type) continue;
+      rename.set(name, `${name}_${i}`);
+      uniforms.push({ effect: i, name, glslName: `${name}_${i}`, type });
+    }
+    // Every function the effect defines, including `effect` itself
+    const fn = /(?:^|[\s;}])(?:void|float|int|bool|vec[234]|mat[234]|Surface)\s+([A-Za-z_]\w*)\s*\(/g;
+    for (const m of src.matchAll(fn)) rename.set(m[1], `${m[1]}_${i}`);
+
+    for (const [from, to] of rename) src = src.replace(new RegExp(`\\b${from}\\b`, "g"), to);
+
+    const decls = uniforms.filter((u) => u.effect === i).map((u) => `uniform ${u.type} ${u.glslName};`).join("\n");
+    code += `\n// Effect ${i}${e.name ? ": " + e.name : ""}\n${decls}\n${src}\n`;
+    calls += `  color = effect_${i}(color, s);\n`;
+  });
+
+  return { code, calls, uniforms };
+}
+
+/** A key that's the same for effect lists that compile to the same shader. */
+export function effectsKey(effects) {
+  return effects
+    .map((e) => (e.glsl ?? "") + "|" + Object.entries(e.uniforms ?? {}).map(([k, v]) => k + ":" + uniformType(v)).join(","))
+    .join("\n");
+}

package/trid/render/loop.js

@@ -0,0 +1,42 @@
+/**
+ * Runs a callback every animation frame using requestAnimationFrame.
+ *
+ * The callback receives:
+ * - `dt`: seconds since the previous frame (0 on the first frame),
+ *   capped at `maxDt` so a hidden tab doesn't cause a big jump
+ * - `time`: seconds since the loop started
+ *
+ * Typical usage:
+ *   const stop = loop((dt) => { ... });
+ *   stop(); // later, to end the loop
+ *
+ * @param {(dt:number, time:number) => void} update - Called once per frame
+ * @param {Object} [opts]
+ * @param {number} [opts.maxDt=0.1] - Largest dt passed to `update`, in seconds
+ * @returns {() => void} Function that stops the loop
+ */
+export function loop(update, { maxDt = 0.1 } = {}) {
+  let running = true;
+  let id = 0;
+  let start = null;
+  let last = null;
+
+  function frame(now) {
+    if (!running) return;
+
+    if (start === null) start = last = now;
+    const dt = Math.min(Math.max(now - last, 0) / 1000, maxDt);
+    last = now;
+
+    update(dt, (now - start) / 1000);
+
+    if (running) id = requestAnimationFrame(frame);
+  }
+
+  id = requestAnimationFrame(frame);
+
+  return function stop() {
+    running = false;
+    cancelAnimationFrame(id);
+  };
+}

package/trid/render/normals.js

@@ -0,0 +1,90 @@
+/** Faces meeting at a sharper angle than this (degrees) keep a hard edge with `smooth: true`. */
+export const DEFAULT_CREASE = 60;
+
+const cache = new WeakMap();
+
+/**
+ * Normals at each corner of each face, for smooth shading.
+ *
+ * A corner's normal is the average of the faces around its vertex
+ * (bigger faces count more), skipping faces that meet this one at a
+ * sharper angle than `crease`. So a sphere looks round while a cube
+ * keeps its sharp edges.
+ *
+ * When the mesh has its own normals (`mesh.normals` and
+ * `mesh.faceNormals`, as loaded from an OBJ file), those are used
+ * for the faces that have them.
+ *
+ * The result is cached per mesh until its arrays are replaced,
+ * resized, or `mesh.dirty` is set.
+ *
+ * @param {{ vertices:{x:number,y:number,z:number}[], faces?:number[][],
+ *   normals?:{x:number,y:number,z:number}[], faceNormals?:(number[]|null)[] }} mesh
+ * @param {number} [crease=60] - Angle in degrees
+ * @returns {{x:number,y:number,z:number}[][]} For each face, one unit normal per corner
+ */
+export function cornerNormals(mesh, crease = DEFAULT_CREASE) {
+  const faces = mesh.faces ?? [];
+  const key = `${crease}/${mesh.vertices.length}/${faces.length}`;
+  const hit = cache.get(mesh);
+  if (hit && !mesh.dirty && hit.key === key && hit.vertices === mesh.vertices && hit.faces === faces) {
+    return hit.result;
+  }
+
+  const v = mesh.vertices;
+  const raw = faces.map((f) => (f.length >= 3 ? newell(f.map((i) => v[i])) : { x: 0, y: 0, z: 0 }));
+  const unit = raw.map(normalize);
+
+  // Faces touching each vertex
+  const around = v.map(() => []);
+  faces.forEach((f, k) => {
+    for (const i of f) around[i].push(k);
+  });
+
+  const minDot = Math.cos((crease * Math.PI) / 180) - 1e-6;
+  const result = faces.map((f, k) => {
+    const own = mesh.faceNormals?.[k];
+    if (own && mesh.normals) return own.map((n) => normalize(mesh.normals[n]));
+
+    const u = unit[k];
+    return f.map((i) => {
+      let x = 0, y = 0, z = 0;
+      for (const g of around[i]) {
+        const w = unit[g];
+        if (u.x * w.x + u.y * w.y + u.z * w.z < minDot) continue;
+        x += raw[g].x; y += raw[g].y; z += raw[g].z;
+      }
+      return normalize({ x, y, z });
+    });
+  });
+
+  cache.set(mesh, { key, vertices: mesh.vertices, faces, result });
+  return result;
+}
+
+/** The `smooth` material setting as a crease angle, or null for flat shading. */
+export function creaseOf(smooth) {
+  if (smooth === true) return DEFAULT_CREASE;
+  if (typeof smooth === "number" && smooth > 0) return smooth;
+  return null;
+}
+
+/**
+ * Normal of a polygon (Newell's method, works for any number of points).
+ * Points clockwise as seen from a side give a normal pointing to that side.
+ */
+export function newell(pts) {
+  let x = 0, y = 0, z = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const a = pts[i], b = pts[(i + 1) % pts.length];
+    x += (a.y - b.y) * (a.z + b.z);
+    y += (a.z - b.z) * (a.x + b.x);
+    z += (a.x - b.x) * (a.y + b.y);
+  }
+  return { x, y, z };
+}
+
+function normalize(p) {
+  const len = Math.hypot(p.x, p.y, p.z) || 1;
+  return { x: p.x / len, y: p.y / len, z: p.z / len };
+}