Skip to content

feat(rendering): place hammer-on, pull-off and slide labels above the staff and improve effect annotation spacing - #2945

Merged
Danielku15 merged 14 commits into
developfrom
feat/effect-slur-labels-band
Oct 9, 2026
Merged

Danielku15 merged 14 commits into
developfrom
feat/effect-slur-labels-band

Conversation

@Danielku15

Copy link
Copy Markdown
Member

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

Fixes #2944

Proposed changes

H / P / sl. labels as effect bands above the staff

The labels were painted on the slur arcs, which put them below the tab staff for lower arcs, lost labels when a
chord mixed kinds and showed a label per arc. Like Guitar Pro and MuseScore they are now annotations above the
staff for standard notation, tab and numbered notation:

  • One effect band per kind (hammer-on/pull-off, legato slide), both built from the same implementation. The
    existing EffectHammerOnPullOffText / EffectSlideText notation elements keep controlling their visibility.
  • One label per beat for all notes of the chord, centered between the beats of the segment. Different texts of
    one kind (H on one string, P on another) and different kinds ("sl." above "H") are stacked with the usual band
    padding.
  • Segments crossing a bar line are centered across it. Segments crossing a system break are labeled on the first
    system, centered up to the system end; the continuation gets no label.
  • Labels are derived from the model (each note now knows the slur segment starting at it), not from the arc
    glyphs. The label code of the tie/slur glyphs is removed, which also stops regular slurs from showing effect
    labels.

Effect band placement and spacing

  • A bar now reserves its own content plus the bands placed on it, taken from their final position. Before, the
    reserved height was derived from the skyline growth during placement, which also contained content of other
    bars (ties, brackets) and missed content registered only as overflow. Bands could be cut at the top of a
    system or leave too much space (e.g. sustain pedal markings). The height is now rounded once instead of twice,
    which moves many references by 1–2px.
  • Note-attached markers (labels, tap, pick stroke, harmonics, fingering, …) are placed glyph by glyph instead of
    as one block per bar, so markers of different effects can share a row in the gaps between each other. All
    glyphs of a band still share one height.
  • A glyph can keep a wider range clear than it occupies: labels keep their whole segment clear (so they stay above
    fret numbers and noteheads of the segment), markers attached to a beat keep the noteheads and stems of their
    own beat clear (e.g. a pick stroke above the stem of its note).
  • The minimum padding between the content of adjacent staves also considers content horizontally closer than
    ½ stave-space (Behind Bars), not only content at the same x position.
  • Jump direction texts (Fine, To Coda, …) are drawn from the top like other text effects; centered on the font's
    middle line their ink reached above the reserved space.

Known limitations (not addressed here)

  • Text effects report the advance width of their text as bounding box, not the ink. With the horizontal staff
    padding this occasionally adds a stave-space where the ink of two annotations is just far enough apart.
  • In the horizontal layout, a label centered exactly on a partial boundary is cut, like the slur arcs already are.

Tests

  • New visual tests for effect slur labels on chords and in multi-voice bars, across bar lines and across system
    breaks.
  • Reference images updated for the label placement and the spacing changes.
  • C# and Kotlin ports build, the C# test suite passes.

Checklist

  • I consent that this change becomes part of alphaTab under its current or any future open source license
  • This PR is linked to an accepted issue (see above)
  • Changes are implemented
  • New tests were added
  • I have read AGENTS.md if an AI helped draft any part of this PR

AI authorship disclosure

  • No AI agent authored any part of this PR (description, code, tests, or commit messages)
  • An AI agent contributed to this PR. The AI-authored disclosure block
    (alphatab-ai-authored-v1) is present at the top of this body, and I have
    personally reviewed every change and can explain each one

Further details

  • This is a breaking change
  • This change will require update of the documentation/website

…staff

The H/P/sl. labels were painted on the slur arcs, which put them below or
inside the staff for lower arcs, lost labels of other notes in a chord and
even showed effect labels on regular slurs. Like Guitar Pro and MuseScore the
labels are now effect bands above the staff (standard notation, tab and
numbered): one label per beat for all notes of a chord, centered between the
beats of the segment (or up to the system end when the effect continues on
the next system), with slide labels stacked above hammer-on/pull-off labels.
The height the effect bands add to a bar's overflow was the growth of the
staff skyline in the bar's range during placement. The skyline before
placement also holds content of other bars reaching into the bar (ties,
brackets) and misses content registered as overflow only, so the reserved
height was too small (bands cut at the top of the system) or too large
(extra space between staves). The bands now reserve what they need from
their final position relative to the bar's own content overflow.
Only vertical spacing drift: identical content, every gap changed by at most
2px (the reserved band height is now rounded once instead of twice).
Different texts of one label kind (H on one string, P on another) were joined
side by side; they are now stacked, the label of the higher note on top. The
end of a segment starting on a grace note was not found, because grace notes
share the display start of their main note.
Bands were placed with the union of all their glyphs in a bar, so markers of
another effect could never use the gaps between them (e.g. a slide label
between hammer-on/pull-off labels, or a tap marker next to them). Note-attached
bands now place each glyph on its own range, all glyphs of a band still share
one height. A glyph can keep a wider range clear than it occupies: the slur
labels keep their whole segment clear, so they stay above fret numbers and
noteheads of the segment while other markers can still sit next to them.
…t effects

The text was centered on the font's middle line at half its measured (ink)
height. For texts without descenders (Fine, To Coda) the ink then reached above
the glyph and was cut at the top of the system.
Placing note-attached markers glyph by glyph and checking the content of
adjacent staves only compared the skylines at the same x positions, so content
right next to each other could touch (pick strokes next to stems, fingering
numbers next to stems of the staff above). The clearance range of placed
markers and the staff content padding check are widened by their padding.
Widening the staff content check by the full vertical staff padding treated
content up to a stave-space next to each other as stacked and added space where
none is needed. Horizontally the half stave-space minimum distance between
characters (beat content padding, Behind Bars) is used instead.
…kers horizontally

Widening the clearance range of every note-attached marker by the band padding
moved markers like bar numbers up for content nearby that they do not belong
to. Markers attached to a beat now keep the noteheads and stems of their own
beat clear (e.g. a pick stroke above the stem of its note); markers placed per
bar are not widened.
@Danielku15 Danielku15 self-assigned this Oct 9, 2026
@Danielku15
Danielku15 merged commit 82f6d37 into develop Oct 9, 2026
6 checks passed
@Danielku15
Danielku15 deleted the feat/effect-slur-labels-band branch October 9, 2026 15:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve placement and spacing of effect annotations (hammer-on/pull-off/slide labels, effect bands)

1 participant