@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/layer/store-retained-chunk.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The chunk of the retained cache and the building and releasing of its batch
+ *
+ * A chunk is a run of at most STORE_CHUNK_TARGET features of one kind. It owns at most one
+ * retained batch (a GPU resource); an immediate chunk owns none and is drawn one feature at a time.
+ */
+import type { Feature, Layer } from '../../store/types.js';
+import type { RetainedLineBatch } from '../renderers/line/line-types.js';
+import { type RetainedPointBatch } from '../renderers/point/point-instance.js';
+import type { RetainedPolygonBatch } from '../renderers/polygon/sdf-polygon.js';
+import type { RetainedRendererSet } from '../renderers/retained.js';
+import type { ChunkBBox } from './store-retained-bbox.js';
+import type { RunKind } from './store-retained-classify.js';
+import { type CoordPatch, type LineCoordSlot } from './store-retained-coord-patch.js';
+/** Upper limit of the number of features per chunk */
+export declare const STORE_CHUNK_TARGET = 512;
+/**
+ * One chunk (= one retained batch, or a list of features drawn immediately)
+ */
+export interface ChunkEntry {
+    readonly kind: RunKind;
+    readonly featureIds: string[];
+    /** The retained batch (null for immediate, or when the contents are empty) */
+    line: RetainedLineBatch | null;
+    polygon: RetainedPolygonBatch | null;
+    point: RetainedPointBatch | null;
+    /** Whether a rebuild is needed (the retained batch is not used while this is true) */
+    dirty: boolean;
+    /**
+     * "feature → position in the coordinate texture" of a line chunk
+     *
+     * Used for the incremental update of vertices. Only the types whose coordinate list goes in as
+     * one contiguous run (LineString / Freehand) are recorded. It is null for anything but a line
+     * chunk and for a chunk without a batch.
+     */
+    lineOffsets: Map<string, LineCoordSlot> | null;
+    /**
+     * Vertices to write into the coordinate texture on the next draw (the diff during a drag)
+     *
+     * The chunk does not become dirty while they are queued (it is not rebuilt).
+     */
+    pendingCoordPatches: CoordPatch[] | null;
+    /**
+     * Longitude/latitude bbox of every feature in the chunk
+     *
+     * Used for the thinning by the viewport. It is null for a chunk without a single coordinate,
+     * and such a chunk is always drawn without thinning (the safe side).
+     */
+    bbox: ChunkBBox | null;
+    /**
+     * The origin the retained batch was built with (null before the first build)
+     *
+     * The vertices are baked relative to it, so the precision on screen depends on how far it is
+     * from what is on screen (see `view/shaders/retained-origin.ts`).
+     */
+    origin: [number, number] | null;
+    /**
+     * The origin chosen for the view by the last rebase (null = the center of the bbox)
+     *
+     * Kept across rebuilds, so a change of the data does not move the origin away from the view.
+     */
+    viewOrigin: [number, number] | null;
+    /** The frame of the last rebase (a chunk is rebased at most once per frame) */
+    rebasedFrame: number;
+}
+/**
+ * Cache for a single layer
+ */
+export interface LayerCache {
+    readonly chunks: ChunkEntry[];
+    /** featureId → chunk index (for partial invalidation) */
+    readonly featureToChunk: Map<string, number>;
+}
+/** Result of building a chunk */
+export type ChunkBuildResult = 
+/** A retained batch was built */
+'built'
+/** There was nothing to draw (no retained batch is needed) */
+ | 'empty'
+/** The GPU resource could not be created (shaders not initialized). Retry on the next frame */
+ | 'retry'
+/** The classification disagreed with the kind of the chunk. Rebuild the whole layer */
+ | 'mismatch';
+/**
+ * A new chunk of the given kind, waiting for its first build
+ */
+export declare function createChunkEntry(kind: RunKind): ChunkEntry;
+/**
+ * Builds the retained batch that matches the kind of the chunk
+ */
+export declare function buildChunkBatch(chunk: ChunkEntry, features: Feature[], layer: Layer | undefined, origin: [number, number], renderers: RetainedRendererSet): ChunkBuildResult;
+/**
+ * Releases the retained batch of a chunk
+ *
+ * @param renderers Where to release the GPU resources (null = only the references are dropped)
+ */
+export declare function disposeChunkBatches(chunk: ChunkEntry, renderers: RetainedRendererSet | null): void;

