Node:Beam, Next:, Previous:BassFigure, Up:All layout objects



Beam

Beam grobs are created by: Auto_beam_engraver, Beam_engraver, Chord_tremolo_engraver and Grace_beam_engraver

spanner-interface

Other grobs have a shape that depends on the horizontal spacing. For example, slur, beam, tie, etc. These grobs form a subtype called Spanner. All spanners have two span-points (these must be Items), one on the left and one on the right. The left bound is also the X-reference point of the spanner.


minimum-length (dimension, in staff space)
try to make the Grob at least this long.

Also works as a scaling parameter for the length of hyphen. . Default value: (unset)

beam-interface

A beam.

#'thickness= weight of beams, in staffspace We take the least squares line through the ideal-length stems, and then damp that using damped = tanh (slope)

this gives an unquantized left and right position for the beam end. Then we take all combinations of quantings near these left and right positions, and give them a score (according to how close they are to the ideal slope, how close the result is to the ideal stems, etc.). We take the best scoring combination.


auto-knee-gap (dimension, in staff space)
If a gap is found between noteheads where a horizontal beam fits that is larger than this number, make a kneed beam. Default value: 5.5
beamed-stem-shorten (list)
shorten beamed stems in forced direction. Default value: '(1.0 0.5 0.25)
chord-tremolo (boolean)
if set, this beam is a tremolo. TODO: use interface for this! Default value: (unset)
concaveness-gap (dimension, in staff space)
A beam is considered to be concave if the distance of an inner notehead to the line between two outer noteheads is bigger than this gap. Default value: 2.0
concaveness-threshold (number)
A beam is considered to be concave is concaveness is bigger than this threshold. Concaveness is calculated as the sum of the vertical distances of inner noteheads that fall outside the interval of the two outer noteheads, to the vertically nearest outer notehead, divided by the square of the inner notes involved. Default value: 0.08
damping (integer)
amount of beam slope damping should beam slope be damped? 0: no, 1: yes, 100000: horizontal beams . Default value: 1
dir-function (procedure)
function of type (count total)->direction. Default value: beam-dir-majority, also available: beam-dir-mean, beam-dir-median.

The ways to calculate the direction of a beam work as follows:

majority
number count of up or down notes
mean
mean center distance of all notes
median
mean centre distance weighted per note

Default value: beam-dir-majority-median

