@doki-land/live2d-renderer 0.0.0 → 0.0.11

package/src/cpu/evaluate.ts

@@ -0,0 +1,101 @@
+import type {
+    FrameBlendMode,
+    FrameDrawable,
+    FrameSnapshot,
+    ModelInstance,
+    ModelProgram,
+} from "@doki-land/live2d-core";
+
+/** Create a runtime instance with default parameter values. */
+export function createModelInstance(program: ModelProgram): ModelInstance {
+    const parameterValues = new Float32Array(program.parameters.length);
+    for (let i = 0; i < program.parameters.length; i++) {
+        parameterValues[i] = program.parameters[i]?.defaultValue ?? 0;
+    }
+    return {
+        program,
+        parameterValues,
+        timeSeconds: 0,
+    };
+}
+
+export function setParameterValue(
+    instance: ModelInstance,
+    parameterId: string,
+    value: number,
+): void {
+    const index = instance.program.parameters.findIndex(
+        (p) => p.id === parameterId,
+    );
+    if (index < 0) {
+        throw new Error(
+            `@doki-land/live2d-renderer: unknown parameter "${parameterId}"`,
+        );
+    }
+    const p = instance.program.parameters[index]!;
+    instance.parameterValues[index] = Math.min(p.max, Math.max(p.min, value));
+}
+
+function paramWeight(instance: ModelInstance, paramIndex: number): number {
+    const p = instance.program.parameters[paramIndex];
+    if (!p) return 0;
+    const v = instance.parameterValues[paramIndex] ?? p.defaultValue;
+    if (v >= p.defaultValue) {
+        const span = p.max - p.defaultValue;
+        return span === 0 ? 0 : (v - p.defaultValue) / span;
+    }
+    const span = p.defaultValue - p.min;
+    return span === 0 ? 0 : (v - p.defaultValue) / span;
+}
+
+/** CPU deform 鈫?FrameSnapshot. */
+export function evaluateFrame(instance: ModelInstance): FrameSnapshot {
+    const drawables: FrameDrawable[] = [];
+
+    for (const d of instance.program.drawables) {
+        const positions = new Float32Array(d.positions);
+        if (d.deformParamIndex >= 0 && d.deformDeltas) {
+            const w = paramWeight(instance, d.deformParamIndex);
+            for (let i = 0; i < positions.length; i++) {
+                positions[i] = positions[i]! + w * d.deformDeltas[i]!;
+            }
+        }
+        drawables.push({
+            index: d.index,
+            textureIndex: d.textureIndex,
+            positions,
+            uvs: d.uvs,
+            indices: d.indices,
+            opacity: d.opacity,
+            blendMode: d.blendMode as FrameBlendMode,
+            renderOrder: d.renderOrder,
+            visible: d.visible,
+            invertedMask: d.invertedMask,
+            maskIndices: d.maskIndices,
+        });
+    }
+
+    drawables.sort((a, b) => a.renderOrder - b.renderOrder);
+
+    return {
+        timeSeconds: instance.timeSeconds,
+        drawables,
+    };
+}
+
+/** Stable fingerprint for golden tests (positions + topology). */
+export function fingerprintSnapshot(snapshot: FrameSnapshot): string {
+    const parts: string[] = [`t=${snapshot.timeSeconds.toFixed(4)}`];
+    for (const d of snapshot.drawables) {
+        parts.push(
+            `d${d.index}:tex=${d.textureIndex};nV=${d.positions.length / 2};nI=${d.indices.length}`,
+        );
+        for (let i = 0; i < d.positions.length; i++) {
+            parts.push(d.positions[i]?.toFixed(5) ?? "0");
+        }
+        for (let i = 0; i < d.indices.length; i++) {
+            parts.push(String(d.indices[i]));
+        }
+    }
+    return parts.join("|");
+}

package/src/create-renderer.ts

