maplibre-gl-layers 0.10.0 → 0.12.0

package/dist/internalTypes.d.ts

@@ -1,14 +1,340 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.10.0
+ * version: 0.12.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
+ * git.commit.hash: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
  */
 
-import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction } from './types';
+import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction, SpriteScreenPoint, SpritePoint } from './types';
+import { ResolvedSpriteScalingOptions, SurfaceCorner } from './math';
+/**
+ * The handle value that using the instance.
+ */
+export type IdHandle = number;
+/**
+ * Id handler interface.
+ * @param T Identified instance type
+ * @remarks It is used for (wasm) interoperability for identity.
+ */
+export interface IdHandler<T> {
+    /**
+     * Allocates a numeric handle for the specified identifier.
+     * @param {string} rawId - Raw identifier.
+     * @returns {IdHandle} Allocated handle.
+     */
+    readonly allocate: (rawId: string) => IdHandle;
+    /**
+     * Stores an instance reference at the given handle index.
+     * @param {IdHandle} handle - Numeric handle.
+     * @param {T} instance - Registered instance.
+     */
+    readonly store: (handle: IdHandle, instance: T) => void;
+    /**
+     * Get instance by handle.
+     * @param handle Numeric handle
+     * @returns Instance.
+     */
+    readonly get: (handle: IdHandle) => T;
+    /**
+     * Releases the handle associated with the provided identifier.
+     * @param {string} rawId - Raw identifier.
+     */
+    readonly release: (rawId: string) => void;
+    /**
+     * Clears all handle bookkeeping state.
+     */
+    readonly reset: () => void;
+}
+/**
+ * Buffers exposing image metadata indexed by handle.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ */
+export interface ImageHandleBuffers {
+    readonly widths: Float32Array;
+    readonly heights: Float32Array;
+    readonly textureReady: Uint8Array;
+}
+/**
+ * Registered image references aligned by handle index.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ */
+export type ImageResourceTable = readonly (Readonly<RegisteredImage> | undefined)[];
+/**
+ * Image handle buffer controller interface.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ */
+export interface ImageHandleBufferController {
+    /**
+     * Flag metadata buffers for regeneration.
+     * @param images Image map.
+     */
+    readonly markDirty: (images: ReadonlyMap<string, RegisteredImage>) => void;
+    /**
+     * Rebuilds the metadata buffers when flagged as dirty.
+     * @returns {ImageHandleBuffers} Metadata buffers aligned by handle index.
+     */
+    readonly ensure: () => ImageHandleBuffers;
+    /**
+     * Returns registered images aligned by handle index. Ensures buffers are up to date.
+     */
+    readonly getResourcesByHandle: () => ImageResourceTable;
+}
+/**
+ * Encoded pointer representing the target of an origin reference.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ *          The high bits encode the sub-layer while the low bits encode the order slot.
+ */
+export type SpriteOriginReferenceKey = number;
+/** Sentinel used when the image does not reference another sprite image. */
+export declare const SPRITE_ORIGIN_REFERENCE_KEY_NONE = -1;
+/**
+ * Index into the render target bucket pointing at the resolved origin image.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ *          When no origin is assigned or the reference could not be resolved,
+ *          the value will be {@link SPRITE_ORIGIN_REFERENCE_INDEX_NONE}.
+ */
+export type SpriteOriginReferenceIndex = number;
+/** Sentinel indicating that the origin pointer has not been resolved yet. */
+export declare const SPRITE_ORIGIN_REFERENCE_INDEX_NONE = -1;
+/**
+ * Encode/Decode interface for a (subLayer, order) pair into a compact numeric key.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ */
+export interface SpriteOriginReference {
+    /**
+     * Encodes a (subLayer, order) pair into a compact numeric key.
+     * @param subLayer Sub-layer identifier within the sprite.
+     * @param order Order slot inside the sub-layer.
+     * @returns Encoded origin reference key.
+     */
+    readonly encodeKey: (subLayer: number, order: number) => SpriteOriginReferenceKey;
+    /**
+     * Decodes an origin reference key back into the sub-layer and order pair.
+     * @param key Encoded origin reference key.
+     * @returns `subLayer` and `order` components; when the key is invalid, both values are set to `-1`.
+     */
+    readonly decodeKey: (key: SpriteOriginReferenceKey) => {
+        readonly subLayer: number;
+        readonly order: number;
+    };
+}
+/**
+ * Tuple representing a single entry in a render target bucket.
+ * @remarks It is used for (wasm) interoperability for sprite origin.
+ *          The first item is the sprite's frame-level state and the second item is
+ *          the specific image being rendered,
+ *          mirroring how the renderer stores draw calls on the CPU side.
+ *          Keeping the pair immutable prevents accidental divergence between cached data
+ *          and the GPU buffers derived from it.
+ */
+export type RenderTargetEntryLike<TTag> = readonly [
+    InternalSpriteCurrentState<TTag>,
+    InternalSpriteImageState
+];
+/**
+ * Parallel typed arrays that expose bucket metadata in a WASM-friendly layout.
+ * @remarks It is used for (wasm) interoperability for sprite origin.
+ *          Both arrays always share the same length as the bucket, allowing shader-side
+ *          code (or WASM helpers) to traverse origin reference metadata without touching
+ *          the heavyweight tuple objects.
+ */
+export interface RenderTargetBucketBuffers {
+    /**
+     * Encoded origin metadata (sub-layer/order pairs) for each queued image,
+     * mirroring `image.originReferenceKey`. A value of
+     * `SPRITE_ORIGIN_REFERENCE_KEY_NONE` denotes that the entry is self-originating.
+     */
+    readonly originReferenceKeys: Int32Array;
+    /**
+     * Bucket index pointing to the entry that should provide the origin image for
+     * the current sprite. Values equal to
+     * `SPRITE_ORIGIN_REFERENCE_INDEX_NONE` or outside the bucket range mark the
+     * origin as unresolved.
+     */
+    readonly originTargetIndices: Int32Array;
+}
+/**
+ * Represents a projected three dimensional position.
+ * `MercatorCoordinate` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units:
+ * - the size of 1 unit is the width of the projected world instead of the "mercator meter"
+ * - the origin of the coordinate space is at the north-west corner instead of the middle
+ */
+export interface SpriteMercatorCoordinate {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export interface Releaseable {
+    readonly release: () => void;
+}
+/**
+ * Abstraction that exposes projection-related helpers.
+ */
+export interface ProjectionHost extends Releaseable {
+    /**
+     * Get current zoom level.
+     * @returns Zoom level.
+     */
+    readonly getZoom: () => number;
+    /**
+     * Extracts the current clip-space context if the mercator matrix is available.
+     * @returns {ClipContext | null} Clip context or `null` when the transform is not ready.
+     */
+    readonly getClipContext: () => ClipContext | null;
+    /**
+     * Get mercator coordinate from the location
+     * @param location Location.
+     * @returns Mercator coordinate.
+     */
+    readonly fromLngLat: (location: Readonly<SpriteLocation>) => SpriteMercatorCoordinate;
+    /**
+     * Project the location.
+     * @param location Location.
+     * @returns Projected point if valid location.
+     */
+    readonly project: (location: Readonly<SpriteLocation>) => SpritePoint | null;
+    /**
+     * Unproject the location.
+     * @param point Projected point.
+     * @returns Location if valid point.
+     */
+    readonly unproject: (point: Readonly<SpritePoint>) => SpriteLocation | null;
+    /**
+     * Calculate perspective ratio.
+     * @param location Location.
+     * @param cachedMercator Mercator coodinate when available earlier calculation.
+     * @returns The ratio.
+     */
+    readonly calculatePerspectiveRatio: (location: Readonly<SpriteLocation>, cachedMercator?: SpriteMercatorCoordinate) => number;
+}
+export interface PrepareDrawSpriteImageParamsBase {
+    readonly imageResources: ImageResourceTable;
+    readonly imageHandleBuffers: Readonly<ImageHandleBuffers>;
+    readonly baseMetersPerPixel: number;
+    readonly spriteMinPixel: number;
+    readonly spriteMaxPixel: number;
+    readonly drawingBufferWidth: number;
+    readonly drawingBufferHeight: number;
+    readonly pixelRatio: number;
+    readonly clipContext: Readonly<ClipContext> | null;
+}
+export interface PrepareDrawSpriteImageParamsBefore<TTag> extends PrepareDrawSpriteImageParamsBase {
+    readonly bucket: readonly Readonly<RenderTargetEntryLike<TTag>>[];
+    readonly bucketBuffers: Readonly<RenderTargetBucketBuffers>;
+    readonly resolvedScaling: ResolvedSpriteScalingOptions;
+    readonly zoomScaleFactor: number;
+}
+export interface PrepareDrawSpriteImageParamsAfter extends PrepareDrawSpriteImageParamsBase {
+    readonly identityScaleX: number;
+    readonly identityScaleY: number;
+    readonly identityOffsetX: number;
+    readonly identityOffsetY: number;
+    readonly screenToClipScaleX: number;
+    readonly screenToClipScaleY: number;
+    readonly screenToClipOffsetX: number;
+    readonly screenToClipOffsetY: number;
+}
+export interface PrepareDrawSpriteImageParams<TTag> extends PrepareDrawSpriteImageParamsBefore<TTag>, PrepareDrawSpriteImageParamsAfter {
+}
+/**
+ * Prepared parameters for WebGL rendering.
+ */
+export interface PreparedDrawSpriteImageParams<T> {
+    readonly spriteEntry: InternalSpriteCurrentState<T>;
+    readonly imageEntry: InternalSpriteImageState;
+    readonly imageResource: RegisteredImage;
+    readonly vertexData: Float32Array;
+    readonly opacity: number;
+    readonly hitTestCorners: readonly [
+        Readonly<SpriteScreenPoint>,
+        Readonly<SpriteScreenPoint>,
+        Readonly<SpriteScreenPoint>,
+        Readonly<SpriteScreenPoint>
+    ] | null;
+    readonly screenToClip: {
+        readonly scaleX: number;
+        readonly scaleY: number;
+        readonly offsetX: number;
+        readonly offsetY: number;
+    };
+    readonly useShaderSurface: boolean;
+    readonly surfaceShaderInputs: SurfaceShaderInputs | undefined;
+    readonly surfaceClipEnabled: boolean;
+    readonly useShaderBillboard: boolean;
+    readonly billboardUniforms: {
+        readonly center: SpritePoint;
+        readonly halfWidth: number;
+        readonly halfHeight: number;
+        readonly anchor: SpriteAnchor;
+        readonly sin: number;
+        readonly cos: number;
+    } | null;
+}
+/**
+ * The render calculation host.
+ * Abstraction that render calculations.
+ * @param TTag Tag type.
+ */
+export interface RenderCalculationHost<TTag> extends Releaseable {
+    readonly prepareDrawSpriteImages: (params: PrepareDrawSpriteImageParams<TTag>) => PreparedDrawSpriteImageParams<TTag>[];
+}
+/**
+ * Corner model describing world displacements and resulting geographic coordinates for shader validation.
+ */
+export interface SurfaceShaderCornerState extends SpriteLocation, SurfaceCorner {
+}
+/**
+ * Aggregated inputs required to reproduce surface geometry on the GPU.
+ */
+export interface SurfaceShaderInputs {
+    readonly mercatorCenter: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly worldToMercatorScale: Readonly<SurfaceCorner>;
+    readonly halfSizeMeters: Readonly<SurfaceCorner>;
+    readonly anchor: Readonly<SpriteAnchor>;
+    readonly offsetMeters: Readonly<SurfaceCorner>;
+    readonly sinCos: {
+        readonly sin: number;
+        readonly cos: number;
+    };
+    readonly totalRotateDeg: number;
+    readonly depthBiasNdc: number;
+    readonly centerDisplacement: Readonly<SurfaceCorner>;
+    readonly baseLngLat: Readonly<SpriteLocation>;
+    readonly displacedCenter: Readonly<SpriteLocation>;
+    readonly scaleAdjustment: number;
+    readonly corners: readonly Readonly<SurfaceShaderCornerState>[];
+    clipCenter: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipBasisEast: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipBasisNorth: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipCorners: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    }>;
+}
 /**
  * Runtime state describing the active interpolation between two sprite locations.
  * Consumers reuse the same state across ticks to avoid re-allocations while animation is running.
@@ -70,10 +396,14 @@ export interface ResolvedTextureFilteringOptions {
  * Image metadata ready for use as a WebGL texture.
  */
 export interface RegisteredImage {
-    id: string;
-    width: number;
-    height: number;
-    bitmap: ImageBitmap;
+    readonly id: string;
+    /**
+     * For use (wasm) interoperability id.
+     */
+    readonly handle: number;
+    readonly width: number;
+    readonly height: number;
+    readonly bitmap: ImageBitmap;
     texture: WebGLTexture | undefined;
 }
 /**
@@ -116,7 +446,7 @@ export interface ResolvedTextGlyphOptions {
 /**
  * Mutable point reused when computing hit-test corners.
  */
