@sudobility/music_drawing 0.0.33 → 0.0.35

package/dist/canvas-renderer.d.ts

@@ -19,7 +19,28 @@ 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;
+    /**
+     * Which part of the frame to draw. Default `'all'`.
+     *
+     * A frame is two layers. The **overlay** is the active track's notes — the
+     * noteheads, stems and flags, their beams, tuplet brackets, ties and slurs —
+     * with the track-info gutter over them; the **base** is everything else.
+     * Playback only ever changes the overlay: the only notes that light up are
+     * the active track's (`noteColorsFor`), so a host that keeps the base from
+     * the last paint redraws one track's notes per change of lit notes instead
+     * of the whole window. See `createLayeredPaint`.
+     *
+     * `'all'` is exactly `'base'` followed by `'overlay'` on the same context,
+     * so a layered host and a single-pass one draw the same picture — the
+     * active track's notes sit over the rest of the window either way.
+     *
+     * `'overlay'` never clears, and draws against the window the last `'base'`
+     * pass built. Asked for a window that pass did not paint, it draws the
+     * whole frame instead, which is right whatever lies underneath.
+     */
+    layer?: RenderLayer;
 };
+export type RenderLayer = 'all' | 'base' | 'overlay';
 /**
  * Where notes actually live inside a measure.
  *
@@ -144,7 +165,52 @@ export declare class CanvasScoreRenderer {
     private columnFor;
     /** Trims the column cache back to twice what the frame just drew, oldest first. */
     private evictColumns;
+    /**
+     * Builds, without drawing anything, up to `limit` of the measure columns the
+     * window in `options.viewport` needs and this renderer does not already
+     * hold; answers how many are still missing after that.
+     *
+     * Building a column — constructing and formatting its VexFlow objects — is
+     * what a frame costs when it shows music it has not shown before, which
+     * during playback is exactly the frame the view moves to the next system on:
+     * measured at 8ms in a browser on a dense score, several times that on a
+     * phone's engine, landing on the moment the eye is following the music
+     * across the break. A host that calls this ahead of time, a column per idle
+     * task, turns that frame into an ordinary repaint.
+     *
+     * The columns go into the same cache `render` reads, so nothing else
+     * changes: the frame that eventually shows them is built from them.
+     */
+    prepare(score: Score, options: CanvasRenderOptions, limit?: number): number;
     render(score: Score, ctx: DrawingContext2D, options: CanvasRenderOptions): CanvasRenderResult;
+    /**
+     * The track whose notes are the overlay: the active one, on screen.
+     *
+     * Null in print, and with no active track, which is when nothing can light
+     * up and the base carries every note.
+     */
+    private overlayTrackId;
+    /** Sets the frame's transform on `ctx`, content scrolled by the viewport. */
+    private applyContentTransform;
+    /** Clears the canvas and paints everything but the overlay track's notes. */
+    private paintBase;
+    /**
+     * Paints the overlay track's notes over a base already on the canvas: its
+     * voices, beams and tuplets on the staves the base drew, then its ties and
+     * slurs. Never clears.
+     */
+    private paintOverlay;
+    private drawSpans;
+    /**
+     * What the host gets back.
+     *
+     * Note boxes only once the frame is complete: VexFlow places a note when it
+     * draws it (see `ColumnDrawing.bboxes`), so a base pass that left the active
+     * track out would report none for it — and a base on its own is never what a
+     * host hit-tests against, because the overlay pass that follows returns the
+     * whole frame's.
+     */
+    private frameResult;
     /**
      * Assembles the drawn window out of measure columns, building only the ones
      * the cache does not already hold.
@@ -257,13 +323,22 @@ export declare class CanvasScoreRenderer {
      */
     private collectColumnBBoxes;
     /**
-     * Paints an already-built system.
+     * Paints an already-built system, less the overlay track's notes.
      *
      * 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.
+     * again when the selection moves — cheap beside the building it no longer
+     * has to repeat.
+     */
+    private paintSystemBase;
+    /**
+     * One track's notes, beams and tuplets over a system the base already drew.
+     *
+     * Styled here rather than in the base, since this is where the colour a
+     * change of lit notes makes is applied.
      */