@@ -0,0 +1,143 @@
+import {
+    type Canvas2DRendererOptions,
+    createCanvas2DRenderer,
+} from "./backends/canvas2d.js";
+import {
+    createWebGl2Renderer,
+    type WebGl2RendererOptions,
+} from "./backends/webgl2.js";
+import {
+    createWebGpuRenderer,
+    type WebGpuRendererOptions,
+} from "./backends/webgpu.js";
+import type { Renderer, RendererKind } from "./types.js";
+
+export interface CreateRendererOptions {
+    /**
+     * Backend try order at initialize time.
+     * Default: `["webgpu", "webgl2", "canvas2d"]`.
+     */
+    prefer?: RendererKind[];
+    webgpu?: WebGpuRendererOptions;
+    webgl2?: WebGl2RendererOptions;
+    canvas2d?: Canvas2DRendererOptions;
+}
+
+const DEFAULT_PREFER: RendererKind[] = ["webgpu", "webgl2", "canvas2d"];
+
+/** Avoid indefinite hangs on `requestAdapter` / `requestDevice`. */
+const INIT_TIMEOUT_MS: Record<RendererKind, number> = {
+    webgpu: 2500,
+    webgl2: 1500,
+    canvas2d: 1000,
+};
+
+function instantiate(
+    kind: RendererKind,
+    options: CreateRendererOptions,
+): Renderer {
+    if (kind === "webgpu") return createWebGpuRenderer(options.webgpu);
+    if (kind === "webgl2") return createWebGl2Renderer(options.webgl2);
+    return createCanvas2DRenderer(options.canvas2d);
+}
+
+async function initializeWithTimeout(
+    kind: RendererKind,
+    candidate: Renderer,
+    canvas: HTMLCanvasElement,
+): Promise<void> {
+    const ms = INIT_TIMEOUT_MS[kind];
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+        await Promise.race([
+            candidate.initialize(canvas),
+            new Promise<never>((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(
+                        new Error(
+                            `@doki-land/live2d-renderer: ${kind} initialize timed out after ${ms}ms`,
+                        ),
+                    );
+                }, ms);
+            }),
+        ]);
+    } finally {
+        if (timer !== undefined) clearTimeout(timer);
+    }
+}
+
+/**
+ * Renderer that picks the first backend whose `initialize` succeeds.
+ * Availability is decided at initialize time, not via sync navigator checks.
+ */
+class FallbackRenderer implements Renderer {
+    #inner: Renderer | null = null;
+    #kind: RendererKind = "webgpu";
+    readonly #prefer: RendererKind[];
+    readonly #options: CreateRendererOptions;
+
+    constructor(prefer: RendererKind[], options: CreateRendererOptions) {
+        this.#prefer = prefer;
+        this.#options = options;
+    }
+
+    get kind(): RendererKind {
+        return this.#inner?.kind ?? this.#kind;
+    }
+
+    async initialize(canvas: HTMLCanvasElement): Promise<void> {
+        const errors: string[] = [];
+        for (const kind of this.#prefer) {
+            const candidate = instantiate(kind, this.#options);
+            try {
+                await initializeWithTimeout(kind, candidate, canvas);
+                this.#inner = candidate;
+                this.#kind = candidate.kind;
+                return;
+            } catch (err) {
+                candidate.destroy();
+                errors.push(
+                    `${kind}: ${err instanceof Error ? err.message : String(err)}`,
+                );
+            }
+        }
+        throw new Error(
+            `@doki-land/live2d-renderer: no renderer initialized (${errors.join("; ")})`,
+        );
+    }
+
+    createModelDrawPass() {
+        if (!this.#inner) {
+            throw new Error(
+                "@doki-land/live2d-renderer: renderer not initialized",
+            );
+        }
+        return this.#inner.createModelDrawPass();
+    }
+
+    beginFrame(): void {
+        this.#inner?.beginFrame();
+    }
+
+    endFrame(): void {
+        this.#inner?.endFrame();
+    }
+
+    resize(width: number, height: number): void {
+        this.#inner?.resize(width, height);
+    }
+
+    destroy(): void {
+        this.#inner?.destroy();
+        this.#inner = null;
+    }
+}
+
+/**
+ * Create a renderer provider. Actual backend is chosen on `initialize`
+ * (WebGPU → WebGL2 → Canvas2D by default).
+ */
+export function createRenderer(options: CreateRendererOptions = {}): Renderer {
+    const prefer = options.prefer?.length ? options.prefer : DEFAULT_PREFER;
+    return new FallbackRenderer(prefer, options);
+}

package/src/detect-format.ts

@@ -0,0 +1,19 @@
+/**
+ * moc binary format peek. Settings JSON detection lives in live2d-core
+ * (`detectModelSettingsFormat`) so loader and renderer share one helper.
+ */
+
+import type { ModelFormat } from "@doki-land/live2d-core";
+
+export { detectModelSettingsFormat } from "@doki-land/live2d-core";
+
+/** Peek moc2 vs moc3 from magic bytes. */
+export function detectMocBinaryFormat(bytes: ArrayBuffer): ModelFormat | null {
+    if (bytes.byteLength < 4) return null;
+    const u8 = new Uint8Array(bytes, 0, 4);
+    const magic4 = String.fromCharCode(u8[0]!, u8[1]!, u8[2]!, u8[3]!);
+    if (magic4 === "MOC3") return "moc3";
+    const magic3 = String.fromCharCode(u8[0]!, u8[1]!, u8[2]!);
+    if (magic3 === "moc") return "moc2";
+    return null;
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+/**
+ * `@doki-land/live2d-renderer`
+ *
+ * Layout:
+ * - `backends/`  — graphics only (webgpu / webgl2 / canvas2d)
+ * - `moc/`       — moc2 / moc3 decode + model runtimes (not graphics backends)
+ * - `cpu/`       — CPU evaluate + cpu-program fixture codec
+ * - `tests/`     — all vitest suites (package root)
+ */
+
+export {
+    Canvas2DRendererImpl,
+    type Canvas2DRendererOptions,
+    createCanvas2DRenderer,
+    isCanvas2DAvailable,
+} from "./backends/canvas2d.js";
+export {
+    createWebGl2Renderer,
+    isWebGl2Available,
+    WebGl2RendererImpl,
+    type WebGl2RendererOptions,
+} from "./backends/webgl2.js";
+export {
+    createWebGpuRenderer,
+    isWebGpuAvailable,
+    WebGpuRendererImpl,
+    type WebGpuRendererOptions,
+} from "./backends/webgpu.js";
+export {
+    applyWebGl2BlendMode,
+    canvasCompositeForBlendMode,
+    webGpuBlendState,
+} from "./blend.js";
+export {
+    buildClippingContexts,
+    type ClippingContext,
+    type ClippingDrawableRef,
+    type ClippingPartition,
+    calcClippedDrawableBounds,
+    calcVertexBounds,
+    expandBounds,
+    FULL_NDC_BOUNDS,
+    fitClippingContexts,
+    type LaidOutClippingContext,
+    layoutMaskAtlas,
+    layoutMaskAtlasRgba,
+    layoutMaskAtlasUvGrid,
+    MASK_CHANNEL_FLAGS,
+    type MaskAtlasMode,
+    type MaskAtlasOptions,
+    type MaskChannelFlag,
+    type MaskLayoutRect,
+    maskChannelVec4,
+    maskLayoutVec4,
+    partitionForClipping,
+} from "./clipping.js";
+export {
+    CPU_PROGRAM_KIND,
+    type CpuProgramFile,
+    createQuadProgram,
+    isCpuProgramBytes,
+    parseCpuProgram,
+    serializeCpuProgram,
+} from "./cpu/cpu-program.js";
+export {
+    createModelInstance,
+    evaluateFrame,
+    fingerprintSnapshot,
+    setParameterValue,
+} from "./cpu/evaluate.js";
+export {
+    type CreateRendererOptions,
+    createRenderer,
+} from "./create-renderer.js";
+export {
+    detectMocBinaryFormat,
+    detectModelSettingsFormat,
+} from "./detect-format.js";
+export {
+    type DecodedMoc2,
+    type DecodedMoc3,
+    decodeMoc2,
+    decodeMoc3,
+} from "./moc/decode.js";
+export {
+    decodeMoc2ColorComposition,
+    decodeMoc3DrawableFlags,
+    Moc3DrawableFlag,
+} from "./moc/drawable-flags.js";
+export { createMoc2Backend, Moc2Backend } from "./moc/moc2.js";
+export { createMoc3Backend, Moc3Backend } from "./moc/moc3.js";
+export {
+    applyMoc3Glues,
+    loadMoc3Glues,
+    type Moc3GlueDef,
+    type Moc3GluePair,
+    meanGlueSeamDistance,
+} from "./moc/moc3-glue.js";
+export {
+    type ModelBackend,
+    type ModelBackendOptions,
+    type ParameterBinding,
+    selectModelBackend,
+} from "./model-runtime.js";
+export {
+    PREVIEW_FILL,
+    PREVIEW_STROKE,
+    triangleEdgesToLineList,
+} from "./preview-style.js";
+export {
+    BlendMode,
+    type DrawableMesh,
+    type ModelDrawPass,
+    type Renderer,
+    type RendererKind,
+    type TextureData,
+    type WebGl2Renderer,
+    type WebGpuRenderer,
+} from "./types.js";
+
+export const LIVE2D_RENDERER_VERSION = "0.0.0" as const;

package/src/moc/decode.ts

@@ -0,0 +1,73 @@
+/**
+ * moc binary decode: ArrayBuffer → CPU ModelProgram.
+ */
+
+import type { ModelProgram } from "@doki-land/live2d-core";
+import { Moc2Parser } from "./moc2-objects.js";
+import { moc2ModelToProgram } from "./moc2-to-program.js";
+import { parseMoc3Document } from "./moc3-reader.js";
+import { moc3DocumentToProgram } from "./moc3-to-program.js";
+
+export interface DecodedMoc2 {
+    readonly format: "moc2";
+    readonly program: ModelProgram;
+}
+
+export interface DecodedMoc3 {
+    readonly format: "moc3";
+    readonly program: ModelProgram;
+}
+
+function readMagic(bytes: ArrayBuffer): string {
+    if (bytes.byteLength < 4) return "";
+    return String.fromCharCode(...new Uint8Array(bytes, 0, 4));
+}
+
+/** Decode official moc2 (`.moc`) bytes into a default-pose ModelProgram. */
+export async function decodeMoc2(bytes: ArrayBuffer): Promise<DecodedMoc2> {
+    if (bytes.byteLength < 4) {
+        throw new Error("@doki-land/live2d-renderer: truncated moc2 header");
+    }
+    const magic3 = String.fromCharCode(...new Uint8Array(bytes, 0, 3));
+    if (magic3 !== "moc") {
+        throw new Error(
+            `@doki-land/live2d-renderer: unrecognized moc2 bytes (magic=${JSON.stringify(magic3)})`,
+        );
+    }
+    try {
+        const model = new Moc2Parser(bytes).parseModel();
+        const program = moc2ModelToProgram(model);
+        return { format: "moc2", program };
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.startsWith("@doki-land/live2d-renderer:")) throw err;
+        throw new Error(
+            `@doki-land/live2d-renderer: moc2 decode failed: ${msg}`,
+        );
+    }
+}
+
+/**
+ * Decode official moc3 bytes into a ModelProgram.
+ * Applies keyform blending + warp/rotation deformer chains at the given pose
+ * (defaults when called via decodeMoc3).
+ */
+export async function decodeMoc3(bytes: ArrayBuffer): Promise<DecodedMoc3> {
+    const magic = readMagic(bytes);
+    if (magic !== "MOC3") {
+        throw new Error(
+            `@doki-land/live2d-renderer: unrecognized moc3 bytes (magic=${JSON.stringify(magic)})`,
+        );
+    }
+    try {
+        const doc = parseMoc3Document(bytes);
+        const program = moc3DocumentToProgram(doc);
+        return { format: "moc3", program };
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.startsWith("@doki-land/live2d-renderer:")) throw err;
+        throw new Error(
+            `@doki-land/live2d-renderer: moc3 decode failed: ${msg}`,
+        );
+    }
+}

