3d-spinner 0.9.0

package/dist/engines/little-3d-engine/little-3d-engine.js

@@ -0,0 +1,167 @@
+import { Camera } from "./core/camera.js";
+import { Light } from "./core/light.js";
+import { multiply, rotationX, rotationY, rotationZ, scaleMatrix, translation, } from "./core/math.js";
+import { transform as makeTransform } from "./core/mesh.js";
+import { createRenderer } from "./renderer.js";
+function modelMatrix(t) {
+    const rotation = multiply(rotationZ(t.rotation.z), multiply(rotationY(t.rotation.y), rotationX(t.rotation.x)));
+    return multiply(translation(t.position.x, t.position.y, t.position.z), multiply(rotation, scaleMatrix(t.scale)));
+}
+/**
+ * A minimal software/hardware 3D engine. It projects colored meshes with flat
+ * directional lighting through a swappable {@link Backend} renderer. Mount it
+ * into any element to render in a component, or into a transparent positioned
+ * element to overlay a page.
+ */
+export class Little3dEngine {
+    constructor(options = {}) {
+        this.scene = [];
+        this.cssWidth = 0;
+        this.cssHeight = 0;
+        this.ready = false;
+        this.generation = 0;
+        this.rafId = 0;
+        this.running = false;
+        this.camera = new Camera(options.camera);
+        this.light = new Light(options.light);
+        this.backend = options.backend ?? "canvas2d";
+        this.background = options.background;
+    }
+    /**
+     * Create the canvas inside `target`, load the selected backend, and start
+     * tracking size. Resolves once the renderer is ready; rejects if the backend
+     * is unavailable. Drawing is a no-op until it resolves.
+     */
+    async mount(target) {
+        const canvas = document.createElement("canvas");
+        canvas.style.display = "block";
+        canvas.style.width = "100%";
+        canvas.style.height = "100%";
+        target.appendChild(canvas);
+        this.canvas = canvas;
+        this.observer = new ResizeObserver(() => this.resize());
+        this.observer.observe(canvas);
+        this.resize();
+        const generation = this.generation;
+        const dropCanvas = () => {
+            if (this.canvas !== canvas)
+                return;
+            this.observer?.disconnect();
+            this.observer = undefined;
+            canvas.remove();
+            this.canvas = undefined;
+        };
+        try {
+            const renderer = await createRenderer(this.backend, { background: this.background });
+            if (generation !== this.generation) {
+                renderer.destroy();
+                dropCanvas();
+                return;
+            }
+            await renderer.init(canvas);
+            if (generation !== this.generation) {
+                renderer.destroy();
+                dropCanvas();
+                return;
+            }
+            this.renderer = renderer;
+            this.resize();
+            this.ready = true;
+        }
+        catch (error) {
+            dropCanvas();
+            throw error;
+        }
+    }
+    /** Add a mesh to the scene and return a handle for animating it. */
+    add(mesh, init) {
+        const entry = { mesh, transform: makeTransform(init) };
+        this.scene.push(entry);
+        return {
+            mesh,
+            transform: entry.transform,
+            remove: () => {
+                const i = this.scene.indexOf(entry);
+                if (i >= 0)
+                    this.scene.splice(i, 1);
+            },
+        };
+    }
+    resize() {
+        const canvas = this.canvas;
+        if (!canvas)
+            return;
+        const dpr = window.devicePixelRatio || 1;
+        this.cssWidth = canvas.clientWidth || canvas.parentElement?.clientWidth || 0;
+        this.cssHeight = canvas.clientHeight || canvas.parentElement?.clientHeight || 0;
+        canvas.width = Math.max(1, Math.round(this.cssWidth * dpr));
+        canvas.height = Math.max(1, Math.round(this.cssHeight * dpr));
+        this.renderer?.resize(this.cssWidth, this.cssHeight, dpr);
+    }
+    /** Draw a single frame from the current scene state. */
+    render() {
+        if (!this.ready || !this.renderer)
+            return;
+        const width = this.cssWidth;
+        const height = this.cssHeight;
+        if (width === 0 || height === 0)
+            return;
+        const items = this.scene.map((entry) => ({
+            mesh: entry.mesh,
+            model: modelMatrix(entry.transform),
+        }));
+        this.renderer.render({
+            items,
+            viewProjection: this.camera.viewProjection(width / height),
+            eye: this.camera.options.position,
+            light: this.light.params,
+            width,
+            height,
+        });
+    }
+    /** Start an internal animation loop that calls {@link render} each frame. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const loop = () => {
+            if (!this.running)
+                return;
+            this.render();
+            this.rafId = requestAnimationFrame(loop);
+        };
+        this.rafId = requestAnimationFrame(loop);
+    }
+    /** Stop the internal animation loop started by {@link start}. */
+    stop() {
+        this.running = false;
+        if (this.rafId)
+            cancelAnimationFrame(this.rafId);
+        this.rafId = 0;
+    }
+    /** Stop animating, release the renderer, and remove the canvas. */
+    destroy() {
+        this.generation++;
+        this.ready = false;
+        this.stop();
+        this.observer?.disconnect();
+        this.observer = undefined;
+        this.renderer?.destroy();
+        this.renderer = undefined;
+        this.canvas?.remove();
+        this.canvas = undefined;
+    }
+}
+export { Camera } from "./core/camera.js";
+export { Light } from "./core/light.js";
+export { cube } from "./shapes/cube.js";
+export { tetrahedron } from "./shapes/tetrahedron.js";
+export { octahedron } from "./shapes/octahedron.js";
+export { pyramid } from "./shapes/pyramid.js";
+export { uvSphere } from "./shapes/uv-sphere.js";
+export { icosphere } from "./shapes/icosphere.js";
+export { octaSphere } from "./shapes/octa-sphere.js";
+export { cubeSphere } from "./shapes/cube-sphere.js";
+export { expandToTriangles } from "./core/geometry.js";
+export { transform } from "./core/mesh.js";
+export { vec3, subtract, cross, dot, scale, normalize, } from "./core/math.js";

