@react-x11/components 0.8.0 → 0.10.0

package/src/maps/types.ts

@@ -26,6 +26,29 @@ export type {
   SymbolLayer,
   Zoomed,
 } from './style.js';
+export type { MapIcon } from './icons.js';
+
+/** Which renderer draws a map — see `<Map renderer>`. */
+export type MapRenderer = 'gl' | 'retained';
+
+/**
+ * What `<Map renderer>` asks for: one of the two renderers, or `'auto'` —
+ * GL wherever this connection has direct GL, and the retained renderer
+ * everywhere else.
+ */
+export type MapRendererRequest = 'auto' | MapRenderer;
+
+/** Why a map is drawn with the renderer it is, when that is not what it
+ *  asked for. */
+export type MapRendererReason =
+  /** The connection has no direct GL — indirect GLX, or none at all —
+   *  so `useSupports('shaders')` is false. */
+  | 'no-direct-gl'
+  /** GL failed at run time: no surface, a context that would not create, a
+   *  shader that would not compile, a throw from a frame. */
+  | 'gl-failed'
+  /** `REACT_X11_MAP_RENDERER` chose it. */
+  | 'forced';
 
 /** Where a pointer event happened, in every space that could be wanted. */
 export interface MapPointerEvent {
@@ -45,28 +68,50 @@ export interface MapPointerEvent {
   button: number;
 }
 
-/** What one frame cost — for a performance HUD, and what
- *  `scripts/bench/maps.ts` reads. */
+/**
+ * What one frame cost — for a performance HUD, and what the benches read.
+ *
+ * The fields both renderers have are named the same; the ones only one of
+ * them has are optional, and present on that renderer's frames.
+ */
 export interface MapFrameStats {
+  /** Which renderer drew the frame. */
+  renderer: MapRenderer;
   /** Milliseconds spent rasterizing tiles into their surfaces this frame.
-   *  Bounded by `rasterBudgetMs` except for the one run that crossed it. */
+   *  Bounded by `rasterBudgetMs` except for the one run that crossed it.
+   *  Always `0` on the GL renderer, which rasterizes nothing. */
   rasterMs: number;
-  /** …and compositing them, drawing the labels, overlays and markers. */
+  /** The rest of the frame on this thread: compositing tiles and drawing
+   *  the labels, overlays and markers (retained), or issuing the frame's GL
+   *  calls and placing its labels (GL — the GPU's own time is not in it). */
   drawMs: number;
   /** Tiles the cover asked for. */
   tiles: number;
-  /** …of which were composited from their own finished surface. Under
-   *  `progressive` this also counts the half-drawn ones. */
+  /** …of which were drawn from their own data: a finished surface
+   *  (retained; under `progressive` the half-drawn ones too) or their own
+   *  geometry (GL). */
   ready: number;
   /** …and how many were drawn from a coarser ancestor instead, scaled up.
    *  What covers a hole while zooming *in*. */
   fromAncestor: number;
   /** …and how many from their finer descendants, scaled down. What covers
-   *  a hole while zooming *out*, where there is no ancestor to borrow. */
+   *  a hole while zooming *out*, where there is no ancestor to borrow.
+   *  Descendants cover what they can and an ancestor the gaps between them,
+   *  so a hole covered partly from each counts in both. */
   fromDescendant: number;
-  /** Tiles still to rasterize — non-zero means the map is still sharpening
-   *  and another frame is already scheduled. */
+  /** Tiles still to rasterize (retained) or to build (GL) — non-zero means
+   *  the map is still sharpening and another frame is already scheduled. */
   pending: number;
+  /**
+   * Whether what is on screen is the previous style.
+   *
+   * True from a `mapStyle` change or `refresh()` until the swap: the new
+   * style is drawn behind the old picture — tiles, background and labels —
+   * and replaces all of it in one frame, so the map never shows the two at
+   * once. The first frame it is false again is the one that swapped. Never
+   * true under `progressive`, which shows the repaint as it happens.
+   */
+  restyling: boolean;
   /** Labels placed, and labels drawn. */
   labels: number;
   /**
@@ -77,10 +122,12 @@ export interface MapFrameStats {
    * difference is not something a user can see.
    */
   errors: number;
-  /** Bytes of rendered surfaces the cache is holding. */
+  /** Bytes of rendered surfaces the cache is holding. `0` on the GL
+   *  renderer, whose tiles are geometry — its bytes are `gl.gpuBytes`. */
   surfaceBytes: number;
   /**
-   * What this pass repainted, in device pixels, or `null` for a full one.
+   * What this pass repainted, in device pixels, or `null` for a full one —
+   * which every GL frame is.
    *
    * The number to watch when a map looks busy: a frame that is only
    * continuing a rasterization should claim almost nothing, because the
@@ -90,7 +137,8 @@ export interface MapFrameStats {
    * many frames a second reads as flashing.
    */
   damage: { x: number; y: number; width: number; height: number } | null;
-  /** What the rasterizer did, summed over the tiles drawn this frame. */
+  /** What the rasterizer did, summed over the tiles drawn this frame. All
+   *  zeros on the GL renderer. */
   draw: {
     features: number;
     vertices: number;
@@ -98,6 +146,57 @@ export interface MapFrameStats {
     culled: number;
     batches: number;
   };
+  /** GL only: what the frame cost on the GPU's side of the thread. */
+  gl?: MapGlFrameStats;
+}
+
+/** What a GL frame cost, beyond what both renderers report. */
+export interface MapGlFrameStats {
+  /** Milliseconds since the frame before — what a frame rate is made of. */
+  interval: number;
+  /** Milliseconds this thread spent issuing the frame's GL calls. */
+  cpuMs: number;
+  /** …building tiles' geometry, when the builds are on this thread. */
+  buildMs: number;
+  /** Tiles loaded and waiting for a build, and tiles still loading. */
+  building: number;
+  loading: number;
+  /** Bytes of tile geometry on the GPU. */
+  gpuBytes: number;
+  /** Segment instances drawn, every pass counted — the frame's work. */
+  instances: number;
+  drawCalls: number;
+  /** Tiles uploaded to the GPU this frame, and their bytes. */
+  uploads: number;
+  uploadBytes: number;
+  /** Whether the frame was drawn through an offscreen framebuffer — which
+   *  a surface with no stencil buffer of its own needs. */
+  offscreen: boolean;
+  /** The pyramid level the view is drawn from, and the one fully shown:
+   *  they differ while a level fades in (`levelFade`). */
+  level: number;
+  shownLevel: number;
+  /** How much of the arriving level was faded in; `0` with no fade. */
+  fade: number;
+  /** The adaptive-quality rung the frame was drawn at: `0` is everything,
+   *  higher leaves more out (`adaptive`). */
+  quality: number;
+  /** What adaptive quality predicted a moving frame would cost, in ms, or
+   *  `0` for a frame it did not price. */
+  predictedMs: number;
+  /** A settled frame's own time, drained and finished — what the cost
+   *  model learns from — or `0`. Moving frames are never timed. */
+  measuredMs: number;
+  /** Whether the camera moved within the settle window. */
+  moving: boolean;
+  /** Label anchors considered, and labels placed, this frame. */
+  labelCandidates: number;
+  labelsPlaced: number;
+  /** Milliseconds this thread spent on labels: placing them, and measuring
+   *  strings it had not measured before. */
+  labelMs: number;
+  /** Label text still waiting to be rasterized. */
+  textPending: boolean;
 }
 
 /** Options for framing a box. */
@@ -140,6 +239,11 @@ export interface MapViewProps {
    * Where tiles come from, drawn in order — a basemap, then an overlay
    * pyramid over it. Empty draws the style's background and nothing else,
    * which is what a map with only markers on it wants.
+   *
+   * Tiles are cached per source **object**, whatever its `id`: switching
+   * to another source shows only its tiles, and switching back finds the
+   * first one's still cached. So keep each source stable across renders —
+   * one made anew every render fetches every tile again every render.
    */
   sources?: readonly MapSource[];
   /** How to draw them. Defaults to {@link shortbreadStyle} in the theme's
@@ -187,11 +291,15 @@ export interface MapViewProps {
    * road casings, then roads, across a dozen frames — which is honest about
    * what the renderer is doing and does not look like a map.
    *
-   * The one thing the default costs is a transition that invalidates every
-   * surface at once: a `mapStyle` change, `refresh()`, or a display-scale
-   * change leaves no finished tile *and* no finished ancestor, so the map
-   * drops to its background colour until the new tiles land. `true` shows
-   * it repainting instead.
+   * The difference is widest at a `mapStyle` change or `refresh()`, which
+   * redraws every tile at once. By default the previous style stays on
+   * screen whole — tiles, background and labels — while the new one is
+   * drawn behind it, and the view swaps in one frame once every tile in it
+   * that has data is redrawn; a tile still loading does not hold the swap.
+   * If the view keeps moving meanwhile, the wait is bounded, and a tile not
+   * redrawn by then shows the background until it is. `true` shows the
+   * repaint instead: the new background and labels at once, and each tile
+   * as it is redrawn.
    */
   progressive?: boolean;
   /**
@@ -249,12 +357,96 @@ export interface MapViewProps {
   ref?: Ref<unknown>;
 }
 
+/**
+ * What only the GL renderer reads. Accepted by the retained renderer and
+ * ignored there, as the retained renderer's own — `progressive`,
+ * `rasterBudgetMs`, `rasterScale`, `surfaceBudget`, `batchVertices` — are
+ * ignored by GL: switching renderer is never a type error or a rewrite.
+ */
+export interface MapGlProps {
+  /**
+   * Cross-fade between pyramid levels over this many milliseconds, instead
+   * of switching to the new level's geometry in one frame. `0` (the
+   * default) switches. While a level fades in the frame is drawn twice —
+   * the level leaving, and the level arriving over it.
+   */
+  levelFade?: number;
+  /**
+   * Trade detail for frame rate while the camera moves. **On by default**,
+   * holding each moving frame to 12 ms; `{ budgetMs }` picks another budget
+   * and `false` turns it off. When the camera settles the next frame draws
+   * everything again.
+   *
+   * It is on by default because the alternative is a renderer that can take
+   * the whole thread: unbudgeted, a fly across ten zoom levels left the
+   * event loop unable to run a `setTimeout` for a second at a time, with
+   * nothing individually slow inside it. An app embedding a map should not
+   * have to know that to keep its own clock running.
+   */
+  adaptive?: boolean | { budgetMs?: number };
+  /**
+   * Place labels in every frame while the camera moves, and set a new
+   * name's text in the frame it is placed in, so the names always match
+   * the zoom on screen. Off by default: new names then wait until the zoom
+   * has been still for 120 ms, and arrive a readback later.
+   *
+   * What it costs: a zoom crosses several label sets, so names arrive and
+   * leave at every step of it (each fading, over 220 ms), and each new name
+   * is set on this thread in the frame that needs it — up to 8 ms a frame,
+   * the rest the frame after. Needs a text engine that sets a string
+   * synchronously (react-x11 2.21's layout coverage); on one that cannot,
+   * names still arrive a readback later, but are placed every frame.
+   */
+  labelsWhileMoving?: boolean;
+  /** Build tiles' geometry on this many worker threads, so no frame pays
+   *  for a tile arriving. `0` (the default) builds on this thread, a few
+   *  milliseconds a frame. */
+  buildWorkers?: number;
+  /** Antialias polygon edges with a half-pixel line. `true` by default; the
+   *  surfaces have no multisampling, so without it an edge is a staircase. */
+  antialias?: boolean;
+  /** `'nonzero'` (the default, and the retained renderer's rule) or
+   *  `'evenodd'`, one stencil pass cheaper and wrong wherever two features
+   *  of one layer overlap. */
+  fillRule?: 'nonzero' | 'evenodd';
+  /**
+   * Raw GL after the map has drawn and before the swap, with the frame's
+   * framebuffer bound. What a test or a screenshot reads a frame back
+   * through: a capture of the window from outside does not see a GL surface
+   * on either backend.
+   */
+  onAfterDraw?: (gl: unknown, info: { width: number; height: number }) => void;
+}
+
 /** What `<Map>` takes. */
-export interface MapProps extends Omit<MapViewProps, 'ref'> {
+export interface MapProps extends Omit<MapViewProps, 'ref'>, MapGlProps {
   ref?: Ref<MapHandle>;
+  /**
+   * Which renderer draws the map: `'retained'` composites rasterized tile
+   * pictures and runs anywhere; `'gl'` draws every frame from the vector
+   * data on the GPU, and needs direct GL; `'auto'`, the default, takes GL
+   * where the connection has it and the retained renderer everywhere else.
+   * `REACT_X11_MAP_RENDERER` overrides it for every map. See the docs page's
+   * "Renderers".
+   */
+  renderer?: MapRendererRequest;
+  /** The map is drawn with a renderer other than the one it asked for, or
+   *  changed renderer: `'auto'` finding no direct GL, or GL failing at run
+   *  time. The camera and the handle carry over. */
+  onRendererChange?: (renderer: MapRenderer, reason: MapRendererReason) => void;
+  /**
+   * GL failed, on a map that asked for it by name (`renderer="gl"`). Such a
+   * map never falls back — an application that asked for GL wants to know it
+   * did not get it — so this is where it finds out; under `'auto'` a failure
+   * moves the map to the retained renderer and says so through
+   * `onRendererChange` instead.
+   */
+  onError?: (error: Error) => void;
   /** Anything absolutely positioned over the map — a legend, a control
-   *  panel. Laid out as siblings of the drawn pane rather than inside it,
-   *  because a registered element paints its children *before* its own
-   *  drawing and anything inside would be painted over. */
+   *  panel. On the retained renderer they are siblings of the drawn pane
+   *  rather than inside it, because a registered element paints its
+   *  children *before* its own drawing and anything inside would be painted
+   *  over; on GL they go inside the surface, whose children core draws
+   *  above it — opaquely on X11, so give a legend a background of its own. */
   children?: ReactNode;
 }

package/src/markdown/expressions.ts

@@ -15,7 +15,11 @@
 // in as few words as they can: do not pass `scope` alongside a document you
 // did not write.
 
-import type { BlockNode, Document, InlineNode } from './ast.js';
+import type {
+  BlockNode,
+  Document,
+  InlineNode,
+} from '../internal/markdown/ast.js';
 
 /** A compiled expression, or null if it would not compile at all. */
 type Compiled = ((...args: unknown[]) => unknown) | null;