@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/renderers/line/line-uniforms.js

@@ -0,0 +1,390 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The renderer-specific uniforms of the SDF line program, with a record of the values written
+ * last
+ *
+ * The projection uniforms are handled by ProjectionUniformManager; this covers the line width,
+ * the zoom, the viewport, the miter limit, the coordinate texture, the subdivision count, the
+ * dash pattern, and the draw-time factors. Writes of the same value are skipped within a frame
+ * (see shaders/frame.ts).
+ */
+import { getDashPattern, RENDERING_DEFAULTS } from '../../../shared/math/index.js';
+import { getRenderFrame } from '../../shaders/frame.js';
+/**
+ * The uniform locations of one SDF line program and the values written to them last
+ *
+ * @internal
+ */
+export class LineUniforms {
+    constructor(gl) {
+        Object.defineProperty(this, "gl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: gl
+        });
+        // Uniform locations (renderer-specific)
+        // Color and opacity are instance attributes, so they have no uniforms
+        Object.defineProperty(this, "widthLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "viewportLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "miterLimitLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "coordTexLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "texSizeLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "dashArrayLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "dashEnabledLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "zoomLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "sizeScaleLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "opacityLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "stationsLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "stationMercatorLoc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // A record of the renderer-specific uniforms written last (for memoization within a frame)
+        //
+        // Retained mode passes through here once per chunk, but the viewport, the miter limit, and
+        // the sampler unit are invariant within a frame. Writes of the same value are skipped, and
+        // they are rewritten once the frame changes (see shaders/frame.ts).
+        Object.defineProperty(this, "memoViewportFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        Object.defineProperty(this, "memoViewportWidth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoViewportHeight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        Object.defineProperty(this, "memoWidth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoMiterLimit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoTexSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoStations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoStationMercator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoCoordTexUnit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoDashFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        Object.defineProperty(this, "memoDashEnabled", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoDashLength", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoDashGap", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoFactorsFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        Object.defineProperty(this, "memoSizeScale", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+        Object.defineProperty(this, "memoOpacity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: Number.NaN
+        });
+    }
+    /**
+     * Reads the uniform locations of a (re)created program and discards the record
+     *
+     * A recreated program also resets its uniforms to their initial values.
+     */
+    bind(program) {
+        this.widthLoc = this.gl.getUniformLocation(program, 'u_width');
+        this.viewportLoc = this.gl.getUniformLocation(program, 'u_viewport');
+        this.miterLimitLoc = this.gl.getUniformLocation(program, 'u_miter_limit');
+        this.coordTexLoc = this.gl.getUniformLocation(program, 'u_coord_tex');
+        this.texSizeLoc = this.gl.getUniformLocation(program, 'u_tex_size');
+        this.dashArrayLoc = this.gl.getUniformLocation(program, 'u_dashArray');
+        this.dashEnabledLoc = this.gl.getUniformLocation(program, 'u_dashEnabled');
+        this.zoomLoc = this.gl.getUniformLocation(program, 'u_zoom');
+        this.sizeScaleLoc = this.gl.getUniformLocation(program, 'u_size_scale');
+        this.opacityLoc = this.gl.getUniformLocation(program, 'u_opacity');
+        this.stationsLoc = this.gl.getUniformLocation(program, 'u_stations');
+        this.stationMercatorLoc = this.gl.getUniformLocation(program, 'u_station_mercator');
+        this.reset();
+    }
+    /**
+     * Discards the record of the values written last
+     */
+    reset() {
+        this.memoViewportFrame = -1;
+        this.memoViewportWidth = Number.NaN;
+        this.memoViewportHeight = Number.NaN;
+        this.memoFrame = -1;
+        this.memoWidth = Number.NaN;
+        this.memoZoom = Number.NaN;
+        this.memoMiterLimit = Number.NaN;
+        this.memoTexSize = Number.NaN;
+        this.memoStations = Number.NaN;
+        this.memoStationMercator = Number.NaN;
+        this.memoCoordTexUnit = Number.NaN;
+        this.memoDashFrame = -1;
+        this.memoDashEnabled = Number.NaN;
+        this.memoDashLength = Number.NaN;
+        this.memoDashGap = Number.NaN;
+        this.memoFactorsFrame = -1;
+        this.memoSizeScale = Number.NaN;
+        this.memoOpacity = Number.NaN;
+    }
+    /**
+     * Writes the viewport (not rewritten when the value is the same)
+     */
+    setViewport(width, height) {
+        if (!this.viewportLoc)
+            return;
+        const frame = getRenderFrame();
+        if (this.memoViewportFrame === frame &&
+            this.memoViewportWidth === width &&
+            this.memoViewportHeight === height) {
+            return;
+        }
+        this.gl.uniform2f(this.viewportLoc, width, height);
+        this.memoViewportWidth = width;
+        this.memoViewportHeight = height;
+        this.memoViewportFrame = frame;
+    }
+    /**
+     * Writes the uniforms for the line width, the zoom, the miter limit, and the coordinate
+     * texture (shared between immediate mode and retained mode; not rewritten when the value is
+     * the same)
+     *
+     * @param stations The number of parts a segment is split into (1 = not split)
+     * @param mercatorStations Whether the split points move along the Mercator plane (the
+     *   globe) rather than along the degrees (the terrain)
+     */
+    setLineDraw(width, zoomValue, texSize, stations, mercatorStations = false) {
+        const gl = this.gl;
+        const frame = getRenderFrame();
+        const staleFrame = this.memoFrame !== frame;
+        if (this.widthLoc && (staleFrame || this.memoWidth !== width)) {
+            gl.uniform1f(this.widthLoc, width);
+            this.memoWidth = width;
+        }
+        if (this.zoomLoc && (staleFrame || this.memoZoom !== zoomValue)) {
+            gl.uniform1f(this.zoomLoc, zoomValue);
+            this.memoZoom = zoomValue;
+        }
+        if (this.miterLimitLoc &&
+            (staleFrame || this.memoMiterLimit !== RENDERING_DEFAULTS.MITER_LIMIT)) {
+            gl.uniform1f(this.miterLimitLoc, RENDERING_DEFAULTS.MITER_LIMIT);
+            this.memoMiterLimit = RENDERING_DEFAULTS.MITER_LIMIT;
+        }
+        if (this.texSizeLoc && (staleFrame || this.memoTexSize !== texSize)) {
+            gl.uniform1f(this.texSizeLoc, texSize);
+            this.memoTexSize = texSize;
+        }
+        if (this.stationsLoc && (staleFrame || this.memoStations !== stations)) {
+            gl.uniform1f(this.stationsLoc, stations);
+            this.memoStations = stations;
+        }
+        const stationMercator = mercatorStations ? 1 : 0;
+        if (this.stationMercatorLoc && (staleFrame || this.memoStationMercator !== stationMercator)) {
+            gl.uniform1f(this.stationMercatorLoc, stationMercator);
+            this.memoStationMercator = stationMercator;
+        }
+        // The sampler unit (binding the texture is done by the caller every time)
+        if (this.coordTexLoc && (staleFrame || this.memoCoordTexUnit !== 0)) {
+            gl.uniform1i(this.coordTexLoc, 0);
+            this.memoCoordTexUnit = 0;
+        }
+        this.memoFrame = frame;
+    }
+    /**
+     * Writes the factors used at draw time
+     *
+     * Uniforms are per-program residual state, so paths that do not use the factors (immediate
+     * mode, the Store's retained rendering) always reset them to 1. If the value already written
+     * is the same, it is not rewritten.
+     */
+    setDrawFactors(factors) {
+        const gl = this.gl;
+        const frame = getRenderFrame();
+        const staleFrame = this.memoFactorsFrame !== frame;
+        if (this.sizeScaleLoc && (staleFrame || this.memoSizeScale !== factors.scale)) {
+            gl.uniform1f(this.sizeScaleLoc, factors.scale);
+            this.memoSizeScale = factors.scale;
+        }
+        if (this.opacityLoc && (staleFrame || this.memoOpacity !== factors.opacity)) {
+            gl.uniform1f(this.opacityLoc, factors.opacity);
+            this.memoOpacity = factors.opacity;
+        }
+        this.memoFactorsFrame = frame;
+    }
+    /**
+     * Sets the dash-related uniforms (shared between immediate mode and retained mode)
+     *
+     * They are not rewritten when the value is the same (lines in retained mode are always
+     * solid, so no matter how many chunks are drawn there is no need to rewrite "not dashed").
+     *
+     * @param pixelRatio Drawing-buffer px per CSS px (the ratio the cumulative distance of the
+     *   instances was written with)
+     */
+    setDash(shape, pixelRatio) {
+        const gl = this.gl;
+        const frame = getRenderFrame();
+        const staleFrame = this.memoDashFrame !== frame;
+        const dash = resolveDashUniform(shape, pixelRatio);
+        const dashEnabled = dash ? 1.0 : 0.0;
+        if (this.dashEnabledLoc && (staleFrame || this.memoDashEnabled !== dashEnabled)) {
+            gl.uniform1f(this.dashEnabledLoc, dashEnabled);
+            this.memoDashEnabled = dashEnabled;
+        }
+        if (dash && this.dashArrayLoc) {
+            const [dashLength, gapLength] = dash;
+            if (staleFrame || this.memoDashLength !== dashLength || this.memoDashGap !== gapLength) {
+                gl.uniform4fv(this.dashArrayLoc, dash);
+                this.memoDashLength = dashLength;
+                this.memoDashGap = gapLength;
+            }
+        }
+        this.memoDashFrame = frame;
+    }
+}
+/**
+ * The value of `u_dashArray` for a batch, or null when the line is solid
+ *
+ * The dash and the gap are given in CSS px and returned in drawing-buffer px
+ * (`[dash, gap, dash + gap, 0]`), the unit of the cumulative distance the vertex shader
+ * passes on (`v_linesofar`), so a dash keeps its length in CSS px at any zoom and latitude.
+ *
+ * @param pixelRatio Drawing-buffer px per CSS px
+ *
+ * @internal
+ */
+export function resolveDashUniform(shape, pixelRatio) {
+    const dashPattern = shape.dashArray ?? getDashPattern(shape.lineStyle);
+    if (shape.lineStyle === 'solid' || dashPattern.length < 2)
+        return null;
+    const dash = dashPattern[0] * pixelRatio;
+    const gap = dashPattern[1] * pixelRatio;
+    return [dash, gap, dash + gap, 0];
+}