package/dist/view/layer/store-retained-chunk.js

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { toInstancedPointShape, } from '../renderers/point/point-instance.js';
+import { collectLineItems, collectPoints, collectPolygons } from './store-retained-collect.js';
+import { computeLineCoordSlots, } from './store-retained-coord-patch.js';
+/** Upper limit of the number of features per chunk */
+export const STORE_CHUNK_TARGET = 512;
+/**
+ * A new chunk of the given kind, waiting for its first build
+ */
+export function createChunkEntry(kind) {
+    return {
+        kind,
+        featureIds: [],
+        line: null,
+        polygon: null,
+        point: null,
+        dirty: true,
+        lineOffsets: null,
+        pendingCoordPatches: null,
+        bbox: null,
+        origin: null,
+        viewOrigin: null,
+        rebasedFrame: -1,
+    };
+}
+/**
+ * Builds the retained batch that matches the kind of the chunk
+ */
+export function buildChunkBatch(chunk, features, layer, origin, renderers) {
+    const styles = renderers.styles;
+    if (chunk.kind === 'line') {
+        const items = collectLineItems(features, styles, layer);
+        if (items.length === 0)
+            return 'empty';
+        const batch = renderers.line.buildRetainedBatch(items, { lineStyle: 'solid' }, { origin });
+        if (!batch)
+            return 'retry';
+        chunk.line = batch;
+        // Index table used for the incremental update of a vertex drag (kept in step with the order
+        // of items)
+        chunk.lineOffsets = computeLineCoordSlots(features);
+        return 'built';
+    }
+    if (chunk.kind === 'polygon') {
+        const polygons = collectPolygons(features, styles, layer);
+        if (polygons.length === 0)
+            return 'empty';
+        const batch = renderers.polygon.buildRetained(polygons, { origin });
+        if (!batch)
+            return 'retry';
+        chunk.polygon = batch;
+        return 'built';
+    }
+    const shape = pointShapeOfRun(chunk.kind);
+    if (shape) {
+        const points = collectPoints(features, styles, layer);
+        if (points.length === 0)
+            return 'empty';
+        const batch = renderers.point.buildRetained(points, shape, { origin });
+        if (!batch)
+            return 'retry';
+        chunk.point = batch;
+        return 'built';
+    }
+    return 'empty';
+}
+/**
+ * The point shape of a point run (null for any other kind)
+ */
+function pointShapeOfRun(kind) {
+    return kind.startsWith('point-') ? toInstancedPointShape(kind.slice('point-'.length)) : null;
+}
+/**
+ * Releases the retained batch of a chunk
+ *
+ * @param renderers Where to release the GPU resources (null = only the references are dropped)
+ */
+export function disposeChunkBatches(chunk, renderers) {
+    if (renderers) {
+        if (chunk.polygon)
+            renderers.polygon.disposeRetained(chunk.polygon);
+        if (chunk.line)
+            renderers.line.disposeRetainedBatch(chunk.line);
+        if (chunk.point)
+            renderers.point.disposeRetained(chunk.point);
+    }
+    chunk.polygon = null;
+    chunk.line = null;
+    chunk.point = null;
+    // Once the batch is gone, both the index table and the queued patches lose their meaning
+    chunk.lineOffsets = null;
+    chunk.pendingCoordPatches = null;
+}

