maplibre-gl-layers 0.6.0 → 0.11.0

package/dist/internalTypes.d.ts

@@ -0,0 +1,265 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.11.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: 371efb126f281333d59ec75cfe788d45f3b1482e
+ */
+
+import { MercatorCoordinate } from 'maplibre-gl';
+import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction } from './types';
+/**
+ * Corner model describing world displacements and resulting geographic coordinates for shader validation.
+ */
+export interface SurfaceShaderCornerState {
+    east: number;
+    north: number;
+    lng: number;
+    lat: number;
+}
+/**
+ * Aggregated inputs required to reproduce surface geometry on the GPU.
+ */
+export interface SurfaceShaderInputs {
+    mercatorCenter: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    worldToMercatorScale: {
+        east: number;
+        north: number;
+    };
+    halfSizeMeters: {
+        east: number;
+        north: number;
+    };
+    anchor: SpriteAnchor;
+    offsetMeters: {
+        east: number;
+        north: number;
+    };
+    sinCos: {
+        sin: number;
+        cos: number;
+    };
+    totalRotateDeg: number;
+    depthBiasNdc: number;
+    centerDisplacement: {
+        east: number;
+        north: number;
+    };
+    baseLngLat: SpriteLocation;
+    displacedCenter: SpriteLocation;
+    scaleAdjustment: number;
+    corners: SurfaceShaderCornerState[];
+    clipCenter: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    clipBasisEast: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    clipBasisNorth: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    clipCorners: Array<{
+        x: number;
+        y: number;
+        z: number;
+        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.
+ *
+ * @property mode - Strategy used to resolve the target location (feedback or feedforward).
+ * @property durationMs - Total time allocated for the interpolation in milliseconds.
+ * @property easing - Resolved easing function applied to raw progress values.
+ * @property startTimestamp - Epoch millisecond when the interpolation started, or -1 when uninitialized.
+ * @property from - Origin sprite location cloned from the current render state.
+ * @property to - Destination sprite location being interpolated towards.
+ */
+export interface SpriteInterpolationState {
+    readonly mode: SpriteInterpolationMode;
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    startTimestamp: number;
+    readonly from: SpriteLocation;
+    readonly to: SpriteLocation;
+}
+/**
+ * Runtime state tracked for numeric interpolations.
+ * @property {number} durationMs - Total duration of the interpolation in milliseconds.
+ * @property {EasingFunction} easing - Easing function applied to progress samples.
+ * @property {number} from - Start value used for interpolation.
+ * @property {number} to - Adjusted target along the shortest rotation path.
+ * @property {number} finalValue - Caller-requested final value (used once interpolation completes).
+ * @property {number} startTimestamp - Timestamp when interpolation began, `-1` until evaluation starts.
+ */
+export interface DegreeInterpolationState {
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    readonly from: number;
+    readonly to: number;
+    readonly finalValue: number;
+    startTimestamp: number;
+}
+export interface DistanceInterpolationState {
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    readonly from: number;
+    readonly to: number;
+    readonly finalValue: number;
+    startTimestamp: number;
+}
+/**
+ * Alias for the interpolation state used internally by sprites.
+ */
+export type InternalSpriteInterpolationState = SpriteInterpolationState;
+/**
+ * Texture filtering parameters resolved from the public options structure.
+ */
+export interface ResolvedTextureFilteringOptions {
+    readonly minFilter: SpriteTextureMinFilter;
+    readonly magFilter: SpriteTextureMagFilter;
+    readonly generateMipmaps: boolean;
+    readonly maxAnisotropy: number;
+}
+/**
+ * Image metadata ready for use as a WebGL texture.
+ */
+export interface RegisteredImage {
+    id: string;
+    width: number;
+    height: number;
+    bitmap: ImageBitmap;
+    texture: WebGLTexture | undefined;
+}
+/**
+ * Padding resolved for glyph rendering with guaranteed non-negative values.
+ */
+export interface ResolvedTextGlyphPadding {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/**
+ * Border sides resolved for glyph rendering.
+ */
+export interface ResolvedBorderSides {
+    readonly top: boolean;
+    readonly right: boolean;
+    readonly bottom: boolean;
+    readonly left: boolean;
+}
+/**
+ * Fully resolved glyph rendering options with defaults applied.
+ */
+export interface ResolvedTextGlyphOptions {
+    readonly fontFamily: string;
+    readonly fontStyle: 'normal' | 'italic';
+    readonly fontWeight: string;
+    readonly fontSizePixel: number;
+    readonly color: string;
+    readonly letterSpacingPixel: number;
+    readonly backgroundColor?: string;
+    readonly paddingPixel: ResolvedTextGlyphPadding;
+    readonly borderColor?: string;
+    readonly borderWidthPixel: number;
+    readonly borderRadiusPixel: number;
+    readonly borderSides: ResolvedBorderSides;
+    readonly textAlign: SpriteTextGlyphHorizontalAlign;
+    readonly renderPixelRatio: number;
+}
+/**
+ * Mutable point reused when computing hit-test corners.
+ */
+export interface MutableSpriteScreenPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Compact representation of an Array-like 4x4 matrix.
+ */
+export type MatrixInput = ArrayLike<number>;
+/**
+ * Cached clip-space context containing the mercator matrix required to project coordinates.
+ */
+export type ClipContext = {
+    readonly mercatorMatrix: MatrixInput;
+};
+/**
+ * 2D canvas rendering context accepted by the glyph renderer.
+ */
+export type Canvas2DContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Canvas sources supported when rendering text glyphs.
+ */
+export type Canvas2DSource = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Base attributes for an image that composes a sprite.
+ */
+export interface InternalSpriteImageState {
+    subLayer: number;
+    order: number;
+    imageId: string;
+    mode: SpriteMode;
+    opacity: number;
+    scale: number;
+    anchor: 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;
+    lastCommandRotateDeg: number;
+    lastCommandOffsetDeg: number;
+    lastCommandOffsetMeters: number;
+    surfaceShaderInputs?: SurfaceShaderInputs;
+    hitTestCorners?: [
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint
+    ];
+}
+/**
+ * Current sprite state tracked internally by the layer.
+ */
+export interface InternalSpriteCurrentState<TTag> {
+    spriteId: string;
+    isEnabled: boolean;
+    currentLocation: SpriteLocation;
+    fromLocation?: SpriteLocation;
+    toLocation?: SpriteLocation;
+    images: Map<number, Map<number, InternalSpriteImageState>>;
+    tag: TTag | null;
+    interpolationState: InternalSpriteInterpolationState | null;
+    pendingInterpolationOptions: SpriteInterpolationOptions | null;
+    lastCommandLocation: SpriteLocation;
+    lastAutoRotationLocation: SpriteLocation;
+    lastAutoRotationAngleDeg: number;
+    cachedMercator: MercatorCoordinate;
+    cachedMercatorLng: number;
+    cachedMercatorLat: number;
+    cachedMercatorZ: number;
+}

package/dist/interpolation.d.ts

@@ -1,33 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
-import { EasingFunction, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';
-/**
- * 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.
- *
- * @property mode - Strategy used to resolve the target location (feedback or feedforward).
- * @property durationMs - Total time allocated for the interpolation in milliseconds.
- * @property easing - Resolved easing function applied to raw progress values.
- * @property startTimestamp - Epoch millisecond when the interpolation started, or -1 when uninitialised.
- * @property from - Origin sprite location cloned from the current render state.
- * @property to - Destination sprite location being interpolated towards.
- */
-export interface SpriteInterpolationState {
-    readonly mode: SpriteInterpolationMode;
-    readonly durationMs: number;
-    readonly easing: EasingFunction;
-    startTimestamp: number;
-    readonly from: SpriteLocation;
-    readonly to: SpriteLocation;
-}
+import { SpriteInterpolationOptions, SpriteLocation } from './types';
+import { SpriteInterpolationState } from './internalTypes';
 /**
  * Parameters required to create a fresh interpolation state for the next animation segment.
  *

package/dist/interpolationChannels.d.ts

@@ -0,0 +1,37 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.11.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: 371efb126f281333d59ec75cfe788d45f3b1482e
+ */
+
+import { SpriteInterpolationOptions, SpriteImageOffset } from './types';
+import { InternalSpriteImageState } from './internalTypes';
+/**
+ * Ensures the rotation channel reflects the latest targets, optionally overriding interpolation.
+ */
+export declare const syncImageRotationChannel: (image: InternalSpriteImageState, optionsOverride?: SpriteInterpolationOptions | null) => void;
+/**
+ * Clears any running offset angle interpolation.
+ */
+export declare const clearOffsetDegInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Clears any running offset distance interpolation in meters.
+ */
+export declare const clearOffsetMetersInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Executes all interpolation steppers for an image and reports whether any remain active.
+ */
+export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number) => boolean;
+interface ApplyOffsetUpdateOptions {
+    readonly deg?: SpriteInterpolationOptions | null;
+    readonly meters?: SpriteInterpolationOptions | null;
+}
+/**
+ * Applies offset updates across both angular and radial channels.
+ */
+export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: SpriteImageOffset, options?: ApplyOffsetUpdateOptions) => void;
+export {};

package/dist/location.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
 import { SpriteLocation } from './types';

package/dist/looseQuadTree.d.ts

@@ -0,0 +1,34 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.11.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: 371efb126f281333d59ec75cfe788d45f3b1482e
+ */
+
+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 LooseQuadTreeOptions {
+    readonly bounds: Rect;
+    readonly maxItemsPerNode?: number;
+    readonly maxDepth?: number;
+    readonly looseness?: number;
+}
+export interface LooseQuadTree<TState> {
+    readonly size: number;
+    add(item: Item<TState>): void;
+    remove(x0: number, y0: number, x1: number, y1: number, item: Item<TState>): boolean;
+    update(oldX0: number, oldY0: number, oldX1: number, oldY1: number, newX0: number, newY0: number, newX1: number, newY1: number, item: Item<TState>): boolean;
+    lookup(x0: number, y0: number, x1: number, y1: number): Item<TState>[];
+    clear(): void;
+}
+export declare const createLooseQuadTree: <TState>(options: LooseQuadTreeOptions) => LooseQuadTree<TState>;

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';
@@ -391,6 +391,19 @@ export type QuadCorner = {
  * @returns {QuadCorner[]} Array containing screen- and texture-space information per corner.
  */
 export declare const calculateBillboardCornerScreenPositions: (params: BillboardCornerParams) => QuadCorner[];
+export type SurfaceShaderModelParams = {
+    baseLngLat: SpriteLocation;
+    worldWidthMeters: number;
+    worldHeightMeters: number;
+    anchor: SpriteAnchor;
+    totalRotateDeg: number;
+    offsetMeters: {
+        east: number;
+        north: number;
+    };
+};
+export type SurfaceShaderCornerModel = SurfaceCorner & SpriteLocation;
+export declare const computeSurfaceCornerShaderModel: (params: SurfaceShaderModelParams) => SurfaceShaderCornerModel[];
 /**
  * Parameters for projecting a surface sprite's center into screen space.
  * @typedef SurfaceCenterParams

package/dist/rotationInterpolation.d.ts

@@ -1,40 +1,42 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
-import { SpriteNumericInterpolationOptions } from './types';
-import { NumericInterpolationState } from './numericInterpolation';
+import { SpriteInterpolationOptions } from './types';
+import { DegreeInterpolationState } from './internalTypes';
 /**
  * Normalizes an absolute angle in degrees to the range [0, 360).
  * @param {number} angle - Angle provided by the caller which may fall outside a single revolution.
  * @returns {number} Angle wrapped to [0, 360) with negative zero converted to zero.
  */
-export declare const normaliseAngleDeg: (angle: number) => number;
+export declare const normalizeAngleDeg: (angle: number) => number;
 /**
  * Parameters describing the rotation update request.
  * @property {number} currentAngleDeg - Current angle already applied to the sprite in degrees.
  * @property {number} targetAngleDeg - Desired angle in degrees that should be reached.
- * @property {SpriteNumericInterpolationOptions | null} [options] - Optional interpolation configuration.
+ * @property {number | undefined} previousCommandAngleDeg - Previous commanded angle for feed-forward prediction.
+ * @property {SpriteInterpolationOptions | null} [options] - Optional interpolation configuration.
  */
 export interface ResolveRotationTargetParams {
     currentAngleDeg: number;
     targetAngleDeg: number;
-    options?: SpriteNumericInterpolationOptions | null;
+    previousCommandAngleDeg?: number;
+    options?: SpriteInterpolationOptions | null;
 }
 /**
  * Result produced by {@link resolveRotationTarget} when determining the next rotation step.
  * @property {number} nextAngleDeg - Angle that should be applied immediately.
- * @property {NumericInterpolationState | null} interpolationState - Optional state for animating toward the target.
+ * @property {DegreeInterpolationState | null} interpolationState - Optional state for animating toward the target.
  */
 export interface ResolveRotationTargetResult {
     readonly nextAngleDeg: number;
-    readonly interpolationState: NumericInterpolationState | null;
+    readonly interpolationState: DegreeInterpolationState | null;
 }
 /**
  * Determines whether a rotation change requires interpolation and, if so, produces the state to drive it.