maplibre-gl-layers 0.15.0 → 0.17.0

package/dist/utils/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.15.0
+ * version: 0.17.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
+ * git.commit.hash: 9fe9aa30db6602d13643e32c94af39ae2b26b082
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpritePoint, SpriteScalingOptions, SpriteScreenPoint } from '../types';
@@ -40,21 +40,21 @@ export declare const normalizeAngleDeg: (angle: number) => number;
 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.
- * @property {number} zoomMin - Lowest zoom level at which scaling interpolation begins.
- * @property {number} zoomMax - Highest zoom level at which scaling interpolation ends.
- * @property {number} scaleMin - Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMin}.
- * @property {number} scaleMax - Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMax}.
- * @property {number} spriteMinPixel - Lower clamp for sprite size in pixels.
- * @property {number} spriteMaxPixel - Upper clamp for sprite size in pixels.
  */
 export interface ResolvedSpriteScalingOptions {
+    /** Effective number of meters represented by each rendered pixel. */
     metersPerPixel: number;
+    /** Lowest zoom level at which scaling interpolation begins. */
     zoomMin: number;
+    /** Highest zoom level at which scaling interpolation ends. */
     zoomMax: number;
+    /** Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMin}. */
     scaleMin: number;
+    /** Scale multiplier applied at {@link ResolvedSpriteScalingOptions.zoomMax}. */
     scaleMax: number;
+    /** Lower clamp for sprite size in pixels. */
     spriteMinPixel: number;
+    /** Upper clamp for sprite size in pixels. */
     spriteMaxPixel: number;
 }
 /**
@@ -203,25 +203,25 @@ export declare const calculateEffectivePixelsPerMeter: (metersPerPixelAtLatitude
  * Projects a geographic coordinate and elevation into homogeneous clip space.
  * @typedef ProjectToClipSpaceFn
  * @param {number} location - Location in degrees.
- * @returns {[number, number, number, number] | null} Homogeneous clip coordinates or `null` when outside the view.
+ * @returns {[number, number, number, number] | undefined} Homogeneous clip coordinates or `undefined` when outside the view.
  */
-export type ProjectToClipSpaceFn = (location: Readonly<SpriteLocation>) => [number, number, number, number] | null;
+export type ProjectToClipSpaceFn = (location: Readonly<SpriteLocation>) => [number, number, number, number] | undefined;
 /**
  * Unprojects a screen-space point back to longitude/latitude.
  * @typedef UnprojectPointFn
  * @param {SpriteScreenPoint} point - Screen-space coordinates in pixels.
- * @returns {SpriteLocation | null} Geographic location or `null` when unprojection fails.
+ * @returns {SpriteLocation | undefined} Geographic location or `undefined` when unprojection fails.
  */
-export type UnprojectPointFn = (point: Readonly<SpriteScreenPoint>) => SpriteLocation | null;
+export type UnprojectPointFn = (point: Readonly<SpriteScreenPoint>) => SpriteLocation | undefined;
 /**
  * Resolves a depth key for billboards by sampling the clip-space Z at the sprite center.
  * @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.
+ * @returns {number | undefined} Negative normalized device coordinate Z used for depth sorting, or `undefined` when unavailable.
  */
