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

package/dist/render/geometry.d.ts

@@ -1,26 +1,28 @@
-import type * as spec from '@galacean/effects-specification';
+import * as spec from '@galacean/effects-specification';
 import type { Engine } from '../engine';
 import { EffectsObject } from '../effects-object';
-export declare const BYTES_TYPE_MAP: Record<string, number>;
-/**
- * Geometry 的绘制模式
- */
-export type GeometryDrawMode = WebGLRenderingContext['POINTS'] | WebGLRenderingContext['TRIANGLES'] | WebGLRenderingContext['TRIANGLE_STRIP'] | WebGLRenderingContext['TRIANGLE_FAN'] | WebGLRenderingContext['LINES'] | WebGLRenderingContext['LINE_STRIP'] | WebGLRenderingContext['LINE_LOOP'];
+import { Buffer } from './buffer';
+import type { DataBuffer, IndexData, IndicesArray } from './data-buffer';
+import { VertexBuffer } from './vertex-buffer';
+import type { ShaderVariant } from './shader';
+export type GeometryDrawMode = number;
 export type Attribute = spec.AttributeWithData | spec.AttributeWithDataPointer | spec.AttributeWithType | spec.AttributeWithDataSource;
 export interface GeometryProps {
     name?: string;
     attributes: Record<string, Attribute>;
     indices?: {
-        data: spec.TypedArray;
-        releasable?: boolean;
+        data: IndexData;
     };
     mode?: GeometryDrawMode;
     drawCount?: number;
     drawStart?: number;
     instanceCount?: number;
-    bufferUsage?: WebGLRenderingContext['STATIC_DRAW'] | WebGLRenderingContext['DYNAMIC_DRAW'];
     /**
-     * 粒子最大数量，适用于无法更新 GPU 缓存长度的引擎接入
+     * 顶点和索引缓冲区的使用方式，默认使用静态缓冲区。
+     */
+    bufferUsage?: number;
+    /**
+     * 为初始空缓冲区预留的最大顶点数量。
      */
     maxVertex?: number;
 }
@@ -30,93 +32,69 @@ export interface SkinProps {
     inverseBindMatrices?: number[];
 }
 /**
- * Geometry 抽象类
+ * 几何数据、属性布局和绘制范围的后端无关实现。
  */
