5 * Conversion stages:: Lilypond is a multi-pass program.
7 * Grobs:: Graphical object
11 * Molecules:: Molecules are stand-alone descriptions of output
12 * Font metrics:: Font metrics
15 @node Conversion stages
16 @section Conversion stages
18 When translating the input to notation, there are number of distinct
19 phases. We list them here:
25 The .ly file is read, and converted to a list of @code{Scores}, which
26 each contain @code{Music} and paper/midi-definitions.
28 @item Interpreting music
29 @cindex interpreting music
31 All music events are "read" in the same order as they would be played
32 (or read from paper). At every step of the interpretation, musical
33 events are delivered to
34 interpretation contexts,
36 which use them to build grobs (or MIDI objects, for MIDI output).
42 At places where line breaks may occur, clefs and bars are prepared for
43 a possible line break.
49 In this stage, all information that is needed to determine line breaking
52 @item Break calculation:
54 The lines and horizontal positions of the columns are determined.
58 Relations between all grobs are modified to reflect line breaks. See
59 also @ref{Pointer substitution}.
63 All vertical dimensions and spanning objects are computed, and all grobs
64 are output, line by line.
71 Moment is a rational number. Since GUILE doesn't support them natively,
72 so we created our own rational data type.
77 @defun make-moment num den
78 create the rational number @var{num}/@var{den}.
84 This section is about Grobs (short for Graphical Objects), which are
85 formatting objects used to create the final output. This material is
86 normally the domain of LilyPond gurus, but occasionally, a normal user
87 also has to deal with grobs.
89 The most simple interaction with Grobs are when you use
93 \property Voice.Stem \override #'direction = #1
96 This piece of lily input causes all stem objects to be stem-up
97 henceforth. In effect, you are telling lilypond to extend the defintion
98 of the "Stem" grob with the setting @code{direction := 1}. Of course
99 there are many more ways of customizing Lily output, and since most of
100 them involve Grobs in some form, this section explains some details of
106 * Setting grob properties::
107 * Items and Spanners::
108 * Pointer substitution::
109 * Grob Scheme functions::
112 @node What is a grob?
113 @subsection What is a grob?
115 In music notation, lots of symbols are related in some way. You can
116 think of music notation as a graph where nodes are formed by the
117 symbols, and the arcs by their relations. A grob is node in that
118 graph. A grob stores references to other grobs, the directed edges in
121 The objective of this big graph of grobs, is to specify the notation
122 problem. The solution of this problem is a description of the printout
123 that is in closed form, i.e. but a list of values. These values are
124 Molecules. (see @ref{Molecules})
126 All grobs have an X and Y-position on the page. These X and Y positions
127 are stored in a relative format, so they can easily be combined by
128 stacking them, hanging one grob to the side of another, and coupling
129 them into a grouping-grob.
131 Each grob has a reference point, or parent: the position of a grob is
132 stored relative to that reference point. For example the X-reference
133 point of a staccato dot usually is the note head that it applies
134 to. Whenever the note head is moved, the staccato dot moves along
137 If you keep following offset reference points, you will always end up at
138 the root-object. This root object is called @rgrob{Line_of_score}, and it
139 represents a system (ie. a line of music).
141 All grobs carry a set of grob-properties. In the Stem example above,
142 the property @code{direction} is set to value @code{1}. The function
143 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
144 @code{direction} to determine how to print the stem and the flag. The
145 appearance of a grob is determined solely by the values of its
148 Often, a grob also is associated with a symbol. On the other hand,
149 Some grobs do not print any symbols, but take care of grouping
150 objects. For example, there is a separate grob that stacks staffs
151 vertically, so they are not printed in overstrike. The
152 @rgrob{NoteCollision} is another example of an abstract grob. It only
153 moves around chords, but doesn't print anything.
155 A complete list of grob types is found in
156 @ref{(lilypond-internals)LilyPond backend}
158 Grobs are created in the "Interpreting music" phase, by things in
159 LilyPond called engravers. In this phase of the translation, a load of
160 grobs are created, and they are linked into a giant network of objects.
161 This network of grobs forms the "specification" of the print
162 problem. This problem is then solved: configurations, directions,
163 dimensions, line breaks, etc. are calculated. Finally, the printing
164 description in the form of Molecules (@ref{Molecules}) is extracted from
165 the network. These are then dumped into the output file
168 @subsection Callbacks
170 Offsets of grobs are relative to a parent reference point. Most
171 positions are not known when an object is created, so these are
172 calculated as needed. This is done by adding a callback for a specific
175 Suppose you have the following code in a .ly file.
177 #(define (my-callback gr axis)
178 (* 2.0 (get-gr-property grob 'direction))
183 \property Voice.Stem \override #'Y-offset-callbacks = #(list
187 When the Y-offset of a Stem object is needed, LilyPond will
188 automatically execute all callbacks for that object. In this case, it
189 will find @code{my-callback}, and execute that. The result is that the
190 stem is translated by two staff spaces in its direction.
192 (note: Y-offset-callbacks is also a property)
195 Offset callbacks can be stacked, ie.
198 \property .... \override #'Y-offset-callbacks = #(list
199 callback1 callback2 callback3)
203 The callbacks will be executed in the order callback3 callback2
204 callback1. This is used for quantized positioning: the staccato dot is
205 above or below a note head, and it must not be on a staff-line.
207 To achieve this, for the staccato there are two callbacks: one callback
208 that positions the grob above or below the note head, and one callback
209 that rounds the Y-position of the grob to the nearest open space.
211 Similarly, the size of a grob are determined through callbacks, settable
212 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
213 There can be only one extent-callback for each axis. No callback (value #f)
214 means: "empty in this direction". If you fill in a pair, that pair
215 hard-codes the extent in that coordinate.
218 @node Setting grob properties
219 @subsection Setting grob properties
221 Grob properties are stored as GUILE association lists, with symbols as
222 keys. From C++, element properties can be accessed using the functions
225 SCM get_grob_property (SCM) const;
226 void set_grob_property (const char * , SCM val);
227 void set_immutable_grob_property (const char * , SCM val);
228 void set_immutable_grob_property (SCM key, SCM val);
229 void set_grob_property (SCM , SCM val);
230 void set_grob_pointer (const char*, SCM val);
231 SCM remove_grob_property (const char* nm);
234 In GUILE, LilyPond provides
237 ly-get-grob-property GROB SYMBOL
238 ly-set-grob-property GROB SYMBOL VALUE
241 All lookup functions identify undefined properties with
242 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
244 Properties are stored in two ways:
246 @item mutable properties:
247 element properties that change from object to object. The storage of
248 these are private to a grob. Typically this is used to store lists of
249 pointers to other grobs
251 @item immutable properties:
252 element properties that are shared across different grobs of the same
253 type. The storage is shared, and hence it is read-only. Typically, this
254 is used to store function callbacks, and values for shared element
255 properties are read from @file{scm/element-description.scm}.
258 There are two ways to manually set grob properties.
260 You can change immutable grob properties. This is done with the
264 \property Voice.Stem \override #'direction = #1
267 This will push the entry @code{'(direction . 1)} on the immutable
268 property list for stems, in effect overriding the setting from
269 @file{scm/element-description.scm}. This can be undone by
272 \property Voice.stem \revert #'direction
275 If you use this a lot, this gets old quickly. So we also have a
279 \property Context.GrobType \set #'prop = #VAL
282 this does a @code{\revert} followed by a @code{\override}
284 The second way is \outputproperty. This construct looks like
287 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
290 In this case, in every grob that satisfies @var{pred}, the property
291 assignment @var{sym} = @var{val} is done. For example
295 #(lambda (gr) (string? (ly-get-grob-property gr
297 #'extra-offset = #'(-1.0 . 0.0)
300 This shifts all elements that have a @code{text} property one staff
301 space to the left. This mechanism is rather clumsy to use, but it allows
302 you tweak any setting of any grob.
304 @node Items and Spanners
305 @unnumberedsubsec Items and Spanners
307 Grobs can also be distinguished in their role in the horizontal spacing.
308 A lot of grobs define constraints on the spacing by their sizes. For
309 example, note heads, clefs, stems, and all other symbols with a fixed
310 shape. These grobs form a subtype called @code{Item}.
312 Other grobs have a shape that depends on the horizontal spacing. For
313 example, slur, beam, tie, etc. These grobs form a subtype called
314 @code{Spanner}. All spanners have two span-points (these must be
315 @code{Item}s), one on the left and one on the right. The left bound is
316 also the X-reference point.
318 Some items need special treatment for line breaking. For example, a
319 clef is normally only printed at the start of a line (ie. after a line
320 break). To model this, `breakable' items (clef, key signature, bar lines,
321 etc.) are copied twice. Then we have three versions of each breakable
322 item: one version if there is no line break, one version that is printed
323 before the line break (at the end of a system), one version that is
324 printed after the line break.
326 Whether these versions are visible and take up space, is determined by
327 the outcome of the visibility-lambda. This is a function taking a
328 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
329 this grob should be transparent and have no extent.
331 @node Pointer substitution
332 @unnumberedsubsec Pointer substitution
335 Symbols that cross line-breaks (such as slurs) cause some more
336 complications. When a spanner crosses a line-break, then the spanner is
337 "broken into pieces", for every line that the spanner is in, a copy of
338 the grob is made. A substitution process redirects all grob-reference
339 so that spanner grob will only reference other grobs in the same line.
341 @node Grob Scheme functions
342 @unnumberedsubsec Grob Scheme functions
345 @defun ly-get-grob-property g sym
346 Get the value of a value in grob @var{g} of property @var{sym}. It
347 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
350 @defun ly-set-grob-property g sym val
353 @defun ly-get-spanner-bound spanner dir
362 @defun make-duration length dotcount
364 @var{length} is the negative logarithm (base 2) of the duration:
365 1 is a half note, 2 is a quarter note, 3 is an eighth
366 note, etc. The number of dots after the note is given by
372 @node Pitch data type
373 @section Pitch data type
377 @defun make-pitch octave note shift
379 @var{octave} is specified by an integer, zero for the octave
380 containing middle C. @var{note} is a number from 0 to 7, with 0
381 corresponding to C and 7 corresponding to B. The shift is zero for a
382 natural, negative to add flats, or positive to add sharps.
388 @defun pitch-notename
391 @defun pitch-alteration
394 @defun pitch-semitones
397 @defun Pitch::transpose
403 @defun ly-get-trans-property
406 @defun ly-set-trans-property
410 @section Music_iterator
418 @defun ly-get-mus-property
421 @defun ly-set-mus-property
430 @cindex Output description
432 The objective of any typesetting system is to put ink on paper in the
433 right places. For LilyPond, this final stage is left to the TeX and the
434 printer subsystem. For lily, the last stage in processing a score is
435 outputting a description of what to put where. This description roughly
444 you merely have to look at the tex output of lily to see this.
445 Internally these instructions are encoded in Molecules:@footnote{At some
446 point LilyPond also contained Atom-objects, but they have been replaced
447 by Scheme expressions, making the name outdated.}. A molecule is an
448 object that combines dimension information (how large is this glyph ?)
449 with what-to-print-where.
451 Conceptually, Molecules can be constructed from Scheme code, by
452 translating a Molecule and by combining two molecules. In BNF
456 Molecule = COMBINE Molecule Molecule
457 | TRANSLATE Offset Molecule
462 If you are interested in seeing how this information is stored, you
463 can run with the @code{-f scm} option. The scheme expressions are then
464 dumped onto the output file.
466 (refer to the C++ code for more details). All visible,
467 ie. non-transparant, grobs have a callback to create a Molecule. The
468 name of the property is @code{molecule-callback}, and its value should
469 be a Scheme function taking one argument (the grob) and returning a
475 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
478 @defun ly-get-molecule-extent! mol axis
481 @defun ly-set-molecule-extent! mol axis extent
485 @section Font metrics
487 The font object represents the metric information of a font. Every font
488 that is loaded into LilyPond can be accessed via Scheme.
490 LilyPond only needs to know the dimension of glyph to be able to process
491 them. This information is present in font-metric files. LilyPond can
492 read two types of font-metrics: @TeX{} Font Metric files (tfm files) and
493 Adobe Font Metric files (afm files). AFM files are more versatile, and
494 LilyPond needs those features to typeset musical symbols. So LilyPond
495 will always try to load afm files first.
498 @defun ly-get-default-font gr
499 This returns the default font for grob @var{gr}.
502 @defun ly-find-glyph-by-name font name
503 This function retrieves a Molecule for the glyph named @var{name} in
504 @var{font}. The font must be available as a afm file.
509 @node Miscellaneous Scheme functions
510 @section Miscellaneous Scheme functions
512 @defun ly-input-location?
527 @defun ly-number->string