package/dist/view/layer/store-retained-classify.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Classification of the Store features into runs
+ *
+ * A run is a sequence of features that the BatchManager of immediate mode would draw in one
+ * batch. Cutting the feature list where the kind changes keeps the z-order of retained mode
+ * identical to immediate mode.
+ */
+import type { Feature, Layer } from '../../store/types.js';
+import type { FeatureCompanionRegistry } from '../feature-companion.js';
+import { type PointShape } from '../renderers/point/point-instance.js';
+import type { RetainedStyleResolver } from '../renderers/retained.js';
+/**
+ * Kind of a run
+ *
+ * It is matched with the unit at which the BatchManager of immediate mode flushes a batch (the
+ * batch kind and the point shape). A position where the kind changes becomes a run boundary.
+ */
+export type RunKind = 'polygon' | 'line' | `point-${PointShape}` | 'immediate';
+/**
+ * Classifies a feature into the kind of its run
+ *
+ * It copies the batch kinds, the flush rules and the fallback rules of immediate mode
+ * (BatchManager.processFeature) as they are. If this drifts from immediate mode the z-order
+ * breaks, so keep the conditions here in one-to-one correspondence with the immediate-mode side.
+ *
+ * @param customTypes Renderers of the custom feature types (a registered type is drawn at once)
+ * @param layer The layer it belongs to (used to evaluate the style rules)
+ */
+export declare function classifyFeature(feature: Feature, styles: RetainedStyleResolver, customTypes: ReadonlyMap<string, unknown>, companions: FeatureCompanionRegistry, layer?: Layer): RunKind;
+/**
+ * Origin of the relative coordinates of a chunk (the representative coordinate of the first
+ * feature)
+ */
+export declare function featureOrigin(feature: Feature | undefined): [number, number];

package/dist/view/layer/store-retained-classify.js

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { toInstancedPointShape } from '../renderers/point/point-instance.js';
+/**
+ * Classifies a feature into the kind of its run
+ *
+ * It copies the batch kinds, the flush rules and the fallback rules of immediate mode
+ * (BatchManager.processFeature) as they are. If this drifts from immediate mode the z-order
+ * breaks, so keep the conditions here in one-to-one correspondence with the immediate-mode side.
+ *
+ * @param customTypes Renderers of the custom feature types (a registered type is drawn at once)
+ * @param layer The layer it belongs to (used to evaluate the style rules)
+ */
+export function classifyFeature(feature, styles, customTypes, companions, layer) {
+    // A custom type is drawn immediately (it cannot go on a core batch)
+    if (customTypes.has(feature.type))
+        return 'immediate';
+    // A feature that has a companion (feature companion) needs a hook right before it, so it cannot
+    // go on a retained batch. It is split out into an immediate chunk and drawn one at a time (on
+    // the assumption that features with a companion are few; if no provider at all is registered
+    // this test is false in O(1)).
+    if (companions.has(feature))
+        return 'immediate';
+    switch (feature.type) {
+        case 'Point':
+        case 'MultiPoint': {
+            const shape = toInstancedPointShape(styles.getPointStyle(feature, layer).shape);
+            // A shape without instancing support is drawn immediately, one point at a time
+            return shape ? `point-${shape}` : 'immediate';
+        }
+        case 'LineString':
+        case 'Freehand':
+        case 'MultiLineString': {
+            const strokeStyle = styles.getLineStringStrokeStyle(feature, layer);
+            // Dashed and dotted lines cannot be retained because their CPU-side splitting depends on
+            // the zoom
+            return strokeStyle.lineStyle === 'solid' ? 'line' : 'immediate';
+        }
+        case 'Polygon':
+        case 'MultiPolygon':
+        case 'Circle': {
+            const { strokeStyle } = styles.getPolygonStyles(feature, layer);
+            // Only a dashed outline cannot be retained (fill only and a solid outline can be)
+            if (strokeStyle.opacity > 0 && strokeStyle.lineStyle !== 'solid')
+                return 'immediate';
+            return 'polygon';
+        }
+        default:
+            // Kinds that retained mode does not handle, such as Image
+            return 'immediate';
+    }
+}
+/**
+ * Origin of the relative coordinates of a chunk (the representative coordinate of the first
+ * feature)
+ */
+export function featureOrigin(feature) {
+    if (!feature)
+        return [0, 0];
+    switch (feature.type) {
+        case 'MultiPoint': {
+            const coord = feature.coordinates[0];
+            return coord ? [coord[0], coord[1]] : [0, 0];
+        }
+        case 'LineString':
+        case 'Freehand': {
+            const coord = feature.coordinates[0];
+            return coord ? [coord[0], coord[1]] : [0, 0];
+        }
+        case 'MultiLineString': {
+            const coord = feature.coordinates[0]?.[0];
+            return coord ? [coord[0], coord[1]] : [0, 0];
+        }
+        case 'Polygon': {
+            const coord = feature.coordinates[0]?.[0];
+            return coord ? [coord[0], coord[1]] : [0, 0];
+        }
+        case 'MultiPolygon': {
+            const coord = feature.coordinates[0]?.[0]?.[0];
+            return coord ? [coord[0], coord[1]] : [0, 0];
+        }
+        default: {
+            // A single coordinate, such as Point / Circle
+            const coord = feature.coordinates;
+            return Array.isArray(coord) && typeof coord[0] === 'number' ? [coord[0], coord[1]] : [0, 0];
+        }
+    }
+}

