soonspacejs 2.15.19 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soonspacejs",
-  "version": "2.15.19",
+  "version": "2.16.0",
   "homepage": "https://www.xwbuilders.com/soonspacejs/",
   "description": "soonspacejs 2.x",
   "module": "./dist/index.esm.js",
@@ -26,10 +26,10 @@
   "author": "xunwei",
   "license": "UNLICENSED",
   "peerDependencies": {
-    "@types/three": ">=0.183.1",
+    "@types/three": ">=0.185.4",
     "camera-controls": ">=3.1.2",
-    "postprocessing": ">=6.39.0",
-    "three": ">=0.183.2",
+    "postprocessing": ">=6.39.4",
+    "three": ">=0.185.1",
     "three-mesh-bvh": ">=0.9.9"
   },
   "gitHead": "4a87dd85050651088e11c3da777c49fab3db7e5d"

package/types/Library/Link.d.ts

@@ -18,6 +18,6 @@ declare class Link extends BaseMesh {
     updateGeometry(params: Pick<LinkInfo, 'start' | 'end'>): void;
     computeVertex(): void;
     computeTextureRepeat(texture: Texture<HTMLImageElement>): void;
-    createTexture(imgUrl?: string): Texture<HTMLImageElement> | undefined;
+    createTexture(imgUrl?: string): Texture<HTMLImageElement, import('three').TextureEventMap> | undefined;
 }
 export { Link, LinkInfo, clearTextureCache as clearLinkTextureCache, };

package/types/Manager/PoiManage.d.ts