package/dist/engines/little-3d-engine/loaders/obj.d.ts

@@ -0,0 +1,24 @@
+import type { Mesh } from "../core/mesh.js";
+/** Options for {@link parseObj}. */
+export interface ObjOptions {
+    /**
+     * CSS colors assigned to faces in order, cycling when there are more faces
+     * than colors. Defaults to a built-in palette. Pass a single-entry array for
+     * a uniform color.
+     */
+    colors?: string[];
+}
+/**
+ * Parse Wavefront OBJ text into a {@link Mesh}.
+ *
+ * Reads `v` vertex positions and `f` faces (triangles, quads, or n-gons, in
+ * `v`, `v/vt`, `v/vt/vn`, or `v//vn` form, with 1-based or negative indices).
+ * Normals (`vn`) and texture coordinates (`vt`) are ignored - the engine
+ * computes a flat normal per face - as are groups, materials, and other
+ * statements. Face winding is preserved, so models should be wound CCW as seen
+ * from outside for correct backface culling and shading.
+ *
+ * @param text Contents of an `.obj` file.
+ * @param options Color palette to apply to the faces.
+ */
+export declare function parseObj(text: string, options?: ObjOptions): Mesh;

package/dist/engines/little-3d-engine/loaders/obj.js

@@ -0,0 +1,48 @@
+const DEFAULT_COLORS = ["#3b82f6", "#8b5cf6", "#ec4899", "#f59e0b", "#10b981", "#ef4444"];
+function resolveIndex(token, vertexCount) {
+    const n = parseInt(token, 10);
+    return n < 0 ? vertexCount + n : n - 1;
+}
+/**
+ * Parse Wavefront OBJ text into a {@link Mesh}.
+ *
+ * Reads `v` vertex positions and `f` faces (triangles, quads, or n-gons, in
+ * `v`, `v/vt`, `v/vt/vn`, or `v//vn` form, with 1-based or negative indices).
+ * Normals (`vn`) and texture coordinates (`vt`) are ignored - the engine
+ * computes a flat normal per face - as are groups, materials, and other
+ * statements. Face winding is preserved, so models should be wound CCW as seen
+ * from outside for correct backface culling and shading.
+ *
+ * @param text Contents of an `.obj` file.
+ * @param options Color palette to apply to the faces.
+ */
+export function parseObj(text, options = {}) {
+    const colors = options.colors ?? DEFAULT_COLORS;
+    const vertices = [];
+    const faces = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const parts = trimmed.split(/\s+/);
+        const keyword = parts[0];
+        if (keyword === "v") {
+            vertices.push({
+                x: parseFloat(parts[1]),
+                y: parseFloat(parts[2]),
+                z: parseFloat(parts[3]),
+            });
+        }
+        else if (keyword === "f") {
+            const indices = [];
+            for (let i = 1; i < parts.length; i++) {
+                const vertexToken = parts[i].split("/")[0];
+                indices.push(resolveIndex(vertexToken, vertices.length));
+            }
+            if (indices.length >= 3) {
+                faces.push({ indices, color: colors[faces.length % colors.length] });
+            }
+        }
+    }
+    return { vertices, faces };
+}

