@sakuzu/maplibre-gl-draw 1.0.0

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

@@ -0,0 +1,567 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { resolveContentPixelRatio, resolvePixelRatio } from '../../../shared/utils/pixel-ratio.js';
+import { calculateOffsetUniforms, createProgram } from '../../shaders/helpers.js';
+import { ProjectionUniformManager } from '../../shaders/projection.js';
+import { TerrainContext } from '../../terrain/context.js';
+import { NEUTRAL_DRAW_FACTORS } from '../draw-factors.js';
+import { buildLineBatchArrays, buildPackedLineBatchArrays, defaultLineOrigin, growFloat32, INSTANCE_STRIDE, lineStationsOnMercatorPlane, maxInstanceSegmentMercator, normalizeOrigin, resolveLineStations, STATION_VERTICES, toLineInstanceColor, writeLineCoordTexels, writeLineInstances, } from './line-geometry.js';
+import { createRetainedLineBatch, deleteRetainedLineBatch, ImmediateCoordTexture, patchRetainedCoordTexels, releaseInstanceAttribs, setupInstanceAttribs, setupQuadAttribs, } from './line-gl.js';
+import { buildLineVertexSource, LINE_FRAGMENT_SOURCE } from './line-shader.js';
+import { LineUniforms } from './line-uniforms.js';
+/**
+ * SDFLineRenderer
+ *
+ * Line rendering with the HHAA approach
+ */
+export class SDFLineRenderer {
+    constructor(_map, gl, pixelRatio, terrain = new TerrainContext()) {
+        Object.defineProperty(this, "gl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "program", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "variantName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        // Buffers for instancing
+        Object.defineProperty(this, "quadVAO", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "quadVBO", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // GPU resources reused in immediate mode
+        Object.defineProperty(this, "immCoordTexture", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** MAX_TEXTURE_SIZE of the context (read once, 0 = not read yet) */
+        Object.defineProperty(this, "maxTextureSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * 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.
+         */
+        Object.defineProperty(this, "scratchCoords", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Float32Array(0)
+        });
+        Object.defineProperty(this, "scratchInstances", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Float32Array(0)
+        });
+        Object.defineProperty(this, "immInstanceBuffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // State tracking within a frame
+        // isDrawing: a flag for skipping the recomputation of the projection uniforms and the
+        // viewport setup
+        // Note: the program and the VAO may be changed by other renderers, so they are always rebound
+        Object.defineProperty(this, "isDrawing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "frameCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        // The renderer-specific uniforms and the record of the values written last
+        Object.defineProperty(this, "uniforms", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Projection uniform management (shared)
+        Object.defineProperty(this, "projectionUniformManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Stores the offset uniforms
+        Object.defineProperty(this, "offsetUniforms", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The injected rendering ratio (read from window each time when not injected) */
+        Object.defineProperty(this, "pixelRatio", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The terrain state of the draw instance this renderer belongs to */
+        Object.defineProperty(this, "terrain", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.gl = gl;
+        this.pixelRatio = pixelRatio;
+        this.terrain = terrain;
+        this.uniforms = new LineUniforms(gl);
+        this.immCoordTexture = new ImmediateCoordTexture(gl);
+        this.projectionUniformManager = new ProjectionUniformManager(gl, { surface: true, terrain });
+        this.initBuffers();
+    }
+    /**
+     * Initializes the fixed quad vertex buffer
+     */
+    initBuffers() {
+        const gl = this.gl;
+        this.quadVAO = gl.createVertexArray();
+        gl.bindVertexArray(this.quadVAO);
+        this.quadVBO = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.quadVBO);
+        gl.bufferData(gl.ARRAY_BUFFER, STATION_VERTICES, gl.STATIC_DRAW);
+        setupQuadAttribs(gl);
+        gl.bindVertexArray(null);
+        // The instance buffer for immediate mode (orphaned and reused on every draw)
+        this.immInstanceBuffer = gl.createBuffer();
+    }
+    /**
+     * Called at the start of a frame
+     *
+     * @internal
+     */
+    incrementFrame() {
+        this.frameCount++;
+    }
+    /**
+     * Begins drawing
+     *
+     * Sets the isDrawing flag to true and sets up the projection uniforms and the viewport.
+     * This lets subsequent draw()/drawBatch() calls skip those settings.
+     *
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     *
+     * @internal
+     */
+    beginDraw(projectionData, zoom) {
+        if (!this.program)
+            return;
+        const gl = this.gl;
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.quadVAO);
+        this.setProjectionUniforms(projectionData, zoom);
+        // Set the viewport size (the actual framebuffer size)
+        this.uniforms.setViewport(gl.drawingBufferWidth, gl.drawingBufferHeight);
+        this.isDrawing = true;
+    }
+    /**
+     * Ends drawing
+     *
+     * Resets the isDrawing flag to false.
+     * Calling it at the end of a frame makes the projection uniforms be set up again on the next
+     * frame.
+     *
+     * @internal
+     */
+    endDraw() {
+        if (!this.isDrawing)
+            return;
+        const gl = this.gl;
+        releaseInstanceAttribs(gl);
+        this.isDrawing = false;
+    }
+    /**
+     * Gets the cache statistics
+     *
+     * @internal
+     */
+    getCacheStats() {
+        return {
+            size: 0,
+            frameCount: this.frameCount,
+        };
+    }
+    /**
+     * Ensures the shader
+     */
+    ensureShader(shaderData) {
+        if (this.variantName !== shaderData.variantName) {
+            if (this.program) {
+                this.gl.deleteProgram(this.program);
+            }
+            this.program = createProgram(this.gl, buildLineVertexSource(shaderData.vertexShaderPrelude, shaderData.define), LINE_FRAGMENT_SOURCE);
+            this.variantName = shaderData.variantName;
+            // Get the renderer-specific uniform locations (this also discards the record of the
+            // values written last, since a recreated program resets its uniforms)
+            this.uniforms.bind(this.program);
+            // Get the projection-related uniform locations (shared)
+            this.projectionUniformManager.getLocations(this.program);
+        }
+    }
+    /**
+     * Sets the uniforms for offset mode
+     */
+    setOffsetUniforms(uniforms) {
+        this.offsetUniforms = uniforms;
+    }
+    /**
+     * 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)
+     */
+    setProjectionUniforms(projectionData, zoom) {
+        this.projectionUniformManager.setUniforms(projectionData, zoom, this.offsetUniforms);
+    }
+    /** The largest side of a coordinate texture this GPU allows (MAX_TEXTURE_SIZE, read once) */
+    textureSizeLimit() {
+        if (this.maxTextureSize === 0) {
+            const max = Number(this.gl.getParameter(this.gl.MAX_TEXTURE_SIZE));
+            this.maxTextureSize = Number.isFinite(max) && max > 0 ? max : 4096;
+        }
+        return this.maxTextureSize;
+    }
+    /**
+     * 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.
+     */
+    executeDrawCall(instanceCount, texSize, shape, zoom, projectionData, widthOverride, stations, factors = NEUTRAL_DRAW_FACTORS) {
+        const gl = this.gl;
+        // The program and the VAO may have been changed by other renderers, so always bind them
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.quadVAO);
+        // The projection uniforms and the viewport are skipped when beginDraw() already set them
+        // (a performance optimization)
+        if (!this.isDrawing) {
+            this.setProjectionUniforms(projectionData, zoom);
+            this.uniforms.setViewport(gl.drawingBufferWidth, gl.drawingBufferHeight);
+        }
+        // Set up the instance attributes (stride = 48 bytes = 12 floats)
+        // vertexAttribPointer records the current ARRAY_BUFFER binding, so it must always be
+        // called with the instance buffer bound
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.immInstanceBuffer);
+        setupInstanceAttribs(gl);
+        // Uniforms (color and opacity moved to instance attributes, so they are not here)
+        this.uniforms.setLineDraw(widthOverride, zoom, texSize, stations, lineStationsOnMercatorPlane(this.terrain));
+        // Always written (1 when the caller has none) so that no factor of an earlier draw is left
+        this.uniforms.setDrawFactors(factors);
+        // The coordinate texture (the sampler unit is written by LineUniforms.setLineDraw)
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.immCoordTexture.texture);
+        // The dash pattern
+        this.uniforms.setDash(shape, resolvePixelRatio(this.pixelRatio));
+        // Draw
+        gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 2 * (stations + 1), instanceCount);
+        if (!this.isDrawing) {
+            releaseInstanceAttribs(gl);
+        }
+    }
+    /**
+     * Draws a line
+     */
+    draw(coords, style, options, zoom, projectionData) {
+        if (!this.program || coords.length < 2 || !projectionData)
+            return;
+        const gl = this.gl;
+        // Get the rendering ratio (to convert CSS pixels into physical pixels)
+        //
+        // When there is a createdZoom (= the GPU scales with zoom), use the ratio without
+        // renderScale applied; for a fixed width drawn with u_width, use the ratio that includes
+        // renderScale (the "two ratios" in shared/utils/pixel-ratio.ts).
+        const screenDpr = resolvePixelRatio(this.pixelRatio);
+        const contentDpr = resolveContentPixelRatio(this.pixelRatio);
+        const n = coords.length;
+        // The texture size
+        const texSize = Math.max(2, Math.ceil(Math.sqrt(n)));
+        // Compute the relative coordinates on the CPU side (offset mode: computed at 64-bit
+        // precision)
+        const centerLngLat = this.offsetUniforms?.centerLngLat ?? [0, 0];
+        // The texture data (stores the relative coordinates). Only the first n texels are read,
+        // so what the reused array holds past them does not matter
+        this.scratchCoords = growFloat32(this.scratchCoords, texSize * texSize * 4);
+        const texData = this.scratchCoords.subarray(0, texSize * texSize * 4);
+        writeLineCoordTexels(texData, 0, coords, centerLngLat);
+        // Upload into the coordinate texture (the persistent texture is reused)
+        if (!this.immCoordTexture.upload(texData, texSize, this.textureSizeLimit()))
+            return;
+        // The instance data (12 floats per instance: indices(4) + extra(4) + color(4))
+        const instanceCount = n - 1;
+        this.scratchInstances = growFloat32(this.scratchInstances, instanceCount * INSTANCE_STRIDE);
+        const instanceData = this.scratchInstances.subarray(0, instanceCount * INSTANCE_STRIDE);
+        const instanceColor = toLineInstanceColor(style.color, style.opacity);
+        // Compute on the GPU when createdZoom is specified, otherwise use u_width
+        const useGpuScaling = options.createdZoom !== undefined;
+        // Convert the line width into physical pixels (CSS pixels * devicePixelRatio)
+        const strokeWidth = useGpuScaling ? style.width * contentDpr : 0;
+        const createdZoom = options.createdZoom ?? 0;
+        const maxSegmentMeters = writeLineInstances(instanceData, 0, 0, coords, {
+            closed: options.closed,
+            zoom,
+            dashPixelRatio: screenDpr,
+            // a_extra.y: the original line width (px); u_width is used when it is 0
+            strokeWidth,
+            createdZoom,
+            color: instanceColor,
+        });
+        // Only the globe reads the length on the Mercator plane
+        const maxSegmentMercator = lineStationsOnMercatorPlane(this.terrain)
+            ? maxInstanceSegmentMercator(instanceData, instanceCount, zoom, screenDpr)
+            : 0;
+        // Upload into the instance buffer (orphaned and reused)
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.immInstanceBuffer);
+        gl.bufferData(gl.ARRAY_BUFFER, instanceData, gl.STREAM_DRAW);
+        // widthOverride: the GPU computation (0) when createdZoom is specified, otherwise u_width
+        // Convert the line width into physical pixels (CSS pixels * devicePixelRatio)
+        const widthOverride = useGpuScaling ? 0 : style.width * screenDpr;
+        this.executeDrawCall(instanceCount, texSize, { lineStyle: style.lineStyle, dashArray: style.dashArray }, zoom, projectionData, widthOverride, resolveLineStations(this.terrain, maxSegmentMeters, instanceCount, maxSegmentMercator));
+    }
+    /**
+     * Draws a closed path
+     */
+    drawClosed(coords, style, options, zoom, projectionData) {
+        if (coords.length < 3)
+            return;
+        // Remove the duplicate when the first and last points are the same
+        let closedCoords = coords;
+        const first = coords[0];
+        const last = coords[coords.length - 1];
+        if (first[0] === last[0] && first[1] === last[1]) {
+            closedCoords = coords.slice(0, -1);
+        }
+        // Draw it as a closed path
+        const loopCoords = [...closedCoords, closedCoords[0]];
+        this.draw(loopCoords, style, { ...options, closed: true }, zoom, projectionData);
+    }
+    /**
+     * Batch-draws multiple lines (per-instance colors)
+     *
+     * Color and opacity are passed as instance attributes, so even when the color differs from
+     * one line to the next, they can be drawn in one draw call as long as the shape parameters
+     * (the dash kind) are the same.
+     *
+     * @param items The line data (carrying the color, opacity, and width per line)
+     * @param shape The per-batch shape parameters, such as the dash kind
+     * @param factors The factors used at draw time (the opacity of the layer being drawn; 1x
+     *   scale and opacity 1 when omitted)
+     *
+     * @internal
+     */
+    drawAll(items, shape, zoom, projectionData, factors = NEUTRAL_DRAW_FACTORS) {
+        if (!this.program || items.length === 0)
+            return;
+        const gl = this.gl;
+        // Compute the relative coordinates on the CPU side (offset mode: computed at 64-bit
+        // precision)
+        const centerLngLat = this.offsetUniforms?.centerLngLat ?? [0, 0];
+        const arrays = buildLineBatchArrays(items, zoom, centerLngLat, this.pixelRatio);
+        if (!arrays)
+            return;
+        // Upload into the coordinate texture (the persistent texture is reused)
+        if (!this.immCoordTexture.upload(arrays.texData, arrays.texSize, this.textureSizeLimit())) {
+            return;
+        }
+        // Upload into the instance buffer (orphaned and reused)
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.immInstanceBuffer);
+        gl.bufferData(gl.ARRAY_BUFFER, arrays.instanceData, gl.STREAM_DRAW);
+        this.executeDrawCall(arrays.instanceCount, arrays.texSize, shape, zoom, projectionData, 0, resolveLineStations(this.terrain, arrays.maxSegmentMeters, arrays.instanceCount, arrays.maxSegmentMercator), factors);
+    }
+    /**
+     * Builds a retained-mode line batch
+     *
+     * It creates the coordinate texture, the instance buffer, and the VAO so that on later
+     * frames `drawRetainedBatch` can draw with nothing but a bind, the uniforms, and the draw
+     * call. The vertex data does not depend on the camera (the projection is done by the
+     * uniforms on every frame).
+     *
+     * @param items The line data (carrying the color, opacity, and width per line)
+     * @param shape The per-batch shape parameters, such as the dash kind
+     * @param options The origin of the relative coordinates and the zoom for the line-width
+     *   computation
+     * @returns The built batch, or null when the shader is not initialized or there are not
+     *   enough coordinates
+     *
+     * @internal
+     */
+    buildRetainedBatch(items, shape, options = {}) {
+        if (!this.program || items.length === 0)
+            return null;
+        // The origin of the relative coordinates is fixed per batch (it must not depend on the
+        // camera center)
+        const origin = normalizeOrigin(options.origin ?? defaultLineOrigin(items));
+        const arrays = buildLineBatchArrays(items, options.distanceZoom ?? 0, origin, this.pixelRatio);
+        if (!arrays)
+            return null;
+        return createRetainedLineBatch(this.gl, arrays, shape, origin, options.widthZoom ?? null, this.textureSizeLimit());
+    }
+    /**
+     * Builds a retained-mode line batch from packed lines
+     *
+     * The same batch as `buildRetainedBatch` builds for the same lines, without an array per line.
+     *
+     * @returns The built batch, or null when the shader is not initialized or there are not
+     *   enough coordinates
+     *
+     * @internal
+     */
+    buildRetainedPackedBatch(lines, shape, options = {}) {
+        if (!this.program || lines.count === 0)
+            return null;
+        const first = lines.start[0] * lines.stride;
+        const origin = normalizeOrigin(options.origin ?? [lines.coords[first] ?? 0, lines.coords[first + 1] ?? 0]);
+        const arrays = buildPackedLineBatchArrays(lines, options.distanceZoom ?? 0, origin, this.pixelRatio);
+        if (!arrays)
+            return null;
+        return createRetainedLineBatch(this.gl, arrays, shape, origin, options.widthZoom ?? null, this.textureSizeLimit());
+    }
+    /**
+     * Draws a retained-mode line batch
+     *
+     * It neither creates textures nor calls bufferData. The projection uniforms are recomputed
+     * every frame from the origin coordinate of the batch (the vertex data is not rebuilt).
+     *
+     * @param factors The factors used at draw time (when omitted, 1x scale and opacity 1, the
+     *   same as before)
+     *
+     * @internal
+     */
+    drawRetainedBatch(batch, zoom, projectionData, factors = NEUTRAL_DRAW_FACTORS) {
+        if (!this.program || batch.instanceCount === 0)
+            return;
+        const gl = this.gl;
+        gl.useProgram(this.program);
+        gl.bindVertexArray(batch.vao);
+        // The center of linearization is aligned with the camera center (linearizing around the
+        // origin coordinate of the batch turns the residual of the Mercator approximation into a
+        // displacement of pixel magnitude at vertices far from the center).
+        // The vertices are relative to the origin coordinate, so that difference is passed via
+        // u_origin_shift
+        const cameraUniforms = this.offsetUniforms;
+        if (cameraUniforms) {
+            this.projectionUniformManager.setUniforms(projectionData, zoom, cameraUniforms, [
+                batch.origin[0] - cameraUniforms.centerLngLat[0],
+                batch.origin[1] - cameraUniforms.centerLngLat[1],
+            ]);
+        }
+        else {
+            // Fallback (normally custom-layer has already called setOffsetUniforms each frame)
+            this.projectionUniformManager.setUniforms(projectionData, zoom, calculateOffsetUniforms(batch.origin, projectionData.mainMatrix));
+        }
+        this.uniforms.setViewport(gl.drawingBufferWidth, gl.drawingBufferHeight);
+        const stations = resolveLineStations(this.terrain, batch.maxSegmentMeters, batch.instanceCount, batch.maxSegmentMercator);
+        this.uniforms.setLineDraw(0, batch.widthZoom ?? zoom, batch.texSize, stations, lineStationsOnMercatorPlane(this.terrain));
+        this.uniforms.setDrawFactors(factors);
+        // The coordinate texture (the sampler unit is written by LineUniforms.setLineDraw)
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, batch.texture);
+        this.uniforms.setDash(batch.shape, resolvePixelRatio(this.pixelRatio));
+        gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 2 * (stations + 1), batch.instanceCount);
+        gl.bindVertexArray(null);
+        // When this interrupted an immediate-mode frame, restore the shared VAO and the projection
+        // uniforms (because the subsequent drawAll assumes the state set up by beginDraw)
+        if (this.isDrawing) {
+            gl.bindVertexArray(this.quadVAO);
+            this.setProjectionUniforms(projectionData, zoom);
+            // Leave no residual factors either (executeDrawCall rewrites them too, but the restoring
+            // side closes the loop)
+            this.uniforms.setDrawFactors(NEUTRAL_DRAW_FACTORS);
+        }
+    }
+    /**
+     * Partially updates the coordinate texture of a retained batch (applying the diff from a
+     * vertex drag)
+     *
+     * Rebuilding the batch every time a single vertex moves overflows the frame for lines with
+     * many vertices. The coordinates live in the texture, so rewriting only the texel of the
+     * vertex that moved is enough.
+     *
+     * The instance array is not touched. The indices (a_indices) are invariant as topology as
+     * long as the number of coordinates does not change, and the miter computation follows
+     * automatically because the shader reads them back with texelFetch. a_extra.x (the
+     * cumulative distance) and a_extra.w (the segment length) are left stale, but those are
+     * dash-only values, and a retained-mode line batch is always solid (dashed lines go through
+     * immediate mode). Both the line width and the caps are computed from lengths recomputed in
+     * screen space, so there is no visual impact. Those values return to correct ones on the
+     * next full rebuild (a style change, a change in the number of vertices, and so on).
+     *
+     * There is also no need to rebuild after the drag is committed. The last patch applied is
+     * the committed value as it stands.
+     *
+     * @param updates The running index within the coordinate texture and the new longitude and
+     *   latitude of that vertex
+     *
+     * @internal
+     */
+    patchRetainedBatchCoords(batch, updates) {
+        patchRetainedCoordTexels(this.gl, batch, updates);
+    }
+    /**
+     * Disposes of a retained-mode line batch
+     *
+     * @internal
+     */
+    disposeRetainedBatch(batch) {
+        deleteRetainedLineBatch(this.gl, batch);
+    }
+    /**
+     * Disposes of the resources
+     *
+     * @internal
+     */
+    dispose() {
+        const gl = this.gl;
+        if (this.program) {
+            gl.deleteProgram(this.program);
+            this.program = null;
+        }
+        if (this.quadVAO) {
+            gl.deleteVertexArray(this.quadVAO);
+            this.quadVAO = null;
+        }
+        if (this.quadVBO) {
+            gl.deleteBuffer(this.quadVBO);
+            this.quadVBO = null;
+        }
+        this.immCoordTexture.dispose();
+        if (this.immInstanceBuffer) {
+            gl.deleteBuffer(this.immInstanceBuffer);
+            this.immInstanceBuffer = null;
+        }
+    }
+}

