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: When a
71 spanner, eg. a slur, crosses a line-break, then the spanner is "broken
72 into pieces", for every line that the spanner is in, a copy of the grob
73 is made. A substitution process redirects all grob-reference so that
74 spanner grob will only reference other grobs in the same line.
78 All vertical dimensions and spanning objects are computed, and all grobs
79 are output, line by line.
86 Moment is a rational number. Since GUILE doesn't support them natively,
87 so we created our own rational data type.
92 @defun make-moment num den
93 create the rational number @var{num}/@var{den}.
99 This section is about Grobs (short for Graphical Objects), which are
100 formatting objects used to create the final output. This material is
101 normally the domain of LilyPond gurus, but occasionally, a normal user
102 also has to deal with grobs.
104 The most simple interaction with Grobs are when you use
108 \property Voice.Stem \override #'direction = #1
111 This piece of lily input causes all stem objects to be stem-up
112 henceforth. In effect, you are telling lilypond to extend the defintion
113 of the "Stem" grob with the setting @code{direction := 1}. Of course
114 there are many more ways of customizing Lily output, and since most of
115 them involve Grobs in some form, this section explains some details of
121 * Setting grob properties::
123 * Items and Spanners::
124 * Grob Scheme functions::
129 @node What is a grob?
130 @subsection What is a grob?
132 In music notation, lots of symbols are related in some way. You can
133 think of music notation as a graph where nodes are formed by the
134 symbols, and the arcs by their relations. A grob is node in that
135 graph. A grob stores references to other grobs, the directed edges in
138 The objective of this big graph of grobs, is to specify the notation
139 problem. The solution of this problem is a description of the printout
140 that is in closed form, i.e. but a list of values. These values are
141 Molecules. (see @ref{Molecules})
143 All grobs have an X and Y-position on the page. These X and Y positions
144 are stored in a relative format, so they can easily be combined by
145 stacking them, hanging one grob to the side of another, and coupling
146 them into a grouping-grob.
148 Each grob has a reference point, or parent: the position of a grob is
149 stored relative to that reference point. For example the X-reference
150 point of a staccato dot usually is the note head that it applies
151 to. Whenever the note head is moved, the staccato dot moves along
154 If you keep following offset reference points, you will always end up at
155 the root-object. This root object is called @code{Line_of_score}, and it
156 represents a system (ie. a line of music).
158 All grobs carry a set of grob-properties. In the Stem example above,
159 the property @code{direction} is set to value @code{1}. The function
160 that draws the symbol (@code{Stem::brew_molecule}) uses the value of
161 @code{direction} to determine how to print the stem and the flag. The
162 appearance of a grob is determined solely by the values of its
165 Often, a grob also is associated with a symbol. However, some
166 grobs do not print any symbols, but take care of grouping objects. For
167 example, there is a separate grob that stacks staffs vertically, so they
168 are not printed in overstrike. The @code{NoteCollision} is another
169 example of an abstract grob. It only moves around chords, but doesn't
172 A complete list of grob types is found in
173 @ref{(lilypond-internals)LilyPond backend}
175 Grobs are created in the "Interpreting music" phase, by objects in
176 LilyPond called engravers. In this phase of the translation, a load of
177 grobs are created, and they are linked into a giant network of objects.
178 This network of grobs forms the "specification" of the print
179 problem. This problem is then solved: configurations, directions,
180 dimensions, line breaks, etc. are calculated. Finally, the printing
181 description in the form of Molecules (@ref{Molecules}) is extracted from
182 the network. These are then dumped into the output file
185 @subsection Callbacks
187 Offsets of grobs are relative to a parent reference point. Most
188 positions are not known when an object is created, so these are
189 calculated as needed. This is done by adding a callback for a specific
192 Suppose you have the following code in a .ly file.
194 #(define (my-callback gr axis)
195 (* 2.0 (get-grob-property gr 'direction))
200 \property Voice.Stem \override #'Y-offset-callbacks = #(list
204 When the Y-offset of a Stem object is needed, LilyPond will
205 automatically execute all callbacks for that object. In this case, it
206 will find @code{my-callback}, and execute that. The result is that the
207 stem is translated by two staff spaces in its direction.
209 (note: Y-offset-callbacks is also a property)
212 Offset callbacks can be stacked, ie.
215 \property .... \override #'Y-offset-callbacks = #(list
216 callback1 callback2 callback3)
220 The callbacks will be executed in the order callback3 callback2
221 callback1. This is used for quantized positioning: the staccato dot is
222 above or below a note head, and it must not be on a staff-line. To
223 achieve this, for the staccato there are two callbacks: one callback
224 that positions the grob above or below the note head, and one callback
225 that rounds the Y-position of the grob to the nearest open space.
227 Similarly, the size of a grob are determined through callbacks, settable
228 with grob properties @code{X-extent-callback} and
229 @code{Y-extent-callback}. There can be only one extent-callback for
230 each axis. No callback (Scheme value @code{#f}) means: "empty in this
231 direction". If you fill in a pair of numbers, that pair hard-codes the
232 extent in that coordinate.
235 @node Setting grob properties
236 @subsection Setting grob properties
238 Grob properties are stored as GUILE association lists, with symbols as
239 keys. From C++, element properties can be accessed using the functions
242 SCM get_grob_property (SCM) const;
243 void set_grob_property (const char * , SCM val);
244 void set_immutable_grob_property (const char * , SCM val);
245 void set_immutable_grob_property (SCM key, SCM val);
246 void set_grob_property (SCM , SCM val);
247 void set_grob_pointer (const char*, SCM val);
248 SCM remove_grob_property (const char* nm);
251 In GUILE, LilyPond provides
254 ly-get-grob-property GROB SYMBOL
255 ly-set-grob-property GROB SYMBOL VALUE
258 All lookup functions identify undefined properties with
259 end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
261 Properties are stored in two ways:
263 @item mutable properties:
264 element properties that change from object to object. The storage of
265 these are private to a grob. Typically this is used to store lists of
266 pointers to other grobs
268 @item immutable properties:
269 element properties that are shared across different grobs of the same
270 type. The storage is shared, and hence it is read-only. Typically, this
271 is used to store function callbacks, and values for shared element
272 properties are read from @file{scm/element-description.scm}.
275 There are two ways to manually set grob properties.
277 You can change immutable grob properties. This is done with the
281 \property Voice.Stem \override #'direction = #1
284 This will push the entry @code{'(direction . 1)} on the immutable
285 property list for stems, in effect overriding the setting from
286 @file{scm/element-description.scm}. This can be undone by
289 \property Voice.stem \revert #'direction
292 If you use this a lot, this gets old quickly. So we also have a
296 \property Context.GrobType \set #'prop = #VAL
299 this does a @code{\revert} followed by a @code{\override}
301 The second way is \outputproperty. This construct looks like
304 \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val}
307 In this case, in every grob that satisfies @var{pred}, the property
308 assignment @var{sym} = @var{val} is done. For example
312 #(lambda (gr) (string? (ly-get-grob-property gr
314 #'extra-offset = #'(-1.0 . 0.0)
317 This shifts all elements that have a @code{text} property one staff
318 space to the left. This mechanism is rather clumsy to use, but it allows
319 you tweak any setting of any grob.
322 @node Grob interfaces
323 @unnumberedsubsec Grob interfaces
325 Grob properties form a namespace where you can set variables per
326 object. Each object however, may have multiple functions. For example,
327 consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
328 above or below the staff, it is a dynamic sign, and it is a kind of
331 To reflect this different functions of a grob, procedures and variables
332 are grouped into so-called interfaces. The dynamic text for example
333 supports the following interfaces:
336 The glyph is built from characters from a font, hence the
337 @code{font-interface}. For objects supporting @code{font-interface}, you
338 can select alternate fonts by setting @code{font-style},
339 @code{font-point-size}, etc.
341 @item dynamic-interface
342 Dynamic interface is not associated with any variable or function in
343 particular, but this makes it possible to distinguish this grob from
344 other similar grobs (like @code{TextScript}), that have no meaning of
348 This interface is for texts that are to be set using special routines
349 to stack text into lines, using kerning, etc.
351 @item general-grob-interface
352 This interface is supported by all grob types.
357 @node Items and Spanners
358 @unnumberedsubsec Items and Spanners
360 Grobs can also be distinguished in their role in the horizontal spacing.
361 A lot of grobs define constraints on the spacing by their sizes. For
362 example, note heads, clefs, stems, and all other symbols with a fixed
363 shape. These grobs form a subtype called @code{Item}.
365 Other grobs have a shape that depends on the horizontal spacing. For
366 example, slur, beam, tie, etc. These grobs form a subtype called
367 @code{Spanner}. All spanners have two span-points (these must be
368 @code{Item}s), one on the left and one on the right. The left bound is
369 also the X-reference point.
371 Some items need special treatment for line breaking. For example, a
372 clef is normally only printed at the start of a line (ie. after a line
373 break). To model this, `breakable' items (clef, key signature, bar lines,
374 etc.) are copied twice. Then we have three versions of each breakable
375 item: one version if there is no line break, one version that is printed
376 before the line break (at the end of a system), one version that is
377 printed after the line break.
379 Whether these versions are visible and take up space, is determined by
380 the outcome of the visibility-lambda. This is a function taking a
381 direction (-1, 0 or 1) and returns a cons of booleans, signifying wether
382 this grob should be transparent and have no extent.
385 @node Grob Scheme functions
386 @unnumberedsubsec Grob Scheme functions
389 @defun ly-get-grob-property g sym
390 Get the value of a value in grob @var{g} of property @var{sym}. It
391 will return @code{'()} (end-of-list) if @var{g} doesn't have @var{sym} set.
394 @defun ly-set-grob-property g sym val
395 Set @var{sym} in grob @var{g} to value @var{val}
398 @defun ly-get-spanner-bound spanner dir
399 Get one of the bounds of @var{spanner}. @var{dir} may be @code{-1} for
400 left, and @code{1} for right.
404 Typecheck: is @var{g} a grob?
410 @defun make-duration length dotcount
412 @var{length} is the negative logarithm (base 2) of the duration:
413 1 is a half note, 2 is a quarter note, 3 is an eighth
414 note, etc. The number of dots after the note is given by
420 type predicate for Duration
423 @node Pitch data type
424 @section Pitch data type
428 @defun make-pitch octave note shift
430 @var{octave} is specified by an integer, zero for the octave
431 containing middle C. @var{note} is a number from 0 to 7, with 0
432 corresponding to C and 7 corresponding to B. The shift is zero for a
433 natural, negative to add flats, or positive to add sharps.
436 @defun pitch-octave p
437 extract the octave from pitch @var{p}.
440 @defun pitch-notename
441 extract the note name from pitch @var{p}.
444 @defun pitch-alteration
445 extract the alteration from pitch @var{p}.
448 @defun pitch-semitones
449 calculate the number of semitones of @var{p} from central C.
452 @defun Pitch::transpose t p
453 Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that
454 central C is transposed to.
460 Engravers are building blocks of contexts. They are not yet user accessible.
462 @defun ly-get-trans-property tr sym
463 retrieve the value of @var{sym} from context @var{tr}
466 @defun ly-set-trans-property tr sym val
467 set value of property @var{sym} in context @var{tr} to @var{val}.
471 @section Music_iterator
473 This data-type is a direct hook into some C++ constructor functions. It
474 is not yet user-serviceable.
477 type predicate for c++-function.
483 Music is the data type that music expressions are stored in. The data
484 type does not yet offer many manipulations.
486 @defun ly-get-mus-property m sym
487 Get the property @var{sym} of music expression @var{m}.
490 @defun ly-set-mus-property m sym val
491 Set property @var{sym} in music expression @var{m} to @var{val}.
494 @defun ly-make-music name
495 Make a music object/expression of type @var{name}. Warning: this
496 interface will likely change in the near future.
504 @cindex Output description
506 The objective of any typesetting system is to put ink on paper in the
507 right places. For LilyPond, this final stage is left to the TeX and the
508 printer subsystem. For lily, the last stage in processing a score is
509 outputting a description of what to put where. This description roughly
518 you merely have to look at the tex output of lily to see this.
519 Internally these instructions are encoded in Molecules:@footnote{At some
520 point LilyPond also contained Atom-objects, but they have been replaced
521 by Scheme expressions, making the name outdated.}. A molecule is an
522 object that combines dimension information (how large is this glyph ?)
523 with what-to-print-where.
525 Conceptually, Molecules can be constructed from Scheme code, by
526 translating a Molecule and by combining two molecules. In BNF
530 Molecule = COMBINE Molecule Molecule
531 | TRANSLATE Offset Molecule
536 If you are interested in seeing how this information is stored, you
537 can run with the @code{-f scm} option. The scheme expressions are then
538 dumped onto the output file.
540 All visible, i.e. non-transparant, grobs have a callback to create a
541 Molecule. The name of the property is @code{molecule-callback}, and its
542 value should be a Scheme function taking one argument (the grob) and
543 returning a Molecule. Most molecule callbacks are written in C++, but
544 you can also write them in Scheme. An example is provided in
545 @code{input/regression/molecule-hacking.ly}.
552 @defun ly-combine-molecule-at-edge mol1 axis dir mol2 padding
553 Construct a molecule by putting @var{mol2} next to
554 @var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be
555 -1 (left or down) or 1 (right or up). @var{padding} specifies extra
556 space to add in between. The unit is global staff space. is the
559 @defun ly-get-molecule-extent! mol axis
560 Return a pair of numbers signifying the extent of @var{mol} in
561 @var{axis} direction (0 or 1 for x and y axis respectively).
564 @defun ly-set-molecule-extent! mol axis extent
565 Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in
566 @var{axis} direction (0 or 1 for x and y axis respectively).
570 @section Font metrics
572 The font object represents the metric information of a font. Every font
573 that is loaded into LilyPond can be accessed via Scheme.
575 LilyPond only needs to know the dimension of glyph to be able to process
576 them. This information is stored in font metric files. LilyPond can
577 read two types of font-metrics: @TeX{} Font Metric files (tfm files) and
578 Adobe Font Metric files (@file{.afm} files). LilyPond will always try
579 to load afm files first since @file{.afm} files are more versatile.
581 @defun ly-get-default-font gr
582 This returns the default font for grob @var{gr}.
585 @defun ly-find-glyph-by-name font name
586 This function retrieves a Molecule for the glyph named @var{name} in
587 @var{font}. The font must be available as a afm file.
592 @node Miscellaneous Scheme functions
593 @section Miscellaneous Scheme functions
595 @defun ly-input-location?
600 Scheme callable function to issue the warning @code{msg}.
604 Return the current lilypond version as a list, e.g.
605 @code{(1 3 127 uu1)}.
608 @defun ly-gulp-file name
609 read file named @var{name}, and return its contents in a string. This
610 uses the lilypond search path.
615 type predicate. A direction is a -1, 0 or 1.
618 @defun ly-number->string num
619 converts @var{num} without generating many decimals. It leaves a space
623 @defun set-lily-option sym val
624 Set a global option for the program.
626 [todo: document interesting sym/val pairs ]