@doki-land/live2d-renderer 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -34,7 +34,7 @@ interface TextureData {
 }
 interface ModelDrawPass {
     setTextures(textures: TextureData[]): void;
-    draw(drawables: DrawableMesh[], modelMatrix: Float32Array): void;
+    draw(drawables: readonly DrawableMesh[], modelMatrix: Float32Array): void;
     destroy(): void;
 }
 /** Top-level renderer bound to a canvas. */
@@ -138,123 +138,6 @@ declare class WebGpuRendererImpl implements WebGpuRenderer {
 declare function createWebGpuRenderer(options?: WebGpuRendererOptions): WebGpuRenderer;
 declare function isWebGpuAvailable(): boolean;
 
-/**
- * Map Live2D blend modes to WebGL / Canvas compositing.
- */
-
-/** Apply premultiplied-friendly Live2D blend factors on a WebGL2 context. */
-declare function applyWebGl2BlendMode(gl: WebGL2RenderingContext, mode: BlendMode): void;
-/** Canvas2D globalCompositeOperation for Live2D blend modes. */
-declare function canvasCompositeForBlendMode(mode: BlendMode): GlobalCompositeOperation;
-/** WebGPU blend state for Live2D modes (straight alpha draw path). */
-declare function webGpuBlendState(mode: BlendMode): GPUBlendState;
-
-/**
- * Clipping-mask context grouping + mask atlas layout.
- *
- * Two packing modes:
- * - `uv-grid`: √N UV cells, alpha channel only (Canvas2D / simple path)
- * - `rgba`: Cubism-style channel × UV packing (≤4 → full UV on R/G/B/A)
- */
-interface ClippingDrawableRef {
-    readonly index: number;
-    readonly maskIndices: readonly number[];
-    readonly invertedMask: boolean;
-}
-interface ClippingContext {
-    /** Stable key: invert flag + sorted mask drawable indices. */
-    readonly key: string;
-    readonly maskIndices: readonly number[];
-    readonly clippedIndices: readonly number[];
-    readonly invertedMask: boolean;
-}
-/** UV-space rectangle inside the shared mask atlas (0..1). */
-interface MaskLayoutRect {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/** R/G/B/A write/sample selector (Cubism channelFlag). */
-type MaskChannelFlag = readonly [number, number, number, number];
-declare const MASK_CHANNEL_FLAGS: readonly MaskChannelFlag[];
-type MaskAtlasMode = "uv-grid" | "rgba";
-interface MaskAtlasOptions {
-    /** Packing strategy. Default `rgba` (Cubism density). */
-    readonly mode?: MaskAtlasMode;
-    /** Cell inset for `uv-grid` only (reduces neighbour bleed). */
-    readonly inset?: number;
-    /** Render-texture count for `rgba` (default 1 → max 36). */
-    readonly renderTextureCount?: number;
-}
-interface LaidOutClippingContext extends ClippingContext {
-    readonly layout: MaskLayoutRect;
-    /** 0=R … 3=A. `uv-grid` always uses A (3). */
-    readonly channelIndex: number;
-    readonly channelFlag: MaskChannelFlag;
-    /** Cubism multi-RT buffer index; currently always 0. */
-    readonly bufferIndex: number;
-    /**
-     * Expanded AABB of clipped drawables in vertex/NDC space.
-     * Mask write/sample map this rect into `layout` (Cubism bounds-fit).
-     * Default before `fitClippingContexts`: full NDC (-1..1)².
-     */
-    readonly modelBounds: MaskLayoutRect;
-}
-/** Full clip-space quad used when no valid clipped bounds exist. */
-declare const FULL_NDC_BOUNDS: MaskLayoutRect;
-interface ClippingPartition {
-    readonly contexts: readonly LaidOutClippingContext[];
-    /** Drawables that consume a mask (drawn after mask pass). */
-    readonly clipped: ReadonlySet<number>;
-    /** Drawables used as masks (mask buffer only, not color target). */
-    readonly maskOnly: ReadonlySet<number>;
-}
-/**
- * Group drawables that consume clipping masks into shared contexts.
- * Drawables with empty maskIndices are omitted.
- */
-declare function buildClippingContexts(drawables: readonly ClippingDrawableRef[]): ClippingContext[];
-/**
- * Pack clipping contexts into a square-ish UV grid on one atlas (alpha only).
- */
-declare function layoutMaskAtlasUvGrid(contexts: readonly ClippingContext[], options?: {
-    inset?: number;
-}): LaidOutClippingContext[];
-/**
- * Cubism `setupLayoutBounds`: pack across R/G/B/A then UV cells.
- * Single RT → max 36 (4×9); multi-RT → 32 per sheet.
- */
-declare function layoutMaskAtlasRgba(contexts: readonly ClippingContext[], options?: {
-    renderTextureCount?: number;
-}): LaidOutClippingContext[];
-/** Pack clipping contexts (default: Cubism RGBA density). */
-declare function layoutMaskAtlas(contexts: readonly ClippingContext[], options?: MaskAtlasOptions): LaidOutClippingContext[];
-/** Partition drawables and assign atlas layouts. */
-declare function partitionForClipping(drawables: readonly ClippingDrawableRef[], options?: MaskAtlasOptions): ClippingPartition;
-/** Axis-aligned bounds of interleaved xy vertex positions. */
-declare function calcVertexBounds(positions: Float32Array): MaskLayoutRect | null;
-/** Expand bounds by a relative margin on each axis (Cubism uses 0.05). */
-declare function expandBounds(bounds: MaskLayoutRect, margin?: number): MaskLayoutRect;
-interface MaskBoundsMeshRef {
-    readonly index: number;
-    readonly vertexPositions: Float32Array;
-}
-/**
- * Union AABB of clipped drawables, expanded by margin (Cubism
- * `calcClippedDrawableTotalBounds` + 0.05 expand).
- */
-declare function calcClippedDrawableBounds(clippedIndices: readonly number[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): MaskLayoutRect;
-/**
- * Attach per-context `modelBounds` so mask write/sample fit the clipped
- * drawable AABB into the atlas cell (higher mask texel density).
- */
-declare function fitClippingContexts(contexts: readonly LaidOutClippingContext[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): LaidOutClippingContext[];
-/** Flatten layout to `[x, y, w, h]` for GPU uniforms. */
-declare function maskLayoutVec4(layout: MaskLayoutRect): Float32Array;
-/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. */
-declare function maskChannelVec4(flag: MaskChannelFlag): Float32Array;
-
 declare const CPU_PROGRAM_KIND: "cpu-program";
 interface CpuProgramFile {
     readonly kind: typeof CPU_PROGRAM_KIND;
@@ -294,27 +177,11 @@ declare function parseCpuProgram(bytes: ArrayBuffer): ModelProgram;
 /** Create a runtime instance with default parameter values. */
 declare function createModelInstance(program: ModelProgram): ModelInstance;
 declare function setParameterValue(instance: ModelInstance, parameterId: string, value: number): void;
-/** CPU deform 鈫?FrameSnapshot. */
+/** CPU deform → FrameSnapshot. */
 declare function evaluateFrame(instance: ModelInstance): FrameSnapshot;
 /** Stable fingerprint for golden tests (positions + topology). */
 declare function fingerprintSnapshot(snapshot: FrameSnapshot): string;
 
-interface CreateRendererOptions {
-    /**
-     * Backend try order at initialize time.
-     * Default: `["webgpu", "webgl2", "canvas2d"]`.
-     */
-    prefer?: RendererKind[];
-    webgpu?: WebGpuRendererOptions;
-    webgl2?: WebGl2RendererOptions;
-    canvas2d?: Canvas2DRendererOptions;
-}
-/**
- * Create a renderer provider. Actual backend is chosen on `initialize`
- * (WebGPU → WebGL2 → Canvas2D by default).
- */
-declare function createRenderer(options?: CreateRendererOptions): Renderer;
-
 /**
  * moc binary format peek. Settings JSON detection lives in live2d-core
  * (`detectModelSettingsFormat`) so loader and renderer share one helper.
@@ -412,6 +279,11 @@ interface ModelBackend {
     setParameter?(model: InternalModel, id: string, value: number): void;
     /** 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[];
 }
 declare function selectModelBackend(backends: ModelBackend[], json: unknown): ModelBackend;
@@ -425,9 +297,12 @@ declare class Moc2Backend implements ModelBackend {
     getDrawables(model: InternalModel): DrawableMesh[];
     captureFrame(model: InternalModel): FrameSnapshot | null;
     setParameter(model: InternalModel, id: string, value: number): void;
+    resolveParameter(model: InternalModel, id: string): number | undefined;
     listParameters(model: InternalModel): readonly ParameterBinding[];
     hitTest(_model: InternalModel, _x: number, _y: number): string | null;
     destroyModel(model: InternalModel): void;
+    /** Test/harness: stable program + instance refs. */
+    getResidentInstance(model: InternalModel): ModelInstance | null;
 }
 declare function createMoc2Backend(): Moc2Backend;
 
@@ -441,9 +316,11 @@ declare class Moc3Backend implements ModelBackend {
     captureFrame(model: InternalModel): FrameSnapshot | null;
     setParameter(model: InternalModel, id: string, value: number): void;
     setPartOpacity(model: InternalModel, id: string, value: number): void;
+    resolveParameter(model: InternalModel, id: string): number | undefined;
     listParameters(model: InternalModel): readonly ParameterBinding[];
     hitTest(_model: InternalModel, _x: number, _y: number): string | null;
     destroyModel(model: InternalModel): void;
+    getResidentInstance(model: InternalModel): ModelInstance | null;
 }
 declare function createMoc3Backend(): Moc3Backend;
 
@@ -522,6 +399,123 @@ declare function applyMoc3Glues(positionsByMesh: Map<number, Float32Array>, glue
 /** Mean Euclidean distance between glued vertex pairs (for tests). */
 declare function meanGlueSeamDistance(positionsByMesh: ReadonlyMap<number, Float32Array>, glue: Moc3GlueDef): number;
 
+/**
+ * Map Live2D blend modes to WebGL / Canvas compositing.
+ */
+
+/** Apply premultiplied-friendly Live2D blend factors on a WebGL2 context. */
+declare function applyWebGl2BlendMode(gl: WebGL2RenderingContext, mode: BlendMode): void;
+/** Canvas2D globalCompositeOperation for Live2D blend modes. */
+declare function canvasCompositeForBlendMode(mode: BlendMode): GlobalCompositeOperation;
+/** WebGPU blend state for Live2D modes (straight alpha draw path). */
+declare function webGpuBlendState(mode: BlendMode): GPUBlendState;
+
+/**
+ * Clipping-mask context grouping + mask atlas layout.
+ *
+ * Two packing modes:
+ * - `uv-grid`: √N UV cells, alpha channel only (Canvas2D / simple path)
+ * - `rgba`: Cubism-style channel × UV packing (≤4 → full UV on R/G/B/A)
+ */
+interface ClippingDrawableRef {
+    readonly index: number;
+    readonly maskIndices: readonly number[];
+    readonly invertedMask: boolean;
+}
+interface ClippingContext {
+    /** Stable key: invert flag + sorted mask drawable indices. */
+    readonly key: string;
+    readonly maskIndices: readonly number[];
+    readonly clippedIndices: readonly number[];
+    readonly invertedMask: boolean;
+}
+/** UV-space rectangle inside the shared mask atlas (0..1). */
+interface MaskLayoutRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** R/G/B/A write/sample selector (Cubism channelFlag). */
+type MaskChannelFlag = readonly [number, number, number, number];
+declare const MASK_CHANNEL_FLAGS: readonly MaskChannelFlag[];
+type MaskAtlasMode = "uv-grid" | "rgba";
+interface MaskAtlasOptions {
+    /** Packing strategy. Default `rgba` (Cubism density). */
+    readonly mode?: MaskAtlasMode;
+    /** Cell inset for `uv-grid` only (reduces neighbour bleed). */
+    readonly inset?: number;
+    /** Render-texture count for `rgba` (default 1 → max 36). */
+    readonly renderTextureCount?: number;
+}
+interface LaidOutClippingContext extends ClippingContext {
+    readonly layout: MaskLayoutRect;
+    /** 0=R … 3=A. `uv-grid` always uses A (3). */
+    readonly channelIndex: number;
+    readonly channelFlag: MaskChannelFlag;
+    /** Cubism multi-RT buffer index; currently always 0. */
+    readonly bufferIndex: number;
+    /**
+     * Expanded AABB of clipped drawables in vertex/NDC space.
+     * Mask write/sample map this rect into `layout` (Cubism bounds-fit).
+     * Default before `fitClippingContexts`: full NDC (-1..1)².
+     */
+    readonly modelBounds: MaskLayoutRect;
+}
+/** Full clip-space quad used when no valid clipped bounds exist. */
+declare const FULL_NDC_BOUNDS: MaskLayoutRect;
+interface ClippingPartition {
+    readonly contexts: readonly LaidOutClippingContext[];
+    /** Drawables that consume a mask (drawn after mask pass). */
+    readonly clipped: ReadonlySet<number>;
+    /** Drawables used as masks (mask buffer only, not color target). */
+    readonly maskOnly: ReadonlySet<number>;
+}
+/**
+ * Group drawables that consume clipping masks into shared contexts.
+ * Drawables with empty maskIndices are omitted.
+ */
+declare function buildClippingContexts(drawables: readonly ClippingDrawableRef[]): ClippingContext[];
+/**
+ * Pack clipping contexts into a square-ish UV grid on one atlas (alpha only).
+ */
+declare function layoutMaskAtlasUvGrid(contexts: readonly ClippingContext[], options?: {
+    inset?: number;
+}): LaidOutClippingContext[];
+/**
+ * Cubism `setupLayoutBounds`: pack across R/G/B/A then UV cells.
+ * Single RT → max 36 (4×9); multi-RT → 32 per sheet.
+ */
+declare function layoutMaskAtlasRgba(contexts: readonly ClippingContext[], options?: {
+    renderTextureCount?: number;
+}): LaidOutClippingContext[];
+/** Pack clipping contexts (default: Cubism RGBA density). */
+declare function layoutMaskAtlas(contexts: readonly ClippingContext[], options?: MaskAtlasOptions): LaidOutClippingContext[];
+/** Partition drawables and assign atlas layouts. */
+declare function partitionForClipping(drawables: readonly ClippingDrawableRef[], options?: MaskAtlasOptions): ClippingPartition;
+/** Axis-aligned bounds of interleaved xy vertex positions. */
+declare function calcVertexBounds(positions: Float32Array): MaskLayoutRect | null;
+/** Expand bounds by a relative margin on each axis (Cubism uses 0.05). */
+declare function expandBounds(bounds: MaskLayoutRect, margin?: number): MaskLayoutRect;
+interface MaskBoundsMeshRef {
+    readonly index: number;
+    readonly vertexPositions: Float32Array;
+}
+/**
+ * Union AABB of clipped drawables, expanded by margin (Cubism
+ * `calcClippedDrawableTotalBounds` + 0.05 expand).
+ */
+declare function calcClippedDrawableBounds(clippedIndices: readonly number[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): MaskLayoutRect;
+/**
+ * Attach per-context `modelBounds` so mask write/sample fit the clipped
+ * drawable AABB into the atlas cell (higher mask texel density).
+ */
+declare function fitClippingContexts(contexts: readonly LaidOutClippingContext[], byIndex: ReadonlyMap<number, MaskBoundsMeshRef>, margin?: number): LaidOutClippingContext[];
+/** Flatten layout to `[x, y, w, h]` for GPU uniforms. */
+declare function maskLayoutVec4(layout: MaskLayoutRect): Float32Array;
+/** Flatten channel flag to `[r, g, b, a]` for GPU uniforms. */
+declare function maskChannelVec4(flag: MaskChannelFlag): Float32Array;
+
 /** Shared untextured preview colors (Canvas2D / WebGL2 / WebGPU parity). */
 declare const PREVIEW_FILL: {
     readonly r: number;
@@ -538,6 +532,22 @@ declare const PREVIEW_STROKE: {
 /** Expand triangle indices into a line-list (each edge twice-wound). */
 declare function triangleEdgesToLineList(indices: Uint16Array): Uint16Array;
 
+interface CreateRendererOptions {
+    /**
+     * Backend try order at initialize time.
+     * Default: `["webgpu", "webgl2", "canvas2d"]`.
+     */
+    prefer?: RendererKind[];
+    webgpu?: WebGpuRendererOptions;
+    webgl2?: WebGl2RendererOptions;
+    canvas2d?: Canvas2DRendererOptions;
+}
+/**
+ * Create a renderer provider. Actual backend is chosen on `initialize`
+ * (WebGPU → WebGL2 → Canvas2D by default).
+ */
+declare function createRenderer(options?: CreateRendererOptions): Renderer;
+
 /** One-time decode of moc bytes for stage-level {@link ModelAsset} sharing. */
 declare function compileSharedModelCompile(settings: ModelSettings, mocBytes: ArrayBuffer): SharedModelCompile;