-export declare abstract class Geometry extends EffectsObject {
-    /**
-     * Geometry 的名称
-     */
+export declare class Geometry extends EffectsObject {
+    static create: (engine: Engine, props?: GeometryProps) => Geometry;
     name: string;
-    /**
-     * 子网格数据
-     */
     subMeshes: spec.SubMesh[];
-    /**
-     * Geometry 创建函数
-     */
-    static create: (engine: Engine, opts?: GeometryProps) => Geometry;
-    /**
-     * 获取 Geometry 的 attribute 数据。
-     * @param name - attribute 名称
-     */
-    abstract getAttributeData(name: string): spec.TypedArray | undefined;
-    /**
-     * 设置 Geometry 的 attribute 数据。
-     * @param name - attribute 名称
-     * @param data - 要设置的 attribute 数据
-     */
-    abstract setAttributeData(name: string, data: spec.TypedArray): void;
-    /**
-     * 设置 attribute 的部分数据，当 attribute 数据只有部分更新时，可调用此函数。
-     * @param name - attribute 名称
-     * @param offset - 更新数据在 attribute 数组的起始位置 index
-     * @param data - 要设置的 attribute 数据
-     */
-    abstract setAttributeSubData(name: string, offset: number, data: spec.TypedArray): void;
-    /**
-     * 获取 attribute 的步长
-     * @param name - attribute 名称
-     */
-    abstract getAttributeStride(name: string): number;
-    /**
-     * 获取当前 Geometry 所有的 attribute 名称。
-     */
-    abstract getAttributeNames(): string[];
-    /**
-     * 获取当前 Geometry 的 indices 数据。
-     */
-    abstract getIndexData(): spec.TypedArray | undefined;
-    /**
-     * 设置 Geometry 的 indices 数据。
-     * @param data - 要设置的 indices 数据
-     */
-    abstract setIndexData(data: spec.TypedArray): void;
-    /**
-     * 设置 indices 的部分数据，当 indices 数据只有部分更新时，可调用此函数。
-     * @param offset - 更新数据在 indices 数组的起始位置 index
-     * @param data - 要设置的 indices 数据
-     */
-    abstract setIndexSubData(offset: number, data: spec.TypedArray): void;
-    /**
-     * 设置 Geometry 绘制的 drawStart
-     * @param value 要设置的 drawStart 值
-     */
-    abstract setDrawStart(count: number): void;
-    /**
-     * 获取当前 Geometry 的 drawStart
-     */
-    abstract getDrawStart(): number;
-    /**
-     * 设置 Geometry 绘制的 drawCount。
-     * @param count 要设置的 drawCount 值
-     */
-    abstract setDrawCount(count: number): void;
-    /**
-     * 获取当前 Geometry 的 drawcount
-     */
-    abstract getDrawCount(): number;
-    /**
-     * 获取当前 Geometry 关联的蒙皮数据
-     */
-    abstract getSkinProps(): SkinProps;
-    /**
-     * 初始化 GPU 资源
-     * @override
-     */
+    /** @hide */
+    mode: GeometryDrawMode;
+    /** @hide */
+    instanceCount: number;
+    private vertexBuffers;
+    private indices;
+    private drawCount;
+    private drawStart;
+    private skin;
+    private indexBuffer?;
+    private disposed;
+    private initialized;
+    private options?;
+    private bufferUsage;
+    private vertexArrayObjects?;
+    /** @hide */
+    constructor(engine: Engine, props?: GeometryProps);
+    /** @hide */
+    isDisposed(): boolean;
+    /** @hide */
+    getVertexBuffer(name: string): VertexBuffer | undefined;
+    /** @hide */
+    setVerticesBuffer(vertexBuffer: VertexBuffer, disposeExistingBuffer?: boolean): void;
+    /** @hide */
+    getAttributeBuffer(name: string): Buffer | undefined;
+    getAttributeData(name: string): spec.TypedArray | undefined;
+    setAttributeData(name: string, data: spec.TypedArray): void;
+    setAttributeSubData(name: string, offset: number, data: spec.TypedArray): void;
+    getAttributeStride(name: string): number;
+    getAttributeNames(): string[];
+    /** @hide */
+    getIndexBuffer(): DataBuffer | undefined;
+    getIndexData(): IndexData;
+    /** @hide */
+    getIndexType(): number;
+    setIndexData(data: IndicesArray): void;
+    setIndexSubData(offset: number, data: IndicesArray): void;
+    setDrawStart(start: number): void;
+    getDrawStart(): number;
+    setDrawCount(count: number): void;
+    getDrawCount(): number;
+    getSkinProps(): SkinProps;
+    /** @hide */
+    bind(shader: ShaderVariant): void;
+    private releaseVertexArrayObject;
     initialize(): void;
-    /**
-     * 几何数据刷新
-     */
     flush(): void;
+    /** @hide */
+    restore(): void;
+    fromData(data: spec.GeometryData): void;
+    dispose(): void;
+    private processProps;
+    private releaseCurrentBuffers;
+    private disposeVertexArrayObjects;
+    private createIndexBuffer;
+    private releaseIndexBuffer;
+    private forEachVertexBuffer;
 }
-export declare function generateEmptyTypedArray(type: number): Float32Array | Int16Array | Int32Array;
+export declare const BYTES_TYPE_MAP: Record<string, number>;
+export declare function generateEmptyTypedArray(type: number): spec.TypedArray;

package/dist/render/gpu-capability.d.ts

@@ -14,6 +14,8 @@ export interface GPUCapabilityDetail {
     maxTextureAnisotropy: number;
     shaderTextureLod: boolean;
     instanceDraw?: boolean;
+    /** @hide */
+    vertexArrayObject?: boolean;
     ktx2Support: boolean;
     drawBuffers?: boolean;
     asyncShaderCompile: boolean;

package/dist/render/graphics.d.ts

@@ -62,6 +62,7 @@ export declare class Graphics {
      * 提交当前累积的顶点到 renderer，清空缓冲(批次内部 flush 不重置 batchType)
      */
     private flushBatch;
+    private updateAttributeData;
     /**
      * 线段顶点按顺序连接 (p0-p1, p1-p2, p2-p3, ...)
      * @param points - 点数组，格式 [x1,y1,x2,y2,...]，至少需要2个点(4个数值)
@@ -174,8 +175,8 @@ export declare class Graphics {
      * `color` 作为乘色与白色字形 alpha 相乘，任意颜色都不会污染 atlas。
      *
      * 字体参数全部展开，避免调用方每帧创建临时 style 对象触发 GC
-     * @param x - 文本左下角 X 坐标
-     * @param y - 文本左下角 Y 坐标（对齐 baseline 上方 ascent 处）
+     * @param x - 文本左下角 X 坐标（首字 ink 起始处，含 padding 的 quad 会向左延伸）
+     * @param y - 文本左下角 Y 坐标（cell 底，含底部 padding；字形 ink 在其上方 padding+ascent 处）
      * @param text - 要绘制的文本内容，空串直接 return
      * @param fontSize - 字号（逻辑像素）
      * @param color - 乘色，默认白色，范围 0-1

package/dist/render/index.d.ts

@@ -7,6 +7,9 @@ export * from './shader';
 export * from './gpu-capability';
 export * from './mesh';
 export * from './geometry';
+export * from './data-buffer';
+export * from './buffer';
+export * from './vertex-buffer';
 export * from './framebuffer';
 export * from './renderer';
 export * from './graphics';

package/dist/render/shader.d.ts

@@ -57,8 +57,9 @@ export interface SharedShaderWithSource {
 export type ShaderWithSource = SharedShaderWithSource;
 export declare abstract class ShaderVariant extends EffectsObject {
     readonly source: ShaderWithSource;
+    readonly key: string;
     shader: Shader;
-    constructor(engine: Engine, source: ShaderWithSource);
+    constructor(engine: Engine, source: ShaderWithSource, key: string);
     initialize(): void;
     abstract setFloat(name: string, value: number): void;
     abstract setInt(name: string, value: number): void;

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

@@ -21,20 +21,24 @@ export declare const ATLAS_SIZE = 512;
 /**
  * 单个字形在 atlas 中的位置 / 度量。
  *
- * `px/py/pw/ph` 是 atlas canvas 像素（scale 后）。
- * `width` 是逻辑像素宽度（= pw / FONT_SCALE），用于 quad 宽 + cursor advance
+ * `px/py/pw/ph` 是 atlas canvas 像素（scale 后，含四周 padding）。
+ * `advance` 是逻辑像素光标前进量（1x，不含 padding）— quad 宽度含 padding，
+ * 但相邻字只按 advance 前进，padding 区透明因此重叠无妨。
+ * `paddingLeft` 是逻辑像素左侧留白（1x），quad 起点左偏此量使字形 ink 落在 cursorX
  */
 export type GlyphInfo = {
     px: number;
     py: number;
     pw: number;
     ph: number;
-    width: number;
+    advance: number;
+    paddingLeft: number;
 };
 /**
  * 一种字体（family + weight + style + size 唯一确定）对应一张 atlas。
  *
- * Skyline 风格 packer：行内堆字，行尾换行，行高 = (ascent+descent) * FONT_SCALE。
+ * Skyline 风格 packer：行内堆字，行尾换行，cell 高 = ceil((fontHeight + padding*2) * 1)，
+ * 所有字共用同一 cell 高与 baseline，实现同行 baseline 对齐。
  * atlas 满后 `ensureChar` 返回 null，调用方应跳过该字（不再扩页，v1 范围）。
  *
  * canvas 内容变更后需要 `uploadIfDirty` 重新上传到纹理 — 由调用方在使用纹理前主动触发，
@@ -47,18 +51,18 @@ export declare class GlyphAtlas {
     readonly canvas: HTMLCanvasElement;
     /** 与 canvas 绑定的纹理，内容变更后通过 updateSource 重传 */
     readonly texture: Texture;
-    /** 行高（逻辑像素，= ascent + descent），所有字共享 */
+    /** cell 高（逻辑像素，含 padding），用于 quad 高度 */
     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;
+    /** baseline 距 cell 顶距离（像素，scale 后，含顶部 padding） */
+    private readonly baselinePx;
+    /** cell 高（像素，scale 后，含 padding） */
+    private readonly cellHPx;
+    /** 四周留白（像素，scale 后） */
+    private readonly paddingPx;
+    /** italic 字形 cell 宽额外放大倍数（防斜体越界重叠） */
+    private readonly italicScale;
     /** packer 状态：下一字开始的左上角像素位置 */
     private currentX;
     private currentY;
@@ -66,7 +70,11 @@ export declare class GlyphAtlas {
     private full;
     /** 自上次 upload 以来 canvas 是否有新字写入 */
     private dirty;
-    constructor(engine: Engine, scaledFontString: string, ascent: number, descent: number);
+    constructor(engine: Engine, scaledFontString: string, 
+    /** baseline 距 cell 顶距离（像素，scale 后，仅 ascent 部分，不含 padding） */
+    ascentPx: number, 
+    /** baseline 距 cell 底距离（像素，scale 后，仅 descent 部分） */
+    descentPx: number, fontStyle: FontStyle);
     /**
      * 取（必要时渲染并打包）单字。返回 GlyphInfo 或 null（atlas 已满）
      */

package/dist/render/vertex-buffer.d.ts

@@ -0,0 +1,72 @@
+import type * as spec from '@galacean/effects-specification';
+import type { Engine } from '../engine';
+import type { Disposable } from '../utils';
+import { Buffer } from './buffer';
+import type { DataArray, DataBuffer } from './data-buffer';
+import { BufferDataType } from './data-buffer';
+export interface VertexBufferProps {
+    updatable?: boolean;
+    postponeInternalCreation?: boolean;
+    stride?: number;
+    instanced?: boolean;
+    offset?: number;
+    size?: number;
+    type?: number;
+    normalized?: boolean;
+    useBytes?: boolean;
+    divisor?: number;
+    takeBufferOwnership?: boolean;
+    label?: string;
+}
+/**
+ * 描述一个顶点属性如何读取共享缓冲区。
+ */
+export declare class VertexBuffer implements Disposable {
+    static readonly PositionKind = "aPos";
+    static readonly NormalKind = "aNormal";
+    static readonly TangentKind = "aTangent";
+    static readonly UVKind = "aUV";
+    static readonly UV2Kind = "aUV2";
+    static readonly UV3Kind = "aUV3";
+    static readonly UV4Kind = "aUV4";
+    static readonly UV5Kind = "aUV5";
+    static readonly UV6Kind = "aUV6";
+    static readonly ColorKind = "aColor";
+    static readonly JointsKind = "aJoints";
+    static readonly WeightsKind = "aWeights";
+    static readonly BYTE = BufferDataType.Byte;
+    static readonly UNSIGNED_BYTE = BufferDataType.UnsignedByte;
+    static readonly SHORT = BufferDataType.Short;
+    static readonly UNSIGNED_SHORT = BufferDataType.UnsignedShort;
+    static readonly INT = BufferDataType.Int;
+    static readonly UNSIGNED_INT = BufferDataType.UnsignedInt;
+    static readonly FLOAT = BufferDataType.Float;
+    readonly byteStride: number;
+    readonly byteOffset: number;
+    readonly normalized: boolean;
+    readonly type: spec.BufferType;
+    readonly engine: Engine;
+    private readonly kind;
+    private readonly size;
+    private _isDisposed;
+    private instanced;
+    private _instanceDivisor;
+    constructor(engine: Engine, data: DataArray | Buffer | DataBuffer, kind: string, props?: VertexBufferProps);
+    get isDisposed(): boolean;
+    get instanceDivisor(): number;
+    set instanceDivisor(value: number);
+    getKind(): string;
+    isUpdatable(): boolean;
+    getData(): DataArray | undefined;
+    getBuffer(): DataBuffer | undefined;
+    getWrapperBuffer(): Buffer;
+    getStrideSize(): number;
+    getOffset(): number;
+    getSize(sizeInBytes?: boolean): number;
+    getIsInstanced(): boolean;
+    getInstanceDivisor(): number;
+    create(data?: DataArray): void;
+    update(data: DataArray): void;
+    updateDirectly(data: DataArray, offset: number, useBytes?: boolean): void;
+    dispose(): void;
+}

package/dist/scene.d.ts

@@ -67,13 +67,16 @@ export interface SceneLoadOptions {
      */
     variables?: spec.TemplateVariables;
     /**
-     * 是否使用压缩纹理
-     * @default undefined
+     * 是否优先使用压缩纹理
+     * 当资源存在且当前环境支持时使用，否则回退到普通图片
+     * 需要注册 KTX2 loader，例如 import '@galacean/effects-plugin-ktx2'
+     * @default true
      */
     useCompressedTexture?: boolean;
     /**
-     * 是否使用 Hevc 视频
-     * @default undefined
+     * 是否优先使用 Hevc 视频
+     * 当资源存在且当前环境支持时使用，否则回退到普通视频
+     * @default true
      */
     useHevcVideo?: boolean;
     /**

package/dist/utils/index.d.ts

@@ -29,7 +29,7 @@ export interface Disposable {
     dispose(): void;
 }
 export interface RestoreHandler {
-    restore(): void;
+    restore(): void | Promise<void>;
 }
 export interface LostHandler {
     lost(e: Event): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/effects-core",
-  "version": "2.10.0-alpha.0",
+  "version": "2.10.0-alpha.2",
   "description": "Galacean Effects runtime core for the web",
   "module": "./dist/index.mjs",
   "main": "./dist/index.js",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@galacean/effects-specification": "^2.8.1",
-    "@galacean/effects-math": "1.1.0",
+    "@galacean/effects-math": "1.2.0",
     "flatbuffers": "24.3.25",
     "uuid": "9.0.1",
     "libtess": "1.2.2"