@galacean/effects-core 2.9.3 → 2.10.0-alpha.1

package/dist/canvas-pool.d.ts

@@ -1,9 +1,64 @@
+/**
+ * 池内缓存的一组 canvas 与其 2D context。
+ */
+export type CanvasAndContext = {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+};
 declare class CanvasPool {
-    readonly elements: HTMLCanvasElement[];
+    /**
+     * 空闲 canvas 的全局缓存上限。
+     */
+    private readonly _maxCachedCount;
+    /**
+     * 按尺寸 key 分桶的空闲 canvas 池。
+     */
+    private readonly _canvasPool;
+    /**
+     * 全局空闲队列，顺序表示最近归还时间，头部最久未使用。
+     */
+    private readonly _cachedCanvasAndContexts;
     constructor();
+    /**
+     * 释放池内所有空闲 canvas。
+     */
     dispose(): void;
-    getCanvas(): HTMLCanvasElement;
-    saveCanvas(canvas: HTMLCanvasElement): void;
+    /**
+     * 清空当前池里的所有空闲项。
+     */
+    clear(): void;
+    /**
+     * 按目标尺寸获取一组可复用的 canvas 与 context。
+     */
+    getCanvasAndContext(width: number, height: number): CanvasAndContext;
+    /**
+    * 归还一组 canvas 与 context，并在超过上限时收缩空闲缓存池。
+     */
+    releaseCanvasAndContext(canvasAndContext: CanvasAndContext): void;
+    /**
+     * 新建一组指定尺寸的 canvas 与 context。
+     */
+    private createCanvasAndContext;
+    /**
+     * 清理归还对象上的绘制状态，确保下次复用时是干净的。
+     */
+    private resetCanvasAndContext;
+    /**
+     * 计算尺寸分桶使用的整数 key。
+     */
+    private getKey;
+    /**
+     * 当前池内空闲对象总数。
+     */
+    private getCachedCount;
+    /**
+     * 收缩空闲缓存池，移除最久未使用的一半空闲项。
+     */
+    private cleanUnusedCachedCanvasPool;
+    /**
+     * 销毁单个 canvas 节点。
+     */
+    private destroyCanvas;
 }
 export declare const canvasPool: CanvasPool;
 export {};

package/dist/components/base-render-component.d.ts

