leaflet-city-mapper 0.0.9 → 0.1.0

package/src/layer-controls/runPlacements.js

@@ -1,8 +1,7 @@
 import { pendingPlacements } from '../globals/pendingPlacements.js';
-
-
 import { placeUnderEntry } from './placeUnderEntry.js';
 
+/** Place the next queued element if its layer is still on the map. */
 export function runPlacements() {
   const state = pendingPlacements.shift();
   if (state?.map.hasLayer(state.layer)) placeUnderEntry(state);

package/src/layer-controls/underEntry.js

@@ -5,9 +5,13 @@ import { removeEntry } from './removeEntry.js';
 
 /**
  * Keeps `element` right under `layer`'s entry in the map's layers control while the layer is on the map.
- * Returns false when no layers control lists the layer.
+ *
+ * @param {L.Layer} layer Layer whose entry should contain the element.
+ * @param {HTMLElement} element Element to place.
+ * @param {Function} [onPlace] Callback receiving whether placement succeeded.
+ *
+ * @returns {boolean} False when no layers control lists the layer.
  */
-
 export function underEntry(layer, element, onPlace) {
   const state = /* alloc */ { map: layer._map, layer, element, onPlace };
   state.map.on('layeradd layerremove', replaceEntry, state);

package/src/layer-controls/updateLayerCount.js

@@ -1,9 +1,13 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
 import { countStatusByLayer } from '../weakmaps/countStatusByLayer.js';
-
 import { underEntry } from './underEntry.js';
 import { renderLayerCount } from './renderLayerCount.js';
 
+/**
+ * Collect loaded and pending counts from an event or layer areas and refresh the status.
+ *
+ * @param {Object} event Layer event containing the target and optional loading counts.
+ */
 export function updateLayerCount(event) {
   const layer = event.target, status = countStatusByLayer.get(layer)
   if (!layer._map) return;

package/src/lighting/README.md

@@ -0,0 +1,28 @@
+# Lighting
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Collects point lights from visible scene layers and maintains spatial grids for
+fixed and moving lights. Grid data is uploaded for the shared renderer.
+
+## Point-light grids
+
+```mermaid
+flowchart LR
+  Layers["Visible nightLight layers"] --> Collect["Collect world-space lights"]
+  Collect --> Fixed["Fixed grid"]
+  Collect --> Moving["Moving grid"]
+  Fixed --> Buffer["Shared GPU storage buffer"]
+  Moving --> Buffer
+  Buffer --> Shader["Nearby-light lookup"]
+```
+
+Grids use 32-metre cells. If their data exceeds the GPU storage limit, the
+update throws; buffer growth also refreshes bindings. Directional sunlight uses
+separate [shadows](../shadows/README.md).
+
+- [updatePointLights.js](./updatePointLights.js): collect, cache and upload light grids.
+- [lightGrid.js](./lightGrid.js): build a spatial light grid.
+- [worldLights.js](./worldLights.js): transform lights into world coordinates.
+
+Related: [shadows](../shadows/README.md), [sunlight](../sunlight/README.md), [rendering](../rendering/README.md).

package/src/lighting/cacheLightGrid.js

@@ -1,7 +1,15 @@
 import { lightGrid } from './lightGrid.js';
 import { worldLights } from './worldLights.js';
 
-/** Keep fixed lamps cached when moving headlights change. */
+/**
+ * Reuse a light grid when its meshes and world-space light snapshots are unchanged.
+ *
+ * @param {Object[]} meshes Meshes containing point lights.
+ * @param {Object} [previous] Previous grid and mesh snapshots, if any.
+ * @param {number} maxBytes Maximum GPU storage size in bytes.
+ *
+ * @returns {Object} Reused or rebuilt light grid and snapshots.
+ */
 export function cacheLightGrid(meshes, previous, maxBytes) {
   let unchanged = previous?.meshes.length === meshes.length;
   let i, mesh, matrix, lights, cache, sameMatrix, j;

package/src/lighting/collectLightMeshes.js

@@ -1,6 +1,12 @@
 import { geometryEmpty } from '../globals/geometryEmpty.js';
 
-
+/**
+ * Collect visible nodes with lights into fixed and moving mesh lists.
+ *
+ * @param {Object} node Scene node to visit.
+ * @param {Object[]} fixed Output list for fixed lights.
+ * @param {Object[]} moving Output list for dynamic lights.
+ */
 export function collectLightMeshes(node, fixed, moving) {
   if (!node.visible) return;
   if (node.extras?.lights) (node.extras.dynamicLights ? moving : fixed).push(node);

package/src/lighting/lightGrid.js

@@ -1,6 +1,15 @@
 import { visitCells } from './visitLightGridCells.js';
 
-/** Pack world-space point lights into the shader's spatial grid. */
+/**
+ * Pack world-space point lights into the shader's spatial grid.
+ *
+ * @param {Float32Array[]} packed Arrays of world-space light records.
+ * @param {number} maxBytes Maximum GPU storage size in bytes.
+ *
+ * @returns {Object} Packed grid data and light count.
+ *
+ * @throws {Error} If the grid exceeds the GPU storage limit.
+ */
 export function lightGrid(packed, maxBytes) {
   let count = 0;
   let values, i, value, key;

package/src/lighting/updatePointLights.js

@@ -1,14 +1,18 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { bindSunlight } from '../shadows/bindSunlight.js';
 import { cacheLightGrid } from './cacheLightGrid.js';
 import { collectLightMeshes } from './collectLightMeshes.js';
 
+/**
+ * Cache and upload fixed and moving point-light grids for the shared renderer.
+ *
+ * @param {L.Layer} layer Layer owning the shared renderer.
+ *
+ * @throws {Error} If the combined grids exceed the GPU storage limit.
+ */
 export function updatePointLights(layer) {
   const { device, sunlight: sun } = rendererByLayer.get(layer);
   const fixed = /* alloc */ [];

package/src/lighting/visitLightCells.js

@@ -1,3 +1,17 @@
+import { writeLightCell } from './writeLightCell.js';
+
+/**
+ * Count or write a light into each spatial grid cell covered by its radius.
+ *
+ * @param {Float32Array} values Packed light records.
+ * @param {number} i Starting index of the light record.
+ * @param {number} minX Grid origin on the x axis.
+ * @param {number} minZ Grid origin on the z axis.
+ * @param {number} cellSize Grid cell width.
+ * @param {number} columns Number of grid columns.
+ * @param {Uint32Array} offsets Per-cell counts or write offsets.
+ * @param {Float32Array} [data] Output grid data; omitted during counting.
+ */
 export function visitLightCells(values, i, minX, minZ, cellSize, columns, offsets, data) {
   const radius = values[i + 3], x = values[i] - minX, z = values[i + 2] - minZ;
   let y, c, key;
@@ -10,4 +24,3 @@ export function visitLightCells(values, i, minX, minZ, cellSize, columns, offset
     }
   }
 }
-import { writeLightCell } from './writeLightCell.js';

package/src/lighting/visitLightGridCells.js

@@ -1,5 +1,16 @@
 import { visitLightCells } from './visitLightCells.js';
 
+/**
+ * Visit covered grid cells for every packed light.
+ *
+ * @param {Float32Array[]} packed Arrays of packed light records.
+ * @param {number} minX Grid origin on the x axis.
+ * @param {number} minZ Grid origin on the z axis.
+ * @param {number} cellSize Grid cell width.
+ * @param {number} columns Number of grid columns.
+ * @param {Uint32Array} offsets Per-cell counts or write offsets.
+ * @param {Float32Array} [data] Output grid data; omitted during counting.
+ */
 export function visitCells(packed, minX, minZ, cellSize, columns, offsets, data) {
   let values, i;
   for (values of packed) for (i = 0; i < values.length; i += 8) {

package/src/lighting/worldLights.js

@@ -1,6 +1,13 @@
 import { lightScale } from '../globals/lightScale.js';
 
-/** World-space [x, y, z, radius, r, g, b, intensity] for one mesh's point lights. */
+/**
+ * Transform a mesh's point lights to world-space packed records.
+ *
+ * @param {Object[]} lights Local point lights.
+ * @param {number[]|Float32Array} m Column-major world matrix.
+ *
+ * @returns {Float32Array} Records of [x, y, z, radius, r, g, b, intensity].
+ */
 export function worldLights(lights, m) {
   const values = /* alloc */ new Float32Array(lights.length * 8);
   let i, x, y, z, radius, color, flux, w;

package/src/lighting/writeLightCell.js

@@ -1,3 +1,12 @@
+/**
+ * Copy a packed light record into a cell and advance that cell's write offset.
+ *
+ * @param {Float32Array} values Packed light records.
+ * @param {number} i Starting index of the light record.
+ * @param {number} key Grid cell index.
+ * @param {Uint32Array} offsets Per-cell write offsets in vec4 units.
+ * @param {Float32Array} data Output grid data.
+ */
 export function writeLightCell(values, i, key, offsets, data) {
   let j, o;
   for (j = 0, o = offsets[key] * 4; j < 8; j++) data[o + j] = values[i + j];

package/src/materials/README.md

@@ -0,0 +1,28 @@
+# Materials
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Builds GPU material programs, layouts and uniforms, converts model materials,
+and handles terrain and roof material requirements.
+
+## Material to GPU program
+
+```mermaid
+flowchart LR
+  Model["glTF material"] --> Convert["Convert material"]
+  Convert --> Features["Material features"]
+  Features --> WGSL["Generate WGSL + bindings"]
+  Features --> Layout["Program layout + uniforms"]
+  WGSL --> Program["GPU program / pipeline cache"]
+  Layout --> Program
+  Textures["Texture uploads"] --> Program
+```
+
+Shader declarations, binding order, uniforms and mesh attributes must agree.
+Compilation diagnostics are reported through [gpu](../gpu/README.md).
+
+- [createProgram.js](./createProgram.js): create a material program.
+- [createProgramLayout.js](./createProgramLayout.js): configure GPU bindings.
+- [modelMaterialFor.js](./modelMaterialFor.js): derive materials from model data.
+
+Related: [shaders](../shaders/README.md), [textures](../textures/README.md), [rendering](../rendering/README.md).

package/src/materials/createProgram.js

@@ -1,5 +1,4 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { defaultMaterial } from '../globals/defaultMaterial.js';
 import { vertexShader } from '../globals/vertexShader.js';
 import { fragmentShader } from '../globals/fragmentShader.js';
@@ -12,12 +11,17 @@ import { uVLayout } from '../globals/uVLayout.js';
 import { instanceLayout } from '../globals/instanceLayout.js';
 import { createProgramLayout } from './createProgramLayout.js';
 import { createProgramUniforms } from './createProgramUniforms.js';
-
-
 import { materialShaders } from '../shaders/materialShaders.js';
-
 import { reportCompilation } from '../gpu/reportShaderCompilation.js';
 
+/**
+ * Create shader modules, layouts and uniforms for a layer material.
+ *
+ * @param {L.Layer} layer Layer providing the renderer and shader options.
+ * @param {Object} [material] Material options.
+ *
+ * @returns {Object} Program state and pipeline cache.
+ */
 export function createProgram(layer, material = defaultMaterial) {
   const renderer = rendererByLayer.get(layer), { device } = renderer;
   const shaders = materialShaders(

package/src/materials/createProgramLayout.js

@@ -6,6 +6,14 @@ import { terrainLayoutEntry } from '../globals/terrainLayoutEntry.js';
 import { textureLayoutEntries } from '../globals/textureLayoutEntries.js';
 import { samplerLayoutEntries } from '../globals/samplerLayoutEntries.js';
 
+/**
+ * Create a bind group layout for mesh, frame, terrain and shader texture bindings.
+ *
+ * @param {GPUDevice} device Device creating the layout.
+ * @param {Object} shaders Shader bindings and terrain requirements.
+ *
+ * @returns {GPUBindGroupLayout} The created layout.
+ */
 export function createProgramLayout(device, shaders) {
   const bindGroupEntries = programEntries;
   bindGroupEntries.length = 0;

package/src/materials/createProgramUniforms.js

@@ -1,3 +1,10 @@
+/**
+ * Create material uniform values and add bindings for configured textures.
+ *
+ * @param {Object} material Material properties.
+ *
+ * @returns {Object} Uniform values keyed by shader property.
+ */
 export function createProgramUniforms(material) {
   const uniforms = /* alloc */ {
     baseColor: /* alloc */ { value: material.color || /* alloc */ [1, 1, 1] },

package/src/materials/modelMaterialFor.js

@@ -1,5 +1,13 @@
 import { textureFor } from '../textures/modelTextureFor.js';
 
+/**
+ * Translate a glTF material into renderer material properties and texture bindings.
+ *
+ * @param {Object} context Model loading context and backend layer.
+ * @param {Object} material glTF material definition.
+ *
+ * @returns {Object} Renderer material properties.
+ */
 export function materialFor(context, material) {
   const { backend: layer } = context;
   const pbr = material.pbrMetallicRoughness;

package/src/materials/prepareMeshCutout.js

@@ -1,3 +1,12 @@
+/**
+ * Validate and write native or raster cutout settings into the mesh uniform buffer.
+ *
+ * @param {Object} renderer Renderer containing uniform data and pixel ratio.
+ * @param {Object} mesh Mesh with optional native or raster source.
+ * @param {number} base Starting index in the uniform array.
+ *
+ * @throws {Error} If cutout coordinates or radius are invalid.
+ */
 export function prepareMeshCutout(renderer, mesh, base) {
   const data = renderer.uniformData;
   const cutout = (mesh._nativeSource || mesh._rasterSource)?.options.cutout;

package/src/materials/terrainRasterProgram.js

@@ -1,11 +1,10 @@
-import { demByLayer } from '../weakmaps/demByLayer.js';
-import { rasterProgramByLayer } from '../weakmaps/rasterProgramByLayer.js';
-import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-import { terrainBoundsByLayer } from '../weakmaps/terrainBoundsByLayer.js';
-import { terrainGridsByLayer } from '../weakmaps/terrainGridsByLayer.js';
-import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevationByLayer.js';
-import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
-
+import { demByLayer } from '../weakmaps/demByLayer.js';
+import { rasterProgramByLayer } from '../weakmaps/rasterProgramByLayer.js';
+import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
+import { terrainBoundsByLayer } from '../weakmaps/terrainBoundsByLayer.js';
+import { terrainGridsByLayer } from '../weakmaps/terrainGridsByLayer.js';
+import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevationByLayer.js';
+import { terrainTilesByLayer } from '../weakmaps/terrainTilesByLayer.js';
 import { demTexture } from '../globals/demTexture.js';
 import { demTarget } from '../globals/demTarget.js';
 import { demLayout } from '../globals/demLayout.js';
@@ -14,6 +13,14 @@ import { createProgram } from './createProgram.js';
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { terrainAtlas } from '../terrain/terrainAtlas.js';
 
+/**
+ * Reuse the current terrain raster program or create it with an uploaded elevation atlas.
+ *
+ * @param {L.Layer} layer Layer providing terrain and renderer state.
+ * @param {Object} texture Raster texture used by the program.
+ *
+ * @returns {Object} Terrain raster program.
+ */
 export function rasterProgram(layer, texture) {
   const device = rendererByLayer.get(layer).device
   if (rasterProgramByLayer.get(layer)?.device === device) return rasterProgramByLayer.get(layer);

package/src/materials/validateRoofMaterial.js

@@ -1,3 +1,10 @@
+/**
+ * Validate the optional roof and wall texture material settings.
+ *
+ * @param {Object} material Material containing texture settings.
+ *
+ * @throws {Error} If a texture setting is not a boolean or a finite number from 0 to 1.
+ */
 export function validateRoofMaterial(material) {
   let name, value;
   for (name of /* alloc */ ['roofTexture', 'wallTexture']) {

package/src/models/README.md

@@ -0,0 +1,27 @@
+# Models
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Loads static GLB/glTF resources, decodes model attributes and builds scene nodes.
+Model loading uses a source worker before attaching nodes to the layer.
+
+## Loading and attachment
+
+```mermaid
+flowchart LR
+  Added["Layer added"] --> Worker["Worker: decode glTF / GLB + resources"]
+  Worker --> View["Wait for camera view"]
+  View --> Nodes["Build nodes, geometry and materials"]
+  Nodes --> Transform["Apply layer transform"]
+  Transform --> Attach["Attach to layer root"]
+  Attach --> Terrain["Optional terrain conformance"]
+```
+
+Missing scenes and empty root lists are errors. For misplaced models, inspect
+node and layer [transforms](../transforms/README.md) before projection.
+
+- [loadModel.js](./loadModel.js): load, attach and optionally conform a model to terrain.
+- [decodeModel.js](./decodeModel.js): decode model content.
+- [buildModelNodes.js](./buildModelNodes.js): assemble model scene nodes.
+
+Related: [workers](../workers/README.md), [materials](../materials/README.md), [transforms](../transforms/README.md).

package/src/models/applyModelTransform.js

@@ -1,6 +1,10 @@
-import { modelByLayer } from '../weakmaps/modelByLayer.js';
-
+import { modelByLayer } from '../weakmaps/modelByLayer.js';
 
+/**
+ * Apply the layer's optional rotation and scale to its model.
+ *
+ * @param {L.Layer} layer Layer containing the transform options.
+ */
 export function applyModelTransform(layer) {
   const model = modelByLayer.get(layer);
   if (layer.options.rotation) {

package/src/models/buildModelNodes.js

@@ -1,6 +1,16 @@
 import { modelNode } from './modelNode.js';
 import { releaseModelResources } from './releaseModelResources.js';
 
+/**
+ * Build scene roots, releasing allocated resources if node construction fails.
+ *
+ * @param {Object} context Model construction context.
+ * @param {Object} scene glTF scene containing root node indices.
+ *
+ * @returns {Array<Object>} Built root nodes.
+ *
+ * @throws {Error} If building a node fails.
+ */
 export function buildModelNodes(context, scene) {
   const nodes = /* alloc */ [];
   let index;

package/src/models/createModelContext.js

@@ -1,6 +1,15 @@
 import { geometryEmpty } from '../globals/geometryEmpty.js';
 import { materialFor } from '../materials/modelMaterialFor.js';
 
+/**
+ * Create the model construction context and prepare its materials.
+ *
+ * @param {L.Layer} layer Rendering backend for the model.
+ * @param {Object} description Decoded glTF document.
+ * @param {Array} images Loaded model images.
+ *
+ * @returns {Object} Context containing materials, textures and tracked resources.
+ */
 export function createModelContext(layer, description, images) {
   const context = /* alloc */ {
     backend: layer, description, images,

package/src/models/decodeModel.js

@@ -1,8 +1,19 @@
 import { geometryDecoder } from '../globals/geometryDecoder.js';
-/** Decode a static glTF JSON document or GLB v2 container. */
 import { hasUnsupportedPrimitives } from './hasUnsupportedPrimitives.js';
 
-
+/**
+ * Decode a static glTF JSON document or GLB v2 container.
+ *
+ * @param {ArrayBuffer} data Encoded glTF or GLB data.
+ *
+ * @returns {Object} Decoded glTF document.
+ *
+ * @throws {Error} If the GLB header is invalid.
+ * @throws {Error} If a GLB chunk header is truncated.
+ * @throws {Error} If GLB chunk data is truncated.
+ * @throws {Error} If the GLB JSON chunk is missing.
+ * @throws {Error} If the model uses unsupported glTF features.
+ */
 export function decodeModel(data) {
   const view = /* alloc */ new DataView(data);
   const decoder = geometryDecoder;

package/src/models/hasUnsupportedPrimitives.js

@@ -1,3 +1,10 @@
+/**
+ * Check whether any mesh uses morph targets or a non-triangle primitive mode.
+ *
+ * @param {Array<Object>} meshes glTF meshes, if present.
+ *
+ * @returns {boolean} Whether unsupported primitives were found.
+ */
 export function hasUnsupportedPrimitives(meshes) {
   if (!meshes) return false;
   let mesh, primitive;

package/src/models/loadBuffer.js

@@ -1,3 +1,13 @@
+/**
+ * Fetch a glTF buffer into its binary property unless already loaded.
+ *
+ * @param {Object} buffer Buffer description and URI.
+ * @param {string} directory Base URL for the buffer URI.
+ *
+ * @returns {Promise<void>} Completion of the buffer load.
+ *
+ * @throws {Error} If the buffer response is not successful.
+ */
 export async function loadBuffer(buffer, directory) {
   if (buffer.binary) return;
   const response = await fetch(/* alloc */ new URL(buffer.uri, directory).href);

package/src/models/loadModel.js

@@ -4,9 +4,6 @@ import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
 import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
-
 import { runSourceWorker } from '../workers/runSourceWorker.js';
 import { setParent } from '../scene/setParent.js';
 import { emptyNode } from '../scene/createSceneNode.js';
@@ -15,10 +12,16 @@ import { createModelContext } from './createModelContext.js';
 import { buildModelNodes } from './buildModelNodes.js';
 import { applyModelTransform } from './applyModelTransform.js';
 
-
-/** glTF/GLB model loading. */
-/** Load the configured GLB/glTF (static triangles) under `root`; GPU resources need attachment. */
-
+/**
+ * Load the configured static GLB/glTF model, attach it to the layer and conform it to terrain.
+ *
+ * @param {L.Layer} layer Layer that owns the model and its scene root.
+ *
+ * @returns {Promise<void>} Completion of the model load.
+ *
+ * @throws {Error} If the glTF scene is missing.
+ * @throws {Error} If the glTF scene has no root nodes.
+ */
 export async function loadModel(layer) {
   await addedByLayer.get(layer).promise;
   const url = /* alloc */ new URL(modelUrlByLayer.get(layer), document.baseURI).href;

package/src/models/loadModelResources.js

@@ -2,6 +2,14 @@ import { geometryEmpty } from '../globals/geometryEmpty.js';
 import { loadBuffer } from './loadBuffer.js';
 import { loadImage } from '../textures/loadModelImage.js';
 
+/**
+ * Load the buffers and images referenced by a decoded glTF document.
+ *
+ * @param {Object} description Decoded glTF document.
+ * @param {string} directory Base URL for resource URIs.
+ *
+ * @returns {Promise<Array>} Loaded images.
+ */
 export async function loadModelResources(description, directory) {
   const bufferRequests = /* alloc */ [];
   let buffer;

package/src/models/modelNode.js

@@ -1,11 +1,21 @@
 import { nextId } from '../globals/nextId.js';
 import { geometryEmpty } from '../globals/geometryEmpty.js';
-
 import { emptyNode } from '../scene/createSceneNode.js';
 import { nodeMatrix } from '../transforms/modelNodeMatrix.js';
 import { setParent } from '../scene/setParent.js';
 import { createModelGeometry } from '../geometry/createModelGeometry.js';
 
+/**
+ * Recursively construct a scene node and its mesh primitives and children.
+ *
+ * @param {Object} context Model construction context.
+ * @param {number} index Index into the glTF nodes array.
+ *
+ * @returns {Object} Constructed scene node.
+ *
+ * @throws {Error} If the node forms a cycle.
+ * @throws {Error} If the node index is invalid.
+ */
 export function modelNode(context, index) {
   const { backend: layer, description, active } = context;
   // Track only the recursion path: shared mesh references are valid, cycles are not.

package/src/models/normalizeAccessor.js

@@ -1,3 +1,13 @@
+/**
+ * Convert integer accessor data to floats, applying glTF normalization when requested.
+ *
+ * @param {Object} spec glTF accessor specification.
+ * @param {TypedArrayConstructor} Type Integer component array constructor.
+ * @param {TypedArray} data Raw accessor components.
+ * @param {number} size Components per element.
+ *
+ * @returns {Object} Float data, element size and original integer data.
+ */
 export function normalizeAccessor(spec, Type, data, size) {
   const normalized = /* alloc */ new Float32Array(data.length);
   let i;

package/src/models/prepareModel.js

@@ -2,6 +2,16 @@ import { decodeModel } from './decodeModel.js';
 import { loadModelResources } from './loadModelResources.js';
 import { prepareModelGeometry } from './prepareModelGeometry.js';
 
+/**
+ * Fetch a static model and prepare its images and geometry for transfer from a worker.
+ *
+ * @param {string} url Model URL.
+ *
+ * @returns {Promise<Object>} Prepared description, images and transferables.
+ *
+ * @throws {Error} If the model response is not successful.
+ * @throws {Error} If the glTF scene is missing.
+ */
 export async function prepareModel(url) {
   const response = await fetch(url);
   if (!response.ok) throw /* alloc */ new Error(`Unable to load model: HTTP ${response.status}`);

package/src/models/prepareModelGeometry.js

@@ -1,6 +1,16 @@
 import { geometryEmpty } from '../globals/geometryEmpty.js';
 import { prepareModelPrimitive } from './prepareModelPrimitive.js';
 
+/**
+ * Prepare geometry for meshes reachable from the scene and collect their buffers.
+ *
+ * @param {Object} description Decoded glTF document with loaded buffers.
+ * @param {Object} scene glTF scene containing root node indices.
+ *
+ * @returns {Array<ArrayBuffer>} Unique geometry buffers to transfer.
+ *
+ * @throws {Error} If a referenced node is invalid.
+ */
 export function prepareModelGeometry(description, scene) {
   const pending = scene.nodes.slice(), visited = /* alloc */ new Set();
   const meshes = /* alloc */ new Set(), transfers = /* alloc */ new Set();

package/src/models/prepareModelPrimitive.js

@@ -2,6 +2,14 @@ import { readModelAttributes } from './readModelAttributes.js';
 import { readModelIndices } from './readModelIndices.js';
 import { vertexNormals } from '../geometry/vertexNormals.js';
 
+/**
+ * Decode primitive attributes and indices, generating normals when absent.
+ *
+ * @param {Object} description Decoded glTF document with loaded buffers.
+ * @param {Object} primitive glTF mesh primitive to prepare.
+ *
+ * @returns {Object} Prepared attributes, also stored on the primitive.
+ */
 export function prepareModelPrimitive(description, primitive) {
   const { attributes, vertexCount } = readModelAttributes(description, primitive);
   readModelIndices(description, primitive, attributes, vertexCount);