@taole/giftstage 0.1.28 → 0.1.29

package/README.md

@@ -4,7 +4,8 @@
 
 - `SVGA`
 - `VAP / VAPX`
-- 透明视频 `AlphaVideo`
+- 透明视频 `AlphaVideo`
+- 静态图片 `Image`
 
 底层支持：
 
@@ -16,7 +17,7 @@
 
 - 直播间礼物
 - 大批同屏动画
-- 需要统一接入 `SVGA / VAP / 透明视频` 的业务场景
+- 需要统一接入 `SVGA / VAP / 透明视频 / 图片` 的业务场景
 
 ## npm 包信息
 
@@ -36,14 +37,15 @@ const { GiftStage } = require('@taole/giftstage');
 
 ## 特性
 
-- 统一 API：`addGift()` 即可播放三类礼物
+- 统一 API：`addGift()` 即可播放四类礼物
 - `SVGA` 支持 Worker 解析、atlas 缓存、slot 替换
 - `VAP / AlphaVideo` 支持实验性的 `WebCodecs` 和稳定的 `HTMLVideoElement` 双路径
 - 同源视频播放实例、纹理、资源复用
 - 内存 LRU 缓存，默认 `128MB`
 - `IndexedDB` 磁盘 LRU 缓存，默认 `2048MB`
-- `x / y` 支持百分比定位
-- `width / height` 支持按礼物原始尺寸自动补全
+- `x / y` 支持百分比定位
+- `width / height` 支持按礼物原始尺寸自动补全
+- 四类礼物共用位移、缩放、透明度、旋转、层级和销毁生命周期
 
 ## 安装
 
@@ -191,8 +193,9 @@ Promise<GiftHandle>;
 
 - `gift.id`
 - `gift.type`
-- `gift.pause()`
-- `gift.resume()`
+- `gift.pause()`
+- `gift.resume()`
+  - 暂停期间礼物播放时钟、图片 `duration` 和后置动画都会冻结
 - `gift.destroy()`
   - 立即移除当前礼物
 - `gift.animate(stepOrSteps?)`
@@ -237,7 +240,7 @@ Promise<GiftHandle>;
 
 ### 通用参数
 
-- `type: 'svga' | 'vap' | 'alphaVideo'`
+- `type: 'svga' | 'vap' | 'alphaVideo' | 'image'`
 - `source: string | ArrayBuffer`
 - `x: number | \`${number}%\``
 - `y: number | \`${number}%\``
@@ -245,25 +248,37 @@ Promise<GiftHandle>;
 - `width?: number`
 - `height?: number`
 - `useOriginalSize?: boolean`
-- `objectFit?: 'contain' | 'cover' | 'fill'`
+- `objectFit?: 'contain' | 'cover'`
 - `loop?: number`
   - `0` 表示无限循环
 - `opacity?: number`
   - 全局透明度，范围 `0 ~ 1`，默认 `1`
-- `videoRGBAlphaMode?: 'straight' | 'premultiplied'`
-  - 仅用于 `vap` / `alphaVideo` 分离 Alpha 视频源，默认 `premultiplied`
-  - `straight`：RGB 区域尚未乘独立 Alpha，播放器负责预乘
-  - `premultiplied`：RGB 区域在制作阶段已经乘过独立 Alpha，播放器不会再次相乘
-  - 该参数只描述输入视频；最终画布仍统一输出预乘 Alpha
-- `clearsAfterStop?: boolean`
+- `rotation?: number`
+  - 初始旋转弧度；屏幕坐标中正值为顺时针
+- `transformOrigin?: { x: number | \`${number}%\`; y: number | \`${number}%\` }`
+  - 相对未缩放礼物框左上角，默认 `50% / 50%`
+  - 数值使用 CSS 像素；允许负值或超过礼物宽高，用于绕框外点公转
+- `videoRGBAlphaMode?: 'straight' | 'premultiplied'`
+  - 仅用于 `vap` / `alphaVideo` 分离 Alpha 视频源，默认 `premultiplied`
+  - `straight`：RGB 区域尚未乘独立 Alpha，播放器负责预乘
+  - `premultiplied`：RGB 区域在制作阶段已经乘过独立 Alpha，播放器不会再次相乘
+  - 该参数只描述输入视频；最终画布仍统一输出预乘 Alpha
+- `clearsAfterStop?: boolean`
   - 播放结束后，是否自动移除礼物
   - 默认 `true`，传 `false` 时会停留最后一帧，方便后续继续调用 `gift.animate(...).start()`