@@ -12,6 +12,10 @@ import { RendererComponent } from './renderer-component';
  */
 export interface ItemRenderer extends Required<Omit<spec.RendererOptions, 'texture' | 'shape' | 'anchor' | 'particleOrigin' | 'mask'>> {
     texture: Texture;
+    /**
+     * @deprecated 2.10 起此字段无实际意义，仅为兼容老版本读取保留；
+     * 请使用 `MaskProcessor.getMaskReferences()` 获取当前蒙版引用列表
+     */
     mask: number;
 }
 interface MaskableGraphicData extends spec.ComponentData {

package/dist/components/canvas-item.d.ts

@@ -0,0 +1,131 @@
+import type { Color } from '@galacean/effects-math/es/core';
+import type { FontStyle, FontWeight, TextureRegion } from '../render';
+import type { Texture } from '../texture';
+import { CanvasLayer } from './canvas-layer';
+import { Component } from './component';
+/**
+ * 画布元素组件
+ *
+ * 进入场景树时沿父链向上查找最近的 CanvasLayer 祖先并注册自己；
+ * 父级改变或自身销毁时,刷新 / 注销在所属 CanvasLayer 的登记。
+ *
+ * 注:拓扑(parent / children / 所属 layer)与 enabled/active 解耦 —
+ * `component.enabled=false` 仅让自身 draw 被跳过,**不**改父子关系,也**不**从 layer 注销;
+ * 整棵子树的隐藏由 `vfxItem.setActive(false)` 配合 drawInternal 中的 `isActive` 检查处理
+ */
+export declare class CanvasItem extends Component {
+    /**
+     * 父 CanvasItem
+     * 沿 VFXItem 父链向上查找到的最近的 CanvasItem(只看类型,不看 active/enabled — 拓扑跟激活状态解耦)。
+     * 若不存在 CanvasItem 祖先（即直属于 CanvasLayer 或处于游离状态），该值为 null。
+     */
+    parent: CanvasItem | null;
+    /**
+     * 子 CanvasItem 列表（按注册顺序）
+     * 由子节点在维护自身 parent 时反向写入，draw 时按数组顺序递归绘制
+     */
+    readonly children: CanvasItem[];
+    /**
+     * 当前所属的 CanvasLayer，未注册到任何 CanvasLayer 时为 null
+     */
+    protected canvasLayerNode: CanvasLayer | null;
+    /**
+     * 获取当前所属的 CanvasLayer
+     */
+    get canvasLayer(): CanvasLayer | null;
+    onEnable(): void;
+    onDisable(): void;
+    onParentChanged(): void;
+    onDestroy(): void;
+    /**
+     * 绘制函数
+     * 子类重写此方法以输出实际的绘制内容；调用时 graphics 的变换栈顶已经累积了从根到当前节点的所有父变换，
+     * 子类直接使用 this.drawXxx / this.fillXxx 系列封装方法绘制即可，绘制坐标视为本地坐标。
+     */
+    draw(): void;
+    /**
+     * 绘制单条线段
+     * @param x1 - 起点 x
+     * @param y1 - 起点 y
+     * @param x2 - 终点 x
+     * @param y2 - 终点 y
+     * @param color - 线条颜色
+     * @param thickness - 线宽
+     */
+    drawLine(x1: number, y1: number, x2: number, y2: number, color?: Color, thickness?: number): void;
+    /**
+     * 按顺序连接所有点绘制折线（首尾相同则视为闭合）
+     * @param points - 点数组，格式 [x1,y1,x2,y2,...]
+     * @param color - 线条颜色
+     * @param thickness - 线宽
+     */
+    drawPolyline(points: number[], color?: Color, thickness?: number): void;
+    /**
+     * 绘制三次贝塞尔曲线
+     */
+    drawBezier(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, x4: number, y4: number, color?: Color, thickness?: number): void;
+    /**
+     * 绘制三角形边框
+     */
+    drawTriangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color, thickness?: number): void;
+    /**
+     * 绘制矩形边框
+     * @param x - 矩形左下角 x 坐标
+     * @param y - 矩形左下角 y 坐标
+     */
+    drawRect(x: number, y: number, width: number, height: number, color?: Color, thickness?: number): void;
+    /**
+     * 绘制圆形边框
+     */
+    drawCircle(cx: number, cy: number, radius: number, color?: Color, thickness?: number): void;
+    /**
+     * 绘制填充三角形
+     */
+    fillTriangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color): void;
+    /**
+     * 绘制填充矩形
+     * @param x - 矩形左下角 x 坐标
+     * @param y - 矩形左下角 y 坐标
+     */
+    fillRect(x: number, y: number, width: number, height: number, color?: Color): void;
+    /**
+     * 绘制填充圆形
+     */
+    fillCircle(cx: number, cy: number, radius: number, color?: Color): void;
+    /**
+     * 绘制纹理矩形(本地坐标,Y 向上,(x, y) 为左下角)
+     * @param region - 纹理 UV 子矩形,默认全图。Y 向上,(u0, v0) 为左下角 UV
+     * @param color - 乘色,默认白色
+     */
+    drawTexture(x: number, y: number, width: number, height: number, texture: Texture, region?: TextureRegion, color?: Color): void;
+    /**
+     * 绘制文本(本地坐标,Y 向上,(x, y) 为文本左下角)。
+     *
+     * 同一段文本不同颜色不会重复 upload — 颜色由 `color` 参数透传作为乘色,纹理只缓存白色字形。
+     * 字体参数全部展开,避免调用方每帧创建临时 style 对象触发 GC
+     */
+    drawText(x: number, y: number, text: string, fontSize: number, color?: Color, fontFamily?: string, fontWeight?: FontWeight, fontStyle?: FontStyle): void;
+    /**
+     * 从当前所属的 CanvasLayer 注销自身（如果有）
+     * 仅当自身是顶层 CanvasItem 时，才会触发 layer 顶层列表的移除
+     */
+    private removeFromCanvasLayer;
+    /**
+     * 从当前父 CanvasItem 的 children 中移除自身（如果有）
+     */
+    private removeFromParent;
+    /**
+     * 更新所有子 CanvasItem 的层级归属。
+     * 自身失效时调用，子节点会跳过自己向上找到新的父 CanvasItem（可能为 null）。
+     */
+    private updateChildrenParentItems;
+    /**
+     * 沿父链向上查找最近的 CanvasLayer 祖先
+     * 注意：自身所在 VFXItem 上的 CanvasLayer 也参与查找（同节点上可能并存 CanvasLayer 与 CanvasItem）
+     */
+    private getCanvasLayerNode;
+    /**
+     * 沿 VFXItem 父链向上查找最近的 CanvasItem 祖先(不包含自身,只看类型不看 active/enabled)
+     */
+    private getParentItem;
+}

package/dist/components/canvas-layer.d.ts

