ice3 0.1.1 → 0.2.1

package/README.md

@@ -47,6 +47,10 @@ scene.addChild(new ICEMesh({
 engine.setScene(scene).setCamera(camera).start();
 ```
 
+默认使用 WebGL2。WebGPU 是实验性能力，必须显式使用
+`await new ICE3({ renderer: 'webgpu' }).initAsync(host)` 才会启用；`auto` 保留为
+WebGL2 兼容别名。拾取使用 `await engine.pick(point)`。
+
 完整文档和相关工具见
 [Engine 文档](https://github.com/ice-3d/ice3-engine/blob/main/README.md)。
 

package/dist/_types/assets/ICEPreparedGLB.d.ts

@@ -21,6 +21,7 @@ export interface ICEPreparedMaterial {
     readonly id: string;
     readonly baseColor: string;
     readonly edgeColor?: string;
+    readonly shading?: 'directional' | 'flat' | 'water';
 }
 export interface ICEPreparedMesh {
     readonly id: string;

package/dist/_types/assets/ICEPreviewGeometryPacket.d.ts

@@ -0,0 +1,60 @@
+export type ICEPreviewGeometryBackend = 'cpu' | 'gpu';
+export type ICEPreviewGeometryResidencyMode = 'cpu' | 'cold' | 'warm' | 'resident' | 'snapshot';
+export type ICEPreviewGeometryRangeUsage = 'vertex_attributes' | 'indices';
+export interface ICEPreviewGeometryRange {
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    readonly usage: ICEPreviewGeometryRangeUsage;
+}
+export interface ICEPreviewGeometryNode {
+    readonly nodeId: string;
+    readonly parentId: string | null;
+    readonly name: string;
+    readonly matrix: readonly number[];
+    readonly materialId: string | null;
+    readonly geometryId: string | null;
+    readonly visible: boolean;
+}
+export interface ICEPreviewGeometryRecord {
+    readonly geometryId: string;
+    readonly residentGeometryId: string | null;
+    readonly topologyDigest: string;
+    readonly attributeDigest: string;
+    readonly vertexCount: number;
+    readonly indexCount: number;
+    readonly indexWidth: 2 | 4;
+    readonly ranges: readonly ICEPreviewGeometryRange[];
+}
+export interface ICEPreviewGeometry extends ICEPreviewGeometryRecord {
+    readonly positions: Float32Array;
+    readonly indices: Uint16Array | Uint32Array;
+}
+export interface ICEPreviewGeometryMaterial {
+    readonly materialId: string;
+    readonly baseColor: readonly [number, number, number, number];
+    readonly metallic: number;
+    readonly roughness: number;
+    readonly opacity: number;
+}
+export interface ICEPreviewGeometryManifest {
+    readonly schemaVersion: number;
+    readonly transportVersion: number;
+    readonly revision: number;
+    readonly parentRevision: number | null;
+    readonly sourceDigest: string;
+    readonly backend: ICEPreviewGeometryBackend;
+    readonly residencyMode: ICEPreviewGeometryResidencyMode;
+    readonly nodes: readonly ICEPreviewGeometryNode[];
+    readonly geometries: readonly ICEPreviewGeometryRecord[];
+    readonly materials: readonly ICEPreviewGeometryMaterial[];
+    readonly removedNodeIds: readonly string[];
+    readonly removedGeometryIds: readonly string[];
+}
+export interface ICEPreviewGeometryPacket extends Omit<ICEPreviewGeometryManifest, 'geometries'> {
+    readonly geometries: readonly ICEPreviewGeometry[];
+    readonly binary: Uint8Array;
+}
+export type ICEPreviewGeometryDelta = ICEPreviewGeometryPacket;
+export declare function parsePreviewGeometryPacket(input: Uint8Array | ArrayBuffer): ICEPreviewGeometryPacket;
+export declare function applyPreviewGeometryDelta(base: ICEPreviewGeometryPacket, delta: ICEPreviewGeometryDelta): ICEPreviewGeometryPacket;
+//# sourceMappingURL=ICEPreviewGeometryPacket.d.ts.map

package/dist/_types/assets/index.d.ts

@@ -1,5 +1,7 @@
 export { readPreparedGLB, verifyPreparedGLBIntegrity, } from './ICEGLBReader.js';
 export type { ICEPreparedAssetSnapshot, ICEPreparedBatch, ICEPreparedBatching, ICEPreparedContract, ICEPreparedGeometry, ICEPreparedMaterial, ICEPreparedMesh, ICEPreparedNode, ICEPreparedStats, } from './ICEPreparedGLB.js';
+export { applyPreviewGeometryDelta, parsePreviewGeometryPacket, } from './ICEPreviewGeometryPacket.js';
+export type { ICEPreviewGeometry, ICEPreviewGeometryBackend, ICEPreviewGeometryDelta, ICEPreviewGeometryManifest, ICEPreviewGeometryMaterial, ICEPreviewGeometryNode, ICEPreviewGeometryPacket, ICEPreviewGeometryRange, ICEPreviewGeometryRangeUsage, ICEPreviewGeometryRecord, ICEPreviewGeometryResidencyMode, } from './ICEPreviewGeometryPacket.js';
 export { readTileset } from './ICETilesetReader.js';
 export type { ICETilesetSnapshot, ICETilesetTile, } from './ICETileset.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/_types/core/camera/ICEPerspectiveCamera.d.ts

@@ -11,13 +11,14 @@ export interface ICEPerspectiveCameraOptions {
 export declare class ICEPerspectiveCamera {
     readonly id: string;
     readonly fov: number;
-    readonly near: number;
-    readonly far: number;
+    near: number;
+    far: number;
     private eye;
     private lookTarget;
     constructor(options: ICEPerspectiveCameraOptions);
     setPosition(position: ICEVector3Tuple): this;
     setTarget(target: ICEVector3Tuple): this;
+    setClipPlanes(near: number, far: number): this;
     getPosition(): ICEVector3;
     getTarget(): ICEVector3;
     getViewProjectionMatrix(aspect: number): ICEMatrix4;

package/dist/_types/core/geometry/ICEGeometry.d.ts

@@ -2,6 +2,18 @@ export interface ICEGeometryBounds {
     readonly min: readonly [number, number, number];
     readonly max: readonly [number, number, number];
 }
+export interface ICEGeometryIdentity {
+    readonly geometryId: string;
+    readonly topologyDigest: string;
+    readonly attributeDigest: string;
+}
+export interface ICEGeometryByteRange {
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+export interface ICEGeometryBufferUpdate {
+    readonly positionRanges: readonly ICEGeometryByteRange[];
+}
 export interface ICEGeometry {
     readonly typeId: string;
     readonly positions: Float32Array;
@@ -9,6 +21,7 @@ export interface ICEGeometry {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity?: ICEGeometryIdentity;
     getBounds(): ICEGeometryBounds;
     toJSON(): Record<string, unknown>;
 }

package/dist/_types/core/geometry/ICEIndexedGeometry.d.ts

@@ -1,4 +1,4 @@
-import type { ICEGeometry, ICEGeometryBounds } from './ICEGeometry.js';
+import type { ICEGeometry, ICEGeometryBounds, ICEGeometryIdentity } from './ICEGeometry.js';
 export interface ICEIndexedGeometryOptions {
     readonly id: string;
     readonly positions: Float32Array;
@@ -6,6 +6,7 @@ export interface ICEIndexedGeometryOptions {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity?: ICEGeometryIdentity;
 }
 export declare class ICEIndexedGeometry implements ICEGeometry {
     readonly typeId = "ice3:IndexedGeometry";
@@ -15,6 +16,7 @@ export declare class ICEIndexedGeometry implements ICEGeometry {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity: ICEGeometryIdentity;
     constructor(options: ICEIndexedGeometryOptions);
     getBounds(): ICEGeometryBounds;
     toJSON(): Record<string, unknown>;

package/dist/_types/core/index.d.ts

@@ -7,7 +7,7 @@ export { ICEBoxGeometry } from './geometry/ICEBoxGeometry.js';
 export type { ICEBoxGeometryOptions } from './geometry/ICEBoxGeometry.js';
 export { ICEIndexedGeometry } from './geometry/ICEIndexedGeometry.js';
 export type { ICEIndexedGeometryOptions } from './geometry/ICEIndexedGeometry.js';
-export type { ICEGeometry, ICEGeometryBounds } from './geometry/ICEGeometry.js';
+export type { ICEGeometry, ICEGeometryBounds, ICEGeometryBufferUpdate, ICEGeometryByteRange, ICEGeometryIdentity, } from './geometry/ICEGeometry.js';
 export { ICEBasicMaterial } from './material/ICEBasicMaterial.js';
 export type { ICEBasicMaterialOptions } from './material/ICEBasicMaterial.js';
 export { ICEPerspectiveCamera } from './camera/ICEPerspectiveCamera.js';

package/dist/_types/core/material/ICEBasicMaterial.d.ts

@@ -1,11 +1,13 @@
 export interface ICEBasicMaterialOptions {
     readonly color: string;
     readonly edgeColor?: string;
+    readonly shading?: 'directional' | 'flat' | 'water';
 }
 export declare class ICEBasicMaterial {
     readonly typeId = "ice3:BasicMaterial";
     readonly color: string;
     readonly edgeColor: string | undefined;
+    readonly shading: 'directional' | 'flat' | 'water' | undefined;
     constructor(options: ICEBasicMaterialOptions);
     toJSON(): Record<string, unknown>;
 }

package/dist/_types/core/scene/ICENode.d.ts

@@ -50,13 +50,17 @@ export declare class ICENode extends ICEEventDispatcher {
     readonly position: ICEVector3;
     readonly rotation: ICEVector3;
     readonly scale: ICEVector3;
-    visible: boolean;
     private _parent;
     private readonly _children;
     private readonly worldMatrix;
     private localMatrixOverride;
+    private _visible;
+    private _revision;
     constructor(options: ICENodeOptions);
     get typeId(): string;
+    get visible(): boolean;
+    set visible(value: boolean);
+    get revision(): number;
     get parent(): ICENode | null;
     get children(): readonly ICENode[];
     addChild(node: ICENode): this;
@@ -71,6 +75,7 @@ export declare class ICENode extends ICEEventDispatcher {
     toJSON(): ICESerializedNode;
     dispose(): void;
     private getRoot;
+    private markSceneChanged;
     private isAncestorOf;
     private localMatrix;
 }

package/dist/_types/renderer/Color.d.ts

@@ -0,0 +1,2 @@
+export declare function colorToRgba(color: string): readonly [number, number, number, number];
+//# sourceMappingURL=Color.d.ts.map

package/dist/_types/renderer/FakeRendererBackend.d.ts

@@ -19,7 +19,7 @@ export declare class FakeRendererBackend implements ICERendererBackend {
     prepareBatchGeometry(): void;
     releaseBatchGeometry(): void;
     render(frame: ICEFrame): void;
-    pick(): string | undefined;
+    pick(): Promise<string | undefined>;
     dispose(): void;
     get disposeCount(): number;
     private assertActive;

package/dist/_types/renderer/InstanceBatch.d.ts

@@ -0,0 +1,14 @@
+import type { ICEBasicMaterial, ICEGeometry } from '../core/index.js';
+import type { ICEGeometryRenderable } from './Renderables.js';
+export interface ICEInstanceBatch {
+    readonly id: string;
+    readonly geometry: ICEGeometry;
+    readonly material: ICEBasicMaterial;
+    readonly instanceMatrices: Float32Array;
+    readonly semanticIds: readonly string[];
+    readonly semanticIndices: Uint32Array;
+    readonly meshIds: readonly string[];
+    readonly materialKey: string;
+}
+export declare function collectInstanceBatches(renderables: readonly ICEGeometryRenderable[], output?: ICEInstanceBatch[]): readonly ICEInstanceBatch[];
+//# sourceMappingURL=InstanceBatch.d.ts.map

package/dist/_types/renderer/RenderBatch.d.ts

@@ -0,0 +1,17 @@
+import type { ICEBasicMaterial, ICEGeometry, ICENode, ICEScene } from '../core/index.js';
+export interface ICERenderBatchNode extends ICENode {
+    readonly geometry: ICEGeometry;
+    readonly material: ICEBasicMaterial;
+    readonly semanticIds: readonly string[];
+    readonly semanticNodeIds: readonly string[];
+    readonly semanticSelectionIds: readonly string[];
+    readonly materialKey: string;
+}
+export interface ICERenderBatchDraw {
+    readonly id: string;
+    readonly batch: ICERenderBatchNode;
+    readonly worldMatrix: Float32Array;
+}
+export declare function collectRenderBatches(scene: ICEScene, output?: ICERenderBatchDraw[]): readonly ICERenderBatchDraw[];
+export declare function semanticSelectionId(batch: Pick<ICERenderBatchNode, 'semanticSelectionIds'>, semanticIndex: number): string | undefined;
+//# sourceMappingURL=RenderBatch.d.ts.map

package/dist/_types/renderer/Renderables.d.ts

@@ -0,0 +1,9 @@
+import { ICEMesh, type ICEScene } from '../core/index.js';
+export interface ICEGeometryRenderable {
+    readonly id: string;
+    readonly mesh: ICEMesh;
+    readonly worldMatrix: Float32Array;
+}
+export declare function collectRenderables(scene: ICEScene, output?: ICEGeometryRenderable[]): readonly ICEGeometryRenderable[];
+export declare const selectionIdentity: (mesh: ICEMesh) => string;
+//# sourceMappingURL=Renderables.d.ts.map

package/dist/_types/renderer/RendererProfiler.d.ts

@@ -0,0 +1,19 @@
+export type ICEFrameStageProfile = Readonly<{
+    collectMs: number;
+    prepareAndUploadMs: number;
+    encodeMs: number;
+    submitMs: number;
+}>;
+type Stage = 'collect' | 'prepareAndUpload' | 'encode' | 'submit';
+export declare class RendererProfiler {
+    private enabled;
+    private cursor;
+    private readonly marks;
+    enable(value: boolean): void;
+    get isEnabled(): boolean;
+    begin(): void;
+    mark(stage: Stage): void;
+    end(): ICEFrameStageProfile | null;
+}
+export {};
+//# sourceMappingURL=RendererProfiler.d.ts.map

package/dist/_types/renderer/RendererSelection.d.ts

@@ -0,0 +1,12 @@
+import type { ICE3RendererPreference, ICE3RendererSelection, ICERendererBackend } from './types.js';
+export type ICERendererFactories = Readonly<{
+    createWebGPU: () => Promise<ICERendererBackend>;
+    createWebGL2: () => ICERendererBackend;
+}>;
+export type ICERendererBackendSelection = Readonly<{
+    backend: ICERendererBackend;
+    selection: ICE3RendererSelection;
+}>;
+export declare function selectRendererBackend(preference: ICE3RendererPreference, factories: ICERendererFactories): Promise<ICERendererBackendSelection>;
+export declare function selectDefaultRendererBackend(preference: ICE3RendererPreference): Promise<ICERendererBackendSelection>;
+//# sourceMappingURL=RendererSelection.d.ts.map

package/dist/_types/renderer/WebGL2GeometryBatch.d.ts

@@ -1,10 +1,3 @@
-import { ICEMesh, type ICEScene } from '../core/index.js';
-export interface ICEGeometryRenderable {
-    readonly id: string;
-    readonly mesh: ICEMesh;
-    readonly worldMatrix: Float32Array;
-}
-export declare function collectRenderables(scene: ICEScene, output?: ICEGeometryRenderable[]): readonly ICEGeometryRenderable[];
-export declare const selectionIdentity: (mesh: ICEMesh) => string;
-export { collectRenderBatches, semanticSelectionId, type ICERenderBatchDraw, type ICERenderBatchNode, } from './WebGL2RenderBatch.js';
+export { collectRenderables, selectionIdentity, type ICEGeometryRenderable, } from './Renderables.js';
+export { collectRenderBatches, semanticSelectionId, type ICERenderBatchDraw, type ICERenderBatchNode, } from './RenderBatch.js';
 //# sourceMappingURL=WebGL2GeometryBatch.d.ts.map

package/dist/_types/renderer/WebGL2GeometryCache.d.ts

@@ -1,5 +1,9 @@
-import type { ICEGeometry } from '../core/index.js';
+import type { ICEGeometry, ICEGeometryBufferUpdate } from '../core/index.js';
 export interface GeometryEntry {
+    geometry: ICEGeometry;
+    readonly geometryId: string;
+    readonly attributeDigest: string;
+    readonly topologyDigest: string;
     readonly vertexArray: WebGLVertexArrayObject;
     readonly positionBuffer: WebGLBuffer;
     readonly triangleIndexBuffer: WebGLBuffer;
@@ -19,24 +23,34 @@ export declare class WebGL2GeometryCache {
     private readonly entries;
     private active;
     private readonly pinned;
+    private readonly objectKeys;
+    private readonly legacyKeys;
+    private objectKeySequence;
     private gl;
     private uploads;
+    private updatedBytes;
     private evictions;
     private frameId;
     private readonly inactiveGraceFrames;
     private readonly maxBytes;
     constructor(options?: WebGL2GeometryCacheOptions);
     retain(gl: WebGL2RenderingContext, geometry: ICEGeometry): Readonly<GeometryEntry>;
+    private createEntry;
     beginFrame(): void;
-    pin(gl: WebGL2RenderingContext, geometry: ICEGeometry): Readonly<GeometryEntry>;
+    pin(gl: WebGL2RenderingContext, geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): Readonly<GeometryEntry>;
     unpin(geometry: ICEGeometry): void;
     endFrame(): void;
     clear(): void;
     dispose(): void;
     get totalBytes(): number;
     get uploadCount(): number;
+    get updateBytes(): number;
     get evictionCount(): number;
     private deleteEntry;
     private enforceBudget;
+    private applyPositionUpdate;
+    private canReuse;
+    private sameTopology;
+    private keyFor;
 }
 //# sourceMappingURL=WebGL2GeometryCache.d.ts.map

package/dist/_types/renderer/WebGL2InstanceBatch.d.ts

@@ -1,17 +1,7 @@
-import type { ICEBasicMaterial, ICEGeometry } from '../core/index.js';
 import { WebGL2GeometryCache } from './WebGL2GeometryCache.js';
-import type { ICEGeometryRenderable } from './WebGL2GeometryBatch.js';
-export type { ICEGeometryRenderable } from './WebGL2GeometryBatch.js';
-export interface ICEInstanceBatch {
-    readonly id: string;
-    readonly geometry: ICEGeometry;
-    readonly material: ICEBasicMaterial;
-    readonly instanceMatrices: Float32Array;
-    readonly semanticIds: readonly string[];
-    readonly semanticIndices: Uint32Array;
-    readonly meshIds: readonly string[];
-    readonly materialKey: string;
-}
+import type { ICEInstanceBatch } from './InstanceBatch.js';
+export type { ICEGeometryRenderable } from './Renderables.js';
+export { collectInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
 export interface WebGL2InstanceEntry {
     readonly vertexArray: WebGLVertexArrayObject;
     readonly matrixBuffer: WebGLBuffer;
@@ -37,5 +27,4 @@ export declare class WebGL2InstanceCache {
     get totalBytes(): number;
     private deleteEntry;
 }
-export declare function collectInstanceBatches(renderables: readonly ICEGeometryRenderable[], output?: ICEInstanceBatch[]): readonly ICEInstanceBatch[];
 //# sourceMappingURL=WebGL2InstanceBatch.d.ts.map

package/dist/_types/renderer/WebGL2Program.d.ts

@@ -1,4 +1,5 @@
 import type { ICEMatrix4 } from '../core/index.js';
+export declare function directionalLightingShade(normal: readonly [number, number, number]): number;
 export declare class WebGL2Program {
     private readonly gl;
     static readonly POSITION_ATTRIBUTE = 0;
@@ -10,14 +11,27 @@ export declare class WebGL2Program {
     private readonly colorLocation;
     private readonly clipOffsetLocation;
     private readonly vertexColorLocation;
+    private readonly directionalShadingLocation;
+    private readonly waterShadingLocation;
+    private readonly cameraPositionLocation;
+    private readonly shadowMapLocation;
+    private readonly lightMatrixLocation;
+    private readonly shadowEnabledLocation;
     private readonly instancingLocation;
+    private readonly pickModeLocation;
     constructor(gl: WebGL2RenderingContext);
     use(): void;
     setMatrix(matrix: ICEMatrix4): void;
     setColor(color: readonly [number, number, number, number]): void;
     setClipOffset(x: number, y: number): void;
     setVertexColors(enabled: boolean): void;
+    /** 绑定阴影贴图与光源矩阵；关闭时着色器跳过采样。 */
+    setShadow(enabled: boolean, texture: WebGLTexture | null, matrix: Float32Array | null, unit?: number): void;
+    setDirectionalShading(enabled: boolean): void;
+    setWaterShading(enabled: boolean): void;
+    setCameraPosition(position: readonly [number, number, number]): void;
     setInstancing(enabled: boolean): void;
+    setPickMode(enabled: boolean): void;
     dispose(): void;
     private createProgram;
     private compile;

package/dist/_types/renderer/WebGL2RenderBatch.d.ts

@@ -1,17 +1,2 @@
-import type { ICEBasicMaterial, ICEGeometry, ICENode, ICEScene } from '../core/index.js';
-export interface ICERenderBatchNode extends ICENode {
-    readonly geometry: ICEGeometry;
-    readonly material: ICEBasicMaterial;
-    readonly semanticIds: readonly string[];
-    readonly semanticNodeIds: readonly string[];
-    readonly semanticSelectionIds: readonly string[];
-    readonly materialKey: string;
-}
-export interface ICERenderBatchDraw {
-    readonly id: string;
-    readonly batch: ICERenderBatchNode;
-    readonly worldMatrix: Float32Array;
-}
-export declare function collectRenderBatches(scene: ICEScene, output?: ICERenderBatchDraw[]): readonly ICERenderBatchDraw[];
-export declare function semanticSelectionId(batch: Pick<ICERenderBatchNode, 'semanticSelectionIds'>, semanticIndex: number): string | undefined;
+export { collectRenderBatches, semanticSelectionId, type ICERenderBatchDraw, type ICERenderBatchNode, } from './RenderBatch.js';
 //# sourceMappingURL=WebGL2RenderBatch.d.ts.map

package/dist/_types/renderer/WebGL2RendererBackend.d.ts

@@ -1,6 +1,7 @@
 import { type ICEGeometry } from '../core/index.js';
+import { type ICEFrameStageProfile } from './RendererProfiler.js';
 import type { ICERendererBackend, ICERendererCapabilities, ICEFrame, ICEScreenPoint, ICEViewport } from './types.js';
-export declare function colorToRgba(color: string): readonly [number, number, number, number];
+export { colorToRgba } from './Color.js';
 export declare class WebGL2RendererBackend implements ICERendererBackend {
     capabilities: Readonly<ICERendererCapabilities>;
     private canvas;
@@ -10,6 +11,8 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     private onContextLost;
     private onContextRestored;
     private program;
+    private shadowMap;
+    private readonly shadowEnabled;
     private semanticProgram;
     private geometryCache;
     private instanceCache;
@@ -20,6 +23,8 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     private readonly batchesScratch;
     private readonly instancesScratch;
     private readonly instancedMeshIds;
+    private readonly profiler;
+    private lastFrameProfile;
     private backgroundRgba;
     private frameStats;
     private readonly handleContextLost;
@@ -32,9 +37,15 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     resize(viewport: ICEViewport, dpr: number): void;
     setBackgroundColor(color: string): void;
     prepareBatchGeometry(geometry: ICEGeometry): void;
+    prepareGeometry(geometry: ICEGeometry, update?: import('../core/index.js').ICEGeometryBufferUpdate): void;
+    releaseGeometry(geometry: ICEGeometry): void;
     releaseBatchGeometry(geometry: ICEGeometry): void;
     render(frame: ICEFrame): void;
-    pick(frame: ICEFrame, point: ICEScreenPoint): string | undefined;
+    enableProfiling(enabled: boolean): void;
+    get frameProfile(): ICEFrameStageProfile | null;
+    pick(frame: ICEFrame, point: ICEScreenPoint): Promise<string | undefined>;
+    capture(): Promise<Blob>;
+    finish(): Promise<void>;
     dispose(): void;
     getViewport(): ICEViewport;
     getDevicePixelRatio(): number;

package/dist/_types/renderer/WebGL2ShadowMap.d.ts

@@ -0,0 +1,26 @@
+/** 光源方向（与主着色器的 diffuse 保持同一方向）。 */
+export declare const LIGHT_DIRECTION: readonly [number, number, number];
+export declare class WebGL2ShadowMap {
+    private readonly gl;
+    private framebuffer;
+    private depthTexture;
+    private program;
+    private lightMatrixLocation;
+    private matrixScratch;
+    constructor(gl: WebGL2RenderingContext);
+    /** 深度纹理，供主着色器采样。 */
+    get texture(): WebGLTexture | null;
+    get matrix(): Float32Array;
+    /** 绑定阴影帧缓冲，返回是否成功。 */
+    begin(): boolean;
+    /** 解绑，恢复默认帧缓冲。 */
+    end(width: number, height: number): void;
+    dispose(): void;
+    private createResources;
+    /** 正交光源矩阵：覆盖整片场地，与主着色器的光方向一致。 */
+    private updateLightMatrix;
+    private createProgram;
+    private compile;
+}
+export declare const SHADOW_BIAS = 0.0018;
+//# sourceMappingURL=WebGL2ShadowMap.d.ts.map

package/dist/_types/renderer/WebGPUBundleCache.d.ts

@@ -0,0 +1,14 @@
+export declare class WebGPUBundleCache {
+    private readonly device;
+    private readonly format;
+    private key;
+    private bundle;
+    private recreations;
+    constructor(device: GPUDevice, format: GPUTextureFormat);
+    get(key: string, record: (encoder: GPURenderBundleEncoder) => void): GPURenderBundle;
+    get current(): GPURenderBundle | null;
+    get bundleRecreations(): number;
+    invalidate(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=WebGPUBundleCache.d.ts.map

package/dist/_types/renderer/WebGPUCapabilities.d.ts

@@ -0,0 +1,23 @@
+export type ICEWebGPUAccelerationTier = 'baseline' | 'storage' | 'gpu-driven';
+export declare const WEBGPU_STORAGE_DEFAULT = false;
+export declare const WEBGPU_GPU_DRIVEN_DEFAULT = false;
+export declare const WEBGPU_INSTANCE_VISIBILITY_THRESHOLD = 1024;
+export type ICEWebGPUOptimizationStats = Readonly<{
+    tier: ICEWebGPUAccelerationTier;
+    selectionMaskActive: boolean;
+    bundleActive: boolean;
+    storageActive: boolean;
+    visibilityActive: boolean;
+    instanceUploadBytes: number;
+    bundleRecreations: number;
+    timestampUnavailableReason?: string;
+}>;
+export type ICEWebGPUAcceleration = Readonly<{
+    tier: ICEWebGPUAccelerationTier;
+    storage: boolean;
+    visibility: boolean;
+    maxStorageBufferBindingSize: number;
+    minStorageBufferOffsetAlignment: number;
+}>;
+export declare function detectWebGPUAcceleration(device: GPUDevice): ICEWebGPUAcceleration;
+//# sourceMappingURL=WebGPUCapabilities.d.ts.map

package/dist/_types/renderer/WebGPUDrawStorage.d.ts

@@ -0,0 +1,28 @@
+export type ICEWebGPUDrawUniform = Readonly<{
+    matrix: ArrayLike<number>;
+    color: readonly [number, number, number, number];
+    useVertexColor: boolean;
+    useInstancing: boolean;
+    useLighting?: boolean;
+    semanticHighlight?: number;
+    useSemantic?: boolean;
+    selectionBase: number;
+    useSelectionMask: boolean;
+    pageBase?: number;
+    useIndirect?: boolean;
+}>;
+export declare class WebGPUDrawStorage {
+    private readonly minimumCapacity;
+    private uniformBuffer;
+    private capacity;
+    private generationValue;
+    private count;
+    constructor(minimumCapacity?: number);
+    begin(requiredDraws: number): void;
+    append(draw: ICEWebGPUDrawUniform): number;
+    get uniformData(): Float32Array;
+    get drawCount(): number;
+    get generation(): number;
+    private ensureCapacity;
+}
+//# sourceMappingURL=WebGPUDrawStorage.d.ts.map

package/dist/_types/renderer/WebGPUGeometryCache.d.ts

@@ -0,0 +1,59 @@
+import { type ICEGeometry, type ICEGeometryBufferUpdate } from '../core/index.js';
+export interface WebGPUGeometryEntry {
+    geometry: ICEGeometry;
+    readonly geometryId: string;
+    readonly attributeDigest: string;
+    readonly topologyDigest: string;
+    readonly vertexBuffer: GPUBuffer;
+    readonly triangleIndexBuffer: GPUBuffer;
+    readonly edgeIndexBuffer: GPUBuffer | null;
+    readonly semanticBuffer: GPUBuffer | null;
+    readonly triangleCount: number;
+    readonly edgeCount: number;
+    readonly indexFormat: GPUIndexFormat;
+    readonly vertexCount: number;
+    readonly bytes: number;
+    lastUsedFrame: number;
+}
+export interface WebGPUGeometryCacheOptions {
+    readonly device: GPUDevice;
+    readonly inactiveGraceFrames?: number;
+    readonly maxBytes?: number;
+}
+export declare class WebGPUGeometryCache {
+    private readonly device;
+    private readonly entries;
+    private active;
+    private readonly pinned;
+    private readonly objectKeys;
+    private readonly legacyKeys;
+    private objectKeySequence;
+    private readonly inactiveGraceFrames;
+    private readonly maxBytes;
+    private uploads;
+    private updatedBytes;
+    private evictions;
+    private frameId;
+    private resourceGeneration;
+    constructor(options: WebGPUGeometryCacheOptions);
+    retain(geometry: ICEGeometry): WebGPUGeometryEntry;
+    private createEntry;
+    pin(geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): WebGPUGeometryEntry;
+    unpin(geometry: ICEGeometry): void;
+    beginFrame(): void;
+    endFrame(): void;
+    clear(): void;
+    dispose(): void;
+    get totalBytes(): number;
+    get uploadCount(): number;
+    get updateBytes(): number;
+    get evictionCount(): number;
+    get generation(): number;
+    private enforceBudget;
+    private deleteEntry;
+    private applyPositionUpdate;
+    private canReuse;
+    private sameTopology;
+    private keyFor;
+}
+//# sourceMappingURL=WebGPUGeometryCache.d.ts.map