-export interface MutableSpriteScreenPoint {
+export interface MutableSpriteScreenPoint extends SpriteScreenPoint {
     x: number;
     y: number;
 }
@@ -127,9 +457,9 @@ export type MatrixInput = ArrayLike<number>;
 /**
  * Cached clip-space context containing the mercator matrix required to project coordinates.
  */
-export type ClipContext = {
+export interface ClipContext {
     readonly mercatorMatrix: MatrixInput;
-};
+}
 /**
  * 2D canvas rendering context accepted by the glyph renderer.
  */
@@ -145,24 +475,28 @@ export interface InternalSpriteImageState {
     subLayer: number;
     order: number;
     imageId: string;
+    imageHandle: number;
     mode: SpriteMode;
     opacity: number;
     scale: number;
-    anchor: SpriteAnchor;
+    anchor: Readonly<SpriteAnchor>;
     offset: SpriteImageOffset;
     rotateDeg: number;
     displayedRotateDeg: number;
     autoRotation: boolean;
     autoRotationMinDistanceMeters: number;
     resolvedBaseRotateDeg: number;
-    originLocation?: SpriteImageOriginLocation;
-    rotationInterpolationState: DegreeInterpolationState | null;
-    rotationInterpolationOptions: SpriteInterpolationOptions | null;
-    offsetDegInterpolationState: DegreeInterpolationState | null;
-    offsetMetersInterpolationState: DistanceInterpolationState | null;
+    originLocation?: Readonly<SpriteImageOriginLocation>;
+    originReferenceKey: SpriteOriginReferenceKey;
+    originRenderTargetIndex: SpriteOriginReferenceIndex;
+    rotationInterpolationState: Readonly<DegreeInterpolationState> | null;
+    rotationInterpolationOptions: Readonly<SpriteInterpolationOptions> | null;
+    offsetDegInterpolationState: Readonly<DegreeInterpolationState> | null;
+    offsetMetersInterpolationState: Readonly<DistanceInterpolationState> | null;
     lastCommandRotateDeg: number;
     lastCommandOffsetDeg: number;
     lastCommandOffsetMeters: number;
+    surfaceShaderInputs?: Readonly<SurfaceShaderInputs>;
     hitTestCorners?: [
         MutableSpriteScreenPoint,
         MutableSpriteScreenPoint,
@@ -175,15 +509,20 @@ export interface InternalSpriteImageState {
  */
 export interface InternalSpriteCurrentState<TTag> {
     spriteId: string;
+    handle: IdHandle;
     isEnabled: boolean;
-    currentLocation: SpriteLocation;
-    fromLocation?: SpriteLocation;
-    toLocation?: SpriteLocation;
+    currentLocation: Readonly<SpriteLocation>;
+    fromLocation?: Readonly<SpriteLocation>;
+    toLocation?: Readonly<SpriteLocation>;
     images: Map<number, Map<number, InternalSpriteImageState>>;
     tag: TTag | null;
     interpolationState: InternalSpriteInterpolationState | null;
     pendingInterpolationOptions: SpriteInterpolationOptions | null;
-    lastCommandLocation: SpriteLocation;
-    lastAutoRotationLocation: SpriteLocation;
+    lastCommandLocation: Readonly<SpriteLocation>;
+    lastAutoRotationLocation: Readonly<SpriteLocation>;
     lastAutoRotationAngleDeg: number;
+    cachedMercator: Readonly<SpriteMercatorCoordinate>;
+    cachedMercatorLng: number;
+    cachedMercatorLat: number;
+    cachedMercatorZ: number | undefined;
 }

package/dist/interpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.10.0
+ * version: 0.12.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
+ * git.commit.hash: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
  */
 
 import { SpriteInterpolationOptions, SpriteLocation } from './types';

package/dist/interpolationChannels.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.10.0
+ * version: 0.12.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
+ * git.commit.hash: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
  */
 
 import { SpriteInterpolationOptions, SpriteImageOffset } from './types';

package/dist/looseQuadTree.d.ts

@@ -0,0 +1,34 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.0
+ * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
+ * git.commit.hash: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+export interface Rect {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+export interface Item<TState> extends Rect {
+    readonly state: TState;
+}
+export interface LooseQuadTree<TState> {
+    readonly size: number;
+    readonly add: (item: Item<TState>) => void;
+    readonly remove: (x0: number, y0: number, x1: number, y1: number, item: Item<TState>) => boolean;
+    readonly update: (oldX0: number, oldY0: number, oldX1: number, oldY1: number, newX0: number, newY0: number, newX1: number, newY1: number, item: Item<TState>) => boolean;
+    readonly lookup: (x0: number, y0: number, x1: number, y1: number) => Item<TState>[];
+    readonly clear: () => void;
+}
+export interface LooseQuadTreeOptions {
+    readonly bounds: Rect;
+    readonly maxItemsPerNode?: number;
+    readonly maxDepth?: number;
+    readonly looseness?: number;
+}
+export declare const createLooseQuadTree: <TState>(options: LooseQuadTreeOptions) => LooseQuadTree<TState>;

package/dist/mapLibreProjectionHost.d.ts

@@ -0,0 +1,18 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.0
+ * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
+ * git.commit.hash: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+import { Map as MapLibreMap } from 'maplibre-gl';
+import { ProjectionHost } from './internalTypes';
+/**
+ * Create a projection host that delegates to MapLibre.
+ * @param map MapLibre map instance
+ * @returns Projection host
+ */
+export declare const createMapLibreProjectionHost: (map: MapLibreMap) => ProjectionHost;