@@ -0,0 +1,23 @@
+import type { CanvasItem } from './canvas-item';
+import { Component } from './component';
+/**
+ * 画布层组件
+ *
+ * 作为一组顶层 CanvasItem 的容器：本层内所有 parent 为 null 的 CanvasItem 都登记在 canvasItems 中。
+ * 嵌套关系下的子 CanvasItem 通过其父 CanvasItem 的 children 数组管理，由父节点在 draw 时递归绘制。
+ */
+export declare class CanvasLayer extends Component {
+    /**
+     * 当前层中的顶层 CanvasItem 列表(按注册顺序)。
+     * 仅包含 parent 为 null 的 CanvasItem;嵌套的子 CanvasItem 不会出现在此列表
+     */
+    readonly canvasItems: CanvasItem[];
+    /**
+     * 绘制层级，数值越小越先绘制
+     */
+    layer: number;
+    onEnable(): void;
+    onDisable(): void;
+    private removeFromComposition;
+    private refreshCanvasItemsLayer;
+}

package/dist/components/control.d.ts

@@ -0,0 +1,18 @@
+import { CanvasItem } from './canvas-item';
+/**
+ * 锚点布局组件
+ *
+ * `Control extends CanvasItem`。CanvasItem 仅承担绘制与节点层级，Control 在挂到 VFXItem 时把
+ * `item.transform` 升级为 {@link RectTransform}。
+ *
+ * 布局完全由 RectTransform 自治:父子节点关系沿 `Transform.parentTransform / children` 走，
+ * 父节点 size 变化时通过 `RectTransform.sizeChanged()` 直接调用子节点 sizeChanged 链式传播。
+ * Control 本身不持有任何与布局相关的状态
+ */
+export declare class Control extends CanvasItem {
+    /**
+     * 在挂到 VFXItem 时确保 `item.transform` 是 `RectTransform`。
+     * 既有 Transform 状态(position / rotation / scale / size / anchor 等)通过 `RectTransform.fromTransform` 复制
+     */
+    onAwake(): void;
+}

package/dist/components/index.d.ts

@@ -6,6 +6,8 @@ export * from './effect-component';
 export * from './position-constraint';
 export * from './post-process-volume';
 export * from './base-render-component';
-export * from './shape-component';
 export * from './fake-3d-component';
 export * from './frame-component';
+export * from './canvas-layer';
+export * from './canvas-item';
+export * from './control';

package/dist/composition.d.ts

@@ -168,9 +168,9 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      */
     readonly url: Scene.LoadType;
     /**
-     * 合成根元素
+     * 合成场景根元素
      */
-    readonly rootItem: VFXItem;
+    readonly sceneRoot: VFXItem;
     /**
      * 合成的相机对象
      */
@@ -179,6 +179,10 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 合成开始渲染的时间
      */
     readonly startTime: number;
+    /**
+     * 插件元素根元素
+     */
+    readonly pluginRoot: VFXItem;
     /**
      * 场景中视频列表
      */
@@ -222,6 +226,10 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      */
     get height(): number;
     get renderer(): import("packages/effects-core/src/render/renderer").Renderer;
+    /**
+     * @deprecated 2.10.0 Please use `sceneRoot` instead
+     */
+    get rootItem(): VFXItem;
     /**
      * 所有合成 Item 的根变换
      */
@@ -331,7 +339,7 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 重置状态函数
      */
     protected reset(): void;
-    prepareRender(): void;
+    render(): void;
     /**
      * 合成更新，针对所有 item 的更新
      * @param deltaTime - 更新的时间步长
@@ -347,6 +355,7 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 更新主合成组件
      */
     private updateCompositionTime;
+    private renderCanvasLayers;
     /**
      * 通过名称获取元素
      * @param name - 元素名称
@@ -387,6 +396,11 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      */
     removeInteractiveItem(item: VFXItem, type: spec.InteractType): void;
     lost(e: Event): void;
+    /**
+     * 上下文恢复后的空操作。
+     * GPU 资源已由引擎统一重建，视频纹理会在下次渲染时自然更新，不自动重新播放。
+     */
+    restore(): void;
     /**
      * 合成对象销毁
      */

package/dist/engine.d.ts

@@ -1,9 +1,11 @@
 import * as spec from '@galacean/effects-specification';
