4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
14 * Conversion stages:: Lilypond is a multi-pass program.
16 * Grobs:: Graphical object
22 * Molecules:: Molecules are stand-alone descriptions of output
23 * Font metrics:: Font metrics
24 * Miscellaneous Scheme functions::
27 @node Conversion stages
28 @section Conversion stages
30 When translating the input to notation, there are number of distinct
31 phases. We list them here:
37 The .ly file is read, and converted to a list of @code{Scores}, which
38 each contain @code{Music} and paper/midi-definitions.
40 @item Interpreting music
41 @cindex interpreting music
43 All music events are "read" in the same order as they would be played
44 (or read from paper). At every step of the interpretation, musical
45 events are delivered to
46 interpretation contexts,
48 which use them to build grobs (or MIDI objects, for MIDI output).
54 At places where line breaks may occur, clefs and bars are prepared for
55 a possible line break.
61 In this stage, all information that is needed to determine line breaking
64 @item Break calculation:
66 The lines and horizontal positions of the columns are determined.
70 Relations between all grobs are modified to reflect line breaks. See
71 also @ref{Pointer substitution}.
75 All vertical dimensions and spanning objects are computed, and all grobs
76 are output, line by line.
83 Moment is a rational number. Since GUILE doesn't support them natively,
84 so we created our own rational data type.
89 @defun make-moment num den
90 create the rational number @var{num}/@var{den}.
96 This section is about Grobs (short for Graphical Objects), which are
97 formatting objects used to create the final output. This material is
98 normally the domain of LilyPond gurus, but occasionally, a normal user
99 also has to deal with grobs.
101 The most simple interaction with Grobs are when you use
105 \property Voice.Stem \override #'direction = #1
108 This piece of lily input causes all stem objects to be stem-up
109 henceforth. In effect, you are telling lilypond to extend the defintion
110 of the "Stem" grob with the setting @code{direction := 1}. Of course
111 there are many more ways of customizing Lily output, and since most of
112 them involve Grobs in some form, this section explains some details of
118 * Setting grob properties::
119 * Items and Spanners::
120 * Pointer substitution::
121 * Grob Scheme functions::
124 @node What is a grob?
125 @subsection What is a grob?
127 In music notation, lots of symbols are related in some way. You can
128 think of music notation as a graph where nodes are formed by the
129 symbols, and the arcs by their relations. A grob is node in that
130 graph. A grob stores references to other grobs, the directed edges in
133 The objective of this big graph of grobs, is to specify the notation
134 problem. The solution of this problem is a description of the printout
135 that is in closed form, i.e. but a list of values. These values are
136 Molecules. (see @ref{Molecules})
138 All grobs have an X and Y-position on the page. These X and Y positions
139 are stored in a relative format, so they can easily be combined by
140 stacking them, hanging one grob to the side of another, and coupling
141 them into a grouping-grob.
143 Each grob has a reference point, or parent: the position of a grob is
144 stored relative to that reference point. For example the X-reference
145 point of a staccato dot usually is the note head that it applies
146 to. Whenever the note head is moved, the staccato dot moves along
149 If you keep following offset reference points, you will always end up at
150 the root-object. This root object is called @rgrob{Line_of_score}, and it
151 represents a system (ie. a line of music).
153 All grobs carry a set of grob-properties. In the Stem example above,
154 the property @code{direction} is set to value @code{1}. The function
155 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
156 @code{direction} to determine how to print the stem and the flag. The
157 appearance of a grob is determined solely by the values of its
160 Often, a grob also is associated with a symbol. On the other hand,
161 Some grobs do not print any symbols, but take care of grouping
162 objects. For example, there is a separate grob that stacks staffs
163 vertically, so they are not printed in overstrike. The
164 @rgrob{NoteCollision} is another example of an abstract grob. It only
165 moves around chords, but doesn't print anything.
167 A complete list of grob types is found in
168 @ref{(lilypond-internals)LilyPond backend}
170 Grobs are created in the "Interpreting music" phase, by things in
171 LilyPond called engravers. In this phase of the translation, a load of
172 grobs are created, and they are linked into a giant network of objects.
173 This network of grobs forms the "specification" of the print
174 problem. This problem is then solved: configurations, directions,
175 dimensions, line breaks, etc. are calculated. Finally, the printing
176 description in the form of Molecules (@ref{Molecules}) is extracted from
177 the network. These are then dumped into the output file
180 @subsection Callbacks
182 Offsets of grobs are relative to a parent reference point. Most
183 positions are not known when an object is created, so these are
184 calculated as needed. This is done by adding a callback for a specific
187 Suppose you have the following code in a .ly file.
189 #(define (my-callback gr axis)
190 (* 2.0 (get-gr-property grob 'direction))
195 \property Voice.Stem \override #'Y-offset-callbacks = #(list
199 When the Y-offset of a Stem object is needed, LilyPond will
200 automatically execute all callbacks for that object. In this case, it
201 will find @code{my-callback}, and execute that. The result is that the
202 stem is translated by two staff spaces in its direction.
204 (note: Y-offset-callbacks is also a property)
207 Offset callbacks can be stacked, ie.
210 \property .... \override #'Y-offset-callbacks = #(list
211 callback1 callback2 callback3)
215 The callbacks will be executed in the order callback3 callback2
216 callback1. This is used for quantized positioning: the staccato dot is
217 above or below a note head, and it must not be on a staff-line.
219 To achieve this, for the staccato there are two callbacks: one callback
220 that positions the grob above or below the note head, and one callback
221 that rounds the Y-position of the grob to the nearest open space.
223 Similarly, the size of a grob are determined through callbacks, settable
224 with grob properties @code{X-extent-callback} and @code{Y-extent-callback}.
225 There can be only one extent-callback for each axis. No callback (value #f)
226 means: "empty in this direction". If you fill in a pair, that pair
227 hard-codes the extent in that coordinate.
230 @node Setting grob properties
231 @subsection Setting grob properties
233 Grob properties are stored as GUILE association lists, with symbols as
234 keys. From C++, element properties can be accessed using the functions
237 SCM get_grob_property (SCM) const;
238 void set_grob_property (const char * , SCM val);
239 void set_immutable_grob_property (const char * , SCM val);
240 void set_immutable_grob_property (SCM key, SCM val);
241 void set_grob_property (SCM , SCM val);
242 void set_grob_pointer (const char*, SCM val);
243 SCM remove_grob_property (const char* nm);
246 In GUILE, LilyPond provides
249 ly-get-grob-property GROB SYMBOL
250 ly-set-grob-property GROB SYMBOL VALUE
253 All lookup functions identify undefined properties with
254 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
256 Properties are stored in two ways:
258 @item mutable properties:
259 element properties that change from object to object. The storage of
260 these are private to a grob. Typically this is used to store lists of
261 pointers to other grobs
263 @item immutable properties:
264 element properties that are shared across different grobs of the same
265 type. The storage is shared, and hence it is read-only. Typically, this
266 is used to store function callbacks, and values for shared element
267 properties are read from @file{scm/element-description.scm}.
270 There are two ways to manually set grob properties.
272 You can change immutable grob properties. This is done with the
276 \property Voice.Stem \override #'direction = #1
279 This will push the entry @code{'(direction . 1)} on the immutable
280 property list for stems, in effect overriding the setting from
281 @file{scm/element-description.scm}. This can be undone by
284 \property Voice.stem \revert #'direction
287 If you use this a lot, this gets old quickly. So we also have a
291 \property Context.GrobType \set #'prop = #VAL
294 this does a @code{\revert} followed by a @code{\override}
296 The second way is \outputproperty. This construct looks like
299 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
302 In this case, in every grob that satisfies @var{pred}, the property
303 assignment @var{sym} = @var{val} is done. For example
307 #(lambda (gr) (string? (ly-get-grob-property gr
309 #'extra-offset = #'(-1.0 . 0.0)
312 This shifts all elements that have a @code{text} property one staff
313 space to the left. This mechanism is rather clumsy to use, but it allows
314 you tweak any setting of any grob.
316 @node Items and Spanners
317 @unnumberedsubsec Items and Spanners
319 Grobs can also be distinguished in their role in the horizontal spacing.
320 A lot of grobs define constraints on the spacing by their sizes. For
321 example, note heads, clefs, stems, and all other symbols with a fixed
322 shape. These grobs form a subtype called @code{Item}.
324 Other grobs have a shape that depends on the horizontal spacing. For
325 example, slur, beam, tie, etc. These grobs form a subtype called
326 @code{Spanner}. All spanners have two span-points (these must be
327 @code{Item}s), one on the left and one on the right. The left bound is
328 also the X-reference point.
330 Some items need special treatment for line breaking. For example, a
331 clef is normally only printed at the start of a line (ie. after a line
332 break). To model this, `breakable' items (clef, key signature, bar lines,
333 etc.) are copied twice. Then we have three versions of each breakable
334 item: one version if there is no line break, one version that is printed
335 before the line break (at the end of a system), one version that is
336 printed after the line break.
338 Whether these versions are visible and take up space, is determined by
339 the outcome of the visibility-lambda. This is a function taking a
340 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
341 this grob should be transparent and have no extent.
343 @node Pointer substitution
344 @unnumberedsubsec Pointer substitution
347 Symbols that cross line-breaks (such as slurs) cause some more
348 complications. When a spanner crosses a line-break, then the spanner is
349 "broken into pieces", for every line that the spanner is in, a copy of
350 the grob is made. A substitution process redirects all grob-reference
351 so that spanner grob will only reference other grobs in the same line.
353 @node Grob Scheme functions
354 @unnumberedsubsec Grob Scheme functions
357 @defun ly-get-grob-property g sym
358 Get the value of a value in grob @var{g} of property @var{sym}. It
359 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
362 @defun ly-set-grob-property g sym val
365 @defun ly-get-spanner-bound spanner dir
376 @defun make-duration length dotcount
378 @var{length} is the negative logarithm (base 2) of the duration:
379 1 is a half note, 2 is a quarter note, 3 is an eighth
380 note, etc. The number of dots after the note is given by
386 @node Pitch data type
387 @section Pitch data type
391 @defun make-pitch octave note shift
393 @var{octave} is specified by an integer, zero for the octave
394 containing middle C. @var{note} is a number from 0 to 7, with 0
395 corresponding to C and 7 corresponding to B. The shift is zero for a
396 natural, negative to add flats, or positive to add sharps.
402 @defun pitch-notename
405 @defun pitch-alteration
408 @defun pitch-semitones
411 @defun Pitch::transpose
417 @defun ly-get-trans-property
420 @defun ly-set-trans-property
424 @section Music_iterator
432 @defun ly-get-mus-property
435 @defun ly-set-mus-property
444 @cindex Output description
446 The objective of any typesetting system is to put ink on paper in the
447 right places. For LilyPond, this final stage is left to the TeX and the
448 printer subsystem. For lily, the last stage in processing a score is
449 outputting a description of what to put where. This description roughly
458 you merely have to look at the tex output of lily to see this.
459 Internally these instructions are encoded in Molecules:@footnote{At some
460 point LilyPond also contained Atom-objects, but they have been replaced
461 by Scheme expressions, making the name outdated.}. A molecule is an
462 object that combines dimension information (how large is this glyph ?)
463 with what-to-print-where.
465 Conceptually, Molecules can be constructed from Scheme code, by
466 translating a Molecule and by combining two molecules. In BNF
470 Molecule = COMBINE Molecule Molecule
471 | TRANSLATE Offset Molecule
476 If you are interested in seeing how this information is stored, you
477 can run with the @code{-f scm} option. The scheme expressions are then
478 dumped onto the output file.
480 (refer to the C++ code for more details). All visible,
481 ie. non-transparant, grobs have a callback to create a Molecule. The
482 name of the property is @code{molecule-callback}, and its value should
483 be a Scheme function taking one argument (the grob) and returning a
489 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
492 @defun ly-get-molecule-extent! mol axis
495 @defun ly-set-molecule-extent! mol axis extent
499 @section Font metrics
501 The font object represents the metric information of a font. Every font
502 that is loaded into LilyPond can be accessed via Scheme.
504 LilyPond only needs to know the dimension of glyph to be able to process
505 them. This information is present in font-metric files. LilyPond can
506 read two types of font-metrics: @TeX{} Font Metric files (tfm files) and
507 Adobe Font Metric files (afm files). AFM files are more versatile, and
508 LilyPond needs those features to typeset musical symbols. So LilyPond
509 will always try to load afm files first.
512 @defun ly-get-default-font gr
513 This returns the default font for grob @var{gr}.
516 @defun ly-find-glyph-by-name font name
517 This function retrieves a Molecule for the glyph named @var{name} in
518 @var{font}. The font must be available as a afm file.
523 @node Miscellaneous Scheme functions
524 @section Miscellaneous Scheme functions
526 @defun ly-input-location?
541 @defun ly-number->string