@galacean/effects-core 2.9.1-beta.0 → 2.10.0-alpha.0

package/dist/render/text-cache.d.ts

@@ -0,0 +1,109 @@
+import type { Engine } from '../engine';
+import { Texture } from '../texture';
+/**
+ * 字重（对齐 canvas 2d font 字符串可接受值）
+ */
+export type FontWeight = 'normal' | 'bold' | number;
+/**
+ * 字形（对齐 canvas 2d font 字符串可接受值）
+ */
+export type FontStyle = 'normal' | 'italic';
+/**
+ * 字形纹理超采样倍数。canvas 按 `fontSize * FONT_SCALE` 渲染，纹理像素也是 scale 倍，
+ * 但 quad 仍按 1x 逻辑尺寸绘制 — 双线性 downsample 后比原 1x 渲染清晰得多
+ */
+export declare const FONT_SCALE = 2;
+/**
+ * 单张字符 atlas 的边长(像素,scale 后的实际像素,非逻辑尺寸)。
+ * 512×512 在 24px 字号下约可容纳 250+ 字形,常见 demo 文本足够
+ */
+export declare const ATLAS_SIZE = 512;
+/**
+ * 单个字形在 atlas 中的位置 / 度量。
+ *
+ * `px/py/pw/ph` 是 atlas canvas 像素（scale 后）。
+ * `width` 是逻辑像素宽度（= pw / FONT_SCALE），用于 quad 宽 + cursor advance
+ */
+export type GlyphInfo = {
+    px: number;
+    py: number;
+    pw: number;
+    ph: number;
+    width: number;
+};
+/**
+ * 一种字体（family + weight + style + size 唯一确定）对应一张 atlas。
+ *
+ * Skyline 风格 packer：行内堆字，行尾换行，行高 = (ascent+descent) * FONT_SCALE。
+ * atlas 满后 `ensureChar` 返回 null，调用方应跳过该字（不再扩页，v1 范围）。
+ *
+ * canvas 内容变更后需要 `uploadIfDirty` 重新上传到纹理 — 由调用方在使用纹理前主动触发，
+ * 避免每加一字都 upload 一次造成的 GL 开销
+ */
+export declare class GlyphAtlas {
+    private engine;
+    private readonly scaledFontString;
+    /** atlas canvas（像素 = ATLAS_SIZE × ATLAS_SIZE，自有不进 canvasPool） */
+    readonly canvas: HTMLCanvasElement;
+    /** 与 canvas 绑定的纹理，内容变更后通过 updateSource 重传 */
+    readonly texture: Texture;
+    /** 行高（逻辑像素，= ascent + descent），所有字共享 */
+    readonly lineHeight: number;
+    /** 行 ascent（逻辑像素，baseline 距行顶距离） */
+    readonly ascent: number;
+    /** 行 descent（逻辑像素，baseline 距行底距离） */
+    readonly descent: number;
+    private readonly ctx;
+    private readonly glyphs;
+    /** 行高（像素，scale 后） */
+    private readonly lineHeightPx;
+    /** baseline 距行顶距离（像素，scale 后） */
+    private readonly ascentPx;
+    /** packer 状态：下一字开始的左上角像素位置 */
+    private currentX;
+    private currentY;
+    /** atlas 已满，后续 ensureChar 全部失败（避免反复 measureText） */
+    private full;
+    /** 自上次 upload 以来 canvas 是否有新字写入 */
+    private dirty;
+    constructor(engine: Engine, scaledFontString: string, ascent: number, descent: number);
+    /**
+     * 取（必要时渲染并打包）单字。返回 GlyphInfo 或 null（atlas 已满）
+     */
+    ensureChar(char: string): GlyphInfo | null;
+    /**
+     * 若有新字写入 canvas，把整张 canvas 重新上传到纹理。调用方在使用纹理（flushBatch）前调用
+     */
+    uploadIfDirty(): void;
+    dispose(): void;
+}
+/**
+ * 字符 atlas 缓存。每种字体（family + weight + style + size）分配一张
+ * `ATLAS_SIZE × ATLAS_SIZE` 的离屏 canvas atlas，字符按需逐个绘制并打包，
+ * `Graphics.drawText` 通过逐字 quad 引用 atlas 子矩形渲染。
+ *
+ * - 同一段文本不同颜色不会重复 upload（颜色由顶点 `vColor` 乘上字形 alpha）
+ * - 同一字体/字号下重复字符只渲染一次，显著减少 canvas → texture 上传次数
+ *
+ * 入参全部展开（避免调用方每帧创建临时 style 对象触发 GC）
+ */
+export declare class TextCache {
+    private engine;
+    /** fontKey -> 该字体的字符 atlas */
+    private readonly atlases;
+    constructor(engine: Engine);
+    /**
+     * 取(必要时新建)对应字体的字符 atlas
+     */
+    getAtlas(fontSize: number, fontFamily: string, fontWeight: FontWeight, fontStyle: FontStyle): GlyphAtlas;
+    /**
+     * 把所有 dirty 的 atlas canvas 内容上传到对应纹理。
+     * 由 `Graphics.flushBatch` 在 drawGeometry 前调用，确保即将采样的 atlas 纹理是最新的；
+     * 一帧多次 drawText 共写同一 atlas 时，只在 flush 边界 upload 一次，避免逐 drawText 反复重传
+     */
+    uploadDirty(): void;
+    /**
+     * 清空所有 atlas 并 dispose 对应纹理。Engine dispose 时调用
+     */
+    dispose(): void;
+}