package/dist/view/layer/store-retained-collect.d.ts

@@ -0,0 +1,24 @@
+import type { Feature, Layer } from '../../store/types.js';
+import type { LineBatchItem } from '../renderers/line/line-types.js';
+import type { PointInstanceDataFull } from '../renderers/point/point-instance.js';
+import type { SDFPolygonBatchData } from '../renderers/polygon/sdf-polygon.js';
+import type { RetainedStyleResolver } from '../renderers/retained.js';
+/**
+ * Collects the items of a line batch
+ *
+ * A feature without createdZoom has to be drawn with a constant width on screen. u_zoom is per
+ * batch, so a fixed width is expressed with a negative width (a convention of the shader). This
+ * way fixed widths and variable widths can be mixed in the same batch and the z-order is kept.
+ */
+export declare function collectLineItems(features: Feature[], styles: RetainedStyleResolver, layer: Layer | undefined): LineBatchItem[];
+/**
+ * Collects the data of a polygon batch
+ *
+ * A fill-only polygon is also pushed as an SDFPolygon without an outline (strokeOpacity = 0).
+ * Immediate mode draws it with PolygonBatchRenderer, but the appearance of the fill is the same.
+ */
+export declare function collectPolygons(features: Feature[], styles: RetainedStyleResolver, layer: Layer | undefined): SDFPolygonBatchData[];
+/**
+ * Collects the data of the point instances
+ */
+export declare function collectPoints(features: Feature[], styles: RetainedStyleResolver, layer: Layer | undefined): PointInstanceDataFull[];

package/dist/view/layer/store-retained-collect.js

