@doki-land/live2d-renderer 0.0.18 → 0.0.20

package/src/moc/moc3.ts

@@ -10,7 +10,7 @@ import { detectModelSettingsFormat } from "@doki-land/live2d-core";
 import { isCpuProgramBytes, parseCpuProgram } from "../cpu/cpu-program.js";
 import {
     createModelInstance,
-    evaluateFrame,
+    evaluateFrameInto,
     setParameterValue,
 } from "../cpu/evaluate.js";
 import type {
@@ -21,13 +21,34 @@ import type {
 import type { BlendMode, DrawableMesh } from "../types.js";
 import { cascadedPartOpacity, readMoc3PartTables } from "./moc3-parts.js";
 import { type Moc3Document, parseMoc3Document } from "./moc3-reader.js";
-import { moc3DocumentToProgram } from "./moc3-to-program.js";
+import {
+    evaluateMoc3PoseInto,
+    moc3ArtMeshIndicesInProgramOrder,
+    moc3DocumentToProgram,
+} from "./moc3-to-program.js";
 
-function toDrawableMesh(d: FrameDrawable): DrawableMesh {
-    return {
+interface Moc3State {
+    /** Present for binary MOC3 input; null for cpu-program fixtures. */
+    doc: Moc3Document | null;
+    instance: ModelInstance;
+    meshes: DrawableMesh[];
+    drawView: DrawableMesh[];
+    /** art-mesh index → mesh (binary path); empty for cpu-program. */
+    byArtMesh: Map<number, DrawableMesh>;
+    poseOpacity: Float32Array;
+    poseDirty: boolean;
+    partOpacity: Map<string, number>;
+    bindings: ParameterBinding[];
+    paramIndexById: Map<string, number>;
+}
+
+const stateByModel = new WeakMap<InternalModel, Moc3State>();
+
+function allocateMeshesFromProgram(program: ModelProgram): DrawableMesh[] {
+    return program.drawables.map((d) => ({
         index: d.index,
         textureIndex: d.textureIndex,
-        vertexPositions: d.positions,
+        vertexPositions: new Float32Array(d.positions),
         uvs: d.uvs,
         indices: d.indices,
         opacity: d.opacity,
@@ -37,49 +58,96 @@ function toDrawableMesh(d: FrameDrawable): DrawableMesh {
         dynamicFlag: true,
         maskIndices: [...d.maskIndices],
         visible: d.visible,
-    };
+    }));
+}
+
+function buildBindings(instance: ModelInstance): {
+    bindings: ParameterBinding[];
+    paramIndexById: Map<string, number>;
+} {
+    const bindings: ParameterBinding[] = [];
+    const paramIndexById = new Map<string, number>();
+    for (let i = 0; i < instance.program.parameters.length; i++) {
+        const p = instance.program.parameters[i]!;
+        bindings.push({
+            id: p.id,
+            min: p.min,
+            max: p.max,
+            defaultValue: p.defaultValue,
+            value: instance.parameterValues[i] ?? p.defaultValue,
+        });
+        paramIndexById.set(p.id, i);
+    }
+    return { bindings, paramIndexById };
 }
 
-function paramFingerprint(values: ArrayLike<number>): string {
-    let s = "";
-    for (let i = 0; i < values.length; i++) {
-        s += `${values[i]?.toFixed(5)},`;
+function syncBindingValues(state: Moc3State): void {
+    for (let i = 0; i < state.bindings.length; i++) {
+        const b = state.bindings[i]!;
+        (b as { value: number }).value =
+            state.instance.parameterValues[i] ?? b.defaultValue;
     }
-    return s;
 }
 
-interface Moc3State {
-    /** Present for binary MOC3 input; null for cpu-program fixtures. */
-    doc: Moc3Document | null;
-    instance: ModelInstance;
-    lastFrame: FrameSnapshot | null;
-    bakedFingerprint: string;
-    /** Runtime PartOpacity overrides (id → 0..1). */
-    partOpacity: Map<string, number>;
+function refreshDrawView(state: Moc3State): void {
+    const view = state.drawView;
+    view.length = 0;
+    for (const m of state.meshes) view.push(m);
+    view.sort((a, b) => a.renderOrder - b.renderOrder || a.index - b.index);
 }
 
-const stateByModel = new WeakMap<InternalModel, Moc3State>();
+function applyPartOpacity(state: Moc3State): void {
+    const tables = state.doc ? readMoc3PartTables(state.doc) : null;
+    for (const mesh of state.meshes) {
+        const base = state.poseOpacity[mesh.index] ?? mesh.opacity;
+        if (!tables || state.partOpacity.size === 0) {
+            mesh.opacity = base;
+            continue;
+        }
+        mesh.opacity =
+            base * cascadedPartOpacity(tables, mesh.index, state.partOpacity);
+    }
+}
 
 function bakePose(state: Moc3State): void {
-    if (!state.doc) {
-        state.lastFrame = evaluateFrame(state.instance);
-        return;
-    }
-
-    const values = Float32Array.from(state.instance.parameterValues);
-    const timeSeconds = state.instance.timeSeconds;
-    const fp = paramFingerprint(values);
-    if (fp === state.bakedFingerprint && state.lastFrame) return;
-
-    const program = moc3DocumentToProgram(state.doc, {
-        getParamByIndex: (i) => values[i] ?? 0,
-    });
-    const next = createModelInstance(program);
-    next.parameterValues.set(values);
-    next.timeSeconds = timeSeconds;
-    state.instance = next;
-    state.bakedFingerprint = fp;
-    state.lastFrame = evaluateFrame(next);
+    if (!state.poseDirty) return;
+    if (state.doc) {
+        const values = state.instance.parameterValues;
+        evaluateMoc3PoseInto(
+            state.doc,
+            (i) => values[i] ?? 0,
+            state.byArtMesh,
+            state.poseOpacity,
+        );
+    } else {
+        evaluateFrameInto(state.instance, state.meshes, state.poseOpacity);
+    }
+    refreshDrawView(state);
+    syncBindingValues(state);
+    state.poseDirty = false;
+}
+
+function frameFromMeshes(
+    meshes: readonly DrawableMesh[],
+    timeSeconds: number,
+): FrameSnapshot {
+    const drawables: FrameDrawable[] = [];
+    for (const m of meshes) {
+        drawables.push({
+            index: m.index,
+            textureIndex: m.textureIndex,
+            positions: m.vertexPositions,
+            uvs: m.uvs,
+            indices: m.indices,
+            opacity: m.opacity,
+            blendMode: m.blendMode,
+            renderOrder: m.renderOrder,
+            visible: m.visible,
+            invertedMask: m.invertedMask,
+            maskIndices: m.maskIndices,
+        });
+    }
+    return { timeSeconds, drawables };
 }
 
 /** moc3 model backend for binary `.moc3` input or CPU `.program.json` fixtures. */
@@ -121,18 +189,39 @@ export class Moc3Backend implements ModelBackend {
         }
 
         const instance = createModelInstance(program);
+        const meshes = allocateMeshesFromProgram(program);
+        const byArtMesh = new Map<number, DrawableMesh>();
+        if (doc) {
+            const artOrder = moc3ArtMeshIndicesInProgramOrder(doc);
+            for (let i = 0; i < artOrder.length; i++) {
+                const art = artOrder[i]!;
+                const mesh = meshes[i];
+                if (mesh) byArtMesh.set(art, mesh);
+            }
+        }
+        const poseOpacity = new Float32Array(meshes.length);
+        for (const m of meshes) poseOpacity[m.index] = m.opacity;
+        const { bindings, paramIndexById } = buildBindings(instance);
         const model: InternalModel = {
             id: settings.name ?? settings.url,
             settings,
             format: "moc3",
         };
-        stateByModel.set(model, {
+        const state: Moc3State = {
             doc,
             instance,
-            lastFrame: null,
-            bakedFingerprint: paramFingerprint(instance.parameterValues),
+            meshes,
+            drawView: [],
+            byArtMesh,
+            poseOpacity,
+            poseDirty: true,
             partOpacity: new Map(),
-        });
+            bindings,
+            paramIndexById,
+        };
+        bakePose(state);
+        applyPartOpacity(state);
+        stateByModel.set(model, state);
         return model;
     }
 
@@ -141,54 +230,39 @@ export class Moc3Backend implements ModelBackend {
         if (!state) return;
         state.instance.timeSeconds += deltaTimeSeconds;
         bakePose(state);
-        if (state.lastFrame) {
-            state.lastFrame = {
-                ...state.lastFrame,
-                timeSeconds: state.instance.timeSeconds,
-            };
-        }
+        applyPartOpacity(state);
     }
 
     getDrawables(model: InternalModel): DrawableMesh[] {
         const state = stateByModel.get(model);
         if (!state) return [];
         bakePose(state);
-        const frame = state.lastFrame ?? evaluateFrame(state.instance);
-        state.lastFrame = frame;
-        const tables = state.doc ? readMoc3PartTables(state.doc) : null;
-        return frame.drawables.map((d) => {
-            const mesh = toDrawableMesh(d);
-            if (!tables || state.partOpacity.size === 0) return mesh;
-            const mul = cascadedPartOpacity(tables, d.index, state.partOpacity);
-            return { ...mesh, opacity: mesh.opacity * mul };
-        });
+        applyPartOpacity(state);
+        return state.drawView;
     }
 
     captureFrame(model: InternalModel): FrameSnapshot | null {
         const state = stateByModel.get(model);
         if (!state) return null;
         bakePose(state);
-        const frame = state.lastFrame ?? evaluateFrame(state.instance);
-        state.lastFrame = frame;
-        const tables = state.doc ? readMoc3PartTables(state.doc) : null;
-        if (!tables || state.partOpacity.size === 0) return frame;
-        return {
-            ...frame,
-            drawables: frame.drawables.map((d) => ({
-                ...d,
-                opacity:
-                    d.opacity *
-                    cascadedPartOpacity(tables, d.index, state.partOpacity),
-            })),
-        };
+        applyPartOpacity(state);
+        return frameFromMeshes(state.drawView, state.instance.timeSeconds);
     }
 
     setParameter(model: InternalModel, id: string, value: number): void {
         const state = stateByModel.get(model);
         if (!state) return;
         setParameterValue(state.instance, id, value);
-        state.lastFrame = null;
-        state.bakedFingerprint = "";
+        const index = state.paramIndexById.get(id);
+        if (index !== undefined) {
+            const binding = state.bindings[index];
+            if (binding) {
+                (binding as { value: number }).value =
+                    state.instance.parameterValues[index] ??
+                    binding.defaultValue;
+            }
+        }
+        state.poseDirty = true;
     }
 
     setPartOpacity(model: InternalModel, id: string, value: number): void {
@@ -196,19 +270,20 @@ export class Moc3Backend implements ModelBackend {
         if (!state) return;
         const v = Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
         state.partOpacity.set(id, v);
-        // Opacity is applied in getDrawables; no need to rebake deform.
+    }
+
+    resolveParameter(model: InternalModel, id: string): number | undefined {
+        const state = stateByModel.get(model);
+        if (!state) return undefined;
+        return state.paramIndexById.get(id);
     }
 
     listParameters(model: InternalModel): readonly ParameterBinding[] {
         const state = stateByModel.get(model);
         if (!state) return [];
-        return state.instance.program.parameters.map((p, i) => ({
-            id: p.id,
-            min: p.min,
-            max: p.max,
-            defaultValue: p.defaultValue,
-            value: state.instance.parameterValues[i] ?? p.defaultValue,
-        }));
+        bakePose(state);
+        syncBindingValues(state);
+        return state.bindings;
     }
 
     hitTest(_model: InternalModel, _x: number, _y: number): string | null {
@@ -218,6 +293,10 @@ export class Moc3Backend implements ModelBackend {
     destroyModel(model: InternalModel): void {
         stateByModel.delete(model);
     }
+
+    getResidentInstance(model: InternalModel): ModelInstance | null {
+        return stateByModel.get(model)?.instance ?? null;
+    }
 }
 
 export function createMoc3Backend(): Moc3Backend {

package/src/render/clipping-plan.ts

@@ -0,0 +1,140 @@
+/**
+ * Resident clipping / mask atlas plan.
+ *
+ * Topology (maskIndices / invert / packing options) is compiled once; per frame
+ * only `modelBounds` is refreshed from current vertex positions.
+ */
+
+import type { DrawableMesh } from "../types.js";
+import {
+    type ClippingDrawableRef,
+    type ClippingPartition,
+    calcClippedDrawableBounds,
+    type LaidOutClippingContext,
+    type MaskAtlasOptions,
+    type MaskBoundsMeshRef,
+    type MaskLayoutRect,
+    partitionForClipping,
+} from "./clipping.js";
+
+/** Stable key for mask topology (ignores vertex positions / opacity). */
+export function clippingTopologyKey(
+    drawables: readonly ClippingDrawableRef[],
+): string {
+    let key = `n:${drawables.length}`;
+    for (let i = 0; i < drawables.length; i++) {
+        const d = drawables[i]!;
+        key += `|${d.index}:${d.invertedMask ? 1 : 0}:`;
+        const masks = d.maskIndices;
+        for (let j = 0; j < masks.length; j++) {
+            key += `${masks[j]!},`;
+        }
+    }
+    return key;
+}
+
+function atlasOptionsKey(options: MaskAtlasOptions): string {
+    return `${options.mode ?? "rgba"}:${options.inset ?? ""}:${options.renderTextureCount ?? ""}`;
+}
+
+type ResidentContext = {
+    -readonly [K in keyof LaidOutClippingContext]: LaidOutClippingContext[K];
+} & { modelBounds: MaskLayoutRect };
+
+/**
+ * Update `modelBounds` on resident contexts without reallocating the plan.
+ */
+export function fitClippingContextsInPlace(
+    contexts: readonly ResidentContext[],
+    byIndex: ReadonlyMap<number, MaskBoundsMeshRef>,
+    margin = 0.05,
+): void {
+    for (let i = 0; i < contexts.length; i++) {
+        const ctx = contexts[i]!;
+        ctx.modelBounds = calcClippedDrawableBounds(
+            ctx.clippedIndices,
+            byIndex,
+            margin,
+        );
+    }
+}
+
+/**
+ * Caches atlas layout + mask/clipped sets while drawable mask topology is
+ * unchanged. Call {@link resolve} each frame; call {@link clear} on destroy.
+ */
+export class ResidentClippingPlan {
+    #cacheKey = "";
+    #contexts: ResidentContext[] = [];
+    #clipped: Set<number> = new Set();
+    #maskOnly: Set<number> = new Set();
+    readonly #byIndex = new Map<number, MaskBoundsMeshRef>();
+
+    /**
+     * Returns a partition whose `contexts` array identity is stable across
+     * frames with the same topology. `modelBounds` are refreshed in place.
+     */
+    resolve(
+        drawables: readonly ClippingDrawableRef[],
+        options: MaskAtlasOptions = {},
+    ): ClippingPartition {
+        const nextKey = `${clippingTopologyKey(drawables)}|${atlasOptionsKey(options)}`;
+        if (nextKey !== this.#cacheKey) {
+            const partitioned = partitionForClipping(drawables, options);
+            this.#contexts = partitioned.contexts.map((ctx) => ({
+                key: ctx.key,
+                maskIndices: ctx.maskIndices,
+                clippedIndices: ctx.clippedIndices,
+                invertedMask: ctx.invertedMask,
+                layout: ctx.layout,
+                channelIndex: ctx.channelIndex,
+                channelFlag: ctx.channelFlag,
+                bufferIndex: ctx.bufferIndex,
+                modelBounds: { ...ctx.modelBounds },
+            }));
+            this.#clipped = new Set(partitioned.clipped);
+            this.#maskOnly = new Set(partitioned.maskOnly);
+            this.#cacheKey = nextKey;
+        }
+
+        this.#byIndex.clear();
+        for (let i = 0; i < drawables.length; i++) {
+            const d = drawables[i]!;
+            if ("vertexPositions" in d) {
+                this.#byIndex.set(d.index, d as MaskBoundsMeshRef);
+            }
+        }
+        fitClippingContextsInPlace(this.#contexts, this.#byIndex);
+        return {
+            contexts: this.#contexts,
+            clipped: this.#clipped,
+            maskOnly: this.#maskOnly,
+        };
+    }
+
+    /** Convenience for full drawable meshes (GPU backends). */
+    resolveMeshes(
+        drawables: readonly DrawableMesh[],
+        options: MaskAtlasOptions = {},
+    ): ClippingPartition {
+        return this.resolve(drawables, options);
+    }
+
+    /** True when the last {@link resolve} reused the cached atlas layout. */
+    get hasPlan(): boolean {
+        return this.#cacheKey.length > 0;
+    }
+
+    /** Exposed for tests — context array identity while topology holds. */
+    get residentContexts(): readonly LaidOutClippingContext[] {
+        return this.#contexts;
+    }
+
+    clear(): void {
+        this.#cacheKey = "";
+        this.#contexts = [];
+        this.#clipped = new Set();
+        this.#maskOnly = new Set();
+        this.#byIndex.clear();
+    }
+}

package/src/render/clipping.ts

@@ -412,12 +412,28 @@ export function fitClippingContexts(
     }));
 }
 
-/** Flatten layout to `[x, y, w, h]` for GPU uniforms. */
-export function maskLayoutVec4(layout: MaskLayoutRect): Float32Array {
-    return new Float32Array([layout.x, layout.y, layout.width, layout.height]);
+/** Flatten layout to `[x, y, w, h]` for GPU uniforms. Reuses `into` when provided. */
+export function maskLayoutVec4(
+    layout: MaskLayoutRect,
+    into?: Float32Array,
+): Float32Array {
+    const out = into && into.length >= 4 ? into : new Float32Array(4);
+    out[0] = layout.x;
+    out[1] = layout.y;
+    out[2] = layout.width;
+    out[3] = layout.height;
+    return out;
 }
 
-/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. */
-export function maskChannelVec4(flag: MaskChannelFlag): Float32Array {
-    return new Float32Array([flag[0], flag[1], flag[2], flag[3]]);
+/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. Reuses `into` when provided. */
+export function maskChannelVec4(
+    flag: MaskChannelFlag,
+    into?: Float32Array,
+): Float32Array {
+    const out = into && into.length >= 4 ? into : new Float32Array(4);
+    out[0] = flag[0];
+    out[1] = flag[1];
+    out[2] = flag[2];
+    out[3] = flag[3];
+    return out;
 }

package/src/render/mesh-interleave.ts

@@ -0,0 +1,28 @@
+/**
+ * Pos/UV interleave with optional resident output buffer (GPU upload scratch).
+ */
+
+/** Interleave `[x,y]` + `[u,v]` into `[x,y,u,v,…]`. Reuses `into` when large enough. */
+export function interleavePosUv(
+    positions: Float32Array,
+    uvs: Float32Array,
+    into?: Float32Array,
+): Float32Array {
+    const n = Math.floor(positions.length / 2);
+    const need = n * 4;
+    const out = into && into.length >= need ? into : new Float32Array(need);
+    for (let i = 0; i < n; i++) {
+        const o = i * 4;
+        const p = i * 2;
+        out[o] = positions[p]!;
+        out[o + 1] = positions[p + 1]!;
+        out[o + 2] = uvs[p] ?? 0;
+        out[o + 3] = uvs[p + 1] ?? 0;
+    }
+    return out;
+}
+
+/** Byte length of the live interleaved prefix (vertexCount * 16). */
+export function interleaveByteLength(positions: Float32Array): number {
+    return Math.floor(positions.length / 2) * 16;
+}

package/src/runtime/model-runtime.ts

@@ -69,6 +69,12 @@ export interface ModelBackend {
     /** Optional PartOpacity override (moc3 parts / pose / motion). */
     setPartOpacity?(model: InternalModel, id: string, value: number): void;
 
+    /**
+     * Resolve parameter id → index (O(1) after load).
+     * Used by motion blend / hosts instead of `listParameters().find`.
+     */
+    resolveParameter?(model: InternalModel, id: string): number | undefined;
+
     listParameters?(model: InternalModel): readonly ParameterBinding[];
 }
 

package/src/types.ts

@@ -36,7 +36,7 @@ export interface TextureData {
 export interface ModelDrawPass {
     setTextures(textures: TextureData[]): void;
 
-    draw(drawables: DrawableMesh[], modelMatrix: Float32Array): void;
+    draw(drawables: readonly DrawableMesh[], modelMatrix: Float32Array): void;
 
     destroy(): void;
 }