flag-width-function (procedure)
Procedure that computes the width of a half-beam (a non-connecting beam.). Default value: beam-flag-width-function
gap (dimension, in staff space)
Size of a gap in a variable symbol. Default value: 0.8
gap-count (integer)
Number of gapped beams for tremolo. Default value: (unset)
knee (boolean)
Is this beam a knee? Default value: (unset)
least-squares-dy (number)
ideal beam slope, without damping. Default value: (unset)
neutral-direction (direction)
Where to go if we're on the neutral position of the staff (by default, the middle of the staff; see also grob-property neutral-position). [Ross] has the following to say about this: Some engravers consider the middle line neutral, and take the option of using either up- or down-stems for notes that fall on it. However, more up-to-date engraving no longer permits an option; now a down-stem is always appropriate. Default value: -1
position-callbacks (list)
list of functions set spanner positions. Default value: '(#<primitive-procedure Beam::least_squares> #<primitive-procedure Beam::check_concave> #<primitive-procedure Beam::slope_damping> #<primitive-procedure Beam::shift_region_to_valid> #<primitive-procedure Beam::quanting>)
positions (pair)
cons of staff positions (LEFT . RIGHT Default value: '(#f . #f)
quant-score (number)
Beam quanting score - can be stored for debugging Default value: (unset)
shorten (dimension, in staff space)
the amount of space that a stem should be shortened (DOCME!) Default value: (unset)
space-function (procedure)
return interbeam space given Beam grob and multiplicity. Default value: Beam::space_function
thickness (number)
thickness, measured in stafflinethickness. Default value: 0.48
staff-symbol-referencer-interface

Object whose Y position is meaning with reference to a staff symbol. Objects that have this interface should include Staff_symbol_referencer::callback in their Y-offset-callback.


staff-position (number)
vertical position in staff spaces, counted from the middle line. Default value: (unset)
grob-interface

In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the symbols, and the arcs by their relations. A grob is a node in that graph. The directed edges in the graph are formed by references to other grobs (i.e. pointers). This big graph of grobs specifies the notation problem. The solution of this problem is a description of the printout in closed form, i.e. a list of values. These values are Molecules.

All grobs have an X and Y-position on the page. These X and Y positions are stored in a relative format, so they can easily be combined by stacking them, hanging one grob to the side of another, and coupling them into a grouping-grob.

Each grob has a reference point (a.k.a. parent): the position of a grob is stored relative to that reference point. For example the X-reference point of a staccato dot usually is the note head that it applies to. When the note head is moved, the staccato dot moves along automatically.

A grob is often associated with a symbol, but some grobs do not print any symbols. They take care of grouping objects. For example, there is a separate grob that stacks staves vertically. The NoteCollision is also an abstract grob: it only moves around chords, but doesn't print anything.


X-extent (pair of numbers)
Store extent. internal use only. Default value: (unset)
X-extent-callback (procedure)
procedure taking an grob and axis argument, returning a number-pair. The return value is the extent of the grob.

The size of a grob are determined through callbacks, settable with grob properties X-extent-callback and Y-extent-callback. There can be only one extent-callback for each axis. No callback (Scheme value #f) means: `empty in this direction'. If you fill in a pair of numbers, that pair hard-codes the extent in that coordinate.

Default value: (unset)

X-offset-callbacks (list)
list of functions, each taking an grob and axis argument. The function determine the position relative to this grob's parent. The last one in the list is called first.

Offsets of grobs are relative to a parent reference point. Most positions are not known when an object is created, so these are calculated as needed. This is done by adding a callback for a specific direction.

Offset callbacks can be stacked, i.e.

                  property .... override #'Y-offset-callbacks = #(list
                          callback1 callback2 callback3)
          
          

The callbacks will be executed in the order callback3 callback2 callback1. This is used for quantized positioning: the staccato dot is above or below a note head, and it must not be on a staff-line. To achieve this, the staccato dot has two callbacks: one that positions the grob above or below the note head, and one that rounds the Y-position of the grob to the nearest open space.

Default value: (unset)

Y-extent (pair of numbers)
Store extent. internal use only. Default value: (unset)
Y-extent-callback (procedure)
see X-extent-callback. Default value: (unset)
Y-offset-callbacks (list)
see X-offset-callbacks. Default value: (unset)
after-line-breaking-callback (procedure)
Procedure taking a grob as argument. This procedure is called (using dependency resolution) after line breaking. Return value is ignored. Default value: Beam::after_line_breaking
before-line-breaking-callback (procedure)
Procedure taking grob as argument. This procedure is called (using dependency resolution) before line breaking, but after generating discretionary items. Return value is ignored. Default value: Beam::before_line_breaking
cause (any type)
Any kind of causation objects (i.e. music, or perhaps translator) that was the cause for this grob. Default value: (unset)
dependencies (list of grobs)
list of score-grob pointers that indicate who to compute first for certain global passes. Default value: (unset)
extra-X-extent (pair of numbers)
enlarge in X dimension by this much, measured in staff space. Default value: (unset)
extra-Y-extent (pair of numbers)
see extra-Y-extent. Default value: (unset)
extra-offset (pair of numbers)
pair of reals (a cons) forcing an extra offset before outputting. extra-offset is added just before `printing' the grob, so the typesetting engine is completely oblivious to it.

Default value: (unset)

interfaces (list)
list of symbols indicating the interfaces supported by this object. Is initialized from the meta field. Default value: (unset)
layer (number)
The output layer [0..2]. The default is 1. Default value: (unset)
meta (list)
Alist of meta information of this grob.

The alist contains the following entries: name, interfaces.

Default value: '((name . Beam) (interfaces grob-interface staff-symbol-referencer-interface beam-interface spanner-interface))

minimum-X-extent (pair of numbers)
minimum size in X dimension, measured in staff space. Default value: (unset)
minimum-Y-extent (pair of numbers)
see minimum-Y-extent. Default value: (unset)
molecule (unknown)
Cached output of the molecule-callback. Default value: (unset)
molecule-callback (procedure)
Function taking grob as argument, returning a smobbed Molecule.

All visible, i.e. non-transparent, grobs have a callback to create a Molecule. The callback 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.

Default value: Beam::brew_molecule

spacing-procedure (procedure)
procedure taking grob as argument. This is called after before-line-breaking-callback, but before the actual line breaking itself. Return value is ignored. Default value: (unset)
staff-symbol (grob (GRaphical OBject))
the staff symbol grob that we're in. Default value: (unset)
transparent (boolean)
This is almost the same as setting molecule-callback to #f, but this retains the dimensions of this grob, which means that you can erase grobs individually. . Default value: (unset)

This page is for LilyPond-2.0.0 (stable-branch).

Report errors to <bug-lilypond@gnu.org>.