package/src/moc/drawable-flags.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared moc2/moc3 drawable constant-flag decode → blend / invert-mask.
+ */
+
+import { FrameBlendMode } from "@doki-land/live2d-core";
+
+/** Cubism Core constant drawable flag bits (moc3 art_mesh.drawable_flags). */
+export const Moc3DrawableFlag = {
+    BlendAdditive: 1 << 0,
+    BlendMultiplicative: 1 << 1,
+    IsDoubleSided: 1 << 2,
+    IsInvertedMask: 1 << 3,
+} as const;
+
+/** Decode moc3 constant flags into blend + invert-mask. */
+export function decodeMoc3DrawableFlags(flags: number): {
+    blendMode: number;
+    invertedMask: boolean;
+    doubleSided: boolean;
+} {
+    let blendMode: number = FrameBlendMode.Normal;
+    if ((flags & Moc3DrawableFlag.BlendAdditive) !== 0) {
+        blendMode = FrameBlendMode.Additive;
+    } else if ((flags & Moc3DrawableFlag.BlendMultiplicative) !== 0) {
+        blendMode = FrameBlendMode.Multiplicative;
+    }
+    return {
+        blendMode,
+        invertedMask: (flags & Moc3DrawableFlag.IsInvertedMask) !== 0,
+        doubleSided: (flags & Moc3DrawableFlag.IsDoubleSided) !== 0,
+    };
+}
+
+/**
+ * Decode moc2 color-composition enum (after optionFlags bit0).
+ * 0 normal, 1 additive, 2 multiplicative.
+ */
+export function decodeMoc2ColorComposition(composition: number): number {
+    if (composition === 1) return FrameBlendMode.Additive;
+    if (composition === 2) return FrameBlendMode.Multiplicative;
+    return FrameBlendMode.Normal;
+}