@@ -0,0 +1,121 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Conversions from features to the data of a retained batch
+ *
+ * The same math as the collect functions of display: the style is resolved once at build time
+ * and the result is baked into the vertex or instance data of the batch.
+ */
+import { generateCirclePolygon } from '../../shared/math/index.js';
+import { getCircleRadius, getCreatedZoom } from '../../shared/utils/property.js';
+import { toLineBatchItem, toPointInstanceData } from '../renderers/batch-manager.js';
+/**
+ * createdZoom of a fixed-width feature
+ *
+ * When the line width is expressed as a negative value the shader ignores createdZoom, so the
+ * value itself has no meaning. It is a constant only to decide what goes into the array.
+ */
+const FIXED_WIDTH_CREATED_ZOOM = 0;
+/**
+ * Collects the items of a line batch
+ *
+ * A feature without createdZoom has to be drawn with a constant width on screen. u_zoom is per
+ * batch, so a fixed width is expressed with a negative width (a convention of the shader). This
+ * way fixed widths and variable widths can be mixed in the same batch and the z-order is kept.
+ */
+export function collectLineItems(features, styles, layer) {
+    const items = [];
+    for (const feature of features) {
+        const strokeStyle = styles.getLineStringStrokeStyle(feature, layer);
+        const createdZoom = getCreatedZoom(feature);
+        const push = (coords) => {
+            if (!coords || coords.length < 2)
+                return;
+            const item = toLineBatchItem(coords, feature.id, strokeStyle, createdZoom ?? FIXED_WIDTH_CREATED_ZOOM);
+            if (createdZoom === undefined)
+                item.strokeWidth = -strokeStyle.width;
+            items.push(item);
+        };
+        if (feature.type === 'MultiLineString') {
+            for (const part of feature.coordinates)
+                push(part);
+        }
+        else {
+            push(feature.coordinates);
+        }
+    }
+    return items;
+}
+/**
+ * Collects the data of a polygon batch
+ *
+ * A fill-only polygon is also pushed as an SDFPolygon without an outline (strokeOpacity = 0).
+ * Immediate mode draws it with PolygonBatchRenderer, but the appearance of the fill is the same.
+ */
+export function collectPolygons(features, styles, layer) {
+    const polygons = [];
+    for (const feature of features) {
+        const { fillColor, strokeStyle } = styles.getPolygonStyles(feature, layer);
+        const hasStroke = strokeStyle.opacity > 0 && strokeStyle.width > 0;
+        const createdZoom = getCreatedZoom(feature);
+        // The outline of a feature without createdZoom has a fixed width (the negative convention)
+        const strokeWidth = hasStroke
+            ? createdZoom === undefined
+                ? -strokeStyle.width
+                : strokeStyle.width
+            : 0;
+        const push = (rings, partIndex) => {
+            const outerRing = rings?.[0];
+            if (!rings || !outerRing || outerRing.length < 3)
+                return;
+            if (!hasStroke && fillColor[3] <= 0)
+                return;
+            polygons.push({
+                coordinates: rings,
+                style: {
+                    fillColor,
+                    fillOpacity: 1,
+                    strokeColor: strokeStyle.color,
+                    strokeWidth,
+                    strokeOpacity: hasStroke ? 1 : 0,
+                },
+                createdZoom: createdZoom ?? FIXED_WIDTH_CREATED_ZOOM,
+                featureId: feature.id,
+                partIndex,
+            });
+        };
+        if (feature.type === 'MultiPolygon') {
+            const parts = feature.coordinates;
+            for (let i = 0; i < parts.length; i++)
+                push(parts[i], i);
+        }
+        else if (feature.type === 'Circle') {
+            const radiusMeters = getCircleRadius(feature);
+            if (!radiusMeters || radiusMeters <= 0)
+                continue;
+            push([generateCirclePolygon(feature.coordinates, radiusMeters)], 0);
+        }
+        else {
+            push(feature.coordinates, 0);
+        }
+    }
+    return polygons;
+}
+/**
+ * Collects the data of the point instances
+ */
+export function collectPoints(features, styles, layer) {
+    const points = [];
+    for (const feature of features) {
+        const style = styles.getPointStyle(feature, layer);
+        if (feature.type === 'MultiPoint') {
+            for (const coord of feature.coordinates) {
+                points.push(toPointInstanceData(coord, style));
+            }
+        }
+        else {
+            points.push(toPointInstanceData(feature.coordinates, style));
+        }
+    }
+    return points;
+}

