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

package/dist/input/enums.d.ts

@@ -0,0 +1,65 @@
+export declare enum MouseFilter {
+    Stop = 0,
+    Pass = 1,
+    Ignore = 2
+}
+export declare enum MouseBehaviorRecursive {
+    Inherited = 0,
+    Disabled = 1,
+    Enabled = 2
+}
+export declare enum MouseButton {
+    None = 0,
+    Left = 1,
+    Right = 2,
+    Middle = 3,
+    WheelUp = 4,
+    WheelDown = 5,
+    WheelLeft = 6,
+    WheelRight = 7,
+    Xbutton1 = 8,
+    Xbutton2 = 9
+}
+export declare enum MouseButtonMask {
+    None = 0,
+    Left = 1,
+    Right = 2,
+    Middle = 4,
+    Xbutton1 = 128,
+    Xbutton2 = 256
+}
+export declare enum FocusMode {
+    None = 0,
+    Click = 1,
+    All = 2,
+    Accessibility = 3
+}
+export declare enum FocusBehaviorRecursive {
+    Inherited = 0,
+    Disabled = 1,
+    Enabled = 2
+}
+export declare enum KeyLocation {
+    Unspecified = 0,
+    Left = 1,
+    Right = 2
+}
+export declare enum CursorShape {
+    Arrow = 0,
+    Ibeam = 1,
+    PointingHand = 2,
+    Cross = 3,
+    Wait = 4,
+    Busy = 5,
+    Drag = 6,
+    CanDrop = 7,
+    Forbidden = 8,
+    Vsize = 9,
+    Hsize = 10,
+    Bdiagsize = 11,
+    Fdiagsize = 12,
+    Move = 13,
+    Vsplit = 14,
+    Hsplit = 15,
+    Help = 16
+}

package/dist/input/index.d.ts

@@ -0,0 +1,2 @@
+export * from './enums';
+export * from './input-event';

package/dist/input/input-event.d.ts

@@ -0,0 +1,77 @@
+import type { Matrix3 } from '@galacean/effects-math/es/core/matrix3';
+import { Vector2 } from '@galacean/effects-math/es/core/vector2';
+import { KeyLocation, MouseButton, MouseButtonMask } from './enums';
+export declare class InputEvent {
+    static readonly deviceIdEmulation = -1;
+    static readonly deviceIdInternal = -2;
+    static readonly deviceIdKeyboard = 16;
+    static readonly deviceIdMouse = 32;
+    device: number;
+    pressed: boolean;
+    canceled: boolean;
+    isPressed(): boolean;
+    isReleased(): boolean;
+    isCanceled(): boolean;
+    isEcho(): boolean;
+    xformedBy(transform: Matrix3): InputEvent;
+}
+export declare class InputEventWithModifiers extends InputEvent {
+    commandOrControlAutoremap: boolean;
+    shiftPressed: boolean;
+    altPressed: boolean;
+    metaPressed: boolean;
+    ctrlPressed: boolean;
+    protected copyModifiersTo(event: InputEventWithModifiers): void;
+    xformedBy(transform: Matrix3): InputEventWithModifiers;
+}
+export declare class InputEventKey extends InputEventWithModifiers {
+    keycode: string;
+    physicalKeycode: string;
+    keyLabel: string;
+    unicode: number;
+    location: KeyLocation;
+    echo: boolean;
+    isEcho(): boolean;
+    xformedBy(transform: Matrix3): InputEventKey;
+}
+export declare class InputEventMouse extends InputEventWithModifiers {
+    buttonMask: MouseButtonMask;
+    position: Vector2;
+    globalPosition: Vector2;
+    protected copyMouseTo(event: InputEventMouse): void;
+    xformedBy(transform: Matrix3): InputEventMouse;
+}
+export declare class InputEventMouseButton extends InputEventMouse {
+    factor: number;
+    buttonIndex: MouseButton;
+    doubleClick: boolean;
+    xformedBy(transform: Matrix3): InputEventMouseButton;
+}
+export declare class InputEventMouseMotion extends InputEventMouse {
+    tilt: Vector2;
+    pressure: number;
+    relative: Vector2;
+    screenRelative: Vector2;
+    velocity: Vector2;
+    screenVelocity: Vector2;
+    penInverted: boolean;
+    xformedBy(transform: Matrix3): InputEventMouseMotion;
+}
+export declare class InputEventScreenTouch extends InputEvent {
+    index: number;
+    position: Vector2;
+    doubleTap: boolean;
+    xformedBy(transform: Matrix3): InputEventScreenTouch;
+}
+export declare class InputEventScreenDrag extends InputEvent {
+    index: number;
+    position: Vector2;
+    relative: Vector2;
+    screenRelative: Vector2;
+    velocity: Vector2;
+    screenVelocity: Vector2;
+    pressure: number;
+    tilt: Vector2;
+    penInverted: boolean;
+    xformedBy(transform: Matrix3): InputEventScreenDrag;
+}

