769 lines
31 KiB
TypeScript
769 lines
31 KiB
TypeScript
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
// Copyright (C) 2026 ZiroEDA and contributors.
|
|
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
|
|
/**
|
|
* `GAL::DrawGrid` + `GAL::blitCursor` — the one grid and crosshair every editor
|
|
* frame shares.
|
|
*
|
|
* Upstream both live on the GAL, which is constructed once by
|
|
* `EDA_DRAW_PANEL_GAL` (`common/draw_panel_gal.cpp:170`) and is therefore the
|
|
* same code in eeschema, pcbnew, the symbol and footprint editors, gerbview and
|
|
* pl_editor. `EDA_DRAW_PANEL_GAL::onPaint` calls `m_gal->DrawGrid()` for every
|
|
* frame in the suite (`draw_panel_gal.cpp:386`), styled from
|
|
* `GAL_DISPLAY_OPTIONS` (grid style / line width / min spacing / axes) and
|
|
* `WINDOW_SETTINGS::cursor` (crosshair mode, always-show).
|
|
*
|
|
* We had four separate implementations
|
|
* (`schematic/render/renderer.ts`, `pcb/renderBoard.ts`, and inline passes in
|
|
* `DrawingSheetCanvas.tsx` and `GerberCanvas.tsx`) plus a fifth hardcoded one in
|
|
* `symbol/render/symbolRenderer.ts` that no toggle could turn off, and the
|
|
* footprint editor drew no grid at all while its toolbar button rendered
|
|
* pressed. Only the schematic copy implemented all three grid styles; the other
|
|
* four assumed DOTS and ignored the setting.
|
|
*
|
|
* Everything here is framework-free so `qa`'s tsc (which has no `--jsx`) can
|
|
* typecheck it, and the geometry decisions are pure functions so they can be
|
|
* asserted without a canvas.
|
|
*
|
|
* Colour is deliberately NOT owned here. Upstream each frame answers
|
|
* `GetGridColor()` / `GetCursorColor()` out of its own `COLOR_SETTINGS` layer —
|
|
* `LAYER_SCHEMATIC_GRID` in eeschema (`sch_render_settings.h:70`), `LAYER_GRID`
|
|
* in pcbnew and the footprint editor (`pcb_painter.h:133`,
|
|
* `footprint_editor_utils.cpp:269`), `LAYER_GERBVIEW_GRID` in gerbview
|
|
* (`gerbview_frame.cpp:1042`) and a background-luma choice in pl_editor
|
|
* (`ds_painter.h:71`) — so a per-editor colour is parity, not drift. The caller
|
|
* passes the colour its own theme resolved.
|
|
*/
|
|
import { parseColor4d, toCss, withAlpha } from './index.js';
|
|
|
|
/** `KIGFX::GRID_STYLE` (include/gal/gal_display_options.h:46-51). */
|
|
export type GridStyle = 'dots' | 'lines' | 'crosses';
|
|
|
|
/** `KIGFX::CROSS_HAIR_MODE` (gal_display_options.h:68-73). */
|
|
export type CrosshairMode = 'small' | 'full' | '45';
|
|
|
|
/**
|
|
* The three radio buttons `PANEL_GAL_OPTIONS` offers for that enum, in its
|
|
* order, with its labels verbatim
|
|
* (common/dialogs/panel_gal_options_base.cpp:102-108, read back off the
|
|
* running Preferences dialog).
|
|
*
|
|
* Here rather than in a panel because the panel is shared upstream: one
|
|
* `PANEL_GAL_OPTIONS` is embedded by eeschema, pcbnew, the symbol and footprint
|
|
* editors, gerbview and pl_editor, so the labels have exactly one home. Note
|
|
* the third: "45 degree crosshairs", spelled out — not a degree sign, and not
|
|
* "full window".
|
|
*/
|
|
export const CROSSHAIR_MODE_CHOICES: readonly (readonly [CrosshairMode, string])[] = [
|
|
['small', 'Small crosshairs'],
|
|
['full', 'Full window crosshairs'],
|
|
['45', '45 degree crosshairs'],
|
|
];
|
|
|
|
/**
|
|
* `m_checkBoxCursorFullscreen`'s neighbour, the separate checkbox
|
|
* (panel_gal_options_base.cpp:114). It is NOT part of the shape radio, and
|
|
* running the two together into one checkbox — as the Drawing Sheet Editor's
|
|
* Preferences once did — makes the 45-degree mode unreachable.
|
|
*/
|
|
export const ALWAYS_SHOW_CROSSHAIRS_LABEL = 'Always show crosshairs';
|
|
|
|
/**
|
|
* `GAL::SetCoarseGrid( 10 )` from the GAL constructor
|
|
* (`graphics_abstraction_layer.cpp:76`): every tenth line/dot/cross is drawn at
|
|
* double width, and it is also the factor the spacing steps up by when the grid
|
|
* gets too dense — a grid jumps 50 mil -> 500 mil, it does not double.
|
|
*/
|
|
export const GRID_TICK = 10;
|
|
|
|
/**
|
|
* `GAL::GetVisibleGridSize` floors the grid size at 100 IU before anything else
|
|
* (`graphics_abstraction_layer.h:879-881`).
|
|
*/
|
|
export const MIN_GRID_IU = 100;
|
|
|
|
/**
|
|
* `blitCursor`'s `const int cursorSize = 80` (`cairo_gal.cpp:1231`,
|
|
* `opengl_gal.cpp:2841`): the small crosshair is 80 screen px across at any
|
|
* zoom, so each arm is 40 px.
|
|
*
|
|
* "Screen" here is GAL's `m_screenSize`, which `EDA_DRAW_PANEL_GAL::onSize`
|
|
* fills from `GetClientSize()` — *logical* pixels, not native ones
|
|
* (`draw_panel_gal.cpp:459`; `OPENGL_GAL::ResizeScreen` multiplies by the scale
|
|
* factor only for the framebuffer, `opengl_gal.cpp:2050-2059`). So on a
|
|
* device-pixel canvas the arms are 40 * devicePixelRatio device px.
|
|
*/
|
|
export const SMALL_CROSS_PX = 80;
|
|
|
|
/**
|
|
* The appearance half of `GAL_DISPLAY_OPTIONS`, with KiCad's own defaults
|
|
* (`common/gal/gal_display_options.cpp:49-56`, and the `.grid.*` params in
|
|
* `common/settings/app_settings.cpp:549-562`, which agree).
|
|
*/
|
|
export interface GridAppearance {
|
|
/** `m_gridStyle`. Every app defaults to DOTS (`grid.style` default 0). */
|
|
style: GridStyle;
|
|
/** `m_gridLineWidth`, in logical px. */
|
|
lineWidthPx: number;
|
|
/** `m_gridMinSpacing`, the minimum on-screen node spacing in logical px. */
|
|
minSpacingPx: number;
|
|
}
|
|
|
|
export const DEFAULT_GRID_APPEARANCE: GridAppearance = {
|
|
style: 'dots',
|
|
lineWidthPx: 1,
|
|
minSpacingPx: 10,
|
|
};
|
|
|
|
/**
|
|
* `KIGFX::GRID_SNAPPING` — `m_gridSnapping`, the other half of
|
|
* `GAL_DISPLAY_OPTIONS` the "Snap to grid" choice writes. Stored as the
|
|
* `wxChoice` selection upstream stores: 0 ALWAYS, 1 WITH_GRID, 2 NEVER.
|
|
*/
|
|
export type GridSnapping = 0 | 1 | 2;
|
|
|
|
/**
|
|
* `KIGFX::GAL::GetGridSnapping()`
|
|
* (`include/gal/graphics_abstraction_layer.h:815-819`):
|
|
*
|
|
* return m_options.m_gridSnapping == GRID_SNAPPING::ALWAYS
|
|
* || ( m_gridVisibility && m_options.m_gridSnapping == GRID_SNAPPING::WITH_GRID );
|
|
*
|
|
* — one method on the GAL, which is why it is one function here and not one per
|
|
* editor. Every canvas asks it with its OWN app's `window.grid.snap` and its
|
|
* OWN grid visibility; the two arguments are what keep one editor's answer out
|
|
* of another's.
|
|
*
|
|
* It is also why the middle option reads "When grid shown" and not "When a grid
|
|
* is set": the term is `m_gridVisibility`, i.e. `ACTIONS::toggleGrid`, and has
|
|
* nothing to do with the grid LIST.
|
|
*
|
|
* `GRID_SNAPPING::NEVER` falls out of both arms and needs no branch.
|
|
*
|
|
* @param snapping `window.grid.snap` from the calling app's settings.
|
|
* @param gridVisible `m_gridVisibility` — the live Show Grid state, not the
|
|
* stored one, because that is the term upstream reads.
|
|
*/
|
|
export function gridSnappingEnabled(snapping: GridSnapping, gridVisible: boolean): boolean {
|
|
return snapping === 0 || (gridVisible && snapping === 1);
|
|
}
|
|
|
|
/**
|
|
* A canvas' world -> device-pixel transform.
|
|
*
|
|
* `scale` is always positive (device px per world IU); a mirrored axis is a
|
|
* flag rather than a negative scale so the lattice maths never has to reason
|
|
* about a sign. pcbnew's flip-board view mirrors X (`SetMirror` on X) and
|
|
* gerbview's canvas is Y-up, so both flags are real.
|
|
*/
|
|
export interface GridView {
|
|
scale: number;
|
|
tx: number;
|
|
ty: number;
|
|
flipX?: boolean;
|
|
flipY?: boolean;
|
|
}
|
|
|
|
/**
|
|
* The same transform spelled `{ scale, offsetX, offsetY }`, which is how the
|
|
* eeschema and symbol-editor canvases carry theirs.
|
|
*/
|
|
export function viewFromOffsets(v: { scale: number; offsetX: number; offsetY: number }): GridView {
|
|
return { scale: v.scale, tx: v.offsetX, ty: v.offsetY };
|
|
}
|
|
|
|
/** Device x for a world x under `view`. */
|
|
export function worldToDeviceX(view: GridView, x: number): number {
|
|
return x * (view.flipX ? -view.scale : view.scale) + view.tx;
|
|
}
|
|
|
|
/** Device y for a world y under `view`. */
|
|
export function worldToDeviceY(view: GridView, y: number): number {
|
|
return y * (view.flipY ? -view.scale : view.scale) + view.ty;
|
|
}
|
|
|
|
/** World x for a device x under `view`. */
|
|
export function deviceToWorldX(view: GridView, px: number): number {
|
|
return (px - view.tx) / (view.flipX ? -view.scale : view.scale);
|
|
}
|
|
|
|
/** World y for a device y under `view`. */
|
|
export function deviceToWorldY(view: GridView, py: number): number {
|
|
return (py - view.ty) / (view.flipY ? -view.scale : view.scale);
|
|
}
|
|
|
|
/**
|
|
* `GAL::GetVisibleGridSize` (`graphics_abstraction_layer.h:875-896`), which is
|
|
* also the loop `DrawGrid` runs inline (`cairo_gal.cpp:1785-1795`).
|
|
*
|
|
* `worldScale` is device px per world IU and `dpr` is GAL's `m_scaleFactor`:
|
|
* the threshold is a *screen pixel* distance, so it converts through the same
|
|
* scale factor GAL applies to every pixel-valued display option.
|
|
*
|
|
* SMALL_CROSS needs twice the room because a cross is wider than a dot.
|
|
*/
|
|
export function visibleGridStep(
|
|
sizeIU: number,
|
|
worldScale: number,
|
|
style: GridStyle,
|
|
minSpacingPx: number,
|
|
dpr = 1,
|
|
): number {
|
|
let step = Math.max(MIN_GRID_IU, sizeIU);
|
|
if (!(worldScale > 0)) return step;
|
|
// KiROUND( computeMinGridSpacing() / m_worldScale ) — the rounding is
|
|
// upstream's and matters at very high zoom, where the threshold in IU is a
|
|
// fraction of one unit and rounds to zero.
|
|
let threshold = Math.round((Math.max(0, minSpacingPx) * dpr) / worldScale);
|
|
if (style === 'crosses') threshold *= 2;
|
|
while (step <= threshold) step *= GRID_TICK;
|
|
return step;
|
|
}
|
|
|
|
/**
|
|
* `DrawGrid`'s node index range for one axis (`cairo_gal.cpp:1798-1813`):
|
|
* `KiROUND( ( world - origin ) / step )` at each end, normalised so start < end,
|
|
* then one node of margin on each side so the lattice always fills the screen.
|
|
*/
|
|
export function gridIndexRange(
|
|
worldA: number,
|
|
worldB: number,
|
|
origin: number,
|
|
step: number,
|
|
): { start: number; end: number } {
|
|
let start = Math.round((worldA - origin) / step);
|
|
let end = Math.round((worldB - origin) / step);
|
|
if (start > end) [start, end] = [end, start];
|
|
return { start: start - 1, end: end + 1 };
|
|
}
|
|
|
|
/**
|
|
* `OPENGL_GAL::DrawGrid`'s `minorLineWidth` / `majorLineWidth` in device pixels
|
|
* (`opengl_gal.cpp:1911-1912`):
|
|
*
|
|
* float minorLineWidth = std::fmax( 1.0f, m_gridLineWidth )
|
|
* * getWorldPixelSize() / GetScaleFactor();
|
|
* float majorLineWidth = minorLineWidth * 2.0f;
|
|
*
|
|
* with the stored width GAL derives from the setting:
|
|
* `m_gridLineWidth = m_scaleFactor * options.m_gridLineWidth + 0.25`
|
|
* (`graphics_abstraction_layer.cpp:124`). The `+ 0.25` is real: a default
|
|
* `grid.line_width` of 1.0 (`app_settings.cpp:549-550`) gives 1.25, not 1.
|
|
*
|
|
* This is the LINES pen and the DOTS mark both. Upstream they are one number
|
|
* in OpenGL, because a DOTS grid there is not drawn as dots at all: the whole
|
|
* lattice of rows is stroked invisibly into the stencil buffer and the columns
|
|
* are then stroked through it, so every visible mark is the intersection of
|
|
* two lines of exactly these widths (`opengl_gal.cpp:1959-2040`).
|
|
*
|
|
* CAIRO_GAL_BASE::DrawGrid arrives at the same two numbers a different way and
|
|
* clamps in a different order — `drawGridPoint( pos, tickX ? m_gridLineWidth *
|
|
* 2.0f : m_gridLineWidth, ... )` with `std::max( 1.0, aWidth )` applied AFTER
|
|
* the doubling (`cairo_gal.cpp:1868-1871, 1115-1116`), so a 0.5 px setting
|
|
* gives Cairo a 1.5 px tick where OpenGL gives 2. OpenGL is KiCad's default
|
|
* backend and is what a live pl_editor on this machine is running, so it is
|
|
* the one we follow.
|
|
*/
|
|
export function gridPenWidths(lineWidthPx: number, dpr = 1): { minor: number; major: number } {
|
|
const stored = dpr * Math.max(0, lineWidthPx) + 0.25;
|
|
const minor = Math.max(1, stored);
|
|
return { minor, major: minor * 2 };
|
|
}
|
|
|
|
/**
|
|
* Where a dot's rectangle starts, and how many whole device pixels it lights —
|
|
* the two halves of one rule.
|
|
*
|
|
* A grid mark is not painted as a fractional-width rectangle. Upstream it is a
|
|
* pair of stencilled line quads, and the rasteriser lights a pixel when the
|
|
* pixel's CENTRE falls inside the quad. Centres sit at half-integers, so a
|
|
* mark of width `w` centred on pixel `c` lights the pixels `c + k` for every
|
|
* integer `k` in `[-w/2, w/2)` — the half-open interval is the usual
|
|
* lower-edge-inclusive fill rule. That is
|
|
*
|
|
* leftmost = c - floor( w / 2 ) (`gridDotEdge`)
|
|
* count = floor( w / 2 ) + ceil( w / 2 ) (`gridDotSize`)
|
|
*
|
|
* and `c` itself is the snap `CAIRO_GAL_BASE::drawGridPoint` writes out —
|
|
* `roundp( x )` is `floor( x + 0.5 ) + 0.5` for an odd pen
|
|
* (`cairo_gal.cpp:186-188, 1113`), so the centre is `floor( x + 0.5 )`.
|
|
*
|
|
* **Measured**, not derived, on this machine against the installed KiCad
|
|
* 10.0.5: a live pl_editor at its default `grid.line_width` of 1.0 was
|
|
* captured and the canvas held exactly two colours — background and
|
|
* `rgb(194,194,194)` — with no anti-aliased pixel anywhere, so every mark is a
|
|
* whole number of pixels. A minor mark is **1 px**; a mark on a tick column is
|
|
* **3 px wide** and one on a tick row **3 px tall**; a tick crossing is 3x3.
|
|
* The tick columns were 955 px apart against a 95.5 px node pitch, which is
|
|
* `m_gridTick` = 10 (`SetCoarseGrid( 10 )`, graphics_abstraction_layer.cpp:76).
|
|
*
|
|
* The rule above reproduces both numbers from the widths the C++ computes:
|
|
* 1.25 lights one pixel (only `k = 0` is within 0.625) and 2.5 lights three
|
|
* (`k = -1, 0, 1` are all within 1.25). Ours filled a literal 1.25 x 1.25 and
|
|
* 2.5 x 2.5 rectangle instead, which the canvas anti-aliased into one solid
|
|
* pixel with a 25% bleed to the right and below, and two solid pixels with a
|
|
* 50% bleed — visibly softer than KiCad's hard marks.
|
|
*/
|
|
export function gridDotEdge(device: number, width: number): number {
|
|
return Math.floor(device + 0.5) - Math.floor(width / 2);
|
|
}
|
|
|
|
/** The other half of {@link gridDotEdge}: whole device pixels lit. */
|
|
export function gridDotSize(width: number): number {
|
|
return Math.floor(width / 2) + Math.ceil(width / 2);
|
|
}
|
|
|
|
/**
|
|
* Which line of the retained lattice sits ON an axis, and so must not be drawn.
|
|
*
|
|
* `OPENGL_GAL::DrawGrid` tests it per line, on the world coordinate rather than
|
|
* on the index (`common/gal/opengl/opengl_gal.cpp:2000-2004` for the rows and
|
|
* `:2027-2031` for the columns):
|
|
*
|
|
* const double y = j * gridScreenSize.y + m_gridOrigin.y;
|
|
*
|
|
* // If axes are drawn, skip the lines that would cover them
|
|
* if( m_axesEnabled && y == 0.0 )
|
|
* continue;
|
|
*
|
|
* The axes are painted BEFORE the grid (`:1919-1928`), so without the skip the
|
|
* grid line would overpaint the axis it lies under. `CAIRO_GAL_BASE::DrawGrid`
|
|
* carries the identical two tests (`common/gal/cairo/cairo_gal.cpp:1825-1827`,
|
|
* `:1839-1841`), so for LINES the two backends agree and the rule does not
|
|
* depend on which one is running.
|
|
*
|
|
* Our lattice is retained anchor-relative and translated, so the *local* index
|
|
* of that line moves as the view pans; this converts. `anchor` is the global
|
|
* node index the path's origin sits on and `dir` is +1, or -1 on a mirrored
|
|
* axis, matching the walk in {@link drawGrid}. Returns null when no line can
|
|
* land on the axis at all — which is every case where `origin` is not a whole
|
|
* number of steps from zero, exactly as the `== 0.0` test decides upstream.
|
|
*/
|
|
export function axisLineIndex(
|
|
anchor: number,
|
|
dir: number,
|
|
step: number,
|
|
origin: number,
|
|
): number | null {
|
|
if (!(step > 0)) return null;
|
|
const j = Math.round(-origin / step);
|
|
// Upstream's test, evaluated for the only index that can satisfy it. Written
|
|
// as the same product-and-sum so a grid origin that is a hair off a step
|
|
// fails here for the same floating-point reason it fails in the C++.
|
|
if (j * step + origin !== 0) return null;
|
|
return (j - anchor) * dir;
|
|
}
|
|
|
|
/** A line segment in device pixels. */
|
|
export interface Segment {
|
|
x1: number;
|
|
y1: number;
|
|
x2: number;
|
|
y2: number;
|
|
}
|
|
|
|
/**
|
|
* `CAIRO_GAL_BASE::blitCursor` (`cairo_gal.cpp:1204-1235`), as device-pixel
|
|
* segments. The OpenGL backend draws the identical shapes in world space
|
|
* (`opengl_gal.cpp:2824-2905`); expressing them in screen space is what makes
|
|
* the small cross 80 px at every zoom, which is what upstream means.
|
|
*/
|
|
export function crosshairSegments(
|
|
mode: CrosshairMode,
|
|
cursor: { x: number; y: number },
|
|
widthPx: number,
|
|
heightPx: number,
|
|
/** GAL's `m_scaleFactor`: `cursorSize` is 80 *logical* px. */
|
|
dpr = 1,
|
|
): Segment[] {
|
|
const { x, y } = cursor;
|
|
if (mode === 'full') {
|
|
return [
|
|
{ x1: 0, y1: y, x2: widthPx, y2: y },
|
|
{ x1: x, y1: 0, x2: x, y2: heightPx },
|
|
];
|
|
}
|
|
if (mode === '45') {
|
|
// "Oversized but that's ok" — cairo_gal.cpp:1222.
|
|
const d = widthPx + heightPx;
|
|
return [
|
|
{ x1: x - d, y1: y - d, x2: x + d, y2: y + d },
|
|
{ x1: x - d, y1: y + d, x2: x + d, y2: y - d },
|
|
];
|
|
}
|
|
const half = (SMALL_CROSS_PX / 2) * (dpr > 0 ? dpr : 1);
|
|
return [
|
|
{ x1: x - half, y1: y, x2: x + half, y2: y },
|
|
{ x1: x, y1: y - half, x2: x, y2: y + half },
|
|
];
|
|
}
|
|
|
|
/**
|
|
* `GAL::IsCursorEnabled()` (`graphics_abstraction_layer.h:1003-1006`) folded
|
|
* together with `GAL::getCursorColor()` (`graphics_abstraction_layer.cpp:
|
|
* 258-268`).
|
|
*
|
|
* `toolWantsCursor` is `m_isCursorEnabled`, which the active tool sets via
|
|
* `ShowCursor` — the drawing tools turn it on, the selection tool does not.
|
|
* `alwaysShow` is `m_forceDisplayCursor`, the "Always show crosshairs"
|
|
* preference. A cursor that is on only because it was forced is drawn at half
|
|
* alpha: upstream's own comment says that "helps to provide a hint for active
|
|
* tools".
|
|
*
|
|
* Returns the alpha multiplier, or null when no crosshair is drawn at all.
|
|
*/
|
|
export function cursorAlphaFactor(toolWantsCursor: boolean, alwaysShow: boolean): number | null {
|
|
if (!toolWantsCursor && !alwaysShow) return null;
|
|
return toolWantsCursor ? 1 : 0.5;
|
|
}
|
|
|
|
/** `getCursorColor()` applied to a CSS colour: multiply, do not overwrite, alpha. */
|
|
export function dimmedCursorColor(css: string, factor: number): string {
|
|
if (factor >= 1) return css;
|
|
const c = parseColor4d(css);
|
|
return toCss(withAlpha(c, c.a * factor));
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Painting
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/** Everything `DrawGrid` reads, for one canvas, for one frame. */
|
|
export interface GridOptions {
|
|
/** `WINDOW_SETTINGS::grid.show` / `GAL::SetGridVisibility`. */
|
|
show?: boolean;
|
|
/** `GAL::m_gridSize`, in the canvas' world units. */
|
|
sizeIU: number;
|
|
/** `GAL::m_gridOrigin` (pcbnew's board grid origin; zero elsewhere). */
|
|
origin?: { x: number; y: number };
|
|
/** The frame's `GetGridColor()`. */
|
|
color: string;
|
|
/** `GAL_DISPLAY_OPTIONS::m_gridStyle`. */
|
|
style?: GridStyle;
|
|
/** `m_gridLineWidth`, logical px. */
|
|
lineWidthPx?: number;
|
|
/** `m_gridMinSpacing`, logical px. */
|
|
minSpacingPx?: number;
|
|
/** GAL's `m_scaleFactor`. */
|
|
devicePixelRatio?: number;
|
|
/** `m_axesEnabled` + `m_axesColor`; null/omitted = axes off (KiCad's default). */
|
|
axes?: { color: string } | null;
|
|
}
|
|
|
|
/**
|
|
* Guard against a pathological view (a not-yet-sized canvas, or a scale of a
|
|
* few nanometres per pixel) asking for millions of nodes. No upstream
|
|
* counterpart: GAL cannot hit this because `GetVisibleGridSize` is driven by a
|
|
* real window size.
|
|
*/
|
|
const MAX_GRID_NODES = 1_000_000;
|
|
|
|
interface GridGeometry {
|
|
key: string;
|
|
/** Minor nodes/lines, and the coarse (every GRID_TICK-th) ones. */
|
|
minor: Path2D;
|
|
major: Path2D;
|
|
}
|
|
|
|
/**
|
|
* Retained lattice geometry, per canvas context.
|
|
*
|
|
* The lattice is built once into `Path2D` form in device space and afterwards
|
|
* only translated, so the grid costs one fill (dots) or two strokes
|
|
* (lines/crosses) per frame instead of a draw call per node — the same reason
|
|
* `OPENGL_GAL::DrawGrid` submits the whole grid through the non-cached vertex
|
|
* manager in one go. Keyed on the context rather than module-global because six
|
|
* canvases share this module and two of them can be mounted at once.
|
|
*/
|
|
const geomCache = new WeakMap<CanvasRenderingContext2D, GridGeometry>();
|
|
|
|
/** Non-negative remainder, for indices that go negative left of the origin. */
|
|
function mod(a: number, n: number): number {
|
|
return ((a % n) + n) % n;
|
|
}
|
|
|
|
/**
|
|
* `GAL::DrawGrid` (`common/gal/cairo/cairo_gal.cpp:1756-1876`), painted in
|
|
* device space on the live canvas — GAL draws it to `TARGET_NONCACHED` at
|
|
* `m_depthRange.y * 0.75`, i.e. behind every layer but re-rasterised every
|
|
* frame, which is exactly what an untransformed pass before the scene blit is.
|
|
*
|
|
* The caller's transform is saved and restored.
|
|
*/
|
|
export function drawGrid(
|
|
ctx: CanvasRenderingContext2D,
|
|
view: GridView,
|
|
widthPx: number,
|
|
heightPx: number,
|
|
opts: GridOptions,
|
|
): void {
|
|
const dpr = opts.devicePixelRatio && opts.devicePixelRatio > 0 ? opts.devicePixelRatio : 1;
|
|
const style = opts.style ?? DEFAULT_GRID_APPEARANCE.style;
|
|
const lineWidthPx = opts.lineWidthPx ?? DEFAULT_GRID_APPEARANCE.lineWidthPx;
|
|
const minSpacingPx = opts.minSpacingPx ?? DEFAULT_GRID_APPEARANCE.minSpacingPx;
|
|
const ox = opts.origin?.x ?? 0;
|
|
const oy = opts.origin?.y ?? 0;
|
|
|
|
ctx.save();
|
|
ctx.setTransform(1, 0, 0, 1, 0, 0);
|
|
|
|
// "Draw axes if desired" runs before the grid-visibility test upstream
|
|
// (cairo_gal.cpp:1773-1781, opengl_gal.cpp:1919-1928), so the axes survive
|
|
// Show Grid being off. Because they go down FIRST, the lattice would cover
|
|
// them; `axisLineIndex` below is how upstream stops it.
|
|
//
|
|
// The settings flag `grid.axes_enabled` defaults FALSE in every app
|
|
// (`common/settings/app_settings.cpp:459-460`), but GerbView does not go
|
|
// through it: GERBVIEW_FRAME's constructor sets the GAL option directly,
|
|
// "Enable the axes to match legacy draw style"
|
|
// (`gerbview/gerbview_frame.cpp:188-191`), so the Gerber Viewer is the one
|
|
// editor that draws them.
|
|
if (opts.axes) {
|
|
const axisX = worldToDeviceX(view, 0);
|
|
const axisY = worldToDeviceY(view, 0);
|
|
ctx.strokeStyle = opts.axes.color;
|
|
ctx.lineWidth = gridPenWidths(lineWidthPx, dpr).minor;
|
|
ctx.setLineDash([]);
|
|
ctx.beginPath();
|
|
ctx.moveTo(0, axisY);
|
|
ctx.lineTo(widthPx, axisY);
|
|
ctx.moveTo(axisX, 0);
|
|
ctx.lineTo(axisX, heightPx);
|
|
ctx.stroke();
|
|
}
|
|
|
|
// "if( !m_gridVisibility || m_gridSize.x == 0 || m_gridSize.y == 0 ) return"
|
|
if (opts.show === false || !(opts.sizeIU > 0) || !(view.scale > 0)) {
|
|
ctx.restore();
|
|
return;
|
|
}
|
|
|
|
const step = visibleGridStep(opts.sizeIU, view.scale, style, minSpacingPx, dpr);
|
|
const pitch = step * view.scale; // node spacing, device px (always positive)
|
|
if (!(pitch > 0)) {
|
|
ctx.restore();
|
|
return;
|
|
}
|
|
|
|
const xr = gridIndexRange(deviceToWorldX(view, 0), deviceToWorldX(view, widthPx), ox, step);
|
|
const yr = gridIndexRange(deviceToWorldY(view, 0), deviceToWorldY(view, heightPx), oy, step);
|
|
|
|
const nx = xr.end - xr.start;
|
|
const ny = yr.end - yr.start;
|
|
if (!Number.isFinite(nx) || !Number.isFinite(ny) || (nx + 1) * (ny + 1) > MAX_GRID_NODES) {
|
|
ctx.restore();
|
|
return;
|
|
}
|
|
|
|
// Walk the lattice in the +device direction: on a mirrored axis that is the
|
|
// *decreasing* index direction. Coarseness has period GRID_TICK and is
|
|
// symmetric about a tick, so counting steps from a tick-aligned anchor gives
|
|
// the same coarse pattern either way, and the retained path then only has to
|
|
// be translated as the view pans.
|
|
const dirX = view.flipX ? -1 : 1;
|
|
const dirY = view.flipY ? -1 : 1;
|
|
const i0 = view.flipX ? xr.end : xr.start;
|
|
const j0 = view.flipY ? yr.end : yr.start;
|
|
// Nearest tick-aligned index at or before i0 in the walking direction.
|
|
const iA = i0 - dirX * mod(dirX * i0, GRID_TICK);
|
|
const jA = j0 - dirY * mod(dirY * j0, GRID_TICK);
|
|
const cols = nx + GRID_TICK;
|
|
const rows = ny + GRID_TICK;
|
|
|
|
const { minor: minorW, major: majorW } = gridPenWidths(lineWidthPx, dpr);
|
|
|
|
/**
|
|
* The lattice line that lies on each axis, as a local index into the
|
|
* retained path — see {@link axisLineIndex}.
|
|
*
|
|
* SMALL_CROSS is deliberately excluded. Upstream's skip lives only in the
|
|
* line branch; the cross branch (`opengl_gal.cpp:1973-1993`) has no such
|
|
* test, so the cross at the origin paints over the axes. **Measured** on
|
|
* this machine against the installed KiCad 10.0.5, with GerbView — the one
|
|
* frame that turns the axes on without a preference
|
|
* (`gerbview/gerbview_frame.cpp:188-191`) — captured at each of the three
|
|
* styles (`qa/probes/grid_axis_skip/measure.py`). The axes there are the
|
|
* GAL's own `SetAxesColor( COLOR4D( BLUE ) )` and painted as rgb(0,0,132)
|
|
* against a rgb(132,132,132) grid, so which one survives is readable pixel
|
|
* by pixel:
|
|
*
|
|
* LINES the axis column is unbroken blue for the full canvas height,
|
|
* interrupted only where the OTHER axis' perpendicular grid lines
|
|
* cross it, and the crossing pixel itself is blue;
|
|
* DOTS the row and the column of dots on the axes are absent entirely
|
|
* — the dot columns ran ..., 817, 835, [853 skipped], 871, 889 at
|
|
* a 17.8 px pitch — which is CAIRO's behaviour ruled out, since
|
|
* its dots branch has no skip at all. OpenGL draws a dots grid as
|
|
* the stencil intersection of these same two line loops, so the
|
|
* skip removes the whole row and column;
|
|
* CROSSES the crossing pixel is rgb(132,132,132): the cross at the origin
|
|
* overpainted the axes.
|
|
*
|
|
* So the skip applies to LINES and DOTS and not to CROSSES, and the backend
|
|
* that is running is OpenGL.
|
|
*/
|
|
const axisCol = opts.axes && style !== 'crosses' ? axisLineIndex(iA, dirX, step, ox) : null;
|
|
const axisRow = opts.axes && style !== 'crosses' ? axisLineIndex(jA, dirY, step, oy) : null;
|
|
// Only an on-screen axis changes the geometry, so an axis panned out of view
|
|
// leaves the cache key alone rather than churning the retained path.
|
|
const skipCol = axisCol !== null && axisCol >= 0 && axisCol <= cols ? axisCol : null;
|
|
const skipRow = axisRow !== null && axisRow >= 0 && axisRow <= rows ? axisRow : null;
|
|
|
|
const key = `${style}|${pitch}|${cols}x${rows}|${widthPx}x${heightPx}|${minorW}|${skipCol},${skipRow}`;
|
|
let geom = geomCache.get(ctx);
|
|
if (!geom || geom.key !== key) {
|
|
const minorPath = new Path2D();
|
|
const majorPath = new Path2D();
|
|
const w = cols * pitch;
|
|
const h = rows * pitch;
|
|
|
|
if (style === 'lines') {
|
|
// "Now draw the grid, every coarse grid line gets the double width"
|
|
// (cairo_gal.cpp:1819-1846): a horizontal line is coarse on its own row
|
|
// index and a vertical one on its own column index.
|
|
for (let l = 0; l <= rows; l++) {
|
|
if (l === skipRow) continue;
|
|
const y = l * pitch;
|
|
const p = l % GRID_TICK === 0 ? majorPath : minorPath;
|
|
p.moveTo(0, y);
|
|
p.lineTo(w, y);
|
|
}
|
|
for (let k = 0; k <= cols; k++) {
|
|
if (k === skipCol) continue;
|
|
const x = k * pitch;
|
|
const p = k % GRID_TICK === 0 ? majorPath : minorPath;
|
|
p.moveTo(x, 0);
|
|
p.lineTo(x, h);
|
|
}
|
|
} else if (style === 'crosses') {
|
|
// SMALL_CROSS (opengl_gal.cpp:1973-1993): a cross is coarse only where
|
|
// *both* indices are on a tick (`tickX && tickY`), and each arm is
|
|
// `lineLen = 2.0 * GetLineWidth()`.
|
|
//
|
|
// The two backends disagree by half a pixel here — CAIRO_GAL_BASE::
|
|
// drawGridCross uses `2.0 * m_lineWidthInPixels + 0.5` — and OpenGL is
|
|
// KiCad's default renderer, so that is the one we match.
|
|
for (let k = 0; k <= cols; k++) {
|
|
const x = k * pitch;
|
|
const tickX = k % GRID_TICK === 0;
|
|
for (let l = 0; l <= rows; l++) {
|
|
const y = l * pitch;
|
|
const coarse = tickX && l % GRID_TICK === 0;
|
|
const p = coarse ? majorPath : minorPath;
|
|
const arm = 2 * (coarse ? majorW : minorW);
|
|
p.moveTo(x - arm, y);
|
|
p.lineTo(x + arm, y);
|
|
p.moveTo(x, y - arm);
|
|
p.lineTo(x, y + arm);
|
|
}
|
|
}
|
|
} else {
|
|
// DOTS (opengl_gal.cpp:1959-2040): the rows are stencilled and the
|
|
// columns drawn through them, so a mark's WIDTH comes from its column's
|
|
// tick-ness and its HEIGHT from its row's — a coarse column is a wider
|
|
// mark, a coarse row a taller one, a coarse crossing a big square. Ours
|
|
// fills them as rectangles in one pass, which is the same picture.
|
|
for (let k = 0; k <= cols; k++) {
|
|
// A dot exists only where a stencilled row and a drawn column cross,
|
|
// so a skipped line takes its whole row or column of marks with it.
|
|
if (k === skipCol) continue;
|
|
const x = k * pitch;
|
|
const sw = k % GRID_TICK === 0 ? majorW : minorW;
|
|
for (let l = 0; l <= rows; l++) {
|
|
if (l === skipRow) continue;
|
|
const sh = l % GRID_TICK === 0 ? majorW : minorW;
|
|
// Each point is snapped, as `drawGridPoint` snaps each one — not the
|
|
// path as a whole. Rounding only the translate would leave every
|
|
// mark off by the same fraction and blur all of them together. The
|
|
// SIZE is snapped too: a mark covers whole device pixels, never a
|
|
// fraction of one. See `gridDotEdge`.
|
|
minorPath.rect(
|
|
gridDotEdge(x, sw),
|
|
gridDotEdge(l * pitch, sh),
|
|
gridDotSize(sw),
|
|
gridDotSize(sh),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
geom = { key, minor: minorPath, major: majorPath };
|
|
geomCache.set(ctx, geom);
|
|
}
|
|
|
|
const tx = worldToDeviceX(view, iA * step + ox);
|
|
const ty = worldToDeviceY(view, jA * step + oy);
|
|
// The dot path is already snapped point by point, so the offset it rides on
|
|
// has to be whole pixels too — a fractional translate would put every
|
|
// snapped mark back between pixels and undo the snapping.
|
|
if (style === 'dots') ctx.translate(Math.round(tx), Math.round(ty));
|
|
else ctx.translate(tx, ty);
|
|
if (style === 'dots') {
|
|
ctx.fillStyle = opts.color;
|
|
ctx.fill(geom.minor);
|
|
} else {
|
|
ctx.strokeStyle = opts.color;
|
|
ctx.setLineDash([]);
|
|
ctx.lineWidth = minorW;
|
|
ctx.stroke(geom.minor);
|
|
ctx.lineWidth = majorW;
|
|
ctx.stroke(geom.major);
|
|
}
|
|
ctx.restore();
|
|
}
|
|
|
|
/** Everything `blitCursor` reads. */
|
|
export interface CrosshairOptions {
|
|
/** `WINDOW_SETTINGS::cursor.cross_hair_mode`. */
|
|
mode?: CrosshairMode;
|
|
/** The frame's `GetCursorColor()`. */
|
|
color: string;
|
|
/** `m_isCursorEnabled` — the active tool asked for a crosshair. */
|
|
toolWantsCursor?: boolean;
|
|
/** `m_forceDisplayCursor` — "Always show crosshairs". */
|
|
alwaysShow?: boolean;
|
|
/** GAL's `m_scaleFactor`; the pen is 1 logical px (`glLineWidth( 1.0 )`). */
|
|
devicePixelRatio?: number;
|
|
}
|
|
|
|
/**
|
|
* `blitCursor` (`cairo_gal.cpp:1204-1235`, `opengl_gal.cpp:2823-2915`).
|
|
*
|
|
* `cursor` is already in device pixels and already snapped — upstream draws at
|
|
* `m_cursorPosition`, which the tools set through
|
|
* `VIEW_CONTROLS::ForceCursorPosition`/the grid helper, so the crosshair marks
|
|
* where the click will land rather than where the pointer is. Pass null to draw
|
|
* nothing (the pointer has left the canvas).
|
|
*
|
|
* The caller's transform is saved and restored.
|
|
*/
|
|
export function drawCrosshair(
|
|
ctx: CanvasRenderingContext2D,
|
|
cursor: { x: number; y: number } | null,
|
|
widthPx: number,
|
|
heightPx: number,
|
|
opts: CrosshairOptions,
|
|
): void {
|
|
if (!cursor) return;
|
|
const alpha = cursorAlphaFactor(opts.toolWantsCursor ?? false, opts.alwaysShow ?? false);
|
|
if (alpha === null) return;
|
|
const dpr = opts.devicePixelRatio && opts.devicePixelRatio > 0 ? opts.devicePixelRatio : 1;
|
|
|
|
ctx.save();
|
|
ctx.setTransform(1, 0, 0, 1, 0, 0);
|
|
// Clip so the 45-degree lines (deliberately oversized upstream) and the
|
|
// full-window ones never spill past the canvas.
|
|
ctx.beginPath();
|
|
ctx.rect(0, 0, widthPx, heightPx);
|
|
ctx.clip();
|
|
ctx.strokeStyle = dimmedCursorColor(opts.color, alpha);
|
|
ctx.lineWidth = Math.max(1, dpr);
|
|
ctx.setLineDash([]);
|
|
ctx.beginPath();
|
|
for (const s of crosshairSegments(opts.mode ?? 'small', cursor, widthPx, heightPx, dpr)) {
|
|
ctx.moveTo(s.x1, s.y1);
|
|
ctx.lineTo(s.x2, s.y2);
|
|
}
|
|
ctx.stroke();
|
|
ctx.restore();
|
|
}
|