3d-spinner 0.9.0 → 0.9.2

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

@@ -1,6 +1,6 @@
 import { type CameraOptions } from "./core/camera.js";
 import { type LightOptions } from "./core/light.js";
-import { type Mesh, type Transform } from "./core/mesh.js";
+import { type Mesh, type Transform, type Transparency } from "./core/mesh.js";
 import { type Backend } from "./renderer.js";
 /** Options for {@link Little3dEngine}. */
 export interface Little3dEngineOptions {
@@ -15,9 +15,15 @@ export interface Little3dEngineOptions {
 export interface MeshHandle {
     readonly mesh: Mesh;
     readonly transform: Transform;
+    /** Optional per-instance transparency. Mutate or replace it between frames. */
+    transparency?: Transparency;
     /** Remove this mesh from the scene. */
     remove(): void;
 }
+/** Initial state for one mesh instance. */
+export interface MeshInstanceOptions extends Partial<Transform> {
+    transparency?: Transparency;
+}
 /**
  * A minimal software/hardware 3D engine. It projects colored meshes with flat
  * directional lighting through a swappable {@link Backend} renderer. Mount it
@@ -47,7 +53,7 @@ export declare class Little3dEngine {
      */
     mount(target: HTMLElement): Promise<void>;
     /** Add a mesh to the scene and return a handle for animating it. */
-    add(mesh: Mesh, init?: Partial<Transform>): MeshHandle;
+    add(mesh: Mesh, init?: MeshInstanceOptions): MeshHandle;
     private resize;
     /** Draw a single frame from the current scene state. */
     render(): void;
@@ -69,7 +75,8 @@ 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 type { Mesh, Face, Transform } from "./core/mesh.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 { 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

@@ -1,8 +1,8 @@
 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";
+import { transform as makeTransform, } from "./core/mesh.js";
+import { createRenderer, orderRenderItems, } 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)));
@@ -75,17 +75,18 @@ export class Little3dEngine {
     }
     /** 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 {
+        const entry = {
             mesh,
-            transform: entry.transform,
+            transform: makeTransform(init),
+            transparency: init?.transparency,
             remove: () => {
                 const i = this.scene.indexOf(entry);
                 if (i >= 0)
                     this.scene.splice(i, 1);
             },
         };
+        this.scene.push(entry);
+        return entry;
     }
     resize() {
         const canvas = this.canvas;
@@ -109,11 +110,13 @@ export class Little3dEngine {
         const items = this.scene.map((entry) => ({
             mesh: entry.mesh,
             model: modelMatrix(entry.transform),
+            transparency: entry.transparency,
         }));
+        const eye = this.camera.options.position;
         this.renderer.render({
-            items,
+            items: orderRenderItems(items, eye),
             viewProjection: this.camera.viewProjection(width / height),
-            eye: this.camera.options.position,
+            eye,
             light: this.light.params,
             width,
             height,
@@ -164,4 +167,5 @@ 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 { orderRenderItems } from "./renderer.js";
 export { vec3, subtract, cross, dot, scale, normalize, } from "./core/math.js";

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

@@ -15,8 +15,8 @@ export interface ObjOptions {
  * `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.
+ * statements. 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.

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

@@ -10,8 +10,8 @@ function resolveIndex(token, vertexCount) {
  * `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.
+ * statements. 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.

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

@@ -1,13 +1,26 @@
 import type { LightParams } from "./core/light.js";
 import type { Mat4, Vec3 } from "./core/math.js";
-import type { Mesh } from "./core/mesh.js";
+import type { Mesh, Transparency, TwoSidedTransparency } 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;
+    transparency?: Transparency;
 }
+export declare const DEFAULT_ONE_SIDED_OPACITY = 0.35;
+export declare const DEFAULT_BACK_OPACITY = 0.84;
+export declare const DEFAULT_FRONT_OPACITY = 0.56;
+/** Clamp an optional opacity to the range accepted by rendering backends. */
+export declare function opacity(value: number | undefined, fallback: number): number;
+/** Resolve two-sided defaults, shorthand, and explicit per-side overrides. */
+export declare function resolveTwoSidedOpacity(transparency: TwoSidedTransparency): {
+    front: number;
+    back: number;
+};
+/** Draw opaque instances first, then transparent instances from farthest to nearest. */
+export declare function orderRenderItems(items: ReadonlyArray<RenderItem>, eye: Vec3): RenderItem[];
 /** Everything a renderer needs to draw one frame. */
 export interface RenderFrame {
     items: ReadonlyArray<RenderItem>;
@@ -28,6 +41,7 @@ export interface RendererOptions {
 /**
  * A pluggable drawing backend. The engine owns the canvas and sizing; a
  * renderer only initializes its context, reacts to resizes, and draws frames.
+ * Renderer-specific features can produce intentional visual differences.
  */
 export interface Renderer {
     init(canvas: HTMLCanvasElement): void | Promise<void>;

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

@@ -1,3 +1,39 @@
+export const DEFAULT_ONE_SIDED_OPACITY = 0.35;
+export const DEFAULT_BACK_OPACITY = 0.84;
+export const DEFAULT_FRONT_OPACITY = 0.56;
+/** Clamp an optional opacity to the range accepted by rendering backends. */
+export function opacity(value, fallback) {
+    return Math.max(0, Math.min(1, value ?? fallback));
+}
+/** Resolve two-sided defaults, shorthand, and explicit per-side overrides. */
+export function resolveTwoSidedOpacity(transparency) {
+    const front = opacity(transparency.frontOpacity ?? transparency.opacity, DEFAULT_FRONT_OPACITY);
+    const backFallback = transparency.opacity === undefined
+        ? DEFAULT_BACK_OPACITY
+        : front * (2 / 3);
+    return {
+        front,
+        back: opacity(transparency.backOpacity, backFallback),
+    };
+}
+/** Draw opaque instances first, then transparent instances from farthest to nearest. */
+export function orderRenderItems(items, eye) {
+    const opaque = [];
+    const transparent = [];
+    for (const item of items) {
+        (item.transparency ? transparent : opaque).push(item);
+    }
+    transparent.sort((a, b) => {
+        const ax = a.model[12] - eye.x;
+        const ay = a.model[13] - eye.y;
+        const az = a.model[14] - eye.z;
+        const bx = b.model[12] - eye.x;
+        const by = b.model[13] - eye.y;
+        const bz = b.model[14] - eye.z;
+        return bx * bx + by * by + bz * bz - (ax * ax + ay * ay + az * az);
+    });
+    return opaque.concat(transparent);
+}
 /**
  * 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

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

@@ -1,4 +1,4 @@
-import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+import { type Renderer, type RenderFrame, type RendererOptions } from "../renderer.js";
 /** Software renderer: projects geometry on the CPU and fills 2D polygons. */
 export declare class Canvas2DRenderer implements Renderer {
     private readonly options;

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

@@ -1,5 +1,6 @@
 import { shadeColor } from "../core/light.js";
 import { dot, cross, normalize, subtract, transformAffine, transformPoint } from "../core/math.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity, resolveTwoSidedOpacity, } from "../renderer.js";
 /** Software renderer: projects geometry on the CPU and fills 2D polygons. */
 export class Canvas2DRenderer {
     constructor(options = {}) {
@@ -27,13 +28,25 @@ export class Canvas2DRenderer {
         const polygons = [];
         for (const item of frame.items) {
             const world = item.mesh.vertices.map((v) => transformAffine(item.model, v));
+            const twoSidedOpacity = item.transparency?.mode === "two-sided"
+                ? resolveTwoSidedOpacity(item.transparency)
+                : undefined;
             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)
+                const frontFacing = dot(normal, subtract(frame.eye, a)) > 0;
+                const transparency = item.transparency;
+                if (!frontFacing && transparency?.mode !== "two-sided")
                     continue;
+                let faceOpacity = 1;
+                if (transparency?.mode === "one-sided") {
+                    faceOpacity = opacity(transparency.opacity, DEFAULT_ONE_SIDED_OPACITY);
+                }
+                else if (twoSidedOpacity) {
+                    faceOpacity = frontFacing ? twoSidedOpacity.front : twoSidedOpacity.back;
+                }
                 const points = face.indices.map((i) => {
                     const ndc = transformPoint(frame.viewProjection, world[i]);
                     return {
@@ -47,7 +60,12 @@ export class Canvas2DRenderer {
                     depth += dot(d, d);
                 }
                 depth /= face.indices.length;
-                polygons.push({ points, color: shadeColor(normal, face.color, frame.light), depth });
+                polygons.push({
+                    points,
+                    color: shadeColor(normal, face.color, frame.light),
+                    depth,
+                    opacity: faceOpacity,
+                });
             }
         }
         polygons.sort((p, q) => q.depth - p.depth);
@@ -63,9 +81,11 @@ export class Canvas2DRenderer {
             ctx.fillStyle = poly.color;
             ctx.strokeStyle = poly.color;
             ctx.lineWidth = 1;
+            ctx.globalAlpha = poly.opacity;
             ctx.fill();
             ctx.stroke();
         }
+        ctx.globalAlpha = 1;
     }
     destroy() {
         this.ctx = undefined;

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

@@ -1,4 +1,4 @@
-import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+import { type Renderer, type RenderFrame, type RendererOptions } from "../renderer.js";
 /** Hardware renderer using WebGL2: GPU transforms with a real depth buffer. */
 export declare class WebGLRenderer implements Renderer {
     private gl?;

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

@@ -1,4 +1,5 @@
 import { expandToTriangles, parseColor } from "../core/geometry.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity, resolveTwoSidedOpacity, } from "../renderer.js";
 const VERTEX_SHADER = `#version 300 es
 in vec3 aPos;
 in vec3 aNormal;
@@ -19,11 +20,12 @@ in vec3 vColor;
 uniform vec3 uToLight;
 uniform float uIntensity;
 uniform float uAmbient;
+uniform float uOpacity;
 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);
+  fragColor = vec4(vColor * brightness, uOpacity);
 }`;
 function compile(gl, type, source) {
     const shader = gl.createShader(type);
@@ -71,6 +73,7 @@ export class WebGLRenderer {
             uToLight: gl.getUniformLocation(this.program, "uToLight"),
             uIntensity: gl.getUniformLocation(this.program, "uIntensity"),
             uAmbient: gl.getUniformLocation(this.program, "uAmbient"),
+            uOpacity: gl.getUniformLocation(this.program, "uOpacity"),
         };
         gl.enable(gl.DEPTH_TEST);
         gl.enable(gl.CULL_FACE);
@@ -122,12 +125,46 @@ export class WebGLRenderer {
         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);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.cullFace(gl.BACK);
         for (const item of frame.items) {
+            if (item.transparency)
+                continue;
             const mesh = this.buffers(item.mesh);
             gl.uniformMatrix4fv(loc.uModel, false, new Float32Array(item.model));
+            gl.uniform1f(loc.uOpacity, 1);
             gl.bindVertexArray(mesh.vao);
             gl.drawArrays(gl.TRIANGLES, 0, mesh.count);
         }
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+        for (const item of frame.items) {
+            const transparency = item.transparency;
+            if (!transparency)
+                continue;
+            const mesh = this.buffers(item.mesh);
+            gl.uniformMatrix4fv(loc.uModel, false, new Float32Array(item.model));
+            gl.bindVertexArray(mesh.vao);
+            if (transparency.mode === "two-sided") {
+                const resolved = resolveTwoSidedOpacity(transparency);
+                gl.cullFace(gl.FRONT);
+                gl.uniform1f(loc.uOpacity, resolved.back);
+                gl.drawArrays(gl.TRIANGLES, 0, mesh.count);
+                gl.cullFace(gl.BACK);
+                gl.uniform1f(loc.uOpacity, resolved.front);
+                gl.drawArrays(gl.TRIANGLES, 0, mesh.count);
+            }
+            else {
+                gl.cullFace(gl.BACK);
+                gl.uniform1f(loc.uOpacity, opacity(transparency.opacity, DEFAULT_ONE_SIDED_OPACITY));
+                gl.drawArrays(gl.TRIANGLES, 0, mesh.count);
+            }
+        }
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+        gl.cullFace(gl.BACK);
         gl.bindVertexArray(null);
     }
     destroy() {

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

@@ -1,10 +1,12 @@
-import type { Renderer, RenderFrame, RendererOptions } from "../renderer.js";
+import { type Renderer, type RenderFrame, type 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 transparentBackPipeline;
+    private transparentFrontPipeline;
     private uniformBuffer;
     private uniformCapacity;
     private depthTexture;

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

@@ -1,5 +1,6 @@
 import { expandToTriangles, parseColor } from "../core/geometry.js";
 import { multiply } from "../core/math.js";
+import { DEFAULT_ONE_SIDED_OPACITY, opacity, resolveTwoSidedOpacity, } from "../renderer.js";
 const WGSL = `
 struct Uniforms {
   viewProj: mat4x4<f32>,
@@ -29,7 +30,7 @@ fn vs(@location(0) pos: vec3<f32>, @location(1) normal: vec3<f32>, @location(2)
 fn fs(in: VSOut) -> @location(0) vec4<f32> {
   let lambert = max(dot(normalize(in.normal), normalize(u.toLight.xyz)), 0.0);
   let brightness = clamp(u.params.y + u.params.x * lambert, 0.0, 1.0);
-  return vec4<f32>(in.color * brightness, 1.0);
+  return vec4<f32>(in.color * brightness, u.params.z);
 }
 `;
 // Maps OpenGL clip space (z in -1..1) to WebGPU clip space (z in 0..1).
@@ -84,17 +85,37 @@ export class WebGPURenderer {
             arrayStride: 12,
             attributes: [{ shaderLocation: location, offset: 0, format: "float32x3" }],
         });
-        this.pipeline = device.createRenderPipeline({
-            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+        const blend = {
+            color: {
+                srcFactor: "src-alpha",
+                dstFactor: "one-minus-src-alpha",
+                operation: "add",
+            },
+            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+        };
+        const pipeline = (cullMode, transparent) => device.createRenderPipeline({
+            layout: pipelineLayout,
             vertex: {
                 module,
                 entryPoint: "vs",
                 buffers: [vertexBuffer(0), vertexBuffer(1), vertexBuffer(2)],
             },
-            fragment: { module, entryPoint: "fs", targets: [{ format }] },
-            primitive: { topology: "triangle-list", cullMode: "back", frontFace: "ccw" },
-            depthStencil: { format: "depth24plus", depthWriteEnabled: true, depthCompare: "less" },
+            fragment: {
+                module,
+                entryPoint: "fs",
+                targets: [{ format, ...(transparent ? { blend } : {}) }],
+            },
+            primitive: { topology: "triangle-list", cullMode, frontFace: "ccw" },
+            depthStencil: {
+                format: "depth24plus",
+                depthWriteEnabled: !transparent,
+                depthCompare: "less",
+            },
         });
+        this.pipeline = pipeline("back", false);
+        this.transparentBackPipeline = pipeline("front", true);
+        this.transparentFrontPipeline = pipeline("back", true);
         this.canvas = canvas;
         this.device = device;
         this.context = context;
@@ -139,15 +160,15 @@ export class WebGPURenderer {
         this.cache.set(mesh, result);
         return result;
     }
-    ensureUniformCapacity(items) {
-        if (items <= this.uniformCapacity && this.uniformBuffer)
+    ensureUniformCapacity(draws) {
+        if (draws <= this.uniformCapacity && this.uniformBuffer)
             return;
         this.uniformBuffer?.destroy?.();
         this.uniformBuffer = this.device.createBuffer({
-            size: Math.max(1, items) * UNIFORM_STRIDE,
+            size: Math.max(1, draws) * UNIFORM_STRIDE,
             usage: globalThis.GPUBufferUsage.UNIFORM | globalThis.GPUBufferUsage.COPY_DST,
         });
-        this.uniformCapacity = items;
+        this.uniformCapacity = draws;
     }
     render(frame) {
         if (this.destroyed || !this.device || !this.context || !this.pipeline)
@@ -155,7 +176,37 @@ export class WebGPURenderer {
         if (frame.width === 0 || frame.height === 0 || frame.items.length === 0)
             return;
         this.ensureDepth();
-        this.ensureUniformCapacity(frame.items.length);
+        const draws = [];
+        for (const item of frame.items) {
+            if (!item.transparency)
+                draws.push({ item, opacity: 1, pipeline: this.pipeline });
+        }
+        for (const item of frame.items) {
+            const transparency = item.transparency;
+            if (!transparency)
+                continue;
+            if (transparency.mode === "two-sided") {
+                const resolved = resolveTwoSidedOpacity(transparency);
+                draws.push({
+                    item,
+                    opacity: resolved.back,
+                    pipeline: this.transparentBackPipeline,
+                });
+                draws.push({
+                    item,
+                    opacity: resolved.front,
+                    pipeline: this.transparentFrontPipeline,
+                });
+            }
+            else {
+                draws.push({
+                    item,
+                    opacity: opacity(transparency.opacity, DEFAULT_ONE_SIDED_OPACITY),
+                    pipeline: this.transparentFrontPipeline,
+                });
+            }
+        }
+        this.ensureUniformCapacity(draws.length);
         const viewProj = multiply(CLIP_Z_FIX, frame.viewProjection);
         const layout = this.pipeline.getBindGroupLayout(0);
         const bindGroup = this.device.createBindGroup({
@@ -164,12 +215,12 @@ export class WebGPURenderer {
                 { binding: 0, resource: { buffer: this.uniformBuffer, offset: 0, size: 160 } },
             ],
         });
-        frame.items.forEach((item, i) => {
+        draws.forEach((draw, i) => {
             const data = new Float32Array(UNIFORM_STRIDE / 4);
             data.set(viewProj, 0);
-            data.set(item.model, 16);
+            data.set(draw.item.model, 16);
             data.set([frame.light.toLight.x, frame.light.toLight.y, frame.light.toLight.z, 0], 32);
-            data.set([frame.light.intensity, frame.light.ambient, 0, 0], 36);
+            data.set([frame.light.intensity, frame.light.ambient, draw.opacity, 0], 36);
             this.device.queue.writeBuffer(this.uniformBuffer, i * UNIFORM_STRIDE, data);
         });
         const encoder = this.device.createCommandEncoder();
@@ -189,9 +240,9 @@ export class WebGPURenderer {
                 depthStoreOp: "store",
             },
         });
-        pass.setPipeline(this.pipeline);
-        frame.items.forEach((item, i) => {
-            const mesh = this.buffers(item.mesh);
+        draws.forEach((draw, i) => {
+            const mesh = this.buffers(draw.item.mesh);
+            pass.setPipeline(draw.pipeline);
             pass.setBindGroup(0, bindGroup, [i * UNIFORM_STRIDE]);
             pass.setVertexBuffer(0, mesh.position);
             pass.setVertexBuffer(1, mesh.normal);
@@ -215,6 +266,8 @@ export class WebGPURenderer {
         this.device = undefined;
         this.context = undefined;
         this.pipeline = undefined;
+        this.transparentBackPipeline = undefined;
+        this.transparentFrontPipeline = undefined;
         this.uniformBuffer = undefined;
         this.depthTexture = undefined;
         this.canvas = undefined;