3d-spinner 0.9.2 → 0.9.4

package/dist/composite-animation.d.ts

@@ -0,0 +1,18 @@
+import type { AnimationFrame, SpinnerAnimation } from "./animation.js";
+/** One animation layer in a {@link CompositeAnimation}. Later layers render above earlier ones. */
+export interface CompositeAnimationLayer {
+    readonly animation: SpinnerAnimation;
+    readonly zIndex?: number;
+}
+/** Run multiple animations through one spinner lifecycle in stacked layers. */
+export declare class CompositeAnimation implements SpinnerAnimation {
+    private readonly layers;
+    private readonly elements;
+    constructor(layers: ReadonlyArray<SpinnerAnimation | CompositeAnimationLayer>);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    render(now: number, frame: AnimationFrame): void;
+    isFinished(): boolean;
+    destroy(): void;
+}

package/dist/composite-animation.js

@@ -0,0 +1,39 @@
+/** Run multiple animations through one spinner lifecycle in stacked layers. */
+export class CompositeAnimation {
+    constructor(layers) {
+        this.elements = [];
+        this.layers = layers.map((layer) => "animation" in layer ? layer : { animation: layer });
+    }
+    mount(target) {
+        target.style.position = "relative";
+        for (const [index, layer] of this.layers.entries()) {
+            const element = document.createElement("div");
+            element.style.cssText = `position:absolute;inset:0;z-index:${layer.zIndex ?? index}`;
+            target.appendChild(element);
+            this.elements.push(element);
+            layer.animation.mount(element);
+        }
+    }
+    enter(now) {
+        for (const layer of this.layers)
+            layer.animation.enter(now);
+    }
+    exit(now) {
+        for (const layer of this.layers)
+            layer.animation.exit(now);
+    }
+    render(now, frame) {
+        for (const layer of this.layers)
+            layer.animation.render(now, frame);
+    }
+    isFinished() {
+        return this.layers.every((layer) => layer.animation.isFinished());
+    }
+    destroy() {
+        for (const layer of this.layers)
+            layer.animation.destroy();
+        for (const element of this.elements)
+            element.remove();
+        this.elements.length = 0;
+    }
+}

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

@@ -1,11 +1,11 @@
 import { type CameraOptions } from "./core/camera.js";
 import { type LightOptions } from "./core/light.js";
 import { type Mesh, type Transform, type Transparency } from "./core/mesh.js";
