leaflet-city-mapper 0.0.9 → 0.1.1

package/src/globals/roofShader.js

@@ -1,3 +1,8 @@
+/**
+ * Shader module descriptor for compositing roof tiles with opacity.
+ *
+ * @type {Object}
+ */
 export const roofShader = {
   code: /* wgsl */`
       @group(0) @binding(0) var source: texture_2d<f32>;

package/src/globals/roofSignatures.js

@@ -1 +1,6 @@
+/**
+ * Reusable list of raster layer signatures for roof atlas invalidation.
+ *
+ * @type {Array<string>}
+ */
 export const roofSignatures = [];

package/src/globals/roofSize.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable size for roof atlas bounds.
+ *
+ * @type {{x: number, y: number}}
+ */
 export const roofSize = {
   x: 1,
   y: 1

package/src/globals/roofTarget.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable image copy destination descriptor for roof raster tiles.
+ *
+ * @type {Object}
+ */
 export const roofTarget = {
   texture: null
 };

package/src/globals/roofTexture.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable RGBA texture descriptor for the roof raster atlas.
+ *
+ * @type {Object}
+ */
 export const roofTexture = {
   size: [null, null],
   format: 'rgba8unorm',

package/src/globals/roofTiles.js

@@ -1 +1,6 @@
+/**
+ * Reusable list of raster tiles used to rebuild a roof atlas.
+ *
+ * @type {Array}
+ */
 export const roofTiles = [];

package/src/globals/roundProfile.js

@@ -1,3 +1,8 @@
+/**
+ * Height and radius fractions defining round tree crowns.
+ *
+ * @type {Array<Array<number>>}
+ */
 export const roundProfile = [
   [0, 0],
   [0.35, 0.8],

package/src/globals/samplerLayoutEntries.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable sampler bind group layout entries for material textures.
+ *
+ * @type {Array<Object>}
+ */
 export const samplerLayoutEntries = [{
     binding: null,
     visibility: null,

package/src/globals/sceneCleanupFields.js

@@ -1 +1,6 @@
+/**
+ * Shared scene state fields cleared when a renderer owner is released.
+ *
+ * @type {Array<string>}
+ */
 export const sceneCleanupFields = ['_layers', '_sceneOrigin', '_size', '_zoomLevel', '_cursor'];

package/src/globals/sceneEmptyOptions.js

@@ -1 +1,6 @@
+/**
+ * Shared immutable empty options for scene layer initialization.
+ *
+ * @type {Object}
+ */
 export const sceneEmptyOptions = Object.freeze({});

package/src/globals/scenePass.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable render pass descriptor for the multisampled scene and depth attachments.
+ *
+ * @type {Object}
+ */
 export const scenePass = {
   colorAttachments: [{
     view: null,

package/src/globals/sceneSunlightUniforms.js

@@ -1,3 +1,8 @@
+/**
+ * Initial sunlight uniforms with an identity shadow matrix.
+ *
+ * @type {Float32Array}
+ */
 export const sceneSunlightUniforms = new Float32Array(20);
 sceneSunlightUniforms[0] = sceneSunlightUniforms[5] =
   sceneSunlightUniforms[10] = sceneSunlightUniforms[15] = 1;

package/src/globals/sceneTransferFields.js

@@ -1 +1,6 @@
+/**
+ * Shared scene state fields transferred when renderer ownership changes.
+ *
+ * @type {Array<string>}
+ */
 export const sceneTransferFields = ['_layers', '_sceneOrigin', '_size', '_zoomLevel', '_zoomTransitions', '_zoomView', '_cursor', '_roofRaster'];

package/src/globals/sceneWalkHandlers.js

@@ -1 +1,6 @@
+/**
+ * Map interaction handlers disabled while walking.
+ *
+ * @type {Array<string>}
+ */
 export const sceneWalkHandlers = ['dragging', 'keyboard', 'doubleClickZoom', 'boxZoom'];

package/src/globals/shadowBindGroup.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group descriptor for shadow mesh uniforms.
+ *
+ * @type {Object}
+ */
 export const shadowBindGroup = {
   layout: null,
   entries: [{

package/src/globals/shadowBounds.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable world-space bounds for shadow camera fitting.
+ *
+ * @type {Object}
+ */
 export const shadowBounds = {
   min: [0, 0, 0],
   max: [0, 0, 0]

package/src/globals/shadowCamera.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable camera and matrix state for sunlight shadow projection.
+ *
+ * @type {Object}
+ */
 export const shadowCamera = {
   position: [0, 0, 0],
   target: [0, 0, 0],

package/src/globals/shadowDepthLayout.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout descriptor for shadow depth uniforms.
+ *
+ * @type {Object}
+ */
 export const shadowDepthLayout = {
   entries: [{
     binding: 0,

package/src/globals/shadowHigh.js

@@ -1 +1,6 @@
+/**
+ * Reusable upper bounds vector for shadow camera calculations.
+ *
+ * @type {Array<number>}
+ */
 export const shadowHigh = [0, 0, 0];

package/src/globals/shadowInstanceLayouts.js

@@ -1,4 +1,9 @@
 import { positionLayout as sharedPositionLayout } from './positionLayout.js';
 import { instanceLayout as sharedInstanceLayout } from './instanceLayout.js';
 
+/**
+ * Vertex buffer layouts for instanced shadow meshes.
+ *
+ * @type {Array<Object>}
+ */
 export const shadowInstanceLayouts = [sharedPositionLayout, sharedInstanceLayout];

package/src/globals/shadowLayouts.js

@@ -1,3 +1,8 @@
 import { positionLayout as sharedPositionLayout } from './positionLayout.js';
 
+/**
+ * Vertex buffer layouts for non-instanced shadow meshes.
+ *
+ * @type {Array<Object>}
+ */
 export const shadowLayouts = [sharedPositionLayout];

package/src/globals/shadowLow.js

@@ -1 +1,6 @@
+/**
+ * Reusable lower bounds vector for shadow camera calculations.
+ *
+ * @type {Array<number>}
+ */
 export const shadowLow = [0, 0, 0];

package/src/globals/shadowMeshLayout.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout descriptor for dynamically offset shadow mesh uniforms.
+ *
+ * @type {Object}
+ */
 export const shadowMeshLayout = {
   entries: [{
     binding: 0,

package/src/globals/shadowOffsets.js

@@ -1 +1,6 @@
+/**
+ * Reusable dynamic mesh uniform offsets for shadow drawing.
+ *
+ * @type {Array<number|null>}
+ */
 export const shadowOffsets = [null];

package/src/globals/shadowPass.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth-only render pass descriptor for shadows.
+ *
+ * @type {Object}
+ */
 export const shadowPass = {
   colorAttachments: [],
   depthStencilAttachment: {

package/src/globals/shadowPipeline.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth render pipeline descriptor for shadow meshes.
+ *
+ * @type {Object}
+ */
 export const shadowPipeline = {
   layout: null,
   vertex: {

package/src/globals/shadowPipelineLayout.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable pipeline layout descriptor for shadow bind groups.
+ *
+ * @type {Object}
+ */
 export const shadowPipelineLayout = {
   bindGroupLayouts: [null, null]
 };

package/src/globals/shadowShader.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable shader module descriptor for generated shadow code.
+ *
+ * @type {Object}
+ */
 export const shadowShader = {
   code: null
 };

package/src/globals/shadowTexture.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable depth texture descriptor for the sunlight shadow map.
+ *
+ * @type {Object}
+ */
 export const shadowTexture = {
   size: [null, null],
   format: 'depth32float',

package/src/globals/shadowValues.js

@@ -1 +1,6 @@
+/**
+ * Reusable sunlight shadow matrix and parameter uniform data.
+ *
+ * @type {Float32Array}
+ */
 export const shadowValues = new Float32Array(20);

package/src/globals/shirt.js

@@ -1 +1,6 @@
+/**
+ * RGB shirt color for the shared walker model.
+ *
+ * @type {Array<number>}
+ */
 export const shirt = [0.75, 0.2, 0.15];

package/src/globals/sinObliquity.js

@@ -1,3 +1,8 @@
-import { radians } from './radians.js';
-
-export const sinObliquity = Math.sin(23.4397 * radians);
+import { radians } from './radians.js';
+
+/**
+ * Sine of Earth's axial obliquity used in celestial position calculations.
+ *
+ * @type {number}
+ */
+export const sinObliquity = Math.sin(23.4397 * radians);

package/src/globals/sizes.js

@@ -1,3 +1,8 @@
+/**
+ * Component counts for supported glTF accessor types.
+ *
+ * @type {Object<string, number>}
+ */
 export const sizes = {
   SCALAR: 1,
   VEC2: 2,

package/src/globals/skin.js

@@ -1,2 +1,7 @@
 // Pedestrian, about 1.77 m tall, prisms as in utils/vehicles.js (forward -z). Limbs hang from their pivot at y = 0.
+/**
+ * RGB skin color shared by walker and pedestrian models.
+ *
+ * @type {Array<number>}
+ */
 export const skin = [0.85, 0.64, 0.5];

package/src/globals/speed.js

@@ -1,3 +1,7 @@
 // Pure helpers of the 'traffic' type: lane interpolation and vehicle scheduling.
-/** Default urban speed (m/s) used to turn a lane's hourly `flow` into vehicles on the road. */
+/**
+ * Default urban speed in m/s used to turn a lane's hourly flow into vehicles on the road.
+ *
+ * @type {number}
+ */
 export const speed = 8;

package/src/globals/sunBindGroup.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group descriptor for sunlight uniforms, shadow texture and lights.
+ *
+ * @type {Object}
+ */
 export const sunBindGroup = {
   layout: null,
   entries: [{

package/src/globals/taillight.js

@@ -1 +1,6 @@
+/**
+ * Emissive red RGB color used for vehicle tail lights.
+ *
+ * @type {Array<number>}
+ */
 export const taillight = [1.7, 0.06, 0.05];

package/src/globals/tau.js

@@ -1 +1,6 @@
-export const tau = 2 * Math.PI;
+/**
+ * Full circle angle in radians.
+ *
+ * @type {number}
+ */
+export const tau = 2 * Math.PI;

package/src/globals/terrainLayoutEntry.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout entry for the elevation texture.
+ *
+ * @type {Object}
+ */
 export const terrainLayoutEntry = {
   binding: 2,
   visibility: null,

package/src/globals/textureLayoutEntries.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable bind group layout entries for material texture views.
+ *
+ * @type {Array<Object>}
+ */
 export const textureLayoutEntries = [{
     binding: null,
     visibility: null,

package/src/globals/tiledBounds.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original grid tiled pixel bounds method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tiledBounds = { value: undefined };

package/src/globals/tooltipEvents.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original tooltip event method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tooltipEvents = { value: undefined };

package/src/globals/tooltipPosition.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for Leaflet's original tooltip position method.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const tooltipPosition = { value: undefined };

package/src/globals/trafficClocks.js

@@ -1 +1,6 @@
+/**
+ * Cached timetable date formatters keyed by time zone.
+ *
+ * @type {Map<string, Intl.DateTimeFormat>}
+ */
 export const trafficClocks = new Map();

package/src/globals/trafficEmptyList.js

@@ -1 +1,6 @@
+/**
+ * Immutable empty feature list used when traffic data has no features.
+ *
+ * @type {ReadonlyArray}
+ */
 export const trafficEmptyList = Object.freeze([]);

package/src/globals/trafficEmptyOptions.js

@@ -1 +1,6 @@
+/**
+ * Immutable empty options used by traffic initialization and mesh creation.
+ *
+ * @type {Object}
+ */
 export const trafficEmptyOptions = Object.freeze({});

package/src/globals/trafficRouteMaterial.js

@@ -1 +1,6 @@
+/**
+ * Unlit material options for displayed traffic routes.
+ *
+ * @type {Object}
+ */
 export const trafficRouteMaterial = Object.freeze({ unlit: true });

package/src/globals/trafficShader.js

@@ -1,4 +1,8 @@
-// One workgroup per vehicle shares its lane lookup and pose across all model vertices.
+/**
+ * Compute shader for vehicle poses; one workgroup shares lane lookup across model vertices.
+ *
+ * @type {string}
+ */
 export const trafficShader = /* wgsl */`
   struct Params { seconds: f32, side: f32, vertices: u32, total: u32 }
   struct Vehicle { start: u32, count: u32, base: f32, speed: f32 }

package/src/globals/triangleContexts.js

@@ -1 +1,6 @@
+/**
+ * Stack of active triangle output contexts during tree geometry generation.
+ *
+ * @type {Array<Object>}
+ */
 export const triangleContexts = [];

package/src/globals/trousers.js

@@ -1 +1,6 @@
+/**
+ * RGB trousers color used by walker and pedestrian models.
+ *
+ * @type {Array<number>}
+ */
 export const trousers = [0.16, 0.2, 0.32];

package/src/globals/types.js

@@ -1,3 +1,8 @@
+/**
+ * Typed array constructors indexed by glTF accessor component type.
+ *
+ * @type {Object<number, Function>}
+ */
 export const types = {
   5120: Int8Array,
   5121: Uint8Array,

package/src/globals/tyre.js

@@ -1 +1,6 @@
+/**
+ * Dark RGB color for vehicle tyres.
+ *
+ * @type {Array<number>}
+ */
 export const tyre = [0.05, 0.05, 0.05];

package/src/globals/uVLayout.js

@@ -1,3 +1,8 @@
+/**
+ * WebGPU vertex buffer layout for two-component texture coordinates.
+ *
+ * @type {Object}
+ */
 export const uVLayout = Object.freeze({
   arrayStride: 8,
   attributes: Object.freeze([Object.freeze({

package/src/globals/vectorStyleNamedColors.js

@@ -1,8 +1,13 @@
-export const vectorStyleNamedColors = {
-  black: [0, 0, 0, 1],
-  white: [255, 255, 255, 1],
-  gray: [128, 128, 128, 1],
-  blue: [0, 0, 255, 1],
-  red: [255, 0, 0, 1],
-  green: [0, 128, 0, 1]
-};
+/**
+ * Supported named vector style colors as red, green, blue and alpha values.
+ *
+ * @type {Object<string, Array<number>>}
+ */
+export const vectorStyleNamedColors = {
+  black: [0, 0, 0, 1],
+  white: [255, 255, 255, 1],
+  gray: [128, 128, 128, 1],
+  blue: [0, 0, 255, 1],
+  red: [255, 0, 0, 1],
+  green: [0, 128, 0, 1]
+};

package/src/globals/vectorTileEvents.js

@@ -1 +1,6 @@
-export const vectorTileEvents = 'move zoom rotate pitch resize viewreset';
+/**
+ * Map events that schedule vector tile refreshes.
+ *
+ * @type {string}
+ */
+export const vectorTileEvents = 'move zoom rotate pitch resize viewreset';

package/src/globals/vehicles.js

@@ -9,6 +9,8 @@ import { boatModel } from '../vehicles/boatModel.js';
 /**
  * `side`: default offset (metres) to the right of the lane centreline. `model(i)` gives the prisms of the i-th vehicle.
  * `lights`: night point lights in model space (see the night lighting grid), e.g. the pool cast by the headlights.
+ *
+ * @type {Object<string, Object>}
  */
 export const vehicles = {
   bicycle: {

package/src/globals/vertexShader.js

@@ -1,3 +1,8 @@
+/**
+ * Reusable shader module descriptor for material vertex code.
+ *
+ * @type {Object}
+ */
 export const vertexShader = {
   code: null
 };

package/src/globals/wantedTiles.js

@@ -1 +1,6 @@
+/**
+ * Reusable map of raster tiles wanted for the current update.
+ *
+ * @type {Map}
+ */
 export const wantedTiles = new Map();

package/src/globals/white.js

@@ -1 +1,6 @@
+/**
+ * Off-white RGB color used in vehicle models.
+ *
+ * @type {Array<number>}
+ */
 export const white = [0.92, 0.93, 0.92];

package/src/globals/workerCogSource.js

@@ -1 +1,6 @@
-export const workerCogSource = new Map();
+/**
+ * Worker-local cache of open COG sources keyed by URL and asset.
+ *
+ * @type {Map}
+ */
+export const workerCogSource = new Map();

package/src/gpu/README.md

@@ -0,0 +1,29 @@
+# GPU resources
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Requests WebGPU adapters and devices, initializes shared renderer resources and
+reports device or shader failures. Rendering operations are in a separate folder.
+
+## Renderer lifetime
+
+```mermaid
+flowchart LR
+  Attach["First scene owner"] --> Adapter["Request adapter + device"]
+  Adapter --> Canvas["Configure canvas"]
+  Canvas --> Resources["Create scene / camera / GPU resources"]
+  Resources --> Share["Other layers share renderer"]
+  Share --> Last{"Last owner removed?"}
+  Last -->|yes| Wait["Wait for submitted work"]
+  Wait --> Destroy["Destroy resources + device"]
+  Last -->|no| Transfer["Transfer ownership"]
+```
+
+Missing WebGPU or canvas context is an attachment error. Cleanup errors are
+reported to the layer; see [scene](../scene/README.md) for ownership transfer.
+
+- [initializeSharedRenderer.js](./initializeSharedRenderer.js): create shared renderer state.
+- [initializeRendererResources.js](./initializeRendererResources.js): initialize GPU resources.
+- [releaseRenderer.js](./releaseRenderer.js): release renderer resources.
+
+Related: [rendering](../rendering/README.md), [materials](../materials/README.md).