feat(rendering): add per-beat rest display position via beat.restDisplayTone, beat.restDisplayOctave (#2721)

Co-authored-by: Danielku15 <danielku15@coderline.net>

Author: roscopeeco

packages/alphatab/src/generated/model/BeatCloner.ts

@@ -39,6 +39,8 @@ export class BeatCloner {
         clone.text = original.text;
         clone.slashed = original.slashed;
         clone.deadSlapped = original.deadSlapped;
+        clone.restDisplayTone = original.restDisplayTone;
+        clone.restDisplayOctave = original.restDisplayOctave;
         clone.brushType = original.brushType;
         clone.brushDuration = original.brushDuration;
         clone.tupletDenominator = original.tupletDenominator;

packages/alphatab/src/generated/model/BeatSerializer.ts

@@ -64,6 +64,8 @@ export class BeatSerializer {
         o.set("text", obj.text);
         o.set("slashed", obj.slashed);
         o.set("deadslapped", obj.deadSlapped);
+        o.set("restdisplaytone", obj.restDisplayTone);
+        o.set("restdisplayoctave", obj.restDisplayOctave);
         o.set("brushtype", obj.brushType as number);
         o.set("brushduration", obj.brushDuration);
         o.set("tupletdenominator", obj.tupletDenominator);
@@ -168,6 +170,12 @@ export class BeatSerializer {
             case "deadslapped":
                 obj.deadSlapped = v! as boolean;
                 return true;
+            case "restdisplaytone":
+                obj.restDisplayTone = v! as number;
+                return true;
+            case "restdisplayoctave":
+                obj.restDisplayOctave = v! as number;
+                return true;
             case "brushtype":
                 obj.brushType = JsonHelper.parseEnum<BrushType>(v, BrushType)!;
                 return true;

packages/alphatab/src/importer/alphaTex/AlphaTex1LanguageDefinitions.ts

@@ -664,6 +664,7 @@ export class AlphaTex1LanguageDefinitions {
             ]
         ],
         ['txt', [[[[17, 10], 0]]]],
+        ['restdisplaypitch', [[[[10, 17], 0]]]],
         [
             'lyrics',
             [

packages/alphatab/src/importer/alphaTex/AlphaTex1LanguageHandler.ts

@@ -1616,6 +1616,23 @@ export class AlphaTex1LanguageHandler implements IAlphaTexLanguageImportHandler
             case 'txt':
                 beat.text = (p.arguments!.arguments[0] as AlphaTexTextNode).text;
                 return ApplyNodeResult.Applied;
+            case 'restdisplaypitch': {
+                const tuning = ModelUtils.parseTuning((p.arguments!.arguments[0] as AlphaTexTextNode).text);
+                if (tuning !== null) {
+                    beat.restDisplayTone = tuning.tone.noteValue;
+                    beat.restDisplayOctave = tuning.octave - 1;
+                } else {
+                    importer.addSemanticDiagnostic({
+                        code: AlphaTexDiagnosticCode.AT212,
+                        message: `Invalid pitch value '${(p.arguments!.arguments[0] as AlphaTexTextNode).text}', expected format like 'C5' or 'G4'`,
+                        severity: AlphaTexDiagnosticsSeverity.Error,
+                        start: p.arguments!.arguments[0].start,
+                        end: p.arguments!.arguments[0].end
+                    });
+                    return ApplyNodeResult.NotAppliedSemanticError;
+                }
+                return ApplyNodeResult.Applied;
+            }
             case 'lyrics':
                 let lyricsLine = 0;
                 let lyricsText = '';

packages/alphatab/src/model/Beat.ts

@@ -425,6 +425,18 @@ export class Beat {
      */
     public deadSlapped: boolean = false;
 
+    /**
+     * Gets or sets the chromatic tone value (0–11) of the pitch at which this rest should be displayed.
+     * A value of -1 means use the default position formula.
+     */
+    public restDisplayTone: number = -1;
+
+    /**
+     * Gets or sets the octave at which this rest should be displayed.
+     * Only relevant when {@link restDisplayTone} is set. -1 means use the default position formula.
+     */
+    public restDisplayOctave: number = -1;
+
     /**
      * Gets or sets the brush type applied to the notes of this beat.
      */

packages/alphatab/src/rendering/glyphs/ScoreBeatGlyph.ts

@@ -1,5 +1,6 @@
 import { Logger } from '@coderline/alphatab/Logger';
 import { AccentuationType } from '@coderline/alphatab/model/AccentuationType';
+import { AccidentalHelper } from '@coderline/alphatab/rendering/utils/AccidentalHelper';
 import { BeatSubElement } from '@coderline/alphatab/model/Beat';
 import { Duration } from '@coderline/alphatab/model/Duration';
 import { GraceType } from '@coderline/alphatab/model/GraceType';
@@ -301,18 +302,23 @@ export class ScoreBeatGlyph extends BeatOnNoteGlyphBase {
 
     private _createRestGlyphs() {
         const sr = this.renderer as ScoreBarRenderer;
-
-        let steps = Math.ceil((this.renderer.bar.staff.standardNotationLineCount - 1) / 2) * 2;
-
-        // this positioning is quite strange, for most staff line counts
-        // the whole/rest are aligned as half below the whole rest.
-        // but for staff line count 1 and 3 they are aligned centered on the same line.
-        if (
-            this.container.beat.duration === Duration.Whole &&
-            this.renderer.bar.staff.standardNotationLineCount !== 1 &&
-            this.renderer.bar.staff.standardNotationLineCount !== 3
-        ) {
-            steps -= 2;
+        const beat = this.container.beat;
+        const lineCount = this.renderer.bar.staff.standardNotationLineCount;
+
+        let steps: number;
+        if (beat.restDisplayTone !== -1 && beat.restDisplayOctave !== -1) {
+            // Per-beat override: same step as a note at that pitch. SMuFL rest glyphs use the same
+            // baseline convention as note heads, so no further adjustment is applied.
+            steps = AccidentalHelper.calculateRestDisplaySteps(sr.bar, beat.restDisplayTone, beat.restDisplayOctave);
+        } else {
+            // Default placement: centred on the staff. Whole rests sit one line above (per SMuFL/Guitar Pro
+            // convention) so their hanging body lines up with where half/shorter rest bodies appear.
+            // 1- and 3-line staves keep the whole rest on the default rest line (Guitar Pro convention;
+            // see musescore/MuseScore#25279).
+            steps = Math.ceil((lineCount - 1) / 2) * 2;
+            if (beat.duration === Duration.Whole && lineCount !== 1 && lineCount !== 3) {
+                steps -= 2;
+            }
         }
 
         const restGlyph = new ScoreRestGlyph(0, sr.getScoreY(steps), this.container.beat.duration);

packages/alphatab/src/rendering/utils/AccidentalHelper.ts

@@ -5,6 +5,7 @@ import type { Clef } from '@coderline/alphatab/model/Clef';
 import { ModelUtils, type ResolvedSpelling } from '@coderline/alphatab/model/ModelUtils';
 import type { Note } from '@coderline/alphatab/model/Note';
 import { NoteAccidentalMode } from '@coderline/alphatab/model/NoteAccidentalMode';
+import { Ottavia } from '@coderline/alphatab/model/Ottavia';
 import { PercussionMapper } from '@coderline/alphatab/model/PercussionMapper';
 import type { LineBarRenderer } from '@coderline/alphatab/rendering/LineBarRenderer';
 import type { ScoreBarRenderer } from '@coderline/alphatab/rendering/ScoreBarRenderer';
@@ -267,6 +268,27 @@ export class AccidentalHelper {
         return steps;
     }
 
+    public static calculateRestDisplaySteps(bar: Bar, tone: number, octave: number): number {
+        let noteValue = (octave + 1) * 12 + tone;
+        switch (bar.clefOttava) {
+            case Ottavia._15ma:
+                noteValue -= 24;
+                break;
+            case Ottavia._8va:
+                noteValue -= 12;
+                break;
+            case Ottavia._8vb:
+                noteValue += 12;
+                break;
+            case Ottavia._15mb:
+                noteValue += 24;
+                break;
+        }
+
+        const spelling = ModelUtils.resolveSpelling(bar.keySignature, noteValue, NoteAccidentalMode.Default);
+        return AccidentalHelper.calculateNoteSteps(bar.clef, spelling);
+    }
+
     public getNoteSteps(n: Note): number {
         return this._appliedScoreSteps.get(n.id)!;
     }