Package eu.bandm.music.entities

Class Ornament

java.lang.Object
eu.bandm.tscore.base.Entity<Ornament>
eu.bandm.music.entities.Ornament
All Implemented Interfaces:
Translet.Parseable<Ornament>, Cloneable
Direct Known Subclasses:
Ornament_JSB_klavierbuechlein, Ornament_KdF_special
public class Ornament extends Entity<Ornament> implements Cloneable
Abstract class for ornaments = shortcuts which replace one notated note with a sequence of played faster notes.

Each ornament defines three sequences of integers, which are distances from the central pitch in diatonic steps. The segments are played in a row, the middle can be repeated one or more times. Instances of this very simple model basically are extended to sequences of fast played notes with pitches around the notated reference pitch. Only conceptually, all fast notes have the same duration which is an integral part of the notated duration of the reference note. The played pitches are n scalar steps remote from the reference, which is declared by the integers in the three sequences/arrays. The expansion works as follows:

  1. Determine the duration of the played notes.
  2. Determine how often the central segment must be repeated to fill the duration. It must appear at least once.
      All repeated indexes are melt into one single played event, so a central segment defined by "<0>", which is repeated as long as necessary, simply is a long hold of the reference pitch.

  • Field Details

    • pre

      final int[] pre
      Sequence of pitch distances for the pre part of the ornament

    • rep

      final int[] rep
      Sequence of pitch distances for the main repeated part of the ornament

    • post

      final int[] post
      Sequence of pitch distances for the post part of the ornament

    • mainNote

      public static final int[] mainNote
      Can be used as the main part to simply hold the main note.

    • nothing

      public static final int[] nothing
      Can be used to make pre or post part not executing.

    • repUpperStart

      public static final int[] repUpperStart
      Can be used for the body of a trill.

    • repLowerStart

      public static final int[] repLowerStart
      Can be used for the body of a trill.

    • only1

      final int[] only1
      This is a repetition count result, not an ornament segment.

  • Constructor Details

    • Ornament

      protected Ornament(EntityCatalog<Ornament> c, Map<String,String> map, int[] pre, int[] rep, int[] post)
      Construct one ornament type completely.
      Parameters:
      c - the catalog is here a collection of ornaments
      map - the name of the ornament in different langugages
      pre - the sequence of integers describing the pre part
      rep - the sequence of integers describing the main part, which can be repeated
      post - the sequence of integers describing the post part

    • Ornament

      protected Ornament(EntityCatalog<Ornament> c, MuLi names, int[] pre, int[] rep, int[] post)
      Construct one ornament type completely.
      Parameters:
      c - the catalog is here a collection of ornaments
      names - the name of the ornament in different langugages
      pre - the sequence of integers describing the pre part
      rep - the sequence of integers describing the main part, which can be repeated
      post - the sequence of integers describing the post part

  • Method Details

    • allOffsets

      public Set<Integer> allOffsets()
      Sequence of pitch distances for the pre part of the ornament

    • dump

      public void dump(PrintStream ps)
      Description copied from class: Entity
      Debugging method to display this entity. Called by EntityCatalog.dump(PrintStream)
      Overrides:
      dump in class Entity<Ornament>

    • repetitionLimits

      @Deprecated(forRemoval=true) public int[] repetitionLimits(Rational noteDuration, Rational minDuration, Rational maxDuration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns the minimal and maximal possible number of repetitions of the central "rep" segment. All duration values are relative to the same base, in most cases notated metrical durations. But the algorithm as such works with arbitrary reference systems, e.g. milliseconds.
      Parameters:
      noteDuration - the overall notated duration of the note carrying this ornament.
      minDuration - the minimal duration for each played note when executing this ornament.
      maxDuration - the maximal duration for each played note when executing this ornament.
      Returns:
      array with minimal and maximal repetition counts

    • expand

      @Deprecated(forRemoval=true) @Opt public @Opt List<Integer> expand(Rational noteDuration, Rational minDuration, Rational maxDuration, int... factors)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns an expansion of the ornament as a list of (scale-step) offsets to the central note. (= the same encoding as in pre, etc.)

      This very simple algorithm prefers the fastest found solution. Other variants can be sensible, which e.g. prefer the most complex or least complex metric structure. This algorithm will fail to find a solution (return null) in many cases. A variant which allows the prolongation of one note (e.g. the very last) would generate much more hits.

      Parameters:
      noteDuration - the overall notated duration of the note carrying this ornament.
      minDuration - the minimal duration for each played note when executing this ornament.
      maxDuration - the maximal duration for each played note when executing this ornament.
      factors - allowed division factors which may be applied to approximate the required repetition count. Eg. [9, 5] allows triplets, triplets in triplets. and 5-plets, while [15, 7] allows triplets and 5-plets, even nested, and 7-plets.

    • getPre

      public int @Opt [] getPre()

    • getRep

      public int @Opt [] getRep()

    • getPost

      public int @Opt [] getPost()

    • doExpand

      protected List<Integer> doExpand(int r)

    • repetitionCounts

      public int[] repetitionCounts(Rational noteDuration, Rational minDuration, Rational maxDuration)

    • expand

      public int expand(Rational noteDuration, Rational minDuration, Rational maxDuration, List<Integer> offsets, List<Rational> durations, int... factors)
      Returns an expansion of the ornament as a list of (scale-step) offsets to the central note (= the same encoding as in pre, etc.) and a list of durations. The middle segment must appear at least once.

      This very simple algorithm prefers the fastest found solution. Other variants can be sensible, which e.g. prefer the most complex or least complex metric structure. This algorithm will fail to find a solution (return null) in many cases. A variant which allows the prolongation of one note (e.g. the very last) would generate much more hits.

      Parameters:
      noteDuration - the overall notated duration of the note carrying this ornament.
      minDuration - the minimal duration for each played note when executing this ornament.
      maxDuration - the maximal duration for each played note when executing this ornament.
      offsets - output data where to place the diatonic offsets of the pitches of the replacement events.
      durations - output data where to place the durations of the replacement events.
      factors - allowed division factors which may be applied to approximate the required repetition count. Eg. [9, 5] allows triplets, triplets in triplets. and 5-plets, while [15, 7] allows triplets and 5-plets, even nested, and 7-plets. If this list is empty, no additional divisions are allowed.
      Returns:
      the number of generated events. Return 0 if no expansion was possible.

    • fill

      protected void fill(List<Integer> offsets, List<Rational> durations, Rational dura, int r)
      Generate the expansion notes. Each has in principle the same duration, but adjacent notes with the same pitch are melted.
      Parameters:
      offsets - container where to put the result, namely the offsets from the central note, measured in diatonic steps.
      durations - container where to put the result, namely the durations.
      dura - the base duration for one single expansion note, notwithstanding melting.
      r - the number how often the central segment is to be repeated. must be positive or zero.