vis-core 0.33.14 → 0.33.16

package/README.md

@@ -1 +1,25 @@
 # vis-core
+
+## 提前初始化 GPU
+
+`SceneManager` 首次读取 URL 模板时，会先发出网络请求，再自动预热实际渲染器。现有 `load(url)`、`loadMapRegion(url, ...)` 和 `requestMapRegion(url, ...)` 调用无需修改。内存文档不会自动预热。
+
+宿主已经确认即将展示场景时，也可以更早调用：
+
+```ts
+const manager = new SceneManager({ container });
+void manager.prewarmRuntime().catch(error => {
+  // 预热是可选优化；正式加载仍可重新尝试初始化。
+  console.debug('GPU 预热未完成', error);
+});
+
+// 稍后需要展示时，复用预热中的或已就绪的上下文。
+await manager.load(templateUrl);
+
+// 页面卸载时，也会释放尚未被场景接管的预热上下文。
+manager.dispose();
+```
+
+每个 manager 独立持有预热状态，重复调用共用初始化 Promise。预热只初始化渲染器，不读取场景、展开材质、挂载 canvas 或启动渲染循环；首次场景按最终配置接管同一个渲染器。模板或钩子修改了深度、后端等渲染器配置时，不兼容的预热实例会释放，按最终配置重新创建。WebGPU 降级及深度精度策略与普通加载相同。
+
+预热失败或未使用的设备丢失后可以重试。预热不能消除 GPU 冷启动成本，也不会把同步 WebGL 初始化移入后台线程；收益来自更早启动，以及与模板下载等等待重叠。测量时应分别记录预热耗时和后续加载耗时。

package/dist/index.d.ts

@@ -50,8 +50,8 @@ import { Raycaster } from 'three/webgpu';
 import { RectAreaLight as RectAreaLight_2 } from 'three';
 import { RenderPipeline } from 'three/webgpu';
 import { RenderTarget } from 'three/webgpu';
-import { Scene } from 'three';
-import { Scene as Scene_2 } from 'three/webgpu';
+import { Scene } from 'three/webgpu';
+import { Scene as Scene_2 } from 'three';
 import { ShaderMaterial } from 'three';
 import { ShaderMaterialJSON } from 'three';
 import { SpotLight as SpotLight_2 } from 'three';
