@vvfx/artis 0.0.1-alpha.0

package/dist/helper/index.d.ts

@@ -0,0 +1,5 @@
+export * from './exporter';
+export * from './size-adapt';
+export * from './screen-shot';
+export * from './html-overlay';
+export * from './scene-builder';

package/dist/helper/scene-builder.d.ts

@@ -0,0 +1,111 @@
+import { spec } from '../shared';
+import { type SceneEntry } from '../core/store';
+import { type ArtisItem } from '../core/item';
+import { type SceneDataAssembler } from '../core/service';
+/**
+ * 远程 / 字符串 / 对象 → JSONScene 的解析结果
+ */
+export type SceneSource = spec.JSONScene | string;
+/**
+ * 单个视图（场景b：一 JSON 在不同尺寸容器中渲染，含安全区）
+ */
+export type SceneView = {
+    /** 视图尺寸 [width, height] */
+    viewSize: [number, number];
+    /** 出血安全区 [top, bottom, left, right] */
+    safeArea?: [number, number, number, number];
+    /** 适配方向 */
+    direction?: 'x' | 'y';
+    /** 采样帧（gotoAndStop 冻结帧） */
+    tick?: number;
+};
+/**
+ * 单个 Galacean/effects 产物源
+ *
+ * - `views` 为空 → 直接以 JSON 单场景加载，主视口＝previewSize 自适应（场景a/c）
+ * - `views` 非空 → 每个 view 各成一个场景变体（按 viewSize，配合 sizeAdapt 开关决定是否做 SizeAdapt，场景b）
+ */
+export type SceneSourceInput = {
+    /** Galacean/effects 产物 JSON 对象或 URL */
+    url: SceneSource;
+    /** 视图列表（场景b）；缺省则该源仅产一个原始场景 */
+    views?: SceneView[];
+};
+/**
+ * SceneBuilder - 把多个 JSON 源（含各自自适应参数）构建为 SceneEntry[]
+ *
+ * 承载方案 §10「一 JSON 多场景生成」：
+ * - origin 场景：原始 JSON 直接作为一个 SceneEntry
+ * - adapted 场景：每组 AdaptConfig → SizeAdapt.adjustment 产生一个新的 JSONScene → 独立 SceneEntry
+ * - 多 JSON 源：各自走上述路径，结果都进同一 SceneStore
+ *
+ * runtime 装配（loadScene + gotoAndStop + SceneDataAssembler）依赖真实 Player 环境，
+ * 通过 {@link SceneBuilderDeps} 注入装配函数，使编排逻辑可单测；真实 Player 接入在 P6/P10。
+ */
+export type SceneBuilderDeps = {
+    /**
+     * 解析 JSON 源（对象直返、字符串按 URL fetch）为 JSONScene
+     */
+    resolveScene: (source: SceneSource) => Promise<spec.JSONScene>;
+    /**
+     * 在一个 JSONScene 上做 headless loadScene + gotoAndStop + assemble，返回 ArtisItem[]
+     * 缺省则 items 为空（runtime 环境未就绪时）。
+     * 允许同步返回（runtime 已就绪时直接从主 Player 装配）。
+     */
+    assemble?: (scene: spec.JSONScene, tick?: number) => ArtisItem[] | Promise<ArtisItem[]>;
+    /**
+     * SceneDataAssembler 实例（若提供则 assemble 缺省走它）
+     */
+    assembler?: SceneDataAssembler;
+};
+export declare class SceneBuilder {
+    private _deps;
+    /**
+     * @param deps 注入的解析/装配依赖
+     */
+    constructor(deps: SceneBuilderDeps);
+    /**
+     * 构建全部场景条目。
+     *
+     * @param inputs 产物源列表（每个源可带多视图）
+     * @param sizeAdaptEnabled 是否启用尺寸自适应。场景b 下：
+     *   - `true`：每个 view 经 SizeAdapt 对原始 JSON 重排后成独立场景
+     *   - `false`：每个 view 仅按 viewSize 含原始 JSON（不重排），用于仅切主视口尺寸/安全区的场景
+     * @returns SceneEntry[]，第一个 origin 的 id 在前；adapted 紧随其同源 origin
+     */
+    build(inputs: SceneSourceInput[], sizeAdaptEnabled?: boolean): Promise<SceneEntry[]>;
+    /**
+     * 用 SizeAdapt 对 origin 做自适应，返回新的 JSONScene（不污染 origin）
+     * @param origin 原始 JSON 场景，不会被修改
+     * @param cfg 自适应配置（视口尺寸、安全区、方向、tick 等）
+     * @returns 自适应后的新 JSONScene
+     */
+    private _adapt;
+    /**
+     * 装配 ArtisItem[]：优先用注入的 assemble，其次用 assembler，否则空数组
+     * @param scene JSON 场景
+     * @param tick 可选时间戳，传入装配函数用于定位指定时刻
+     * @returns 装配出的 ArtisItem 数组；无装配来源时返回空数组
+     */
+    private _assemble;
+    /**
+     * 提取产物预览尺寸作为内容尺寸（主视口范围依据）。
+     *
+     * 优先取 `compositions[0].previewSize`（产物设计尺寸，驱动主视口）；
+     * 回退到顶层 items 中 CompositionComponent 的 options.size；再回退默认 1080×1920。
+     * @param scene JSON 场景
+     * @returns [宽, 高]
+     */
+    private _extractContentSize;
+    /**
+     * 提取场景 CompositionComponent 的 id（优先 item.id，其次 id）
+     * @param scene JSON 场景
+     * @returns composition id；不存在返回 undefined
+     */
+    private _extractCompositionId;
+    /**
+     * 生成一个全局唯一 id
+     * @returns GUID 字符串
+     */
+    private _genId;
+}