-export declare const calculateBillboardDepthKey: (center: Readonly<SpriteScreenPoint>, unproject: UnprojectPointFn, projectToClipSpace: ProjectToClipSpaceFn) => number | null;
+export declare const calculateBillboardDepthKey: (center: Readonly<SpriteScreenPoint>, unproject: UnprojectPointFn, projectToClipSpace: ProjectToClipSpaceFn) => number | undefined;
 /**
  * Signature for surface depth bias callbacks that tweak clip-space Z/W.
  * @typedef SurfaceDepthBiasFn
@@ -242,68 +242,68 @@ export type SurfaceDepthBiasFn = (params: {
  * @param {readonly SurfaceCorner[]} displacements - Corner offsets in meters from the center.
  * @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.
+ * @returns {number | undefined} Depth key suitable for sorting, or `undefined` when any corner cannot be projected.
  */
 export declare const calculateSurfaceDepthKey: (baseLngLat: Readonly<SpriteLocation>, displacements: readonly SurfaceCorner[], projectToClipSpace: ProjectToClipSpaceFn, options?: {
     readonly indices?: readonly number[];
     readonly biasFn?: SurfaceDepthBiasFn;
-}) => number | null;
+}) => number | undefined;
 /**
  * Projects a longitude/latitude pair to screen-space pixels.
  * @typedef ProjectLngLatFn
  * @param {SpriteLocation} lngLat - Geographic coordinate to project.
- * @returns {SpriteScreenPoint | null} Screen coordinates or `null` when projection fails.
+ * @returns {SpriteScreenPoint | undefined} Screen coordinates or `undefined` when projection fails.
  */
-export type ProjectLngLatFn = (lngLat: Readonly<SpriteLocation>) => SpriteScreenPoint | null;
+export type ProjectLngLatFn = (lngLat: Readonly<SpriteLocation>) => SpriteScreenPoint | undefined;
 /**
  * Parameters required to resolve a billboard center position.
- * @typedef BillboardCenterParams
- * @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.
- * @property {number} imageScale - User-provided scaling multiplier.
- * @property {number} zoomScaleFactor - Zoom-dependent scale multiplier.
- * @property {number} effectivePixelsPerMeter - Pixels per meter after perspective adjustments.
- * @property {number} spriteMinPixel - Lower clamp for the sprite's largest pixel dimension.
- * @property {number} spriteMaxPixel - Upper clamp for the sprite's largest pixel dimension.
- * @property {number} totalRotateDeg - Aggregate rotation applied to the sprite in degrees.
- * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
- * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
  */
 export interface BillboardCenterParams {
+    /** Reference screen-space position (usually anchor point). */
     base: Readonly<SpriteScreenPoint>;
+    /** Source bitmap width in pixels. */
     imageWidth?: number;
+    /** Source bitmap height in pixels. */
     imageHeight?: number;
+    /** Meters represented by a pixel at the sprite latitude. */
     baseMetersPerPixel: number;
+    /** User-provided scaling multiplier. */
     imageScale: number;
+    /** Zoom-dependent scale multiplier. */
     zoomScaleFactor: number;
+    /** Pixels per meter after perspective adjustments. */
     effectivePixelsPerMeter: number;
+    /** Lower clamp for the sprite's largest pixel dimension. */
     spriteMinPixel: number;
+    /** Upper clamp for the sprite's largest pixel dimension. */
     spriteMaxPixel: number;
+    /** Aggregate rotation applied to the sprite in degrees. */
     totalRotateDeg: number;
+    /** Anchor definition normalized between -1 and 1. */
     anchor?: Readonly<SpriteAnchor>;
+    /** Offset definition applied in meters/deg. */
     offset?: Readonly<SpriteImageOffset>;
 }
 /**
  * Resolved properties describing the billboard center and derived dimensions.
- * @typedef BillboardCenterResult
- * @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 {SpritePoint} anchorShift - Pixel delta caused by anchor rotation.
- * @property {SpritePoint} offsetShift - Pixel delta caused by radial offset.
  */
 export interface BillboardCenterResult {
+    /** Screen-space coordinate after offset adjustments. */
     center: SpriteScreenPoint;
+    /** Half of the clamped pixel width. */
     halfWidth: number;
+    /** Half of the clamped pixel height. */
     halfHeight: number;
+    /** Full pixel width after scaling and clamping. */
     pixelWidth: number;
+    /** Full pixel height after scaling and clamping. */
     pixelHeight: number;
+    /** Pixel delta caused by anchor rotation. */
     anchorShift: SpritePoint;
+    /** Pixel delta caused by radial offset. */
     offsetShift: SpritePoint;
+    /** Scaling adjustment applied during pixel dimension calculation. */
+    scaleAdjustment: number;
 }
 /**
  * Calculates the final billboard center position, applying scaling, anchor, and offset adjustments.
@@ -313,28 +313,26 @@ export interface BillboardCenterResult {
 export declare const calculateBillboardCenterPosition: (params: BillboardCenterParams) => BillboardCenterResult;
 /**
  * Parameters controlling how billboard corners are computed in screen space.
- * @typedef BillboardCornerParams
- * @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 interface BillboardCornerParams {
+    /** Screen-space coordinate for the billboard center after offsets. */
     center: Readonly<SpriteScreenPoint>;
