isard 1.0.0 → 1.2.0

package/dist/wasm/isard.js

@@ -1,5 +1,9 @@
 /* @ts-self-types="./isard.d.ts" */
 
+/**
+ * A map on one canvas: its WebGL2 context, camera, ground (raster layers over the relief) and the layers over it.
+ * Draws only when `render` is called (the JavaScript side calls it after `redraw` asks for a frame)
+ */
 export class Engine {
     __destroy_into_raw() {
         const ptr = this.__wbg_ptr;
@@ -13,6 +17,11 @@ export class Engine {
     }
     /**
      * Circle layer of `feature_count` features: points (Mercator [0, 1], interleaved) and the feature of each
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log), or when `feature_count` features need a table texture past the GPU's `MAX_TEXTURE_SIZE`
      * @param {Float64Array} points
      * @param {Uint32Array} feature
      * @param {number} feature_count
@@ -43,6 +52,11 @@ export class Engine {
     }
     /**
      * An empty extrusion layer: its blocks come in batches (`setExtrusionBatch`)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log)
      * @returns {number}
      */
     addExtrusions() {
@@ -56,6 +70,11 @@ export class Engine {
      * Fill layer of `feature_count` features: polygons given by their points (Mercator [0, 1], interleaved), the first
      * point of each ring (`ring_start`, one more entry than rings), the first ring of each polygon (`polygon_start`,
      * one more entry than polygons; the first ring is the outer one, the others holes) and the feature of each polygon
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log), or when `feature_count` features need a table texture past the GPU's `MAX_TEXTURE_SIZE`
      * @param {Float64Array} points
      * @param {Uint32Array} ring_start
      * @param {Uint32Array} polygon_start
@@ -82,6 +101,10 @@ export class Engine {
      * Ground layer running `code` (GLSL ES 3.0 defining `vec4 ground(vec2 offset)`, see `render::ground`) over the
      * ground; `anchor`: Mercator point the offsets are taken from; bounds: Mercator box it shows in. Compilation errors
      * come back with the shader's info log (line numbers of `code`)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when `code` does not compile or link, with the shader's info log
      * @param {string} code
      * @param {number} anchor_x
      * @param {number} anchor_y
@@ -103,6 +126,11 @@ export class Engine {
     /**
      * Line layer of `feature_count` features: polylines given by their points (Mercator [0, 1], interleaved), the
      * first point of each (`start`, one more entry than lines) and the feature each one belongs to
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log), or when the features or the lines need a table texture past the GPU's `MAX_TEXTURE_SIZE`
      * @param {Float64Array} points
      * @param {Uint32Array} start
      * @param {Uint32Array} feature
@@ -126,6 +154,11 @@ export class Engine {
      * A glTF / GLB model (its URL, a `blob:` one for data of the page) drawn at each instance of `instances`
      * (`INSTANCE_NUMBERS` numbers each: longitude, latitude, altitude, heading, pitch, roll in degrees, scale);
      * `ground`: altitudes above the relief, else above the ellipsoid
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log). A model that fails to load or decode does not throw: the layer stays empty
      * @param {string} url
      * @param {Float64Array} instances
      * @param {boolean} ground
@@ -148,6 +181,12 @@ export class Engine {
      * edges (node index pairs, interleaved). `line_start` and `line_points`: the line of each edge from A to B, points
      * `line_start[e] .. line_start[e + 1]` of `line_points` (Mercator, interleaved; straight if fewer than two). `costs`: per edge, the
      * cost of travelling it from A to B then from B to A; without, values are interpolated along the edges.
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when `style` is not 25 numbers, `edges` is not node pairs or names a node past
+     * those of `mercator`, the nodes or edges need a table texture past the GPU's `MAX_TEXTURE_SIZE`, or when
+     * a WebGL object cannot be created or a shader fails to compile (the error carries its info log)
      * @param {Float64Array} mercator
      * @param {Uint32Array} edges
      * @param {Uint32Array | null | undefined} line_start
@@ -179,6 +218,11 @@ export class Engine {
      * A COPC point cloud from its URL (HTTP range requests). `resolve(wkt)` gives the CRS of the file from its WKT
      * (undefined if it has none): its inverse projection, whether its altitudes are above the geoid, the metres of
      * a unit of z; it may throw (an unknown CRS), the layer then stays empty
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log). The file itself is read later: a bad file, or a `resolve` that throws, leaves the layer empty
      * @param {string} url
      * @param {(wkt: string | undefined) => PointCloudCrs} resolve
      * @returns {number}
@@ -196,6 +240,10 @@ export class Engine {
      * Raster tiles in Web Mercator; `url` holds {z}, {x} and {y}. `size`: side of the tiles' textures (256 by
      * default); `loader`: draws each tile instead of fetching `url`, `(z, x, y, signal) => Promise<ImageBitmap |
      * null>`, an image of `size` × `size` (null: nothing there)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the texture holding the layer's tiles cannot be created
      * @param {string} url
      * @param {number} min_z
      * @param {number} max_z
@@ -216,6 +264,11 @@ export class Engine {
     }
     /**
      * An empty symbol layer
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL object cannot be created or a shader fails to compile (the error carries its
+     * info log)
      * @returns {number}
      */
     addSymbols() {
@@ -229,6 +282,11 @@ export class Engine {
      * 3D Tiles (b3dm / glb textured meshes, external tilesets) from the URL of a `tileset.json`. `max_error`:
      * screen-space error (CSS pixels) above which a tile is refined; 16 is the usual value, lower is finer.
      * `geoid`: its heights are altitudes (NGF-IGN69), each tile raised by the RAF20 geoid onto the relief.
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when one of the layer's programs fails to compile or link (the error carries
+     * its info log). The tileset itself is read later: a bad one leaves the layer empty, it does not throw
      * @param {string} url
      * @param {number} max_error
      * @param {boolean | null} [geoid]
@@ -255,6 +313,7 @@ export class Engine {
         return v1;
     }
     /**
+     * The camera as set or moved: center (degrees), zoom, pitch and bearing (degrees)
      * @returns {Camera}
      */
     camera() {
@@ -267,6 +326,9 @@ export class Engine {
     clearPanorama() {
         wasm.engine_clearPanorama(this.__wbg_ptr);
     }
+    /**
+     * Stops loading the tiles of the flight's destination (`preload`)
+     */
     clearPreload() {
         wasm.engine_clearPreload(this.__wbg_ptr);
     }
@@ -371,6 +433,11 @@ export class Engine {
     }
     /**
      * `redraw` is called when the engine needs a new frame (a tile arrived)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the canvas gives no WebGL2 context ("WebGL2 is not available"), or when a WebGL
+     * object of the globe, the sky or the raster pass cannot be created or one of their shaders fails to compile
      * @param {HTMLCanvasElement} canvas
      * @param {() => void} redraw
      */
@@ -473,6 +540,7 @@ export class Engine {
         return ret;
     }
     /**
+     * Removes batch `key` of an extrusion layer (nothing if there is none)
      * @param {number} id
      * @param {number} key
      */
@@ -480,12 +548,15 @@ export class Engine {
         wasm.engine_removeExtrusionBatch(this.__wbg_ptr, id, key);
     }
     /**
+     * Removes a layer and frees its GPU objects; the other layers forget it (a layer that referred to it)
      * @param {number} id
      */
     removeLayer(id) {
         wasm.engine_removeLayer(this.__wbg_ptr, id);
     }
     /**
+     * Draws a frame: the backdrop, the ground and the layers over it bottom to top, then the panorama and the
+     * viewshed; returns true while tiles are still loading (a new frame will be asked through `redraw`)
      * @returns {boolean}
      */
     render() {
@@ -536,6 +607,7 @@ export class Engine {
         wasm.engine_setAtmosphere(this.__wbg_ptr, ptr0, len0);
     }
     /**
+     * Color the canvas is cleared to (RGB 0-1), where neither ground nor sky is drawn
      * @param {number} r
      * @param {number} g
      * @param {number} b
@@ -561,6 +633,8 @@ export class Engine {
         wasm.engine_setBody(this.__wbg_ptr, radius, flattening, ptr0, len0, lowest, highest);
     }
     /**
+     * Sets the camera (degrees, the conventions of `MapLibre`): leaves a street-level view, and the camera keeps this
+     * center as the relief comes in
      * @param {number} lon
      * @param {number} lat
      * @param {number} zoom
@@ -593,6 +667,11 @@ export class Engine {
     }
     /**
      * Anchors of batch `key` on the linked network: per feature, node A, node B, cost from A, cost from B
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the batch's features need an anchor texture past the GPU's
+     * `MAX_TEXTURE_SIZE`, or when it cannot be created
      * @param {number} id
      * @param {number} key
      * @param {Float32Array} anchors
@@ -608,6 +687,11 @@ export class Engine {
     /**
      * Adds or replaces batch `key` of an extrusion layer: polygons as for `addFills`, `feature_count` features (the
      * feature style gives each its height and base height as its two sizes, metres)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when a WebGL buffer or vertex array of the batch cannot be created, or when
+     * `feature_count` features need a table texture past the GPU's `MAX_TEXTURE_SIZE`
      * @param {number} id
      * @param {number} key
      * @param {Float64Array} points
@@ -744,6 +828,10 @@ export class Engine {
     /**
      * The glyph atlas shared by the symbol layers, one page: `width` × `height` bytes of signed distances
      * (allocated again, filled with `data` if given)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) as `setGlyphPages` does: a size that is not positive, or the texture not created
      * @param {number} width
      * @param {number} height
      * @param {Uint8Array | null} [data]
@@ -760,6 +848,11 @@ export class Engine {
      * The glyph atlas shared by the symbol layers, `pages` pages of `width` × `height` bytes of signed distances,
      * allocated again and empty (`updateGlyphPage` fills them). A glyph on page `p` at row `v` has the atlas
      * coordinate `v + p × height`
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when `width` or `height` is not positive (or their product overflows), `pages`
+     * is not 1 to 256, or the atlas texture cannot be created
      * @param {number} width
      * @param {number} height
      * @param {number} pages
@@ -771,6 +864,7 @@ export class Engine {
         }
     }
     /**
+     * Moves the Mercator box (0-1) a ground layer shows in
      * @param {number} id
      * @param {number} min_x
      * @param {number} min_y
@@ -784,6 +878,11 @@ export class Engine {
      * Creates the texture of sampler `name` (`format`: r8, r8ui, r16ui, r16i, r32ui, r32f, rg16ui, rg32f, rgba8,
      * rgba8ui, rgba16ui, rgba32f; `depth` 0 for 2D, else a 2D array of that many layers; `linear` filtering for the
      * non-integer formats); `data`: its texels as bytes, or undefined for an empty texture
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) on an unknown `format`, a size not positive (or overflowing), `data` shorter
+     * than the texels, more textures than the layer takes, or a texture WebGL cannot create
      * @param {number} id
      * @param {string} name
      * @param {string} format
@@ -807,6 +906,11 @@ export class Engine {
     }
     /**
      * A uniform of a ground layer's code, as numbers
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the shader has no uniform `name` (one its code does not use is removed
+     * by the compiler)
      * @param {number} id
      * @param {string} name
      * @param {Float64Array} values
@@ -822,6 +926,7 @@ export class Engine {
         }
     }
     /**
+     * Shows or hides a ground layer (kept, with its uniforms and textures)
      * @param {number} id
      * @param {boolean} visible
      */
@@ -831,6 +936,11 @@ export class Engine {
     /**
      * The icon atlas shared by the symbol layers: `width` × `height` RGBA texels, premultiplied, allocated again
      * and empty (`updateIconAtlas` fills it)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when `width` or `height` is not positive (or their product overflows), or the
+     * atlas texture cannot be created
      * @param {number} width
      * @param {number} height
      */
@@ -859,6 +969,11 @@ export class Engine {
     }
     /**
      * New lines for a line layer (same arguments as `addLines`, the same features)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the lines need a table texture past the GPU's `MAX_TEXTURE_SIZE`, or
+     * when it cannot be created; the layer then keeps its lines
      * @param {number} id
      * @param {Float64Array} points
      * @param {Uint32Array} start
@@ -948,6 +1063,10 @@ export class Engine {
     }
     /**
      * The image of camera `index` of the panorama (the images sharing the size of the first)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when WebGL refuses the upload of `image` into the panorama's texture
      * @param {number} index
      * @param {ImageBitmap} image
      */
@@ -963,6 +1082,11 @@ export class Engine {
      * frame, row-major, 9; position in it, 3; focal x, y; center x, y; skew; image width, height; principal point of
      * the distortion x, y; its coefficients r³, r⁵, r⁷; its limit, pixels), a backdrop sphere of `radius` metres, at
      * `opacity`. Its images come after (`setPanoramaImage`)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when `rotation` holds fewer than 9 numbers, or when a WebGL object cannot be created or a
+     * shader fails to compile (the error carries its info log)
      * @param {number} lon
      * @param {number} lat
      * @param {number} height
@@ -999,6 +1123,7 @@ export class Engine {
         wasm.engine_setPointCloudStyle(this.__wbg_ptr, id, ptr0, len0, ptr1, len1, ptr2, len2);
     }
     /**
+     * Opacity and saturation (0-1) of a raster layer; nothing for another id
      * @param {number} id
      * @param {number} opacity
      * @param {number} saturation
@@ -1062,6 +1187,11 @@ export class Engine {
      * Labels of a symbol layer, shaped by the page: anchors (Mercator, interleaved), their texts' boxes (min x, min y,
      * max x, max y, CSS pixels from the anchor), styles (36 floats each, see `LABEL_FLOATS`) and glyph and icon quads
      * (11 floats each, see `QUAD_FLOATS`)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the labels need a table texture past the GPU's `MAX_TEXTURE_SIZE`, or
+     * when it cannot be created; the layer then keeps its labels
      * @param {number} id
      * @param {Float64Array} anchors
      * @param {Float32Array} boxes
@@ -1091,6 +1221,10 @@ export class Engine {
      * above the ellipsoid, those of 3D Tiles; over France, on the Earth only), else left as served (the default);
      * `loader`: gives the
      * altitudes of each tile instead of fetching `url` (an encoding decoded by the page: Terrarium, Terrain-RGB)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when the texture holding the relief's tiles cannot be created
      * @param {string | null | undefined} url
      * @param {number} exaggeration
      * @param {number | null | undefined} max_z
@@ -1134,6 +1268,11 @@ export class Engine {
      * only heading, tilt, angles of view across and up (degrees), the heading NaN to look all around. What some
      * observer sees is tinted with `visible`, what is hidden from all those that reach it with `hidden` (RGB 0-1),
      * at `opacity`; `outline` (RGB 0-1, or empty) the color of the cones' edges drawn in 3D
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when, on the first call, a WebGL object cannot be created or a shader fails to compile
+     * (the error carries its info log)
      * @param {Float64Array} observers
      * @param {Float32Array} visible
      * @param {Float32Array} hidden
@@ -1155,6 +1294,7 @@ export class Engine {
         }
     }
     /**
+     * Lowest and highest zoom levels the camera accepts
      * @param {number} min
      * @param {number} max
      */
@@ -1251,6 +1391,11 @@ export class Engine {
     }
     /**
      * Replaces a region of a ground layer's texture (one layer of a 2D array)
+     *
+     * # Errors
+     *
+     * Throws (to JavaScript) when there is no texture `name`, or when the region is out of its bounds or
+     * `data` holds too few bytes
      * @param {number} id
      * @param {string} name
      * @param {number} x
@@ -1296,6 +1441,7 @@ export class Engine {
         return v1;
     }
     /**
+     * Zooms by `delta` levels around a screen point (CSS pixels), which keeps the same ground point under it
      * @param {number} delta
      * @param {number} x
      * @param {number} y