From: Graham Percival Date: Tue, 20 Feb 2007 21:57:39 +0000 (-0800) Subject: Misc updates and first part of Trevor's Proportional rewrite. X-Git-Tag: release/2.11.20-1~16 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=04adc45f53726f63511be5c1ab20e32d9018ea10;p=lilypond.git Misc updates and first part of Trevor's Proportional rewrite. --- diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely index 777c92b44b..51911fe741 100644 --- a/Documentation/user/advanced-notation.itely +++ b/Documentation/user/advanced-notation.itely @@ -1828,7 +1828,7 @@ see those sections of the documentation. @menu * Polymetric notation:: * Time administration:: -* Proportional notation:: +* Proportional notation (introduction):: * Clusters:: * Special noteheads:: * Feathered beams:: @@ -2044,10 +2044,15 @@ note duration and @code{ly:make-moment 7 16} is the duration of seven sixteenths notes. -@node Proportional notation -@subsection Proportional notation +@node Proportional notation (introduction) +@subsection Proportional notation (introduction) @cindex Proportional notation +See @ref{Proportional notation}. + + +TODO: remove all this stuff? + Notes can be spaced proportionally to their time-difference by assigning a duration to @code{proportionalNotationDuration} diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely index 06ac1b5580..3e697e9a27 100644 --- a/Documentation/user/basic-notation.itely +++ b/Documentation/user/basic-notation.itely @@ -759,10 +759,12 @@ Program reference: @internalsref{TupletBracket}, You can alter the length of duration by a fraction @var{N/M} appending @samp{*@var{N/M}} (or @samp{*@var{N}} if @var{M=1}). This -will not affect the appearance of the notes or rests produced. +will not affect the appearance of the notes or rests produced. These +may be combined such as @samp{*M*N}. In the following example, the first three notes take up exactly two beats, but no triplet bracket is printed. + @lilypond[quote,ragged-right,fragment,relative=2,verbatim] \time 2/4 a4*2/3 gis4*2/3 a4*2/3 diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely index 629750b815..cdf3845dd0 100644 --- a/Documentation/user/spacing.itely +++ b/Documentation/user/spacing.itely @@ -31,11 +31,10 @@ or stretched. @menu * Paper and pages:: * Music layout:: +* Displaying spacing:: * Breaks:: * Vertical spacing:: * Horizontal spacing:: -* Displaying spacing:: -* Vertical collision avoidance:: @end menu @@ -471,6 +470,37 @@ layout. This manual: @ref{Changing context default settings} +@node Displaying spacing +@section Displaying spacing + +@funindex annotate-spacing +@cindex Spacing, display of properties + +To graphically display the dimensions of vertical properties that may +be altered for page formatting, set @code{annotate-spacing} in the +@code{\paper} block, like this + + +@lilypond[verbatim] +#(set-default-paper-size "a6" 'landscape) + +\book { + \score { { c4 } } + \paper { annotate-spacing = ##t } +} +@end lilypond + +@c need to have \book{} otherwise we get the separate systems. -hwn + +@noindent +@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp +Some unit dimensions are measured in staff spaces, while others +are measured in millimeters. +The pairs +(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and +@var{b} the upper edge of the interval. + + @node Breaks @section Breaks @@ -812,6 +842,7 @@ staves inside a system. * Vertical spacing between systems:: * Explicit staff and system positioning:: * Two-pass vertical spacing:: +* Vertical collision avoidance:: @end menu @@ -1136,6 +1167,83 @@ lilypond -dbackend=null -d dump-tweaks .ly lilypond .ly @end example + +@node Vertical collision avoidance +@subsection Vertical collision avoidance + +@funindex outside-staff-priority +@funindex outside-staff-padding +@funindex outside-staff-horizontal-padding + +Intuitively, there are some objects in musical notation that belong +to the staff and there are other objects that should be placed outside +the staff. Objects belonging outside the staff include things such as +rehearsal marks, text and dynamic markings (from now on, these will +be called outside-staff objects). LilyPond's rule for the +vertical placement of outside-staff objects is to place them as close +to the staff as possible but not so close that they collide with +another object. + +LilyPond uses the @code{outside-staff-priority} property to determine +whether a grob is an outside-staff object: if @code{outside-staff-priority} +is a number, the grob is an outside-staff object. In addition, +@code{outside-staff-priority} tells LilyPond in which order the objects +should be placed. + +First, LilyPond places all the objects that do not belong outside +the staff. Then it sorts the outside-staff objects according to their +@code{outside-staff-priority} (in increasing order). One by one, LilyPond +takes the outside-staff objects and places them so that they do +not collide with any objects that have already been placed. That +is, if two outside-staff grobs are competing for the same space, the one +with the lower @code{outside-staff-priority} will be placed closer to +the staff. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +c4_"Text"\pp +r2. +\once \override TextScript #'outside-staff-priority = #1 +c4_"Text"\pp % this time the text will be closer to the staff +r2. +% by setting outside-staff-priority to a non-number, we +% disable the automatic collision avoidance +\once \override TextScript #'outside-staff-priority = ##f +\once \override DynamicLineSpanner #'outside-staff-priority = ##f +c4_"Text"\pp % now they will collide +@end lilypond + +The vertical padding between an outside-staff object and the +previously-positioned grobs can be controlled with +@code{outside-staff-padding}. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +\once \override TextScript #'outside-staff-padding = #0 +a'^"This text is placed very close to the note" +\once \override TextScript #'outside-staff-padding = #3 +c^"This text is padded away from the previous text" +c^"This text is placed close to the previous text" +@end lilypond + +By default, outside-staff objects are placed without regard to +their horizontal distance from the previously-posititioned grobs. This +can lead to situations in which objects are placed very close to each +other horizontally. Setting @code{outside-staff-horizontal-padding} +causes an object to be offset vertically so that such a situation +doesn't occur. + +@lilypond[quote,ragged-right,relative=2,fragment,verbatim] +% the markup is too close to the following note +c2^"Text" +c''2 +% setting outside-staff-horizontal-padding fixes this +R1 +\once \override TextScript #'outside-staff-horizontal-padding = #1 +c,,2^"Text" +c''2 +@end lilypond + + + @node Horizontal spacing @section Horizontal Spacing @@ -1147,6 +1255,7 @@ lilypond .ly * New spacing area:: * Changing horizontal spacing:: * Line length:: +* Proportional notation:: @end menu @@ -1407,107 +1516,238 @@ paragraph, the last line simply takes its natural horizontal length. @end example -@node Displaying spacing -@section Displaying spacing +@node Proportional notation +@subsection Proportional notation -@funindex annotate-spacing -@cindex Spacing, display of properties +LilyPond supports proportional notation, a type of horizontal spacing +in which each note consumes an amount of horizontal space exactly +equivalent to its rhythmic duration. This type of proportional spacing +is comparable to horizontal spacing on top of graph paper. Some late +20th- and early 21st-century scores use proportional notation to +clarify complex rhythmic relationships or to faciliate the placement +of timelines or other graphics directly in the score. -To graphically display the dimensions of vertical properties that may -be altered for page formatting, set @code{annotate-spacing} in the -@code{\paper} block, like this +LilyPond supports five different settings for proportional notation, +which may be used together or alone: +@itemize +proportionalNotationDuration +uniform-stretching +strict-note-spacing +\remove Separating_line_group_engraver +\override PaperColumn #'used = ##t +@end itemize -@lilypond[verbatim] -#(set-default-paper-size "a6" 'landscape) +In the examples that follow, we explore these five different +proportional notation settings and examine how these settings interact. -\book { - \score { { c4 } } - \paper { annotate-spacing = ##t } -} +We start with the following one-measure example, which uses classical +spacing with ragged-right turned on. + +@lilypond[quote,verbatim,ragged-right] +\new Score << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } +>> @end lilypond -@c need to have \book{} otherwise we get the separate systems. -hwn +Notice that the half note which begins the measure takes up far less +than half of the horizontal space of the measure. Likewise, the +sixteenth notes and sixteenth-note quintuplets (or twentieth notes) +which end the measure together take up far more than half the +horizontal space of the measure. -@noindent -@c FIXME: really bad vagueness due to bug in annotate-spacing. -gp -Some unit dimensions are measured in staff spaces, while others -are measured in millimeters. -The pairs -(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and -@var{b} the upper edge of the interval. +In classical engraving, this spacing may be exactly what we want +because we can borrow horizontal space from the half note and conserve +horizontal space across the measure as a whole. +On the other hand, if we want to insert a measured timeline or other +graphic above or below our score, we need proportional notation. We +turn proportional notation on with the proportionalNotationDuration +setting. -@node Vertical collision avoidance -@section Vertical collision avoidance +@lilypond[quote,verbatim,ragged-right] +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 20) +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } +>> +@end lilypond -@funindex outside-staff-priority -@funindex outside-staff-padding -@funindex outside-staff-horizontal-padding +The half note at the beginning of the measure and the faster notes in +the second half of the measure now occupy equal amounts of horizontal +space. We could place a measured timeline or graphic above or below +this example. + +The @code{proportionalNotationDuration} setting is a context setting that +lives in @context{Score}. Recall that context settings appear in one of +three locations in our input file -- in a @code{\with} block, in a +@code{\context} block, or directly in music entry +preceeded by the @code{\set} command. As with all +context settings, users can pick which of the three different +locations they would like to set @code{proportionalNotationDuration}. + +The @code{proportionalNotationDuration} setting takes a single argument, +which is the reference duration against which all music will be +spaced. The LilyPond Scheme function make-moment takes two arguments +-- a numerator and denominator which together express some fraction of +a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces a +reference duration of a twentieth note. The values +@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and +@code{#(ly:make-moment 3 97)} are all possible as well. + +How do we select the right reference duration to pass to +@code{proportionalNotationDuration}? Usually by a process of trial and error, +beginning with a duration close to the fastest (or smallest) duration +in the piece. Smaller reference durations space music loosely; larger +reference durations space music tightly. + +@lilypond[quote,verbatim,ragged-right] +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 8) +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } +>> -Intuitively, there are some objects in musical notation that belong -to the staff and there are other objects that should be placed outside -the staff. Objects belonging outside the staff include things such as -rehearsal marks, text and dynamic markings (from now on, these will -be called outside-staff objects). LilyPond's rule for the -vertical placement of outside-staff objects is to place them as close -to the staff as possible but not so close that they collide with -another object. +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 16) +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } +>> -LilyPond uses the @code{outside-staff-priority} property to determine -whether a grob is an outside-staff object: if @code{outside-staff-priority} -is a number, the grob is an outside-staff object. In addition, -@code{outside-staff-priority} tells LilyPond in which order the objects -should be placed. +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 32) +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } +>> +@end lilypond -First, LilyPond places all the objects that do not belong outside -the staff. Then it sorts the outside-staff objects according to their -@code{outside-staff-priority} (in increasing order). One by one, LilyPond -takes the outside-staff objects and places them so that they do -not collide with any objects that have already been placed. That -is, if two outside-staff grobs are competing for the same space, the one -with the lower @code{outside-staff-priority} will be placed closer to -the staff. +Note that too large a reference duration -- such as the eighth note, +above -- spaces music too tightly and can cause notehead collisions. +Note also that proportional notation in general takes up more +horizontal space that does classical spacing. Proportional spacing +provides rhythmic clarity at the expense of horizontal space. -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -c4_"Text"\pp -r2. -\once \override TextScript #'outside-staff-priority = #1 -c4_"Text"\pp % this time the text will be closer to the staff -r2. -% by setting outside-staff-priority to a non-number, we -% disable the automatic collision avoidance -\once \override TextScript #'outside-staff-priority = ##f -\once \override DynamicLineSpanner #'outside-staff-priority = ##f -c4_"Text"\pp % now they will collide +Next we examine how to optimally space overlapping tuplets. + +We start by examining what happens to our original example, with +classical spacing, when we add a second staff with a different type of +tuplet. + +@lilypond[quote,verbatim,ragged-right] +\new Score << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } + \new RhythmicStaff { + \times 8/9 { + c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 + } + } +>> @end lilypond -The vertical padding between an outside-staff object and the -previously-positioned grobs can be controlled with -@code{outside-staff-padding}. +The spacing is bad because the evenly notes of the bottom staff do not +stretch uniformly. Classical engraving includes very few complex +triplets and so classical engraving rules can generate this type of +result. Setting @code{proportionalNotationDuration} remedies this +situation considerably. -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -\once \override TextScript #'outside-staff-padding = #0 -a'^"This text is placed very close to the note" -\once \override TextScript #'outside-staff-padding = #3 -c^"This text is padded away from the previous text" -c^"This text is placed close to the previous text" +@lilypond[quote,verbatim,ragged-right] +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 20) +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } + \new RhythmicStaff { + \times 8/9 { + c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 + } + } +>> @end lilypond -By default, outside-staff objects are placed without regard to -their horizontal distance from the previously-posititioned grobs. This -can lead to situations in which objects are placed very close to each -other horizontally. Setting @code{outside-staff-horizontal-padding} -causes an object to be offset vertically so that such a situation -doesn't occur. +But if we look very carefully we can see that notes of the second half +of the 9-tuplet space ever so slightly more widely than do the notes +of the first half of the 9-tuplet. To ensure uniform stretching, we +turn on @code{uniform-stretching}, which is a property of +@code{SpacingSpanner}. -@lilypond[quote,ragged-right,relative=2,fragment,verbatim] -% the markup is too close to the following note -c2^"Text" -c''2 -% setting outside-staff-horizontal-padding fixes this -R1 -\once \override TextScript #'outside-staff-horizontal-padding = #1 -c,,2^"Text" -c''2 +@lilypond[quote,verbatim,ragged-right] +\new Score \with { + proportionalNotationDuration = #(ly:make-moment 1 20) + \override SpacingSpanner #'uniform-stretching = ##t +} << + \new RhythmicStaff { + c'2 + c'16 c'16 c'16 c'16 + \times 4/5 { + c'16 c'16 c'16 c'16 c'16 + } + } + \new RhythmicStaff { + \times 8/9 { + c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 + } + } +>> @end lilypond + +Our two-staff example now spaces exactly, our rhythmic relationships +are visually clear, and we can include a measured timeline or graphic +if we want. + +The @code{SpacingSpanner} is an abstract grob that lives in the +@context{Score} context. As with our settings of +@code{proportionalNotationDuration}, +overrides to the @code{SpacingSpanner} can occur in any of three different +places in our input file -- in the Score @code{\with} block, in a +Score @code{\context} block, or in note entry directly. + +There is by default only one @code{SpacingSpanner} per @code{Score}. This +means that, by default, @code{uniform-stretching} is either turned on for the +entire score or turned off for the entire score. We can, however, +override this behavior and turn on different spacing features at +different places in the score. We do this with the command +@code{\newSpacingSection}. See @ref{New spacing area} for more info. + +@c zzz +