+    /** Half of the billboard width in pixels. */
     halfWidth: number;
+    /** Half of the billboard height in pixels. */
     halfHeight: number;
+    /** Optional anchor definition normalized between -1 and 1. */
     anchor?: Readonly<SpriteAnchor>;
+    /** Total rotation applied to the billboard in degrees. */
     totalRotateDeg: number;
 }
 /**
  * Screen-space coordinates combined with UV data for a quad corner.
- * @typedef QuadCorner
- * @property {number} u - Texture u coordinate.
- * @property {number} v - Texture v coordinate.
  */
 export interface QuadCorner extends SpriteScreenPoint {
+    /** Texture u coordinate. */
     readonly u: number;
+    /** Texture v coordinate. */
     readonly v: number;
 }
 /**
@@ -355,68 +353,66 @@ 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
- * @property {SpriteLocation} baseLngLat - Base geographic location of the sprite.
- * @property {number} [imageWidth] - Source bitmap width in pixels.
- * @property {number} [imageHeight] - Source bitmap height in pixels.
- * @property {number} baseMetersPerPixel - Base meters per pixel at the sprite latitude.
- * @property {number} imageScale - User-provided scaling multiplier.
- * @property {number} zoomScaleFactor - Zoom-dependent scale multiplier.
- * @property {number} totalRotateDeg - Rotation applied to the sprite in degrees.
- * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
- * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
- * @property {number} [effectivePixelsPerMeter] - Conversion rate from meters to on-screen pixels.
- * @property {number} [spriteMinPixel] - Lower clamp for the sprite's largest pixel dimension.
- * @property {number} [spriteMaxPixel] - Upper clamp for the sprite's largest pixel dimension.
- * @property {ProjectLngLatFn} [project] - Projection function mapping longitude/latitude to screen space.
- * @property {ProjectToClipSpaceFn} [projectToClipSpace] - Projection into clip space when available.
- * @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 {boolean} [resolveAnchorless] - When true, also computes the anchorless center.
  */
 export interface SurfaceCenterParams {
+    /** Base geographic location of the sprite. */
     baseLngLat: Readonly<SpriteLocation>;
+    /** Source bitmap width in pixels. */
     imageWidth?: number;
+    /** Source bitmap height in pixels. */
     imageHeight?: number;
+    /** Base meters per pixel at the sprite latitude. */
     baseMetersPerPixel: number;
+    /** User-provided scaling multiplier. */
     imageScale: number;
+    /** Zoom-dependent scale multiplier. */
     zoomScaleFactor: number;
+    /** Rotation applied to the sprite in degrees. */
     totalRotateDeg: number;
+    /** Anchor definition normalized between -1 and 1. */
     anchor?: Readonly<SpriteAnchor>;
+    /** Offset definition applied in meters/deg. */
     offset?: Readonly<SpriteImageOffset>;
+    /** Conversion rate from meters to on-screen pixels. */
     effectivePixelsPerMeter?: number;
+    /** Lower clamp for the sprite's largest pixel dimension. */
     spriteMinPixel?: number;
+    /** Upper clamp for the sprite's largest pixel dimension. */
     spriteMaxPixel?: number;
+    /** Projection function mapping longitude/latitude to screen space. */
     project?: ProjectLngLatFn;
+    /** Projection into clip space when available. */
     projectToClipSpace?: ProjectToClipSpaceFn;
+    /** WebGL drawing buffer width in device pixels. */
     drawingBufferWidth?: number;
+    /** WebGL drawing buffer height in device pixels. */
     drawingBufferHeight?: number;
+    /** Device pixel ratio relating CSS pixels to device pixels. */
     pixelRatio?: number;
+    /** When true, also computes the anchorless center. */
     resolveAnchorless?: boolean;
 }
 /**
  * Output describing the resolved surface center and displacement details.
- * @typedef SurfaceCenterResult
- * @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 {SurfaceCorner} totalDisplacement - Combined anchor and offset displacement in meters.
- * @property {SpriteLocation} displacedLngLat - Geographic coordinates after applying displacement.
- * @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 interface SurfaceCenterResult {
-    center: Readonly<SpriteScreenPoint> | null;
+    /** Projected screen coordinates or `undefined` when projection fails. */
+    center: Readonly<SpriteScreenPoint> | undefined;
+    /** Sprite dimensions in world meters. */
     worldDimensions: Readonly<{
         width: number;
         height: number;
         scaleAdjustment: number;
     }>;