@@ -343,6 +343,8 @@ declare type Base_2 = Base_3;
 
 declare class Base_3 extends Camera {
     static VisName: string;
+    /** Internal: Share final renderer configuration with SceneManager prewarming. */
+    static prewarmRenderer(options: BaseOptions): ReturnType<typeof Pencil.prewarmRenderer>;
     runtimePolicy: {
         observeParentScale: boolean;
         applyDisabledMouseButtons: boolean;
@@ -358,8 +360,8 @@ declare class Base_3 extends Camera {
     roomEnvMap?: _THREE.Texture;
     private roomEnvLease?;
     visName: string;
-    private detectRes?;
     private ownsPencil;
+    private rendererWarmup?;
     private renderingSuspensions;
     /** Internal: 在运行时创建前也可暂停，保证整个初始化过程不提交中间帧。 */
     suspendRendering(): () => void;
@@ -382,7 +384,6 @@ declare class Base_3 extends Camera {
     private getQueryOverrides;
     private getEffectiveLogarithmicDepthBuffer;
     private getEffectiveTier;
-    private isExtClipControlAvailable;
     private resolveRendererDepthBufferOptions;
     private showDetectRes;
     setOptions(options: Record<string, any>): void;
@@ -611,6 +612,8 @@ declare interface BaseOptions {
     css2DContainer?: HTMLElement;
     controlsContainer?: HTMLElement;
     pencil?: any;
+    /** Internal: Owned by SceneManager until the first Pencil adopts it. */
+    rendererWarmup?: ReturnType<typeof Pencil.prewarmRenderer>;
     pencilConfig?: Record<string, any>;
     disableInitShow?: boolean;
     logarithmicDepthBuffer?: boolean;
@@ -1741,7 +1744,7 @@ declare class CameraPages extends OrigonPages<PerspectiveCamera_2> {
     private _cachedMatrixWorldInverse;
     private externallySyncedCameras;
     private ownedCameras;
-    constructor(options: Options_3);
+    constructor(options: Options_4);
     addPerspectiveCamera(cameraParams?: {
         fov: number;
         aspect?: number;
@@ -1992,11 +1995,11 @@ declare const ColorSpace: {
 /** WebGPU render pipeline. Compatibility controls retain the saved scene schema. */
 declare class Composer {
     renderer: WebGPURenderer;
-    scene: Scene_2;
+    scene: Scene;
     camera: Camera_2;
     finalComposer: RenderPipeline;
     renderPass: {
-        scene: Scene_2;
+        scene: Scene;
         camera: Camera_2;
     };
     bloomComposer?: RenderTarget;
@@ -2027,7 +2030,7 @@ declare class Composer {
     bloomSelection: Set<BaseObject< Object3D<Object3DEventMap>>>;
     bloomLayer: Layers;
     active: boolean;
-    options: Options_2;
+    options: Options_3;
     private readonly target;
     private overlayTarget?;
     private outputPipeline?;
@@ -2049,13 +2052,15 @@ declare class Composer {
     private readonly gtaoViews;
     private readonly onCameraChange;
     private readonly onSceneChange;
-    constructor(options: Options_2);
+    constructor(options: Options_3);
     private createDepthTexture;
+    /** Reconcile async backend selection before the first draw; preserve target identities. */
+    synchronizeRendererCapabilities(multisampling?: number): void;
     private resizeTargets;
     private rebuild;
     private activateView;
     changeCamera(camera: Camera_2): void;
-    changeScene(scene: Scene_2): void;
+    changeScene(scene: Scene): void;
     addOutputPass(): void;
     setPremultiplieAlpha(value: boolean): void;
     addSSAOPass(params: SSAOParams): void;
@@ -2217,7 +2222,7 @@ declare class CSSRendererController {
     setSize(width: number, height: number): void;
     setViewport(viewport: CSSRendererViewport): void;
     private applyViewport;
-    render(scene: Scene, camera: PerspectiveCamera_2): void;
+    render(scene: Scene_2, camera: PerspectiveCamera_2): void;
     dispose(): void;
 }
 
@@ -2744,7 +2749,7 @@ declare class Lead_2 extends Pick_2 {
     sceneResources: SceneResources_2;
     get objectsPromise(): MapIterator<Promise<void>>;
     constructor(pencil: Pencil, ops: {
-        scene: Scene;
+        scene: Scene_2;
         sceneResources: SceneResources_2;
     });
     /**
@@ -2807,7 +2812,7 @@ declare class LeadPages extends OrigonPages<Lead_2> {
     options: Options_11;
     get lead(): Lead_2;
     constructor(options: Options_11);
-    addLead(scene: Scene, sceneResources: SceneResources_2, index?: number): Lead_2;
+    addLead(scene: Scene_2, sceneResources: SceneResources_2, index?: number): Lead_2;
     removePage(index: number): void;
     setPageActive(index: number): void;
     setSize(width: number, height: number): void;
@@ -2892,7 +2897,7 @@ declare class Loader {
     assets: Map<string, Texture | Object3D | any>;
     event: EventEmitter;
     options: Options_9;
-    scene: Scene;
+    scene: Scene_2;
     private disposed;
     readonly resources: ResourceRegistry;
     private assetLeases;
@@ -2948,7 +2953,7 @@ declare class LoaderPages extends OrigonPages<Loader> {
     options: Options_10;
     get loader(): Loader;
     constructor(options: Options_10);
-    addLoader(scene: Scene, index?: number): Loader;
+    addLoader(scene: Scene_2, index?: number): Loader;
     removePage(index: number): void;
 }
 
@@ -3841,6 +3846,8 @@ declare class OptionMaterialDependencies {
 
 declare interface Options {
     container: HTMLElement;
+    /** Optional single-use renderer prepared by Pencil.prewarmRenderer(). */
+    rendererWarmup?: RendererWarmup;
     helper?: boolean;
     controls?: Partial<ControlsParams>;
     renderer?: Partial<RendererParams>;
@@ -3968,11 +3975,9 @@ declare interface Options_19 {
 }
 
 declare interface Options_2 {
-    sceneController: ScenePages;
-    cameraController: CameraPages;
-    rendererController: RendererController;
-    composerParams: ComposerParams;
-    resources?: ResourceRegistry;
+    width: number;
+    height: number;
+    rendererParams: RendererParams;
 }
 
 declare interface Options_20 {
@@ -4022,14 +4027,16 @@ declare interface Options_23 {
 }
 
 declare interface Options_3 {
-    width: number;
-    height: number;
+    sceneController: ScenePages;
+    cameraController: CameraPages;
+    rendererController: RendererController;
+    composerParams: ComposerParams;
+    resources?: ResourceRegistry;
 }
 
 declare interface Options_4 {
     width: number;
     height: number;
-    rendererParams: RendererParams;
 }
 
 declare interface Options_5 {
@@ -4045,16 +4052,16 @@ declare interface Options_6 {
 
 declare interface Options_7 {
     renderer: WebGPURenderer;
-    scene: Scene_2;
+    scene: Scene;
     /** Authored page identity when scene is a shared overlay. */
-    viewScene?: Scene_2;
+    viewScene?: Scene;
     camera: Camera_2;
 }
 
 declare interface Options_8 {
     sceneController: ScenePages;
     /** Editor overlays live outside the authored scene and its render passes. */
-    helperScene?: Scene_2;
+    helperScene?: Scene;
     cameraController: CameraPages;
     container: HTMLElement;
     resources?: ResourceRegistry;
@@ -4064,7 +4071,7 @@ declare interface Options_9 {
     prefix?: string;
     simpleTexture4deleted?: boolean;
     anisotropy: number;
-    scene: Scene | null;
+    scene: Scene_2 | null;
     resources?: ResourceRegistry;
 }
 
@@ -4082,7 +4089,9 @@ declare class OrigonPages<T = any> {
 }
 
 /** Pack an export copy only; preserve the editor's independent scene snapshots. */
-export declare function packSceneDocumentResources<T extends VisSceneDocument>(document: T): T;
+export declare function packSceneDocumentResources<T extends VisSceneDocument>(document: T, options?: {
+    encodePixels?: boolean;
+}): T;
 
 /** Page identities are independent of Three's 32 rendering layers. */
 declare class Pages {
@@ -4147,7 +4156,7 @@ export declare function patchSceneViewportDocument(document: VisSceneDocument, s
 declare class Pencil {
     readonly resources: ResourceRegistry;
     readonly ready: Promise<void>;
-    options: Omit<DeepRequiredOptions, 'controls' | 'loader' | 'css2DRendererParams' | 'css3DRendererParams'> & Pick<Options, 'controls' | 'loader'> & {
+    options: Omit<DeepRequiredOptions, 'controls' | 'loader' | 'css2DRendererParams' | 'css3DRendererParams' | 'rendererWarmup'> & Pick<Options, 'controls' | 'loader'> & {
         css2DRendererParams: CSSRendererParams;
         css3DRendererParams: CSSRendererParams;
     };
@@ -4161,7 +4170,7 @@ declare class Pencil {
     helperController?: HelperController;
     private _helperScene?;
     /** Drawn only in the editor, after the authored scene's postprocessing. */
-    get helperScene(): Scene_2< Object3DEventMap>;
+    get helperScene(): Scene< Object3DEventMap>;
     private sceneCapture?;
     loaderController: LoaderPages;
     leadController: LeadPages;
@@ -4182,7 +4191,7 @@ declare class Pencil {
     get cameraPositon(): Vector3_2;
     get cameraTarget(): Vector3_2;
     get camera(): PerspectiveCamera;
-    get scene(): Scene_2< Object3DEventMap>;
+    get scene(): Scene< Object3DEventMap>;
     get loader(): Loader;
     get lead(): Lead_2;
     get sceneResources(): SceneResources_2;
@@ -4195,6 +4204,7 @@ declare class Pencil {
         controls: boolean;
         renderer: {
             forceWebGL: boolean;
+            autoDepthBuffer: boolean;
             antialias: boolean;
             devicePixelRatio: number;
             powerPreference: string;
@@ -4262,6 +4272,9 @@ declare class Pencil {
         attributesWorkerMaxWorkers: number;
     };
     private TweenRaf;
+    private rendererWarmup?;
+    /** Start only the GPU environment; the eventual Pencil takes ownership. */
+    static prewarmRenderer(renderer?: Partial<RendererParams>): RendererWarmup;
     private tweenUpdateRaf;
     private cancelTweenRaf;
     constructor(options: Options);
@@ -4678,7 +4691,12 @@ export declare function remapProjectMaterialIds<T extends VisSceneDocument>(docu
  * 复制一组场景并为它们分配新 ID，同时保持文档内部的场景跳转关系。
  * 用于把完整模板追加到另一个场景文档中。
  */
-export declare function remapSceneDocumentIds(document: VisSceneDocument, createSceneId: (scene: SceneViewportDocument, index: number) => string): RemappedSceneDocument;
+export declare function remapSceneDocumentIds(document: VisSceneDocument, createSceneId: (scene: SceneViewportDocument, index: number) => string, options?: {
+    /** Leave authored definitions in the library until the selected scene loads. */
+    materialize?: boolean;
+    /** Resolve cross-project material collisions in the same ownership pass. */
+    occupiedMaterialIds?: Iterable<string>;
+}): RemappedSceneDocument;
 
 export declare const remapSceneMaterialReferencesCopy: <T>(scene: T, previous: string, next: string) => T;
 
@@ -4706,13 +4724,14 @@ declare class RendererController {
     private disposed;
     private hasRenderableSize;
     private readonly pointSprites;
-    options: Options_4;
+    options: Options_2;
     private displayScaleObserver?;
-    constructor(options: Options_4);
+    private releaseRenderPipelines?;
+    constructor(options: Options_2);
     observeDisplayScale(container: HTMLElement): void;
     setSize(width: number, height: number): void;
     setPixelRatio(ratio: number): void;
-    render(scene: Scene_2, camera: Camera_2): void;
+    render(scene: Scene, camera: Camera_2): void;
     setViewport(op: {
         x: number;
         y: number;
@@ -4736,10 +4755,26 @@ declare interface RendererParams {
     stencil: boolean;
     depth: boolean;
     reversedDepthBuffer: boolean;
+    /** Prefer reversed depth on the selected backend; retain logarithmic depth on GL without EXT_clip_control. */
+    autoDepthBuffer?: boolean;
     /** Use the WebGL 2 backend of WebGPURenderer, primarily for compatibility testing. */
     forceWebGL?: boolean;
 }
 
+/** A single-use, privately owned renderer. No scene, loader, DOM attachment or render loop. */
+declare class RendererWarmup {
+    readonly ready: Promise<void>;
+    private controller?;
+    private readonly parameters;
+    private cancelled;
+    private detachDeviceListener?;
+    get available(): boolean;
+    constructor(parameters: RendererParams);
+    /** Transfer ownership only when the final scene's renderer configuration matches. */
+    take(parameters: RendererParams, width: number, height: number): RendererController | undefined;
+    dispose(): void;
+}
+
 export declare function replaceMaterialAssetDocument(document: VisSceneDocument, asset: MaterialAsset): VisSceneDocument;
 
 export declare const RESOURCE_SOURCE = "_resourceSource";
@@ -4872,6 +4907,8 @@ declare class ResourceScope {
 }
 
 declare interface RestoreBaseObjectOptions {
+    /** Image loading boundaries, before native materials and scene objects are restored. */
+    onResourceLoad?: (phase: 'start' | 'done') => void | Promise<void>;
     /** Transfer an exclusively owned snapshot between packages; restoration may mutate it. */
     consumeInput?: boolean;
     /** The caller must validate equality with the serialized resource definitions. */
@@ -5009,6 +5046,8 @@ export declare class SceneManager extends Event_2 {
     private isSwitching;
     private isRegionSwitching;
     private pencil?;
+    private rendererWarmup?;
+    private disposed;
     private safeAreaInsets?;
     private generation;
     private mapRequests;
@@ -5040,6 +5079,13 @@ export declare class SceneManager extends Event_2 {
     setSceneCachePolicy(cacheScenes: boolean, maxCachedScenes?: number | undefined): void;
     private reportSceneRetirementErrors;
     constructor(options: SceneManagerInitOptions);
+    /**
+     * Initialize the eventual renderer without downloading/expanding a scene or drawing.
+     * Call after starting template I/O to overlap network work with GPU startup.
+     * Repeated calls share one promise. A scene with different renderer options
+     * uses its own compatible renderer; failed warmups may be retried.
+     */
+    prewarmRuntime(): Promise<void>;
     private prepareScene;
     /** Publish one identity remap without exporting runtimes or copying other pages/resources. */
     remapCommittedIdentity(sceneId: string, previous: string, next: string, objectIdentity: boolean): boolean;
@@ -5103,7 +5149,12 @@ export declare class SceneManager extends Event_2 {
     commitSceneStructure(prepared: PreparedSceneStructure): void;
     /** Commit scalar material history without accepting or copying caller object graphs. */
     patchMaterialDefinitions(assets: MaterialAsset[], scenes: Pick<SceneViewportDocument, 'id'>[], scope?: MaterialDefinitionScope): void;
-    load(documentOrUrl: VisSceneDocument | VisSceneManifest | string, hooks?: Record<string, any>): Promise<Base_3>;
+    load(documentOrUrl: VisSceneDocument | VisSceneManifest | string, hooks?: Record<string, any>, options?: {
+        /** Transfer a detached document to the manager; the caller must not mutate it afterwards. */
+        consumeInput?: boolean;
+        /** Restore a saved active scene without changing the project's entry scene. */
+        sceneId?: string;
+    }): Promise<Base_3>;
     /**
      * 创建一个没有快照输入的运行时页面，并在可选构建步骤完成后将其导出为
      * 标准单场景文档。主要供编辑器新建和旧模板迁移使用。
@@ -5239,14 +5290,14 @@ export declare interface SceneObjectPropertyPatch {
     unset?: readonly string[];
 }
 
-declare class ScenePages extends OrigonPages<Scene> {
-    get scene(): Scene< Object3DEventMap>;
-    addScene(sceneParams?: SceneParams, index?: number): Scene< Object3DEventMap>;
+declare class ScenePages extends OrigonPages<Scene_2> {
+    get scene(): Scene_2< Object3DEventMap>;
+    addScene(sceneParams?: SceneParams, index?: number): Scene_2< Object3DEventMap>;
     setPageActive(index: number): void;
 }
 
 declare interface SceneParams {
-    background: Scene['background'];
+    background: Scene_2['background'];
 }
 
 declare type ScenePropertyField = typeof scenePropertyFields[number];
@@ -5398,18 +5449,22 @@ export declare interface SceneStructurePatch {
         set?: Partial<Record<SceneStructureGraphKey, any>>;
         unset?: SceneStructureGraphKey[];
     };
+    /** Optional order lists every final row identity, including unchanged rows. */
     resources?: Partial<Record<SceneStructureResource, {
         upsert?: Record<string, any>[];
         remove?: string[];
+        order?: string[];
         unset?: true;
     }>>;
     assets?: {
         upsert?: MaterialAsset[];
         remove?: string[];
+        order?: string[];
     };
     prefabs?: {
         upsert?: PrefabAsset[];
         remove?: string[];
+        order?: string[];
     };
 }
 
@@ -5746,7 +5801,7 @@ declare class TransformControlsController {
     event: EventEmitter;
     constructor(options: Options_7);
     setViewport(viewport: Viewport): void;
-    bindActiveView(camera: Camera_2 | undefined, scene: Scene_2 | undefined, viewScene?: Scene_2< Object3DEventMap> | undefined): void;
+    bindActiveView(camera: Camera_2 | undefined, scene: Scene | undefined, viewScene?: Scene< Object3DEventMap> | undefined): void;
     private releaseRaycastCamera;
     private getBoundingClientRect;
     addEvent(): void;
@@ -5811,7 +5866,7 @@ declare class UseMaterial extends PointerEvent_2 {
 
 declare type ValuesOf<T extends readonly any[]> = T[number];
 
-export declare const VERSION = "0.33.14";
+export declare const VERSION = "0.33.16";
 
 declare interface Viewport {
     left: number;