maplibre-gl-layers 0.11.0 → 0.12.0

package/README.md

@@ -25,7 +25,10 @@ Here is a minimal example that places a single sprite:
 ```typescript
 // Use MapLibre GL JS together with maplibre-gl-layers
 import { Map } from 'maplibre-gl';
-import { createSpriteLayer } from 'maplibre-gl-layers';
+import {
+  createSpriteLayer,
+  initializeSpriteLayerHost,
+} from 'maplibre-gl-layers';
 
 // Create the MapLibre instance
 const map = new Map({
@@ -38,8 +41,10 @@ const map = new Map({
 // Create the SpriteLayer
 const spriteLayer = createSpriteLayer({ id: 'vehicles' });
 
-// Add the layer after the map finishes loading
+// When MapLibre is ready
 map.on('load', async () => {
+  // Optional: enable WASM acceleration (falls back to JS when unavailable)
+  await initializeSpriteLayerHost();
   map.addLayer(spriteLayer);
 
   // Register an image that can be referenced by sprites

package/dist/SpriteLayer.d.ts

@@ -1,44 +1,17 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.11.0
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
  */
 
-import { Map as MapLibreMap, MercatorCoordinate } from 'maplibre-gl';
-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.
- * @param {MapLibreMap} mapInstance - MapLibre map providing the transform and camera distance.
- * @param {SpriteLocation} location - Location used to derive mercator coordinates for scaling.
- * @param {MercatorCoordinate | undefined} [cachedMercator] - Optional precomputed Mercator coordinate for the location.
- * @returns {number} Perspective ratio applied when scaling sprites; defaults to 1 if unavailable.
- */
-export declare const calculatePerspectiveRatio: (mapInstance: MapLibreMap, location: SpriteLocation, cachedMercator?: MercatorCoordinate) => number;
-/**
- * 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 multiplyMatrixAndVector: (matrix: MatrixInput, x: number, y: number, z: number, w: number) => [number, number, number, number];
-/**
- * Projects a longitude/latitude/elevation tuple into clip space using the provided context.
- * @param {number} lng - Longitude in degrees.
- * @param {number} lat - Latitude in degrees.
- * @param {number} elevationMeters - Elevation above the ellipsoid in meters.
- * @param {ClipContext | null} context - Clip-space context; `null` skips projection.
- * @returns {[number, number, number, number] | null} Clip coordinates or `null` when projection fails.
- */
-export declare const projectLngLatToClipSpace: (lng: number, lat: number, elevationMeters: number, context: ClipContext | null) => [number, number, number, number] | null;
+import { SpriteLayerInterface, SpriteLayerOptions, SpriteAnchor, SpriteLocation, SpriteImageDefinitionInit, SpriteImageOffset, SpriteInterpolationOptions, SpriteLayerCalculationVariant } from './types';
+import { InternalSpriteImageState, InternalSpriteCurrentState, SpriteOriginReference } from './internalTypes';
+export declare const initializeSpriteLayerHost: (calculationVariant?: SpriteLayerCalculationVariant) => Promise<SpriteLayerCalculationVariant>;
+export declare const releaseSpriteLayerHost: () => void;
 /**
  * Applies auto-rotation to all images within a sprite when movement exceeds the configured threshold.
  * @template T Arbitrary sprite tag type.
@@ -47,24 +20,6 @@ export declare const projectLngLatToClipSpace: (lng: number, lat: number, elevat
  * @returns {boolean} `true` when auto-rotation was applied, `false` otherwise.
  */
 export declare const applyAutoRotation: <T>(sprite: InternalSpriteCurrentState<T>, nextLocation: SpriteLocation) => boolean;
-/**
- * Compiles a shader from source, throwing if compilation fails.
- * @param {WebGLRenderingContext} glContext - Active WebGL context.
- * @param {number} type - Shader type (`VERTEX_SHADER` or `FRAGMENT_SHADER`).
- * @param {string} source - GLSL source code.
- * @returns {WebGLShader} Compiled shader object.
- * @throws When shader creation or compilation fails.
- */
-export declare const compileShader: (glContext: WebGLRenderingContext, type: number, source: string) => WebGLShader;
-/**
- * Links a vertex and fragment shader into a WebGL program.
- * @param {WebGLRenderingContext} glContext - Active WebGL context.
- * @param {string} vertexSource - Vertex shader GLSL source.
- * @param {string} fragmentSource - Fragment shader GLSL source.
- * @returns {WebGLProgram} Linked shader program ready for use.
- * @throws When linking fails or a program cannot be created.
- */
-export declare const createShaderProgram: (glContext: WebGLRenderingContext, vertexSource: string, fragmentSource: string) => WebGLProgram;
 /**
  * Clones a sprite anchor, defaulting to the origin when none supplied.
  * @param {SpriteAnchor} [anchor] - Anchor to clone.
@@ -88,9 +43,10 @@ export declare const cloneInterpolationOptions: (options: SpriteInterpolationOpt
  * @param {SpriteImageDefinitionInit} imageInit - Caller-provided image definition.
  * @param {number} subLayer - Sub-layer index the image belongs to.
  * @param {number} order - Ordering slot within the sub-layer.
+ * @param {SpriteOriginReference} originReference - Encode/Decode origin reference.
  * @returns {InternalSpriteImageState} Normalized internal state ready for rendering.
  */
-export declare const createImageStateFromInit: (imageInit: SpriteImageDefinitionInit, subLayer: number, order: number) => InternalSpriteImageState;
+export declare const createImageStateFromInit: (imageInit: SpriteImageDefinitionInit, subLayer: number, order: number, originReference: SpriteOriginReference) => InternalSpriteImageState;
 /**
  * Factory that creates the MapLibre layer interface for the sprite layer.
  * Implements the CustomLayerInterface lifecycle (init -> render -> dispose), packing thousands

package/dist/calculationHost.d.ts

@@ -0,0 +1,63 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+import { Map as MapLibreMap } from 'maplibre-gl';
+import { InternalSpriteCurrentState, InternalSpriteImageState, RegisteredImage, ProjectionHost, PreparedDrawSpriteImageParams, RenderCalculationHost, PrepareDrawSpriteImageParamsBefore, PrepareDrawSpriteImageParamsAfter } from './internalTypes';
+import { SpritePoint } from './types';
+import { ProjectionHostParams } from './projectionHost';
+/**
+ * Cache entry storing anchor-adjusted and raw centers for a sprite image.
+ */
+interface ImageCenterCacheEntry {
+    readonly anchorApplied?: SpritePoint;
+    readonly anchorless?: SpritePoint;
+}
+/**
+ * Nested cache keyed by sprite ID and image key to avoid recomputing centers each frame.
+ */
+type ImageCenterCache = Map<string, Map<string, ImageCenterCacheEntry>>;
+/**
+ * Resolves the image entry that a sprite should use as its origin reference when
+ * another image in the same render bucket needs to inherit that origin.
+ * The resolver is always invoked with the current sprite/image pair and can
+ * return `null` when the origin is not available (e.g., the reference was
+ * culled or stored in another bucket).
+ */
+type OriginImageResolver<T> = (sprite: Readonly<InternalSpriteCurrentState<T>>, image: Readonly<InternalSpriteImageState>) => InternalSpriteImageState | null;
+interface DepthSortedItem<T> {
+    readonly sprite: InternalSpriteCurrentState<T>;
+    readonly image: InternalSpriteImageState;
+    readonly resource: Readonly<RegisteredImage>;
+    readonly depthKey: number;
+    readonly resolveOrigin: OriginImageResolver<T>;
+}
+export declare const collectDepthSortedItemsInternal: <T>(projectionHost: ProjectionHost, zoom: number, zoomScaleFactor: number, originCenterCache: ImageCenterCache, { bucket, bucketBuffers, imageResources, clipContext, baseMetersPerPixel, spriteMinPixel, spriteMaxPixel, drawingBufferWidth, drawingBufferHeight, pixelRatio, }: PrepareDrawSpriteImageParamsBefore<T>) => DepthSortedItem<T>[];
+/**
+ * Prepares quad data for a single sprite image before issuing the draw call.
+ */
+export declare const prepareDrawSpriteImageInternal: <TTag>(projectionHost: ProjectionHost, item: DepthSortedItem<TTag>, zoom: number, zoomScaleFactor: number, originCenterCache: ImageCenterCache, { imageResources, baseMetersPerPixel, spriteMinPixel, spriteMaxPixel, drawingBufferWidth, drawingBufferHeight, pixelRatio, clipContext, identityScaleX, identityScaleY, identityOffsetX, identityOffsetY, screenToClipScaleX, screenToClipScaleY, screenToClipOffsetX, screenToClipOffsetY, }: PrepareDrawSpriteImageParamsAfter) => PreparedDrawSpriteImageParams<TTag> | null;
+/**
+ * Create calculation host that binding MapLibre.
+ * @param TTag Tag type.
+ * @param map MapLibre Map.
+ * @returns Calculation host.
+ */
+export declare const createMapLibreCalculationHost: <TTag>(map: MapLibreMap) => RenderCalculationHost<TTag>;
+/**
+ * Create calculation host that pure implementation.
+ * @param TTag Tag type.
+ * @param params Projection host PrepareDrawSpriteImageInputsparams.
+ * @returns Calculation host.
+ */
+export declare const createCalculationHost: <TTag>(params: ProjectionHostParams) => RenderCalculationHost<TTag>;
+export declare const __wasmProjectionCalculationTestInternals: {
+    __createWasmProjectionCalculationTestHost: <TTag>(params: ProjectionHostParams) => RenderCalculationHost<TTag>;
+};
+export {};

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+/** Debug flag */
+export declare const SL_DEBUG = false;
+/** Enables the upcoming shader-based billboard corner computation when true. */
+export declare const USE_SHADER_BILLBOARD_GEOMETRY = true;
+/** Enables the upcoming shader-based surface corner computation when true. */
+export declare const USE_SHADER_SURFACE_GEOMETRY = true;
+/** Whether to enable the NDC bias for surface rendering (disabled by default). */
+export declare const ENABLE_NDC_BIAS_SURFACE = true;

package/dist/const.d.ts

@@ -1,29 +1,67 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.11.0
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
  */
 
-import { SpriteScalingOptions, SpriteTextureFilteringOptions } from './types';
+import { Rect } from './looseQuadTree';
+import { SpriteAnchor, SpriteImageOffset, SpriteTextGlyphHorizontalAlign } from './types';
+/** Default sprite anchor centered at the image origin. */
+export declare const DEFAULT_ANCHOR: Readonly<SpriteAnchor>;
+/** Default image offset applied when none is provided. */
+export declare const DEFAULT_IMAGE_OFFSET: Readonly<SpriteImageOffset>;
+export declare const DEFAULT_TEXT_GLYPH_FONT_FAMILY = "sans-serif";
+export declare const DEFAULT_TEXT_GLYPH_FONT_STYLE: 'normal' | 'italic';
+export declare const DEFAULT_TEXT_GLYPH_FONT_WEIGHT = "normal";
+export declare const DEFAULT_TEXT_GLYPH_COLOR = "#000000";
+export declare const DEFAULT_TEXT_GLYPH_ALIGN: SpriteTextGlyphHorizontalAlign;
+export declare const DEFAULT_TEXT_GLYPH_FONT_SIZE = 32;
+export declare const DEFAULT_TEXT_GLYPH_RENDER_PIXEL_RATIO = 1;
 /**
- * Unlimited (default) values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
- * metersPerPixel is 1.
+ * WGS84-compatible Earth radius in meters.
+ * Used to convert one radian of longitude into meters when scaling sprites.
+ * @constant
  */
-export declare const UNLIMITED_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+export declare const EARTH_RADIUS_METERS = 6378137;
 /**
- * Standard values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
- * metersPerPixel is 1.
+ * Multiplier for converting degrees to radians.
+ * @constant
  */
-export declare const STANDARD_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+export declare const DEG2RAD: number;
 /**
- * Defaulted text filtering options.
+ * Multiplier for converting radians to degrees.
+ * @constant
  */
-export declare const DEFAULT_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
+export declare const RAD2DEG: number;
 /**
- * Better text filtering options than default options.
+ * Default MapLibre tile size used for Web Mercator calculations.
+ * @constant
  */
-export declare const BETTER_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
+export declare const TILE_SIZE = 512;
+export declare const MIN_CLIP_Z_EPSILON = 1e-7;
+/** Small depth bias applied in NDC space. */
+export declare const EPS_NDC = 0.000001;
+/** Maximum number of order slots available within a sub-layer (0..ORDER_MAX-1). */
+export declare const ORDER_MAX = 16;
+/** Bucket width used to encode sub-layer and order into a single number. */
+export declare const ORDER_BUCKET = 16;
+export declare const MIN_CLIP_W = 0.000001;
+export declare const HIT_TEST_WORLD_BOUNDS: Rect;
+/** Small tolerance used to handle floating-point error during hit testing. */
+export declare const HIT_TEST_EPSILON = 0.001;
+export declare const MAX_TEXT_GLYPH_RENDER_PIXEL_RATIO = 4;
+export declare const MIN_TEXT_GLYPH_FONT_SIZE = 4;
+/**
+ * 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
+ */
+export declare const UV_CORNERS: ReadonlyArray<readonly [number, number]>;

package/dist/default.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+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

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

package/dist/distanceInterpolation.d.ts

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

package/dist/easing.d.ts

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

package/dist/image.d.ts

@@ -0,0 +1,32 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.12.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: e8e2cd81aeec4b10f2898c0ede5880ac56bf748d
+ */
+
+import { SpriteImageRegisterOptions } from './types';
+export type SvgSizeResolutionErrorCode = 'size-missing' | 'viewbox-disabled' | 'invalid-dimensions';
+export declare class SvgSizeResolutionError extends Error implements Error {
+    readonly code: SvgSizeResolutionErrorCode;
+    constructor(message: string, code: SvgSizeResolutionErrorCode);
+}
+/**
+ * Helper that read an ImageBitmap from a blob.
+ * @param blob Target blob.
+ * @param options Optional reading options.
+ * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps reading SVG with better manner.
+ */
+export declare const readImageBitmap: (blob: Blob, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;
+/**
+ * Helper that loads an ImageBitmap from a URL.
+ * @param url Target image URL.
+ * @param options Optional loading options.
+ * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps loading SVG with better manner.
+ */
+export declare const loadImageBitmap: (url: string, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;