1 \input texinfo @c -*-texinfo-*-
2 @setfilename internals.info
3 @settitle LilyPond internals
5 @node Top, LilyPond internals, (dir), (dir)
10 * LilyPond internals::
24 @node LilyPond internals, , Top, Top
28 * Request_engraver:: Request_engraver
42 * Straightforward extensions
48 @chapter LilyPond internals
51 This documents some aspects of the internals of GNU LilyPond. Some of
52 this stuff comes from e-mail I wrote, some from e-mail others wrote,
53 some are large comments taken away from the headers. This page may be
54 a little incoherent. Unfortunately, it is also quite outdated. A
55 more thorough and understandable document is in the works.
57 You should use @code{doc++} to take a peek at the sources.
59 @node Overview, mudela, Top, Top
62 GNU LilyPond is a "multi-pass" system. The different passes have been
63 created so that they do not depend on each other. In a later stage
64 some parts may be moved into libraries, or seperate programs, or they
65 might be integrated in larger systems.
71 No difficult algorithms. The .ly file is read, and converted to a list
72 of @code{Scores}, which each contain @code{Music} and paper/midi-definitions.
74 @item Interpreting music
76 The music is walked through in time-order. The iterators which do the
77 walking report Music to Translators which use this information to
78 create elements, either MIDI or "visual" elements. The translators
79 form a hierarchy; the ones for paper output are Engravers, for MIDI
82 The translators swallow Music (mostly atomic gobs called Requests),
83 create elements, broadcast them to other translators on higher or same
84 level in the hierarchy:
86 The stem of a voice A is broadcast to the staff which contains A, but
87 not to the stems, beams and noteheads of a different voice (say B) or
88 a different staff. The stem and noteheads of A are coupled, because
89 the the Note_heads_engraver broadcasts its heads, and the Stem_engraver catches
92 The engraver which agrees to handle a request decides whether to to
93 honor the request, ignore it, or merge it with other requests. Merging
94 of requests is preferably done with other requests done by members of
95 the same voicegroups (beams, brackets, stems). In this way you can put
96 the voices of 2 instruments in a conductor's score so they make chords
97 (the Beam requests of both instruments will be merged).
101 Breakable stuff (eg. clefs and bars) are copied into pre and
106 Some dependencies are resolved, such as the direction of stems, beams,
107 and "horizontal" placement issues (the order of clefs, keys etc,
108 placement of chords in multi-voice music),
110 @item Break calculation:
112 The lines and horizontal positions of the columns are determined.
116 Through some magical interactions with Line_of_score and Super_elem
117 (check out the source) the "lines" are produced.
119 All other spanners can figure across which lines they are spread. If
120 applicable, they break themselves into pieces. After this, each piece
121 (or, if there are no pieces, the original spanner itself) throws out
122 any dependencies which are in the wrong line.
126 Some items and all spanners need computation after the Paper_column
127 positions are determined. Examples: slurs, vertical positions of
134 @node mudela, Request_engraver, Overview, Top
137 Most information is stored in the form of a request. In music
138 typesetting, the user might want to cram a lot more symbols on the
139 paper than actually fits. To reflect this idea (the user asks more
140 than we can do), the container for this data is called Request.
142 In a lot of other formats this would be called an 'Event'
145 @item @code{Barcheck_req}
146 Checks during music processing if start of this voice element
147 coincides with the start of a measure. Handy to check if you left out
149 @item @code{Note_req}
150 LilyPond has to decide if the ball should be hanging left or
151 right. This influences the horizontal dimensions of a column, and this
152 is why request processing should be done before horizontal spacing.
153 Other voices' frivolities may cause the need for accidentals, so this
154 is also for the to decide. The engraver can decide on positioning based on
155 ottava commands and the appropriate clef.
156 @item @code{Rest_req}
158 @item @code{Span_req}
159 This type of request typically results in the creation of a @code{Spanner}
160 @item @code{Beam_req}
162 Engraver has to combine this request with the stem_request, since the
163 number of flags that a stem wants to carry will determine the
166 Each dynamic is bound to one note (a crescendo spanning multiple
167 notes is thought to be made of two "dynamics": a start and a stop).
168 Dynamic changes can occur in a smaller time than the length of its
169 note, therefore fore each @code{Dynamic} request carries a time, measured
170 from the start of its note.
173 @node Request_engraver, , mudela, Top
174 @section Request_engraver
176 In the previous section the idea of Request has been explained, but
177 this only solves one half of the problem. The other half is deciding
178 which requests should be honored, which should merged with other
179 requests, and which should be ignored. Consider this input
183 \type Staff < % chord
184 @{ \meter 2/4; [c8 c8] @}
185 @{\meter 2/4; [e8 e8] @}
190 Both the cs and es are part of a staff (they are in the same
191 Voice_group), so they should share meters, but the two [ ] pairs
194 The judge in this "allocation" problem a set of brokers: the requests
195 are transmitted to so-called engravers which respond if they want to
196 accept a request eg, the @code{Notehead_engraver} will accept
197 @code{Note_req}s, and turn down @code{Slur_req}s. If the Music_iterator
198 cannot find a engraver that wants the request, it is junked (with a
201 After all requests have been either assigned, or junked, the Engraver
202 will process the requests (which usually means creating an @code{Item}
203 or @code{Spanner}). If a @code{Request_engraver} creates something, it
204 tells the enclosing context. If all items/spanners have been created,
205 then each Engraver is notified of any created Score_element, via a
208 @unnumberedsubsec example:
220 Note_request (duration 1/4)
221 Stem_request (duration 1/4)
225 Note_request will be taken by a @code{Notehead_engraver}, stem_request
226 will be taken by a @code{Stem_beam_engraver}. @code{Notehead_engraver}
227 creates a @code{Notehead}, @code{Stem_beam_engraver} creates a
228 @code{Stem}. Both announce this to the Staff_engraver. Staff_engraver
229 will tell @code{Stem_beam_engraver} about the @code{Notehead}, which
230 will add the @code{Notehead} to the @code{Stem} it just created.
232 To decide on merging, several engravers have been grouped. Please
233 check @file{init/engraver.ly}.
237 @node Graphic elements, , , Top
238 @section Graphic elements
241 Music notation is composed of a sets of interrelated glyphs. In
242 Lilypond every glyph usually is represented by one object, a so-called
243 Graphic Object. The primary relations between graphic objects involve
247 @item consecutive notes are printed left to right, grouped in a staff
248 @item simultaneous notes are horizontally aligned (internally grouped in
250 @item the staccato mark is horizontally centered on the note it applies
254 The abstract encoding of such relations is done with the concept
255 @dfn{reference point}. The reference point (in X direction) of the
256 staccato mark is the note it applies to. The (X) position of the
257 staccato mark is stored relative to the position of the note head. This
258 means that the staccato will always maintain a fixed offset wrt to the
259 note head, whereever the head is moved to.
261 In the same vein, all notes on a staff have their Y positions stored
262 relative to an abstract object called Axis_group_spanner. If the
263 Axis_group_spanner of one staff is moved, the absolute Y positions of
264 all objects in that spanner change along, in effect causing the staff
265 and all its contents to move as a whole.
267 Each graphic object stores a pointer and an relative offset for each
268 direction: one for the X-axis, one for the Y-axis. For example, the X
269 parent of a Note_head usually is a Note_column. The X parent of a
270 Note_column usually is either a Collision or a Paper_column. The X
271 parent of a Collision usually is a Paper_column. If the Collision
272 moves, all Note_heads that have that Collision as parent also move, but
273 the absolute position of the Paper_column does not change.
275 To build a graphical score with Graphic_elements, conceptually, one
276 needs to have one Root object (in Lilypond: Line_of_score), and
277 recursively attach objects to the Root. However, due to the nature
278 of the context selection mechanisms, it turns out to be more
279 advantageous to construct the tree the other way around: first small
280 trees (note heads, barlines etc.) are created, and these are
281 subsequently composed into larger trees, which are finally hung on a
282 Paper_column (in X direction) or Line_of_score (in Y direction).
284 The structure of the X,Y parent relations are determined by the
285 engravers and notation contexts:
287 The most important X-axis parent relation depends on the timing: notes
288 that come earlier are attached to Paper_column that will be positioned
291 The most important Y-axis relation depends on containment of contexts:
292 notes (created in a Thread or Voice context) are put in the staff where
293 the originating context lives in.
295 Graphical_axis_groups are special graphic objects, that are designed to
296 function as a parent. The size of a Graphical_axis_groups group is the
297 union of its children.
299 @node Score elements, , , Top
301 Besides relative positions there are lots of other relations between
302 elements. Lilypond does not contain other specialized relation
303 management (Like the relative positioning code). In stead, objects can
304 be connected through dependencies, which sets the order in which objects
307 Example: the direction of a beamed stem should equal the direction of
308 the beam. When the stem is a added to the beam, a dependency on the
309 beam is set in the stem: this means that @code{Beam::do_pre_processing
310 ()} (which does various direction related things) will be called before
311 @code{Stem::do_pre_processing ()}.
313 The code that manages dependencies resides in the class
314 @code{Score_element}, a derived class of @code{Graphical_element}. The
315 bulk of the code handles line breaking related issues.
317 To sketch the problems with line breaking: suppose a slur spans a line
321 c4( c'''' c | \break d d )d
324 In this case, the slur will appear as two parts, the first part spanning
325 the first three notes (the @code{c}s), the second spanning the last
326 three (the @code{d}s). Within Lilypond this is modeled as breaking the
327 slur in parts: from the Original slur, two new clones of the old slur
328 are made. Initially both clones depend on the six notes. After the
329 hairy code in Score_element, Spanner and Item which does substitutions
330 in sets of dependencies, the first clone depends on the first three
331 notes, the second on the last three.
333 The major derived classes of Score_element are Item and Spanner.
334 An item has one horizontal position. A spanner hangs on two items.
341 An item is a score element that is associated with only one
342 Paper_column. Examples are note heads, clefs, sup and superscripts, etc.
343 Item is a derived class of Score_element.
345 The shape of an item is known before the break calculations, and line
346 spacing depends on the size of items: very wide items need more space
347 than very small ones.
349 An additional complication is the behavior of items at linebreaks. For
350 example, when you do a time signature change, you get only one symbol.
351 If it occurs at a linebreak, the new time signature must be printed both
352 before and after the linebreak. Other `breakable symbols' such as
353 clefs, and bar lines also exhibit this behavior.
355 if a line of music is broken, the next line usually gets a clef. So in
356 TeX terms, the clef is a postbreak. The same thing happens with meter
357 signs: Normally the meter follows the bar. If a line is broken at that
358 bar, the bar along with the meter stays on the "last" line, but the next
359 line also gets a meter sign after the clef. To support this,
360 breakable items are generated in the three versions: original
361 (unbroken), left (before line break) and right (after line break).
362 During the line spacing, these versions are used to try how the spacing
365 Once the definitive spacing is determined, dependencies (and various
366 other pointers) are substituted such that all dependencies point at the
367 active items: either they point at the original, or they point at left
370 @node Spanners, , , Top
373 Spanners are symbols that are of variable shape, eg. Slurs, beams, etc.
374 Spanners is a derived class of Score_element.
376 The final shape can only be determined after the line breaking process.
377 All spanners are spanned on two items, called the left and right
378 boundary item. The X reference point is the left boundary item.
381 @node Future work, , , Top
384 There are plans to unify Spanner and Item, so there will no longer be
385 such a clear distinction between the two. Right now, Score_elements are
386 always either Item or either Spanner.
388 Most of the properties of a graphic object are now member variables of
389 the classes involved. To offer configurability, we want to move these
390 variables to scheme (GUILE) variables, and no longer use C++ code to
391 calculate them, but use Scheme functions.
393 @node Coding standards, , , Top
395 @chapter CodingStyle - standards while programming for GNU
398 Functions and methods do not return errorcodes.
401 @unnumberedsubsec Languages
403 C++ and Python are preferred. Perl is not. Python code should use an
404 indent of 8, using TAB characters.
406 @unnumberedsubsec Filenames
408 Definitions of classes that are only accessed via pointers
409 (*) or references (&) shall not be included as include files.
415 ".cc" Implementation files
416 ".icc" Inline definition files
417 ".tcc" non inline Template defs
423 (setq auto-mode-alist
424 (append '(("\\.make$" . makefile-mode)
425 ("\\.cc$" . c++-mode)
426 ("\\.icc$" . c++-mode)
427 ("\\.tcc$" . c++-mode)
428 ("\\.hh$" . c++-mode)
429 ("\\.pod$" . text-mode)
435 The class Class_name_abbreviation is coded in @file{class-name-abbr.*}
437 @unnumberedsubsec Indentation
439 Standard GNU coding style is used. In emacs:
442 (add-hook 'c++-mode-hook
443 '(lambda() (c-set-style "gnu")
448 If you like using font-lock, you can also add this to your @file{.emacs}:
451 (setq font-lock-maximum-decoration t)
452 (setq c++-font-lock-keywords-3
454 c++-font-lock-keywords-3
455 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
456 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
460 @unnumberedsubsec Classes and Types
466 @unnumberedsubsec Members
470 Type Class::member_type_
471 Type Class::member_type ()
474 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
476 @unnumberedsubsec Macros
478 Macros should be written completely in uppercase
480 The code should not be compilable if proper macro declarations are not
483 Don't laugh. It took us a whole evening/night to figure out one of
484 these bugs, because we had a macro that looked like
485 @code{DECLARE_VIRTUAL_FUNCTIONS ()}.
487 @unnumberedsubsec Broken code
489 Broken code (hardwired dependencies, hardwired constants, slow
490 algorithms and obvious limitations) should be marked as such: either
491 with a verbose TODO, or with a short "ugh" comment.
493 @unnumberedsubsec Comments
495 The source is commented in the DOC++ style. Check out doc++ at
496 @uref{http://www.zib.de/Visual/software/doc++/index.html}
501 C style comments for multiline comments.
502 They come before the thing to document.
508 Long class documentation.
511 TODO Fix boring_member ()
522 short memo. long doco of member ()
523 @@param description of arguments
526 Rettype member (Argtype);
530 data_member_ = 121; // ugh
537 Unfortunately most of the code isn't really documented that good.
539 @unnumberedsubsec Members (2)
545 ///check that *this satisfies its invariants, abort if not.
548 /// print *this (and substructures) to debugging log
552 protected member. Usually invoked by non-virtual XXXX ()
556 /**add some data to *this.
557 Presence of these methods usually imply that it is not feasible to this
562 /// replace some data of *this
567 @unnumberedsubsec Constructor
569 Every class should have a default constructor.
571 Don't use non-default constructors if this can be avoided:
579 is less readable than
592 Foo f(Foo_convert::int_to_foo (1))
596 @unnumberedsec Hungarian notation naming convention
598 Proposed is a naming convention derived from the so-called
599 @emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all
600 uppercase, with the parts of the names separated by underscores.
602 The hungarian notation is to be used when variables are not declared
603 near usage (mostly in member variables and functions).
605 @unnumberedsubsec Types
609 unsigned char. (The postfix _by is ambiguous)
623 Zero terminated c string
628 @unnumberedsubsec User defined types
636 Slur* slur_p = new Slur;
640 @unnumberedsubsec Modifiers
642 The following types modify the meaning of the prefix.
643 These are preceded by the prefixes:
651 const. Note that the proper order is @code{Type const}
652 i.s.o. @code{const Type}
654 A const pointer. This would be equivalent to @code{_c_l}, but since any
655 "const" pointer has to be a link (you can't delete a const pointer),
658 temporary pointer to object (link)
660 pointer to newed object
665 @unnumberedsubsec Adjective
667 Adjectives such as global and static should be spelled out in full.
668 They come before the noun that they refer to, just as in normal english.
672 foo_global_i: a global variable of type int commonly called "foo".
676 static class members do not need the static_ prefix in the name (the
677 Class::var notation usually makes it clear that it is static)
681 Variable loop: an integer
683 Temporary variable: an unsigned integer
685 Variable test: a character
686 @item @code{first_name_str}
687 Variable first_name: a String class object
688 @item @code{last_name_ch_a}
689 Variable last_name: a @code{char} array
691 Variable foo: an @code{Int*} that you must delete
693 Variable bar: an @code{Int*} that you must not delete
696 Generally default arguments are taboo, except for nil pointers.
698 The naming convention can be quite conveniently memorised, by
699 expressing the type in english, and abbreviating it
703 static Array<int*> foo
707 @code{foo} can be described as "the static int-pointer user-array", so you get
716 @unnumberedsec Miscellaneous
718 For some tasks, some scripts are supplied, notably creating patches, a
719 mirror of the website, generating the header to put over cc and hh
720 files, doing a release.
724 @node Making patches, , , Top
730 PATCHES - track and distribute your code changes
732 This page documents how to distribute your changes to GNU lilypond
734 We would like to have unified context diffs with full pathnames. A
735 script automating supplied with Lily.
737 Distributing a change normally goes like this:
740 @item make your fix/add your code
741 @item Add changes to CHANGES, and add yourself to Documentation/topdocs/AUTHORS.texi
742 @item generate a patch,
743 @item e-mail your patch to one of the mailing lists
744 gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
747 Please do not send entire files, even if the patch is bigger than the
748 original. A patch makes it clear what is changed, and it won't
749 overwrite previous (not yet released) changes.
751 @unnumberedsec Generating a patch
756 make -C lilypond-x.y.z/ distclean
757 make -C lilypond-x.y.z.NEW/ distclean
758 diff -urN lilypond-x.y.z/ lilypond-x.y.z.NEW/
761 Complicated (but automated) version:
763 In @file{VERSION}, set MY_PATCH_LEVEL:
773 In @file{CHANGES}, enter a summary of changes:
780 Then, from the top of Lily's source tree, type
786 These handy python scripts assume a directory structure which looks
791 lilypond -> lilypond-x.y.z # symlink to development directory
792 lilypond-x.y.z/ # current development
793 patches/ # patches between different releases
794 releases/ # .tar.gz releases
798 (Some scripts also assume this lives in @file{$HOME/usr/src}).
801 @unnumberedsec Applying patches
804 If you're following LilyPond development regularly, you probably want to
805 download just the patch for each subsequent release.
806 After downloading the patch (into the patches directory, of course), simply
811 gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
815 and don't forget to make automatically generated files:
819 autoconf footnote(patches don't include automatically generated files,
820 i.e. file(configure) and files generated by file(configure).)