package/dist/helper/screen-shot.d.ts

@@ -0,0 +1,51 @@
+import { spec } from '../shared';
+/**
+ * 截图工具
+ */
+export declare class ScreenShot {
+    /**
+     * 截图播放器
+     */
+    private _player;
+    /**
+     * 截图播放器容器
+     */
+    private _container;
+    defaultBackground: spec.vec4;
+    /**
+     * 初始化截图播放器与画布容器
+     */
+    constructor();
+    /**
+     * 生成场景在指定时刻的截图
+     * @param scene 场景数据（对象或 URL）
+     * @param containerSize 截图播放器画布尺寸
+     * @param resultSize 输出图片尺寸
+     * @param tick 截图时刻
+     * @param background 背景色 rgba，缺省走 defaultBackground
+     * @returns 截图 base64 数据
+     */
+    generate(scene: spec.JSONScene | string, containerSize: spec.vec2, resultSize: spec.vec2, tick: number, background?: spec.vec4): Promise<string>;
+    /**
+     * 释放截图播放器资源
+     */
+    dispose(): void;
+    /**
+     * 以 cover 方式将图像绘制到目标矩形（保持比例裁剪溢出部分）
+     * @param ctx 2D 绘图上下文
+     * @param img 源图像
+     * @param x 目标左上角 x
+     * @param y 目标左上角 y
+     * @param w 目标宽
+     * @param h 目标高
+     * @param offsetX 源裁剪横向锚点 0-1，缺省 0.5
+     * @param offsetY 源裁剪纵向锚点 0-1，缺省 0.5
+     * @param sourceRect 源裁剪矩形，缺省取整图
+     */
+    drawImageCover(ctx: CanvasRenderingContext2D, img: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, x: number, y: number, w: number, h: number, offsetX?: number, offsetY?: number, sourceRect?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): void;
+}

package/dist/helper/size-adapt.d.ts