-    private paintSystem;
+    private paintSystemOverlay;
+    /** Beams, then tuplet brackets, for the tracks `include` admits. */
+    private drawBeamsAndTuplets;
     /**
      * Tints every selected measure across the full height of the system.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"canvas-renderer.d.ts","sourceRoot":"","sources":["../src/canvas-renderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canvas-renderer.d.ts","sourceRoot":"","sources":["../src/canvas-renderer.ts"],"names":[],"mappings":"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"}

package/dist/canvas-renderer.js

@@ -289,20 +289,60 @@ export class CanvasScoreRenderer {
             this.columns.delete(oldest.value);
         }
     }
+    /**
+     * Builds, without drawing anything, up to `limit` of the measure columns the
+     * window in `options.viewport` needs and this renderer does not already
+     * hold; answers how many are still missing after that.
+     *
+     * Building a column — constructing and formatting its VexFlow objects — is
+     * what a frame costs when it shows music it has not shown before, which
+     * during playback is exactly the frame the view moves to the next system on:
+     * measured at 8ms in a browser on a dense score, several times that on a
+     * phone's engine, landing on the moment the eye is following the music
+     * across the break. A host that calls this ahead of time, a column per idle
+     * task, turns that frame into an ordinary repaint.
+     *
+     * The columns go into the same cache `render` reads, so nothing else
+     * changes: the frame that eventually shows them is built from them.
+     */
+    prepare(score, options, limit = 1) {
+        const z = resolveZoom(options.zoom);
+        const plan = this.planFor(score, options);
+        if (this.columnsPlan !== plan) {
+            this.columns.clear();
+            this.columnsPlan = plan;
+        }
+        const systems = systemsInRange(plan, options.viewport.top, options.viewport.bottom);
+        let built = 0;
+        let missing = 0;
+        for (const system of systems) {
+            const indices = this.visibleMeasureIndices(system, plan, options.viewport.left ?? 0, options.viewport.right ?? Number.POSITIVE_INFINITY);
+            for (const measureIndex of indices) {
+                if (this.columns.has(measureIndex))
+                    continue;
+                if (built >= limit) {
+                    missing += 1;
+                    continue;
+                }
+                built += 1;
+                try {
+                    this.columns.set(measureIndex, this.buildColumn(measureIndex, plan, score, z));
+                }
+                catch {
+                    // The frame that needs it will try again and report the failure
+                    // where it would have anyway; a preparation has nobody to tell.
+                }
+            }
+        }
+        return missing;
+    }
     render(score, ctx, options) {
         const z = resolveZoom(options.zoom);
         const dpr = options.devicePixelRatio ?? 1;
         const plan = this.planFor(score, options);
+        const layer = options.layer ?? 'all';
         const viewportLeft = options.viewport.left ?? 0;
         const viewportRight = options.viewport.right ?? Number.POSITIVE_INFINITY;
-        ctx.setTransform(1, 0, 0, 1, 0, 0);
-        ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
-        // `+ 0` normalizes -0 (from a zero scroll offset) to 0.
-        ctx.setTransform(z * dpr, 0, 0, z * dpr, -viewportLeft * z * dpr + 0, -options.viewport.top * z * dpr + 0);
-        const vexCtx = new CanvasContext(ctx);
-        const ink = this.inkColor(options);
-        vexCtx.setFillStyle(ink);
-        vexCtx.setStrokeStyle(ink);
         const visibleSystems = systemsInRange(plan, options.viewport.top, options.viewport.bottom);
         // Everything the drawn window depends on, and nothing colour does. A
         // repaint driven by a note starting or a selection moving produces the same
@@ -313,19 +353,81 @@ export class CanvasScoreRenderer {
             : null;
         const frame = cached ?? this.buildWindow(key, plan, score, z, options, visibleSystems);
         this.window = frame;
-        const { drawings, channelsByTrack, measureIdToBBox, measureNotePositions, drawnMeasureIndices, } = frame;
+        /*
+          The overlay is drawn against what the base pass inked, and only a base
+          pass over this window with the same active track can say what that was.
+          Anything else — a window that has just been built, or a base that left
+          out a different track — means the host's base is not this frame's, and
+          the whole frame is drawn instead: right whatever lies underneath, since
+          it clears first.
+        */
+        const overlayTrackId = this.overlayTrackId(options);
+        const effective = layer === 'overlay' &&
+            (frame.painted === null ||
+                frame.painted.overlayTrackId !== overlayTrackId)
+            ? 'all'
+            : layer;
+        const vexCtx = new CanvasContext(ctx);
+        if (effective !== 'overlay') {
+            this.paintBase(frame, plan, ctx, vexCtx, z, dpr, options, overlayTrackId);
+        }
+        if (effective === 'base') {
+            // The host composites the overlay over this; the result it needs comes
+            // from that pass, which is the one that finishes the frame.
+            return this.frameResult(frame, plan, z, options, false);
+        }
+        this.paintOverlay(frame, ctx, vexCtx, z, dpr, options);
+        if (shouldShowTrackInfo(options)) {
+            this.drawTrackInfoGutter(plan, ctx, z, dpr, visibleSystems, options);
+        }
+        return this.frameResult(frame, plan, z, options, true);
+    }
+    /**
+     * The track whose notes are the overlay: the active one, on screen.
+     *
+     * Null in print, and with no active track, which is when nothing can light
+     * up and the base carries every note.
+     */
+    overlayTrackId(options) {
+        if (this.isPrint(options))
+            return null;
+        return options.activeTrackId ?? null;
+    }
+    /** Sets the frame's transform on `ctx`, content scrolled by the viewport. */
+    applyContentTransform(ctx, z, dpr, options) {
+        const viewportLeft = options.viewport.left ?? 0;
+        // `+ 0` normalizes -0 (from a zero scroll offset) to 0.
+        ctx.setTransform(z * dpr, 0, 0, z * dpr, -viewportLeft * z * dpr + 0, -options.viewport.top * z * dpr + 0);
+    }
+    /** Clears the canvas and paints everything but the overlay track's notes. */
+    paintBase(frame, plan, ctx, vexCtx, z, dpr, options, overlayTrackId) {
+        ctx.setTransform(1, 0, 0, 1, 0, 0);
+        ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+        this.applyContentTransform(ctx, z, dpr, options);
+        const ink = this.inkColor(options);
+        vexCtx.setFillStyle(ink);
+        vexCtx.setStrokeStyle(ink);
         // Which staves this frame actually put ink on. Spans are drawn after every
         // system, so they need the whole frame's answer, not one system's.
         const drawnStaves = new Set();
         const drawnTrackIds = new Set();
-        for (const drawing of drawings) {
+        const visibleStaves = [];
+        for (const drawing of frame.drawings) {
+            const onScreen = new Set();
+            visibleStaves.push(onScreen);
             try {
-                this.paintSystem(drawing, plan, vexCtx, ctx, options, drawnStaves, drawnTrackIds);
+                this.paintSystemBase(drawing, plan, vexCtx, ctx, options, overlayTrackId, onScreen, drawnStaves, drawnTrackIds);
             }
             catch (error) {
                 console.error('CanvasScoreRenderer: skipping system after draw failure', drawing.system.measureIndices, error);
             }
         }
+        frame.painted = {
+            drawnStaves,
+            drawnTrackIds,
+            visibleStaves,
+            overlayTrackId,
+        };
         // Ties and the other spans reach across measures — and across systems —
         // within the drawn window, so they go on last, over everything.
         //
@@ -334,8 +436,41 @@ export class CanvasScoreRenderer {
         // window. Only their colour is a per-frame decision, and that is applied
         // below. They cannot be built before the first paint, though, because a
         // span takes its Y from notes that must already have been drawn.
-        frame.spans ?? (frame.spans = this.buildSpans(channelsByTrack, drawnStaves, drawnTrackIds));
-        for (const { span, trackId, what } of frame.spans) {
+        frame.spans ?? (frame.spans = this.buildSpans(frame.channelsByTrack, drawnStaves, drawnTrackIds));
+        this.drawSpans(frame.spans, vexCtx, options, span => overlayTrackId === null ? true : span.trackId !== overlayTrackId);
+    }
+    /**
+     * Paints the overlay track's notes over a base already on the canvas: its
+     * voices, beams and tuplets on the staves the base drew, then its ties and
+     * slurs. Never clears.
+     */
+    paintOverlay(frame, ctx, vexCtx, z, dpr, options) {
+        const painted = frame.painted;
+        const trackId = painted?.overlayTrackId ?? null;
+        if (!painted || trackId === null)
+            return;
+        this.applyContentTransform(ctx, z, dpr, options);
+        frame.drawings.forEach((drawing, index) => {
+            try {
+                this.paintSystemOverlay(drawing, vexCtx, options, trackId, painted.visibleStaves[index] ?? new Set());
+            }
+            catch (error) {
+                console.error('CanvasScoreRenderer: skipping system after draw failure', drawing.system.measureIndices, error);
+            }
+        });
+        // After this track's notes, so a tie takes its Y from a drawn notehead.
+        if (frame.spans) {
+            this.drawSpans(frame.spans, vexCtx, options, span => span.trackId === trackId);
+        }
+    }
+    drawSpans(spans, vexCtx, options, include) {
+        const ink = this.inkColor(options);
+        vexCtx.setFillStyle(ink);
+        vexCtx.setStrokeStyle(ink);
+        for (const drawing of spans) {
+            if (!include(drawing))
+                continue;
+            const { span, trackId, what } = drawing;
             // Per span, not per channel: one bad tie used to abandon every remaining
             // tie in the channel, so visible ties vanished too.
             try {
@@ -350,21 +485,29 @@ export class CanvasScoreRenderer {
                 console.error(`CanvasScoreRenderer: skipping ${what} after draw failure`, error);
             }
         }
-        // After painting, not before — see `ColumnDrawing.bboxes`.
+    }
+    /**
+     * What the host gets back.
+     *
+     * Note boxes only once the frame is complete: VexFlow places a note when it
+     * draws it (see `ColumnDrawing.bboxes`), so a base pass that left the active
+     * track out would report none for it — and a base on its own is never what a
+     * host hit-tests against, because the overlay pass that follows returns the
+     * whole frame's.
+     */
+    frameResult(frame, plan, z, options, complete) {
         const idToBBox = new Map();
-        for (const drawing of drawings)
-            for (const column of drawing.columns)
-                this.collectColumnBBoxes(column, z, drawnStaves, drawnTrackIds, idToBBox);
-        // Last, so it overlays any content that scrolled underneath it — and not
-        // at all for print, where there is nothing to click.
-        if (shouldShowTrackInfo(options)) {
-            this.drawTrackInfoGutter(plan, ctx, z, dpr, visibleSystems, options);
+        const painted = frame.painted;
+        if (complete && painted) {
+            for (const drawing of frame.drawings)
+                for (const column of drawing.columns)
+                    this.collectColumnBBoxes(column, z, painted.drawnStaves, painted.drawnTrackIds, idToBBox);
         }
         return {
             idToBBox,
-            measureIdToBBox,
-            measureNotePositions,
-            drawnMeasureIndices,
+            measureIdToBBox: frame.measureIdToBBox,
+            measureNotePositions: frame.measureNotePositions,
+            drawnMeasureIndices: frame.drawnMeasureIndices,
             plan,
             theme: options.theme,
         };
@@ -447,6 +590,7 @@ export class CanvasScoreRenderer {
             measureNotePositions,
             drawnMeasureIndices,
             spans: null,
+            painted: null,
         };
     }
     /**
@@ -824,6 +968,7 @@ export class CanvasScoreRenderer {
         };
         const measureStaves = [];
         const voiceGroups = [];
+        const voiceGroupTracks = [];
         const allMetas = []; // buildMeasureContent appends; unused here (channels carry the metas)
         plan.trackLayouts.forEach((trackLayout, trackIndex) => {
             const track = trackLayout.track;
@@ -862,6 +1007,7 @@ export class CanvasScoreRenderer {
             if (voices.length > 0) {
                 voices.forEach(v => v.setStave(stave));
                 voiceGroups.push(voices);
+                voiceGroupTracks.push(track.id);
             }
             column.measureIdToBBox.set(measure.id, {
                 x: placement.box.x * z,
@@ -913,7 +1059,13 @@ export class CanvasScoreRenderer {
                 formatter.joinVoices(group);
             const justifyWidth = Math.max(20, Math.min(...measureStaves.map(s => s.getNoteEndX() - s.getNoteStartX())) - BARLINE_CLEARANCE);
             formatter.format(voiceGroups.flat(), justifyWidth);
-            column.voices.push(...voiceGroups.flat());
+            voiceGroups.forEach((group, index) => {
+                const trackId = voiceGroupTracks[index];
+                if (trackId === undefined)
+                    return;
+                for (const voice of group)
+                    column.voices.push({ voice, trackId });
+            });
             /*
               Attach each tickable to its stave, then record where the formatter put
               it. This is what lets the caret share the notes' own positions rather
@@ -984,15 +1136,19 @@ export class CanvasScoreRenderer {
         }
     }
     /**
-     * Paints an already-built system.
+     * Paints an already-built system, less the overlay track's notes.
      *
      * 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.
+     * again when the selection moves — cheap beside the building it no longer
+     * has to repeat.
      */
-    paintSystem(drawing, plan, vexCtx, 
+    paintSystemBase(drawing, plan, vexCtx, 
     /** The raw 2D context behind `vexCtx`: the measure gutter is a number and a rect, so it needs nothing VexFlow provides. */
     ctx, options, 
+    /** Whose notes are left for the overlay; null leaves nothing out. */
+    overlayTrackId, 
+    /** Collects this system's on-screen staves, for the overlay to draw on. */
+    visibleStaves, 
     /** Collects the staves this system actually drew, for the frame's ties. */
     drawnStaves, 
     /** Collects track ids that drew at least one stave, so later frame-wide scans can skip wholly off-screen tracks. */
@@ -1025,7 +1181,6 @@ export class CanvasScoreRenderer {
         // One pass per kind rather than one per column, so the draw order is by
         // kind across the whole system — which is what puts every beam over every
         // notehead rather than only over its own measure's.
-        const visibleStaves = new Set();
         for (const column of columns) {
             for (const { stave, trackId } of column.staves) {
                 if (!onScreen(stave))
@@ -1033,7 +1188,9 @@ export class CanvasScoreRenderer {
                 visibleStaves.add(stave);
                 drawnStaves.add(stave);
                 drawnTrackIds.add(trackId);
-                this.styleColumnTrackNotes(column, trackId, options);
+                if (trackId !== overlayTrackId) {
+                    this.styleColumnTrackNotes(column, trackId, options);
+                }
                 const dimmed = this.notesDimmed(trackId, options);
                 stave.setStyle({
                     strokeStyle: this.staveColor(trackId, options),
@@ -1055,7 +1212,9 @@ export class CanvasScoreRenderer {
         vexCtx.setFillStyle(ink);
         vexCtx.setStrokeStyle(ink);
         for (const column of columns) {
-            for (const voice of column.voices) {
+            for (const { voice, trackId } of column.voices) {
+                if (trackId === overlayTrackId)
+                    continue;
                 const stave = voice.getStave();
                 if (stave && !visibleStaves.has(stave))
                     continue;
@@ -1063,6 +1222,7 @@ export class CanvasScoreRenderer {
             }
         }
         // After the formatter has run, so the stave's final geometry is settled.
+        // Rests stay in the base: a bar's multi-measure rest never lights up.
         for (const column of columns) {
             for (const { rest, trackId } of column.rests) {
                 const stave = rest.getStave?.();
@@ -1076,9 +1236,60 @@ export class CanvasScoreRenderer {
         }
         vexCtx.setFillStyle(ink);
         vexCtx.setStrokeStyle(ink);
+        this.drawBeamsAndTuplets(columns, vexCtx, options, visibleStaves, trackId => trackId !== overlayTrackId);
+        if (plan.tracks.length > 1) {
+            const topStave = firstStaveByTrack.get(0);
+            const bottomStave = firstStaveByTrack.get(plan.tracks.length - 1);
+            // Culled like everything else. Without this the brace was drawn even
+            // when both of the staves it joins were scrolled off — on a tall score
+            // it stretched thousands of pixels and the slice inside the viewport
+            // read as a stray vertical mark in the corner rather than as notation.
+            if (topStave &&
+                bottomStave &&
+                topStave !== bottomStave &&
+                visibleStaves.has(topStave) &&
+                visibleStaves.has(bottomStave)) {
+                const connector = new StaveConnector(topStave, bottomStave);
+                connector.setType('brace');
+                connector.setContext(vexCtx);
+                connector.draw();
+            }
+        }
+        this.drawMeasureGutter(system, plan, ctx, windowIndices, options);
+    }
+    /**
+     * One track's notes, beams and tuplets over a system the base already drew.
+     *
+     * Styled here rather than in the base, since this is where the colour a
+     * change of lit notes makes is applied.
+     */
+    paintSystemOverlay(drawing, vexCtx, options, trackId, visibleStaves) {
+        const { columns } = drawing;
+        for (const column of columns) {
+            const visible = column.staves.some(entry => entry.trackId === trackId && visibleStaves.has(entry.stave));
+            if (visible)
+                this.styleColumnTrackNotes(column, trackId, options);
+        }
+        const ink = this.inkColor(options);
+        vexCtx.setFillStyle(ink);
+        vexCtx.setStrokeStyle(ink);
+        for (const column of columns) {
+            for (const entry of column.voices) {
+                if (entry.trackId !== trackId)
+                    continue;
+                const stave = entry.voice.getStave();
+                if (stave && !visibleStaves.has(stave))
+                    continue;
+                entry.voice.draw(vexCtx);
+            }
+        }
+        this.drawBeamsAndTuplets(columns, vexCtx, options, visibleStaves, id => id === trackId);
+    }
+    /** Beams, then tuplet brackets, for the tracks `include` admits. */
+    drawBeamsAndTuplets(columns, vexCtx, options, visibleStaves, include) {
         for (const column of columns) {
             for (const { beam, trackId, stave } of column.beams) {
-                if (!visibleStaves.has(stave))
+                if (!include(trackId) || !visibleStaves.has(stave))
                     continue;
                 const color = this.trackColor(this.notesDimmed(trackId, options), options);
                 beam.setStyle({ fillStyle: color, strokeStyle: color });
@@ -1093,7 +1304,7 @@ export class CanvasScoreRenderer {
         */
         for (const column of columns) {
             for (const { tuplet, trackId, stave } of column.tuplets) {
-                if (!visibleStaves.has(stave))
+                if (!include(trackId) || !visibleStaves.has(stave))
                     continue;
                 const color = this.trackColor(this.notesDimmed(trackId, options), options);
                 tuplet.setStyle({ fillStyle: color, strokeStyle: color });
@@ -1101,25 +1312,6 @@ export class CanvasScoreRenderer {
                 tuplet.draw();
             }
         }
-        if (plan.tracks.length > 1) {
-            const topStave = firstStaveByTrack.get(0);
-            const bottomStave = firstStaveByTrack.get(plan.tracks.length - 1);
-            // Culled like everything else. Without this the brace was drawn even
-            // when both of the staves it joins were scrolled off — on a tall score
-            // it stretched thousands of pixels and the slice inside the viewport
-            // read as a stray vertical mark in the corner rather than as notation.
-            if (topStave &&
-                bottomStave &&
-                topStave !== bottomStave &&
-                visibleStaves.has(topStave) &&
-                visibleStaves.has(bottomStave)) {
-                const connector = new StaveConnector(topStave, bottomStave);
-                connector.setType('brace');
-                connector.setContext(vexCtx);
-                connector.draw();
-            }
-        }
-        this.drawMeasureGutter(system, plan, ctx, windowIndices, options);
     }
     /**
      * Tints every selected measure across the full height of the system.