package/dist/view/renderers/line/sdf-line.d.ts

@@ -0,0 +1,92 @@
+/**
+ * SDFLineRenderer
+ *
+ * High-quality line rendering using the HHAA (Half-plane Anti-Aliasing) approach
+ *
+ * Characteristics:
+ * - The CPU only passes geographic coordinates
+ * - The Mercator transform, projection, normal computation, and miter/bevel joins all run
+ *   on the GPU
+ * - A coordinate texture plus instancing draws multiple lines in one draw call
+ * - Offsets are computed in screen space, so the line width is always uniform
+ *
+ * The renderer class binds the parts together: the types (line-types.ts), the vertex data
+ * (line-geometry.ts), the GLSL sources (line-shader.ts), the uniforms (line-uniforms.ts), and
+ * the GL resources (line-gl.ts).
+ */
+import type { Map as MapLibreMap, ProjectionData } from 'maplibre-gl';
+import type { PixelRatioInput } from '../../../shared/utils/pixel-ratio.js';
+import type { OffsetUniforms, ShaderData } from '../../shaders/helpers.js';
+import { TerrainContext } from '../../terrain/context.js';
+import type { SDFStrokeOptions, SDFStrokeStyle } from './line-types.js';
+export type { Color, LineStyle, SDFStrokeOptions, SDFStrokeStyle, WidthUnit, } from './line-types.js';
+/**
+ * SDFLineRenderer
+ *
+ * Line rendering with the HHAA approach
+ */
+export declare class SDFLineRenderer {
+    private gl;
+    private program;
+    private variantName;
+    private quadVAO;
+    private quadVBO;
+    private immCoordTexture;
+    /** MAX_TEXTURE_SIZE of the context (read once, 0 = not read yet) */
+    private maxTextureSize;
+    /**
+     * Scratch arrays of the immediate draw of one line (grown, never shrunk)
+     *
+     * A frame of the immediate path draws every line in view one by one, and allocating two
+     * arrays per line puts the garbage collector under pressure on large data.
+     */
+    private scratchCoords;
+    private scratchInstances;
+    private immInstanceBuffer;
+    private isDrawing;
+    private frameCount;
+    private uniforms;
+    private projectionUniformManager;
+    private offsetUniforms;
+    /** The injected rendering ratio (read from window each time when not injected) */
+    private pixelRatio;
+    /** The terrain state of the draw instance this renderer belongs to */
+    private readonly terrain;
+    constructor(_map: MapLibreMap, gl: WebGL2RenderingContext, pixelRatio?: PixelRatioInput, terrain?: TerrainContext);
+    /**
+     * Initializes the fixed quad vertex buffer
+     */
+    private initBuffers;
+    /**
+     * Ensures the shader
+     */
+    ensureShader(shaderData: ShaderData): void;
+    /**
+     * Sets the uniforms for offset mode
+     */
+    setOffsetUniforms(uniforms: OffsetUniforms): void;
+    /**
+     * Sets the projection uniforms (supporting offset mode and globe mode)
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level (used to switch offset mode)
+     */
+    private setProjectionUniforms;
+    /** The largest side of a coordinate texture this GPU allows (MAX_TEXTURE_SIZE, read once) */
+    private textureSizeLimit;
+    /**
+     * Executes the draw call (processing shared by draw/drawBatch)
+     *
+     * The coordinate texture and the instance buffer use the persistent immediate-mode
+     * resources. Finish the upload into `immCoordTexture` and the `bufferData` into instanceBuffer
+     * before calling it.
+     */
+    private executeDrawCall;
+    /**
+     * Draws a line
+     */
+    draw(coords: Array<[number, number]>, style: SDFStrokeStyle, options: SDFStrokeOptions, zoom: number, projectionData?: ProjectionData): void;
+    /**
+     * Draws a closed path
+     */
+    drawClosed(coords: Array<[number, number]>, style: SDFStrokeStyle, options: Omit<SDFStrokeOptions, 'closed'>, zoom: number, projectionData?: ProjectionData): void;
+}