maplibre-gl-layers 0.6.0 → 0.10.0

package/README.md

@@ -4,7 +4,7 @@ MapLibre's layer extension library enabling the display, movement, and modificat
 
 ![maplibre-gl-layers](images/maplibre-gl-layers-120.png)
 
-[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)
+[![Project Status: WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ----

package/dist/SpriteLayer.d.ts

@@ -1,29 +1,16 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.10.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: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
 import { Map as MapLibreMap } from 'maplibre-gl';
-import { SpriteMode, SpriteLayerInterface, SpriteLayerOptions, SpriteAnchor, SpriteLocation, SpriteImageDefinitionInit, SpriteImageOffset, SpriteInterpolationOptions, SpriteNumericInterpolationOptions, SpriteImageOriginLocation } from './types';
-import { SpriteInterpolationState } from './interpolation';
-import { NumericInterpolationState } from './numericInterpolation';
-/**
- * Compact representation of an Array-like 4x4 matrix.
- * Accepts typed arrays sourced from MapLibre internals.
- */
-type MatrixInput = ArrayLike<number>;
-/**
- * Cached clip-space context containing the mercator matrix required to project coordinates.
- * @property {MatrixInput} mercatorMatrix - Matrix mapping Mercator coordinates to clip space.
- */
-type ClipContext = {
-    readonly mercatorMatrix: MatrixInput;
-};
+import { SpriteLayerInterface, SpriteLayerOptions, SpriteAnchor, SpriteLocation, SpriteImageDefinitionInit, SpriteImageOffset, SpriteInterpolationOptions } from './types';
+import { MatrixInput, ClipContext, InternalSpriteImageState, InternalSpriteCurrentState } from './internalTypes';
 /**
  * Computes the perspective ratio from MapLibre's internal transform.
  * Used to calculate distance-based scaling that responds to pitch, zoom, and altitude.
@@ -77,158 +64,6 @@ export declare const compileShader: (glContext: WebGLRenderingContext, type: num
  * @throws When linking fails or a program cannot be created.
  */
 export declare const createShaderProgram: (glContext: WebGLRenderingContext, vertexSource: string, fragmentSource: string) => WebGLProgram;
-type MutableSpriteScreenPoint = {
-    x: number;
-    y: number;
-};
-/**
- * Base attributes for an image that composes a sprite.
- */
-interface InternalSpriteImageState {
-    /**
-     * Sub-layer identifier.
-     */
-    subLayer: number;
-    /**
-     * Ordering value within the sub-layer.
-     */
-    order: number;
-    /**
-     * Image ID referenced for rendering.
-     */
-    imageId: string;
-    /**
-     * Rendering mode. Defaults to surface.
-     */
-    mode: SpriteMode;
-    /**
-     * Opacity applied to the image alpha. Defaults to 1.0.
-     */
-    opacity: number;
-    /**
-     * Multiplier for real-world meters corresponding to one image pixel. 1.0 = 1 meter. Defaults to 1.0.
-     */
-    scale: number;
-    /**
-     * Anchor position within the sprite. Defaults to [0.0, 0.0].
-     */
-    anchor: SpriteAnchor;
-    /**
-     * Offset from the sprite coordinate. Defaults to no offset.
-     */
-    offset: SpriteImageOffset;
-    /**
-     * Requested rotation angle in degrees. Defaults to 0.
-     * Billboard mode: Clockwise rotation relative to the viewport.
-     * Surface mode: Clockwise azimuth from geographic north.
-     */
-    rotateDeg: number;
-    /**
-     * Rotation currently applied during rendering.
-     */
-    displayedRotateDeg: number;
-    /**
-     * Whether auto-rotation is enabled. Defaults to true in surface mode and false in billboard mode.
-     * The sprite orientation is derived from its movement vector when enabled.
-     */
-    autoRotation: boolean;
-    /**
-     * Minimum distance in meters required before auto-rotation updates. Defaults to 20 m.
-     * Values <= 0 trigger immediate updates.
-     */
-    autoRotationMinDistanceMeters: number;
-    /**
-     * Base rotation determined by auto-rotation. Initially 0.
-     */
-    resolvedBaseRotateDeg: number;
-    /**
-     * Reference sub-layer used as the origin for offsets. Defaults to sprite coordinates.
-     */
-    originLocation?: SpriteImageOriginLocation;
-    /**
-     * Interpolation state for display rotation.
-     */
-    rotationInterpolationState: NumericInterpolationState | null;
-    /**
-     * Default interpolation options for display rotation.
-     */
-    rotationInterpolationOptions: SpriteNumericInterpolationOptions | null;
-    /**
-     * Interpolation state used for offset.offsetDeg.
-     */
-    offsetInterpolationState: NumericInterpolationState | null;
-    /**
-     * Reusable buffer storing screen-space quad corners for hit testing.
-     */
-    hitTestCorners?: [
-        MutableSpriteScreenPoint,
-        MutableSpriteScreenPoint,
-        MutableSpriteScreenPoint,
-        MutableSpriteScreenPoint
-    ];
-}
-/**
- * Sprite position interpolation state.
- */
-type InternalSpriteInterpolationState = SpriteInterpolationState;
-/**
- * Current sprite state.
- * @param TTag Tag type.
- */
-interface InternalSpriteCurrentState<TTag> {
-    /**
-     * Sprite identifier.
-     */
-    spriteId: string;
-    /**
-     * Whether the sprite is enabled.
-     */
-    isEnabled: boolean;
-    /**
-     * Current location (interpolated position when moving).
-     */
-    currentLocation: SpriteLocation;
-    /**
-     * Source location used for movement interpolation.
-     * Feedback mode: previous command location.
-     * Feed-forward mode: current command location.
-     */
-    fromLocation?: SpriteLocation;
-    /**
-     * Destination location used for movement interpolation.
-     * Feedback mode: current command location.
-     * Feed-forward mode: predicted location.
-     */
-    toLocation?: SpriteLocation;
-    /**
-     * Map of image states currently associated with the sprite.
-     */
-    images: Map<number, Map<number, InternalSpriteImageState>>;
-    /**
-     * Optional tag (null when not set).
-     */
-    tag: TTag | null;
-    /**
-     * Active interpolation state, or null when idle.
-     */
-    interpolationState: InternalSpriteInterpolationState | null;
-    /**
-     * Most recently requested interpolation options, or null if none pending.
-     */
-    pendingInterpolationOptions: SpriteInterpolationOptions | null;
-    /**
-     * Most recently commanded location, regardless of interpolation.
-     */
-    lastCommandLocation: SpriteLocation;
-    /**
-     * Latest location used as the basis for auto-rotation calculation.
-     */
-    lastAutoRotationLocation: SpriteLocation;
-    /**
-     * Last resolved base angle from auto-rotation in degrees, reused as the next initial value.
-     */
-    lastAutoRotationAngleDeg: number;
-}
 /**
  * Clones a sprite anchor, defaulting to the origin when none supplied.
  * @param {SpriteAnchor} [anchor] - Anchor to clone.
@@ -242,7 +77,7 @@ export declare const cloneAnchor: (anchor?: SpriteAnchor) => SpriteAnchor;
  */
 export declare const cloneOffset: (offset?: SpriteImageOffset) => SpriteImageOffset;
 /**
- * Deep-clones movement interpolation options to prevent shared references between sprites.
+ * Deep-clones interpolation options to prevent shared references between sprites.
  * @param {SpriteInterpolationOptions} options - Options provided by the user.
  * @returns {SpriteInterpolationOptions} Cloned options object.
  */
@@ -266,4 +101,3 @@ export declare const createImageStateFromInit: (imageInit: SpriteImageDefinition
  * @returns {SpriteLayerInterface<T>} Interface for sprite add/update/remove operations and MapLibre hooks.
  */
 export declare const createSpriteLayer: <T = any>(options?: SpriteLayerOptions) => SpriteLayerInterface<T>;
-export {};

package/dist/const.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.10.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
+ */
+
+import { SpriteScalingOptions, SpriteTextureFilteringOptions } from './types';
+/**
+ * Unlimited (default) values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const UNLIMITED_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+/**
+ * Standard values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const STANDARD_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+/**
+ * Defaulted text filtering options.
+ */
+export declare const DEFAULT_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
+/**
+ * Better text filtering options than default options.
+ */
+export declare const BETTER_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;

package/dist/degreeInterpolation.d.ts

@@ -0,0 +1,66 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.10.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
+ */
+
+import { SpriteInterpolationOptions } from './types';
+import { DegreeInterpolationState } from './internalTypes';
+/**
+ * Parameters required to construct a {@link DegreeInterpolationState}.
+ * @property {number} currentValue - Current numeric value rendered on screen.
+ * @property {number} targetValue - Desired value after interpolation completes.
+ * @property {number | undefined} previousCommandValue - Prior commanded value used for feed-forward prediction.
+ * @property {SpriteInterpolationOptions} options - Timing and easing configuration.
+ */
+export interface CreateDegreeInterpolationStateParams {
+    currentValue: number;
+    targetValue: number;
+    previousCommandValue?: number;
+    options: SpriteInterpolationOptions;
+}
+/**
+ * Result returned by {@link createDegreeInterpolationState} containing state and a flag for activation.
+ * @property {DegreeInterpolationState} state - Resolved state object.
+ * @property {boolean} requiresInterpolation - Indicates whether the caller should animate or snap.
+ */
+export interface CreateDegreeInterpolationStateResult {
+    readonly state: DegreeInterpolationState;
+    readonly requiresInterpolation: boolean;
+}
+/**
+ * Creates interpolation state describing how to move from the current value to the target value.
+ * @param {CreateDegreeInterpolationStateParams} params - Inputs describing the current, target, and options.
+ * @returns {CreateDegreeInterpolationStateResult} State data plus a flag indicating if animation is needed.
+ */
+export declare const createDegreeInterpolationState: (params: CreateDegreeInterpolationStateParams) => CreateDegreeInterpolationStateResult;
+/**
+ * Parameters describing interpolation evaluation state.
+ * @property {DegreeInterpolationState} state - State generated via {@link createDegreeInterpolationState}.
+ * @property {number} timestamp - Timestamp in milliseconds used to sample the interpolation curve.
+ */
+export interface EvaluateDegreeInterpolationParams {
+    state: DegreeInterpolationState;
+    timestamp: number;
+}
+/**
+ * Result of evaluating a numeric interpolation at a specific timestamp.
+ * @property {number} value - Current interpolated value (or final value after completion).
+ * @property {boolean} completed - Indicates whether interpolation reached the end.
+ * @property {number} effectiveStartTimestamp - Start timestamp applied during evaluation.
+ */
+export interface EvaluateDegreeInterpolationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+/**
+ * Evaluates a numeric interpolation against the provided timestamp.
+ * @param {EvaluateDegreeInterpolationParams} params - Inputs containing interpolation state and sample timestamp.
+ * @returns {EvaluateDegreeInterpolationResult} Current value, completion flag, and effective start time.
+ */
+export declare const evaluateDegreeInterpolation: (params: EvaluateDegreeInterpolationParams) => EvaluateDegreeInterpolationResult;

package/dist/distanceInterpolation.d.ts

@@ -0,0 +1,33 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.10.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
+ */
+
+import { SpriteInterpolationOptions } from './types';
+import { DistanceInterpolationState } from './internalTypes';
+export interface CreateDistanceInterpolationStateParams {
+    currentValue: number;
+    targetValue: number;
+    previousCommandValue?: number;
+    options: SpriteInterpolationOptions;
+}
+export interface CreateDistanceInterpolationStateResult {
+    readonly state: DistanceInterpolationState;
+    readonly requiresInterpolation: boolean;
+}
+export declare const createDistanceInterpolationState: (params: CreateDistanceInterpolationStateParams) => CreateDistanceInterpolationStateResult;
+export interface EvaluateDistanceInterpolationParams {
+    state: DistanceInterpolationState;
+    timestamp: number;
+}
+export interface EvaluateDistanceInterpolationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+export declare const evaluateDistanceInterpolation: (params: EvaluateDistanceInterpolationParams) => EvaluateDistanceInterpolationResult;

package/dist/easing.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.10.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: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
 import { EasingFunction } from './types';