package/dist/engines/little-3d-engine/renderer.d.ts

@@ -0,0 +1,43 @@
+import type { LightParams } from "./core/light.js";
+import type { Mat4, Vec3 } from "./core/math.js";
+import type { Mesh } from "./core/mesh.js";
+/** Rendering backend. Each is loaded on demand; unused ones are never fetched. */
+export type Backend = "canvas2d" | "webgl" | "webgpu";
+/** A mesh plus its world transform, ready to draw. */
+export interface RenderItem {
+    mesh: Mesh;
+    model: Mat4;
+}
+/** Everything a renderer needs to draw one frame. */
+export interface RenderFrame {
+    items: ReadonlyArray<RenderItem>;
+    /** Combined view-projection (OpenGL clip space, z in -1..1). */
+    viewProjection: Mat4;
+    /** Camera position, for backface culling. */
+    eye: Vec3;
+    light: LightParams;
+    /** Logical (CSS pixel) viewport size. */
+    width: number;
+    height: number;
+}
+/** Construction-time options shared by all backends. */
+export interface RendererOptions {
+    /** Solid background; omit for a transparent canvas (overlay use). */
+    background?: string;
+}
+/**
+ * A pluggable drawing backend. The engine owns the canvas and sizing; a
+ * renderer only initializes its context, reacts to resizes, and draws frames.
+ */
+export interface Renderer {
+    init(canvas: HTMLCanvasElement): void | Promise<void>;
+    resize(cssWidth: number, cssHeight: number, dpr: number): void;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}
+/**
+ * Load and construct a renderer for `backend`. Each backend lives in its own
+ * module and is pulled in with a dynamic `import()`, so the bytes for the
+ * backends you do not use are never downloaded or compiled.
+ */
+export declare function createRenderer(backend: Backend, options?: RendererOptions): Promise<Renderer>;

package/dist/engines/little-3d-engine/renderer.js

@@ -0,0 +1,16 @@
+/**
+ * Load and construct a renderer for `backend`. Each backend lives in its own
+ * module and is pulled in with a dynamic `import()`, so the bytes for the
+ * backends you do not use are never downloaded or compiled.
+ */
+export async function createRenderer(backend, options = {}) {
+    switch (backend) {
+        case "webgl":
+            return new (await import("./renderers/webgl.js")).WebGLRenderer(options);
+        case "webgpu":
+            return new (await import("./renderers/webgpu.js")).WebGPURenderer(options);
+        case "canvas2d":
+        default:
+            return new (await import("./renderers/canvas2d.js")).Canvas2DRenderer(options);
+    }
+}

package/dist/engines/little-3d-engine/renderers/canvas2d.d.ts

@@ -0,0 +1,12 @@
+import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+/** Software renderer: projects geometry on the CPU and fills 2D polygons. */
+export declare class Canvas2DRenderer implements Renderer {
+    private readonly options;
+    private ctx?;
+    private dpr;
+    constructor(options?: RendererOptions);
+    init(canvas: HTMLCanvasElement): void;
+    resize(_cssWidth: number, _cssHeight: number, dpr: number): void;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}

package/dist/engines/little-3d-engine/renderers/canvas2d.js

