@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/layer/gl-state.js

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { TERRAIN_DEPTH_BIAS } from '../terrain/metrics.js';
+import { getTerrainCoarsening, setQuadDrapeFrame, setTerrainShadeLight, TERRAIN_ATLAS_TEXTURE_UNIT, } from '../terrain/state.js';
+import { setDepthTestEnabled, syncDepthTestEnabled } from './depth-state.js';
+/** Establishes the GL state this frame assumes, at the start of the drawing of a slot */
+export function applySegmentGlState(gl, terrainContext, f) {
+    // Sync the record of the depth test with the actual state of this frame (the foundation that
+    // keeps the symbol rendering from asking gl.isEnabled every time; depth-state.ts)
+    syncDepthTestEnabled(gl);
+    // Deliver the same light as the analytic drape to the polygon fills of the vertex
+    // displacement path, so that the look of a fill does not jump when the paths swap
+    // (terrain/shade.ts). Without terrain it is null and there is no shading
+    setTerrainShadeLight(terrainContext, f.terrainState.active ? f.drapeLight : null);
+    if (f.terrainState.active && f.terrainState.atlasTexture) {
+        // The DEM atlas is left bound to a dedicated texture unit (every renderer uses unit 0 for
+        // its coordinate texture)
+        gl.activeTexture(gl.TEXTURE0 + TERRAIN_ATLAS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, f.terrainState.atlasTexture);
+        gl.activeTexture(gl.TEXTURE0);
+    }
+    f.restoreBlendState();
+    applySegmentDepthState(gl, terrainContext, f);
+    if (f.quadDrapeFrame) {
+        // The layer rendering keeps the depth test after a quad, whether or not the drape was used
+        f.quadDrapeFrame.keepDepthTest = true;
+        setQuadDrapeFrame(terrainContext, f.quadDrapeFrame);
+    }
+}
+/**
+ * Establishes the depth state of the layer rendering of a slot
+ *
+ * `applySegmentGlState` sets it at the start of a slot, and the drape of the segment, which
+ * changes the depth function and the offset, hands it back with this before the layers are
+ * drawn. The layers are therefore drawn in one depth state whether or not the drape was used.
+ * What the drape cannot paint (dashed lines, polygons with a dashed outline, the geometry being
+ * drawn, the features of extensions, the datasets not handed over to it) is
+ * drawn after it by the vertex displacement path and must be hidden by the terrain in the same
+ * way. Symbols switch the depth test off themselves (`drawBillboardsWithoutDepth`).
+ */
+export function applySegmentDepthState(gl, terrainContext, f) {
+    // Depth (used only when there is terrain)
+    //
+    // MapLibre hands control to a '3d' CustomLayer with the depth test enabled, LEQUAL, and
+    // writing allowed. The depth of the terrain mesh is written into the framebuffer of the
+    // screen, so enabling the test correctly hides the features behind a mountain. Writing,
+    // however, is turned off: the stacking order of core (the layer order, the selection UI in
+    // front) was built on a draw order without depth, and letting our own drawings order each
+    // other by depth would break it. gl.depthRange is not rewritten (MapLibre sets a narrowed
+    // range shared with the terrain mesh). The depth function is set to the LEQUAL MapLibre
+    // hands over, so that it is the same after the drape.
+    if (f.terrainState.active && !f.wideFallback) {
+        setDepthTestEnabled(gl, true);
+        gl.depthMask(false);
+        gl.depthFunc(gl.LEQUAL);
+        // The depth bias is applied in proportion to the slope. The disagreement between the
+        // terrain mesh and our own polygons is largest on a slope, so a constant lift cannot cover
+        // it. The factor of polygonOffset is proportional to "the screen-space gradient of the
+        // depth", which fits the shape of this problem.
+        //
+        // The amount is made proportional to "the coarseness of the step". A coarsely subdivided
+        // polygon becomes a chord between the nodes, and on a hilltop the chord sinks below the
+        // terrain. Measured, the sinking was at most 1.2 m for a step of 7.8 m, 3.7 m for 15.6 m
+        // and 5.2 m for 31 m (the hills of northern Kawasaki). The coarser the step, the deeper it
+        // sinks, so the bias grows by the same amount.
+        const bias = TERRAIN_DEPTH_BIAS * getTerrainCoarsening(terrainContext);
+        gl.enable(gl.POLYGON_OFFSET_FILL);
+        gl.polygonOffset(-bias, -bias);
+    }
+    else {
+        setDepthTestEnabled(gl, false);
+    }
+}
+/** Restores the GL state to the defaults of maplibre at the end of the drawing of a slot */
+export function restoreSegmentGlState(gl, f) {
+    if (f.terrainState.active && !f.wideFallback) {
+        gl.depthMask(true);
+        gl.disable(gl.POLYGON_OFFSET_FILL);
+        gl.polygonOffset(0, 0);
+    }
+    // The depth function goes back to the default of maplibre (the slot drew with LEQUAL)
+    gl.depthFunc(gl.LESS);
+    setDepthTestEnabled(gl, true);
+}
+/**
+ * Establishes the GL state of the analytic drape
+ *
+ * Composite with premultiplied alpha (the coverage is evaluated once per pixel, so an overlap
+ * is never painted twice).
+ *
+ * What the drape draws is the ground itself. It coincides with the terrain surface of maplibre
+ * at the same height, so on pixels of equal depth the winner wavers and the edges get eaten away
+ * (pronounced on a shallow slope; confirmed in the field). The depth function is set to LEQUAL so
+ * that equality wins, and the slope-proportional bias (which exists to fill the sinking of the
+ * chords of the CPU subdivision) is not applied: the surfaces of the drape are not chords, so it
+ * is not needed. The occlusion is carried by the depth test itself, so it must not be turned off.
+ *
+ * The depth bias (polygonOffset) is not used. The factor is proportional to the screen-space
+ * gradient of the depth, so it acts too strongly on a shallow slope, and its unit depends on the
+ * resolution of the depth buffer. The drape lifts its vertices ever so slightly to win instead
+ * (DRAPE_LIFT_RATIO in drape/renderer.ts).
+ */
+export function applyDrapeGlState(gl) {
+    applyDrapeBlendState(gl);
+    setDepthTestEnabled(gl, true);
+    gl.depthFunc(gl.LEQUAL);
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+}
+/**
+ * Goes back to the drape after an image was interleaved (the blending and the depth test; the
+ * depth function and the offset were left as the drape set them)
+ */
+export function resumeDrapeGlState(gl) {
+    applyDrapeBlendState(gl);
+    setDepthTestEnabled(gl, true);
+}
+/**
+ * Establishes the GL state of the symbols and the UI (no depth test)
+ *
+ * From here on it is not "something painted onto the ground" but the symbols and the UI.
+ * Points, handles and selection boxes are billboards, so with the depth in effect they disappear
+ * entirely as soon as they sink a little into the ground. Measured, enabling the terrain made
+ * every point invisible. Symbols are always drawn in front.
+ */
+export function enterSymbolGlState(gl) {
+    setDepthTestEnabled(gl, false);
+}
+/** Premultiplied alpha compositing of the drape */
+function applyDrapeBlendState(gl) {
+    gl.enable(gl.BLEND);
+    gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+}