@@ -0,0 +1,88 @@
+import { Box2, Vector2, Vector3 } from '@vvfx/gizmo';
+import { Composition, spec, VFXItem } from '../shared';
+export declare enum SizeAdaptDirection {
+    X = "x",
+    Y = "y"
+}
+/**
+ * 尺寸适配工具
+ */
+export declare class SizeAdapt {
+    /**
+     * 尺寸适配播放器
+     */
+    private _player;
+    /**
+     * 尺寸播放器容器
+     */
+    private _container;
+    /**
+     * 视图大小
+     */
+    size: spec.vec2;
+    /**
+     * 初始化尺寸适配播放器与画布容器
+     */
+    constructor();
+    /**
+     * 按视图尺寸/安全区/方向对场景做自适应，原地修改并返回 scene
+     * @param scene JSON 场景（会被原地修改）
+     * @param tick 自适应基准时刻
+     * @param originSize 原始内容尺寸
+     * @param viewSize 目标视图尺寸
+     * @param safeArea 安全区 [上, 下, 左, 右]，缺省为 0
+     * @param direction 自适应方向，缺省按 originSize 宽高比推断
+     * @returns 自适应后的 scene
+     */
+    adjustment(scene: spec.JSONScene, tick: number, originSize: spec.vec2, viewSize: spec.vec2, safeArea?: spec.vec4, direction?: SizeAdaptDirection): Promise<spec.JSONScene>;
+    /**
+     * 根据宽高比变化保持上/中/下吸附元素垂直排布距离
+     * @param scene JSON 场景（会被原地修改）
+     * @param composition 播放器 composition
+     * @param ratio 视图与原始宽高比之比
+     * @param viewSize 视图尺寸
+     */
+    keepDistribute(scene: spec.JSONScene, composition: Composition, ratio: number, viewSize: spec.vec2): void;
+    /**
+     * 单边/中心吸附自适应：跟随出血区位移缩放并叠加安全区、比例、压板等约束
+     * @param type 吸附类型
+     * @param scene JSON 场景（会被原地修改）
+     * @param composition 播放器 composition
+     * @param translation 安全区位移
+     * @param originViewBox 原始视图包围盒
+     * @param resultViewBox 目标视图包围盒
+     * @param adsorptionDirection 主自适应方向
+     */
+    keepAdsorption(type: 'centerAdsorption' | 'topAdsorption' | 'bottomAdsorption' | 'leftAdsorption' | 'rightAdsorption', scene: spec.JSONScene, composition: Composition, translation: spec.vec2, originViewBox: Box2, resultViewBox: Box2, adsorptionDirection: SizeAdaptDirection): void;
+    /**
+     * 下中心双吸附自适应：缩放并强制元素在目标包围盒内（含比例约束）
+     * @param type 吸附类型
+     * @param scene JSON 场景（会被原地修改）
+     * @param composition 播放器 composition
+     * @param translation 安全区位移
+     * @param originViewBox 原始视图包围盒
+     * @param resultViewBox 目标视图包围盒
+     * @param adsorptionDirection 主自适应方向
+     */
+    keepDoubleAdsorption(type: 'bottomCenterAdsorption', scene: spec.JSONScene, composition: Composition, translation: spec.vec2, originViewBox: Box2, resultViewBox: Box2, adsorptionDirection: SizeAdaptDirection): void;
+    /**
+     * 计算 headless player 中 item 及其子级的视图包围盒
+     * @param targetItem 目标 item
+     * @param childrenItem 直接子级列表
+     * @param projectPoint 世界坐标到视图坐标的投影函数
+     * @returns 包围盒（无内容时为空盒）
+     */
+    getViewBoxByHeadlessPlayerItem(targetItem: VFXItem, childrenItem: VFXItem[], projectPoint: (point: Vector3) => Vector2): Box2;
+    /**
+     * 把增量变换写回场景中对应 item 的 transform 字段
+     * @param scene JSON 场景
+     * @param itemId 目标 item id
+     * @param propertyName 属性名 position/rotation/scale
+     * @param propertyValue 增量值
+     */
+    transformSceneItem(scene: spec.JSONScene, itemId: string, propertyName: string, propertyValue: any): void;
+    /**
+     * 释放尺寸适配播放器资源
+     */
+    dispose(): void;
+}