+    /** Combined anchor and offset displacement in meters. */
     totalDisplacement: Readonly<SurfaceCorner>;
+    /** Geographic coordinates after applying displacement. */
     displacedLngLat: Readonly<SpriteLocation>;
+    /** Anchorless screen coordinates when requested. */
     anchorlessCenter?: Readonly<SpriteScreenPoint> | null;
+    /** Offset-only displacement when requested. */
     anchorlessDisplacement?: Readonly<SurfaceCorner>;
+    /** Anchorless geographic coordinate when requested. */
     anchorlessLngLat?: Readonly<SpriteLocation>;
 }
 /**
@@ -427,28 +423,26 @@ export interface SurfaceCenterResult {
 export declare const calculateSurfaceCenterPosition: (params: SurfaceCenterParams) => SurfaceCenterResult;
 /**
  * Parameters describing how to compute each surface corner displacement.
- * @typedef SurfaceCornerParams
- * @property {number} worldWidthMeters - Width of the sprite footprint in meters.
- * @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 {SurfaceCorner} offsetMeters - Additional displacement applied uniformly to all corners.
  */
 export interface SurfaceCornerParams {
+    /** Width of the sprite footprint in meters. */
     worldWidthMeters: number;
+    /** Height of the sprite footprint in meters. */
     worldHeightMeters: number;
+    /** Anchor definition normalized between -1 and 1. */
     anchor: Readonly<SpriteAnchor>;
+    /** Rotation applied to the surface in degrees. */
     totalRotateDeg: number;
+    /** Additional displacement applied uniformly to all corners. */
     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 interface SurfaceCorner {
+    /** Eastward offset in meters relative to the base center. */
     readonly east: number;
+    /** Northward offset in meters relative to the base center. */
     readonly north: number;
 }
 /**

package/dist/utils/utils.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.15.0
+ * version: 0.17.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
+ * git.commit.hash: 9fe9aa30db6602d13643e32c94af39ae2b26b082
  */
 
 import { ImageHandleBufferController, IdHandler, RenderTargetBucketBuffers, RenderTargetEntryLike, SpriteOriginReference } from '../internalTypes';

package/dist/wasm/config.json.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.15.0
+ * version: 0.17.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
+ * git.commit.hash: 9fe9aa30db6602d13643e32c94af39ae2b26b082
  */
 
 declare const _default: {

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.15.0"
+      "0.17.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.15.0",
+    "version": "0.17.0",
     "commit": {
-      "hash": "d850b7e9c713f54f0630248dc4ea370721b6965b",
-      "shortHash": "d850b7e",
-      "date": "2025-11-15T21:29:11+09:00Z",
+      "hash": "9fe9aa30db6602d13643e32c94af39ae2b26b082",
+      "shortHash": "9fe9aa3",
+      "date": "2025-11-20T13:44:53+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.15.0",
+  "version": "0.17.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",