@react-x11/components 0.3.0 → 0.5.0

package/dist/maps/paint.d.ts

@@ -0,0 +1,226 @@
+import type { CompiledFilter, MapStyleLayer } from './style.js';
+import { GeometryBuffer } from './mvt.js';
+import type { VectorTile } from './mvt.js';
+/**
+ * The slice of ntk's 2d context this draws through.
+ *
+ * Structural because react-x11 types `Context2D` as `unknown` on purpose —
+ * it is ntk's API rather than react-x11's — so something has to name the
+ * operations, and naming them once beats naming them at sixty call sites
+ * (the same argument `src/flow/draw.ts` makes).
+ */
+export interface MapCanvas {
+    fillStyle: unknown;
+    strokeStyle: unknown;
+    lineWidth: number;
+    lineJoin?: unknown;
+    lineCap?: unknown;
+    globalAlpha?: number;
+    save(): void;
+    restore(): void;
+    beginPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    arc(x: number, y: number, r: number, from: number, to: number): void;
+    fill(): void;
+    stroke(): void;
+    clip(): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    /** One request for many rectangles — what a marker cluster and a
+     *  scale bar are drawn with. */
+    fillRects?(rects: readonly number[]): void;
+    setLineDash?(segments: readonly number[]): void;
+    roundRect?(x: number, y: number, w: number, h: number, radii: number): void;
+    drawImage?(image: unknown, ...args: number[]): void;
+    /** Straight RGBA in, for a raster tile the application decoded. */
+    putImageData?(data: {
+        width: number;
+        height: number;
+        data: Uint8Array;
+    }, x: number, y: number): void;
+}
+/**
+ * Whether a context can draw at all.
+ *
+ * The mock backend the headless suite runs on has no path API, which is the
+ * repo convention for keeping a drawn element testable: the element's paint
+ * becomes a no-op there rather than a throw, and everything worth asserting
+ * about it — the cover, the projection, the cache, the hit test — is
+ * asserted without pixels.
+ */
+export declare function isMapCanvas(ctx: unknown): ctx is MapCanvas;
+/**
+ * The clock a rasterization budget is measured on.
+ *
+ * `performance.now()` rather than `Date.now()`, because a budget is a
+ * sub-frame quantity and `Date.now()` counts whole milliseconds: an 8 ms
+ * budget measured on it carries 12% of error, and anything under 1 ms
+ * rounds to a deadline that has already passed — so `rasterBudgetMs: 0.5`
+ * would silently mean "never rasterize", which is not what it says.
+ * Reached through `globalThis` because `src/` compiles with `types: []`.
+ */
+export declare function now(): number;
+/** Vertices after which the accumulated path is flushed. Large enough that
+ *  a whole ordinary layer is one path, small enough that the 130,000-vertex
+ *  outlier is a few rather than one enormous request. */
+export declare const BATCH_VERTICES = 12000;
+/**
+ * How a tile's own integer coordinates reach the target.
+ *
+ * `ox`/`oy`/`span` place the tile: its local `0` lands at `ox`, and its
+ * whole square is `span` target pixels across — so a layer's scale is
+ * `span / layer.extent`, computed **per layer**, because extent is a
+ * per-layer field and real tiles use that (OSM's Shortbread cuts `streets`,
+ * `land`, `ocean` and `water_polygons` at 2048 and its other twenty layers
+ * at 4096; a renderer that reads it once per tile draws half of them at
+ * twice their size).
+ *
+ * `pixelsPerLogical` is what a style's lengths are multiplied by. On the
+ * direct path it is simply the display scale. On the retained path it is
+ * `surfaceSize / tileScreenSize`, which is the display scale divided by
+ * whatever the composite is about to multiply by — so a two-logical-pixel
+ * road is two logical pixels on screen at every fractional zoom, without
+ * the raster being redrawn for any of them.
+ */
+export interface TileDraw {
+    ox: number;
+    oy: number;
+    span: number;
+    pixelsPerLogical: number;
+    /** The zoom the style is resolved at. */
+    zoom: number;
+    /** Target pixels below which a vertex is dropped as a duplicate of the
+     *  one before it. `0` disables decimation. */
+    tolerance?: number;
+    /** Target pixels below which a whole feature is skipped. */
+    minFeature?: number;
+    /** Clip rectangle in target coordinates — the direct path's viewport.
+     *  Null on the retained path, where the surface is the clip. */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Vertices after which the accumulated path is flushed, if not
+     * {@link BATCH_VERTICES}.
+     *
+     * One number for both backends since react-x11 2.6.1, and it was not
+     * before that. On **X11** a fill or stroke becomes an a8 coverage mask
+     * over the path's bounding box, uploaded with one `PutImage`, so a bigger
+     * path is fewer uploads over the same pixels — the number wants to be
+     * large. On the **Cocoa** backend `CGContextStrokePath` used to be
+     * quadratic in the number of subpaths, so it wanted the opposite, and
+     * `<Map>` probed the backend to pick. Core chunks that stroke itself now
+     * (react-x11#457), at a size it can choose and a caller cannot, so
+     * batching small there only defeats it.
+     */
+    batchVertices?: number;
+}
+/** What a rasterization cost, for the bench and for `onFrame`. */
+export interface DrawStats {
+    layers: number;
+    features: number;
+    /** Vertices that survived decimation and were sent. */
+    vertices: number;
+    /** Vertices dropped as sub-pixel duplicates. */
+    decimated: number;
+    /** Features skipped because their whole box was sub-pixel. */
+    culled: number;
+    /** `fill()` and `stroke()` calls — the request count, near enough. */
+    batches: number;
+}
+/** A style layer with its filter already compiled — what a cache holds so
+ *  the compile happens once per style rather than once per tile. */
+export interface PreparedLayer {
+    layer: MapStyleLayer;
+    filter: CompiledFilter;
+}
+/** A maximal run of consecutive style layers over one source layer. */
+export interface StyleRun {
+    sourceLayer: string;
+    /** `[from, to)` into {@link PreparedStyle.layers}. */
+    from: number;
+    to: number;
+}
+/**
+ * A style with its filters compiled and its runs found — computed once per
+ * style, not once per tile.
+ *
+ * The runs are also the unit of **resumable** rasterization: a tile's own
+ * layers are drawn run by run, with a time budget between them, so a
+ * hundred-millisecond tile becomes a dozen frames that each stay inside
+ * one. See {@link drawTileRun}.
+ */
+export interface PreparedStyle {
+    layers: PreparedLayer[];
+    runs: StyleRun[];
+}
+/**
+ * Compile a style once.
+ *
+ * Runs rather than a global grouping by source layer, because the order a
+ * style lists its layers in *is* the cartography — water over landuse,
+ * buildings over both — and a grouping would reorder a style that
+ * interleaves two sources. A run preserves order exactly and captures the
+ * win whenever a style is written the way the casing-then-fill split forces
+ * anyway: a road network is fourteen consecutive layers over `streets`.
+ */
+export declare function prepareStyle(style: {
+    layers: readonly MapStyleLayer[];
+}): PreparedStyle;
+/**
+ * Scratch a caller keeps between tiles, so nothing here allocates per
+ * feature or per layer.
+ */
+export declare class DrawScratch {
+    buffer: GeometryBuffer;
+    /** One clipped ring at a time, reused, so the overzoom path allocates
+     *  nothing per part either. */
+    ring: number[];
+    stats: DrawStats;
+    private _buckets;
+    /** `n` index lists, emptied. Grown to the widest run ever seen and then
+     *  reused for the life of the element. */
+    buckets(n: number): number[][];
+    resetStats(): DrawStats;
+}
+/**
+ * Draw every layer of the style this tile has data for.
+ *
+ * The style is walked in **runs of consecutive layers over one source
+ * layer**, and each run's features are seeked once for the whole run. That
+ * is worth stating plainly because it is the difference between a fast
+ * zoom-12 tile and a slow one: a road network is fourteen style layers over
+ * `streets` (seven classes, and a casing pass before the fill pass so that
+ * junctions knit), so a layer-at-a-time walk parses each of eight thousand
+ * features' headers and tags fourteen times over. A run parses them once
+ * and asks fourteen already-compiled filters about them.
+ *
+ * Runs rather than a global grouping by source layer, because the order a
+ * style lists its layers in *is* the cartography — water over landuse,
+ * buildings over both — and a grouping would reorder a style that
+ * interleaves. A run preserves order exactly and captures the win whenever
+ * a style is written the way the casing/fill split forces anyway.
+ */
+export declare function drawTileLayers(ctx: MapCanvas, tile: VectorTile, prepared: PreparedStyle, draw: TileDraw, scratch: DrawScratch): DrawStats;
+/**
+ * One run of the style, drawn.
+ *
+ * The unit a caller budgets in: the node draws runs until its per-frame
+ * budget is spent, remembers where it stopped, and comes back next frame.
+ * Layers are painted bottom-up, so a tile stopped part-way looks like a map
+ * whose upper layers have not arrived — which is what a partly-drawn map
+ * should look like — rather than like a hole.
+ */
+export declare function drawTileRun(ctx: MapCanvas, tile: VectorTile, prepared: PreparedStyle, runIndex: number, draw: TileDraw, scratch: DrawScratch, resume?: {
+    /** Skip this many of the run's active layers — where a previous frame
+     *  stopped. */
+    fromLayer?: number;
+    /** Stop after the layer that crosses this, on {@link now}'s clock. */
+    deadline?: number;
+}): number;
+//# sourceMappingURL=paint.d.ts.map

package/dist/maps/paint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../src/maps/paint.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAU,MAAM,YAAY,CAAC;AAExE,OAAO,EAAY,cAAc,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,UAAU,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,IAAI,IAAI,CAAC;IACb,OAAO,IAAI,IAAI,CAAC;IAChB,SAAS,IAAI,IAAI,CAAC;IAClB,SAAS,IAAI,IAAI,CAAC;IAClB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,IAAI,IAAI,IAAI,CAAC;IACb,MAAM,IAAI,IAAI,CAAC;IACf,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D;oCACgC;IAChC,SAAS,CAAC,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C,WAAW,CAAC,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAChD,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5E,SAAS,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACpD,mEAAmE;IACnE,YAAY,CAAC,CACX,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,EACzD,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,IAAI,CAAC;CACT;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,SAAS,CAG1D;AAID;;;;;;;;;GASG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED;;yDAEyD;AACzD,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb;kDAC8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;oEACgE;IAChE,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtE;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAaD;oEACoE;AACpE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAClC,GAAG,aAAa,CAoBhB;AAiBD;;;GAGG;AACH,qBAAa,WAAW;IACtB,MAAM,iBAAwB;IAC9B;mCAC+B;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAM;IACpB,KAAK,EAAE,SAAS,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAAkB;IAElC;8CAC0C;IAC1C,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAI7B;IAED,UAAU,IAAI,SAAS,CAGtB;CACF;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,WAAW,GACnB,SAAS,CAKX;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE;IACP;mBACe;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,MAAM,CAyDR"}