3d-spinner 0.9.0 → 0.9.1

package/README.md

@@ -1,4 +1,4 @@
-# 3d-spinner
+# 3d-spinner and beyond
 
 [![tests](https://img.shields.io/github/actions/workflow/status/runelaang/3d-spinner/ci.yml?label=tests&logo=github)](https://github.com/runelaang/3d-spinner/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/3d-spinner?logo=npm)](https://www.npmjs.com/package/3d-spinner)
@@ -145,6 +145,24 @@ do not use is never fetched.
 new SpinAnimation({ backend: "webgl" }); // "canvas2d" (default), "webgl", or "webgpu"
 ```
 
+Renderer-specific features can look different between Canvas 2D, WebGL, and WebGPU. In
+particular, transparent shapes are an approximate visual effect rather than a pixel-identical
+cross-renderer result.
+
+Use `transparency.mode` to choose visible-front-face transparency or a two-pass transparent-solid
+effect. Opacity defaults to `0.35` for one-sided rendering. Two-sided rendering defaults to
+front `0.56` and back `0.84`.
+
+```js
+new SpinAnimation({
+  backend: "webgl",
+  transparency: { mode: "two-sided", opacity: 0.6 }, // front 0.6, back 0.4
+});
+```
+
+For two-sided rendering, explicit `frontOpacity` and `backOpacity` values override the shorthand
+for their respective sides.
+
 ## The engine
 
 The renderer is a small, self-contained 3D engine, exported on its own in case you want it

package/dist/animations/object-motion.d.ts

@@ -1,5 +1,5 @@
 import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
-import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import { type Backend, type Mesh, type Transparency } from "../engines/little-3d-engine/little-3d-engine.js";
 import type { MotionController } from "../motion/controller.js";
 import { type ObjectMotionTransitionConfig } from "../motion/transitions.js";
 /** Which local axis the object's nose points down, used to correct a model that moves backwards or sideways. */
@@ -31,6 +31,8 @@ export interface ObjectMotionOptions {
     color?: string;
     /** Rendering backend. Default `"canvas2d"`. */
     backend?: Backend;
+    /** Optional one-sided or two-sided mesh transparency. */
+    transparency?: Transparency;
     /** Uniform object size after centering. Default `1`. */
     size?: number;
     /** The object's nose axis. Set this to correct a model that moves backwards or sideways. Default `"+x"`. */
@@ -65,6 +67,7 @@ export declare class ObjectMotionAnimation implements SpinnerAnimation {
     private readonly mesh;
     private readonly motion;
     private readonly backend?;
+    private readonly transparency?;
     private readonly labelText?;
     private readonly tailCount;
     private readonly tailGap;

package/dist/animations/object-motion.js

@@ -159,6 +159,7 @@ export class ObjectMotionAnimation {
         this.mesh = applyColor(facing, options.color ?? "#cbd5e1");
         this.motion = options.motion;
         this.backend = options.backend;
+        this.transparency = options.transparency;
         this.labelText = options.label;
         this.tailCount = Math.max(0, Math.floor(options.tail?.count ?? 0));
         this.tailGap = Math.max(0, options.tail?.gapMs ?? 0);
@@ -186,7 +187,7 @@ export class ObjectMotionAnimation {
             camera: { position: { x: 0, y: 0, z: 3 } },
         });
         for (let i = 0; i <= this.tailCount; i++) {
-            this.handles.push(engine.add(this.mesh));
+            this.handles.push(engine.add(this.mesh, { transparency: this.transparency }));
             this.banks.push(0);
             this.headings.push({ x: 1, y: 0, z: 0 });
         }

package/dist/animations/spin.d.ts

@@ -1,5 +1,5 @@
 import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
-import { type Backend, type Mesh } from "../engines/little-3d-engine/little-3d-engine.js";
+import { type Backend, type Mesh, type Transparency } from "../engines/little-3d-engine/little-3d-engine.js";
 import { type ProgressAnimationOptions } from "../progress-animation.js";
 export interface SpinAnimationOptions {
     /** Shape to spin: a mesh, or a factory that returns one. Default: a cube. */
@@ -12,6 +12,8 @@ export interface SpinAnimationOptions {
     spinY?: number;
     /** Rendering backend. Default `"canvas2d"`. */
     backend?: Backend;
+    /** Optional one-sided or two-sided mesh transparency. */
+    transparency?: Transparency;
     /**
      * Enable the start/end pop and progress-driven scale, with an optional overlay
      * label. Omit to spin at constant size with no progress reaction.
@@ -31,6 +33,7 @@ export declare class SpinAnimation implements SpinnerAnimation {
     private readonly spinX;
     private readonly spinY;
     private readonly backend?;
+    private readonly transparency?;
     private readonly progress?;
     private exited;
     constructor(options?: SpinAnimationOptions);

package/dist/animations/spin.js

@@ -36,6 +36,7 @@ export class SpinAnimation {
         this.spinX = options.spinX ?? 0.0007;
         this.spinY = options.spinY ?? 0.0011;
         this.backend = options.backend;
+        this.transparency = options.transparency;
         this.progress = options.progressAnimation
             ? new ProgressAnimation(options.progressAnimation)
             : undefined;
@@ -46,7 +47,7 @@ export class SpinAnimation {
             backend: this.backend,
             camera: { position: { x: 0, y: 0, z: 2.8 } },
         });
-        this.handle = engine.add(this.mesh);
+        this.handle = engine.add(this.mesh, { transparency: this.transparency });
         this.engine = engine;
         engine.mount(target).catch((error) => {
             target.textContent = error instanceof Error ? error.message : String(error);

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

@@ -11,6 +11,24 @@ export interface Mesh {
     vertices: Vec3[];
     faces: Face[];
 }
+/** Draw only outward-facing transparent surfaces. */
+export interface OneSidedTransparency {
+    mode: "one-sided";
+    /** Surface opacity from `0` (invisible) to `1` (opaque). Default `0.35`. */
+    opacity?: number;
+}
+/** Draw back surfaces before front surfaces to suggest a transparent solid. */
+export interface TwoSidedTransparency {
+    mode: "two-sided";
+    /** Front opacity shorthand; back opacity is derived as two-thirds of front. */
+    opacity?: number;
+    /** Back-surface opacity from `0` to `1`. Default `0.84`. */
+    backOpacity?: number;
+    /** Front-surface opacity from `0` to `1`. Default `0.56`. */
+    frontOpacity?: number;
+}
+/** Transparency mode for one mesh instance. */
+export type Transparency = OneSidedTransparency | TwoSidedTransparency;
 /** Position and orientation (Euler radians) applied to a mesh when rendered. */
 export interface Transform {
     position: Vec3;

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/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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "3d-spinner",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "A lightweight, zero-dependency 3D spinner, loader, and progress indicator for JavaScript.",
   "type": "module",
   "main": "./dist/index.js",