+import type { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
 import type { Database, SceneData } from './asset-loader';
 import type { EffectsObject } from './effects-object';
 import type { Material } from './material';
 import type { GPUCapability, Geometry, Mesh, RenderPass, RenderPassClearAction, Renderer, RenderingData, ShaderLibrary } from './render';
-import { RenderTargetPool } from './render';
+import type { Framebuffer, Renderbuffer } from './render';
+import { Graphics, RenderTargetPool } from './render';
 import type { Scene, SceneRenderLevel } from './scene';
 import type { Texture } from './texture';
 import type { Disposable } from './utils';
@@ -11,11 +13,10 @@ import type { Composition } from './composition';
 import type { AssetManager } from './asset-manager';
 import { AssetService } from './asset-service';
 import { Ticker } from './ticker';
-import { EventSystem } from './plugins/interact/event-system';
-import type { GLType } from './gl/create-gl-context';
-import type { PointerEventData, Region } from './plugins/interact/click-handler';
+import type { PointerEventData, Region } from './plugins';
+import { EventSystem } from './plugins';
+import type { GLType } from './gl';
 import { EventEmitter } from './events';
-import type { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
 export interface EngineOptions extends WebGLContextAttributes {
     name?: string;
     glType?: GLType;
@@ -25,6 +26,14 @@ export interface EngineOptions extends WebGLContextAttributes {
     pixelRatio?: number;
     notifyTouch?: boolean;
     interactive?: boolean;
+    /**
+     * 是否不处理 WebGL 上下文丢失恢复。
+     * - `true`（默认）：上传 GPU 后释放 CPU 端源数据以节省内存；上下文丢失后不自动恢复，
+     *   渲染暂停，等待宿主重建资源后手动恢复播放。
+     * - `false`：保留 CPU 端源数据，上下文丢失后引擎自动按资源类型就地重建 GPU 资源并恢复渲染。
+     *   该配置为构造期选项，运行时从 `true` 改为 `false` 无法找回已经丢弃的源数据。
+     */
+    doNotHandleContextLost?: boolean;
 }
 type EngineEvent = {
     contextlost: [eventData: {
@@ -94,12 +103,23 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
      * 存放渲染需要用到的数据
      */
     renderingData: RenderingData;
+    graphics: Graphics;
+    /**
+     * 是否不处理上下文丢失恢复（构造期配置，默认 true）
+     */
+    doNotHandleContextLost: boolean;
+    /**
+     * WebGL 上下文是否处于丢失状态
+     */
+    protected contextWasLost: boolean;
     protected _disposed: boolean;
     protected textures: Texture[];
     protected materials: Material[];
     protected geometries: Geometry[];
     protected meshes: Mesh[];
     protected renderPasses: RenderPass[];
+    protected framebuffers: Framebuffer[];
+    protected renderbuffers: Renderbuffer[];
     private assetLoader;
     private clearAction;
     get disposed(): boolean;
@@ -139,6 +159,10 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
     removeMesh(mesh: Mesh): void;
     addRenderPass(pass: RenderPass): void;
     removeRenderPass(pass: RenderPass): void;
+    addFramebuffer(framebuffer: Framebuffer): void;
+    removeFramebuffer(framebuffer: Framebuffer): void;
+    addRenderbuffer(renderbuffer: Renderbuffer): void;
+    removeRenderbuffer(renderbuffer: Renderbuffer): void;
     addComposition(composition: Composition): void;
     removeComposition(composition: Composition): void;
     getWidth(): number;

package/dist/fallback/migration.d.ts

@@ -26,6 +26,19 @@ export declare function version33Migration(json: JSONScene): JSONScene;
 export declare function version34Migration(json: JSONScene): JSONScene;
 export declare function version35Migration(json: JSONScene): JSONScene;
 export declare function version36Migration(json: JSONScene): JSONScene;
+/**
+ * 3.8 数据适配：SpriteComponent 的 renderer.texture + splits 迁移为独立 Sprite 资产。
+ *
+ * - 遍历所有未引用 sprite 的 SpriteComponentData，按 splits[0]（无则整图 [0,0,1,1]）生成
+ *   Sprite 资产对象放入 miscs，并把组件的 sprite 指向它。
+ * - 删除组件的 splits 与 renderer.texture（纹理归属 sprite，renderer 仅保留渲染状态）。
+ * - 卫语句 `if (sc.sprite) continue` 处理混合数据（部分组件已用 sprite）。
+ * - 多 split（splits.length>1，2x2 纹理打包）保留原 splits 不迁移，仍走 updateGeometryFromMultiSplit 旧路径。
+ *
+ * 由 getStandardJSON 以 `minorVersion < 8` 守卫调用，数据生命周期内只跑一次。
+ * version 字段设为字符串 '3.8'（JSONSceneVersion 枚举无此值，运行时不依赖枚举）。
+ */
+export declare function version37Migration(json: spec.JSONScene): spec.JSONScene;
 export declare function processContent(composition: spec.CompositionData): void;
 export declare function processMask(renderContent: any): void;
 export declare function convertParam(content?: BaseContent): void;

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export * from './template-image';
 export * from './texture';
 export * from './ticker';
 export * from './transform';
+export * from './rect-transform';
 export * from './utils';
 export * from './vfx-item';
 export * from './effects-object';