@@ -0,0 +1,73 @@
+import { shadeColor } from "../core/light.js";
+import { dot, cross, normalize, subtract, transformAffine, transformPoint } from "../core/math.js";
+/** Software renderer: projects geometry on the CPU and fills 2D polygons. */
+export class Canvas2DRenderer {
+    constructor(options = {}) {
+        this.options = options;
+        this.dpr = 1;
+    }
+    init(canvas) {
+        this.ctx = canvas.getContext("2d") ?? undefined;
+    }
+    resize(_cssWidth, _cssHeight, dpr) {
+        this.dpr = dpr;
+        this.ctx?.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }
+    render(frame) {
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        if (this.options.background) {
+            ctx.fillStyle = this.options.background;
+            ctx.fillRect(0, 0, frame.width, frame.height);
+        }
+        else {
+            ctx.clearRect(0, 0, frame.width, frame.height);
+        }
+        const polygons = [];
+        for (const item of frame.items) {
+            const world = item.mesh.vertices.map((v) => transformAffine(item.model, v));
+            for (const face of item.mesh.faces) {
+                const a = world[face.indices[0]];
+                const b = world[face.indices[1]];
+                const c = world[face.indices[2]];
+                const normal = normalize(cross(subtract(b, a), subtract(c, a)));
+                if (dot(normal, subtract(frame.eye, a)) <= 0)
+                    continue;
+                const points = face.indices.map((i) => {
+                    const ndc = transformPoint(frame.viewProjection, world[i]);
+                    return {
+                        x: (ndc.x * 0.5 + 0.5) * frame.width,
+                        y: (1 - (ndc.y * 0.5 + 0.5)) * frame.height,
+                    };
+                });
+                let depth = 0;
+                for (const i of face.indices) {
+                    const d = subtract(world[i], frame.eye);
+                    depth += dot(d, d);
+                }
+                depth /= face.indices.length;
+                polygons.push({ points, color: shadeColor(normal, face.color, frame.light), depth });
+            }
+        }
+        polygons.sort((p, q) => q.depth - p.depth);
+        for (const poly of polygons) {
+            if (poly.points.length < 3)
+                continue;
+            ctx.beginPath();
+            ctx.moveTo(poly.points[0].x, poly.points[0].y);
+            for (let i = 1; i < poly.points.length; i++) {
+                ctx.lineTo(poly.points[i].x, poly.points[i].y);
+            }
+            ctx.closePath();
+            ctx.fillStyle = poly.color;
+            ctx.strokeStyle = poly.color;
+            ctx.lineWidth = 1;
+            ctx.fill();
+            ctx.stroke();
+        }
+    }
+    destroy() {
+        this.ctx = undefined;
+    }
+}

package/dist/engines/little-3d-engine/renderers/webgl.d.ts

@@ -0,0 +1,15 @@
+import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+/** Hardware renderer using WebGL2: GPU transforms with a real depth buffer. */
+export declare class WebGLRenderer implements Renderer {
+    private gl?;
+    private program?;
+    private locations?;
+    private readonly cache;
+    private readonly clearColor;
+    constructor(options?: RendererOptions);
+    init(canvas: HTMLCanvasElement): void;
+    resize(): void;
+    private buffers;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}

package/dist/engines/little-3d-engine/renderers/webgl.js

