@galacean/effects-core 2.10.0-alpha.2 → 2.10.0-alpha.4

package/dist/components/component.d.ts

@@ -64,6 +64,10 @@ export declare abstract class Component extends EffectsObject {
      * 当父级或间接父级发生改变时调用
      */
     onParentChanged(): void;
+    /**
+     * Called when the owning item's sibling order changes.
+     */
+    onOrderInParentChanged(): void;
     setVFXItem(item: VFXItem): void;
     fromData(data: spec.ComponentData): void;
     dispose(): void;

package/dist/components/index.d.ts

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

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

@@ -0,0 +1,28 @@
+import type { Engine } from '../engine';
+import { CanvasRootControl } from '../gui';
+import { Component } from './component';
+export declare enum CanvasRenderMode {
+    ScreenSpace = 0,
+    CameraSpace = 1,
+    WorldSpace = 2,
+    WorldSpaceFaceCamera = 3
+}
+/** Canvas-layer boundary attached to a VFXItem. Input state remains owned by the window root. */
+export declare class UICanvas extends Component {
+    readonly rootControl: CanvasRootControl;
+    renderMode: CanvasRenderMode;
+    receivesEvents: boolean;
+    private _order;
+    private registered;
+    constructor(engine: Engine);
+    get order(): number;
+    set order(value: number);
+    get isVisible(): boolean;
+    onEnable(): void;
+    onDisable(): void;
+    onDestroy(): void;
+    dispose(): void;
+    private register;
+    private unregister;
+    private destroyCanvas;
+}

package/dist/components/ui-control.d.ts

@@ -0,0 +1,38 @@
+import type { ContainerControl, Control } from '../gui';
+import type { Engine } from '../engine';
+import { Component } from './component';
+/**
+ * Scene-tree bridge for a GUI Control. The VFXItem tree owns lifecycle and
+ * serialization while the Control tree owns layout, drawing and input.
+ */
+export declare class UIControl extends Component {
+    static fallbackParentGetDelegate?: (control: UIControl) => ContainerControl | null;
+    private controlNode;
+    private linkedItemTransform;
+    private linkedControl;
+    private syncingLocation;
+    private readonly itemTransformChanged;
+    private readonly controlLocationChanged;
+    constructor(engine: Engine);
+    get control(): Control | null;
+    set control(value: Control | null);
+    get hasControl(): boolean;
+    onAwake(): void;
+    onEnable(): void;
+    onDisable(): void;
+    onParentChanged(): void;
+    onOrderInParentChanged(): void;
+    onDestroy(): void;
+    dispose(): void;
+    /** Unlinks the GUI object without disposing or modifying it. */
+    unlinkControl(): void;
+    private disposeControl;
+    private syncControl;
+    private syncControlOrder;
+    private resolveParent;
+    private bindLocationSync;
+    private unbindLocationSync;
+    private syncItemLocationToControl;
+    private syncControlLocationToItem;
+    private copyItemLocationToControl;
+}

package/dist/composition.d.ts

@@ -3,11 +3,11 @@ import type { Ray } from '@galacean/effects-math/es/core/ray';
 import type { Matrix4 } from '@galacean/effects-math/es/core/matrix4';
 import { Camera } from './camera';
 import type { Component, PostProcessVolume } from './components';
-import { CompositionComponent } from './components';
+import { CompositionComponent, UICanvas } from './components';
 import type { EventSystem, Region } from './plugins';
 import { RenderFrame } from './render';
 import type { Scene } from './scene';
-import type { Texture } from './texture';
+import { type Texture } from './texture';
 import type { Constructor, Disposable, LostHandler } from './utils';
 import { VFXItem } from './vfx-item';
 import type { CompositionEvent } from './events';
@@ -124,7 +124,8 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
     /**
      * 合成渲染顺序，默认按升序渲染
      */
-    renderOrder: number;
+    get renderOrder(): number;
+    set renderOrder(value: number);
     /**
      * 播放完成后是否需要再使用，是的话生命周期结束后不会自动 dispose
      * @deprecated
@@ -134,7 +135,8 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 合成内的元素否允许点击、拖拽交互
      * @since 1.6.0
      */
-    interactive: boolean;
+    get interactive(): boolean;
+    set interactive(value: boolean);
     /**
      * 合成是否结束
      */
@@ -195,6 +197,8 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 合成中消息元素创建/销毁时触发的回调
      */
     onItemMessage?: (message: MessageItem) => void;
+    /** Screen-space GUI boundary owned by this Composition. */
+    readonly uiCanvas: UICanvas;
     /**
      * 销毁状态位
      */
@@ -205,6 +209,8 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      */
     private paused;
     private isEndCalled;
+    private _renderOrder;
+    private _interactive;
     private _textures;
     /**
      * Composition 构造函数
@@ -335,7 +341,12 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 重置状态函数
      */
     protected reset(): void;
+    /** Renders this Composition content. Screen-space UI is rendered by Engine. */
     render(): void;
+    /**
+     * Renders only the Composition scene content.
+     */
+    renderContent(): void;
     /**
      * 合成更新，针对所有 item 的更新
      * @param deltaTime - 更新的时间步长
@@ -351,7 +362,6 @@ export declare class Composition extends EventEmitter<CompositionEvent<Compositi
      * 更新主合成组件
      */
     private updateCompositionTime;
-    private renderCanvasLayers;
     /**
      * 通过名称获取元素
      * @param name - 元素名称

package/dist/engine.d.ts

@@ -1,5 +1,4 @@
 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';
@@ -18,6 +17,8 @@ import { EventSystem } from './plugins';
 import type { ParticleSystem } from './plugins/particle/particle-system';
 import type { GLType } from './gl';
 import { EventEmitter } from './events';
+import { VFXItem } from './vfx-item';
+import { WindowRootControl } from './gui';
 export interface EngineOptions extends WebGLContextAttributes {
     name?: string;
     glType?: GLType;
@@ -83,10 +84,15 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
      * 渲染过程中错误队列
      */
     renderErrors: Set<Error>;
-    compositions: Composition[];
     assetManagers: AssetManager[];
     assetService: AssetService;
     eventSystem: EventSystem;
+    /** Window-level GUI owner and input router. */
+    readonly windowRoot: WindowRootControl;
+    /**
+     * Root of the unified runtime scene tree.
+     */
+    root: VFXItem;
     env: string;
     /**
      * 计时器
@@ -125,6 +131,7 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
     protected framebuffers: Framebuffer[];
     protected renderbuffers: Renderbuffer[];
     protected particleSystems: ParticleSystem[];
+    private _compositions;
     private _graphics;
     private assetLoader;
     private clearAction;
@@ -132,6 +139,7 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
      *
      */
     constructor(canvas: HTMLCanvasElement, options?: EngineOptions);
+    get compositions(): Composition[];
     get graphics(): Graphics;
     get disposed(): boolean;
     clearResources(): void;
@@ -159,7 +167,25 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
     /** @hide */
     releaseBuffer(buffer: DataBuffer): boolean;
     /** @hide */
-    bindBuffers(vertexBuffers: Record<string, VertexBuffer>, indexBuffer: DataBuffer | undefined, effect: ShaderVariant): void;
+    bindBuffers(vertexBuffers: Record<string, VertexBuffer>, indexBuffer: DataBuffer | null, effect: ShaderVariant): void;
+    /**
+     * 使用当前绑定的顶点和索引缓冲区绘制图元。
+     * @param mode - 图元类型
+     * @param indexOffset - 索引缓冲区中的字节偏移
+     * @param indexCount - 索引数量
+     * @param instanceCount - 实例数量
+     * @hide
+     */
+    drawElementsType(mode: number, indexOffset: number, indexCount: number, instanceCount?: number): void;
+    /**
+     * 使用当前绑定的顶点缓冲区绘制图元。
+     * @param mode - 图元类型
+     * @param vertexStart - 起始顶点
+     * @param vertexCount - 顶点数量
+     * @param instanceCount - 实例数量
+     * @hide
+     */
+    drawArraysType(mode: number, vertexStart: number, vertexCount: number, instanceCount?: number): void;
     addTexture(tex: Texture): void;
     removeTexture(tex: Texture): void;
     addMaterial(mat: Material): void;
@@ -189,9 +215,8 @@ export declare class Engine extends EventEmitter<EngineEvent> implements Disposa
      * example:
      * gl.viewport(0, 0, width, height);
      */
-    viewport(x: number, y: number, width: number, height: number): void;
+    setViewport(x: number, y: number, width: number, height: number): void;
     clear(action: RenderPassClearAction): void;
-    drawGeometry(geometry: Geometry, matrix: Matrix4, material: Material, subMeshIndex?: number): void;
     /*** 渲染状态控制 ***/
     setSampleAlphaToCoverage(enable: boolean): void;
     setBlending(enable: boolean): void;

package/dist/gui/control.d.ts

@@ -0,0 +1,188 @@
+import type { Color } from '@galacean/effects-math/es/core';
+import { Matrix3 } from '@galacean/effects-math/es/core/matrix3';
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import type { Engine } from '../engine';
+import type { CursorStyle, InputEventKey, InputEventMouseButton, InputEventMouseMotion, InputEventScreenDrag, InputEventScreenTouch } from '../input';
+import { FocusBehaviorRecursive, FocusMode, MouseBehaviorRecursive, MouseFilter } from '../input';
+import type { EventEmitterListener, EventEmitterOptions } from '../events';
+import type { FontStyle, FontWeight, TextureRegion } from '../render';
+import type { Texture } from '../texture';
+import type { UIControl } from '../components/ui-control';
+import type { VFXItem } from '../vfx-item';
+export type Rect = {
+    position: Vector2;
+    size: Vector2;
+};
+export type LayoutPreset = 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'centerLeft' | 'centerTop' | 'centerRight' | 'centerBottom' | 'center' | 'leftWide' | 'topWide' | 'rightWide' | 'bottomWide' | 'vcenterWide' | 'hcenterWide' | 'fullRect';
+export type ControlEvent = {
+    locationChanged: [control: Control];
+    sizeChanged: [control: Control];
+    parentChanged: [control: Control];
+};
+/**
+ * A drawable GUI object. Controls form a tree independent from the VFXItem
+ * scene tree. UIControl is the bridge between both trees.
+ */
+export declare class Control {
+    readonly engine: Engine;
+    private _parent;
+    private _visible;
+    private _enabled;
+    private _mouseFilter;
+    private _mouseBehaviorRecursive;
+    private _focusMode;
+    private _focusBehaviorRecursive;
+    private _defaultCursorShape;
+    private _rotation;
+    private transformDirty;
+    private readonly cachedTransform;
+    private readonly eventEmitter;
+    private disposed;
+    /** Scene-tree bridge that owns this GUI object, if any. */
+    owner: UIControl | null;
+    readonly position: Vector2;
+    readonly size: Vector2;
+    readonly anchorMin: Vector2;
+    readonly anchorMax: Vector2;
+    readonly offsetMin: Vector2;
+    readonly offsetMax: Vector2;
+    readonly pivot: Vector2;
+    readonly scale: Vector2;
+    readonly shear: Vector2;
+    mouseForcePassScrollEvents: boolean;
+    clipContents: boolean;
+    constructor(engine: Engine);
+    get parent(): ContainerControl | null;
+    /** Scene item exposed through the optional UIControl bridge. */
+    get item(): VFXItem | null;
+    set parent(value: ContainerControl | null);
+    get indexInParent(): number;
+    set indexInParent(value: number);
+    get visible(): boolean;
+    set visible(value: boolean);
+    get visibleInHierarchy(): boolean;
+    get enabled(): boolean;
+    set enabled(value: boolean);
+    get enabledInHierarchy(): boolean;
+    get mouseFilter(): MouseFilter;
+    set mouseFilter(value: MouseFilter);
+    get mouseBehaviorRecursive(): MouseBehaviorRecursive;
+    set mouseBehaviorRecursive(value: MouseBehaviorRecursive);
+    get focusMode(): FocusMode;
+    set focusMode(value: FocusMode);
+    get focusBehaviorRecursive(): FocusBehaviorRecursive;
+    set focusBehaviorRecursive(value: FocusBehaviorRecursive);
+    get defaultCursorShape(): CursorStyle;
+    set defaultCursorShape(value: CursorStyle);
+    get location(): Vector2;
+    set location(value: Vector2);
+    get rotation(): number;
+    get x(): number;
+    set x(value: number);
+    get y(): number;
+    set y(value: number);
+    get width(): number;
+    set width(value: number);
+    get height(): number;
+    set height(value: number);
+    on<E extends keyof ControlEvent>(eventName: E, listener: EventEmitterListener<ControlEvent[E]>, options?: EventEmitterOptions): void;
+    off<E extends keyof ControlEvent>(eventName: E, listener: EventEmitterListener<ControlEvent[E]>): void;
+    setPosition(x: number, y: number, keepOffsets?: boolean): void;
+    setSize(width: number, height: number): void;
+    setScale(x: number, y: number): void;
+    setRotation(degrees: number): void;
+    setShear(x: number, y: number): void;
+    setPivot(x: number, y: number): void;
+    setAnchorMin(x: number, y: number): void;
+    setAnchorMax(x: number, y: number): void;
+    setOffsetMin(x: number, y: number): void;
+    setOffsetMax(x: number, y: number): void;
+    getRect(): Rect;
+    getTransform2D(): Matrix3;
+    setAnchorsPreset(preset: LayoutPreset, keepOffsets?: boolean): void;
+    setOffsetsPreset(preset: LayoutPreset, margin?: number): void;
+    setAnchorsAndOffsetsPreset(preset: LayoutPreset, margin?: number): void;
+    get root(): RootControl | null;
+    get isDisposed(): boolean;
+    getGlobalTransform2D(): Matrix3;
+    hasPoint(point: Vector2): boolean;
+    getEffectiveMouseFilter(): MouseFilter;
+    getFocusModeWithOverride(): FocusMode;
+    getCursorShape(position: Vector2): CursorStyle;
+    focus(): void;
+    grabFocus(): void;
+    grabClickFocus(): void;
+    releaseFocus(): void;
+    warpMouse(position: Vector2): void;
+    /** Converts a window-space position into this control's local coordinates. */
+    makePositionLocal(position: Vector2): Vector2;
+    /** Gets the current mouse position transformed into this control's coordinates. */
+    getLocalMousePosition(): Vector2;
+    update(deltaTime: number): void;
+    draw(): void;
+    onDestroy(): void;
+    drawLine(x1: number, y1: number, x2: number, y2: number, color?: Color, thickness?: number): void;
+    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;
+    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;
+    fillRect(x: number, y: number, width: number, height: number, color?: Color): void;
+    fillCircle(cx: number, cy: number, radius: number, color?: Color): void;
+    drawTexture(x: number, y: number, width: number, height: number, texture: Texture, region?: TextureRegion, color?: Color): void;
+    drawText(x: number, y: number, text: string, fontSize: number, color?: Color, fontFamily?: string, fontWeight?: FontWeight, fontStyle?: FontStyle): void;
+    onMouseEnter(location: Vector2): void;
+    onMouseMove(event: InputEventMouseMotion): void;
+    onMouseLeave(): void;
+    onMouseWheel(event: InputEventMouseButton): void;
+    onMouseDown(event: InputEventMouseButton): void;
+    onMouseUp(event: InputEventMouseButton): void;
+    onTouchDown(event: InputEventScreenTouch): void;
+    onTouchMove(event: InputEventScreenDrag): void;
+    onTouchUp(event: InputEventScreenTouch): void;
+    onKeyDown(event: InputEventKey): void;
+    onKeyUp(event: InputEventKey): void;
+    onGotFocus(): void;
+    onLostFocus(): void;
+    protected getDragData(position: Vector2): unknown;
+    protected canDropData(position: Vector2, data: unknown): boolean;
+    protected dropData(position: Vector2, data: unknown): void;
+    dispose(): void;
+    private applyBounds;
+    private markTransformDirty;
+    private getParentRect;
+    private computeOffsets;
+    private computeAnchors;
+    private isMouseRecursiveEnabled;
+    private isFocusRecursiveEnabled;
+}
+/** A Control that owns child Controls. */
+export declare class ContainerControl extends Control {
+    readonly children: Control[];
+    addChild<T extends Control>(child: T): T;
+    removeChild(child: Control): void;
+    getChildIndex(child: Control): number;
+    drawSelf(): void;
+    draw(): void;
+    protected drawChildren(): void;
+    update(deltaTime: number): void;
+    dispose(): void;
+}
+/** Base class for GUI tree roots and input dispatchers. */
+export declare abstract class RootControl extends ContainerControl {
+    abstract getMousePosition(): Vector2;
+    abstract guiGetFocusOwner(): Control | null;
+    abstract guiIsDragging(): boolean;
+    abstract guiGetDragData(): unknown;
+    abstract guiIsDragSuccessful(): boolean;
+    abstract guiCancelDrag(): void;
+    abstract grabControlFocus(control: Control): void;
+    abstract grabControlClickFocus(control: Control): void;
+    abstract releaseControlFocus(control?: Control): void;
+    abstract warpControlMouse(position: Vector2): void;
+    abstract updateMouseCursorState(): void;
+    abstract controlStateChanged(control: Control): void;
+    abstract controlRemoved(control: Control): void;
+    abstract controlTreeChanged(): void;
+}

package/dist/gui/index.d.ts

@@ -0,0 +1,2 @@
+export * from './control';
+export * from './roots';

package/dist/gui/roots.d.ts

@@ -0,0 +1,79 @@
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import type { UICanvas } from '../components/ui-canvas';
+import type { Engine } from '../engine';
+import type { InputEvent } from '../input';
+import type { Control } from './control';
+import { ContainerControl, RootControl } from './control';
+/** CanvasLayer-like boundary for a single UICanvas GUI tree. */
+export declare class CanvasRootControl extends ContainerControl {
+    readonly canvas: UICanvas;
+    constructor(engine: Engine, canvas: UICanvas);
+    get inputDisabled(): boolean;
+}
+/** Global ordered collection of UICanvas roots. */
+export declare class CanvasContainer extends ContainerControl {
+    constructor(engine: Engine);
+    sortCanvases(): void;
+    addChildInternal(child: Control): void;
+    draw(): void;
+}
+/** Engine window GUI root. Routes events across all UICanvas roots. */
+export declare class WindowRootControl extends RootControl {
+    readonly canvases: CanvasContainer;
+    dragThreshold: number;
+    private lastInput;
+    private readonly gui;
+    constructor(engine: Engine);
+    pushInput(event: InputEvent): void;
+    isInputHandled(): boolean;
+    getMousePosition(): Vector2;
+    guiGetFocusOwner(): Control | null;
+    guiReleaseFocus(): void;
+    guiIsDragging(): boolean;
+    guiGetDragData(): unknown;
+    guiIsDragSuccessful(): boolean;
+    guiCancelDrag(): void;
+    grabControlFocus(control: Control): void;
+    grabControlClickFocus(control: Control): void;
+    releaseControlFocus(control?: Control): void;
+    warpControlMouse(position: Vector2): void;
+    updateMouseCursorState(): void;
+    controlStateChanged(control: Control): void;
+    controlRemoved(control: Control): void;
+    controlTreeChanged(): void;
+    cancelPointerInput(): void;
+    resize(width: number, height: number): void;
+    render(): void;
+    update(deltaTime: number): void;
+    dispose(): void;
+    private processGUIInput;
+    private processMouseButton;
+    private processMouseMotion;
+    private processScreenTouch;
+    private processScreenDrag;
+    private callGUIInput;
+    private callControlInput;
+    private findInputControl;
+    private findControlAtPosition;
+    private updateMouseOver;
+    private buildHoverHierarchy;
+    private findClickFocus;
+    private beginDragging;
+    private finishDrop;
+    private findDropTarget;
+    private endDragging;
+    private updateCursor;
+    private postGrabClickFocus;
+    private cleanupInternalState;
+    private dropMouseFocus;
+    private dropMouseOver;
+    private dropControlState;
+    private requestMouseOverUpdate;
+    private getGlobalInverse;
+    private toLocal;
+    private controlBelongsToSubtree;
+    private isControlValid;
+    private isControlUsable;
+    private findCanvasRoot;
+    private isFocusTargetUsable;
+}

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export * from './decorators';
 export * from './downloader';
 export * from './effects-object';
 export * from './engine';
+export * from './input';
+export * from './gui';
 export { ensureFixedNumber, getStandardComposition, getStandardImage, getStandardItem, getStandardJSON, normalizeColor, } from './fallback';
 export * from './gl';
 export * from './material';
@@ -33,7 +35,6 @@ 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';