package/dist/view/layer/index.d.ts

@@ -0,0 +1,6 @@
+export type { BlendCapableGL } from './blend.js';
+export { applyDrawBlendState } from './blend.js';
+export type { CustomLayerDeps, CustomLayerInterface } from './custom-layer.js';
+export { createCustomLayer } from './custom-layer.js';
+export type { RenderSegment, RenderSlot } from './slots.js';
+export { PRIMARY_RENDER_LAYER_ID, partitionLayerOrder, renderSlotLayerId } from './slots.js';

package/dist/view/layer/index.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { applyDrawBlendState } from './blend.js';
+export { createCustomLayer } from './custom-layer.js';
+export { PRIMARY_RENDER_LAYER_ID, partitionLayerOrder, renderSlotLayerId } from './slots.js';

package/dist/view/layer/render-scope.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The render scope of one draw instance
+ *
+ * Everything the rendering of one CustomLayer keeps between frames and that must never be seen
+ * by another draw instance: the selection scope shared with the modes, the terrain state, and
+ * the caches of triangulation and style evaluation keyed by feature id. Two instances on the
+ * same page (a print preview next to the editor, a duplicated document with the same ids)
+ * therefore never read each other's triangles, styles or terrain.
+ *
+ * The CustomLayer creates it (the selection scope is handed in, because the modes use the same
+ * one) and passes the parts each renderer needs at construction.
+ */
+import { EarcutCache } from '../cache/earcut.js';
+import { StyleRuleCache } from '../cache/style-rule.js';
+import { TerrainContext } from '../terrain/context.js';
+import type { SelectionScope } from '../ui/selection-scope.js';
+export interface RenderScope {
+    /** The selection scope of the draw instance (shared with the modes) */
+    readonly selection: SelectionScope;
+    /** The terrain state of the draw instance */
+    readonly terrain: TerrainContext;
+    /** Triangulation results keyed by feature id */
+    readonly earcut: EarcutCache;
+    /** Evaluated style rules keyed by feature id */
+    readonly styleRules: StyleRuleCache;
+}
+/**
+ * Creates the render scope of one draw instance
+ */
+export declare function createRenderScope(selection: SelectionScope): RenderScope;

