Package eu.bandm.music.entities

Class MTree

java.lang.Object
eu.bandm.music.entities.MTree_<MTree>
eu.bandm.music.entities.MTree
All Implemented Interfaces:
MetrumIndication
public class MTree extends MTree_<MTree>
Each instance has been created from a MTreeSpec by install(MTreeSpec,MTree.CheckedParameters). It is dynamic, since new subnodes and alternatives can be added, e.g. when MSplitter requests new divisions and alternatives.

It maintains additionally the configuration parameters for "essential" proportional brackets and flags/beams.

Additionally each instance holds ("quasi-transient") constant cache fields for the work of MCover/MSplitter.

  • Field Details

    • parent

      @Opt @Opt MTree parent
      The parent node of this tree node. Can be ==null only for the topmost node.

    • position

      int position
      Position of "this" in the parent's list, starting from zero(0).

    • start

      @Opt @Opt Rational start
      The start time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1". The topmost node is that for which MTreeSpec.initialize(eu.bandm.tscore.base.Modifiers.Reaction,MessageReceiver) and install(MTreeSpec,MTree.CheckedParameters) have been called. Can be ==null in a specification and will be calculated by the constraints imposed by parents and siblings, etc. Must be !=null after installing and in every instance of MTree.

    • end

      @Opt @Opt Rational end
      The end time of the time interval (of a measure) represented by this node, relative to the start of the topmost node, which is fixed as "0/1". The topmost node is that for which MTreeSpec.initialize(eu.bandm.tscore.base.Modifiers.Reaction,MessageReceiver) and install(MTreeSpec,MTree.CheckedParameters) have been called. Is always ==null in a specification and will be filled by the constraints imposed by parents and siblings, etc. Must be !=null after installing and in every instance of MTree.

    • implicit

      boolean implicit
      Whether this node has been created automatically, by implict division into halfs.

    • parameters

      MTree.CheckedParameters parameters
      Parameters for the automated insertion of essential brackets and for the selection of beams, beamlets and flags. Set once by install(MTreeSpec,CheckedParameters).

    • bracketStart

      @Opt @Opt MTree.EssentialBracket bracketStart
      The essential bracket starting with this node and required to write its own duration. May expand over subsequent siblings, iff they have the same duration, thus requiring the same proportion. Is set by collectBrackets_topLevel(), which is called in initialization.

    • bracketCont

      @Opt @Opt MTree.EssentialBracket bracketCont
      The essential bracket not starting with this node but covering it on its definition level. Is set by collectBrackets_topLevel(), which is called in initialization. ATTENTION only used in that initialization phase. FIXME STIMMT NICHT !!! CHECK !! FIXME make private, and so ALL OTHER FIELDS !!!

    • synthetic

      boolean synthetic
      Whether this node comes from an spontantuous division when rendering a given rhythm.

    • printable_sound

      @Opt @Opt MTree.Printable printable_sound
      Single duration symbol or sequence of symbols for to print a sound which exactly covers this node. Is initialized by init_printables(Rational) if e-writable; else eventually later by add_free_sectioning(Rational,boolean,msplitter)

    • printable_pause

      @Opt @Opt MTree.Printable printable_pause
      Single duration symbol or sequence of symbols for to print a pause which exactly covers this node. Is initialized by init_printables(Rational) if e-writable; else eventually later by add_free_sectioning(Rational,boolean,msplitter)

    • flagCount

      int flagCount
      Number of flags or beams to notate the duration of the node. (Only makes sense if notatable in one symbol). Filled once by install(MTreeSpec,CheckedParameters). Only needed as a START VALUE for collect_genuine_beams().

    • NOFLAGSFOUND

      public static final int NOFLAGSFOUND
      Value entered in flagCount if this is not applicable = the node is not writeable in one single symbol.
      See Also:

    • genStemEnd

      @Opt @Opt StemEnd genStemEnd
      Number of beams/beamlets to the left/right. (Only makes sense if notatable in one symbol). Filled once by install(MTreeSpec,CheckedParameters).

    • level

      protected int level
      The distance from the toplevel node, which is ==0, counting towards neg inf.

    • weight

      protected int weight
      Metric weight, equal to level but for the first sibling, for which is equal to parent's "weight".

  • Method Details

    • visibleFlags

      protected int visibleFlags()
      Return only positive values of flagCount.

    • install

      public static MTree install(MTreeSpec mt, MTree.CheckedParameters params)
      Only factory method for a user to create an MTree. The MTreeSpec is deep-copied to an MTree, a reference to the parameters is stored in the MTree. Then all duration value specifications are completed, checked and distributed. Then for each sub-node "Essential Brackets" are constructed and memorized, and maybe single symbols for sound and pause separately. (There may be different allowances for prolongation dots.)

    • cloneAsAlternative

      MTree cloneAsAlternative()
      Copying constructor. Only called by MCover for synthetic alternatives. Not all fields are copied. @see #copyTo(MTree)

    • self

      protected MTree self()
      Necessary to avoid "unchecked cast" warning when returning "this" instance in the parameterized superclass MTree_.
      Specified by:
      self in class MTree_<MTree>

    • numeratorByMenoList

      static int numeratorByMenoList(int denom, @Opt @Opt Set<Integer> menoSet)
      Determine the numerator of an EssentialBracket by the parameter parameters.values.MetricParameters.MTreeParameters.proportiones_lentiores. Normally a proportion makes the notes play FASTER, like in "7:4". But "7:8" may also be sensibe. This set contains the threshold from which on behaviour changes. If e.g. "6" is contained in the set, then we get "5:4" but "6:8" and "7:8".

    • collectBrackets_topLevel

      protected void collectBrackets_topLevel()
      Service provider which calculates all essential brackets. Is called only once from MTree installation only for this as the top-level node.

    • collectBrackets

      protected void collectBrackets(@Opt @Opt MTree.EssentialBracket predecBracket, PrimeFactors parentFactors)
      Calculation of essential brackets for all nodes below the top node of a MTree, calls itself recursively.

      Operation: Step through all child nodes of this node: For the longest sequence of equal durations create a EB iff that duration introduces a new prime factor in the denominator, compared to "parentFactors".
      Execute recursively for all child nodes.

      Not supported: automated sectioning of over-complete brackets as from 

        5/12
  |--------3:2------|
    |\ |\ |\    |\ |\     
    x  x  x     x  x
      into 
        5/12
  ,---3:2---, ,--3:2--,
    |\ |\ |\    |\ |\     
    x  x  x     x  x
      Instead, this can/must currently be done explicitly on the MTreeSpec level, e.g. by replacing "5*1/12" with "3*1/12+2*1/12".

      Not yet supported: renamed brackets: 

      
   ,------------- 3:2 ------------,
    |          |         |
    x          x         x
   ,------------- 9:8 ------------,
    |\ |\ |\   |\ |\ |\  |\ |\ |\ 
    x  x  x    x  x  x   x  x  x

      Now supported: vanishing brackets. A VB is a bracket of some parent node which will show up only when this node as such is printed, but not when its child nodes are printed, because not all of these share the new denominator factor. (In other words: some child nodes need this factor and sum up with simpler durations of their neighbours to a sum with this factor. Of course this may happen not in very conventional sheet music, but frequently in avantgardistic notation styles, ethnological transcriptions, bird songs. etc.)
      Example: 

         [1/3-------->  1/3------->]
   
    ,--3:2--,        ,-3:2-,  
     |            |    |\     
    o             x    x      

  may vanish to:

       ,-3:2-,       ,-3:2-,  
    |    |\           |    |\     
    x    x        x    x      


   or
   
   [5/12-------->]
  ,---3:2---,  
    |      |\
   o______x      

  may become              or  (LATER FIXME Convenience brackets:)

         ,-3:2-,       .----5:4---; ,-3:2-, 
    |      |             = = = =     | 
    x      x            | | | | |    |
                        x x x x x    x
      Parameters:
      predecBracket - the next higher (relevant, non-vanishing) bracket covering this node.
      parentFactors - the odd denominator factors already imposed by all non-vanishing brackets of the higher node levels.

    • testForVanishing

      protected boolean testForVanishing(PrimeFactors rulingDenominator)
      If one of the sub-nodes has a simpler denominator than the bracket factor, this bracket is "vanishing".

    • makeBracket

      protected void makeBracket(@Opt @Opt MTree.EssentialBracket predec, PrimeFactors factors, PrimeFactors effectiveDenomFactors, int startPos, int endPos)
      Possibly make a new MTree.EssentialBracket covering the given sub-range of child nodes and link it to all those by the fields bracketStart and bracketCont. Is only called by the recursive descent in collectBrackets(EssentialBracket,PrimeFactors).
      Parameters:
      predec - the next higher (relevant, non-vanishing) bracket covering this node.
      factors - the new factors which shall be introduced by this EB
      startPos - the number of the first child node to cover.
      endPos - the number of the first child which is after the bracket (needs not to exist)

    • linkBracket

      protected void linkBracket(MTree.EssentialBracket eb, int startPos, int endPos)
      Enter the bracket into the fields bracketStart and bracketCont of all childs of this node, in the given range of indexes.
      Parameters:
      eb - the EB
      startPos - index of the first child
      endPos - index of the first child which is after the bracket (needs not to exist)

    • lowestEB

      @Opt public @Opt MTree.EssentialBracket lowestEB()
      Look for the lowest EssentialBracket spannung this node. Steps upward through the chain of parent nodes for the first EB.

    • lowestNonVanishingEB

      @Opt public @Opt MTree.EssentialBracket lowestNonVanishingEB()

    • totalEBProportion

      public Rational totalEBProportion()
      Deliver product of all proportions valid for this node. This is cached in the lowest EB spanning this node, returned by directEB() or lowestNonVanishingEB() If this is ==null, then the proportion is Rational.ONE.

    • directEB

      @Opt public @Opt MTree.EssentialBracket directEB()
      Look for the EssentialBracket directly spanning this node. (= entered in bracketStart or bracketCont.

    • requiredBracketFactor

      @Opt protected @Opt Rational requiredBracketFactor(int parentEnum, int childCount)
      FIXME NOT YET USED! Unify "collectBrackets()", calculate beams and x_divide().
      Calculates the factor required for a sequence of adjacent child nodes. The odd factor of the denominator of the parent is already realized by some EB on a higher level. Therefore here only the odd factors in "parentNumerator" and in "childCount" must be considered.
      Eg., no bracket is required required when dividing a node of duration 5/16 by 5 or 15/17 by 3. 
              odd                           odd              1         newChildNodeCount
 rPf =  ---         rPf = 1    rPf =  ---       rPf = ---       --------------------
        odd                            1              odd      enumOfDurOfParentNode

    • get_position

      public int get_position()
      Position in the parents' list, starting from zero(0).

    • coordinate

      public String coordinate()
      Position in the whole tree, but NOT indicating the alternatives !?! FIXME

    • get_implicit

      public boolean get_implicit()
      Whether this has been created explicitly, or by implicit division by two

    • get_parent

      @Opt public @Opt MTree get_parent()
      Return the parent node.

    • getTopNode

      public MTree getTopNode()
      Get the top most node to which this node is linked as a descendant.

    • get_start

      public Rational get_start()
      Get the start time point value.

    • get_end

      public Rational get_end()
      Get the end time point value.

    • isLast

      public boolean isLast()
      Returns whether this node has no parent or is the last child of its parent.

    • isFollowingSiblingOf

      public boolean isFollowingSiblingOf(MTree predec)
      Returns whether this node is child of the same parent as the argument, and one position further.

    • getFollowingSibling

      @Opt public @Opt MTree getFollowingSibling()
      Returns the node which is child of the same parent, and one position further, iff it exists, otherwise null.
      ATTENTION: There may be alternative nodes, accessible by MTree_.alternative, which have a different structure, but the same duration.

    • getPrecedingSibling

      @Opt public @Opt MTree getPrecedingSibling()
      Returns the node which is child of the same parent, and one position earlier, iff it exists, otherwise null.
      ATTENTION: There may be alternative nodes, accessible by MTree_.alternative, which have a different structure, but the same duration.

    • get_subs_binary

      public void get_subs_binary()
      Creates a sub-tree with a division factor of two(2), iff no children currently exist. This mirrors the default division by two(2) implicitly allowed for every node in CWN. Called only by MCover.doFC_bin(MTree) and MCover.makeSyntheticAlternative(MTree,int).
      Throws:
      IllegalStateException - if the node is already divided other than equidist by two.

    • divide_new_subs

      void divide_new_subs(int num)
      Adds a number of equidistant sub-trees. ONLY used when synthesizing new subnode divisions by MCover. ASSUME only called with this being a FRESH instance, as a synthetic node, which is required because such a division does not exist. Called as such by MCover.

    • calcStartEnd

      protected void calcStartEnd(Rational start)
      Recursive function for calculating start, end and MTree_.equidist. Assume that all MTree_.duration fields of all visited nodes are set.
      Parameters:
      start - the start time point of this node, relative to the start of the top-most node, which represents a complete measure.

    • smoothen

      protected void smoothen(int[] values)
      The smaller value will be doubled until the absolute distance to the larger is minimal. If equidistant, the lower variant is returned: 2,3,4 delivers 2; 8,12,16 delivers 8.
      Parameters:
      values - two different integers. The smaller of both will be replaced by the result of x_smoothen(int,int).

    • x_smoothen

      protected int x_smoothen(int lower, int upper)
      The smaller value will be doubled until the absolute distance to the larger is minimal. If equidistant, the lower variant is returned: 2,3,4 delivers 2; 8,12,16 delivers 8. (Currently only called by requiredBracketFactor(int,int) and x_divide(int,boolean,boolean).)

    • add_free_sectioning

      void add_free_sectioning(Rational duration, boolean isSound, MSplitter msplitter)
      Convert a node into one or more notation symbols. Duration is the "written duration", before the current effective n-plet factors are applied. If the duration is e-writable, a symbol (of type RationalDuration.DottedBaseDuration) has already been stored with the node, different for sound and pause, and this method MUST NOT be called. Otherwise a free sectioning is constructed, its beams are calculated, and stored into the corresponding filed printable_sound and printable_pause. The results depend on parameter values, thus the corresponding cache is maintained with the MSplitter.

    • collect_genuine_beams

      protected void collect_genuine_beams()
      Generate beam information for all sub-nodes and for alternatives. Assume the genStemEnd (=the stem end for the node itself) has already been set (for the top-level node by "install()", for all others by recursive call). Only called from install(MTreeSpec,CheckedParameters) for initial MTree generation, and from x_divide(int,boolean,boolean), whenever later expanding the MTree. (The very top mtree node has only "flags" set, as in a meter called "1/8".

    • do_collect_genuine_beams

      protected void do_collect_genuine_beams(StemEnd se_parent, List<MTree> subtrees)