GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Node:Molecules, Next:Font metrics, Previous:Grobs, Up:Internals

Molecules

The objective of any typesetting system is to put ink on paper in the right places. For LilyPond, this final stage is left to the TeX and the printer subsystem. For lily, the last stage in processing a score is outputting a description of what to put where. This description roughly looks like

        PUT glyph AT (x,y)
        PUT glyph AT (x,y)
        PUT glyph AT (x,y)

you merely have to look at the tex output of lily to see this. Internally these instructions are encoded in Molecules.¹ A molecule is what-to-print-where information that also contains dimension information (how large is this glyph?).

Conceptually, Molecules can be constructed from Scheme code, by translating a Molecule and by combining two molecules. In BNF notation:

Molecule  :: COMBINE Molecule Molecule
           | TRANSLATE Offset Molecule
           | GLYPH-DESCRIPTION
           ;

If you are interested in seeing how this information is stored, you can run with the -f scm option. The scheme expressions are then dumped in the output file.

All visible, i.e. non-transparent, grobs have a callback to create a Molecule. The name of the property is molecule-callback, and its value should be a Scheme function taking one argument (the grob) and returning a Molecule. Most molecule callbacks are written in C++, but you can also write them in Scheme. An example is provided in input/regression/molecule-hacking.ly.

molecule? m

Function

type predicate.

ly-combine-molecule-at-edge mol1 axis dir mol2 padding

Function

Construct a molecule by putting mol2 next to mol1. axis can be 0 (x-axis) or 1 (y-axis), dir can be -1 (left or down) or 1 (right or up). padding specifies extra space to add in between measured in global staff space.

ly-get-molecule-extent! mol axis

Function

Return a pair of numbers signifying the extent of mol in axis direction (0 or 1 for x and y axis respectively).

ly-set-molecule-extent! mol axis extent

Function

Set the extent (extent must be a pair of numbers) of mol in axis direction (0 or 1 for x- and y-axis respectively). Note that an extent (A . B) is an interval and hence A is smaller than B, and is often negative.

Footnotes

1. At some point LilyPond also contained Atom-objects, but they have been replaced by Scheme expressions, making the name outdated.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to lilypond@packages.debian.org

Copyright (c) 1997--2001 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.