package/dist/view/layer/render-scope.js

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The render scope of one draw instance
+ *
+ * Everything the rendering of one CustomLayer keeps between frames and that must never be seen
+ * by another draw instance: the selection scope shared with the modes, the terrain state, and
+ * the caches of triangulation and style evaluation keyed by feature id. Two instances on the
+ * same page (a print preview next to the editor, a duplicated document with the same ids)
+ * therefore never read each other's triangles, styles or terrain.
+ *
+ * The CustomLayer creates it (the selection scope is handed in, because the modes use the same
+ * one) and passes the parts each renderer needs at construction.
+ */
+import { EarcutCache } from '../cache/earcut.js';
+import { StyleRuleCache } from '../cache/style-rule.js';
+import { TerrainContext } from '../terrain/context.js';
+/**
+ * Creates the render scope of one draw instance
+ */
+export function createRenderScope(selection) {
+    return {
+        selection,
+        terrain: new TerrainContext(),
+        earcut: new EarcutCache(),
+        styleRules: new StyleRuleCache(),
+    };
+}

package/dist/view/layer/render.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Per-layer rendering
+ *
+ * The per-layer rendering loop called from CustomLayer's render()
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { DatasetManager } from '../../display/manager.js';
+import type { CustomFeatureHandler, CustomRendererDrawContext, LayerAwareOverlayRenderer } from '../../extension/index.js';
+import type { Store } from '../../store/store.js';
+import type { BoundingBox, Feature, Layer } from '../../store/types.js';
+import type { FeatureCompanionRegistry } from '../feature-companion.js';
+import type { Renderers } from './renderers.js';
+import type { StoreRetainedCache } from './store-retained.js';
+/**
+ * Draw features and overlays layer by layer
+ *
+ * The loop walks the stacking order of the Store (`store.getLayerOrder()`). Its entries are a
+ * mix of layer ids and dataset ids, and for each entry it does the following.
+ *
+ * - A layer exists: draw it in retained / immediate mode as before
+ * - A dataset whose order is 'layer-order' exists: draw that dataset
+ * - Neither of them (an unknown id): skip it (not an error)
+ *
+ * In addition, datasets (display) have two insertion points outside the layer
+ * loop. below-store is drawn before every layer (behind them) and above-store after every layer
+ * (in front of them). Batching uses the same BatchManager as the Store. The per-layer frames
+ * (beginFrame / endFrame) are closed inside the loop, so their state never mixes with a frame
+ * opened outside it. The batch of a dataset is also closed at a layer boundary, so inserting
+ * one in the middle of the order never nests GL state.
+ *
+ * There are two paths for the features of the Store.
+ *
+ * - Retained mode (storeRetained is present and the renderers support it): draws the retained
+ *   batches prepared per layer. The features argument is not used. Thinning of a retained batch
+ *   is done per chunk, so the bbox of the expanded viewport is computed once per frame and passed
+ *   in. Immediate chunks, which draw one feature at a time, are thinned per feature as well, so
+ *   the set of visible ids is passed too (only once it becomes necessary).
+ * - Immediate mode (the path used before): walks features every frame and draws them.
+ *
+ * The rendering result (including the z-order) is the same either way.
+ *
+ * An external renderer (a custom feature type or a layer-aware overlay) may rewrite the GL blend
+ * state for its own purposes. If it comes back having left it rewritten, everything drawn later
+ * in that frame (the layers that follow and the datasets) is drawn with the
+ * wrong blending, so `restoreBlendState` is called at the point control comes back, to
+ * re-establish the contract of the frame.
+ *
+ * @param companions Providers of companion drawing (those of this draw instance)
+ * @param features Features to draw in immediate mode (not used in retained mode)
+ * @param datasets Datasets (not drawn when omitted)
+ * @param storeRetained Retained batch cache for drawing the Store (immediate mode when omitted)
+ * @param restoreBlendState Re-establishes our own blend state (not re-established when omitted)
+ * @param range The segment (slot) to draw (every entry when omitted)
+ * @param view The part of the view to draw, on one copy of the world (the expanded viewport
+ *   of the ViewportFilter when omitted). A view across the antimeridian is drawn once per
+ *   copy, each with its own range
+ */
+export declare function renderLayers(r: Renderers, store: Store, features: Feature[], selectedIdSet: Set<string>, defaultProjectionData: ProjectionData, zoom: number, customRenderers: Map<string, CustomFeatureHandler['renderer']>, customRendererContext: CustomRendererDrawContext, companions: FeatureCompanionRegistry, layerAwareRenderers: LayerAwareOverlayRenderer[], datasets?: DatasetManager, storeRetained?: StoreRetainedCache, restoreBlendState?: () => void, range?: RenderLayersRange, view?: RenderLayersView): void;
+/**
+ * The context of the custom renderers for one layer (the context of the frame with the opacity
+ * of the layer)
+ *
+ * The same object is returned when the opacity is already the one of the context, so a map whose
+ * layers are all opaque allocates nothing per layer.
+ */
+export declare function layerRendererContext(base: CustomRendererDrawContext, layer: Layer): CustomRendererDrawContext;
+/**
+ * The part of the view one rendering covers (one copy of the world)
+ */
+export interface RenderLayersView {
+    /** The range to draw, in stored longitudes (thins the chunks) */
+    readonly bounds: BoundingBox;
+    /** The ids of the features inside `bounds` (thins the immediate chunks one by one) */
+    readonly getVisibleIds: () => ReadonlySet<string>;
+}
+/**
+ * Specification of the segment (slot) to draw
+ *
+ * from / to is [from, to) in layerOrder. first is the first slot (it draws the datasets below
+ * the order), last is the last slot (it draws the datasets above the order).
+ */
+export interface RenderLayersRange {
+    readonly from: number;
+    readonly to: number;
+    readonly first: boolean;
+    readonly last: boolean;
+}