-import { type Backend } from "./renderer.js";
+import { type Backend, type RendererFactory } from "./renderer.js";
 /** Options for {@link Little3dEngine}. */
 export interface Little3dEngineOptions {
-    /** Rendering backend. Loaded on demand. Default `"canvas2d"`. */
-    backend?: Backend;
+    /** Rendering backend, or a factory building a custom renderer. Loaded on demand. Default `"canvas2d"`. */
+    backend?: Backend | RendererFactory;
     camera?: Partial<CameraOptions>;
     light?: Partial<LightOptions>;
     /** Solid background color; omit for a transparent canvas (overlay use). */
@@ -66,17 +66,22 @@ export declare class Little3dEngine {
 }
 export { Camera, type CameraOptions } from "./core/camera.js";
 export { Light, type LightOptions, type LightParams } 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 { cube } from "./shapes/primitives/cube.js";
+export { quad } from "./shapes/primitives/quad.js";
+export { tetrahedron } from "./shapes/primitives/tetrahedron.js";
+export { octahedron } from "./shapes/primitives/octahedron.js";
+export { pyramid } from "./shapes/primitives/pyramid.js";
+export { uvSphere } from "./shapes/primitives/spheres/uv-sphere.js";
+export { icosphere } from "./shapes/primitives/spheres/icosphere.js";
+export { octaSphere } from "./shapes/primitives/spheres/octa-sphere.js";
+export { cubeSphere } from "./shapes/primitives/spheres/cube-sphere.js";
+export { planeMesh } from "./shapes/complex/plane.js";
+export { starTexture } from "./textures/dynamic/star.js";
+export { shineTexture } from "./textures/dynamic/shine.js";
+export { streakTexture } from "./textures/dynamic/streak.js";
 export { expandToTriangles } from "./core/geometry.js";
 export type { Mesh, Face, Transform, Transparency, OneSidedTransparency, TwoSidedTransparency, } from "./core/mesh.js";
 export { transform } from "./core/mesh.js";
-export type { Backend, Renderer, RenderFrame, RenderItem, RendererOptions } from "./renderer.js";
+export type { Backend, Renderer, RendererFactory, RenderFrame, RenderItem, RendererOptions, } from "./renderer.js";
 export { orderRenderItems } from "./renderer.js";
 export { type Vec3, vec3, subtract, cross, dot, scale, normalize, } from "./core/math.js";

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

@@ -157,14 +157,19 @@ export class Little3dEngine {
 }
 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 { cube } from "./shapes/primitives/cube.js";
+export { quad } from "./shapes/primitives/quad.js";
+export { tetrahedron } from "./shapes/primitives/tetrahedron.js";
+export { octahedron } from "./shapes/primitives/octahedron.js";
+export { pyramid } from "./shapes/primitives/pyramid.js";
+export { uvSphere } from "./shapes/primitives/spheres/uv-sphere.js";
+export { icosphere } from "./shapes/primitives/spheres/icosphere.js";
+export { octaSphere } from "./shapes/primitives/spheres/octa-sphere.js";
+export { cubeSphere } from "./shapes/primitives/spheres/cube-sphere.js";
+export { planeMesh } from "./shapes/complex/plane.js";
+export { starTexture } from "./textures/dynamic/star.js";
+export { shineTexture } from "./textures/dynamic/shine.js";
+export { streakTexture } from "./textures/dynamic/streak.js";
 export { expandToTriangles } from "./core/geometry.js";
 export { transform } from "./core/mesh.js";
 export { orderRenderItems } from "./renderer.js";

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

@@ -7,6 +7,13 @@ export interface ObjOptions {
      * a uniform color.
      */
     colors?: string[];
+    /** Contents of an `.mtl` file referenced by the OBJ. */
+    mtl?: string;
+    /**
+     * Use MTL diffuse (`Kd`) values for faces with matching `usemtl`
+     * statements. Default `false`.
+     */
+    useMtlColors?: boolean;
 }
 /**
  * Parse Wavefront OBJ text into a {@link Mesh}.
@@ -14,11 +21,12 @@ export interface ObjOptions {
  * 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 as-is; the engine expects CCW
- * winding as seen from outside.
+ * computes a flat normal per face. Material names can select diffuse colors
+ * from supplied MTL text; groups and other statements are ignored. Face
+ * winding is preserved as-is; the engine expects CCW winding as seen from
+ * outside.
  *
  * @param text Contents of an `.obj` file.
- * @param options Color palette to apply to the faces.
+ * @param options Face palette and optional MTL diffuse colors.
  */
 export declare function parseObj(text: string, options?: ObjOptions): Mesh;

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

@@ -1,4 +1,32 @@
 const DEFAULT_COLORS = ["#3b82f6", "#8b5cf6", "#ec4899", "#f59e0b", "#10b981", "#ef4444"];
+function channelToHex(value) {
+    const channel = Number.parseFloat(value);
+    if (!Number.isFinite(channel))
+        return undefined;
+    return Math.round(Math.min(1, Math.max(0, channel)) * 255)
+        .toString(16)
+        .padStart(2, "0");
+}
+function parseMtlColors(text) {
+    const colors = new Map();
+    let material;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const parts = trimmed.split(/\s+/);
+        if (parts[0] === "newmtl") {
+            material = parts.slice(1).join(" ");
+        }
+        else if (parts[0] === "Kd" && material) {
+            const channels = parts.slice(1, 4).map(channelToHex);
+            if (channels.length === 3 && channels.every((channel) => channel !== undefined)) {
+                colors.set(material, `#${channels.join("")}`);
+            }
+        }
+    }
+    return colors;
+}
 function resolveIndex(token, vertexCount) {
     const n = parseInt(token, 10);
     return n < 0 ? vertexCount + n : n - 1;
@@ -9,17 +37,22 @@ function resolveIndex(token, vertexCount) {
  * 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 as-is; the engine expects CCW
- * winding as seen from outside.
+ * computes a flat normal per face. Material names can select diffuse colors
+ * from supplied MTL text; groups and other statements are ignored. Face
+ * winding is preserved as-is; the engine expects CCW winding as seen from
+ * outside.
  *
  * @param text Contents of an `.obj` file.
- * @param options Color palette to apply to the faces.
+ * @param options Face palette and optional MTL diffuse colors.
  */
 export function parseObj(text, options = {}) {
     const colors = options.colors ?? DEFAULT_COLORS;
+    const materialColors = options.useMtlColors && options.mtl
+        ? parseMtlColors(options.mtl)
+        : undefined;
     const vertices = [];
     const faces = [];
+    let material;
     for (const line of text.split("\n")) {
         const trimmed = line.trim();
         if (trimmed === "" || trimmed.startsWith("#"))
@@ -33,6 +66,9 @@ export function parseObj(text, options = {}) {
                 z: parseFloat(parts[3]),
             });
         }
+        else if (keyword === "usemtl") {
+            material = parts.slice(1).join(" ");
+        }
         else if (keyword === "f") {
             const indices = [];
             for (let i = 1; i < parts.length; i++) {
@@ -40,7 +76,10 @@ export function parseObj(text, options = {}) {
                 indices.push(resolveIndex(vertexToken, vertices.length));
             }
             if (indices.length >= 3) {
-                faces.push({ indices, color: colors[faces.length % colors.length] });
+                const mtlColor = material ? materialColors?.get(material) : undefined;
+                const color = mtlColor
+                    ?? (materialColors ? (colors[0] ?? "#888888") : colors[faces.length % colors.length]);
+                faces.push({ indices, color });
             }
         }
     }

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

@@ -38,6 +38,12 @@ export interface RendererOptions {
     /** Solid background; omit for a transparent canvas (overlay use). */
     background?: string;
 }
+/**
+ * Builds a custom {@link Renderer}; an alternative to naming a built-in
+ * backend. Load the renderer module inside the factory with a dynamic
+ * `import()` to keep it out of the bundle until it is used.
+ */
+export type RendererFactory = (options: RendererOptions) => Renderer | Promise<Renderer>;
 /**
  * A pluggable drawing backend. The engine owns the canvas and sizing; a
  * renderer only initializes its context, reacts to resizes, and draws frames.
@@ -54,4 +60,4 @@ export interface Renderer {
  * 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>;
+export declare function createRenderer(backend: Backend | RendererFactory, options?: RendererOptions): Promise<Renderer>;

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

@@ -40,6 +40,8 @@ export function orderRenderItems(items, eye) {
  * backends you do not use are never downloaded or compiled.
  */
 export async function createRenderer(backend, options = {}) {
+    if (typeof backend === "function")
+        return backend(options);
     switch (backend) {
         case "webgl":
             return new (await import("./renderers/webgl.js")).WebGLRenderer(options);

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

@@ -0,0 +1,20 @@
+import type { Mesh } from "../core/mesh.js";
+import { type Renderer, type RenderFrame, type RendererOptions } from "../renderer.js";
+import type { TextureSource } from "./textured-helpers.js";
+export type { TextureSource } from "./textured-helpers.js";
+/** Canvas 2D texture renderer optimized for planar billboard meshes. */
+export declare class Canvas2DTexturedRenderer implements Renderer {
+    private readonly inner;
+    private readonly sources;
+    private readonly loaded;
+    private ctx?;
+    private dpr;
+    constructor(options?: RendererOptions);
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh: Mesh, source: TextureSource): void;
+    init(canvas: HTMLCanvasElement): void;
+    resize(cssWidth: number, cssHeight: number, dpr: number): void;
+    private drawable;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}

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

@@ -0,0 +1,135 @@
+import { transformAffine, transformPoint } from "../core/math.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity } from "../renderer.js";
+import { Canvas2DRenderer } from "./canvas2d.js";
+function imageSize(source) {
+    if (source instanceof HTMLImageElement) {
+        return source.complete && source.naturalWidth > 0
+            ? { width: source.naturalWidth, height: source.naturalHeight }
+            : undefined;
+    }
+    if (source instanceof HTMLVideoElement) {
+        return source.readyState >= 2
+            ? { width: source.videoWidth, height: source.videoHeight }
+            : undefined;
+    }
+    if (source instanceof SVGImageElement) {
+        const width = source.width.baseVal.value;
+        const height = source.height.baseVal.value;
+        return width > 0 && height > 0 ? { width, height } : undefined;
+    }
+    if (typeof VideoFrame !== "undefined" && source instanceof VideoFrame) {
+        return { width: source.displayWidth, height: source.displayHeight };
+    }
+    const sized = source;
+    return sized.width > 0 && sized.height > 0 ? { width: sized.width, height: sized.height } : undefined;
+}
+function drawMappedTriangle(ctx, image, source, target) {
+    const [s0, s1, s2] = source;
+    const [d0, d1, d2] = target;
+    const determinant = s0.x * (s1.y - s2.y) + s1.x * (s2.y - s0.y) + s2.x * (s0.y - s1.y);
+    if (Math.abs(determinant) < 1e-8)
+        return;
+    const a = (d0.x * (s1.y - s2.y) + d1.x * (s2.y - s0.y) + d2.x * (s0.y - s1.y)) / determinant;
+    const c = (d0.x * (s2.x - s1.x) + d1.x * (s0.x - s2.x) + d2.x * (s1.x - s0.x)) / determinant;
+    const e = (d0.x * (s1.x * s2.y - s2.x * s1.y) + d1.x * (s2.x * s0.y - s0.x * s2.y) + d2.x * (s0.x * s1.y - s1.x * s0.y)) / determinant;
+    const b = (d0.y * (s1.y - s2.y) + d1.y * (s2.y - s0.y) + d2.y * (s0.y - s1.y)) / determinant;
+    const d = (d0.y * (s2.x - s1.x) + d1.y * (s0.x - s2.x) + d2.y * (s1.x - s0.x)) / determinant;
+    const f = (d0.y * (s1.x * s2.y - s2.x * s1.y) + d1.y * (s2.x * s0.y - s0.x * s2.y) + d2.y * (s0.x * s1.y - s1.x * s0.y)) / determinant;
+    ctx.save();
+    ctx.beginPath();
+    ctx.moveTo(d0.x, d0.y);
+    ctx.lineTo(d1.x, d1.y);
+    ctx.lineTo(d2.x, d2.y);
+    ctx.closePath();
+    ctx.clip();
+    ctx.transform(a, b, c, d, e, f);
+    ctx.drawImage(image, 0, 0);
+    ctx.restore();
+}
+/** Canvas 2D texture renderer optimized for planar billboard meshes. */
+export class Canvas2DTexturedRenderer {
+    constructor(options = {}) {
+        this.sources = new Map();
+        this.loaded = new Map();
+        this.dpr = 1;
+        this.inner = new Canvas2DRenderer(options);
+    }
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh, source) {
+        this.sources.set(mesh, source);
+        if (typeof source === "string" && !this.loaded.has(source)) {
+            const image = new Image();
+            image.src = source;
+            this.loaded.set(source, image);
+        }
+    }
+    init(canvas) {
+        this.inner.init(canvas);
+        this.ctx = canvas.getContext("2d") ?? undefined;
+    }
+    resize(cssWidth, cssHeight, dpr) {
+        this.dpr = dpr;
+        this.inner.resize(cssWidth, cssHeight, dpr);
+    }
+    drawable(mesh) {
+        const source = this.sources.get(mesh);
+        return typeof source === "string" ? this.loaded.get(source) : source;
+    }
+    render(frame) {
+        const plain = frame.items.filter((item) => {
+            if (!this.sources.has(item.mesh))
+                return true;
+            const source = this.drawable(item.mesh);
+            return !source || !imageSize(source);
+        });
+        this.inner.render({ ...frame, items: plain });
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        ctx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0);
+        const tinted = new Map();
+        for (const item of frame.items) {
+            const source = this.drawable(item.mesh);
+            if (!source)
+                continue;
+            const size = imageSize(source);
+            if (!size)
+                continue;
+            let image = tinted.get(item.mesh);
+            if (!image) {
+                image = document.createElement("canvas");
+                image.width = size.width;
+                image.height = size.height;
+                const tint = image.getContext("2d");
+                if (!tint)
+                    continue;
+                tint.drawImage(source, 0, 0, size.width, size.height);
+                tint.globalCompositeOperation = "source-in";
+                tint.fillStyle = item.mesh.faces[0]?.color ?? "#ffffff";
+                tint.fillRect(0, 0, size.width, size.height);
+                tinted.set(item.mesh, image);
+            }
+            const world = item.mesh.vertices.map((vertex) => transformAffine(item.model, vertex));
+            const projected = world.map((vertex) => {
+                const ndc = transformPoint(frame.viewProjection, vertex);
+                return { x: (ndc.x * 0.5 + 0.5) * frame.width, y: (1 - (ndc.y * 0.5 + 0.5)) * frame.height };
+            });
+            const face = item.mesh.faces[0];
+            if (!face || face.indices.length !== 4)
+                continue;
+            const [a, b, c, d] = face.indices.map((index) => projected[index]);
+            ctx.globalAlpha = item.transparency?.mode === "one-sided"
+                ? opacity(item.transparency.opacity, DEFAULT_ONE_SIDED_OPACITY)
+                : 1;
+            drawMappedTriangle(ctx, image, [{ x: 0, y: size.height }, { x: size.width, y: size.height }, { x: size.width, y: 0 }], [a, b, c]);
+            drawMappedTriangle(ctx, image, [{ x: 0, y: size.height }, { x: size.width, y: 0 }, { x: 0, y: 0 }], [a, c, d]);
+        }
+        ctx.globalAlpha = 1;
+    }
+    destroy() {
+        this.inner.destroy();
+        this.ctx = undefined;
+        this.sources.clear();
+        this.loaded.clear();
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { Mesh } from "../core/mesh.js";
+/** An image source accepted for a mesh texture: a URL or a drawable element. */
+export type TextureSource = string | TexImageSource;
+/**
+ * UVs as a planar projection of the mesh's XY bounds (u right, v up), emitted
+ * in the same face-fan order as `expandToTriangles` so the arrays stay
+ * aligned. Exact for billboard quads; flat meshes map incidentally.
+ */
+export declare function planarUVs(mesh: Mesh): Float32Array;

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

@@ -0,0 +1,35 @@
+/**
+ * UVs as a planar projection of the mesh's XY bounds (u right, v up), emitted
+ * in the same face-fan order as `expandToTriangles` so the arrays stay
+ * aligned. Exact for billboard quads; flat meshes map incidentally.
+ */
+export function planarUVs(mesh) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const v of mesh.vertices) {
+        minX = Math.min(minX, v.x);
+        minY = Math.min(minY, v.y);
+        maxX = Math.max(maxX, v.x);
+        maxY = Math.max(maxY, v.y);
+    }
+    const width = maxX - minX || 1;
+    const height = maxY - minY || 1;
+    let triangles = 0;
+    for (const face of mesh.faces)
+        triangles += Math.max(0, face.indices.length - 2);
+    const uvs = new Float32Array(triangles * 6);
+    let o = 0;
+    for (const face of mesh.faces) {
+        for (let k = 1; k < face.indices.length - 1; k++) {
+            for (const index of [face.indices[0], face.indices[k], face.indices[k + 1]]) {
+                const v = mesh.vertices[index];
+                uvs[o] = (v.x - minX) / width;
+                uvs[o + 1] = 1 - (v.y - minY) / height;
+                o += 2;
+            }
+        }
+    }
+    return uvs;
+}

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

@@ -0,0 +1,43 @@
+import type { Mesh } from "../core/mesh.js";
+import { type Renderer, type RenderFrame, type RendererOptions } from "../renderer.js";
+import { type TextureSource } from "./textured-helpers.js";
+export type { TextureSource } from "./textured-helpers.js";
+/**
+ * WebGL renderer with image textures on registered meshes; unregistered
+ * meshes render exactly as in the plain WebGL backend. Made for billboard
+ * quads: UVs are a planar projection of the mesh's XY extent, textured faces
+ * render unlit with the texture tinted by the face color, and textured
+ * instances draw after the other transparent instances. Until an image URL
+ * finishes loading its mesh renders with a plain white texture.
+ *
+ * Pass it to the engine (or an animation) as a `backend` factory so the
+ * module is only fetched when used:
+ *
+ * ```js
+ * backend: async (options) => {
+ *   const { WebGLTexturedRenderer } =
+ *     await import("3d-spinner/engines/little-3d-engine/renderers/webgl-textured");
+ *   const renderer = new WebGLTexturedRenderer(options);
+ *   renderer.setTexture(mesh, "/sprite.png");
+ *   return renderer;
+ * }
+ * ```
+ */
+export declare class WebGLTexturedRenderer implements Renderer {
+    private readonly inner;
+    private gl?;
+    private program?;
+    private locations?;
+    private readonly sources;
+    private readonly textures;
+    private readonly buffers;
+    constructor(options?: RendererOptions);
+    /** Texture every instance of `mesh` with `source`. Call any time, also before init. */
+    setTexture(mesh: Mesh, source: TextureSource): void;
+    init(canvas: HTMLCanvasElement): void;
+    resize(): void;
+    private textureFor;
+    private buffersFor;
+    render(frame: RenderFrame): void;
+    destroy(): void;
+}