@sudobility/music_drawing 0.0.1

package/dist/canvas-renderer.d.ts

@@ -0,0 +1,180 @@
+import type { Score } from '@sudobility/music_types';
+import type { LayoutPlan } from './layout.js';
+import type { BBox, RenderOptions, RenderTheme } from './types.js';
+/**
+ * Logical (unscaled) content-coordinate window to draw: typically
+ * `scrollTop/zoom` .. `(scrollTop+clientHeight)/zoom`. `left`/`right`
+ * (defaults: 0/∞ — full width, page-mode behavior) window the draw
+ * horizontally too: continuous mode lays every measure in ONE system, so
+ * without them each frame would draw the entire score.
+ */
+export type CanvasViewport = {
+    top: number;
+    bottom: number;
+    left?: number;
+    right?: number;
+};
+export type CanvasRenderOptions = RenderOptions & {
+    viewport: CanvasViewport;
+    /** Backing-store scale (window.devicePixelRatio); default 1. The canvas element's width/height must already be sized to cssSize × this. */
+    devicePixelRatio?: number;
+};
+export type CanvasRenderResult = {
+    /** Note/rest event id -> bbox, zoom-scaled CSS px, content coordinates (scroll NOT subtracted). Drawn window only. */
+    idToBBox: Map<string, BBox>;
+    /** Measure id -> its stave box (from the layout plan), same units. Drawn window only; one entry per (track, measure). */
+    measureIdToBBox: Map<string, BBox>;
+    drawnMeasureIndices: Set<number>;
+    /** The (cached) full-score layout this frame was drawn against. */
+    plan: LayoutPlan;
+    theme: RenderTheme;
+};
+/**
+ * Where the instrument row's text and icon go, relative to the stave's top line.
+ *
+ * Two rules, and they fix everything else:
+ *
+ * - the **top of the instrument name** sits on the stave's top line, and
+ * - the **icon's centre** sits on the name's centre.
+ *
+ * "Top of the name" means the top of its capitals, not the top of the font's
+ * em box — the em box carries room for accents that nothing here draws, so
+ * aligning to it leaves a visible gap that reads as misalignment. Hence
+ * `capHeight`, measured from the canvas rather than assumed: a baseline placed
+ * by arithmetic put the icon on the line and the text five pixels under it.
+ *
+ * Pure, and exported, because this is the part worth pinning exactly — the
+ * drawing around it is not.
+ */
+export declare function trackInfoRowLayout(staveTopLine: number, capHeight: number, iconSize: number): {
+    textBaseline: number;
+    iconTop: number;
+    rowCenter: number;
+};
+export declare class CanvasScoreRenderer {
+    private cache;
+    /**
+     * The last frame's built objects, reused when only colour changed.
+     *
+     * The single most expensive thing this renderer does is construct and format
+     * VexFlow objects, and playback asks it to redraw on every note boundary to
+     * move one notehead's colour. Keyed on everything geometry depends on —
+     * score identity, zoom, layout mode, width, track set, viewport — and
+     * deliberately *not* on the theme, the note colours, the active track or the
+     * selection, which are exactly what a repaint changes.
+     *
+     * One frame, not an LRU: during playback the viewport is still, so
+     * consecutive repaints hit it; scrolling misses it and rebuilds, which is the
+     * same work it did before. Bounded by construction, since it only ever holds
+     * what was last drawn.
+     */
+    private frame;
+    private planFor;
+    render(score: Score, ctx: CanvasRenderingContext2D, options: CanvasRenderOptions): CanvasRenderResult;
+    /**
+     * The track-info gutter: name, instrument and mute/solo state beside every
+     * stave, for every visible system.
+     *
+     * Pinned to the viewport's left edge rather than drawn at content x=0. In
+     * continuous mode the score is one very wide system scrolled horizontally, so
+     * a gutter in content space would slide out of view — the one thing a
+     * permanent label column cannot do. The vertical scroll is kept, so the
+     * labels still track their staves.
+     *
+     * Reads `name`/`instrumentName`/`muted`/`solo` straight off the live `Track`,
+     * so there is no render option to keep in sync. Alignment is structural: the
+     * gutter is the space `layout.ts` reserved via `TRACK_INFO_WIDTH`, in the
+     * same coordinate space as the staves.
+     */
+    private drawTrackInfoGutter;
+    /**
+     * Styles one VexFlow note by the highest-precedence role among the domain
+     * events it represents (>1 for a chord, or for one segment of a
+     * duration-decomposed long note).
+     *
+     * Both `fillStyle` and `strokeStyle` are set: noteheads fill, stems and
+     * flags stroke, and a note whose stem stayed the default color would read
+     * as half-highlighted.
+     *
+     * `lineWidth` carries the same state redundantly *without* color (spec §27)
+     * — see `noteEmphasisFor`, including why this is not a shadow.
+     */
+    private styleNote;
+    /**
+     * Whether `trackId` is *the* active track. With no active track set, nothing
+     * is active, so every stave draws in `staveInactive` — the neutral state.
+     */
+    private isActiveTrack;
+    /**
+     * Whether a track's notes should dim.
+     *
+     * Deliberately not `!isActiveTrack`. Dimming is *relative* — it says "this
+     * track is not the one you are working on" — so with no active track set
+     * there is nothing to be relative to and no note dims. Stave lines can sit in
+     * their neutral colour without looking wrong; every note in the score going
+     * grey would just look washed out.
+     */
+    private notesDimmed;
+    /** The unstyled-note color for a track, which its beams and ties follow. */
+    private trackColor;
+    private recordEventBBox;
+    /**
+     * The contiguous slice of `system.measureIndices` whose stave boxes
+     * intersect `[left, right]`, found by binary search over the x-sorted
+     * measure layouts — O(log n), so a continuous-mode frame never scans the
+     * whole single-system score (the horizontal analogue of the y-based
+     * system filter).
+     */
+    private visibleMeasureIndices;
+    /**
+     * Builds one system's VexFlow objects, without deciding what colour anything
+     * is.
+     *
+     * Split from painting so the result can be cached: constructing and
+     * formatting notes is what costs milliseconds (measured at 119ms for a
+     * twelve-track sixteenth-note score at zoom 0.5), and a colour change — a
+     * note starting, a selection moving — changes none of it. See `render`.
+     */
+    private buildSystem;
+    /**
+     * Paints an already-built system.
+     *
+     * Everything here is a colour decision or a context write, so it is what runs
+     * again when a note starts sounding or the selection moves — cheap beside the
+     * building it no longer has to repeat.
+     */
+    private paintSystem;
+    /**
+     * Tints every selected measure across the full height of the system.
+     *
+     * The whole bar, not a mark near it: a selection's *extent* is the thing that
+     * has to be legible — "these four bars, on every staff" — and the 2px rule
+     * this replaces stated that in the one strip of the sheet nobody is looking
+     * at. Spanning the system rather than one track's stave is deliberate, and
+     * matches what the selection means: the measure gutter is one band per
+     * system, and replacing a measure region acts on every track in it.
+     *
+     * Drawn **before** the staves and notes so it reads as paper the music sits
+     * on. Over the top it would tint the noteheads themselves, and a selected
+     * bar's notes would not match the same notes anywhere else.
+     */
+    private paintSelectedMeasures;
+    /**
+     * Measure numbers in the band above the system's top stave, with any
+     * measure in `selectedMeasureIds` picked out in the selection colour.
+     *
+     * Extent is carried by `paintSelectedMeasures`, which tints the bar itself;
+     * this only has to say which number belongs to it. It used to draw a 2px rule
+     * under the number instead, which was the only thing showing how far a
+     * selection reached and was easy to miss entirely.
+     *
+     * Drawn straight to the 2D context: there is no VexFlow object for "the
+     * space above a stave", and a number plus a rect needs none. Measure
+     * geometry comes off track 0 because every track shares one measure grid
+     * (see `rebuildMeasureTicks`), which is what lets one gutter serve the
+     * whole system.
+     */
+    private drawMeasureGutter;
+    dispose(): void;
+}
+//# sourceMappingURL=canvas-renderer.d.ts.map

package/dist/canvas-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-renderer.d.ts","sourceRoot":"","sources":["../src/canvas-renderer.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAkBrD,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGnE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAChD,QAAQ,EAAE,cAAc,CAAC;IACzB,2IAA2I;IAC3I,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sHAAsH;IACtH,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5B,yHAAyH;IACzH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB,CAAC;AAwEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAM9D;AAeD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAgE;IAC7E;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,KAAK,CAA2B;IAExC,OAAO,CAAC,OAAO;IAcf,MAAM,CACJ,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,wBAAwB,EAC7B,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB;IA8PrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,mBAAmB;IAgH3B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,SAAS;IAejB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAInB,4EAA4E;IAC5E,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,eAAe;IAyBvB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAuC7B;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAiInB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAwJnB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,qBAAqB;IAuC7B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,iBAAiB;IA4CzB,OAAO,IAAI,IAAI;CAIhB"}