@@ -10,9 +10,9 @@ declare class PoiManage extends DefaultManage {
     textures: Map<string, Texture>;
     constructor(viewport: Viewport, cache: ObjectsCache);
     dispose(): void;
-    _createIcon(info: PoiInfo): Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, import('three').Material | import('three').Material[], import('three').Object3DEventMap> | Icon;
+    _createIcon(info: PoiInfo): Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, import('three').Material<import('three').MaterialEventMap> | import('three').Material<import('three').MaterialEventMap>[], import('three').Object3DEventMap> | Icon;
     _createIconMaterial({ url, type, }: PoiInfo): MeshBasicMaterial | SpriteMaterial | undefined;
-    _createText(info: PoiInfo): Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, import('three').Material | import('three').Material[], import('three').Object3DEventMap> | Icon;
+    _createText(info: PoiInfo): Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, import('three').Material<import('three').MaterialEventMap> | import('three').Material<import('three').MaterialEventMap>[], import('three').Object3DEventMap> | Icon;
     _createTextMaterial(info: PoiInfo): MeshBasicMaterial | SpriteMaterial;
     _createTextTexture(info: ClonePoiInfo): CanvasTexture<HTMLCanvasElement>;
     _createTextCanvas(text: string, info?: NameCanvasInfo): HTMLCanvasElement;

package/types/Shared/map.d.ts

@@ -7,5 +7,5 @@ interface GradientTextureOptions {
     stops?: number[];
     size?: number;
 }
-declare function gradientTexture(options?: GradientTextureOptions): Texture<HTMLCanvasElement> | null;
+declare function gradientTexture(options?: GradientTextureOptions): Texture<HTMLCanvasElement, import('three').TextureEventMap> | null;
 export { GradientTextureOptions, gradientTexture, };

package/types/Viewport/AutoBatchedMesh.d.ts

@@ -0,0 +1,19 @@
+import { BatchedMesh, Mesh } from 'three';
+export interface AutoBatchedCandidate<T> {
+    source: Mesh;
+    value: T;
+}
+export interface AutoBatchedMeshBatch<T> {
+    proxy: BatchedMesh;
+    values: T[];
+}
+interface CreateAutoBatchedMeshOptions {
+    minInstances: number;
+    maxInstancesPerBatch: number;
+}
+export interface AutoBatchedMeshResult<T> {
+    batches: AutoBatchedMeshBatch<T>[];
+    batchedValues: Set<T>;
+}
+export declare function createAutoBatchedMeshes<T>(candidates: AutoBatchedCandidate<T>[], options: CreateAutoBatchedMeshOptions): AutoBatchedMeshResult<T>;
+export {};

package/types/Viewport/AutoInstancingManager.d.ts

@@ -0,0 +1,108 @@
+import { Group as ThreeGroup, Mesh, Object3D, Raycaster, Intersection } from 'three';
+import { default as Viewport } from '.';
+export interface AutoInstancingOptions {
+    /**
+     * 同一批次至少包含多少个 Mesh 时才创建 InstancedMesh。
+     */
+    minInstances?: number;
+    /**
+     * 单个 InstancedMesh 批次允许包含的最大实例数。
+     * 限制批次规模可以降低动态更新和包围体重算的成本。
+     */
+    maxInstancesPerBatch?: number;
+    /**
+     * 连续多少帧发生局部变换后，将对象从静态批次提升为独立代理。
+     */
+    dynamicPromotionFrames?: number;
+    /**
+     * 透明双面 BatchedMesh 是否使用单通道绘制。
+     * 仅在代理渲染期间生效，不修改源材质的持久状态。
+     */
+    transparentSinglePass?: boolean;
+    /**
+     * 是否跳过 image 为空但已标记更新的纹理上传。
+     * 仅在代理渲染期间临时复位纹理版本，避免 WebGLRenderer 每帧重复重试和告警。
+     */
+    skipEmptyTextureUploads?: boolean;
+}
+export interface AutoInstancingStats {
+    active: boolean;
+    sourceObjects: number;
+    sourceRenderables: number;
+    instancedBatches: number;
+    instancedObjects: number;
+    mergedBatches: number;
+    mergedObjects: number;
+    batchedBatches: number;
+    batchedObjects: number;
+    passthroughObjects: number;
+    unsupportedObjects: number;
+    multiDrawSupported: boolean;
+}
+declare class AutoInstancingManager {
+    readonly viewport: Viewport;
+    readonly proxyRoot: ThreeGroup<import('three').Object3DEventMap>;
+    private roots;
+    private pendingRoots;
+    private sourceToProxy;
+    private sourceBindings;
+    private proxyBindings;
+    private dynamicSources;
+    private excludedRoots;
+    private excludedSubtrees;
+    private outlineIndependentSources;
+    private outlineSources;
+    private outlineSourceSet;
+    private safeBeforeRenderListeners;
+    private activeEmptyTextureVersions;
+    private autoMode;
+    private autoModeOptions;
+    private isRendering;
+    constructor(viewport: Viewport);
+    setEnabled(enabled: boolean, options?: AutoInstancingOptions): AutoInstancingStats[];
+    registerRoot(root: Object3D, options?: AutoInstancingOptions): AutoInstancingStats | null;
+    unregisterRoot(root: Object3D, excludeFromAutoMode?: boolean): void;
+    getStats(root?: Object3D): AutoInstancingStats | AutoInstancingStats[] | null;
+    requestSync(): void;
+    markBeforeRenderListenerSafe(listener: () => void): void;
+    unmarkBeforeRenderListenerSafe(listener: () => void): void;
+    hasUnsafeBeforeRenderListeners(numListeners: number): boolean;
+    setOutlineSelection(sources: Mesh[]): Mesh[];
+    getOutlineSelection(): Mesh[];
+    withRenderProxies<T>(render: () => T): T;
+    beginRender(forceSourceSync?: boolean): void;
+    endRender(): void;
+    getRaycastObjects(objects: Object3D | Object3D[]): Object3D | Object3D[];
+    resolveIntersection<TObject extends Object3D = Object3D>(intersection: Intersection<TObject>, raycaster?: Raycaster, sourceIntersections?: Map<Object3D<import('three').Object3DEventMap>, Intersection<Object3D<import('three').Object3DEventMap>>[]>): Intersection<TObject> | null;
+    resolveIntersections<TObject extends Object3D = Object3D>(intersections: Intersection<TObject>[], raycaster?: Raycaster): Intersection<TObject>[];
+    clear(): void;
+    dispose(): void;
+    private _createBinding;
+    private _syncRoot;
+    private _updateProxyBindings;
+    private _syncInstancedMeshBounds;
+    private _isSourceWorldVisible;
+    private _syncOwnedBatchMaterials;
+    private _ensureOutlineProxy;
+    private _removeOutlineProxy;
+    private _promoteDynamicDescendants;
+    private _isTrackedDescendant;
+    private _requiresPartialRendering;
+    private _hideManagedSources;
+    private _restoreRoot;
+    private _removeBinding;
+    private _rebuildDirtyRoots;
+    private _supportsMultiDraw;
+    private _applyEmptyTextureGuards;
+    private _restoreEmptyTextureVersions;
+    private _normalizeOptions;
+    private _registerSceneRoots;
+    private _removeInvalidRoots;
+    private _partitionNestedRoots;
+    private _handleObjectAdded;
+    private _handleObjectRemoved;
+    private _handleSourceChanged;
+    private _handleMaterialChanged;
+    private _retryPendingRoots;
+}
+export default AutoInstancingManager;

package/types/Viewport/AutoMergedMesh.d.ts

@@ -0,0 +1,21 @@
+import { Mesh } from 'three';
+export interface AutoMergedCandidate<T> {
+    source: Mesh;
+    value: T;
+}
+export interface AutoMergedMeshBatch<T> {
+    proxy: Mesh;
+    values: T[];
+    faceEnds: number[];
+}
+interface CreateAutoMergedMeshOptions {
+    minInstances: number;
+    maxInstancesPerBatch: number;
+    maxRootBytes: number;
+}
+export interface AutoMergedMeshResult<T> {
+    batches: AutoMergedMeshBatch<T>[];
+    mergedValues: Set<T>;
+}
+export declare function createAutoMergedMeshes<T>(candidates: AutoMergedCandidate<T>[], options: CreateAutoMergedMeshOptions): AutoMergedMeshResult<T>;
+export {};

package/types/Viewport/RendererManager.d.ts

@@ -2,11 +2,6 @@ import { WebGLRenderer } from 'three';
 import { CSS2DRenderer, CSS3DRenderer } from '../Renderer';
 import { InternalOptions } from '../Interface';
 import { default as Viewport } from '.';
-declare module 'three' {
-    interface WebGLRenderer {
-        autoInstancing: boolean;
-    }
-}
 declare class RendererManager {
     readonly viewport: Viewport;
     internalOptions: InternalOptions;

package/types/Viewport/Scener.d.ts

@@ -38,7 +38,7 @@ declare class Scener {
     unHighlightShow(objects?: Object3D | Object3D[]): Promise<void | void[]>;
     emissiveShow(object: Object3D | Object3D[], options?: EmissiveSelectOptions): Promise<void | void[]>;
     unEmissiveShow(objects?: Object3D | Object3D[]): Promise<void | void[]>;
-    updateMaterial(material: Material, materialOption: UpdateMaterialOption): Material;
+    updateMaterial(material: Material, materialOption: UpdateMaterialOption): Material<import('three').MaterialEventMap>;
     private _handleEmissiveShow;
     private _handleUnEmissive;
     _triggerObjectAdded(object: Object3D): void;

package/types/Viewport/index.d.ts

@@ -16,6 +16,7 @@ import { default as EventHandler } from './EventHandler';
 import { default as Info } from './Info';
 import { ViewHelper } from './ViewHelper';
 import { ObjectsCache } from '../Cache';
+import { default as AutoInstancingManager, AutoInstancingOptions, AutoInstancingStats } from './AutoInstancingManager';
 export declare const innerRenderState: {
     needsUpdate: boolean;
 };
@@ -35,6 +36,7 @@ declare class Viewport {
     renderer: WebGLRenderer;
     rendererCSS2D: CSS2DRenderer;
     rendererCSS3D: CSS3DRenderer;
+    autoInstancingManager: AutoInstancingManager;
     pmremGenerator: PMREMGenerator;
     info: Info;
     stats: Stats;
@@ -57,11 +59,13 @@ declare class Viewport {
      */
     postRender: Map<string | number, () => void>;
     private _loop;
+    private outlineSelection;
     resizeObserver: ResizeObserver;
     constructor(options: ViewportOptions, signals: SignalsState, cache: ObjectsCache);
     _initInfo(): void;
     _initStats(): void;
-    setAutoInstancing(enabled: boolean): void;
+    setAutoInstancing(enabled: boolean, root?: Object3D, options?: AutoInstancingOptions): void;
+    getAutoInstancingStats(root?: Object3D): AutoInstancingStats | AutoInstancingStats[] | null;
     /**
      ***************************** post-processing ***************************
      */
@@ -86,7 +90,7 @@ declare class Viewport {
     /**
      ***************************** environment ***************************
      */
-    setEnvironment(options?: EnvironmentOptions): Promise<Texture<unknown>>;
+    setEnvironment(options?: EnvironmentOptions): Promise<Texture<unknown, import('three').TextureEventMap>>;
     /**
      ***************************** modelAnimation ***************************
      */
@@ -101,6 +105,7 @@ declare class Viewport {
      * @param count
      */
     triggerRender(count?: number): void;
+    private _triggerRender;
     /**
      * 暂停渲染
      * @param pause
@@ -110,6 +115,7 @@ declare class Viewport {
      * effect passes
      */
     _passesObserver(): void;
+    private _syncAutoInstancingOutlineSelection;
     /**
      * 每帧都会被执行
      * @param time
@@ -123,7 +129,7 @@ declare class Viewport {
     };
     getPositionByOffset(offset: OffsetPoint, z?: number, scalar?: number): Vector3;
     getIntersects(event: MouseEvent | TouchEvent | OffsetPoint, objects?: Object3D<import('three').Object3DEventMap>[], options?: IntersectsOptions): Intersection<Object3D<import('three').Object3DEventMap>>[];
-    rayClash(startPoint?: Vector3, dir?: Vector3, objects?: Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, Material | Material[], import('three').Object3DEventMap>[]): Intersection<Object3D<import('three').Object3DEventMap>>[];
+    rayClash(startPoint?: Vector3, dir?: Vector3, objects?: Mesh<import('three').BufferGeometry<import('three').NormalBufferAttributes, import('three').BufferGeometryEventMap>, Material<import('three').MaterialEventMap> | Material<import('three').MaterialEventMap>[], import('three').Object3DEventMap>[]): Intersection<Object3D<import('three').Object3DEventMap>>[];
     clearSignals(): void;
     /**
      * 隔离显示对象 - 使用 Layers API 仅显示指定对象，隐藏场景中其他对象

package/types/index.d.ts

@@ -6,6 +6,7 @@ import { IClipAnimation, BaseObjectInfo, ViewportOptions, SceneGlobalEvents, Plu
 import { BaseObject3D, Model, ModelInfo, Poi, PoiInfo, PoiNode, PoiNodeInfo, Topology, TopologyInfo, Group, GroupInfo, Canvas3D, Canvas3DInfo, PluginObject, PluginObjectInfo, DecalInfo, Decal, DecalGeometryInfo, PoiMeshInfo, PolygonPoiMeshInfo } from './Library';
 import { ObjectsCache } from './Cache';
 import { default as Viewport } from './Viewport';
+import { AutoInstancingOptions, AutoInstancingStats } from './Viewport/AutoInstancingManager';
 import { default as Controls } from './Controls';
 import { default as Manager } from './Manager';
 import { BoxSpace, FindObjectsNearPosition, FindNearbyObjects, SetTextureOptions } from './tools';
@@ -33,6 +34,7 @@ export interface SoonSpaceConstructor {
 export * from './Library';
 export * from './Interface';
 export * from './tools';
+export type { AutoInstancingOptions, AutoInstancingStats, } from './Viewport/AutoInstancingManager';
 export * from './Constants';
 export * from '@three3d/animation';
 /**
@@ -145,7 +147,8 @@ declare class SoonSpace {
     /******* Viewport methods */
     /******/
     /******/
-    setAutoInstancing(enabled: boolean): void;
+    setAutoInstancing(enabled: boolean, root?: Object3D, options?: AutoInstancingOptions): void;
+    getAutoInstancingStats(root?: Object3D): AutoInstancingStats | AutoInstancingStats[] | null;
     /**
      * 设置泛光
      * @param bloom
@@ -197,7 +200,7 @@ declare class SoonSpace {
      * 设置场景环境
      * @returns
      */
-    setEnvironment(options?: EnvironmentOptions): Promise<THREE.Texture<unknown>>;
+    setEnvironment(options?: EnvironmentOptions): Promise<THREE.Texture<unknown, THREE.TextureEventMap>>;
     /**
      * 播放模型动画
      * @param model
@@ -881,7 +884,7 @@ declare class SoonSpace {
      * @param options - 选项
      * @returns 返回设置的纹理对象
      */
-    setTexture(mesh: Mesh, image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | null, options?: SetTextureOptions): THREE.Texture<unknown> | null;
+    setTexture(mesh: Mesh, image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | null, options?: SetTextureOptions): THREE.Texture<unknown, THREE.TextureEventMap> | null;
     /******/
     /******/
     /******* Canvas3D methods */

package/types/tools/units.d.ts

@@ -24,7 +24,7 @@ export declare function createUVMatrix(box: Box2): Matrix3;
  * 判断包围合 与 对象的包围盒是否相交
  */
 export declare function boundingIsIntersected(target: Box3 | Sphere, obj: Object3D): boolean;
-export declare function createTexture(image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, cache?: boolean, textureCache?: Map<string, Texture>): Texture<unknown>;
+export declare function createTexture(image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, cache?: boolean, textureCache?: Map<string, Texture>): Texture<unknown, import('three').TextureEventMap>;
 export interface SetTextureOptions {
     /**
      * 是否使用缓存中的材质
@@ -45,4 +45,4 @@ export interface SetTextureOptions {
  * @param textureCache
  * @returns
  */
-export declare function setTexture(material: MeshStandardMaterial, image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, cache?: boolean, textureCache?: Map<string, Texture>): Texture<unknown>;
+export declare function setTexture(material: MeshStandardMaterial, image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, cache?: boolean, textureCache?: Map<string, Texture>): Texture<unknown, import('three').TextureEventMap>;