isard 1.16.0 → 2.1.0

package/dist/map.js

@@ -9,7 +9,7 @@ import { SEA } from "./basemap/basemaps.js";
 import { pmtilesLayer } from "./basemap/pmtileslayer.js";
 import { VectorTiles } from "./basemap/vectortiles.js";
 import { defaultWorkerUrl } from "./basemap/workerpool.js";
-import { destroyedEngine, engineUrl, gridUrl, loadEngine, tessUrl } from "./engine-loader.js";
+import { destroyedEngine, engineUrl, gridUrl, loadEngine, rendererKind, tessUrl, } from "./engine-loader.js";
 import { IGN_PRESETS } from "./geoplateforme.js";
 import { CustomLayer } from "./layers/custom.js";
 import { ExtrusionLayer, extrusionStyle } from "./layers/extrusions.js";
@@ -34,7 +34,7 @@ import { mapSettings, sendHeaders } from "./map/engine-settings.js";
 import { MapEngines } from "./map/engines.js";
 import { MapListeners } from "./map/events.js";
 import { FrameLoop } from "./map/frame-loop.js";
-import { HoverPick } from "./map/hover-pick.js";
+import { HoverPick, pickOnce } from "./map/hover-pick.js";
 import { addSpec } from "./map/layer-spec.js";
 import { LayerStack } from "./map/layer-stack.js";
 import { OverlayHost } from "./map/overlay-host.js";
@@ -67,12 +67,22 @@ const NETWORK_HALO_OPACITY = 0.11;
 /** A layer whose picked features come back with their properties (lines, circles, fills, extrusions, 3D Tiles…) */
 const hasFeatures = (layer) => 'featureAt' in layer && typeof layer.featureAt === 'function';
 /** A map (see `GeoMap.create`); layers take it as their host */