package/dist/view/layer/render.js

@@ -0,0 +1,187 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { drawFeatureCompanionsInFrame } from '../feature-companion.js';
+import { layerDrawFactors } from '../renderers/draw-factors.js';
+/**
+ * Draw features and overlays layer by layer
+ *
+ * The loop walks the stacking order of the Store (`store.getLayerOrder()`). Its entries are a
+ * mix of layer ids and dataset ids, and for each entry it does the following.
+ *
+ * - A layer exists: draw it in retained / immediate mode as before
+ * - A dataset whose order is 'layer-order' exists: draw that dataset
+ * - Neither of them (an unknown id): skip it (not an error)
+ *
+ * In addition, datasets (display) have two insertion points outside the layer
+ * loop. below-store is drawn before every layer (behind them) and above-store after every layer
+ * (in front of them). Batching uses the same BatchManager as the Store. The per-layer frames
+ * (beginFrame / endFrame) are closed inside the loop, so their state never mixes with a frame
+ * opened outside it. The batch of a dataset is also closed at a layer boundary, so inserting
+ * one in the middle of the order never nests GL state.
+ *
+ * There are two paths for the features of the Store.
+ *
+ * - Retained mode (storeRetained is present and the renderers support it): draws the retained
+ *   batches prepared per layer. The features argument is not used. Thinning of a retained batch
+ *   is done per chunk, so the bbox of the expanded viewport is computed once per frame and passed
+ *   in. Immediate chunks, which draw one feature at a time, are thinned per feature as well, so
+ *   the set of visible ids is passed too (only once it becomes necessary).
+ * - Immediate mode (the path used before): walks features every frame and draws them.
+ *
+ * The rendering result (including the z-order) is the same either way.
+ *
+ * An external renderer (a custom feature type or a layer-aware overlay) may rewrite the GL blend
+ * state for its own purposes. If it comes back having left it rewritten, everything drawn later
+ * in that frame (the layers that follow and the datasets) is drawn with the
+ * wrong blending, so `restoreBlendState` is called at the point control comes back, to
+ * re-establish the contract of the frame.
+ *
+ * @param companions Providers of companion drawing (those of this draw instance)
+ * @param features Features to draw in immediate mode (not used in retained mode)
+ * @param datasets Datasets (not drawn when omitted)
+ * @param storeRetained Retained batch cache for drawing the Store (immediate mode when omitted)
+ * @param restoreBlendState Re-establishes our own blend state (not re-established when omitted)
+ * @param range The segment (slot) to draw (every entry when omitted)
+ * @param view The part of the view to draw, on one copy of the world (the expanded viewport
+ *   of the ViewportFilter when omitted). A view across the antimeridian is drawn once per
+ *   copy, each with its own range
+ */
+export function renderLayers(r, store, features, selectedIdSet, defaultProjectionData, zoom, customRenderers, customRendererContext, companions, layerAwareRenderers, datasets, storeRetained, restoreBlendState, range, view) {
+    const fullOrder = store.getLayerOrder();
+    // When a segment (slot) is given, only the entries of that segment are drawn. The datasets
+    // below the order (below-store) are drawn only by the first segment and those above it
+    // (above-store) only by the last segment (the same thing is not drawn once per slot)
+    const layerOrder = range ? fullOrder.slice(range.from, range.to) : fullOrder;
+    const drawBelow = range ? range.first : true;
+    const drawAbove = range ? range.last : true;
+    const tentative = store.getTentative();
+    // Implementations without the renderers of retained mode (a test stub, for example) fall back
+    // to the immediate mode used before
+    const retainedRenderers = storeRetained !== undefined && typeof r.batchManager.getRetainedRenderers === 'function'
+        ? r.batchManager.getRetainedRenderers()
+        : undefined;
+    const useRetained = storeRetained !== undefined && retainedRenderers !== undefined;
+    if (useRetained)
+        storeRetained.beginFrame(companions);
+    // The range used to thin the retained chunks and the chunks of the datasets.
+    // It does not depend on the number of features, so once per frame is enough (it is computed
+    // regardless of the rendering path and passed to draw / drawOne as an argument; the manager is
+    // not left to look it up lazily). An implementation without a ViewportFilter (a test stub, for
+    // example) does not compute it and leaves it to the default of the dataset.
+    const viewportBounds = view?.bounds ??
+        (typeof r.viewportFilter?.getBounds === 'function' ? r.viewportFilter.getBounds() : undefined);
+    // Immediate chunks (dashed lines, images, custom types) cannot be thinned by the chunk bbox
+    // alone: once a chunk touches the view, even features outside the screen are drawn one by one.
+    // The set of visible ids is passed so that the same per-feature thinning as immediate mode is
+    // applied. Querying the spatial index once per frame is enough, and it is not needed at all in
+    // a frame without a single immediate chunk, so it is looked up once, when first needed.
+    let visibleIdsMemo;
+    const canFilterVisible = view !== undefined ||
+        (viewportBounds !== undefined && typeof r.viewportFilter?.getVisibleIds === 'function');
+    const getVisibleIds = canFilterVisible
+        ? () => {
+            if (!visibleIdsMemo) {
+                visibleIdsMemo = view ? view.getVisibleIds() : r.viewportFilter.getVisibleIds();
+            }
+            return visibleIdsMemo;
+        }
+        : undefined;
+    // Insertion point 1: behind every layer of the Store
+    if (drawBelow) {
+        datasets?.draw('below-store', r.batchManager, defaultProjectionData, zoom, viewportBounds);
+    }
+    // Group the features by layer id (immediate mode only)
+    const featuresByLayer = new Map();
+    if (!useRetained) {
+        for (const feature of features) {
+            const layerFeatures = featuresByLayer.get(feature.layerId) ?? [];
+            layerFeatures.push(feature);
+            featuresByLayer.set(feature.layerId, layerFeatures);
+        }
+    }
+    for (const layerId of layerOrder) {
+        // The layer is needed to evaluate the style rule (layer.styleRule), so it is passed to the
+        // frame of the batch.
+        const layer = store.getLayer(layerId);
+        // An entry that is not a layer is drawn as a dataset taking part in the
+        // stacking order. If it is not a dataset either, it is skipped (the order is the single
+        // source of truth, and an id that is not on it is not drawn).
+        if (!layer) {
+            datasets?.drawOne(layerId, r.batchManager, defaultProjectionData, zoom, viewportBounds);
+            continue;
+        }
+        // The custom renderers and the companions of the layer get its opacity in their context
+        const layerContext = layerRendererContext(customRendererContext, layer);
+        if (useRetained && retainedRenderers) {
+            storeRetained.drawLayer(layerId, layer, defaultProjectionData, zoom, {
+                renderers: retainedRenderers,
+                batchManager: r.batchManager,
+                customRenderers,
+                customRendererContext: layerContext,
+                companions,
+                getVisibleIds,
+                restoreBlendState,
+            }, viewportBounds);
+        }
+        else {
+            const layerFeatures = featuresByLayer.get(layerId) ?? [];
+            r.batchManager.beginFrame(defaultProjectionData, zoom, layer);
+            for (const feature of layerFeatures) {
+                const isSelected = selectedIdSet.has(feature.id);
+                // Companion drawing (feature companion): drawn right before the feature itself, that is,
+                // one z below it. If no provider at all is registered, not even has is called.
+                drawFeatureCompanionsInFrame(companions, feature, r.batchManager, defaultProjectionData, zoom, layer, layerContext, restoreBlendState);
+                const customRenderer = customRenderers.get(feature.type);
+                if (customRenderer) {
+                    // To keep the draw order (painter's algorithm), the core batch that has accumulated is
+                    // flushed first and only then the custom feature is drawn immediately.
+                    // A batch is not painted until endFrame, so without flushing here a custom feature
+                    // would ignore layer.order and be drawn before the core features of the same layer.
+                    r.batchManager.endFrame();
+                    customRenderer.draw({
+                        id: feature.id,
+                        type: feature.type,
+                        coordinates: feature.coordinates,
+                        properties: feature.properties,
+                        style: feature.style,
+                    }, defaultProjectionData, zoom, layerContext);
+                    // Re-establish the blend state that the external renderer may have rewritten.
+                    restoreBlendState?.();
+                    // Restart the batch for the core features that follow.
+                    r.batchManager.beginFrame(defaultProjectionData, zoom, layer);
+                }
+                else {
+                    r.batchManager.processFeature(feature, isSelected);
+                }
+            }
+            r.batchManager.endFrame();
+        }
+        // Tentative rendering
+        if (tentative && tentative.layerId === layerId) {
+            r.tentativeRenderer.drawGeometry(tentative, defaultProjectionData, zoom);
+        }
+        // Layer-aware overlay rendering (an overlay is not content of the layer, so it keeps the
+        // context of the frame, at opacity 1)
+        for (const renderer of layerAwareRenderers) {
+            renderer.drawForLayer(layerId, defaultProjectionData, zoom, customRendererContext);
+            // Re-establish the blend state that the external renderer may have rewritten
+            restoreBlendState?.();
+        }
+    }
+    // Insertion point 2: in front of every layer of the Store (behind the selection UI and
+    // tentative)
+    if (drawAbove) {
+        datasets?.draw('above-store', r.batchManager, defaultProjectionData, zoom, viewportBounds);
+    }
+}
+/**
+ * The context of the custom renderers for one layer (the context of the frame with the opacity
+ * of the layer)
+ *
+ * The same object is returned when the opacity is already the one of the context, so a map whose
+ * layers are all opaque allocates nothing per layer.
+ */
+export function layerRendererContext(base, layer) {
+    const opacity = layerDrawFactors(layer).opacity;
+    return base.opacity === opacity ? base : { ...base, opacity };
+}