-- `mute?: boolean`
-- `onComplete?: (gift) => void`
+- `mute?: boolean`
+- `onComplete?: (gift) => void`
+
+图片专用参数：
+
+- `duration?: number`
+  - 单位毫秒；正数到期后触发 `onComplete`，并遵循 `clearsAfterStop`
+  - 不传或传非正数时持续显示到 `destroy()`；加载完成后 `afterGiftComplete` 可立即继续，但不会自动触发 `onComplete`
+  - `image` 忽略 `loop` 和 `mute`
 
 层级规则：
 
-- `zIndex` 在 `SVGA / VAP / AlphaVideo` 三种礼物间通用
+- `zIndex` 在 `SVGA / VAP / AlphaVideo / Image` 四种礼物间通用
 - 数值越大，渲染越靠上
 - 同层级下，后 `addGift()` 的礼物会覆盖先添加的礼物
 
@@ -353,7 +368,7 @@ transform: translate(-50%, -50%);
 
 如果是数值，则继续按原来的像素坐标语义处理。
 
-## 三类礼物示例
+## 四类礼物示例
 
 ### 播放 SVGA
 
@@ -378,15 +393,15 @@ await stage.addGift({
   config: 'https://example.com/demo.json',
   x: 20,
   y: 20,
-  width: 400,
-  height: 220,
-  // 默认 premultiplied；RGB 尚未乘独立 Alpha 的视频源需显式传 straight
-  videoRGBAlphaMode: 'premultiplied',
-  loop: 0,
-});
+  width: 400,
+  height: 220,
+  // 默认 premultiplied；RGB 尚未乘独立 Alpha 的视频源需显式传 straight
+  videoRGBAlphaMode: 'premultiplied',
+  loop: 0,
+});
 ```
 
-### 播放透明视频
+### 播放透明视频
 
 ```ts
 await stage.addGift({
@@ -394,19 +409,36 @@ await stage.addGift({
   source: 'https://example.com/demo.mp4',
   x: 20,
   y: 20,
-  width: 400,
-  height: 220,
-  // 默认 premultiplied；未预乘的视频源改为 straight
-  videoRGBAlphaMode: 'premultiplied',
-  loop: 0,
+  width: 400,
+  height: 220,
+  // 默认 premultiplied；未预乘的视频源改为 straight
+  videoRGBAlphaMode: 'premultiplied',
+  loop: 0,
 });
-```
+```
+
+### 播放图片
+
+`source` 首版支持 URL 和 `ArrayBuffer`。URL 图片会按地址共享 GPU 纹理并引用计数；图片按静态帧处理，不保证 GIF / WebP 动画播放。跨域 URL 必须允许匿名 CORS 读取。
+
+```ts
+const avatar = await stage.addGift({
+  type: 'image',
+  source: 'https://example.com/avatar.png',
+  x: '50%',
+  y: '50%',
+  width: 100,
+  height: 100,
+  objectFit: 'cover',
+  duration: 5000,
+});
+```
 
 ## 动画控制
 
 ### 链式动画
 
-`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放和改变透明度；多个 `to()` / `then()` 会按顺序播放：
+`addGift()` 返回的 `GiftHandle` 支持 `animate()`。一次 `to()` 是组合动画，同一步里可以同时移动、缩放、改变透明度和旋转；多个 `to()` / `then()` 会按顺序播放。`rotationTo` 直接按数值线性插值，不做最短角度归一化，因此可以明确表达多圈旋转：
 
 ```ts
 const gift = await stage.addGift({
@@ -423,8 +455,9 @@ await gift
   .animate()
   .to({
     flyTo: { x: 200, y: 240 },
-    scaleTo: 0.8,
-    opacity: 0.6,
+    scaleTo: 0.8,
+    opacity: 0.6,
+    rotationTo: Math.PI * 4,
     duration: 500,
   })
   .then({
@@ -442,7 +475,27 @@ await gift
     console.log('chain complete', g.id);
   })
   .start();
-```
+```
+
+### 绕外部中心旋转
+
+下面的礼物初始位于舞台中心右侧 200px，旋转中心通过框外坐标指回舞台中心：
+
+```ts
+const orbitGift = await stage.addGift({
+  type: 'image',
+  source: 'https://example.com/gift.png',
+  x: container.clientWidth / 2 + 150,
+  y: '50%',
+  width: 100,
+  height: 100,
+  transformOrigin: { x: -150, y: '50%' },
+});
+
+await orbitGift
+  .animate({ rotationTo: Math.PI * 2, duration: 1200 })
+  .start();
+```
 
 也可以传入单步或数组：
 

package/dist/core/audio-manager.d.ts

@@ -0,0 +1,19 @@
+import type { GiftSlot, GiftHandle } from '../types';
+export declare class AudioManager {
+    private ctx;
+    private decodedCache;
+    private activeSources;
+    private globalMute;
+    private gainNode;
+    private ensureContext;
+    decodeAudio(key: string, data: ArrayBuffer): Promise<void>;
+    /**
+     * Frame-synced playback: start audio on startFrame, stop on endFrame.
+     * Matches SVGAPlayer-Web-master Canvas/renderer.js playAudio() pattern.
+     */
+    tickFrame(slot: GiftSlot, currentFrame: number, _handle: GiftHandle): void;
+    private startAudio;
+    stopAllForGift(giftId: string): void;
+    setMute(mute: boolean): void;
+    destroy(): void;
+}

package/dist/core/gift-stage.d.ts

@@ -0,0 +1,117 @@
+import type { GiftStageOptions, AddGiftOptions, GiftHandle, BackendType } from '../types';
+export declare function resolveResourcePipelineConcurrency(explicit: number | undefined, hardwareConcurrency?: number | undefined): number;
+export declare class GiftStage {
+    private static readonly SVGA_ATLAS_MAX_SIZE;
+    private static readonly SVGA_ATLAS_PADDING;
+    private static readonly DEFAULT_SHARED_VIDEO_PLAYBACK_WINDOW_MS;
+    private static readonly DEFAULT_RESOURCE_CACHE_MEMORY_BYTES;
+    private static readonly DEFAULT_RESOURCE_CACHE_PERSISTENT_BYTES;
+    private readonly sharedSVGAEntities;
+    private readonly pendingSharedSVGAEntities;
+    private readonly sharedVideoSources;
+    private readonly sharedHtmlVideos;
+    private readonly sharedVideoTextures;
+    private readonly pendingSharedHtmlVideos;
+    private readonly sharedImageTextures;
+    private readonly pendingSharedImageTextures;
+    private readonly sharedWebCodecsPlaybacks;
+    private readonly pendingSharedWebCodecsPlaybacks;
+    private readonly sharedWebCodecsSurfaces;
+    private readonly completedPlaybackSlots;
+    private readonly playbackCompleteWaiters;
+    private canvas;
+    private backend;
+    private manager;
+    private options;
+    /** Resolves when WebGPU/WebGL backend + WASM are ready; safe to `await` before `addGift`. */
+    readonly ready: Promise<void>;
+    private destroyed;
+    private resizeObserver;
+    private nextRenderOrder;
+    private nextSharedWebCodecsPlaybackId;
+    private nextSharedWebCodecsSurfaceId;
+    private readonly onWindowLayout;
+    constructor(options: GiftStageOptions);
+    private backingStoreDpr;
+    private syncCanvasSize;
+    private resourcePipelineConcurrency;
+    private init;
+    private svgaParseOptions;
+    private svgaAtlasFrameBudgetMs;
+    private svgaClipFrameBudgetMs;
+    private isSlotLoadActive;
+    private assertSlotLoadActive;
+    private isLoadCanceled;
+    private currentCanvasCssSize;
+    private resolveGiftIntrinsicSize;
+    private normalizeAddGiftOptions;
+    private resolveAnimationStepTarget;
+    private runGiftAnimationStep;
+    private createGiftAnimationChain;
+    addGift(options: AddGiftOptions): Promise<GiftHandle>;
+    private loadSVGA;
+    private acquireSharedSVGAEntity;
+    private waitForPendingSharedSVGAEntity;
+    private buildSharedSVGAEntity;
+    private releaseSharedSVGAEntity;
+    private createCachedSVGAAtlasTextures;
+    private deleteSVGAAtlasTextures;
+    private deleteSVGAAtlasResultTextures;
+    private finishLoadSVGA;
+    private svgaAtlasMaxSize;
+    private buildSVGAAtlasIfNeeded;
+    private svgaAtlasMaxPages;
+    private shouldTryWebCodecs;
+    /** DevTools: filter by `[GiftStage]` to see WebCodecs vs &lt;video&gt; per gift. */
+    private logPlaybackBackend;
+    private tryWebCodecsPlayback;
+    private acquireWebCodecsPlayback;
+    private acquireSharedWebCodecsPlayback;
+    private createPendingSharedWebCodecsPlayback;
+    private waitForPendingSharedWebCodecsPlayback;
+    private releaseSharedWebCodecsPlayback;
+    private attachWebCodecsPlayback;
+    private releaseAttachedWebCodecsPlayback;
+    private acquireSharedWebCodecsSurface;
+    private retainSharedWebCodecsSurface;
+    private createSharedWebCodecsSurface;
+    private releaseSharedWebCodecsSurface;
+    private attachSharedWebCodecsSurface;
+    private loadVAP;
+    private createVAPMixResourceTextures;
+    private loadAlphaVideo;
+    /**
+     * Some mobile WebKit builds ignore or partially apply `video.loop`; `ended` still fires once.
+     * Drive repeat / infinite playback explicitly from `ended` (aligns with SVGA `loop`: 0 = ∞, default 1).
+     */
+    private bindVideoLoopOnEnded;
+    private createVideo;
+    private waitVideoMetadata;
+    private probeVideoNaturalSize;
+    private acquireVideoPlaybackSource;
+    private normalizeSharedVideoSourceKey;
+    private fetchSharedVideoSource;
+    private releaseSharedVideoSource;
+    private tryAcquireSharedHtmlVideo;
+    private acquireSharedVideoTexture;
+    private acquireImageTexture;
+    private releaseSharedImageTexture;
+    private releaseSharedVideoTexture;
+    private releaseSharedHtmlVideo;
+    /**
+     * After `play()`, wait until at least one frame is presented so WebGPU
+     * `copyExternalImageToTexture(<video>)` can import (avoids “no back resource” / early return).
+     */
+    private waitForFirstVideoFrame;
+    private waitVideoReady;
+    removeGift(id: string): void;
+    removeAll(): void;
+    pause(): void;
+    resume(): void;
+    get activeCount(): number;
+    get backendType(): BackendType;
+    destroy(): void;
+    private markGiftPlaybackComplete;
+    private resolveGiftPlaybackWaiters;
+    private waitForGiftPlaybackComplete;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { GiftStage } from './gift-stage';
+export { RenderManager } from './render-manager';
+export { AudioManager } from './audio-manager';
+export { PostAnimator } from './post-animator';

package/dist/core/post-animator.d.ts

@@ -0,0 +1,43 @@
+import type { GiftSlot } from '../types';
+export interface PostAnimationTarget {
+    targetX: number;
+    targetY: number;
+    targetScale: number;
+    targetOpacity: number;
+    targetRotation?: number;
+    duration: number;
+    easing: (t: number) => number;
+    onComplete?: () => void;
+}
+export declare class PostAnimator {
+    private animations;
+    private completedScratch;
+    private individuallyPaused;
+    private globallyPaused;
+    startFly(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, targetOpacity?: number, targetRotation?: number): void;
+    startTween(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, onCancel?: () => void, targetOpacity?: number, targetRotation?: number): void;
+    startTweenPromise(slot: GiftSlot, targetX: number, targetY: number, targetScale: number, duration: number, easing: (t: number) => number, onComplete?: () => void, targetOpacity?: number, targetRotation?: number): Promise<void>;
+    startSequence(slot: GiftSlot, targets: PostAnimationTarget[]): Promise<void>;
+    update(now: number): void;
+    /**
+     * Get the current animated position/scale for a gift.
+     * Returns null if no active animation.
+     */
+    getAnimatedState(giftId: string, now: number): {
+        x: number;
+        y: number;
+        scale: number;
+        opacity: number;
+        rotation: number;
+    } | null;
+    applyAnimatedState(slot: GiftSlot, now: number): boolean;
+    hasAnimation(giftId: string): boolean;
+    hasActiveAnimations(): boolean;
+    pauseForGift(giftId: string, now?: number): void;
+    resumeForGift(giftId: string, now?: number): void;
+    pauseAll(now?: number): void;
+    resumeAll(now?: number): void;
+    cancelForGift(giftId: string): void;
+    releaseGift(giftId: string): void;
+    destroy(): void;
+}

package/dist/core/render-manager.d.ts

@@ -0,0 +1,99 @@
+import type { GPUBackend, GiftSlot, GiftHandle, GPUTextureHandle } from '../types';
+import { type SVGAClipMeshMap } from '../renderers/svga-batch-renderer';
+import { PostAnimator } from './post-animator';
+import { AudioManager } from './audio-manager';
+import { type WebCodecsAtlasRect } from './webcodecs-video-atlas';
+export declare class RenderManager {
+    private backend;
+    private svgaBatch;
+    private vapRenderer;
+    private alphaVideoRenderer;
+    private imageRenderer;
+    readonly postAnimator: PostAnimator;
+    readonly audioManager: AudioManager;
+    private slots;
+    private handles;
+    private rafId;
+    private lastTime;
+    private running;
+    private forceNextDraw;
+    private readonly onAnimationFrame;
+    private readonly finishedSlotIdsScratch;
+    private readonly videoRunMapScratch;
+    /** Shared WebCodecs RGBA atlas (optional); multiple slots may reference `handle` with distinct `wcAtlasRect`. */
+    private wcAtlas;
+    /** One-shot logs for WebCodecs clock debugging (filter console by `[GiftStage:WC]`). */
+    private readonly wcDbgTickOnce;
+    private readonly advancedSharedWebCodecsScratch;
+    private readonly activeSharedWebCodecsScratch;
+    constructor(backend: GPUBackend);
+    addSlot(slot: GiftSlot, handle: GiftHandle): void;
+    releaseSlotResources(slot: GiftSlot): void;
+    removeSlot(id: string): void;
+    getSlot(id: string): GiftSlot | undefined;
+    get activeCount(): number;
+    getSlotIds(): string[];
+    /**
+     * Reserve a sub-rectangle in the shared WebCodecs atlas (when `webCodecsVideoAtlas` is configured).
+     * Returns null if disabled, full, or size mismatch while the atlas is still in use.
+     */
+    tryAllocateWebCodecsAtlas(slotId: string, frameW: number, frameH: number, cfg: {
+        width: number;
+        height: number;
+    } | undefined): {
+        handle: GPUTextureHandle;
+        rect: WebCodecsAtlasRect;
+    } | null;
+    releaseWebCodecsAtlasAllocation(slotId: string): void;
+    /** Re-apply CSS-space options when canvas backing store or layout changes (skips active fly animations). */
+    syncSlotLayoutFromOptions(): void;
+    private start;
+    private stop;
+    private clearFrameOnce;
+    pause(): void;
+    resume(): void;
+    prewarmSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>, options?: {
+        frameBudgetMs?: number;
+        workerTimeSliceMs?: number;
+        useWorker?: boolean;
+        checkActive?: () => void;
+        signal?: AbortSignal;
+    }): Promise<number>;
+    hydrateSVGAClipMeshes(meshes: SVGAClipMeshMap | null | undefined): void;
+    snapshotSVGAClipMeshes(entity: NonNullable<GiftSlot['videoEntity']>): SVGAClipMeshMap;
+    private renderLoop;
+    /**
+     * Fixed-step frame advancement matching Unity SvgaLitePlayer.Update()
+     */
+    /**
+     * Advance WebCodecs playback clock (mirrors HTMLVideoElement time + `ended` loop semantics).
+     */
+    private tickSharedWebCodecs;
+    private tickWebCodecs;
+    private wcDbgLogTickOnce;
+    /** Same completion path as `GiftStage.bindVideoLoopOnEnded` for &lt;video&gt;. */
+    private onWebCodecsPlaybackComplete;
+    private tickSVGA;
+    private onGiftPlayComplete;
+    private tickImage;
+    private removeFinished;
+    /** Reused scratch to avoid a per-frame array allocation; consumed synchronously by getRenderLayers. */
+    private orderedSlotsScratch;
+    private getRenderOrderedSlots;
+    private getRenderLayers;
+    /**
+     * Multiple copies of the same gift are often added together before each copy
+     * flies to a different target. While their visual state is exactly identical,
+     * drawing every copy only increases overdraw and changes translucent pixels.
+     * Keep the top-most copy until a transform or frame diverges.
+     */
+    private collapseCoincidentVisualDuplicates;
+    private getCoincidentVisualKey;
+    private getSVGASlotTextureKey;
+    private drawLayer;
+    private drawSlotRun;
+    /** Batch keys are cached on the slot and only rebuilt when their inputs change. */
+    private getBatchKey;
+    private deleteSVGAAtlasTextures;
+    destroy(): void;
+}

package/dist/core/webcodecs-video-atlas.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Row-packs decoded WebCodecs frames into one RGBA atlas to share a single texture bind across many gifts.
+ * Falls back to per-gift textures when allocation fails (returns null).
+ */
+export interface WebCodecsAtlasRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare class WebCodecsVideoAtlasAllocator {
+    private readonly atlasW;
+    private readonly atlasH;
+    /** Current row: y offset and row height. */
+    private rowY;
+    private rowH;
+    private rowX;
+    private readonly slots;
+    constructor(atlasW: number, atlasH: number);
+    get size(): {
+        w: number;
+        h: number;
+    };
+    /**
+     * Reserve a `w×h` rectangle (texels). Returns null if it does not fit.
+     */
+    tryAllocate(slotId: string, w: number, h: number): WebCodecsAtlasRect | null;
+    release(slotId: string): void;
+    getRect(slotId: string): WebCodecsAtlasRect | undefined;
+}