feat(engraving): add configurable rest position settings

[roscopeeco]

Issues

#2572

Fixes #

Proposed changes

Adds restPositionMain and restPositionSecondary properties to EngravingSettings, allowing the vertical position of rests to be overridden per-voice via the RestPosition enum.

The RestPosition enum provides named staff-line positions (Line1-Line5 and the spaces between) calibrated to a 5-line staff. Positions are adjusted automatically for staves with fewer than 5 lines using the formula override - (5 - lineCount) * 2.

When either property is null (the default), rest positioning falls back to the existing auto-calculated behaviour so there is no change to existing scores.

These changes are purely to the typescript source code.

Checklist

• [x ] I consent that this change becomes part of alphaTab under it's current or any future open source license
• Changes are implemented
• New tests were added
  I've tested it using creating a restPositionMain setting in the playground/demo/control app (this was not included in the pr). The test just dealt with a 5 line staff case. If you are happy with the content of the changes but need test i can investigate your test suite to see how they should be applied.

Further details

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

[roscopeeco]

I'm thinking we could make this more granular and add per track settings for restPositionMain and restPositionSecondary.

This would be done on a per track basis in the score...something like track.settings.restPositionMain etc.

[roscopeeco]

Just added a set of tests. There is one pre-existing issue that the second test shows. The image rest-position-default-multi-voice.png highlights the issue.

The test doesn't apply any settings but in the image the secondary voice rest on bars 3 & 6 is above the staff

[Danielku15]

I had a look at the code and the base already looks quite good. The biggest design contradiction currently is in where to configure rest positions. Looking at MusicXML the position of rests can be overridden for every rest individually via display-step and display-octave This is the approach I'd like to support in alphaTab.

1. On Beat level we should hold the pitch where rests should be displayed
2. During rest placement we compute the staff line on which the respective pitch is.

Having a "primary/secondary" displacement like you propose it, is still possible via a rewrite pass in the scoreLoaded event. But having it in the model allows also individual displacement.

Importer wise we should then support:

• For MusicXML we should support the display- tags to fill the overrides
• For alphaTex we should add a beat metadata tag to allow overriding

You can try to make an overall implementation if you like. Otherwise if you take care of the base (model + rendering) I can take over the importer support.