+/** The parts of a frame by their code in the engine's GPU timings (`Engine.gpuTimings`) */
+const GPU_PARTS = ['backdrop', 'ground', 'layer', 'shadows', 'panorama', 'viewshed'];
+/** Turns the GPU timing of an engine on or off: whether it times, false for an engine built without it (only a build to
+ * profile has `setGpuTiming`) */
+const engineGpuTiming = (engine, on) => {
+    const set = Reflect.get(engine, 'setGpuTiming');
+    return typeof set === 'function' && Reflect.apply(set, engine, [on]) === true;
+};
 export class GeoMap {
     canvas;
     #engine;
+    /** The frames' parts timed on the GPU (`setGpuTiming`), again on a new engine */
+    gpuTiming = false;
     /** The work the map waits on before it is idle (`track`) */
     #working = 0;
-    /** The engine class (core, or with 3D Tiles) and the engine with 3D Tiles loaded when needed */
+    /** The engine, made asynchronously, and the workers decoding its 3D Tiles */
     engines;
     /** The layers in drawing order and those kept on top */
     stack = new LayerStack(() => this.#engine);
@@ -90,7 +100,7 @@ export class GeoMap {
     tessUrl;
     /** @internal Where the workers load the grid module from (`isard_grid_bg.wasm`) */
     gridUrl;
-    /** The WebGL context is lost: nothing is drawn until it is restored */
+    /** The GPU is lost (the WebGL context, the WebGPU device): nothing is drawn until a new engine is there */
     lost = false;
     gone = false;
     listeners = new MapListeners();
@@ -124,20 +134,25 @@ export class GeoMap {
     static async create(container, given = {}) {
         // A preset under the options given
         const options = given.preset ? { ...IGN_PRESETS[given.preset], ...given } : given;
-        // With 3D Tiles from the start when asked, or when only that engine's URL is given (as before the core engine)
-        const full = options.tiles3d === true || (options.wasmUrl !== undefined && options.coreWasmUrl === undefined);
         // Before anything is created
         if (options.basemap !== undefined)
             checkBasemap(options.basemap);
-        const kind = full ? 'full' : 'core';
+        // The engine on wgpu (#146): WebGPU, else wgpu's WebGL2 fallback
+        const kind = await rendererKind(options.renderer);
         const bindings = await loadEngine(kind, engineUrl(kind, options));
-        const map = new GeoMap(container, options, bindings.Engine, full ? bindings.module : undefined);
-        if (options.tiles3d === 'preload' && !full)
-            map.preloadTiles3d();
+        const map = new GeoMap(container, options, bindings.Engine);
+        // Its device asked for: the map started on a placeholder meanwhile, its layers created on the engine once it is
+        // there (as after a context loss)
+        map.adopt(await map.engines.create(map.canvas, () => map.requestRender(), map.settings));
+        // A profiling script's page (`window.__isardProfile` set before isard loads): its maps, to time
+        if (Reflect.get(globalThis, '__isardProfile')) {
+            const maps = Reflect.get(globalThis, '__isardMaps');
+            Reflect.set(globalThis, '__isardMaps', [...(Array.isArray(maps) ? maps : []), map]);
+        }
         return map;
     }
-    constructor(container, options, engineClass, tiles3dModule) {
-        this.engines = new MapEngines(engineClass, tiles3dModule, options, () => this.gone);
+    constructor(container, options, engineClass) {
+        this.engines = new MapEngines(engineClass, options);
         const workerUrl = options.basemapWorkerUrl ?? defaultWorkerUrl(options.assetsUrl);
         this.tessUrl = tessUrl(options);
         this.gridUrl = gridUrl(options);
@@ -145,7 +160,8 @@ export class GeoMap {
         this.basemaps = new BasemapLayers(this, this.stack, workerUrl, options.basemapTileSize);
         this.container = container;
         this.canvas = createCanvas();
-        this.atlases = new SymbolAtlases(this.canvas, options.glyphs, () => this.#engine);
+        // The engine takes the canvas for itself: it says how large a texture its device takes
+        this.atlases = new SymbolAtlases(() => this.#engine.maxTextureSize(), options.glyphs, () => this.#engine);
         this.overlays = new OverlayHost(container, this.canvas, this);
         this.earth = (options.body ?? 'earth') === 'earth';
         this.body = options.body;
@@ -156,7 +172,6 @@ export class GeoMap {
             lost: () => this.lost,
             interacting: () => this.interaction?.active === true,
             customLayers: () => this.layers.some((layer) => layer instanceof CustomLayer),
-            upgrading: () => this.engines.upgrading !== undefined,
             working: () => this.#working > 0,
             drawn: (hovered) => {
                 this.qualityWatch?.frame(performance.now(), this.movingNow);
@@ -167,15 +182,13 @@ export class GeoMap {
                 this.overlays.positionAll();
             },
         }, this.listeners);
-        this.#engine = this.createEngine();
+        // The engine is made asynchronously (`GeoMap.create` adopts it): a placeholder meanwhile
+        this.#engine = destroyedEngine(EARTH_START);
         // Once it has an engine: a map whose creation failed before is not left following them
         this.unwatchHeaders = onHeaderRules((rules) => sendHeaders(this.#engine, rules));
-        // The browser may take the GPU away (driver reset, background tab on mobile): the map waits, then rebuilds
-        this.unwatchContext = watchContext(this.canvas, () => {
-            this.lost = true;
-            this.frames.cancel();
-            this.dropLostEngine();
-        }, () => this.restore());
+        // The browser may take the GPU away (driver reset, background tab on mobile): the map waits, then rebuilds. A
+        // WebGPU device lost is watched with each engine (`adopt`)
+        this.unwatchContext = watchContext(this.canvas, () => this.gpuLost(), () => this.restore());
         const start = this.earth ? EARTH_START : BODY_START;
         this.setCamera({ ...start, ...options });
         this.setBasemap(options.basemap ?? (this.earth ? 'osm-positron' : 'none'), options.hillshade ?? 0);
@@ -224,33 +237,26 @@ export class GeoMap {
     get onTop() {
         return this.stack.onTop;
     }
-    createEngine() {
-        return this.engines.create(this.canvas, () => this.requestRender(), this.settings);
-    }
-    /** A 3D Tiles layer or a model on the core engine: loads the engine with 3D Tiles, then rebuilds the map on it
-     * (camera, settings and layers kept, as after a context loss); the layer is created then */
-    upgrade() {
-        this.engines.upgrade(() => {
-            // A lost context: the engine is rebuilt on it once restored
-            if (!this.lost)
-                this.restore();
-        }, (error) => {
-            // The 3D Tiles layers stay empty; the next one added tries again
-            report(error);
-            this.requestRender();
-        });
+    /** The GPU is lost: nothing drawn, the engine dropped (`dropLostEngine`) */
+    gpuLost() {
+        this.lost = true;
+        this.frames.cancel();
+        this.dropLostEngine();
     }
-    /** Downloads and compiles the engine with 3D Tiles once the map is idle (`tiles3d: 'preload'`), without running
-     * it: the first 3D Tiles layer then only instantiates it */
-    preloadTiles3d() {
-        if (this.frames.settled)
-            this.engines.preload();
-        else {
-            const off = this.on('idle', () => {
-                off();
-                this.engines.preload();
-            });
-        }
+    /**
+     * Follows the loss of `engine`'s WebGPU device (a phone taking its memory back, a driver reset, the GPU process
+     * gone): while it is the map's, the map drops it and makes a new one at once, WebGPU having no event for the GPU
+     * given back. The device of an engine the map freed itself (replaced, the map destroyed) is lost too: not the map's
+     * any more, left be
+     */
+    watchDevice(engine) {
+        void engine.gpuDevice()?.lost.then((info) => {
+            if (this.gone || this.#engine !== engine)
+                return;
+            console.warn(`isard: the GPU device was lost (${info.reason}: ${info.message}), the map made again`);
+            this.gpuLost();
+            this.restore();
+        });
     }
     /**
      * The context is lost: its engine freed at once, the map's calls going to one that does nothing until `restore`
@@ -266,19 +272,35 @@ export class GeoMap {
         // Glyph ranges and icons arriving meanwhile upload to it, not to the freed engine
         this.atlases.attach(this.#engine);
     }
-    /** After a context loss: a new engine with the same camera, settings and layers (same handles, same order) */
+    /** After the GPU lost: a new engine with the same camera, settings and layers (same handles, same order); the engine
+     * made asynchronously, adopted once there */
     restore() {
         if (this.gone)
             return;
+        this.engines
+            .create(this.canvas, () => this.requestRender(), this.settings)
+            .then((engine) => this.adopt(engine))
+            .catch(report);
+    }
+    /** A new engine in place of the map's (a placeholder, or a lost one): the same camera, settings and layers (same
+     * handles, same order) */
+    adopt(engine) {
+        if (this.gone) {
+            engine.free();
+            return;
+        }
         this.hoverPick.cancel();
         const camera = this.getCamera();
         this.#engine.free();
-        this.#engine = this.createEngine();
+        this.#engine = engine;
         this.lost = false;
+        this.watchDevice(engine);
+        // Still timed (profiling)
+        if (this.gpuTiming)
+            engineGpuTiming(engine, true);
         this.setCamera(camera);
         this.atlases.attach(this.#engine);
-        // Those still waiting for the engine with 3D Tiles (loading, or failed) are created with it
-        this.stack.reattach(this.#engine, (layer) => layer.needsFullEngine && !this.engines.tiles3d);
+        this.stack.reattach(this.#engine);
         this.applySwipe();
         // A street-level eye stays one in the new engine
         if (this.#firstPerson)
@@ -293,6 +315,7 @@ export class GeoMap {
                 void set.show(set.current.index).catch(report);
         });
         this.resize();
+        this.requestRender();
     }
     /** The street-level eye, while there is one (`setFirstPerson`) */
     #firstPerson;
@@ -354,20 +377,14 @@ export class GeoMap {
         return !this.gone && this.stack.has(layer);
     }
     addLayer(layer) {
-        // On the core engine, a 3D Tiles layer or a model waits for the engine with 3D Tiles: it is created with the
-        // others on it
-        if (layer.needsFullEngine && !this.engines.tiles3d)
-            this.upgrade();
-        else {
-            try {
-                layer.attach(this.engine);
-            }
-            catch (error) {
-                // A context lost before the browser says so (its event comes later): nothing could be made on it, the layer is
-                // made with the others on the next engine (`restore`). Any other failure is the caller's
-                if (!this.contextLost())
-                    throw error;
-            }
+        try {
+            layer.attach(this.engine);
+        }
+        catch (error) {
+            // A context lost before the browser says so (its event comes later): nothing could be made on it, the layer is
+            // made with the others on the next engine (`restore`). Any other failure is the caller's
+            if (!this.contextLost())
+                throw error;
         }
         // Under the layers kept on top (the basemap's labels)
         this.stack.add(layer);
@@ -376,6 +393,7 @@ export class GeoMap {
     }
     /** Whether the canvas's WebGL context is lost, its event come or not */
     contextLost() {
+        // On a WebGPU canvas, no WebGL context: null, nothing taken
         return this.lost || this.canvas.getContext('webgl2')?.isContextLost() === true;
     }
     /** @internal Keeps a layer above the layers added after it (they go under it), as the labels of a basemap */
@@ -573,26 +591,64 @@ export class GeoMap {
         this.engine.setBackground(...this.settings.background);
         this.requestRender();
     }
+    /** The GPU memory its layers hold (bytes): the tiles of the 3D Tiles and point clouds, kept within the budget
+     * (`GeoMapOptions.memory`), the rasters' pools */
+    memory() {
+        // Two numbers a layer, its id and its bytes, the relief's (id 0) last
+        const pairs = this.engine.memory();
+        const byId = new Map(Array.from({ length: pairs.length / 2 }, (_, i) => [pairs[2 * i], pairs[2 * i + 1] ?? 0]));
+        const layers = this.layers.flatMap((layer) => {
+            const bytes = layer.id >= 0 ? byId.get(layer.id) : undefined;
+            return bytes === undefined ? [] : [{ layer, bytes }];
+        });
+        return {
+            budget: this.settings.memory,
+            held: [...byId.values()].reduce((sum, bytes) => sum + bytes, 0),
+            layers,
+        };
+    }
     /** Tile counters of the raster layers, for diagnostics */
     stats() {
         return this.engine.stats();
     }
+    /** Times the parts of each frame on the GPU, for profiling (`gpuTimings`): timer queries, read a few frames later.
+     * An engine built to profile only (`PROFILE=1 bun run build`); false without one, or if the browser cannot
+     * (`EXT_disjoint_timer_query_webgl2`) */
+    setGpuTiming(on) {
+        this.gpuTiming = engineGpuTiming(this.engine, on);
+        return this.gpuTiming;
+    }
+    /** The GPU time of the last frame measured (`setGpuTiming`), in all and by part: the backdrop, the ground (the raster
+     * layers over the relief), each layer, the shadows, the panorama, the viewshed (ms) */
+    gpuTimings() {
+        // The frame's number, then each part's code, layer id (-1 for none) and milliseconds
+        const read = Reflect.get(this.engine, 'gpuTimings');
+        const flat = typeof read === 'function' ? Reflect.apply(read, this.engine, []) : undefined;
+        if (!(flat instanceof Float64Array) || flat.length === 0)
+            return undefined;
+        const parts = Array.from({ length: (flat.length - 1) / 3 }, (_, k) => {
+            const [code = 0, id = -1, ms = 0] = flat.subarray(1 + k * 3, 4 + k * 3);
+            const layer = id >= 0 ? this.layers.find((l) => l.id === id) : undefined;
+            return { part: GPU_PARTS[code] ?? 'layer', ms, ...(layer && { layer }) };
+        });
+        return { frame: flat[0] ?? 0, ms: parts.reduce((sum, p) => sum + p.ms, 0), parts };
+    }
     /**
-     * The feature under a screen point (CSS pixels), undefined if none: its layer id and index. Reads one pixel of an
-     * offscreen picking pass, whatever the number of features, but waits for the GPU to finish the frame (a stall): for
-     * clicks and one-off queries. On hover, listen to 'hoverfeature' instead, which picks without waiting.
+     * The feature under a screen point (CSS pixels), undefined if none: its layer id and index. Reads the pixels around
+     * the point of an offscreen picking pass, whatever the number of features, once the GPU is done (a frame or two
+     * later: the GPU is not waited for). On hover, listen to 'hoverfeature' instead.
      */
-    pick(point, { radius = 0, layers } = {}) {
+    async pick(point, { radius = 0, layers } = {}) {
         const only = layers && Uint32Array.from(layers.map((l) => l.id));
-        return this.engine.pick(point[0], point[1], radius, only);
+        return (await pickOnce(() => this.engine, point, radius, only))?.hit;
     }
     /**
      * The feature under a screen point (CSS pixels), or the nearest one within `radius` pixels: its layer handle, its
      * index there and, for line, circle and fill layers, the feature itself; undefined if none. `layers` restricts the
      * search to some layers (the others hide nothing).
      */
-    pickFeature(point, options = {}) {
-        const hit = this.pick(point, options);
+    async pickFeature(point, options = {}) {
+        const hit = await this.pick(point, options);
         return hit && this.featureHit(hit);
     }
     /** A hit with its layer handle and feature; undefined if the layer is gone */
@@ -617,13 +673,6 @@ export class GeoMap {
      * and calibrations loaded, none shown until `show`, which projects one onto the scene around it
      */
     async addPanoramas(options) {
-        // Drawn by the engine with 3D Tiles: loaded first if needed
-        if (!this.engines.tiles3d) {
-            this.upgrade();
-            await this.engines.upgrading;
-            if (!this.engines.tiles3d)
-                throw new Error('isard: panoramas need the engine with 3D Tiles, which failed to load');
-        }
         const host = panoramaHost(this, (lon, lat) => this.engines.geoidHeight(lon, lat));
         const panoramas = await loadPanoramas(host, options);
         this.panoramaSets.add(panoramas);
@@ -664,15 +713,16 @@ export class GeoMap {
             this.interaction.rotateAroundPointer = enabled;
     }
     /** What is drawn under a screen point (CSS pixels), on the relief or standing on it (a roof, a wall, a mesh): its
-     * position and its height above the relief, in metres; undefined where nothing was drawn. The last frame's scene is
-     * drawn again and read back, waiting for the GPU (a stall): for clicks and drags */
+     * position and its height above the relief, in metres; undefined where nothing was drawn. Read from the last copy of
+     * the scene's depth (a frame or two old, a pixel every 4 CSS pixels): at once, without waiting for the GPU */
     pickSurface(point) {
         const hit = this.engine.surface(point[0], point[1]);
         return hit && { lonLat: [hit[0], hit[1]], height: hit[2] };
     }
     /** The height above the relief, in metres, of the top of what stands at a position: a roof, a mesh, 0 on the bare
-     * ground; undefined where nothing of the last frame is there. The scene is drawn from above into a single pixel and
-     * read back: cheap, but it waits for the GPU */
+     * ground; undefined where nothing of the last frame is there, or until measured: the scene is drawn looking down at
+     * it after a frame and read back a frame or two later, the answer kept and measured again every 250 ms at most (ask
+     * again on the next `render` event) */
     surfaceAt(lonLat) {
         return this.engine.surfaceAt(lonLat[0], lonLat[1]);
     }
@@ -802,7 +852,7 @@ export class GeoMap {
     }
     /** Polygons raised into blocks with depth (buildings), styled per feature; tiles of them come with `setTile` */
     addExtrusions(options = {}) {
-        return this.place(new ExtrusionLayer(this, options.data, extrusionStyle(options)), options.before);
+        return this.place(new ExtrusionLayer(this, options.data, extrusionStyle(options), options.drape), options.before);
     }
     /** Text labels from GeoJSON (points, the middle of lines, the center of polygons), placed without overlaps */
     addSymbols(options) {
@@ -879,7 +929,7 @@ export class GeoMap {
     }
     /**
      * A point cloud (see `PointCloudOptions`): a COPC file read by range requests (IGN's LiDAR HD…), or 3D Tiles
-     * points; with depth, on the engine with 3D Tiles; under `before` if given
+     * points; with depth; under `before` if given
      */
     addPointCloud(options) {
         return this.place(new PointCloudLayer(this, options), options.before);
@@ -898,7 +948,7 @@ export class GeoMap {
     addFlow(options) {
         return this.place(new FlowLayer(this, options), options.before);
     }
-    /** A glTF model drawn at positions (see `ModelOptions`), with depth; on the engine with 3D Tiles, as they are */
+    /** A glTF model drawn at positions (see `ModelOptions`), with depth */
     addModels(options) {
         return this.place(new ModelLayer(this, options), options.before);
     }
@@ -913,11 +963,12 @@ export class GeoMap {
         return addPhoto((o) => this.addModels(o), options);
     }
     /**
-     * The page's own WebGL drawing at its place among the layers, in every frame (see `CustomLayerInterface`): raw
-     * WebGL, three.js… with the matrices of the frame (`frame.matrixAt`); under `before` if given
+     * The page's own WebGPU drawing at its place among the layers, in every frame (see `CustomLayerInterface`): raw
+     * WebGPU, three.js's WebGPU renderer… with the map's device and the matrices of the frame (`frame.matrixAt`); under
+     * `before` if given. Not drawn on the WebGL2 fallback
      */
     addCustomLayer(layer, options = {}) {
-        const custom = new CustomLayer(this, layer, this.canvas, this, (lon, lat, altitude) => this.engines.customMatrix(lon, lat, altitude), () => this.getCamera());
+        const custom = new CustomLayer(this, layer, this, (lon, lat, altitude) => this.engines.customMatrix(lon, lat, altitude), () => this.getCamera());
         return this.place(custom, options.before);
     }
     // ── Frames ──
@@ -975,7 +1026,7 @@ export class GeoMap {
         this.resizeObserver.disconnect();
         this.interaction?.destroy();
         this.engines.destroy();
-        // Custom layers free their WebGL objects, models their data, while the context is there
+        // Custom layers free their GPU objects, models their data, while the device is there
         this.stack.dispose();
         this.engine.free();
         // Work still under way (labels being shaped, tiles arriving, timers) may call the engine after this: it finds one