maplibre-gl-layers 0.11.0 → 0.13.0

package/dist/math.d.ts

@@ -1,35 +1,38 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.11.0
+ * version: 0.13.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
+ * git.commit.hash: 4934aa7f4fed93594ece419184b32b5b972bbb88
  */
 
-import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';
+import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpritePoint, SpriteScalingOptions, SpriteScreenPoint } from './types';
+import { InternalSpriteCurrentState, MatrixInput, ProjectionHost, SpriteMercatorCoordinate } from './internalTypes';
 /**
- * WGS84-compatible Earth radius in meters.
- * Used to convert one radian of longitude into meters when scaling sprites.
- * @constant
+ * Produces a deep copy so later updates do not mutate the original object.
  */
-export declare const EARTH_RADIUS_METERS = 6378137;
+export declare const cloneSpriteLocation: (location: SpriteLocation) => SpriteLocation;
 /**
- * Multiplier for converting degrees to radians.
- * @constant
+ * Linearly interpolates longitude, latitude, and optionally altitude.
+ * The `ratio` may fall outside [0, 1]; callers are responsible for clamping if needed.
  */
-export declare const DEG2RAD: number;
+export declare const lerpSpriteLocation: (from: SpriteLocation, to: SpriteLocation, ratio: number) => SpriteLocation;
 /**
- * Multiplier for converting radians to degrees.
- * @constant
+ * Compares two locations. Treats altitude as equal when either side is undefined.
  */
-export declare const RAD2DEG: number;
+export declare const spriteLocationsEqual: (a: SpriteLocation, b: SpriteLocation) => boolean;
 /**
- * Default MapLibre tile size used for Web Mercator calculations.
- * @constant
+ * Multiplies a 4x4 matrix with a 4-component vector using row-major indexing.
+ * @param {MatrixInput} matrix - Matrix to multiply.
+ * @param {number} x - X component of the vector.
+ * @param {number} y - Y component of the vector.
+ * @param {number} z - Z component of the vector.
+ * @param {number} w - W component of the vector.
+ * @returns {[number, number, number, number]} Resulting homogeneous coordinate.
  */
-export declare const TILE_SIZE = 512;
+export declare const multiplyMatrixAndVector: (matrix: MatrixInput, x: number, y: number, z: number, w: number) => [number, number, number, number];
 /**
  * Structure holding resolved sprite scaling options.
  * @property {number} metersPerPixel - Effective number of meters represented by each rendered pixel.
@@ -110,24 +113,18 @@ export declare const calculateBillboardPixelDimensions: (imageWidth: number | un
  * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
  * @param {number} effectivePixelsPerMeter - Conversion factor from meters to pixels.
  * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
- * @returns {{ x: number; y: number }} Screen-space offset relative to the billboard center.
+ * @returns {SpriteScreenPoint} Screen-space offset relative to the billboard center.
  */
-export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, sizeScaleAdjustment?: number) => {
-    x: number;
-    y: number;
-};
+export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, sizeScaleAdjustment?: number) => SpriteScreenPoint;
 /**
  * Computes the screen-space shift caused by anchor rotation for billboards.
  * @param {number} halfWidth - Half of the sprite width in pixels.
  * @param {number} halfHeight - Half of the sprite height in pixels.
  * @param {SpriteAnchor | undefined} anchor - Anchor definition normalized to [-1, 1] range.
  * @param {number} totalRotateDeg - Rotation applied to the sprite, combining user and bearing rotations.
- * @returns {{ x: number; y: number }} Pixel delta required to bring the anchor back to the requested origin.
+ * @returns {SpritePoint} Pixel delta required to bring the anchor back to the requested origin.
  */
