ice3 0.2.0 → 0.2.2

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

@@ -0,0 +1,42 @@
+import { type ICEBounds } from './ShadowFrustum.js';
+/** 光源方向（与主着色器的 diffuse 保持同一方向）。 */
+export { SHADOW_LIGHT_DIRECTION as LIGHT_DIRECTION } from './ShadowFrustum.js';
+export declare class WebGL2ShadowMap {
+    private readonly gl;
+    /** 最近一次着色器编译/链接失败的原因，供诊断读取。 */
+    lastError: string | null;
+    private framebuffer;
+    private depthTexture;
+    private program;
+    private matrixLocation;
+    private instancingLocation;
+    private matrixScratch;
+    private texelWorldValue;
+    constructor(gl: WebGL2RenderingContext);
+    /** 深度纹理，供主着色器采样。 */
+    get texture(): WebGLTexture | null;
+    get matrix(): Float32Array;
+    /** 一个深度纹素在世界空间的边长（米）。法线偏移按它换算，别用魔数。 */
+    get texelWorld(): number;
+    /**
+     * 按场景包围盒拟合视锥。每帧调用没有意义——场景内容不变时矩阵也不会变，
+     * 所以由调用方决定何时重算（包围盒变化或首帧）。
+     */
+    setBounds(bounds: ICEBounds | null): void;
+    /** 绑定阴影帧缓冲，返回是否成功。 */
+    begin(): boolean;
+    /**
+     * 非实例化绘制：矩阵换成 `lightViewProjection × world`，顶点位置直接当世界坐标用。
+     *
+     * 阴影通道原先只会画实例化批次，瓦片（渲染批次）与落单网格因此完全不投影。
+     * 补这两条路径靠的就是这个入口——和 `WebGL2SceneDepth` 同一套写法。
+     */
+    setMatrix(matrix: Float32Array): void;
+    setInstancing(enabled: boolean): void;
+    /** 解绑，恢复默认帧缓冲。 */
+    end(width: number, height: number): void;
+    dispose(): void;
+    private createResources;
+    private createProgram;
+}
+//# sourceMappingURL=WebGL2ShadowMap.d.ts.map

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

@@ -0,0 +1,31 @@
+/**
+ * Base-colour texture cache.
+ *
+ * Materials reference textures by URL; the renderer turns each URL into one
+ * `WebGLTexture` the first time a frame needs it and keeps it for later frames.
+ * Loading is asynchronous, so the first frames after a URL appears draw with the
+ * flat material colour and switch to the texture once the upload lands — a
+ * self-correcting behaviour that never blocks the frame loop.
+ */
+export type ICEImageLoader = (url: string) => Promise<ImageBitmap>;
+export type ICEWebGL2TextureStats = {
+    readonly loaded: number;
+    readonly pending: number;
+    readonly failed: number;
+};
+/** Default loader: fetch the image and decode it off the main thread. */
+export declare const fetchImageLoader: ICEImageLoader;
+export declare class WebGL2TextureCache {
+    private readonly gl;
+    private readonly load;
+    private readonly onUpload?;
+    private readonly entries;
+    private disposed;
+    constructor(gl: WebGL2RenderingContext, load?: ICEImageLoader, onUpload?: (() => void) | undefined);
+    /** Texture for `url`, or `null` while it is still loading (or after failure). */
+    texture(url: string): WebGLTexture | null;
+    stats(): ICEWebGL2TextureStats;
+    dispose(): void;
+    private upload;
+}
+//# sourceMappingURL=WebGL2TextureCache.d.ts.map

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

@@ -0,0 +1,16 @@
+/**
+ * Box-projected texture coordinates.
+ *
+ * Studio generates geometry procedurally, so meshes reach the renderer without a
+ * UV attribute. The projection is derived from the surface instead: each fragment
+ * is projected along the dominant axis of its normal, which is stable inside a
+ * face and needs no extra vertex channel.
+ *
+ * This mirrors `box_projected_uvs` in Studio's exporter, so a surface textured in
+ * the viewport and the same surface exported as glTF land on the same texels.
+ * Coordinates are in metres; tiling is a material concern.
+ */
+export type ICEUvScale = readonly [number, number];
+export declare const DEFAULT_UV_SCALE: ICEUvScale;
+export declare function boxProjectedUv(position: readonly [number, number, number], normal: readonly [number, number, number], scale?: ICEUvScale): [number, number];
+//# sourceMappingURL=WebGL2Uv.d.ts.map

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

