@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/shaders/helpers.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Shader helpers
+ *
+ * Utilities for creating and managing WebGL2 shaders
+ * Performs the WGS84 -> Mercator -> clip coordinate conversion on the GPU
+ */
+/**
+ * Converts WGS84 coordinates to Mercator coordinates (high precision
+ * computation on the CPU side)
+ */
+export declare function lngLatToMercator(lng: number, lat: number): [number, number];
+/**
+ * The shader prelude maplibre passes to the `prerender` / `render` of a custom layer, which
+ * the renderers of this library take to compile their programs for the current projection.
+ */
+export interface ShaderData {
+    /** The GLSL maplibre prepends to a vertex shader (its projection functions) */
+    vertexShaderPrelude: string;
+    /** The `#define` lines of the current projection */
+    define: string;
+    /** The name of the projection variant; a program is recompiled when it changes */
+    variantName: string;
+}
+/**
+ * The precision every sampler of the engine is read with
+ *
+ * GLSL ES 3.00 gives `sampler2D` no default precision other than lowp, in both stages, and a
+ * texture lookup returns the precision of its sampler. The engine reads coordinates (RGBA32F
+ * textures) and 24-bit fixed-point elevations through samplers, which lowp would quantize on
+ * GPUs that honour it, so every program declares highp for them. `createProgram` inserts the
+ * statement into both stages, so no shader source can leave it out.
+ */
+export declare const SAMPLER_PRECISION_GLSL = "precision highp sampler2D;";
+/**
+ * Gives a shader source the engine's sampler precision
+ *
+ * The statement goes right after the `#version 300 es` line (the directive must stay first).
+ * A source without that directive is returned unchanged. Repeating the statement in the source
+ * itself is harmless.
+ */
+export declare function withSamplerPrecision(source: string): string;
+/**
+ * Compiles and links a WebGL2 program from a vertex and a fragment shader source.
+ *
+ * Every program of the engine is compiled here, so the rules that apply to all of them live
+ * here: both stages are given highp samplers (`withSamplerPrecision`).
+ *
+ * @param gl The WebGL2 context
+ * @param vertexSource The vertex shader source, starting with `#version 300 es`
+ * @param fragmentSource The fragment shader source, starting with `#version 300 es`
+ * @returns The linked program
+ * @throws Error with the info log when a shader fails to compile or the program fails to link
+ */
+export declare function createProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string): WebGLProgram;
+/**
+ * Returns the declaration of `u_projection_transition` when a maplibre prelude lacks it.
+ *
+ * MapLibre's globe mode prelude defines u_projection_transition, but the
+ * Mercator mode does not. This function inspects the prelude and returns the
+ * uniform declaration only when it is needed.
+ *
+ * @param prelude MapLibre's vertexShaderPrelude
+ * @returns The uniform declaration (when needed) or an empty string
+ */
+export declare function getProjectionTransitionUniform(prelude: string): string;
+/**
+ * GLSL that reads the elevation (meters) from the DEM atlas
+ *
+ * Used by both the vertex shader (which lifts the vertices) and the fragment
+ * shader (which applies shading to the polygon fill; `terrain-shade.ts`).
+ * Because they share the same way of taking samples, the elevation the vertex
+ * picks up and the elevation the shading reads are always from the same
+ * surface.
+ *
+ * The uniforms end up declared in both stages, but declarations with the same
+ * name and type are bundled into one uniform, so the value only needs to be
+ * written once.
+ */
+export declare const DEM_SAMPLE_GLSL = "\nuniform float u_terrain_on;\nuniform sampler2D u_dem_atlas;\n// xy = the atlas origin (relative to the Mercator coordinates of the viewport center),\n// zw = 1/width, 1/height\nuniform vec4 u_dem_atlas_rect;\nuniform vec2 u_dem_atlas_size;\n// x = the meters -> Mercator z coefficient, y = the lift from the ground surface (meters)\nuniform vec2 u_elevation_params;\n\nfloat dem_decode(vec4 texel) {\n    return dot(texel.rgb * 255.0, vec3(65536.0, 256.0, 1.0)) / 16777216.0 * 65536.0 - 32768.0;\n}\n\n// Reads the elevation (meters) from the atlas with bilinear interpolation\n//\n// Our own subdivision points are placed exactly on the real mesh nodes of the terrain tiles\n// (view/terrain/tiling.ts). At the nodes, the value of the polyline surface MapLibre draws\n// and the bilinear value of the DEM agree, so here it is enough to read the DEM directly.\n// Only the points off the nodes (the vertices of the original feature, the points of its\n// outline) differ between the two, but that difference stays within the sag of a single\n// cell and can be covered by the depth bias.\nfloat dem_elevation_meters(vec2 mercatorOffset) {\n    vec2 uv = clamp((mercatorOffset - u_dem_atlas_rect.xy) * u_dem_atlas_rect.zw, 0.0, 1.0);\n    vec2 coord = uv * u_dem_atlas_size - 0.5;\n    vec2 f = fract(coord);\n    ivec2 c = ivec2(floor(coord));\n    ivec2 hi = ivec2(u_dem_atlas_size) - 1;\n    float tl = dem_decode(texelFetch(u_dem_atlas, clamp(c, ivec2(0), hi), 0));\n    float tr = dem_decode(texelFetch(u_dem_atlas, clamp(c + ivec2(1, 0), ivec2(0), hi), 0));\n    float bl = dem_decode(texelFetch(u_dem_atlas, clamp(c + ivec2(0, 1), ivec2(0), hi), 0));\n    float br = dem_decode(texelFetch(u_dem_atlas, clamp(c + ivec2(1, 1), ivec2(0), hi), 0));\n    return mix(mix(tl, tr, f.x), mix(bl, br, f.x), f.y);\n}\n";
+/**
+ * The GLSL functions that project positions relative to the view center (offset mode), with
+ * globe support; include it in a vertex shader after the maplibre prelude.
+ *
+ * To solve the coordinate precision problem (jitter), it uses the same
+ * approach as deck.gl's project module. The projection functions below include
+ * a port from deck.gl. See THIRD_PARTY_NOTICES.md for the source and the
+ * copyright notice.
+ * In globe mode, MapLibre's projectTile() is used.
+ *
+ * The essential points:
+ * 1. Do not add Mercator coordinates inside the shader
+ * 2. Handle only relative coordinates (offsets) in the shader
+ * 3. Compute the clip coordinates of the center at 64-bit precision on the CPU
+ *    side and add them at the end
+ *
+ * The computation flow:
+ * 1. position.xyz -= coordinateOrigin  // make it relative (Float32 is enough)
+ * 2. offset = project_offset(position) // convert degrees -> Mercator units
+ * 3. gl_Position = viewProjectionMatrix * offset + projectionCenter
+ *    ^ projectionCenter is computed at 64-bit precision on the CPU side
+ *
+ * Globe mode support:
+ * - When projectionTransition > 0, MapLibre's projectTile() is used
+ * - Globe mode is active at zoom < 12, where the precision problem does not
+ *   occur
+ * - In Mercator mode, the precision problem is solved by offset mode
+ *
+ * The uniforms used:
+ * - u_center_lnglat: the WGS84 coordinates of the viewport center (already
+ *   rounded to Float32)
+ * - u_projection_center: the center coordinates in clip space (computed at
+ *   64-bit precision on the CPU side)
+ * - u_units_per_degree: the conversion coefficient from degrees to Mercator
+ *   units (computed on the CPU side)
+ * - u_units_per_degree2: the non-linear correction coefficient (corrects the
+ *   variation due to latitude)
+ * - u_projection_transition: defined in MapLibre's prelude (0 = Mercator,
+ *   1 = globe)
+ *
+ * The uniforms for globe mode (defined in MapLibre's prelude):
+ * - u_projection_tile_mercator_coords: the Mercator coordinates of the tile
+ * - u_projection_clipping_plane: the clipping plane
+ * - u_projection_fallback_matrix: the fallback matrix
+ */
+export declare const OFFSET_MODE_GLSL: string;
+/**
+ * Computes the offset-mode uniforms for a view center, to pass to `setOffsetUniforms` of the
+ * renderers.
+ *
+ * The uniforms for globe mode are obtained directly from ProjectionData, so
+ * this function performs only the offset computation for the Mercator
+ * projection.
+ *
+ * @param centerLngLat The view center `[lng, lat]` in degrees
+ * @param mainMatrix MapLibre's projection matrix (column-major 4x4)
+ * @returns The uniform values for offset mode
+ */
+export declare function calculateOffsetUniforms(centerLngLat: [number, number], mainMatrix: Float32Array | number[]): OffsetUniforms;
+/**
+ * The projection matrix of the copy of the world moved east by `lngShift` degrees
+ *
+ * A view across the antimeridian draws the stored features a second time, moved by 360
+ * degrees. That copy is drawn as a virtual camera: the center moves by -lngShift (so every
+ * offset the CPU computes against it comes out shifted, in 64 bits) and the matrix moves by
+ * +lngShift (M' = M * T(lngShift / 360) in Mercator units), so the two cancel for the camera
+ * and the copy lands next to the stored one. Passing both to `calculateOffsetUniforms` gives
+ * the same projection center as the real camera, and the absolute path of the shader
+ * (projectTile at low zoom) moves by the same amount through the matrix. It is one formula
+ * for the CPU and the GPU.
+ *
+ * @param matrix The projection matrix (column-major 4x4)
+ * @param lngShift The shift in degrees of longitude (a multiple of 360)
+ * @returns The translated matrix (64-bit values)
+ */
+export declare function translateMatrixByLongitude(matrix: ArrayLike<number>, lngShift: number): number[];
+/**
+ * The uniform values for offset mode
+ *
+ * The uniforms for globe mode are obtained directly from ProjectionData, so
+ * this interface contains only the values needed for the offset computation of
+ * the Mercator projection.
+ */
+export interface OffsetUniforms {
+    /** The center coordinates (rounded to Float32, for sending to the shader) */
+    centerLngLat: [number, number];
+    /** The center coordinates (64-bit precision, for the offset computation on the CPU side) */
+    centerLngLat64: [number, number];
+    /**
+     * The Mercator coordinates of the center (a value computed at 64-bit
+     * precision)
+     *
+     * Used to restore the Mercator relative coordinates of a vertex to absolute
+     * coordinates when looking up the terrain DEM atlas. So that everything can
+     * be handled relatively, the atlas origin is also handed over relative to
+     * this value (absolute Mercator coordinates do not have enough digits in
+     * Float32).
+     */
+    centerMercator: [number, number];
+    /** The view center in clip space, computed at 64-bit precision */
+    projectionCenter: [number, number, number, number];
+    /** The Mercator units per degree of longitude and latitude at the center */
+    unitsPerDegree: [number, number, number];
+    /** The second-order correction of `unitsPerDegree` for the change with latitude */
+    unitsPerDegree2: [number, number, number];
+}
+/**
+ * Returns a position relative to the view center in degrees, computed at 64-bit precision
+ * so that it survives Float32.
+ *
+ * Used to solve the coordinate precision problem at high zoom levels.
+ * Converting absolute coordinates to Float32 loses precision, but relative
+ * coordinates (small values) keep enough precision even in Float32.
+ *
+ * @param lngLat The WGS84 coordinates [lng, lat]
+ * @param centerLngLat The center coordinates [lng, lat] (64-bit precision)
+ * @returns The relative coordinates [dLng, dLat] (Float32 has enough precision)
+ */
+export declare function calculateLngLatOffset(lngLat: [number, number], centerLngLat: [number, number]): [number, number];
+/**
+ * Viewport information
+ */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * The interface for the offset mode coordinate transform
+ */
+export interface OffsetModeTransform {
+    project: (lngLat: [number, number]) => {
+        x: number;
+        y: number;
+    };
+    unproject: (point: {
+        x: number;
+        y: number;
+    }) => {
+        lng: number;
+        lat: number;
+    };
+}
+/**
+ * Creates the offset mode coordinate transform (performs the same computation
+ * as the shader on the CPU side)
+ *
+ * The computation flow of the shader:
+ * 1. lngLatOffset = lngLat - u_center_lnglat
+ * 2. mercatorOffset = project_offset(lngLatOffset)
+ *    = lngLatOffset * (u_units_per_degree + u_units_per_degree2 * lngLatOffset.y)
+ * 3. clipPos = viewProjectionMatrix * vec4(mercatorOffset, 0) + u_projection_center
+ * 4. ndc = clipPos.xy / clipPos.w
+ * 5. screen = (ndc * 0.5 + 0.5) * viewport
+ *
+ * @param uniforms The uniform values for offset mode
+ * @param mainMatrix MapLibre's projection matrix
+ * @param viewport The viewport information
+ */
+export declare function createOffsetModeTransform(uniforms: OffsetUniforms, mainMatrix: Float32Array | number[], viewport: Viewport): OffsetModeTransform;