-export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, halfHeight: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => {
-    x: number;
-    y: number;
-};
+export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, halfHeight: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => SpritePoint;
 /**
  * Calculates surface image dimensions in world meters.
  * @param {number | undefined} imageWidth - Source bitmap width in pixels.
@@ -152,65 +149,44 @@ export declare const calculateSurfaceWorldDimensions: (imageWidth: number | unde
  * @param {number} halfHeightMeters - Half of the world-space height.
  * @param {SpriteAnchor | undefined} anchor - Anchor definition normalized to [-1, 1] range.
  * @param {number} totalRotateDeg - Rotation angle applied to the surface.
- * @returns {{ east: number; north: number }} Displacement in meters required to apply the anchor.
+ * @returns {SurfaceCorner} Displacement in meters required to apply the anchor.
  */
-export declare const calculateSurfaceAnchorShiftMeters: (halfWidthMeters: number, halfHeightMeters: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => {
-    east: number;
-    north: number;
-};
+export declare const calculateSurfaceAnchorShiftMeters: (halfWidthMeters: number, halfHeightMeters: number, anchor: SpriteAnchor | undefined, totalRotateDeg: number) => SurfaceCorner;
 /**
  * Calculates surface image offsets in meters.
  * @param {SpriteImageOffset | undefined} offset - Offset configuration for the surface sprite.
  * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
  * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
  * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
- * @returns {{ east: number; north: number }} Offset vector in meters.
+ * @returns {SurfaceCorner} Offset vector in meters.
  */
-export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, sizeScaleAdjustment?: number) => {
-    east: number;
-    north: number;
-};
+export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, sizeScaleAdjustment?: number) => SurfaceCorner;
 /**
  * Adds east/north distances (meters) to a longitude/latitude pair.
- * @param {number} baseLng - Base longitude in degrees.
- * @param {number} baseLat - Base latitude in degrees.
+ * @param {number} location - Base location in degrees.
  * @param {number} east - Eastward displacement in meters.
  * @param {number} north - Northward displacement in meters.
  * @returns {SpriteLocation} New geographic position after applying the displacement.
  */
-export declare const applySurfaceDisplacement: (baseLng: number, baseLat: number, east: number, north: number) => SpriteLocation;
+export declare const applySurfaceDisplacement: (location: SpriteLocation, corner: SurfaceCorner) => SpriteLocation;
 /**
  * Converts screen coordinates to clip space.
- * @param {number} x - Screen-space x coordinate in CSS pixels.
- * @param {number} y - Screen-space y coordinate in CSS pixels.
+ * @param {number} point - Screen-space coordinate in CSS pixels.
  * @param {number} drawingBufferWidth - WebGL drawing buffer width in device pixels.
  * @param {number} drawingBufferHeight - WebGL drawing buffer height in device pixels.
  * @param {number} pixelRatio - Device pixel ratio used to scale CSS pixels to device pixels.
  * @returns {[number, number]} Clip-space coordinates in the range [-1, 1].
  */
