2 mensural-ligature-engraver.cc -- implement Mensural_ligature_engraver
4 source file of the GNU LilyPond music typesetter
6 (c) 2002--2004 Juergen Reuter <reuter@ipd.uka.de>
9 #include "mensural-ligature.hh"
10 #include "coherent-ligature-engraver.hh"
16 #include "paper-column.hh"
17 #include "note-column.hh"
18 #include "rhythmic-head.hh"
19 #include "note-head.hh"
20 #include "staff-symbol-referencer.hh"
21 #include "output-def.hh"
22 #include "font-interface.hh"
25 * TODO: My resources on Franco of Cologne's rules claim that his
26 * rules map ligature<->mensural timing in a non-ambigous way, but in
27 * fact, as presented in these resources, the rules become ambigous as
28 * soon as there appear durations other than breves within a ligature
29 * with more than two heads (ligatura ternaria etc.). Hence, the
30 * below implementation is an approximation of what I think the rules
31 * could look like if forced to be non-ambigous. This should be
32 * further investigated.
34 * TODO: The automat is quite complicated, and its design is error
35 * prone (and most probably, it behaves wrong for some very special
36 * cases). Maybe we can find a better paradigm for modelling Franco
39 * TODO: dotted heads: when applying Franco of Cologne's mapping, put
40 * dots *above* (rather than after) affected ligature heads.
42 * TODO: prohibit multiple voices within a ligature.
44 * TODO: enhance robustness: in case of an illegal ligature (e.g. the
45 * user events for a ligature that contains a minima or STATE_ERROR
46 * is reached), automatically break the ligature into smaller, valid
49 class Mensural_ligature_engraver : public Coherent_ligature_engraver
53 virtual Spanner *create_ligature_spanner ();
54 virtual void build_ligature (Spanner *ligature, Array<Grob_info> primitives);
57 TRANSLATOR_DECLARATIONS (Mensural_ligature_engraver);
60 int apply_transition (Array<Grob_info> primitives,
61 int state, int input, int i);
62 void transform_heads (Array<Grob_info> primitives);
63 void propagate_properties (Spanner *ligature, Array<Grob_info> primitives);
64 void fold_up_primitives (Array<Grob_info> primitives);
65 void join_primitives (Array<Grob_info> primitives);
69 Mensural_ligature_engraver::Mensural_ligature_engraver ()
74 Mensural_ligature_engraver::create_ligature_spanner ()
76 return make_spanner ("MensuralLigature", SCM_EOL);
80 * The following lines implement a finite state automat. Given a
81 * sequence of durations (Longa, Brevis, Semibrevis) or
82 * end-of-ligature-event as input, the automat outputs a sequence of
83 * events for grobs that form a proper ligature.
87 * This enumeration represents the set of possible input values to the
88 * automat. There may (potentially) be any sequence of Longa, Brevis,
89 * and Semibrevis duration symbols fed into the automat, with a final
90 * EndOfLigature symbol to terminate the ligature. Other durations
91 * are explicitly prohibited. Depending on the note's pitch of the
92 * preceding and the current input, the melodic line may be ascending
93 * or descending. Per definition, the melodic line must either ascend
94 * or descend, because if the pitches were twice the same, the two
95 * notes would be merged into a single one (as long as not resulting
96 * in a prohibited duration). In the case of the EndOfLigature
97 * symbol, the melodic line is undefined (but we still have ascending
98 * and descending case for the sake of consistency, making the automat
103 // Ascending/Descending Longa/Brevis/Semibrevis/EndOfLigature
115 * This enumeration represents all possible internal states of the
116 * automat. Besides the generic states START, ERROR, and END, the
117 * remaining states L, B, S, and SS describe pending values from the
118 * sequence of input values that have not yet been transformed to
119 * proper output values, including the melodic direction
120 * (ascending/descending) for state L.
124 // aL = ascending Longa, dL descending Longa, B = Brevis, S =
125 // Semibrevis, SS = 2 Semibreves
137 * The following array represents the transitions of the automat:
138 * given some state and input, it maps to a new state, according (with
139 * the limitations as described above) to the rules of Franco of
142 const int/*new state*/ transition_state[/*old state*/][8/*input*/] =
144 {STATE_aL, STATE_dL, STATE_B, STATE_B,
145 STATE_S, STATE_S, STATE_ERROR, STATE_ERROR}, // was: STATE_START
146 {STATE_aL, STATE_dL, STATE_B, STATE_START,
147 STATE_ERROR, STATE_ERROR, STATE_END, STATE_END}, // was: STATE_aL
148 {STATE_aL, STATE_dL, STATE_B, STATE_START,
149 STATE_ERROR, STATE_ERROR, STATE_END, STATE_END}, // was: STATE_dL
150 {STATE_aL, STATE_dL, STATE_B, STATE_START,
151 STATE_ERROR, STATE_ERROR, STATE_END, STATE_END}, // was: STATE_B
152 {STATE_ERROR, STATE_ERROR, STATE_ERROR, STATE_ERROR,
153 STATE_SS, STATE_SS, STATE_ERROR, STATE_ERROR}, // was: STATE_S
154 {STATE_aL, STATE_dL, STATE_B, STATE_B,
155 STATE_S, STATE_S, STATE_END, STATE_END}, // was: STATE_SS
156 {STATE_ERROR, STATE_ERROR, STATE_ERROR, STATE_ERROR,
157 STATE_ERROR, STATE_ERROR, STATE_ERROR, STATE_ERROR}, // was: STATE_ERROR
158 {STATE_ERROR, STATE_ERROR, STATE_ERROR, STATE_ERROR,
159 STATE_ERROR, STATE_ERROR, STATE_ERROR, STATE_ERROR}, // was: STATE_END
163 * The following array represents the output of the automat while
164 * switching from one state to another: given some state and input, it
165 * maps to the output produced when switching to the next state,
166 * according (with the limitations as described above) to the rules of
169 const int/*output*/ transition_output[/*old state*/][8/*input*/] =
171 {MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE,
172 MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE}, // was: STATE_START
173 {MLP_sc, MLP_ss, MLP_sc, MLP_LB,
174 MLP_NONE, MLP_NONE, MLP_sc, MLP_sc}, // was: STATE_aL
175 {MLP_sc, MLP_ss, MLP_sc, MLP_LB,
176 MLP_NONE, MLP_NONE, MLP_ss, MLP_ss}, // was: STATE_dL
177 {MLP_ss, MLP_cs, MLP_ss, MLP_BB,
178 MLP_NONE, MLP_NONE, MLP_ss, MLP_ss} , // was: STATE_B
179 {MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE,
180 MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE}, // was: STATE_S
181 {MLP_SS, MLP_SS, MLP_SS, MLP_SS,
182 MLP_SS, MLP_SS, MLP_SS, MLP_SS} , // was: STATE_SS
183 {MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE,
184 MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE}, // was: STATE_ERROR
185 {MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE,
186 MLP_NONE, MLP_NONE, MLP_NONE, MLP_NONE}, // was: STATE_END
190 Mensural_ligature_engraver::apply_transition (Array<Grob_info> primitives,
191 int state, int input, int i)
193 int output = transition_output[state][input];
194 Item *last_last_primitive = (i > 1) ?
195 dynamic_cast<Item*> (primitives[i-2].grob_) : 0;
196 Item *last_primitive = (i > 0) ?
197 dynamic_cast<Item*> (primitives[i-1].grob_) : 0;
198 Item *primitive = (i < primitives.size ()) ?
199 dynamic_cast<Item*> (primitives[i].grob_) : 0;
203 // skip note head, expecting a primitive with two note heads
208 // primitive with single note head
211 programming_error ("last_primitive undefined");
214 last_primitive->set_property ("primitive", scm_int2num (output));
218 // primitive with two note heads
221 programming_error ("last_primitive undefined");
226 programming_error ("primitive undefined");
229 last_primitive->set_property ("primitive", scm_int2num (output));
230 primitive->set_property ("primitive", scm_int2num (MLP_NONE));
233 // delayed primitive with two note heads
234 if (!last_last_primitive)
236 programming_error ("last_last_primitive undefined");
241 programming_error ("last_primitive undefined");
244 last_last_primitive->set_property ("primitive", scm_int2num (output));
245 last_primitive->set_property ("primitive", scm_int2num (MLP_NONE));
248 programming_error (_f ("unexpected case fall-through"));
251 return transition_state[state][input];
255 Mensural_ligature_engraver::transform_heads (Array<Grob_info> primitives)
257 if (primitives.size () < 2)
259 warning (_f ("ligature with less than 2 heads -> skipping"));
262 int state = STATE_START;
263 Pitch last_pitch, pitch;
264 bool have_last_pitch = 0, have_pitch = 0;
265 for (int i = 0; i < primitives.size (); i++) {
267 have_last_pitch = have_pitch;
268 Grob_info info = primitives[i];
270 Note_head::get_balltype (dynamic_cast<Item*> (info.grob_));
272 Music *nr = info.music_cause ();
275 ugh. why not simply check for pitch?
277 if (!nr->is_mus_type ("note-event"))
279 info.music_cause ()->origin ()->warning (_f ("can not determine pitch of ligature primitive -> skipping"));
287 pitch = *unsmob_pitch (nr->get_property ("pitch"));
293 if (!have_last_pitch)
295 delta_pitch = 0; // first pitch; delta undefined
299 delta_pitch = (pitch.steps () - last_pitch.steps ());
300 if (Pitch::compare (last_pitch, pitch) == 0)
302 info.music_cause ()->origin ()->warning (_f ("prime interval within ligature -> skipping"));
310 if ((duration_log < -2) || (duration_log > 0))
312 info.music_cause ()->origin ()->warning (_f ("mensural ligature: duration none of L, B, S -> skipping"));
319 int input = (duration_log + 2) * 2 + ((delta_pitch < 0) ? 1 : 0);
320 state = apply_transition (primitives, state, input, i);
321 // TODO: if (state == STATE_ERROR) { ... }
324 state = apply_transition (primitives, state, INPUT_AE, primitives.size ());
325 // TODO: if (state == STATE_ERROR) { ... }
329 * A MensuralLigature grob consists of a bunch of NoteHead grobs that
330 * are glued together. It (a) does not make sense to change
331 * properties like thickness or flexa-width from one head to the next
332 * within a ligature (this would totally screw up alignment), and (b)
333 * some of these properties (like flexa-width) are specific to
334 * e.g. the MensuralLigature (as in contrast to e.g. LigatureBracket),
335 * and therefore should not be handled in the NoteHead code (which is
336 * also used by LigatureBracket). Therefore, we let the user control
337 * these properties via the concrete Ligature grob (like
338 * MensuralLigature) and then copy these properties as necessary to
339 * each of the NoteHead grobs. This is what
340 * propagate_properties () does.
343 Mensural_ligature_engraver::propagate_properties (Spanner *ligature,
344 Array<Grob_info> primitives)
346 Real thickness = robust_scm2double (ligature->get_property ("thickness"), 1.4);
347 thickness *= ligature->get_paper ()->get_dimension (ly_symbol2scm ("linethickness"));
350 Font_interface::get_default_font (ligature)->
351 find_by_name ("noteheads--1mensural").extent (X_AXIS).length ();
352 Real flexa_width = robust_scm2double (ligature->get_property ("flexa-width"), 2);
353 flexa_width *= Staff_symbol_referencer::staff_space (ligature);
355 Real half_flexa_width = 0.5 * (flexa_width + thickness);
357 for (int i = 0; i < primitives.size (); i++)
359 Item *primitive = dynamic_cast<Item*> (primitives[i].grob_);
360 int output = ly_scm2int (primitive->get_property ("primitive"));
361 primitive->set_property ("thickness",
362 scm_make_real (thickness));
365 primitive->set_property ("head-width",
366 scm_make_real (half_flexa_width));
371 primitive->set_property ("head-width",
372 scm_make_real (head_width));
377 primitive->set_property ("head-width",
378 scm_make_real (half_flexa_width));
379 primitive->set_property ("flexa-width",
380 scm_make_real (flexa_width));
383 programming_error (_f ("unexpected case fall-through"));
390 Mensural_ligature_engraver::fold_up_primitives (Array<Grob_info> primitives)
394 for (int i = 0; i < primitives.size (); i++)
396 Item *current = dynamic_cast<Item*> (primitives[i].grob_);
402 get_set_column (current, first->get_column ());
406 current->translate_axis (distance, X_AXIS);
410 ly_scm2double (current->get_property ("head-width")) -
411 ly_scm2double (current->get_property ("thickness"));
416 Mensural_ligature_engraver::join_primitives (Array<Grob_info> primitives)
419 for (int i = 0; i < primitives.size (); i++)
421 Grob_info info = primitives[i];
422 Pitch pitch = *unsmob_pitch (info.music_cause ()->get_property ("pitch"));
425 Item *primitive = dynamic_cast<Item*> (info.grob_);
426 int output = ly_scm2int (primitive->get_property ("primitive"));
427 if (output & MLP_ANY)
429 int delta_pitch = (pitch.steps () - last_pitch.steps ());
430 primitive->set_property ("join-left-amount",
431 scm_int2num (delta_pitch));
439 Mensural_ligature_engraver::build_ligature (Spanner *ligature,
440 Array<Grob_info> primitives)
442 transform_heads (primitives);
443 propagate_properties (ligature, primitives);
444 fold_up_primitives (primitives);
445 join_primitives (primitives);
448 ENTER_DESCRIPTION (Mensural_ligature_engraver,
449 /* descr */ "Handles Mensural_ligature_events by glueing special ligature heads together.",
450 /* creats*/ "MensuralLigature",
451 /* accepts */ "ligature-event",
452 /* acks */ "note-head-interface rest-interface",