package/dist/plugins/interact/event-system.d.ts

@@ -29,20 +29,67 @@ export declare enum PointerEventType {
 export declare class EventSystem implements Disposable {
     engine: Engine;
     allowPropagation: boolean;
-    enabled: boolean;
     skipPointerMovePicking: boolean;
+    private readonly emulateMouseFromTouch;
+    private readonly emulateTouchFromMouse;
+    private _enabled;
     private handlers;
     private nativeHandlers;
     private target;
+    private mouseState;
+    private touchStates;
+    private mouseFromTouchIndex;
+    private touchFromMousePressed;
+    private addedTabIndex;
+    private addedOutlineStyle;
     constructor(engine: Engine, allowPropagation?: boolean);
+    get enabled(): boolean;
+    set enabled(value: boolean);
     bindListeners(target: HTMLCanvasElement | null): void;
     dispatchEvent(type: string, event: TouchEventType): void;
     addEventListener(type: string, callback: (event: TouchEventType) => void): () => void;
     removeEventListener(type: string, callback: (event: TouchEventType) => void): void;
+    dispose(): void;
+    private onNativeWheel;
+    private onNativeKeyDown;
+    private onNativeKeyUp;
+    private onNativeMouseDown;
+    private onNativeMouseMove;
+    private onNativeMouseUp;
+    private onNativeTouchStart;
+    private onNativeTouchMove;
+    private onNativeTouchEnd;
+    private onNativeTouchCancel;
+    private onWindowBlur;
+    private handleNativeMouseDown;
+    private handleNativeKey;
+    private handleNativeTouchEnd;
+    private pushNativeMouseButton;
+    private pushNativeMouseMotion;
+    private pushNativeScreenTouch;
+    private pushNativeScreenDrag;
+    private pushEmulatedMouseButton;
+    private pushEmulatedMouseMotion;
+    private pushMouseButton;
+    private pushWheelButton;
+    private pushMouseMotion;
+    private pushScreenTouch;
+    private pushScreenDrag;
+    private copyMouseFields;
     private onClick;
     private onPointerDown;
     private onPointerUp;
     private onPointerMove;
     private handlePointerEvent;
-    dispose(): void;
+    private createPointerState;
+    private updatePointerState;
+    private getVelocity;
+    private isClick;
+    private createPointerEvent;
+    private getCanvasPosition;
+    private consumeNativeEvent;
+    private preventTouchDefaults;
+    private focusTarget;
+    private addNativeHandler;
+    private unbindListeners;
 }

package/dist/plugins/particle/particle-mesh.d.ts

@@ -139,11 +139,11 @@ export declare class ParticleMesh implements ParticleMeshData {
     private cachedRotationMatrix;
     private cachedLinearMove;
     private tempMatrix3;
+    private readonly attributeData;
     VERT_MAX_KEY_FRAME_COUNT: number;
     constructor(engine: Engine, props: ParticleMeshProps);
     getPointColor(index: number): number[];
     clearPoints(): void;
-    resetGeometryData(geometry: Geometry): void;
     onUpdate(dt: number): void;
     minusTime(time: number): void;
     removePoint(index: number): void;
@@ -151,6 +151,9 @@ export declare class ParticleMesh implements ParticleMeshData {
     private applyTranslation;
     private applyRotation;
     private applyLinearMove;
+    private getAttributeData;
+    private setAttributeData;
+    private setAttributeSubData;
     private expandArray;
 }
 export declare function getParticleMeshShader(item: spec.ParticleItem, gpuCapability: GPUCapability, env?: string): {

package/dist/plugins/particle/particle-system.d.ts

@@ -171,6 +171,13 @@ export declare class ParticleSystem extends Component implements Maskable {
     private update;
     drawStencilMask(maskRef: number): void;
     onDestroy(): void;
+    /**
+     * @hidden
+     * Internal utility.
+     * Not part of the public API — do not rely on this in your code.
+     */
+    rebuild(): void;
+    dispose(): void;
     getParticleBoxes(): {
         center: Vector3;
         size: Vector3;

package/dist/plugins/particle/trail-mesh.d.ts

@@ -41,6 +41,7 @@ export declare class TrailMesh {
     checkVertexDistance: boolean;
     private pointStart;
     private trailCursors;
+    private readonly attributeData;
     constructor(engine: Engine, props: TrailMeshProps);
     get time(): number;
     set time(t: number);
@@ -52,5 +53,8 @@ export declare class TrailMesh {
     getPointStartPos(index: number): Vector3;
     setPointStartPos(index: number, pos: Vector3): void;
     onUpdate(escapeTime: number): any;
+    private getAttributeData;
+    private setAttributeData;
+    private setAttributeSubData;
 }
 export declare function getTrailMeshShader(trails: spec.ParticleTrail, particleMaxCount: number, name: string, gpuCapability: GPUCapability, env?: string): ShaderWithSource;

package/dist/plugins/shape/shape-component.d.ts

@@ -158,6 +158,7 @@ export declare class ShapeComponent extends RendererComponent implements Maskabl
     getBoundingBox(): BoundingBoxTriangle;
     getBoundingBoxInfo(): BoundingBoxInfo;
     private buildGeometryFromPath;
+    private updateAttributeData;
     private computeScreenScale;
     private buildPath;
     private updateMaterials;

package/dist/plugins/sprite/sprite-item.d.ts

@@ -76,5 +76,6 @@ export declare class SpriteComponent extends MaskableGraphic {
      * 不依赖组件状态，splits 由参数传入（同时存在帧动画与多 split 的数据不存在）。
      */
     protected updateGeometryFromMultiSplit(splits: spec.SplitParameter[]): void;
+    private updateAttributeData;
 }
 export {};

package/dist/render/buffer.d.ts

@@ -0,0 +1,33 @@
+import type { Engine } from '../engine';
+import type { Disposable } from '../utils';
+import type { DataArray } from './data-buffer';
+import { DataBuffer } from './data-buffer';
+import { VertexBuffer } from './vertex-buffer';
+/**
+ * 管理顶点数据及其对应的后端缓冲区。
+ */
+export declare class Buffer implements Disposable {
+    readonly engine: Engine;
+    readonly byteStride: number;
+    private data?;
+    private buffer?;
+    private readonly updatable;
+    private readonly instanced;
+    private readonly divisor;
+    private readonly label?;
+    private isAlreadyOwned;
+    private _isDisposed;
+    constructor(engine: Engine, data: DataArray | DataBuffer, updatable: boolean, stride?: number, postponeInternalCreation?: boolean, instanced?: boolean, useBytes?: boolean, divisor?: number, label?: string);
+    get isDisposed(): boolean;
+    get capacity(): number;
+    isUpdatable(): boolean;
+    getData(): DataArray | undefined;
+    getBuffer(): DataBuffer | undefined;
+    getStrideSize(): number;
+    createVertexBuffer(kind: string, offset: number, size: number, stride?: number, instanced?: boolean, useBytes?: boolean, divisor?: number): VertexBuffer;
+    create(data?: DataArray): void;
+    update(data: DataArray): void;
+    updateDirectly(data: DataArray, offset: number, vertexCount?: number, useBytes?: boolean): void;
+    dispose(): void;
+    private getDataBufferOptions;
+}

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

@@ -0,0 +1,39 @@
+import type * as spec from '@galacean/effects-specification';
+export type DataArray = number[] | ArrayBuffer | ArrayBufferView;
+export type IndicesArray = number[] | Int32Array | Uint32Array | Uint16Array;
+export type IndexData = Int32Array | Uint32Array | Uint16Array;
+export declare enum BufferUsage {
+    Stream = 35040,
+    Static = 35044,
+    Dynamic = 35048
+}
+export declare enum BufferDataType {
+    Byte = 5120,
+    UnsignedByte = 5121,
+    Short = 5122,
+    UnsignedShort = 5123,
+    Int = 5124,
+    UnsignedInt = 5125,
+    Float = 5126
+}
+export interface DataBufferOptions {
+    usage: number;
+    type: number;
+    byteStride: number;
+    instanceDivisor: number;
+    label?: string;
+}
+/**
+ * 后端缓冲区的最小抽象，只保存资源状态。
+ */
+export declare class DataBuffer {
+    references: number;
+    capacity: number;
+    is32Bits: boolean;
+    get underlyingResource(): unknown;
+}
+export declare function getBytesPerElement(type: number): number;
+export declare function getDataType(data: DataArray): BufferDataType;
+export declare function getDataByteLength(data: DataArray): number;
+export declare function toBufferView(data: DataArray): ArrayBufferView;
+export declare function createTypedArray(type: number, length: number): spec.TypedArray;

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

@@ -17,6 +17,7 @@ export declare class Graphics {
     private geometry;
     private coloredMaterial;
     private texturedMaterial;
+    private textMaterial;
     private readonly lineShape;
     private readonly bezierShape;
     private readonly triangleShape;
@@ -62,6 +63,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个数值)

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

@@ -9,19 +9,14 @@ export type FontWeight = 'normal' | 'bold' | number;
  */
 export type FontStyle = 'normal' | 'italic';
 /**
- * 字形纹理超采样倍数。canvas 按 `fontSize * FONT_SCALE` 渲染，纹理像素也是 scale 倍，
- * 但 quad 仍按 1x 逻辑尺寸绘制 — 双线性 downsample 后比原 1x 渲染清晰得多
- */
-export declare const FONT_SCALE = 2;
-/**
- * 单张字符 atlas 的边长(像素,scale 后的实际像素,非逻辑尺寸)。
+ * 单张字符 atlas 的逻辑边长。实际 canvas 像素尺寸会乘以渲染 resolution。
  * 512×512 在 24px 字号下约可容纳 250+ 字形,常见 demo 文本足够
  */
 export declare const ATLAS_SIZE = 512;
 /**
  * 单个字形在 atlas 中的位置 / 度量。
  *
- * `px/py/pw/ph` 是 atlas canvas 像素（scale 后，含四周 padding）。
+ * `px/py/pw/ph` 是 atlas canvas 像素（resolution 后，含四周 padding）。
  * `advance` 是逻辑像素光标前进量（1x，不含 padding）— quad 宽度含 padding，
  * 但相邻字只按 advance 前进，padding 区透明因此重叠无妨。
  * `paddingLeft` 是逻辑像素左侧留白（1x），quad 起点左偏此量使字形 ink 落在 cursorX
@@ -47,12 +42,14 @@ export type GlyphInfo = {
 export declare class GlyphAtlas {
     private engine;
     private readonly scaledFontString;
-    /** atlas canvas（像素 = ATLAS_SIZE × ATLAS_SIZE，自有不进 canvasPool） */
+    /** atlas canvas（像素 = ATLAS_SIZE × resolution，自有不进 canvasPool） */
     readonly canvas: HTMLCanvasElement;
     /** 与 canvas 绑定的纹理，内容变更后通过 updateSource 重传 */
     readonly texture: Texture;
     /** cell 高（逻辑像素，含 padding），用于 quad 高度 */
     readonly lineHeight: number;
+    /** 字形 canvas 的像素密度，与 Pixi 的纹理 resolution 语义一致。 */
+    readonly resolution: number;
     private readonly ctx;
     private readonly glyphs;
     /** baseline 距 cell 顶距离（像素，scale 后，含顶部 padding） */
@@ -74,7 +71,7 @@ export declare class GlyphAtlas {
     /** baseline 距 cell 顶距离（像素，scale 后，仅 ascent 部分，不含 padding） */
     ascentPx: number, 
     /** baseline 距 cell 底距离（像素，scale 后，仅 descent 部分） */
-    descentPx: number, fontStyle: FontStyle);
+    descentPx: number, fontStyle: FontStyle, resolution: number);
     /**
      * 取（必要时渲染并打包）单字。返回 GlyphInfo 或 null（atlas 已满）
      */
@@ -99,6 +96,7 @@ export declare class TextCache {
     private engine;
     /** fontKey -> 该字体的字符 atlas */
     private readonly atlases;
+    private resolution;
     constructor(engine: Engine);
     /**
      * 取(必要时新建)对应字体的字符 atlas
@@ -114,4 +112,5 @@ export declare class TextCache {
      * 清空所有 atlas 并 dispose 对应纹理。Engine dispose 时调用
      */
     dispose(): void;
+    private clear;
 }