-export declare const screenToClip: (x: number, y: number, drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => [number, number];
+export declare const screenToClip: (point: SpriteScreenPoint, drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => [number, number];
 /**
  * Converts homogeneous clip coordinates back into screen-space pixels.
  * @param {[number, number, number, number]} clipPosition - Homogeneous clip coordinates.
  * @param {number} drawingBufferWidth - WebGL drawing buffer width in device pixels.
  * @param {number} drawingBufferHeight - WebGL drawing buffer height in device pixels.
  * @param {number} pixelRatio - Device pixel ratio relating CSS pixels to device pixels.
- * @returns {{ x: number; y: number } | null} Screen-space coordinates or `null` when invalid.
- */
-export declare const clipToScreen: (clipPosition: readonly [number, number, number, number], drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => {
-    x: number;
-    y: number;
-} | null;
-/**
- * Index order used to decompose a quad into two triangles.
- * @constant
- */
-export declare const TRIANGLE_INDICES: readonly [0, 1, 2, 2, 1, 3];
-/**
- * UV coordinates for each corner of a quad following the index order in {@link TRIANGLE_INDICES}.
- * @constant
+ * @returns {SpriteScreenPoint | null} Screen-space coordinates or `null` when invalid.
  */
-export declare const UV_CORNERS: ReadonlyArray<readonly [number, number]>;
+export declare const clipToScreen: (clipPosition: readonly [number, number, number, number], drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => SpriteScreenPoint | null;
 /**
  * Calculates the conversion factor between meters and pixels taking perspective into account.
  * @param {number} metersPerPixelAtLatitude - Meters covered by a single pixel at the sprite latitude.
@@ -221,34 +197,26 @@ export declare const calculateEffectivePixelsPerMeter: (metersPerPixelAtLatitude
 /**
  * Projects a geographic coordinate and elevation into homogeneous clip space.
  * @typedef ProjectToClipSpaceFn
- * @param {number} lng - Longitude in degrees.
- * @param {number} lat - Latitude in degrees.
- * @param {number} elevationMeters - Elevation offset in meters.
+ * @param {number} location - Location in degrees.
  * @returns {[number, number, number, number] | null} Homogeneous clip coordinates or `null` when outside the view.
  */
-export type ProjectToClipSpaceFn = (lng: number, lat: number, elevationMeters: number) => [number, number, number, number] | null;
+export type ProjectToClipSpaceFn = (location: Readonly<SpriteLocation>) => [number, number, number, number] | null;
 /**
  * Unprojects a screen-space point back to longitude/latitude.
  * @typedef UnprojectPointFn
- * @param {{ x: number; y: number }} point - Screen-space coordinates in pixels.
+ * @param {SpriteScreenPoint} point - Screen-space coordinates in pixels.
  * @returns {SpriteLocation | null} Geographic location or `null` when unprojection fails.
  */
-export type UnprojectPointFn = (point: {
-    x: number;
-    y: number;
-}) => SpriteLocation | null;
+export type UnprojectPointFn = (point: Readonly<SpriteScreenPoint>) => SpriteLocation | null;
 /**
  * Resolves a depth key for billboards by sampling the clip-space Z at the sprite center.
- * @param {{ x: number; y: number }} center - Screen-space center of the billboard in pixels.
+ * @param {SpriteScreenPoint} center - Screen-space center of the billboard in pixels.
  * @param {SpriteLocation} spriteLocation - Geographic location including optional altitude.
  * @param {UnprojectPointFn} unproject - Function for converting screen coordinates to geographic coordinates.
  * @param {ProjectToClipSpaceFn} projectToClipSpace - Function that projects a geographic coordinate to clip space.
  * @returns {number | null} Negative normalized device coordinate Z used for depth sorting, or `null` when unavailable.
  */
-export declare const calculateBillboardDepthKey: (center: {
-    x: number;
-    y: number;
-}, spriteLocation: SpriteLocation, unproject: UnprojectPointFn, projectToClipSpace: ProjectToClipSpaceFn) => number | null;
+export declare const calculateBillboardDepthKey: (center: Readonly<SpriteScreenPoint>, unproject: UnprojectPointFn, projectToClipSpace: ProjectToClipSpaceFn) => number | null;
 /**
  * Signature for surface depth bias callbacks that tweak clip-space Z/W.
  * @typedef SurfaceDepthBiasFn
@@ -267,12 +235,11 @@ export type SurfaceDepthBiasFn = (params: {
  * Computes a depth key for surface quads by projecting each corner and tracking the deepest point.
  * @param {SpriteLocation} baseLngLat - Base longitude/latitude of the quad center.
  * @param {readonly SurfaceCorner[]} displacements - Corner offsets in meters from the center.
- * @param {SpriteLocation} spriteLocation - Sprite world location including optional altitude.
  * @param {ProjectToClipSpaceFn} projectToClipSpace - Projection function used to reach clip space.
  * @param {{ readonly indices?: readonly number[]; readonly biasFn?: SurfaceDepthBiasFn }} [options] - Optional overrides.
  * @returns {number | null} Depth key suitable for sorting, or `null` when any corner cannot be projected.
  */
-export declare const calculateSurfaceDepthKey: (baseLngLat: SpriteLocation, displacements: readonly SurfaceCorner[], spriteLocation: SpriteLocation, projectToClipSpace: ProjectToClipSpaceFn, options?: {
+export declare const calculateSurfaceDepthKey: (baseLngLat: Readonly<SpriteLocation>, displacements: readonly SurfaceCorner[], projectToClipSpace: ProjectToClipSpaceFn, options?: {
     readonly indices?: readonly number[];
     readonly biasFn?: SurfaceDepthBiasFn;
 }) => number | null;
@@ -280,16 +247,13 @@ export declare const calculateSurfaceDepthKey: (baseLngLat: SpriteLocation, disp
  * Projects a longitude/latitude pair to screen-space pixels.
  * @typedef ProjectLngLatFn
  * @param {SpriteLocation} lngLat - Geographic coordinate to project.
- * @returns {{ x: number; y: number } | null} Screen coordinates or `null` when projection fails.
+ * @returns {SpriteScreenPoint | null} Screen coordinates or `null` when projection fails.
  */
-export type ProjectLngLatFn = (lngLat: SpriteLocation) => {
-    x: number;
-    y: number;
-} | null;
+export type ProjectLngLatFn = (lngLat: Readonly<SpriteLocation>) => SpriteScreenPoint | null;
 /**
  * Parameters required to resolve a billboard center position.
  * @typedef BillboardCenterParams
- * @property {{ x: number; y: number }} base - Reference screen-space position (usually anchor point).
+ * @property {SpriteScreenPoint} base - Reference screen-space position (usually anchor point).
  * @property {number} [imageWidth] - Source bitmap width in pixels.
  * @property {number} [imageHeight] - Source bitmap height in pixels.
  * @property {number} baseMetersPerPixel - Meters represented by a pixel at the sprite latitude.
@@ -302,11 +266,8 @@ export type ProjectLngLatFn = (lngLat: SpriteLocation) => {
  * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
  * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
  */
-export type BillboardCenterParams = {
-    base: {
-        x: number;
-        y: number;
-    };
+export interface BillboardCenterParams {
+    base: Readonly<SpriteScreenPoint>;
     imageWidth?: number;
     imageHeight?: number;
     baseMetersPerPixel: number;
@@ -316,37 +277,29 @@ export type BillboardCenterParams = {
     spriteMinPixel: number;
     spriteMaxPixel: number;
     totalRotateDeg: number;
-    anchor?: SpriteAnchor;
-    offset?: SpriteImageOffset;
-};
+    anchor?: Readonly<SpriteAnchor>;
+    offset?: Readonly<SpriteImageOffset>;
+}
 /**
  * Resolved properties describing the billboard center and derived dimensions.
  * @typedef BillboardCenterResult
- * @property {number} centerX - Screen-space x coordinate after offset adjustments.
- * @property {number} centerY - Screen-space y coordinate after offset adjustments.
+ * @property {SpriteScreenPoint} center - Screen-space coordinate after offset adjustments.
  * @property {number} halfWidth - Half of the clamped pixel width.
  * @property {number} halfHeight - Half of the clamped pixel height.
  * @property {number} pixelWidth - Full pixel width after scaling and clamping.
  * @property {number} pixelHeight - Full pixel height after scaling and clamping.
- * @property {{ x: number; y: number }} anchorShift - Pixel delta caused by anchor rotation.
- * @property {{ x: number; y: number }} offsetShift - Pixel delta caused by radial offset.
+ * @property {SpritePoint} anchorShift - Pixel delta caused by anchor rotation.
+ * @property {SpritePoint} offsetShift - Pixel delta caused by radial offset.
  */
-export type BillboardCenterResult = {
-    centerX: number;
-    centerY: number;
+export interface BillboardCenterResult {
+    center: SpriteScreenPoint;
     halfWidth: number;
     halfHeight: number;
     pixelWidth: number;
     pixelHeight: number;
-    anchorShift: {
-        x: number;
-        y: number;
-    };
-    offsetShift: {
-        x: number;
-        y: number;
-    };
-};
+    anchorShift: SpritePoint;
+    offsetShift: SpritePoint;
+}
 /**
  * Calculates the final billboard center position, applying scaling, anchor, and offset adjustments.
  * @param {BillboardCenterParams} params - Inputs describing sprite geometry and scaling context.
@@ -356,52 +309,43 @@ export declare const calculateBillboardCenterPosition: (params: BillboardCenterP
 /**
  * Parameters controlling how billboard corners are computed in screen space.
  * @typedef BillboardCornerParams
- * @property {number} centerX - Screen-space x coordinate for the billboard center after offsets.
- * @property {number} centerY - Screen-space y coordinate for the billboard center after offsets.
+ * @property {SpriteScreenPoint} center - Screen-space coordinate for the billboard center after offsets.
  * @property {number} halfWidth - Half of the billboard width in pixels.
  * @property {number} halfHeight - Half of the billboard height in pixels.
  * @property {SpriteAnchor} [anchor] - Optional anchor definition normalized between -1 and 1.
  * @property {number} totalRotateDeg - Total rotation applied to the billboard in degrees.
  */
-export type BillboardCornerParams = {
-    centerX: number;
-    centerY: number;
+export interface BillboardCornerParams {
+    center: Readonly<SpriteScreenPoint>;
     halfWidth: number;
     halfHeight: number;
-    anchor?: SpriteAnchor;
+    anchor?: Readonly<SpriteAnchor>;
     totalRotateDeg: number;
-};
+}
 /**
  * Screen-space coordinates combined with UV data for a quad corner.
  * @typedef QuadCorner
- * @property {number} x - Screen-space x coordinate.
- * @property {number} y - Screen-space y coordinate.
  * @property {number} u - Texture u coordinate.
  * @property {number} v - Texture v coordinate.
  */
-export type QuadCorner = {
-    x: number;
-    y: number;
-    u: number;
-    v: number;
-};
+export interface QuadCorner extends SpriteScreenPoint {
+    readonly u: number;
+    readonly v: number;
+}
 /**
  * Produces the rotated, anchor-adjusted screen-space positions for each billboard corner.
  * @param {BillboardCornerParams} params - Inputs describing the billboard geometry.
  * @returns {QuadCorner[]} Array containing screen- and texture-space information per corner.
  */
 export declare const calculateBillboardCornerScreenPositions: (params: BillboardCornerParams) => QuadCorner[];
-export type SurfaceShaderModelParams = {
-    baseLngLat: SpriteLocation;
+export interface SurfaceShaderModelParams {
+    baseLngLat: Readonly<SpriteLocation>;
     worldWidthMeters: number;
     worldHeightMeters: number;
-    anchor: SpriteAnchor;
+    anchor: Readonly<SpriteAnchor>;
     totalRotateDeg: number;
-    offsetMeters: {
-        east: number;
-        north: number;
-    };
-};
+    offsetMeters: Readonly<SurfaceCorner>;
+}
 export type SurfaceShaderCornerModel = SurfaceCorner & SpriteLocation;
 export declare const computeSurfaceCornerShaderModel: (params: SurfaceShaderModelParams) => SurfaceShaderCornerModel[];
 /**
@@ -424,19 +368,18 @@ export declare const computeSurfaceCornerShaderModel: (params: SurfaceShaderMode
  * @property {number} [drawingBufferWidth] - WebGL drawing buffer width in device pixels.
  * @property {number} [drawingBufferHeight] - WebGL drawing buffer height in device pixels.
  * @property {number} [pixelRatio] - Device pixel ratio relating CSS pixels to device pixels.
- * @property {number} [altitudeMeters] - Altitude used when projecting points into clip space.
  * @property {boolean} [resolveAnchorless] - When true, also computes the anchorless center.
  */
-export type SurfaceCenterParams = {
-    baseLngLat: SpriteLocation;
+export interface SurfaceCenterParams {
+    baseLngLat: Readonly<SpriteLocation>;
     imageWidth?: number;
     imageHeight?: number;
     baseMetersPerPixel: number;
     imageScale: number;
     zoomScaleFactor: number;
     totalRotateDeg: number;
-    anchor?: SpriteAnchor;
-    offset?: SpriteImageOffset;
+    anchor?: Readonly<SpriteAnchor>;
+    offset?: Readonly<SpriteImageOffset>;
     effectivePixelsPerMeter?: number;
     spriteMinPixel?: number;
     spriteMaxPixel?: number;
@@ -445,45 +388,32 @@ export type SurfaceCenterParams = {
     drawingBufferWidth?: number;
     drawingBufferHeight?: number;
     pixelRatio?: number;
-    altitudeMeters?: number;
     resolveAnchorless?: boolean;
-};
+}
 /**
  * Output describing the resolved surface center and displacement details.
  * @typedef SurfaceCenterResult
- * @property {{ x: number; y: number } | null} center - Projected screen coordinates or `null` when projection fails.
+ * @property {SpriteScreenPoint | null} center - Projected screen coordinates or `null` when projection fails.
  * @property {{ width: number; height: number; scaleAdjustment: number }} worldDimensions - Sprite dimensions in world meters.
- * @property {{ east: number; north: number }} totalDisplacement - Combined anchor and offset displacement in meters.
+ * @property {SurfaceCorner} totalDisplacement - Combined anchor and offset displacement in meters.
  * @property {SpriteLocation} displacedLngLat - Geographic coordinates after applying displacement.
- * @property {{ x: number; y: number } | null | undefined} [anchorlessCenter] - Anchorless screen coordinates when requested.
- * @property {{ east: number; north: number } | undefined} [anchorlessDisplacement] - Offset-only displacement when requested.
+ * @property {SpriteScreenPoint | null | undefined} [anchorlessCenter] - Anchorless screen coordinates when requested.
+ * @property {SurfaceCorner | undefined} [anchorlessDisplacement] - Offset-only displacement when requested.
  * @property {SpriteLocation | undefined} [anchorlessLngLat] - Anchorless geographic coordinate when requested.
  */
-export type SurfaceCenterResult = {
-    center: {
-        x: number;
-        y: number;
-    } | null;
-    worldDimensions: {
+export interface SurfaceCenterResult {
+    center: Readonly<SpriteScreenPoint> | null;
+    worldDimensions: Readonly<{
         width: number;
         height: number;
         scaleAdjustment: number;
-    };
-    totalDisplacement: {
-        east: number;
-        north: number;
-    };
-    displacedLngLat: SpriteLocation;
-    anchorlessCenter?: {
-        x: number;
-        y: number;
-    } | null;
-    anchorlessDisplacement?: {
-        east: number;
-        north: number;
-    };
-    anchorlessLngLat?: SpriteLocation;
-};
+    }>;
+    totalDisplacement: Readonly<SurfaceCorner>;
+    displacedLngLat: Readonly<SpriteLocation>;
+    anchorlessCenter?: Readonly<SpriteScreenPoint> | null;
+    anchorlessDisplacement?: Readonly<SurfaceCorner>;
+    anchorlessLngLat?: Readonly<SpriteLocation>;
+}
 /**
  * Calculates the projected center of a surface sprite and derives related world-space displacements.
  * @param {SurfaceCenterParams} params - Inputs describing the sprite geometry and projection context.
@@ -497,31 +427,40 @@ export declare const calculateSurfaceCenterPosition: (params: SurfaceCenterParam
  * @property {number} worldHeightMeters - Height of the sprite footprint in meters.
  * @property {SpriteAnchor} anchor - Anchor definition normalized between -1 and 1.
  * @property {number} totalRotateDeg - Rotation applied to the surface in degrees.
- * @property {{ east: number; north: number }} offsetMeters - Additional displacement applied uniformly to all corners.
+ * @property {SurfaceCorner} offsetMeters - Additional displacement applied uniformly to all corners.
  */
-export type SurfaceCornerParams = {
+export interface SurfaceCornerParams {
     worldWidthMeters: number;
     worldHeightMeters: number;
-    anchor: SpriteAnchor;
+    anchor: Readonly<SpriteAnchor>;
     totalRotateDeg: number;
-    offsetMeters: {
-        east: number;
-        north: number;
-    };
-};
+    offsetMeters: Readonly<SurfaceCorner>;
+}
 /**
  * East/north displacement for an individual surface corner.
  * @typedef SurfaceCorner
  * @property {number} east - Eastward offset in meters relative to the base center.
  * @property {number} north - Northward offset in meters relative to the base center.
  */
-export type SurfaceCorner = {
-    east: number;
-    north: number;
-};
+export interface SurfaceCorner {
+    readonly east: number;
+    readonly north: number;
+}
+/**
+ * Number of surface corners returns from `calculateSurfaceCornerDisplacements`.
+ */
+export declare const SURFACE_CORNER_DISPLACEMENT_COUNT: number;
 /**
  * Converts normalized surface corners into world-space displacements honoring anchor, rotation, and offsets.
  * @param {SurfaceCornerParams} params - Inputs describing quad geometry and positioning.
  * @returns {SurfaceCorner[]} Array of corner displacements in meters relative to the base center.
  */
 export declare const calculateSurfaceCornerDisplacements: (params: SurfaceCornerParams) => SurfaceCorner[];
+/**
+ * Ensures the sprite's cached Mercator coordinate matches its current location.
+ * Recomputes the coordinate lazily when longitude/latitude/altitude change.
+ * @param {ProjectionHost} projectionHost - Projection host.
+ * @param {InternalSpriteCurrentState<T>} sprite - Target sprite.
+ * @returns {SpriteMercatorCoordinate} Cached Mercator coordinate representing the current location.
+ */
+export declare const resolveSpriteMercator: <T>(projectionHost: ProjectionHost, sprite: InternalSpriteCurrentState<T>) => SpriteMercatorCoordinate;

package/dist/projectionHost.d.ts

@@ -0,0 +1,60 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.13.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
+ */
+
+import { mat4 as Mat4 } from 'gl-matrix';
+import { Map as MapLibreMap } from 'maplibre-gl';
+import { SpriteLocation } from './types';
+import { ClipContext, ProjectionHost } from './internalTypes';
+/**
+ * Required projection parameters. These correspond to the MapLibre transform state.
+ */
+export interface ProjectionHostParams {
+    readonly zoom: number;
+    readonly width: number;
+    readonly height: number;
+    readonly center: Readonly<SpriteLocation>;
+    readonly pitchDeg?: number;
+    readonly bearingDeg?: number;
+    readonly rollDeg?: number;
+    readonly fovDeg?: number;
+    readonly centerElevationMeters?: number;
+    readonly minElevationMeters?: number;
+    readonly cameraToCenterDistance?: number;
+    readonly centerOffsetX?: number;
+    readonly centerOffsetY?: number;
+    readonly tileSize?: number;
+    readonly autoCalculateNearFarZ?: boolean;
+    readonly nearZOverride?: number;
+    readonly farZOverride?: number;
+}
+export interface PreparedProjectionState {
+    readonly zoom: number;
+    readonly mercatorMatrix: Mat4 | null;
+    readonly pixelMatrix: Mat4 | null;
+    readonly pixelMatrixInverse: Mat4 | null;
+    readonly worldSize: number;
+    readonly pixelPerMeter: number;
+    readonly cameraToCenterDistance: number;
+    readonly clipContext: ClipContext | null;
+}
+export declare const prepareProjectionState: (params: ProjectionHostParams) => PreparedProjectionState;
+/**
+ * Create a pure calculation projection host.
+ * @param params Projection parameters
+ * @returns Projection host
+ */
+export declare const createProjectionHost: (params: ProjectionHostParams) => ProjectionHost;
+/**
+ * Extract current MapLibre transform parameters into {@link ProjectionHostParams}.
+ * Falls back to safe defaults when certain transform fields are unavailable.
+ * @param map MapLibre map instance.
+ * @returns Projection parameters usable by {@link createProjectionHost}.
+ */
+export declare const createProjectionHostParamsFromMapLibre: (map: MapLibreMap) => ProjectionHostParams;

package/dist/rotationInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.11.0
+ * version: 0.13.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
+ * git.commit.hash: 4934aa7f4fed93594ece419184b32b5b972bbb88
  */
 
 import { SpriteInterpolationOptions } from './types';