package/dist/transform.d.ts

@@ -1,4 +1,5 @@
 import { Euler, Matrix4, Quaternion, Vector2, Vector3 } from '@galacean/effects-math/es/core/index';
+import { Matrix3 } from '@galacean/effects-math/es/core/matrix3';
 import type * as spec from '@galacean/effects-specification';
 import type { Disposable } from './utils';
 import type { Engine } from './engine';
@@ -53,7 +54,7 @@ export declare class Transform implements Disposable {
     /**
      * 子变换，可以有多个
      */
-    private children;
+    protected children: Transform[];
     /**
      * 父变换，只能有一个
      */
@@ -70,6 +71,10 @@ export declare class Transform implements Disposable {
      * 仅包含自身变换的模型矩阵
      */
     private localMatrix;
+    /**
+     * 自身变换在 2D 平面（XY）上的仿射部分缓存，按需从 localMatrix 提取
+     */
+    private localMatrix2D;
     /**
      * 变换是否需要生效，不生效返回的模型矩阵为单位矩阵，需要随元素生命周期改变
      */
@@ -90,8 +95,8 @@ export declare class Transform implements Disposable {
     constructor(props?: TransformProps, parent?: Transform);
     set parentTransform(transform: Transform | null);
     get parentTransform(): Transform | null;
-    set parentMatrixDirty(val: boolean);
-    get parentMatrixDirty(): boolean;
+    private set worldMatrixDirty(value);
+    private get worldMatrixDirty();
     /**
      * 设置位置
      * @param x
@@ -184,6 +189,12 @@ export declare class Transform implements Disposable {
      * @returns
      */
     getMatrix(): Matrix4;
+    /**
+     * 获取自身变换对应模型矩阵在 XY 平面上的 3x3 仿射矩阵
+     * 仅当 localMatrix 变化时才重新提取，否则返回缓存。返回的 Matrix3 在调用之间复用，调用方不应缓存其引用。
+     * @returns
+     */
+    getMatrix2D(): Matrix3;
     /**
      * 获取父矩阵，如果有多级父节点，返回整体变换
      * @returns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/effects-core",
-  "version": "2.9.1-beta.0",
+  "version": "2.10.0-alpha.0",
   "description": "Galacean Effects runtime core for the web",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",