
Tuplets
=======

Tuplet is a general term for series of notes played with durations
(usually) shorter than the nominal durations of the drawn notes.  The
obvious example is the triplet, in which three notes are played in the
time of two.

The terminology we use in Rosegarden 4 is: a Tuplet is a single note
within one of these series; Tupled Group (which is a special sort of
Beamed Group -- see sets.txt) is the name for the whole series.  Each
tuplet has a nominal duration, which is the duration of the note as
drawn on the score (e.g. triplet quavers have a nominal one-quaver
duration), and an effective duration, which is the duration of the
note as performed (e.g. two-thirds of a quaver).

Rosegarden 2.1 stored tuplets with their nominal type and duration,
plus some information that could be used to calculate the effective
duration.

For Rosegarden 4, in which each event has a starting time as well as a
duration (RG2.1's events were just a contiguous series, and didn't
store a starting time) it makes more sense to ensure that the starting
times of the tuplets and of the first event after the tupled group are
consistent with the stored durations.  For this reason, Rosegarden 4
stores the effective duration of each tuplet, and records the nominal
duration (or rather, data necessary to calculate it) separately in
event properties.

The complete set of properties associated with a tupled note or rest:

 -- Event's normal absolute time and duration

    These store the performance time and duration, so for example
    the duration is 2/3 of a quaver's duration if the group is
    made up of quaver triplets.

    The absolute time would be slightly complicated to calculate
    from the other properties, but the duration could be calculated
    from the nominal duration and the tupled and untupled lengths
    of the group.

 -- BaseProperties::BEAMED_GROUP_ID
    BaseProperties::BEAMED_GROUP_TYPE

    Indicate membership of the group.

 -- BaseProperties::TUPLET_NOMINAL_DURATION

    The "display" duration of the event, for example the duration
    of a quaver if the group is made up of quaver triplets.

    This is a non-persistent property, calculated at rendering time
    from the duration of the event and the tuplet counts of the group.

 -- BaseProperties::BEAMED_GROUP_UNTUPLED_COUNT
    Number to be drawn on the tupling line.  For a tuplet group
    that consists of "N notes of time T played in the time of M",
    this is N.

 -- BaseProperties::BEAMED_GROUP_TUPLED_COUNT
    For a tuplet group that consists of "N notes of time T played
    in the time of M", this is M.

 -- BaseProperties::BEAMED_GROUP_TUPLET_BASE
    For a tuplet group that consists of "N notes of time T played
    in the time of M", this is T.  This is almost redundant, and
    indeed is not actually used anywhere except as an indication
    that a note is in a tuplet group in the first place -- but it
    has a potential use (which we don't take advantage of yet)
    for regrouping according to the intended group specifications
    after a modification.

(The effective duration is not necessarily exact, although for
triplets it will be.  Our base unit of time was originally 6 units to
1 hemidemisemiquaver, which meant triplets were the only tuplets that
could be guaranteed an exact representation; it's since been increased
to 60 units to the hemidemi, giving various other sorts of tuplets a
good chance of exactness, and at least a "good enough" approximation
for the listener.)

