leaflet-city-mapper 0.0.8 → 0.1.0

package/src/raster/getRasterTileSize.js

@@ -1,7 +1,11 @@
 import { L } from '../globals/L.js';
 import { TILE_SIZE } from '../globals/TILE_SIZE.js';
 
-
+/**
+ * Get the raster tile dimensions.
+ *
+ * @returns {L.Point} Tile size in pixels.
+ */
 export function getRasterTileSize() {
   return /* alloc */ new L.Point(TILE_SIZE, TILE_SIZE);
 }

package/src/raster/initRaster.js

@@ -7,10 +7,7 @@ import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { L } from '../globals/L.js';
-
-
 import { isLoading } from './isRasterLoading.js';
 import { getRasterEvents } from './getRasterEvents.js';
 import { readyRaster } from './readyRaster.js';
@@ -25,6 +22,12 @@ import { getRasterTileSize } from './getRasterTileSize.js';
 import { setPMTileOpacity } from './setPMTileOpacity.js';
 import { setPMTileZIndex } from './setPMTileZIndex.js';
 
+/**
+ * Initialize raster layer state and start reading its archive header.
+ *
+ * @param {L.Layer} layer Raster layer to initialize.
+ * @param {Object} options Layer and archive options.
+ */
 export function initRaster(layer, options) {
   kindByLayer.set(layer, 'raster');
   options = /* alloc */ { ariaLabel: 'PMTiles raster', maxZoom: 18, opacity: 1, zIndex: 0, ...options };

package/src/raster/isRasterLoading.js

@@ -1,8 +1,12 @@
 import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
 
-
-
-
+/**
+ * Check whether a raster layer has tile loads in progress.
+ *
+ * @param {L.Layer} layer Raster layer.
+ *
+ * @returns {boolean} Whether at least one tile is loading.
+ */
 export function isLoading(layer) {
   return loadingTilesByLayer.get(layer) > 0;
 }

package/src/raster/loadRasterTile.js

@@ -1,9 +1,14 @@
 import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
-
-
-
 import { finishRasterTile } from './finishRasterTile.js';
 
+/**
+ * Mark a tile as loading, emit start events and begin its asynchronous load.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} tile Tile to load.
+ *
+ * @returns {Promise<void>} Completion of the load attempt.
+ */
 export function loadRasterTile(layer, tile) {
   tile.started = true;
   const first = loadingTilesByLayer.get(layer) === 0;

package/src/raster/onPMTileAdd.js

@@ -1,11 +1,14 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
-
-
 import { finishAttachment } from './finishRasterAttachment.js';
 import { updateAttachedTiles } from './updateAttachedTiles.js';
 import { attach } from '../scene/attachSharedScene.js';
 
+/**
+ * Attach a raster layer to the shared scene and start updating its tiles when ready.
+ *
+ * @param {L.Layer} layer Raster layer being added.
+ * @param {L.Map} map Map receiving the layer.
+ */
 export function onPMTileAdd(layer, map) {
   if (!locationByLayer.get(layer)) locationByLayer.set(layer, map.getCenter());
   const attached = attach(layer, map);

package/src/raster/onPMTileRemove.js

@@ -1,10 +1,13 @@
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { releaseRasterTiles } from './releaseRasterTiles.js';
 import { onRemove3DLayer } from '../scene/onRemove3DLayer.js';
 
+/**
+ * Release raster tiles and detach the layer from terrain and the 3D scene.
+ *
+ * @param {L.Layer} layer Raster layer being removed.
+ * @param {L.Map} map Map containing the layer.
+ */
 export function onPMTileRemove(layer, map) {
   releaseRasterTiles(layer);
   terrain3DByLayer.set(layer, null);

package/src/raster/pruneRasterTiles.js

@@ -4,11 +4,15 @@ import { pruneWantedByLayer } from '../weakmaps/pruneWantedByLayer.js';
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
 import { wantedRasterTilesByLayer } from '../weakmaps/wantedRasterTilesByLayer.js';
-
-
-
 import { releaseRasterTile } from './releaseRasterTile.js';
 
+/**
+ * Release unwanted tiles once they no longer cover pending or fading wanted tiles.
+ *
+ * @param {L.Layer} layer Raster layer.
+ *
+ * @returns {boolean} Whether another prune is needed after a tile fade.
+ */
 export function pruneRasterTiles(layer) {
   const wanted = wantedRasterTilesByLayer.get(layer);
   const now = performance.now();

package/src/raster/pumpRasterTiles.js

@@ -1,13 +1,14 @@
 import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
-
 import { TILE_SIZE } from '../globals/TILE_SIZE.js';
-
-
-
 import { comparePendingTiles } from './comparePendingTiles.js';
 import { loadRasterTile } from './loadRasterTile.js';
 
+/**
+ * Start pending raster loads by zoom and distance, with at most four concurrent loads.
+ *
+ * @param {L.Layer} layer Raster layer.
+ */
 export function pumpRasterTiles(layer) {
   const map = layer._map;
   if (!map) return;

package/src/raster/rasterTileRange.js

@@ -3,6 +3,15 @@ import { TILE_RADIUS } from '../globals/TILE_RADIUS.js';
 import { archiveNorthWest } from '../globals/archiveNorthWest.js';
 import { archiveSouthEast } from '../globals/archiveSouthEast.js';
 
+/**
+ * Compute the visible tile range, clipped to archive bounds and the center tile radius.
+ *
+ * @param {L.Map} map Map providing the view bounds and projection.
+ * @param {Object} header Archive header with optional geographic bounds.
+ * @param {number} zoom Tile zoom level.
+ *
+ * @returns {Object} Inclusive minimum and maximum tile coordinates.
+ */
 export function rasterTileRange(map, header, zoom) {
   const bounds = map.getBounds();
   const northwest = map.project(bounds.getNorthWest(), zoom).divideBy(TILE_SIZE).floor();

package/src/raster/readyRaster.js

@@ -1,9 +1,14 @@
 import { headerByLayer } from '../weakmaps/headerByLayer.js';
-
-
-
 import { getHeader } from "../archives/getHeader.js";
 
+/**
+ * Read the raster archive header, set zoom defaults and emit the ready event.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} archive Archive to inspect.
+ *
+ * @returns {Promise<L.Layer>} The initialized layer.
+ */
 export async function readyRaster(layer, archive) {
   const header = await getHeader(archive);
   layer.options.archive = archive;

package/src/raster/registerTerrainTile.js

@@ -1,10 +1,16 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { addRasterTile } from './addRasterTile.js';
 
+/**
+ * Register a current loaded raster tile with its terrain layer, reporting attachment errors.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} coords Tile coordinates.
+ * @param {Object} tile Loaded raster tile.
+ *
+ * @returns {Promise<void>} Completion of the registration attempt.
+ */
 export async function registerTerrainTile(layer, coords, tile) {
   if (terrain3DByLayer.get(layer) && tile.done && !tile.request.signal.aborted &&
     rasterTilesByLayer.get(layer).get(`${coords.z}/${coords.x}/${coords.y}`) === tile) {

package/src/raster/releaseRasterTile.js

@@ -1,14 +1,17 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { removeRasterTile } from './removeRasterTile.js';
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Abort and remove a current raster tile, detaching its meshes and releasing its image and texture.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} tile Tile to release.
+ */
 export function releaseRasterTile(layer, tile) {
   const key = `${tile.coords.z}/${tile.coords.x}/${tile.coords.y}`;
   if (rasterTilesByLayer.get(layer).get(key) !== tile) return;

package/src/raster/releaseRasterTiles.js

@@ -1,12 +1,14 @@
 import { rasterGeometryByLayer } from '../weakmaps/rasterGeometryByLayer.js';
 import { rasterProgramByLayer } from '../weakmaps/rasterProgramByLayer.js';
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
-
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { releaseRasterTile } from './releaseRasterTile.js';
 
+/**
+ * Release all raster tiles and their shared program and geometry resources.
+ *
+ * @param {L.Layer} layer Raster layer.
+ */
 export function releaseRasterTiles(layer) {
   let tile, attribute;
   for (tile of rasterTilesByLayer.get(layer).values()) releaseRasterTile(layer, tile);

package/src/raster/removeRasterTile.js

@@ -1,12 +1,15 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { terrainRequestByLayer } from '../weakmaps/terrainRequestByLayer.js';
-
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Remove a raster tile's terrain mesh and abort the terrain request.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {Object} tile Raster tile used as the mesh key.
+ */
 export function removeRasterTile(layer, tile) {
   terrainRequestByLayer.get(layer)?.abort();
   const mesh = rasterTilesByLayer.get(layer).get(tile);

package/src/raster/reportRasterError.js

@@ -1,5 +1,13 @@
 
 
+/**
+ * Emit a raster layer error and propagate it to the caller.
+ *
+ * @param {L.Layer} layer Layer receiving the error event.
+ * @param {Error} error Error to report.
+ *
+ * @throws {Error} The supplied error.
+ */
 export function reportError(layer, error) {
   layer.fire('error', /* alloc */ { error });
   throw error;

package/src/raster/retainRasterTiles.js

@@ -1,7 +1,12 @@
-import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
-
+import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { releaseRasterTile } from './releaseRasterTile.js';
 
+/**
+ * Cancel unneeded unfinished tiles and create state for missing required tiles.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Map<string, Object>} required Required tile coordinates by key.
+ */
 export function retainRasterTiles(layer, required) {
   const tiles = rasterTilesByLayer.get(layer);
   let key, tile, coords;

package/src/raster/setPMTileOpacity.js

@@ -1,5 +1,13 @@
 import { setRasterOpacity } from './setRasterOpacity.js';
 
+/**
+ * Set raster layer opacity and update its existing meshes.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {number} opacity New opacity.
+ *
+ * @returns {L.Layer} The updated layer.
+ */
 export function setPMTileOpacity(layer, opacity) {
   layer.options.opacity = opacity;
   setRasterOpacity(layer, opacity);

package/src/raster/setPMTileZIndex.js

@@ -1,5 +1,13 @@
 import { setRasterZIndex } from './setRasterZIndex.js';
 
+/**
+ * Set raster layer z-index and update its existing meshes.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {number} zIndex New rendering order.
+ *
+ * @returns {L.Layer} The updated layer.
+ */
 export function setPMTileZIndex(layer, zIndex) {
   layer.options.zIndex = zIndex;
   setRasterZIndex(layer, zIndex);

package/src/raster/setRasterOpacity.js

@@ -1,10 +1,13 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Update opacity on the layer's raster and terrain meshes.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {number} opacity New opacity.
+ */
 export function setRasterOpacity(layer, opacity) {
   let tile, terrainMesh;
   for (tile of rasterTilesByLayer.get(layer).values()) {

package/src/raster/setRasterTerrain.js

@@ -1,13 +1,16 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { removeRasterTile } from './removeRasterTile.js';
 import { setParent } from '../scene/setParent.js';
 import { registerTerrainTile } from './registerTerrainTile.js';
 
+/**
+ * Rebind raster tiles to the selected terrain, or restore their flat meshes when detached.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {L.Layer|null} terrain Terrain layer, or null to detach it.
+ */
 export function setRasterTerrain(layer, terrain) {
   // Pending sources bind the current terrain when their raster attachment is ready.
   if (!rasterTilesByLayer.get(layer) || terrain3DByLayer.get(layer) === terrain) return;

package/src/raster/setRasterZIndex.js

@@ -1,10 +1,13 @@
 import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { terrain3DByLayer } from '../weakmaps/terrain3DByLayer.js';
-
-
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Update rendering order on the layer's raster and terrain meshes.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {number} zIndex New rendering order.
+ */
 export function setRasterZIndex(layer, zIndex) {
   let tile, terrainMesh;
   for (tile of rasterTilesByLayer.get(layer).values()) {

package/src/raster/updateAttachedTiles.js

@@ -1,9 +1,15 @@
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
-
-
-
 import { updateRasterTiles } from "./updateRasterTiles.js";
 
+/**
+ * Update tiles once scene attachment and archive initialization finish, reporting errors.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {L.Map} map Map to which the layer was attached.
+ * @param {Promise} attached Shared scene attachment.
+ *
+ * @returns {Promise<void>} Completion of the update attempt.
+ */
 export async function updateAttachedTiles(layer, map, attached) {
   try {
     await Promise.all(/* alloc */ [attached, readyByLayer.get(layer)]);

package/src/raster/updateRasterTiles.js

@@ -3,20 +3,20 @@ import { rasterTilesByLayer } from '../weakmaps/rasterTilesByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { tileZoomByLayer } from '../weakmaps/tileZoomByLayer.js';
 import { wantedRasterTilesByLayer } from '../weakmaps/wantedRasterTilesByLayer.js';
-
 import { wantedTiles } from '../globals/wantedTiles.js';
 import { coverageTiles } from '../globals/coverageTiles.js';
-
-
-
 import { pumpRasterTiles } from './pumpRasterTiles.js';
-
 import { retainRasterTiles } from './retainRasterTiles.js';
 import { pruneRasterTiles } from './pruneRasterTiles.js';
 import { rasterTileRange } from './rasterTileRange.js';
 
 // ponytail: cap horizon views at 169 tiles; raise the radius if extreme pitches need more.
 
+/**
+ * Update visible and fallback raster tiles for the current map view.
+ *
+ * @param {L.Layer} layer Raster layer.
+ */
 export function updateRasterTiles(layer) {
   const map = layer._map;
   if (!map || !sharedByLayer.get(layer) || !headerByLayer.get(layer)) return;

package/src/rendering/README.md

@@ -0,0 +1,32 @@
+# Rendering
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Owns mesh lifecycle and the shared renderer's frame stages: camera updates,
+mesh collection, uniforms, shadows, drawing and GPU submission.
+
+## One frame
+
+```mermaid
+flowchart LR
+  Frame["Scheduled frame"] --> View["Resize + zoom + camera"]
+  View --> World["World matrices + native sync"]
+  World --> Collect["Collect meshes + roof atlas"]
+  Collect --> Prepare["Prepare meshes + uniforms"]
+  Prepare --> Shadow["Shadow pass"]
+  Shadow --> Draw["Scene pass"]
+  Draw --> Submit["Submit GPU commands"]
+  Submit --> Prune["Prune raster / schedule next frame"]
+```
+
+Only the shared owner renders. [drawSceneMeshes.js](./drawSceneMeshes.js)
+selects winding from the world transform, rejects singular transforms and
+draws double-sided transparent non-native meshes in two passes. Buffers,
+programs and textures have different lifetimes; see
+[disposeMesh.js](./disposeMesh.js) and [textures](../textures/README.md).
+
+- [render.js](./render.js): orchestrate a frame.
+- [createMesh.js](./createMesh.js) and [disposeMesh.js](./disposeMesh.js): manage mesh resources.
+- [drawSceneMeshes.js](./drawSceneMeshes.js): issue scene draw commands.
+
+Related: [gpu](../gpu/README.md), [materials](../materials/README.md), [shadows](../shadows/README.md).

package/src/rendering/collectFrameMeshes.js

@@ -3,12 +3,16 @@ import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
 import { shadowMeshesByLayer } from '../weakmaps/shadowMeshesByLayer.js';
 import { visibleMeshesByLayer } from '../weakmaps/visibleMeshesByLayer.js';
-
-
-
 import { updateWorldMatrix } from "../transforms/updateWorldMatrix.js";
 import { collectMeshes } from './collectMeshes.js';
 
+/**
+ * Refresh the camera frustum and collect visible and shadow-casting scene meshes.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} sunlight Current sunlight state, if available.
+ * @param {boolean} sceneChanged Whether scene world matrices need updating.
+ */
 export function collectFrameMeshes(layer, sunlight, sceneChanged) {
   const camera = cameraByLayer.get(layer);
   const projection = camera.projectionViewMatrix;

package/src/rendering/collectMeshes.js

@@ -1,5 +1,16 @@
 import { collectVisibleMesh } from './collectVisibleMesh.js';
 
+/**
+ * Traverse visible scene nodes, collecting camera-visible meshes and eligible shadow casters.
+ *
+ * @param {Object} mesh Scene node to visit.
+ * @param {Object} sunlight Current sunlight state, if available.
+ * @param {ArrayLike<number>} projection Camera projection-view matrix.
+ * @param {Array} frustum Camera frustum planes.
+ * @param {ArrayLike<number>} frustumLengths Lengths of the plane normals.
+ * @param {Array<Object>} candidates Destination for visible meshes.
+ * @param {Array<Object>} shadowMeshes Destination for shadow casters.
+ */
 export function collectMeshes(mesh, sunlight, projection, frustum, frustumLengths, candidates, shadowMeshes) {
   if (!mesh.visible) return;
   if (mesh.geometry) {

package/src/rendering/collectVisibleMesh.js

@@ -1,6 +1,15 @@
 import { computeBounds } from '../geometry/computeBounds.js';
 import { nativeStrokeExpansion } from './nativeStrokeExpansion.js';
 
+/**
+ * Cull a mesh against the camera frustum and append it when visible.
+ *
+ * @param {Object} mesh Mesh whose world-space bounding sphere is tested.
+ * @param {ArrayLike<number>} projection Camera projection-view matrix.
+ * @param {Array} frustum Camera frustum planes.
+ * @param {ArrayLike<number>} frustumLengths Lengths of the plane normals.
+ * @param {Array<Object>} candidates Destination for visible meshes.
+ */
 export function collectVisibleMesh(mesh, projection, frustum, frustumLengths, candidates) {
   if (!mesh.geometry.bounds) computeBounds(mesh.geometry);
   const bounds = mesh.geometry.bounds;

package/src/rendering/compareMeshDepth.js

@@ -1,3 +1,11 @@
+/**
+ * Order opaque meshes front-to-back and transparent meshes by render order and depth.
+ *
+ * @param {Object} a First mesh.
+ * @param {Object} b Second mesh.
+ *
+ * @returns {number} Sort comparison, breaking ties by mesh ID.
+ */
 export function compareMeshDepth(a, b) {
   return a.program.transparent
     ? (a.renderOrder || 0) - (b.renderOrder || 0) ||

package/src/rendering/compareMeshes.js

@@ -1,3 +1,13 @@
+import { compareMeshDepth } from './compareMeshDepth.js';
+
+/**
+ * Sort ground first, then opaque and transparent meshes with their depth ordering.
+ *
+ * @param {Object} a First mesh.
+ * @param {Object} b Second mesh.
+ *
+ * @returns {number} Sort comparison.
+ */
 export function compareMeshes(a, b) {
   return Number(Boolean(b.ground)) - Number(Boolean(a.ground)) ||
     (a.ground && b.ground ? (a.renderOrder || 0) - (b.renderOrder || 0) ||
@@ -5,4 +15,3 @@ export function compareMeshes(a, b) {
     Number(a.program.transparent) - Number(b.program.transparent) ||
     compareMeshDepth(a, b);
 }
-import { compareMeshDepth } from './compareMeshDepth.js';

package/src/rendering/createMesh.js

@@ -1,12 +1,8 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { defaultMaterial } from '../globals/defaultMaterial.js';
 import { meshBuffer } from '../globals/meshBuffer.js';
 import { nextId } from '../globals/nextId.js';
-
-
-
 import { emptyNode } from '../scene/createSceneNode.js';
 import { createProgram } from '../materials/createProgram.js';
 import { setParent } from '../scene/setParent.js';
@@ -16,8 +12,15 @@ import { update } from '../scene/scheduleSceneUpdate.js';
  * Add a non-indexed, vertex-coloured mesh from flat vec3 arrays `{ position, normal, color }` in layer-local metres.
  * `usage` adds GPUBufferUsage flags to the vertex buffers (e.g. STORAGE for compute passes).
  * A supplied `program` shares compiled shaders and pipelines across compatible meshes.
+ *
+ * @param {L.Layer} layer Rendering layer and mesh owner.
+ * @param {Object} data Flat vertex attribute arrays.
+ * @param {Object} [material] Material options for a new program.
+ * @param {number} [usage] Additional vertex buffer usage flags.
+ * @param {Object} [program] Existing program to share.
+ *
+ * @returns {Object} Created scene mesh.
  */
-
 export function createMesh(layer, data, material = defaultMaterial, usage = 0, program) {
   const { device } = rendererByLayer.get(layer), attributes = /* alloc */ {};
   let name, values, array, size, buffer;

package/src/rendering/disposeMesh.js

@@ -1,6 +1,12 @@
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Detach a mesh and destroy its geometry buffers.
+ *
+ * @param {L.Layer} layer Layer to refresh.
+ * @param {Object} mesh Mesh to dispose, if present.
+ */
 export function disposeMesh(layer, mesh) {
   if (!mesh) {
     return;

package/src/rendering/drawGeometry.js

@@ -1,11 +1,18 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { meshOffsets } from '../globals/meshOffsets.js';
 import { drawPipeline } from './drawPipeline.js';
 import { prepareMeshUniforms } from './prepareMeshUniforms.js';
 import { prepareMeshTextures } from '../textures/prepareMeshTextures.js';
 
-/** Upload retained CPU data and draw one mesh in the active WebGPU render pass. */
+/**
+ * Upload modified CPU attributes and draw one mesh in the active WebGPU render pass.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} mesh Mesh to draw.
+ * @param {GPURenderPassEncoder} pass Active render pass.
+ * @param {GPUCullMode} cullMode Pipeline face-culling mode.
+ * @param {GPUFrontFace} frontFace Pipeline front-face winding.
+ */
 export function drawGeometry(layer, mesh, pass, cullMode, frontFace) {
   const { geometry } = mesh, { attributes, drawRange } = geometry;
   const renderer = rendererByLayer.get(layer);

package/src/rendering/drawPipeline.js

@@ -1,6 +1,16 @@
 import { meshPipeline } from '../globals/meshPipeline.js';
 import { alphaBlend } from '../globals/alphaBlend.js';
 
+/**
+ * Get or create a cached render pipeline for a mesh and its face/depth settings.
+ *
+ * @param {Object} renderer Renderer providing the device and color format.
+ * @param {Object} mesh Mesh providing the program and ground flag.
+ * @param {GPUCullMode} cullMode Face-culling mode.
+ * @param {GPUFrontFace} frontFace Front-face winding.
+ *
+ * @returns {GPURenderPipeline} Cached or newly created pipeline.
+ */
 export function drawPipeline(renderer, mesh, cullMode, frontFace) {
   const { program } = mesh;
   // Mixed-LOD imagery composites coarse-to-fine; its depth still occludes later 3D objects.

package/src/rendering/drawSceneMeshes.js

@@ -1,11 +1,17 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
-
 import { scenePass } from '../globals/scenePass.js';
-
-
 import { drawGeometry } from './drawGeometry.js';
 
+/**
+ * Encode the scene render pass, including both faces of double-sided transparent meshes.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the pass.
+ * @param {Array<Object>} meshes Sorted meshes to draw.
+ *
+ * @throws {Error} If a mesh has a singular or non-finite world transform.
+ */
 export function drawSceneMeshes(layer, encoder, meshes) {
   const renderer = rendererByLayer.get(layer);
   const pass = encoder.beginRenderPass((