Package org.jjazz.phrase.api

Class Grid

java.lang.Object
org.jjazz.phrase.api.Grid
All Implemented Interfaces:
Cloneable
public class Grid extends Object implements Cloneable
A convenience class to manipulate notes from a Phrase.

The class assigns notes in fixed-sized "cells" (eg 4 cells per beats=1/16) which can then be directly accessed or modified using the cell index.

To accomodate real time playing, notes starting just before a cell are included in that cell, see PRE_CELL_BEAT_WINDOW.

The refresh() method must be called whenever the phrase is modified outside this Grid object.

  • Field Details

    • PRE_CELL_BEAT_WINDOW

      public static float PRE_CELL_BEAT_WINDOW
      Notes whose relative position is > -PRE_CELL_BEAT_WINDOW will be included in the current cell.

  • Constructor Details

    • Grid

      public Grid(Phrase p, FloatRange beatRange, int nbCellsPerBeat, Predicate<NoteEvent> filter)
      Obtain a grid for the specified Phrase p.

      The first cell starts at range.from (range bounds must be integer values). <> The filter parameter can be used to accept only specific Phrase notes.

      If the caller modifies p outside of this grid it must then call Grid.refresh() to keep it up to date.

      Parameters:
      p - Time signature must not change in the phrase.
      beatRange - Grid will contain notes from this beat range, excluding upper bound. Bounds must be integer values.
      nbCellsPerBeat - Must be > 0.
      filter - If null this grid will contain all Phrase notes

  • Method Details

    • clone

      public Grid clone()

    • getPredicate

      public Predicate<NoteEvent> getPredicate()

    • getCellWithMaxNotes

      public int getCellWithMaxNotes()
      Search the cell which contains the maximum of notes and return this cell index.
      Returns:
      -1 if no note in the grid.

    • getOriginalBeatRange

      public FloatRange getOriginalBeatRange()
      The beat range used to create this grid.

      Does NOT take into account the pre-cell beat window.

      Returns:
      See Also:

    • getAdjustedBeatRange

      public FloatRange getAdjustedBeatRange()
      The beat range of this grid adjusted to the pre-cell beat window.
      Returns:
      See Also:

    • getCellRange

      public IntRange getCellRange()
      The cell index range of this object.
      Returns:

    • getCellBeatRange

      public FloatRange getCellBeatRange(int cell)
      The FloatRange corresponding to the specified cell.

      The pre-cell beat window is excluded from the returned range.

      Parameters:
      cell -
      Returns:

    • getCellRange

      public IntRange getCellRange(FloatRange fr, boolean strict)
      Return the cell range based on the specified beat range.
      Parameters:
      fr -
      strict - If true and range is outside the bounds of this grid throw an IllegalArgumentException. Otherwise use the first/last cell of the grid.
      Returns:

    • contains

      public boolean contains(float posInBeats)
      Convenience method which just calls getAdjustedBeatRange(posInBeats, true).
      Parameters:
      posInBeats -
      Returns:

    • getCell

      public int getCell(float posInBeats, boolean strict)
      Return the cell index for specified position.

      Take into account the getPreCellBeatWindow() value.

      Parameters:
      posInBeats -
      strict - If true and posInBeats is not in this grid bounds, throw an IllegalArgumentException. Otherwise use the first or last cell.
      Returns:

    • getNonEmptyCells

      public List<Integer> getNonEmptyCells()
      Get the indexes of the non empty cells.
      Returns:
      List is ordered. Can be empty.

    • isEmpty

      public boolean isEmpty(int cell)
      True if no note in the specified cell.
      Parameters:
      cell -
      Returns:

    • changeDuration

      public void changeDuration(IntRange range, int cellOff, boolean shorterOk, boolean longerOk)
      Change the duration of all notes in specified cell range so that they end at cell cellIndexOff.

      Notes can be shortened or made longer.

      Parameters:
      range - Can be the empty range.
      cellOff - The cell index where notes should go off.
      shorterOk - If false do not make notes shorter. Can't be false if longerOk is false.
      longerOk - If false do not make notes longer. Can't be false if shorterOk is false.

    • changeVelocity

      public void changeVelocity(IntRange range, Function<Integer,Integer> f)
      Modify velocity of notes in the specified cell range.

      Velocity is always maintained in the 0-127 range.

      Parameters:
      range - Can be the empty range.
      f - A function to modify velocity to another velocity.

    • getCellNotes

      public List<NoteEvent> getCellNotes(int cell)
      Get the note of the specified cell.
      Parameters:
      cell -
      Returns:

    • getCellNotes

      public List<NoteEvent> getCellNotes(IntRange range)
      Get the notes in the specified cell range.
      Parameters:
      range - Can be the empty range.
      Returns:
      List has the same note order than the Phrase.

    • getFirstNote

      public NoteEvent getFirstNote(int cell)
      Get the first note of the cell
      Parameters:
      cell -
      Returns:
      Null if no note

    • getFirstNoteCell

      public int getFirstNoteCell(IntRange range)
      Get the cell index of the first note in the specified cell range.
      Parameters:
      range - Can be the empty range.
      Returns:
      -1 if no note found

    • getLastNote

      public NoteEvent getLastNote(int cell)
      Get the last note of the cell
      Parameters:
      cell -
      Returns:
      Null if no note

    • getLastNoteCell

      public int getLastNoteCell(IntRange range)
      Get the cell of the last note in the specified cell range.
      Parameters:
      range - Can be the empty range.
      Returns:
      -1 if no note found

    • removeNotes

      public List<NoteEvent> removeNotes(int cell)
      Convenient method that just return removeNotes(new IntRange(cell, cell)).
      Parameters:
      cell -
      Returns:

    • removeNotes

      public List<NoteEvent> removeNotes(IntRange range)
      Remove all notes in the specified cells range.
      Parameters:
      range - Can be the empty range.
      Returns:
      The removed notes. Can be empty.

    • addNote

      public NoteEvent addNote(int cell, Note n, float relPosInCell)
      Add a new NoteEvent from the parameters.

      Convenience method that add the note to the grid's phrase and calls refresh().

      Parameters:
      cell -
      n - Pitch, duration and velocity are reused to create the NoteEvent.
      relPosInCell - The relative position in beats of the note in the cell. Value must be in the interval [-getPreCellBeatWindow():cellDuration[
      Returns:
      The added note.

    • replaceNote

      public void replaceNote(NoteEvent oldNote, NoteEvent newNote)
      Replace a note by another one at same position.

      The 2 notes must have the same position.

      Parameters:
      oldNote -
      newNote -

    • moveNotes

      public int moveNotes(int cellFrom, int cellTo, boolean keepNoteOffPosition)
      Move all notes from one cell to another.
      Parameters:
      cellFrom - The index of the cell containing the notes to be moved.
      cellTo - The index of the destination cell
      keepNoteOffPosition - If true AND notes are moved earlier (cellIndexFrom > cellIndexDest), extend the duration of the moved notes so they keep the same NOTE_OFF position.
      Returns:
      The number of moved notes

    • moveFirstNote

      public boolean moveFirstNote(int cellFrom, int cellTo, boolean keepNoteOffPosition)
      Move the first note of cellIndexFrom to another cell.
      Parameters:
      cellFrom - The index of the cell containing the note to be moved.
      cellTo - The index of the destination cell
      keepNoteOffPosition - If true AND note is moved earlier (cellIndexFrom > cellIndexDest), extend the duration of the moved note so it keeps the same NOTE_OFF position.
      Returns:
      True if a note was moved.

    • stopNotesBefore

      public int stopNotesBefore(int cell)
      Force all sounding notes to stop (eg shorten their duration) at the start of the specified cell.
      Parameters:
      cell -
      Returns:
      The number of notes which have been shortened.
      See Also:

    • getPreCellBeatWindow

      public float getPreCellBeatWindow()
      The time window before the start of a cell we consider to be part of the cell.

      This is used to accomodate real time playing notes which may start just before a cell.

      Returns:
      A duration in beats

    • getPhrase

      public Phrase getPhrase()
      Returns:
      the phrase

    • getNbCellsPerBeat

      public int getNbCellsPerBeat()
      Returns:
      A value > 0

    • getStartPos

      public float getStartPos(int cell)
      The position in beats of the start of the specified cell.

      Note that some notes may belong to a cell even if their position is lower than the value returned by getStartPos(), see getPreCellBeatWindow().

      Parameters:
      cell -
      Returns:

    • refresh

      public final void refresh()
      Update the internal data structure: should be called whenever Phrase is modified externally.

      Manage the fact that a note can be included in a cell if its start position is just before the cell.

      See Also:

    • toString

      public String toString(int cellFrom, int cellTo)
      Parameters:
      cellFrom - If out of bound use 0
      cellTo - If out of bound use lastCell
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getRecommendedNbCellsPerBeat

      public static int getRecommendedNbCellsPerBeat(TimeSignature ts, boolean isTernary)
      Get the recommended nb of cells for the specified parameters.
      Parameters:
      ts -
      isTernary -
      Returns:
      3 or 4