package/dist/view/layer/store-retained-coord-patch.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Incremental update of the coordinate texture of a retained line chunk
+ *
+ * A vertex drag moves only a few vertices. Rebuilding a line chunk with many vertices every frame
+ * would overflow the frame, so the diff of the vertices that moved is queued on the chunk and,
+ * right before drawing, only the corresponding texels of the coordinate texture are rewritten
+ * (see SDFLineRenderer.patchRetainedBatchCoords).
+ */
+import type { Coordinate, Feature } from '../../store/types.js';
+import type { RetainedLineBatch } from '../renderers/line/line-types.js';
+import type { SDFLineRenderer } from '../renderers/line/sdf-line.js';
+import type { RetainedLineRenderer } from '../renderers/retained.js';
+import { type ChunkBBox } from './store-retained-bbox.js';
+/**
+ * Upper limit of the number of vertices that one update may put into the incremental update of
+ * the coordinate texture
+ *
+ * A change beyond this (moving vertices in bulk, cut and paste) rebuilds the whole chunk.
+ * The incremental update targets the case where "one vertex drag moves only a few points".
+ */
+export declare const MAX_PATCHED_VERTICES = 8;
+/**
+ * Position of a feature within the coordinate texture of a line chunk
+ */
+export interface LineCoordSlot {
+    /** Serial index of the first texel in the coordinate texture */
+    offset: number;
+    /** Number of vertices (this many are stored consecutively) */
+    count: number;
+}
+/**
+ * Diff of one vertex to write back into the coordinate texture
+ */
+export interface CoordPatch {
+    coordIndex: number;
+    lngLat: [number, number];
+}
+/**
+ * A line renderer that supports partial updates of the coordinate texture
+ *
+ * It is not included in `RetainedLineRenderer` (renderers/retained.ts), so whether the
+ * implementation is present is checked at runtime before it is used.
+ */
+export type LineCoordPatcher = Pick<SDFLineRenderer, 'patchRetainedBatchCoords'>;
+/**
+ * Extracts the line renderer if it supports partial updates of the coordinate texture
+ */
+export declare function asCoordPatcher(line: RetainedLineRenderer): LineCoordPatcher | null;
+/**
+ * Computes the diff of a coordinate list (the indices of the vertices that moved)
+ *
+ * A vertex drag is an update where "the number of vertices is the same and only a few values
+ * differ". Anything else (vertices added or removed, many of them moved) cannot be applied as a
+ * diff, so null is returned.
+ *
+ * The comparison is done in a single pass. If the element references are the same, that vertex
+ * has not moved (the Store reuses the arrays of the vertices it does not change). The values are
+ * looked at only when the references differ.
+ *
+ * @param maxChanged Upper limit of the number of changed vertices allowed as a diff
+ * @returns The indices of the vertices that moved (an empty array when none moved). null when
+ *   the number of vertices differs or the upper limit is exceeded
+ */
+export declare function computeCoordinateDiff(prev: readonly Coordinate[], next: readonly Coordinate[], maxChanged: number): number[] | null;
+/**
+ * Computes the "feature → position in the coordinate texture" of a line chunk
+ *
+ * The coordinate texture is packed with the coordinates in the order of the items returned by
+ * collectLineItems. Therefore this must count in the same order and with the same exclusion rule
+ * as collectLineItems (fewer than 2 vertices are not pushed).
+ *
+ * Only the types where one feature becomes one item and the coordinate list goes in as it is
+ * (LineString / Freehand) are recorded. A MultiLineString splits into several items and its
+ * indices interleave, so it is not a target of the diff (only the coordinate count is advanced).
+ */
+export declare function computeLineCoordSlots(features: readonly Feature[]): Map<string, LineCoordSlot>;
+/**
+ * The part of a chunk that the incremental update reads and writes
+ *
+ * The chunk of the cache satisfies it structurally.
+ */
+export interface PatchableLineChunk {
+    readonly kind: string;
+    line: RetainedLineBatch | null;
+    /** Whether a rebuild is needed (a dirty chunk takes no patches) */
+    dirty: boolean;
+    lineOffsets: Map<string, LineCoordSlot> | null;
+    pendingCoordPatches: CoordPatch[] | null;
+    bbox: ChunkBBox | null;
+}
+/**
+ * Queues a vertex movement as a diff patch against the retained batch
+ *
+ * It can be queued only when all of the following hold. If even one of them fails, false is
+ * returned and the caller rebuilds the whole chunk (rebuilding too much still renders
+ * correctly).
+ *
+ * - A type whose coordinate list goes into the coordinate texture as one contiguous run
+ *   (LineString / Freehand)
+ * - No other item that affects the appearance (properties = the input of the style rules) has
+ *   changed
+ * - The number of vertices is unchanged and between 1 and MAX_PATCHED_VERTICES vertices moved
+ * - The chunk it belongs to has a retained line batch and is not waiting for a rebuild
+ * - The renderer used for drawing supports partial updates of the coordinate texture
+ *
+ * The drag being committed (up) does not trigger another rebuild. The patch queued by the last
+ * movement becomes the committed value as it is.
+ *
+ * @param chunk The chunk that carries the feature (undefined when there is none)
+ * @param line The line renderer used most recently (null before the first draw)
+ */
+export declare function queueCoordPatch(chunk: PatchableLineChunk | undefined, feature: Feature, previous: Feature, line: RetainedLineRenderer | null): boolean;
+/**
+ * Applies the queued vertex diff to the coordinate texture
+ *
+ * It is not called for a chunk thinned away off-screen, but the patches stay queued, so they
+ * are all applied on the first frame where the chunk comes into view.
+ */
+export declare function flushCoordPatches(chunk: PatchableLineChunk, line: RetainedLineRenderer): void;