@@ -3,6 +3,7 @@ export type ICEWebGPUDrawUniform = Readonly<{
     color: readonly [number, number, number, number];
     useVertexColor: boolean;
     useInstancing: boolean;
+    useLighting?: boolean;
     semanticHighlight?: number;
     useSemantic?: boolean;
     selectionBase: number;

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

@@ -1,5 +1,9 @@
-import { type ICEGeometry } from '../core/index.js';
+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;
@@ -21,15 +25,20 @@ export declare class WebGPUGeometryCache {
     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;
-    pin(geometry: ICEGeometry): WebGPUGeometryEntry;
+    private createEntry;
+    pin(geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): WebGPUGeometryEntry;
     unpin(geometry: ICEGeometry): void;
     beginFrame(): void;
     endFrame(): void;
@@ -37,9 +46,14 @@ export declare class WebGPUGeometryCache {
     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

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

@@ -1,5 +1,5 @@
 export declare const WEBGPU_UNIFORM_STRIDE = 256;
-export declare const WEBGPU_UNIFORM_BYTES = 128;
+export declare const WEBGPU_UNIFORM_BYTES = 144;
 export declare class WebGPURenderPipeline {
     readonly device: GPUDevice;
     readonly format: GPUTextureFormat;

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

@@ -80,6 +80,8 @@ export declare class WebGPURendererBackend 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;
     enableProfiling(enabled: boolean): void;

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

@@ -15,7 +15,7 @@ export { WebGPUBundleCache } from './WebGPUBundleCache.js';
 export { buildSelectionMask, WebGPUSelectionMaskBuffer, type ICESelectionMaskLayout, } from './WebGPUSelectionMask.js';
 export { collectWebGPUPickIds, WebGPUPicker, } from './WebGPUPicker.js';
 export { collectRenderables, selectionIdentity, type ICEGeometryRenderable, } from './Renderables.js';
-export { collectInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
+export { collectInstanceBatches, renderablesOutsideInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
 export { queueBatchGeneration } from './ICEWebGL2BatchGenerationUploader.js';
 export type { ICEFrameStageProfile, } from './RendererProfiler.js';
 export { RendererProfiler, } from './RendererProfiler.js';

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

@@ -1,4 +1,4 @@
-import type { ICEGeometry, ICEEngineError, ICEPerspectiveCamera, ICEScene } from '../core/index.js';
+import type { ICEGeometry, ICEGeometryBufferUpdate, ICEEngineError, ICEPerspectiveCamera, ICEScene } from '../core/index.js';
 export type ICEViewport = {
     readonly x: number;
     readonly y: number;
@@ -49,11 +49,19 @@ export interface ICERendererBackend {
         readonly onContextLost?: () => void;
         readonly onContextRestored?: () => void;
         readonly onError?: (error: ICEEngineError) => void;
+        /** A deferred GPU upload (for example a base-colour texture) just landed. */
+        readonly onUploadReady?: () => void;
+        /** Directional-light shadows. Off by default: it costs a full extra scene pass. */
+        readonly shadows?: boolean;
     }): void;
     resize(viewport: ICEViewport, dpr: number): void;
     setBackgroundColor?(color: string): void;
+    /** Clip plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0` are discarded; `null` disables. */
+    setClipPlane?(plane: readonly [number, number, number, number] | null): void;
     prepareBatchGeometry?(geometry: ICEGeometry): void;
     releaseBatchGeometry?(geometry: ICEGeometry): void;
+    prepareGeometry?(geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): void;
+    releaseGeometry?(geometry: ICEGeometry): void;
     pick?(frame: ICEFrame, point: ICEScreenPoint): Promise<string | undefined>;
     render(frame: ICEFrame): void;
     finish?(): Promise<void>;

package/dist/_types/runtime/ICE3.d.ts

@@ -72,6 +72,7 @@ export declare class ICE3 extends ICEEventDispatcher {
     private generatedOverlayCanvas;
     private scene;
     private camera;
+    private clipPlane;
     private viewport;
     private dpr;
     private frameId;
@@ -96,8 +97,15 @@ export declare class ICE3 extends ICEEventDispatcher {
     setScene(scene: ICEScene): this;
     setCamera(camera: ICEPerspectiveCamera): this;
     setBackgroundColor(color: string): this;
+    /**
+     * Section plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0`
+     * are discarded. `null` (or a zero plane) disables clipping.
+     */
+    setClipPlane(plane: readonly [number, number, number, number] | null): this;
     prepareRenderBatchGeometry(geometry: ICEGeometry): this;
     releaseRenderBatchGeometry(geometry: ICEGeometry): this;
+    prepareGeometry(geometry: ICEGeometry, update?: import('../core/index.js').ICEGeometryBufferUpdate): this;
+    releaseGeometry(geometry: ICEGeometry): this;
     addLayer(layer: ICE2DLayer): this;
     removeLayer(layer: ICE2DLayer): this;
     start(): this;

package/dist/_types/runtime/asset/ICEAssetSceneBuilder.d.ts

@@ -1,9 +1,15 @@
-import type { ICEPreparedAssetSnapshot, ICEPreparedStats } from '../../assets/index.js';
-import { ICEScene, type ICEGeometryBounds } from '../../core/index.js';
+import type { ICEPreparedAssetSnapshot, ICEPreparedStats, ICEPreviewGeometryPacket } from '../../assets/index.js';
+import { ICEIndexedGeometry, ICEScene, type ICEGeometryBounds, type ICEGeometryBufferUpdate } from '../../core/index.js';
 export interface ICEBuiltAsset {
     readonly scene: ICEScene;
     readonly bounds: ICEGeometryBounds;
     readonly stats: ICEPreparedStats;
 }
+export interface ICEBuiltPreviewPacket {
+    readonly scene: ICEScene;
+    readonly geometries: ReadonlyMap<string, ICEIndexedGeometry>;
+    readonly geometryUpdates: ReadonlyMap<string, ICEGeometryBufferUpdate>;
+}
 export declare function buildAssetScene(snapshot: ICEPreparedAssetSnapshot): ICEBuiltAsset;
+export declare function buildPreviewPacketScene(packet: ICEPreviewGeometryPacket, previousGeometries?: ReadonlyMap<string, ICEIndexedGeometry>): ICEBuiltPreviewPacket;
 //# sourceMappingURL=ICEAssetSceneBuilder.d.ts.map

package/dist/_types/runtime/asset/ICEPreviewPacketLoader.d.ts

@@ -0,0 +1,25 @@
+import { type ICEPreviewGeometryPacket } from '../../assets/index.js';
+import type { ICEGeometryBufferUpdate, ICEIndexedGeometry, ICEScene } from '../../core/index.js';
+export type ICEPreviewPacketFallbackReason = 'packet-unavailable' | 'packet-invalid' | 'packet-revision-mismatch';
+export type ICEPreviewPacketLoadResult = {
+    readonly kind: 'packet';
+    readonly packet: ICEPreviewGeometryPacket;
+} | {
+    readonly kind: 'fallback';
+    readonly reason: ICEPreviewPacketFallbackReason;
+};
+export interface ICEPreviewPacketLoaderOptions {
+    readonly fetch?: typeof fetch;
+    readonly pinGeometry?: (geometry: ICEIndexedGeometry, update?: ICEGeometryBufferUpdate) => void;
+}
+export declare class ICEPreviewPacketLoader {
+    private readonly fetcher;
+    private readonly pinGeometry;
+    private geometries;
+    private publishedScene;
+    constructor(options?: ICEPreviewPacketLoaderOptions | typeof fetch);
+    get scene(): ICEScene | null;
+    get currentGeometries(): ReadonlyMap<string, ICEIndexedGeometry>;
+    load(url: string, current?: ICEPreviewGeometryPacket): Promise<ICEPreviewPacketLoadResult>;
+}
+//# sourceMappingURL=ICEPreviewPacketLoader.d.ts.map

package/dist/_types/runtime/asset/ICETilesetLoader.d.ts

@@ -154,7 +154,6 @@ export declare class ICETilesetHandle extends ICEEventDispatcher {
     private enterCameraMotion;
     private promoteReadyVisibleTargets;
     private lodReadyVisibleCoverage;
-    private reconcileSelectionVisibility;
     private rejectReadyIfVisibleSetFailed;
     private updateBudgetWarning;
     private residentBudgetReached;

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

@@ -25,10 +25,11 @@ export { ICERenderBatch, type ICERenderBatchOptions, } from './asset/ICERenderBa
 export { ICEAssetLoader, type ICEAssetHandle, type ICEAssetLoaderOptions, type ICEAssetLoadOptions, } from './asset/ICEAssetLoader.js';
 export { ICETilesetHandle, ICETilesetLoader, type ICETilesetEvent, type ICETilesetLoaderOptions, type ICETilesetOpenOptions, type ICETilesetStats, type ICETilesetTileState, } from './asset/ICETilesetLoader.js';
 export { ICETilesetScheduler, type ICETilesetSchedulerOptions, type ICETilesetWorkSet, type ICETilesetWorkSetInput, } from './asset/ICETilesetScheduler.js';
+export { ICEPreviewPacketLoader, type ICEPreviewPacketFallbackReason, type ICEPreviewPacketLoadResult, type ICEPreviewPacketLoaderOptions, } from './asset/ICEPreviewPacketLoader.js';
 export { ICELodSelector, type ICELodSelection, type ICELodSelectionInput, } from './asset/ICELodSelector.js';
 export type { ICELodStats } from './asset/ICETilesetLoader.js';
 export { collectSceneItems, raycastSceneNode, type ICERay, type ICESceneItem, type ICESceneQuery, } from './query/ICESceneQuery.js';
-export type { ICEPreparedContract, ICEPreparedStats, } from '../assets/index.js';
+export type { ICEPreparedContract, ICEPreparedStats, ICEPreviewGeometryPacket, } from '../assets/index.js';
 export { ICEAdaptiveRenderBatchController, } from './batching/ICEAdaptiveRenderBatchController.js';
 export type { ICEAdaptiveBatchExecutionResult, ICEAdaptiveBatchRequest, ICEAdaptiveBatchRequestResult, ICERenderBatchingMode, ICERenderBatchingOptions, } from './batching/ICEAdaptiveRenderBatchController.js';
 export { ICERenderBatchPlanner } from './batching/ICERenderBatchPlanner.js';

package/dist/_types/runtime/input/ICEOrbitController.d.ts

@@ -7,6 +7,8 @@ export declare class ICEOrbitController {
     private yaw;
     private pitch;
     private distance;
+    private readonly minDistance;
+    private readonly maxDistance;
     private targetYaw;
     private targetPitch;
     private targetDistance;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { ICEBasicMaterial, ICEBoxGeometry, ICEIndexedGeometry, ICEEngineError, ICEAssetLoader, ICETilesetHandle, ICETilesetLoader, ICELabel, ICEMesh, ICENode, ICEOrbitController, ICEPerspectiveCamera, ICEScene, ICEScreenLayer, ICETypeRegistry, ICEWorldLayer, ICE3, deserializeScene, serializeScene, } from './_types/runtime/index.js';
-export type { ICEDeserializedScene, ICEDiagnostic, ICEDiagnosticSeverity, ICEEngineDiagnostics, ICE3Options, ICE3RendererPreference, ICE3RendererSelection, ICEInputEvent, ICEInputTarget, ICEKeyboardInputEvent, ICEProjectedPoint, ICEAssetHandle, ICEAssetLoaderOptions, ICEAssetLoadOptions, ICETilesetEvent, ICETilesetLoaderOptions, ICETilesetOpenOptions, ICETilesetStats, ICETilesetTileState, ICEPreparedContract, ICEPreparedStats, ICERenderBatchingOptions, ICESerializedScene, ICEGeometry, ICEGeometryBounds, ICEIndexedGeometryOptions, ICEMatrix4Tuple, ICEPickOutcome, } from './_types/runtime/index.js';
+export { ICEBasicMaterial, ICEBoxGeometry, ICEIndexedGeometry, ICEEngineError, ICEAssetLoader, ICETilesetHandle, ICETilesetLoader, ICELabel, ICEMesh, ICENode, ICEOrbitController, ICEPreviewPacketLoader, ICEPerspectiveCamera, ICEScene, ICEScreenLayer, ICETypeRegistry, ICEWorldLayer, ICE3, collectSceneItems, deserializeScene, serializeScene, } from './_types/runtime/index.js';
+export type { ICEDeserializedScene, ICEDiagnostic, ICEDiagnosticSeverity, ICEEngineDiagnostics, ICE3Options, ICE3RendererPreference, ICE3RendererSelection, ICEInputEvent, ICEInputTarget, ICEKeyboardInputEvent, ICEProjectedPoint, ICEAssetHandle, ICEAssetLoaderOptions, ICEAssetLoadOptions, ICETilesetEvent, ICETilesetLoaderOptions, ICETilesetOpenOptions, ICETilesetStats, ICETilesetTileState, ICEPreparedContract, ICEPreparedStats, ICERenderBatchingOptions, ICESerializedScene, ICEGeometry, ICEGeometryBounds, ICEIndexedGeometryOptions, ICEMatrix4Tuple, ICEPickOutcome, ICEPreviewPacketFallbackReason, ICEPreviewPacketLoadResult, ICEPreviewPacketLoaderOptions, ICEPreviewGeometryPacket, } from './_types/runtime/index.js';
 //# sourceMappingURL=index.d.ts.map