package/dist/view/layer/renderers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Initialization and disposal of the renderers
+ *
+ * Lifecycle management of every renderer that CustomLayer uses
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { CustomFeatureHandler } from '../../extension/index.js';
+import type { FeatureStyleConfig } from '../../shared/config/feature-style.js';
+import type { RenderingConfig } from '../../shared/config/rendering.js';
+import type { SelectionUIConfig } from '../../shared/config/selection.js';
+import type { PixelRatioInput } from '../../shared/utils/pixel-ratio.js';
+import type { SpatialIndex } from '../../store/spatial/spatial-index.js';
+import type { Store } from '../../store/store.js';
+import { TextureCache } from '../cache/texture.js';
+import { BatchManager } from '../renderers/batch-manager.js';
+import { FeatureDrawer } from '../renderers/drawer.js';
+import { type ImageErrorFn, ImageRenderer } from '../renderers/image.js';
+import { SDFLineRenderer } from '../renderers/line/sdf-line.js';
+import { PointInstanceRenderer } from '../renderers/point/point-instance.js';
+import { PointShapeRenderer } from '../renderers/point/point-shape.js';
+import { PolygonBatchRenderer } from '../renderers/polygon/batch.js';
+import { FillShaderManager } from '../renderers/polygon/fill.js';
+import { SDFPolygonRenderer } from '../renderers/polygon/sdf-polygon.js';
+import { StrokeRenderer } from '../renderers/stroke.js';
+import { ShaderInitializer } from '../shaders/initializer.js';
+import { QuadShader } from '../shaders/quad.js';
+import { BoxSelectionRenderer } from '../ui/box-selection.js';
+import { SelectionHandlesRenderer, SelectionUIRenderer } from '../ui/index.js';
+import { TentativeRenderer } from '../ui/tentative.js';
+import { ViewportFilter } from '../viewport.js';
+import type { RenderScope } from './render-scope.js';
+/**
+ * The initialized renderers
+ */
+export interface Renderers {
+    textureCache: TextureCache;
+    quadShader: QuadShader;
+    imageRenderer: ImageRenderer;
+    strokeRenderer: StrokeRenderer;
+    sdfLineRenderer: SDFLineRenderer;
+    pointShapeRenderer: PointShapeRenderer;
+    pointInstanceRenderer: PointInstanceRenderer;
+    polygonBatchRenderer: PolygonBatchRenderer;
+    sdfPolygonRenderer: SDFPolygonRenderer;
+    fillShaderManager: FillShaderManager;
+    selectionUIRenderer: SelectionUIRenderer;
+    selectionHandlesRenderer: SelectionHandlesRenderer;
+    featureDrawer: FeatureDrawer;
+    tentativeRenderer: TentativeRenderer;
+    boxSelectionRenderer: BoxSelectionRenderer;
+    viewportFilter: ViewportFilter;
+    shaderInitializer: ShaderInitializer;
+    batchManager: BatchManager;
+}
+/**
+ * What the renderers of one CustomLayer are built from
+ */
+export interface InitRenderersDeps {
+    gl: WebGL2RenderingContext;
+    map: MapLibreMap;
+    store: Store;
+    spatialIndex: SpatialIndex;
+    featureStyle: FeatureStyleConfig;
+    selectionConfig: SelectionUIConfig;
+    renderingConfig: RenderingConfig;
+    customFeatureHandlers: CustomFeatureHandler[] | undefined;
+    /** Injected rendering pixel ratio (when omitted, read from window every time) */
+    pixelRatio?: PixelRatioInput;
+    /** The state and the caches owned by the draw instance (never shared between instances) */
+    scope: RenderScope;
+    /** Where the failure to load the image of an Image feature is reported */
+    onImageError?: ImageErrorFn;
+}
+/**
+ * Initialize the renderers
+ */
+export declare function initRenderers(deps: InitRenderersDeps): Renderers;
+/**
+ * Dispose the renderers
+ */
+export declare function disposeRenderers(r: Renderers): void;