maplibre-gl-layers 0.13.0 → 0.15.0

package/dist/internalTypes.d.ts

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction, SpriteScreenPoint, SpritePoint } from './types';
-import { ResolvedSpriteScalingOptions, SurfaceCorner } from './math';
+import { SpriteMode, SpriteAnchor, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction, SpriteScreenPoint, SpritePoint, SpriteEasingPresetName } from './types';
+import { ResolvedSpriteScalingOptions, SurfaceCorner } from './utils/math';
 /**
  * The handle value that using the instance.
  */
@@ -167,13 +167,26 @@ export interface SpriteMercatorCoordinate {
     readonly y: number;
     readonly z: number;
 }
-export interface Releaseable {
+/**
+ * Mutable counterpart to {@link InterpolatedValues}, used internally so SpriteLayer
+ * can reuse object references while still exposing readonly snapshots publicly.
+ */
+export interface MutableInterpolatedValues<T> {
+    current: T;
+    from: T | undefined;
+    to: T | undefined;
+}
+export interface MutableSpriteImageInterpolatedOffset {
+    offsetMeters: MutableInterpolatedValues<number>;
+    offsetDeg: MutableInterpolatedValues<number>;
+}
+export interface Releasable {
     readonly release: () => void;
 }
 /**
  * Abstraction that exposes projection-related helpers.
  */
-export interface ProjectionHost extends Releaseable {
+export interface ProjectionHost extends Releasable {
     /**
      * Get current zoom level.
      * @returns Zoom level.
@@ -209,6 +222,7 @@ export interface ProjectionHost extends Releaseable {
      * @returns The ratio.
      */
     readonly calculatePerspectiveRatio: (location: Readonly<SpriteLocation>, cachedMercator?: SpriteMercatorCoordinate) => number;
+    readonly getCameraLocation: () => SpriteLocation | null;
 }
 export interface PrepareDrawSpriteImageParamsBase {
     readonly imageResources: ImageResourceTable;
@@ -247,7 +261,8 @@ export interface PreparedDrawSpriteImageParams<T> {
     readonly imageEntry: InternalSpriteImageState;
     readonly imageResource: RegisteredImage;
     readonly vertexData: Float32Array;
-    readonly opacity: number;
+    opacity: number;
+    readonly cameraDistanceMeters: number;
     readonly hitTestCorners: readonly [
         Readonly<SpriteScreenPoint>,
         Readonly<SpriteScreenPoint>,
@@ -273,13 +288,50 @@ export interface PreparedDrawSpriteImageParams<T> {
         readonly cos: number;
     } | null;
 }
+/**
+ * Common frame parameters shared with interpolation processing.
+ */
+export interface RenderInterpolationFrameContext {
+    readonly baseMetersPerPixel: number;
+    readonly spriteMinPixel: number;
+    readonly spriteMaxPixel: number;
+}
+/**
+ * Parameters consumed when processing sprite interpolations.
+ */
+export interface RenderInterpolationParams<TTag> {
+    readonly sprites: readonly InternalSpriteCurrentState<TTag>[];
+    readonly timestamp: number;
+    readonly frameContext?: RenderInterpolationFrameContext;
+}
+/**
+ * Result produced by sprite interpolation processing.
+ */
+export interface RenderInterpolationResult {
+    readonly handled: boolean;
+    readonly hasActiveInterpolation: boolean;
+}
+/**
+ * Parameters passed into RenderCalculationHost.processDrawSpriteImages.
+ */
+export interface ProcessDrawSpriteImagesParams<TTag> {
+    readonly interpolationParams?: RenderInterpolationParams<TTag>;
+    readonly prepareParams?: PrepareDrawSpriteImageParams<TTag>;
+}
+/**
+ * Result returned from RenderCalculationHost.processDrawSpriteImages.
+ */
+export interface ProcessDrawSpriteImagesResult<TTag> {
+    readonly preparedItems: PreparedDrawSpriteImageParams<TTag>[];
+    readonly interpolationResult: RenderInterpolationResult;
+}
 /**
  * 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>[];
+export interface RenderCalculationHost<TTag> extends Releasable {
+    readonly processDrawSpriteImages: (params: ProcessDrawSpriteImagesParams<TTag>) => ProcessDrawSpriteImagesResult<TTag>;
 }
 /**
  * Corner model describing world displacements and resulting geographic coordinates for shader validation.
@@ -350,6 +402,7 @@ export interface SpriteInterpolationState {
     readonly mode: SpriteInterpolationMode;
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     startTimestamp: number;
     readonly from: SpriteLocation;
     readonly to: SpriteLocation;
@@ -366,6 +419,7 @@ export interface SpriteInterpolationState {
 export interface DegreeInterpolationState {
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     readonly from: number;
     readonly to: number;
     readonly finalValue: number;
@@ -374,11 +428,39 @@ export interface DegreeInterpolationState {
 export interface DistanceInterpolationState {
     readonly durationMs: number;
     readonly easing: EasingFunction;
+    readonly easingPreset: SpriteEasingPresetName | null;
     readonly from: number;
     readonly to: number;
     readonly finalValue: number;
     startTimestamp: number;
 }
+export interface DistanceInterpolationEvaluationParams {
+    readonly state: DistanceInterpolationState;
+    readonly timestamp: number;
+}
+export interface DistanceInterpolationEvaluationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+export interface DegreeInterpolationEvaluationParams {
+    readonly state: DegreeInterpolationState;
+    readonly timestamp: number;
+}
+export interface DegreeInterpolationEvaluationResult {
+    readonly value: number;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
+export interface SpriteInterpolationEvaluationParams {
+    readonly state: SpriteInterpolationState;
+    readonly timestamp: number;
+}
+export interface SpriteInterpolationEvaluationResult {
+    readonly location: SpriteLocation;
+    readonly completed: boolean;
+    readonly effectiveStartTimestamp: number;
+}
 /**
  * Alias for the interpolation state used internally by sprites.
  */
@@ -405,6 +487,11 @@ export interface RegisteredImage {
     readonly height: number;
     readonly bitmap: ImageBitmap;
     texture: WebGLTexture | undefined;
+    atlasPageIndex: number;
+    atlasU0: number;
+    atlasV0: number;
+    atlasU1: number;
+    atlasV1: number;
 }
 /**
  * Padding resolved for glyph rendering with guaranteed non-negative values.
@@ -477,11 +564,12 @@ export interface InternalSpriteImageState {
     imageId: string;
     imageHandle: number;
     mode: SpriteMode;
-    opacity: number;
+    opacity: MutableInterpolatedValues<number>;
     scale: number;
     anchor: Readonly<SpriteAnchor>;
-    offset: SpriteImageOffset;
-    rotateDeg: number;
+    offset: MutableSpriteImageInterpolatedOffset;
+    rotateDeg: MutableInterpolatedValues<number>;
+    rotationCommandDeg: number;
     displayedRotateDeg: number;
     autoRotation: boolean;
     autoRotationMinDistanceMeters: number;
@@ -493,9 +581,15 @@ export interface InternalSpriteImageState {
     rotationInterpolationOptions: Readonly<SpriteInterpolationOptions> | null;
     offsetDegInterpolationState: Readonly<DegreeInterpolationState> | null;
     offsetMetersInterpolationState: Readonly<DistanceInterpolationState> | null;
+    opacityInterpolationState: Readonly<DistanceInterpolationState> | null;
+    opacityInterpolationOptions: Readonly<SpriteInterpolationOptions> | null;
+    opacityTargetValue: number;
+    lodLastCommandOpacity: number;
     lastCommandRotateDeg: number;
     lastCommandOffsetDeg: number;
     lastCommandOffsetMeters: number;
+    lastCommandOpacity: number;
+    interpolationDirty: boolean;
     surfaceShaderInputs?: Readonly<SurfaceShaderInputs>;
     hitTestCorners?: [
         MutableSpriteScreenPoint,
@@ -511,9 +605,8 @@ export interface InternalSpriteCurrentState<TTag> {
     spriteId: string;
     handle: IdHandle;
     isEnabled: boolean;
-    currentLocation: Readonly<SpriteLocation>;
-    fromLocation?: Readonly<SpriteLocation>;
-    toLocation?: Readonly<SpriteLocation>;
+    visibilityDistanceMeters?: number;
+    location: MutableInterpolatedValues<Readonly<SpriteLocation>>;
     images: Map<number, Map<number, InternalSpriteImageState>>;
     tag: TTag | null;
     interpolationState: InternalSpriteInterpolationState | null;
@@ -521,6 +614,7 @@ export interface InternalSpriteCurrentState<TTag> {
     lastCommandLocation: Readonly<SpriteLocation>;
     lastAutoRotationLocation: Readonly<SpriteLocation>;
     lastAutoRotationAngleDeg: number;
+    interpolationDirty: boolean;
     cachedMercator: Readonly<SpriteMercatorCoordinate>;
     cachedMercatorLng: number;
     cachedMercatorLat: number;

package/dist/{degreeInterpolation.d.ts → interpolation/degreeInterpolation.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions } from './types';
-import { DegreeInterpolationState } from './internalTypes';
+import { SpriteInterpolationOptions } from '../types';
+import { DegreeInterpolationState, DegreeInterpolationEvaluationResult, InternalSpriteImageState } from '../internalTypes';
 /**
  * Parameters required to construct a {@link DegreeInterpolationState}.
  * @property {number} currentValue - Current numeric value rendered on screen.
@@ -64,3 +64,18 @@ export interface EvaluateDegreeInterpolationResult {
  * @returns {EvaluateDegreeInterpolationResult} Current value, completion flag, and effective start time.
  */
 export declare const evaluateDegreeInterpolation: (params: EvaluateDegreeInterpolationParams) => EvaluateDegreeInterpolationResult;
+type DegreeInterpolationStateKey = 'rotationInterpolationState' | 'offsetDegInterpolationState';
+interface DegreeInterpolationChannelDescriptor {
+    readonly stateKey: DegreeInterpolationStateKey;
+    readonly normalize?: (value: number) => number;
+    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
+    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
+}
+export interface DegreeInterpolationWorkItem {
+    readonly descriptor: DegreeInterpolationChannelDescriptor;
+    readonly image: InternalSpriteImageState;
+    readonly state: DegreeInterpolationState;
+}
+export declare const collectDegreeInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DegreeInterpolationWorkItem[]) => void;
+export declare const applyDegreeInterpolationEvaluations: (workItems: readonly DegreeInterpolationWorkItem[], evaluations: readonly DegreeInterpolationEvaluationResult[], timestamp: number) => boolean;
+export {};

package/dist/interpolation/distanceInterpolation.d.ts

@@ -0,0 +1,46 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.15.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: d850b7e9c713f54f0630248dc4ea370721b6965b
+ */
+
+import { SpriteInterpolationOptions } from '../types';
+import { DistanceInterpolationEvaluationParams, DistanceInterpolationEvaluationResult, DistanceInterpolationState, InternalSpriteImageState } 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 declare const evaluateDistanceInterpolation: (params: DistanceInterpolationEvaluationParams) => DistanceInterpolationEvaluationResult;
+type DistanceInterpolationStateKey = 'offsetMetersInterpolationState' | 'opacityInterpolationState';
+interface DistanceInterpolationChannelDescriptor {
+    readonly stateKey: DistanceInterpolationStateKey;
+    readonly normalize?: (value: number) => number;
+    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
+    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
+}
+declare const DISTANCE_INTERPOLATION_CHANNELS: Record<'offsetMeters' | 'opacity', DistanceInterpolationChannelDescriptor>;
+export type DistanceInterpolationChannelDescriptorMap = typeof DISTANCE_INTERPOLATION_CHANNELS;
+export type DistanceInterpolationChannelName = keyof DistanceInterpolationChannelDescriptorMap;
+export interface DistanceInterpolationWorkItem {
+    readonly descriptor: DistanceInterpolationChannelDescriptorMap[DistanceInterpolationChannelName];
+    readonly image: InternalSpriteImageState;
+    readonly state: DistanceInterpolationState;
+}
+export interface CollectDistanceInterpolationWorkItemOptions {
+    readonly includeOffsetMeters?: boolean;
+    readonly includeOpacity?: boolean;
+}
+export declare const collectDistanceInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DistanceInterpolationWorkItem[], options?: CollectDistanceInterpolationWorkItemOptions) => void;
+export declare const applyDistanceInterpolationEvaluations: (workItems: readonly DistanceInterpolationWorkItem[], evaluations: readonly DistanceInterpolationEvaluationResult[], timestamp: number) => boolean;
+export {};

package/dist/{easing.d.ts → interpolation/easing.d.ts}

@@ -1,19 +1,24 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { EasingFunction } from './types';
+import { EasingFunction, SpriteEasingPresetName, SpriteInterpolationEasing } from '../types';
 /**
  * Linear interpolation that clamps the value to the [0, 1] range.
  */
 export declare const linearEasing: EasingFunction;
+export interface ResolvedEasing {
+    readonly easing: EasingFunction;
+    readonly preset: SpriteEasingPresetName | null;
+}
 /**
  * Returns the provided easing function or falls back to linear interpolation.
+ * When a preset name is supplied the resolved preset identifier is preserved for downstream consumers.
  */
-export declare const resolveEasing: (easing?: EasingFunction) => EasingFunction;
+export declare const resolveEasing: (easing?: SpriteInterpolationEasing) => ResolvedEasing;

package/dist/{interpolation.d.ts → interpolation/interpolation.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions, SpriteLocation } from './types';
-import { SpriteInterpolationState } from './internalTypes';
+import { SpriteInterpolationOptions, SpriteLocation } from '../types';
+import { SpriteInterpolationState, SpriteInterpolationEvaluationParams, SpriteInterpolationEvaluationResult } from '../internalTypes';
 /**
  * Parameters required to create a fresh interpolation state for the next animation segment.
  *
@@ -41,32 +41,10 @@ export interface CreateInterpolationStateResult {
  * @returns The prepared state alongside a boolean indicating whether animation should run.
  */
 export declare const createInterpolationState: (params: CreateInterpolationStateParams) => CreateInterpolationStateResult;
-/**
- * Parameters required to evaluate an interpolation tick at a given moment.
- *
- * @property state - Active interpolation state previously created.
- * @property timestamp - Epoch millisecond at which interpolation should be evaluated.
- */
-export interface EvaluateInterpolationParams {
-    state: SpriteInterpolationState;
-    timestamp: number;
-}
-/**
- * Result of evaluating interpolation progress at a specific timestamp.
- *
- * @property location - Interpolated sprite location corresponding to the evaluated time.
- * @property completed - Indicates whether the interpolation has reached or exceeded its duration.
- * @property effectiveStartTimestamp - Timestamp detected or assigned as the interpolation starting point.
- */
-export interface EvaluateInterpolationResult {
-    readonly location: SpriteLocation;
-    readonly completed: boolean;
-    readonly effectiveStartTimestamp: number;
-}
 /**
  * Evaluates an interpolation state at a specific point in time and returns the intermediate location.
  *
  * @param params - The interpolation state and the reference timestamp for evaluation.
  * @returns The lerped location, whether the interpolation has finished, and the effective start time.
  */
-export declare const evaluateInterpolation: (params: EvaluateInterpolationParams) => EvaluateInterpolationResult;
+export declare const evaluateInterpolation: (params: SpriteInterpolationEvaluationParams) => SpriteInterpolationEvaluationResult;

package/dist/{interpolationChannels.d.ts → interpolation/interpolationChannels.d.ts}

@@ -1,15 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-import { SpriteInterpolationOptions, SpriteImageOffset } from './types';
-import { InternalSpriteImageState } from './internalTypes';
+import { SpriteInterpolationOptions, SpriteImageOffset } from '../types';
+import { InternalSpriteImageState } from '../internalTypes';
 /**
  * Ensures the rotation channel reflects the latest targets, optionally overriding interpolation.
  */
@@ -22,11 +22,21 @@ export declare const clearOffsetDegInterpolation: (image: InternalSpriteImageSta
  * Clears any running offset distance interpolation in meters.
  */
 export declare const clearOffsetMetersInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Clears any running opacity interpolation.
+ */
+export declare const clearOpacityInterpolation: (image: InternalSpriteImageState) => void;
+export declare const applyOpacityUpdate: (image: InternalSpriteImageState, nextOpacity: number, interpolationOptions?: SpriteInterpolationOptions | null) => void;
+export type ImageInterpolationStepperId = 'rotation' | 'offsetDeg' | 'offsetMeters' | 'opacity';
 /**
  * Executes all interpolation steppers for an image and reports whether any remain active.
  */
-export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number) => boolean;
-interface ApplyOffsetUpdateOptions {
+export interface StepSpriteImageInterpolationOptions {
+    readonly skipChannels?: Partial<Record<ImageInterpolationStepperId, boolean>>;
+}
+export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number, options?: StepSpriteImageInterpolationOptions) => boolean;
+export declare const hasActiveImageInterpolations: (image: InternalSpriteImageState) => boolean;
+export interface ApplyOffsetUpdateOptions {
     readonly deg?: SpriteInterpolationOptions | null;
     readonly meters?: SpriteInterpolationOptions | null;
 }
@@ -34,4 +44,3 @@ interface ApplyOffsetUpdateOptions {
  * Applies offset updates across both angular and radial channels.
  */
 export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: SpriteImageOffset, options?: ApplyOffsetUpdateOptions) => void;
-export {};

package/dist/{rotationInterpolation.d.ts → interpolation/rotationInterpolation.d.ts}

@@ -1,21 +1,16 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.13.0
+ * version: 0.15.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: 4934aa7f4fed93594ece419184b32b5b972bbb88
+ * git.commit.hash: d850b7e9c713f54f0630248dc4ea370721b6965b
  */
 
-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 normalizeAngleDeg: (angle: number) => number;
+import { SpriteInterpolationOptions } from '../types';
+import { DegreeInterpolationState } from '../internalTypes';
+export { normalizeAngleDeg } from '../utils/math';
 /**
  * Parameters describing the rotation update request.
  * @property {number} currentAngleDeg - Current angle already applied to the sprite in degrees.