@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/renderers/point/point-instance.d.ts

@@ -0,0 +1,124 @@
+import type { PixelRatioInput } from '../../../shared/utils/pixel-ratio.js';
+import { TerrainContext } from '../../terrain/context.js';
+import { type SdfPointShape } from './point-sdf.js';
+/** Color type */
+export type Color = [number, number, number, number];
+/** Point shape (every shape is inscribed in the circle of the outer radius) */
+export type PointShape = SdfPointShape;
+/**
+ * The instanced shape a point style is drawn with, or null for a shape the instanced renderer
+ * does not draw (`'icon'`, which goes through the per-point renderer)
+ *
+ * The retained batches (Store and datasets) and the immediate batches all decide
+ * with this function, so the three paths agree on which points are instanced.
+ */
+export declare function toInstancedPointShape(shape: string): PointShape | null;
+/** Point data for instanced rendering (full version) */
+export interface PointInstanceDataFull {
+    coord: [number, number];
+    fillColor: Color;
+    fillSize: number;
+    strokeColor: Color;
+    strokeWidth: number;
+    /**
+     * Ground elevation of the anchor (meters; omitted or 0 means "do not add elevation")
+     *
+     * Both a point and a vertex handle are UI determined by a single point, so on terrain the
+     * longitude and latitude alone do not determine their position. The same elevation as the one
+     * used for hit testing is computed on the CPU (view/terrain/anchor.ts) and passed in here, and
+     * the vertex shader uses this value as is. Sampling the DEM atlas the way polygons and lines
+     * do would give two sources of truth that disagree with hit testing.
+     */
+    elevationMeters?: number;
+    /**
+     * Opacity factor used when the point is occluded by the terrain (omitted or 1 is normal
+     * display)
+     *
+     * Points are drawn without the depth test, so a point behind a mountain is plainly visible and
+     * is misread as being in front. Occluded ones are drawn faint (ghost).
+     *
+     * The factor is folded into the alpha of the color. Since its result changes as the camera
+     * moves, it is not set on paths that bake it in (retained batches). It is set only on the
+     * immediate path, which is rebuilt every frame (baking it in would leave a stale ghost). The
+     * editing UI of the current selection (handles, selection outline) is also under manipulation,
+     * so it is not set there either.
+     */
+    ghost?: number;
+}
+/** Point data for instanced rendering with coordinates only (the style is given as arguments) */
+export interface PointInstanceData {
+    coord: [number, number];
+}
+/**
+ * Padding added to the billboard (device pixels)
+ *
+ * Cutting the billboard exactly at the outer radius loses the outer half of the antialiasing.
+ */
+export declare const POINT_AA_PADDING_PX = 1;
+/**
+ * SDF boundaries of one instance (device pixels)
+ */
+export interface PointSdfEdges {
+    /**
+     * Radius of the fill. Everything inside this takes the fill color (for a shape other than the
+     * circle and the square: everything deeper than the stroke width inside the outer edge)
+     */
+    radius: number;
+    /**
+     * Outer radius (radius + stroke width), the circumradius of the shape. Nothing outside the
+     * shape of this radius is drawn
+     */
+    outer: number;
+    /** Half edge of the billboard (outer radius + antialiasing padding) */
+    extent: number;
+}
+/**
+ * Computes the SDF boundaries
+ *
+ * This is the same computation the shader performs in the vertex and fragment stages (the GLSL
+ * side writes these formulas as they are, and embeds the same constant `POINT_AA_PADDING_PX` for
+ * the padding). Negative values are treated as 0, and when the stroke width is 0 the outer
+ * radius equals the radius.
+ *
+ * @param fillSizePx Radius of the fill (device pixels)
+ * @param strokeWidthPx Stroke width (device pixels)
+ * @param sizeScale Size factor at draw time (default 1)
+ */
+export declare function pointSdfEdges(fillSizePx: number, strokeWidthPx: number, sizeScale?: number): PointSdfEdges;
+/**
+ * Point batch of the retained mode (GPU resources)
+ *
+ * It shares no resources with the shared instance buffer and shared VAO of the immediate mode.
+ * Since the fill and the stroke are drawn from a single instance array, a batch holds only one
+ * set of billboard vertex buffer, instance buffer and VAO.
+ */
+export interface RetainedPointBatch {
+    /** Shape of the points */
+    readonly shape: PointShape;
+    /** VAO dedicated to this batch */
+    readonly vao: WebGLVertexArrayObject;
+    /** Vertex buffer of the billboard */
+    readonly shapeBuffer: WebGLBuffer;
+    /** Instance buffer */
+    readonly instanceBuffer: WebGLBuffer;
+    /** Number of instances */
+    readonly instanceCount: number;
+    /** Origin of the relative coordinates (already rounded to Float32) */
+    readonly origin: [number, number];
+}
+/**
+ * Options for building a point batch of the retained mode
+ */
+export interface RetainedPointBuildOptions {
+    /** Origin of the relative coordinates (defaults to the coordinates of the first point) */
+    origin?: [number, number];
+}
+/**
+ * Builds the instance array (shared by the immediate mode and the retained mode)
+ *
+ * The order is exactly the order of the input (since the instance order directly becomes the
+ * front-to-back order of the rendering, nothing is reordered or thinned out). Coordinates are
+ * stored as values relative to `origin`, so with a fixed `origin` the result does not depend on
+ * the camera.
+ */
+export declare function buildPointInstanceData(points: PointInstanceDataFull[], origin: [number, number], pixelRatio?: PixelRatioInput, terrain?: TerrainContext): Float32Array;