@@ -0,0 +1,146 @@
+import { expandToTriangles, parseColor } from "../core/geometry.js";
+const VERTEX_SHADER = `#version 300 es
+in vec3 aPos;
+in vec3 aNormal;
+in vec3 aColor;
+uniform mat4 uViewProj;
+uniform mat4 uModel;
+out vec3 vNormal;
+out vec3 vColor;
+void main() {
+  vNormal = mat3(uModel) * aNormal;
+  vColor = aColor;
+  gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+}`;
+const FRAGMENT_SHADER = `#version 300 es
+precision mediump float;
+in vec3 vNormal;
+in vec3 vColor;
+uniform vec3 uToLight;
+uniform float uIntensity;
+uniform float uAmbient;
+out vec4 fragColor;
+void main() {
+  float lambert = max(dot(normalize(vNormal), normalize(uToLight)), 0.0);
+  float brightness = clamp(uAmbient + uIntensity * lambert, 0.0, 1.0);
+  fragColor = vec4(vColor * brightness, 1.0);
+}`;
+function compile(gl, type, source) {
+    const shader = gl.createShader(type);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        throw new Error(`3d-spinner: shader compile failed: ${gl.getShaderInfoLog(shader)}`);
+    }
+    return shader;
+}
+function link(gl) {
+    const program = gl.createProgram();
+    gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER));
+    gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER));
+    gl.linkProgram(program);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        throw new Error(`3d-spinner: program link failed: ${gl.getProgramInfoLog(program)}`);
+    }
+    return program;
+}
+/** Hardware renderer using WebGL2: GPU transforms with a real depth buffer. */
+export class WebGLRenderer {
+    constructor(options = {}) {
+        this.cache = new Map();
+        if (options.background) {
+            const [r, g, b] = parseColor(options.background);
+            this.clearColor = [r / 255, g / 255, b / 255, 1];
+        }
+        else {
+            this.clearColor = [0, 0, 0, 0];
+        }
+    }
+    init(canvas) {
+        const gl = canvas.getContext("webgl2");
+        if (!gl)
+            throw new Error("3d-spinner: WebGL2 is not supported in this browser.");
+        this.gl = gl;
+        this.program = link(gl);
+        this.locations = {
+            aPos: gl.getAttribLocation(this.program, "aPos"),
+            aNormal: gl.getAttribLocation(this.program, "aNormal"),
+            aColor: gl.getAttribLocation(this.program, "aColor"),
+            uViewProj: gl.getUniformLocation(this.program, "uViewProj"),
+            uModel: gl.getUniformLocation(this.program, "uModel"),
+            uToLight: gl.getUniformLocation(this.program, "uToLight"),
+            uIntensity: gl.getUniformLocation(this.program, "uIntensity"),
+            uAmbient: gl.getUniformLocation(this.program, "uAmbient"),
+        };
+        gl.enable(gl.DEPTH_TEST);
+        gl.enable(gl.CULL_FACE);
+        gl.cullFace(gl.BACK);
+        gl.frontFace(gl.CCW);
+    }
+    resize() {
+        const gl = this.gl;
+        if (!gl)
+            return;
+        const canvas = gl.canvas;
+        gl.viewport(0, 0, canvas.width, canvas.height);
+    }
+    buffers(mesh) {
+        const cached = this.cache.get(mesh);
+        if (cached)
+            return cached;
+        const gl = this.gl;
+        const loc = this.locations;
+        const data = expandToTriangles(mesh);
+        const vao = gl.createVertexArray();
+        gl.bindVertexArray(vao);
+        const attribute = (location, array) => {
+            if (location < 0)
+                return;
+            const buffer = gl.createBuffer();
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferData(gl.ARRAY_BUFFER, array, gl.STATIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, 3, gl.FLOAT, false, 0, 0);
+        };
+        attribute(loc.aPos, data.positions);
+        attribute(loc.aNormal, data.normals);
+        attribute(loc.aColor, data.colors);
+        gl.bindVertexArray(null);
+        const result = { vao, count: data.count };
+        this.cache.set(mesh, result);
+        return result;
+    }
+    render(frame) {
+        const gl = this.gl;
+        const loc = this.locations;
+        if (!gl || !this.program || !loc)
+            return;
+        gl.clearColor(...this.clearColor);
+        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+        gl.useProgram(this.program);
+        gl.uniformMatrix4fv(loc.uViewProj, false, new Float32Array(frame.viewProjection));
+        gl.uniform3f(loc.uToLight, frame.light.toLight.x, frame.light.toLight.y, frame.light.toLight.z);
+        gl.uniform1f(loc.uIntensity, frame.light.intensity);
+        gl.uniform1f(loc.uAmbient, frame.light.ambient);
+        for (const item of frame.items) {
+            const mesh = this.buffers(item.mesh);
+            gl.uniformMatrix4fv(loc.uModel, false, new Float32Array(item.model));
+            gl.bindVertexArray(mesh.vao);
+            gl.drawArrays(gl.TRIANGLES, 0, mesh.count);
+        }
+        gl.bindVertexArray(null);
+    }
+    destroy() {
+        const gl = this.gl;
+        if (gl) {
+            for (const mesh of this.cache.values())
+                gl.deleteVertexArray(mesh.vao);
+            if (this.program)
+                gl.deleteProgram(this.program);
+        }
+        this.cache.clear();
+        this.gl = undefined;
+        this.program = undefined;
+        this.locations = undefined;
+    }
+}

package/dist/engines/little-3d-engine/renderers/webgpu.d.ts

@@ -0,0 +1,24 @@
+import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+/** Hardware renderer using WebGPU: GPU transforms with a real depth buffer. */
+export declare class WebGPURenderer implements Renderer {
+    private canvas?;
+    private device;
+    private context;
+    private pipeline;
+    private uniformBuffer;
+    private uniformCapacity;
+    private depthTexture;
+    private depthSize;
+    private destroyed;
+    private readonly cache;
+    private readonly clearValue;
+    private readonly alphaMode;
+    constructor(options?: RendererOptions);
+    init(canvas: HTMLCanvasElement): Promise<void>;
+    resize(): void;
+    private ensureDepth;
+    private buffers;
+    private ensureUniformCapacity;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}