package/dist/view/renderers/point/billboard-depth.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runs a draw callback with the depth test off, then restores the depth test as it was.
+ *
+ * Use it around anything drawn as a billboard (a marker or an icon facing the screen) so that
+ * the terrain mesh does not cut it in half. Polygons and lines should stay depth-tested.
+ *
+ * @param gl The WebGL context of the map
+ * @param draw The drawing to run
+ */
+export declare function drawBillboardsWithoutDepth(gl: WebGL2RenderingContext, draw: () => void): void;

package/dist/view/renderers/point/billboard-depth.js

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Draws symbols (billboards and glyphs) with the depth test disabled.
+ *
+ * A point is lifted to the elevation of its anchor and then drawn as a billboard that faces
+ * the screen. The lower half of the billboard sits below the anchor, so testing it against the
+ * depth of the terrain mesh buries it in the ground and clips it away, leaving the point as a
+ * half circle. Whether something is hidden by the terrain is the job of the occlusion ghost
+ * (occlusion.ts), not of the depth test, so the depth test is always disabled here.
+ *
+ * The responsibility for disabling the depth test belongs to the renderer. Disabling it in
+ * custom-layer instead means it gets forgotten in configurations where the analytic drape is
+ * unavailable (a single dataset makes canDrape false). That is exactly what the
+ * "only points of datasets become half circles" defect was.
+ *
+ * Billboards are not drawn in a single place. Both the instanced billboard (point-instance) and
+ * the per-point shapes (point-shape: triangle, star, icon, and the degenerate path for the
+ * default circle) draw billboards. Wrapping only the instanced side leaves hand-drawn points as
+ * half circles. A hand-drawn Point may be taken over by a registered CustomFeatureRenderer,
+ * and then never goes through the instanced path at all. That is why this function is shared
+ * by every renderer that draws billboards. SDF glyphs laid flat on the map plane (text that is
+ * not painted into a ground quad) go through here for the same reason.
+ * A glyph is a flat quad given elevation at its four corners, so, having no subdivision, its
+ * strokes get shaved off where the terrain pokes through from the inside and the text looks
+ * broken.
+ *
+ * The original state is always restored. Polygons and lines must be hidden correctly by the
+ * depth of the terrain mesh.
+ *
+ * The original state is read from the record in `layer/depth-state.ts`. It must not be queried
+ * with `gl.isEnabled` every time (that is a synchronous GPU round trip, and on a map with
+ * thousands of labels a single frame reaches tens of seconds).
+ */
+import { isDepthTestEnabled, setDepthTestEnabled } from '../../layer/depth-state.js';
+/**
+ * Runs a draw callback with the depth test off, then restores the depth test as it was.
+ *
+ * Use it around anything drawn as a billboard (a marker or an icon facing the screen) so that
+ * the terrain mesh does not cut it in half. Polygons and lines should stay depth-tested.
+ *
+ * @param gl The WebGL context of the map
+ * @param draw The drawing to run
+ */
+export function drawBillboardsWithoutDepth(gl, draw) {
+    const depthWasEnabled = isDepthTestEnabled(gl);
+    if (depthWasEnabled)
+        setDepthTestEnabled(gl, false);
+    try {
+        draw();
+    }
+    finally {
+        if (depthWasEnabled)
+            setDepthTestEnabled(gl, true);
+    }
+}