ls_handleTouches.ino

/*********************** ls_handleTouches: LinnStrument Handle Touch Events ***********************
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/
or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
***************************************************************************************************
These routines handle the processing of new touch events, continuous updates of touch events and
released touch events
**************************************************************************************************/

void cellTouched(TouchState state) {
  cellTouched(sensorCol, sensorRow, state);
};
void cellTouched(byte col, byte row, TouchState state) {
  // turn on the bit that correspond to the column and row of this cell,
  // this allows us to very quickly find other touched cells and detect
  // phantom key presses without having to evaluate every cell on the board
  if (state != untouchedCell &&
      state != transferCell) {
    // keep track of how many cells are currently touched
    if (!(rowsInColsTouched[col] & (int32_t)(1 << row))) {
      cellsTouched++;
    }

    // flip the bits to indicate that this cell is now touched
    rowsInColsTouched[col] |= (int32_t)(1 << row);
    colsInRowsTouched[row] |= (int32_t)(1 << col);
  }
  // if the state is untouched, turn off the appropriate bit in the
  // bitmasks that track the touched cells
  else {
    // keep track of how many cells are currently touched
    if ((rowsInColsTouched[col] & (int32_t)(1 << row))) {
      cellsTouched--;
    }

    // flip the bits to indicate that this cell is now untouched
    rowsInColsTouched[col] &= ~(int32_t)(1 << row);
    colsInRowsTouched[row] &= ~(int32_t)(1 << col);
  }
  
  // save the touched state for each cell
  cell(col, row).touched = state;
}

#define TRANSFER_SLIDE_PROXIMITY 100

byte countTouchesForMidiChannel(byte split, byte col, byte row) {
  if (!cell(col, row).hasNote()) {
    return 0;
  }

  return noteTouchMapping[split].getMusicalTouchCount(cell(col, row).channel);
}

const int32_t PENDING_RELEASE_RATE_X = FXD_FROM_INT(5);

boolean potentialSlideTransferCandidate(byte col) {
  if (controlModeActive) return false;
  if (col < 1) return false;
  if (userFirmwareActive) {
    if (!userFirmwareSlideMode[sensorRow]) return false;
  }
  else if (Split[Global.currentPerSplit].sequencer) {
    if (!requiresSequencerSlideTracking()) return false;
  }
  else {
    if (sensorSplit != getSplitOf(col)) return false;
    if (!isLowRow() &&                                                   // don't perform slide transfers
        (!Split[sensorSplit].sendX ||                                    // if pitch slides are disabled
         !isFocusedCell(col, sensorRow) ||                               // if this is not a focused cell
         countTouchesForMidiChannel(sensorSplit, col, sensorRow) > 1)) { // when there are several touches for the same MIDI channel
      return false;
    }
    if (isLowRow() && !lowRowRequiresSlideTracking()) return false;
    if (isStrummingSplit(sensorSplit)) return false;
  }

  if (cell(col, sensorRow).pendingReleaseCount &&                        // if there's a pending release but not enough X change
      cell(col, sensorRow).fxdRateX <= PENDING_RELEASE_RATE_X) {
    return false;
  }

  return cell(col, sensorRow).touched != untouchedCell &&                                                    // the sibling cell has an active touch
    (cell(col, sensorRow).pendingReleaseCount ||                                                             // either a release is pending to be performed, or
     abs(sensorCell->calibratedX() - cell(col, sensorRow).currentCalibratedX) < TRANSFER_SLIDE_PROXIMITY);   // both cells are touched simultaneously on the edges
}

boolean isReadyForSlideTransfer(byte col) {
  return cell(col, sensorRow).pendingReleaseCount ||                 // there's a pending release waiting
    sensorCell->currentRawZ > cell(col, sensorRow).currentRawZ;      // the cell pressure is higher
}

boolean hasImpossibleX() {             // checks whether the calibrated X is outside of the possible bounds for the current cell
  return Device.calibrated &&
    (sensorCell->calibratedX() < FXD_TO_INT(Device.calRows[sensorCol][0].fxdReferenceX - FXD_CALX_PHANTOM_RANGE) ||
     sensorCell->calibratedX() > FXD_TO_INT(Device.calRows[sensorCol][0].fxdReferenceX + FXD_CALX_PHANTOM_RANGE));
}

void transferFromSameRowCell(byte col) {
  TouchInfo* fromCell = &cell(col, sensorRow);

  sensorCell->lastTouch = fromCell->lastTouch;
  sensorCell->didMove = fromCell->didMove;
  sensorCell->initialX = fromCell->initialX;
  sensorCell->initialColumn = fromCell->initialColumn;  
  sensorCell->quantizationOffsetX = 0; // as soon as we transfer to an adjacent cell, the pitch quantization is reset to play the absolute pitch position instead
  sensorCell->lastMovedX = fromCell->lastMovedX;
  sensorCell->fxdRateX = fromCell->fxdRateX;
  sensorCell->fxdRateCountX = fromCell->fxdRateCountX;
  sensorCell->slideTransfer = true;
  sensorCell->rogueSweepX = fromCell->rogueSweepX;
  sensorCell->initialY = fromCell->initialY;
  sensorCell->note = fromCell->note;
  sensorCell->channel = fromCell->channel;
  sensorCell->octaveOffset = fromCell->octaveOffset;
  sensorCell->fxdPrevPressure = fromCell->fxdPrevPressure;
  sensorCell->fxdPrevTimbre = fromCell->fxdPrevTimbre;
  sensorCell->velocity = fromCell->velocity;
  sensorCell->vcount = fromCell->vcount;
  noteTouchMapping[sensorSplit].changeCell(sensorCell->note, sensorCell->channel, sensorCol, sensorRow);

  fromCell->lastTouch = 0;
  fromCell->didMove = false;
  fromCell->initialX = INVALID_DATA;
  fromCell->initialColumn = -1;
  fromCell->quantizationOffsetX = 0;
  fromCell->lastMovedX = 0;
  fromCell->fxdRateX = 0;
  fromCell->fxdRateCountX = 0;
  fromCell->slideTransfer = true;
  fromCell->rogueSweepX = false;
  fromCell->initialY = -1;
  fromCell->pendingReleaseCount = 0;

  fromCell->note = -1;
  fromCell->channel = -1;
  fromCell->octaveOffset = 0;
  fromCell->fxdPrevPressure = 0;
  fromCell->fxdPrevTimbre = FXD_CONST_255;
  fromCell->velocity = 0;
  // do not reset vcount!

  signed char channel = sensorCell->channel;
  if (channel > 0 && col == focus(sensorSplit, channel).col && sensorRow == focus(sensorSplit, channel).row) {
    focus(sensorSplit, channel).col = sensorCol;
    focus(sensorSplit, channel).row = sensorRow;
  }
}

void transferToSameRowCell(byte col) {
  TouchInfo* toCell = &cell(col, sensorRow);
  
  toCell->lastTouch = sensorCell->lastTouch;
  toCell->didMove = sensorCell->didMove;
  toCell->initialX = sensorCell->initialX;
  toCell->initialColumn = sensorCell->initialColumn;
  toCell->quantizationOffsetX = 0; // as soon as we transfer to an adjacent cell, the pitch quantization is reset to play the absolute pitch position instead
  toCell->lastMovedX = sensorCell->lastMovedX;
  toCell->fxdRateX = sensorCell->fxdRateX;
  toCell->fxdRateCountX = sensorCell->fxdRateCountX;
  toCell->slideTransfer = true;
  toCell->rogueSweepX = sensorCell->rogueSweepX;
  toCell->initialY = sensorCell->initialY;
  toCell->note = sensorCell->note;
  toCell->channel = sensorCell->channel;
  toCell->octaveOffset = sensorCell->octaveOffset;
  toCell->fxdPrevPressure = sensorCell->fxdPrevPressure;
  toCell->fxdPrevTimbre = sensorCell->fxdPrevTimbre;
  toCell->velocity = sensorCell->velocity;
  toCell->vcount = sensorCell->vcount;
  noteTouchMapping[sensorSplit].changeCell(toCell->note, toCell->channel, col, sensorRow);

  sensorCell->lastTouch = 0;
  sensorCell->didMove = false;
  sensorCell->initialX = INVALID_DATA;
  sensorCell->initialColumn = -1;
  sensorCell->quantizationOffsetX = 0;
  sensorCell->lastMovedX = 0;
  sensorCell->fxdRateX = 0;
  sensorCell->fxdRateCountX = 0;
  sensorCell->slideTransfer = true;
  sensorCell->rogueSweepX = false;
  sensorCell->initialY = -1;
  sensorCell->pendingReleaseCount = 0;

  sensorCell->note = -1;
  sensorCell->channel = -1;
  sensorCell->octaveOffset = 0;
  sensorCell->fxdPrevPressure = 0;
  sensorCell->fxdPrevTimbre = FXD_CONST_255;
  sensorCell->velocity = 0;
  // do not reset vcount!

  signed char channel = toCell->channel;
  if (channel > 0 && sensorCol == focus(sensorSplit, channel).col && sensorRow == focus(sensorSplit, channel).row) {
    focus(sensorSplit, channel).col = col;
    focus(sensorSplit, channel).row = sensorRow;
  }
}

boolean isPhantomTouchIndividual() {
  // when the device is calibrated we fully rely on the plausability of the X readings to determine
  // if a touch is a phantom touch or not
  if (Device.calibrated) {
    if (hasImpossibleX()) {
      sensorCell->setPhantoms(sensorCol, sensorCol, sensorRow, sensorRow);
      return true;
    }
  }
  return false;
}

boolean isPhantomTouchContextual() {
  // check if this is a potential corner of a rectangle to filter out ghost notes, this first check matches
  // any cells that have other cells on the same row and column, so it's not sufficient by itself, but it's fast
  int32_t rowsInSensorColTouched = rowsInColsTouched[sensorCol] & ~(int32_t)(1 << sensorRow);
  int32_t colsInSensorRowTouched = colsInRowsTouched[sensorRow] & ~(int32_t)(1 << sensorCol);
  if (rowsInSensorColTouched && colsInSensorRowTouched) {

    // now we check each touched row in the column of the current sensor
    // we gradually flip the touched bits to zero until they're all turned off
    // this allows us to loop only over the touched rows, and none other
    while (rowsInSensorColTouched) {
      // we use the ARM Cortex-M3 instruction that reports the leading bit zeros of any number
      // we determine that the left-most bit is that is turned on by substracting the leading zero
      // count from the bitdepth of a 32-bit int
      byte touchedRow = 31 - __builtin_clz(rowsInSensorColTouched);

      // for each touched row we also check each touched column in the row of the current sensor
      int32_t colsInRowTouched = colsInSensorRowTouched;

      // we use the same looping approach as explained for the rows
      while (colsInRowTouched) {

        // we use the same leading zeros approach to dermine the left-most active bit
        byte touchedCol = 31 - __builtin_clz(colsInRowTouched);

        // if we find a cell that has both the touched row and touched column set,
        // then the current sensor completed a rectangle by being the fourth corner
        if (rowsInColsTouched[touchedCol] & (int32_t)(1 << touchedRow)) {

          // since we found four corners, we now have to determine which ones are
          // real presses and which ones are phantom presses, so we're looking for
          // the other corner that was scanned twice to determine which one has the
          // lowest pressure, this is the most likely to be the phantom press
          if ((cell(touchedCol, touchedRow).isHigherPhantomPressure(sensorCell->currentRawZ) &&
               cell(sensorCol, touchedRow).isHigherPhantomPressure(sensorCell->currentRawZ) &&
               cell(touchedCol, sensorRow).isHigherPhantomPressure(sensorCell->currentRawZ))) {

            // store coordinates of the rectangle, which also serves as an indicator that we
            // should stop looking for a phantom press
            cell(sensorCol, sensorRow).setPhantoms(sensorCol, touchedCol, sensorRow, touchedRow);
            cell(touchedCol, touchedRow).setPhantoms(sensorCol, touchedCol, sensorRow, touchedRow);
            cell(sensorCol, touchedRow).setPhantoms(sensorCol, touchedCol, sensorRow, touchedRow);
            cell(touchedCol, sensorRow).setPhantoms(sensorCol, touchedCol, sensorRow, touchedRow);

            return true;
          }
        }

        // turn the left-most active bit off, to continue the iteration over the touched columns
        colsInRowTouched &= ~(1 << touchedCol);
      }

      // turn the left-most active bit off, to continue the iteration over the touched rows
      rowsInSensorColTouched &= ~(1 << touchedRow);
    }
  }
  return false;
}

byte countTouchesInColumn() {
  byte count = 0;
  int32_t rowsInSensorColTouched = rowsInColsTouched[sensorCol];
  if (rowsInSensorColTouched) {
    while (rowsInSensorColTouched) {
      byte touchedRow = 31 - __builtin_clz(rowsInSensorColTouched);
      count++;

      // turn the left-most active bit off, to continue the iteration over the touched rows
      rowsInSensorColTouched &= ~(int32_t)(1 << touchedRow);
    }
  }

  return count;
}

boolean hasOtherTouchInSplit(byte split) {
  for (int r = 0; r < NUMROWS; ++r) {
    int32_t colsInRowTouchedAdapted = colsInRowsTouched[r];
    if (r == sensorRow) {
      colsInRowTouchedAdapted &= ~(int32_t)(1 << sensorCol);
    }

    if (colsInRowTouchedAdapted) {
      // if split is not active and there's a touch on the row, it's obviously in the current split
      if (!Global.splitActive) {
        return true;
      }

      // determine which columns need to be active in the touched row for this to be considered
      // part of either split
      if (split == LEFT && (colsInRowTouchedAdapted & ((int32_t)(1 << Global.splitPoint) - 1))) {
        return true;
      }
      if (split == RIGHT && (colsInRowTouchedAdapted & ~((int32_t)(1 << Global.splitPoint) - 1))) {
        return true;
      }
    }
  }
  return false;
}

boolean hasTouchInSplitOnRow(byte split, byte row) {
  if (colsInRowsTouched[row]) {
    // if split is not active and there's a touch on the row, it's obviously in the current split
    if (!Global.splitActive) {
      return true;
    }

    // determine which columns need to be active in the touched row for this to be considered
    // part of either split
    if (split == LEFT && (colsInRowsTouched[row] & ((int32_t)(1 << Global.splitPoint) - 1))) {
      return true;
    }
    if (split == RIGHT && (colsInRowsTouched[row] & ~((int32_t)(1 << Global.splitPoint) - 1))) {
      return true;
    }
  }

  return false;
}

void handleSlideTransferCandidate(byte siblingCol) {
  // if the pressure gets higher than adjacent cell, the slide is transitioning over
  if (isReadyForSlideTransfer(siblingCol)) {
    transferFromSameRowCell(siblingCol);
 
    // if a slide transfer happened, but the pitch hold was still quantized, reset the
    // X rate and threshold exceed count so that the real X position will be used as soon as
    // the transfer cell is active, this makes the onset of slides from a stationary position
    // smoother when quantize hold is on
    if (fxdRateXThreshold[sensorSplit] - sensorCell->fxdRateX > 0) {
      sensorCell->fxdRateX = fxdRateXThreshold[sensorSplit];
      sensorCell->fxdRateCountX = 0;
    }

    if (userFirmwareActive) {
      // if user firmware is active, we implement a particular transition scheme to allow touches to be tracked over MIDI
      sensorCell->note = sensorCol;
      midiSendControlChange(119, siblingCol, sensorCell->channel, true);
      midiSendNoteOn(LEFT, sensorCol, sensorCell->velocity, sensorCell->channel);
      midiSendNoteOffWithVelocity(LEFT, siblingCol, sensorCol, sensorCell->channel);
    }
    else {
      if (Split[sensorSplit].colorPlayed && Split[sensorSplit].playedTouchMode == playedCell) {
        setLed(siblingCol, sensorRow, COLOR_OFF, cellOff, LED_LAYER_PLAYED);
        if (cell(sensorCol, sensorRow).hasNote()) {
          setLed(sensorCol, sensorRow, Split[sensorSplit].colorPlayed, cellOn, LED_LAYER_PLAYED);
        }
      }
    }

    if (cell(siblingCol, sensorRow).touched != untouchedCell) {
      cellTouched(siblingCol, sensorRow, transferCell);
    }
    
    handleXYZupdate();
  }
  // otherwise act as if this new touch never happend
  else {
    cellTouched(transferCell);
  }
}

boolean handleNewTouch() {
  DEBUGPRINT((1,"handleNewTouch"));
  DEBUGPRINT((1," col="));DEBUGPRINT((1,(int)sensorCol));
  DEBUGPRINT((1," row="));DEBUGPRINT((1,(int)sensorRow));
  DEBUGPRINT((1," velocityZ="));DEBUGPRINT((1,(int)sensorCell->velocityZ));
  DEBUGPRINT((1," pressureZ="));DEBUGPRINT((1,(int)sensorCell->pressureZ));
  DEBUGPRINT((1,"\n"));

  lastTouchMoment = millis();
  
  // if the touches are restricted to a particular row, any touch outside this row is ignored
  if (restrictedRow != -1 && sensorRow != restrictedRow) {
    cellTouched(ignoredCell);
    return false;
  }

  // allow any new touch to cancel scrolling
  if (animationActive) {
    stopAnimation = true;
    cellTouched(ignoredCell);
    return false;
  }

  // any touch will wake up LinnStrument again, and should be ignored
  if (displayMode == displaySleep) {
    cellTouched(ignoredCell);
    setDisplayMode(displayNormal);
    updateDisplay();
    return false;
  }

  boolean result = false;

  cellTouched(touchedCell);                                 // mark this cell as touched

  // if it's a command button, handle it
  if (sensorCol == 0) {
    if (controlModeActive) {
      switchSerialMode(false);
      return false;
    }
    
    // check if we should activate sleep mode
    if ((sensorRow == GLOBAL_SETTINGS_ROW && cell(0, PER_SPLIT_ROW).touched == touchedCell) ||
        (sensorRow == PER_SPLIT_ROW && cell(0, GLOBAL_SETTINGS_ROW).touched == touchedCell)) {
      activateSleepMode();
      return false;
    }

    // user firmware mode only handles the global settings command button
    if (!userFirmwareActive || sensorRow == GLOBAL_SETTINGS_ROW) {
      if (sensorRow != SWITCH_1_ROW &&                        // if commands buttons are pressed that are not the two switches
          sensorRow != SWITCH_2_ROW) {                        // only activate them if there's note being played on the playing surface
        for (int r = 0; r < NUMROWS; ++r) {                   // this prevents accidental settings modifications while playing
          if ((colsInRowsTouched[r] & ~(int32_t)(1)) != 0) {
            cellTouched(ignoredCell);
            return false;
          }
        }
      }
      handleControlButtonNewTouch();
    }
  }
  else {                                                    // or if it's in column 1-25...
    switch (displayMode)
    {
      case displaySplitPoint:                                 // if the Split button is held, this touch changes the split point
        if (splitButtonDown) {
          handleSplitPointNewTouch();
          break;
        }
        // If we get here, we're displaying in displaySplitPoint mode, but we've just gotten a normal new touch.
        // THE FALL THROUGH HERE (no break statement) IS PURPOSEFUL!

      case displayNormal:                                            // it's normal performance mode
      case displayVolume:                                            // it's a volume change

        // check if the new touch could be an ongoing slide to the right
        if (potentialSlideTransferCandidate(sensorCol-1)) {
          handleSlideTransferCandidate(sensorCol-1);
        }
        // check if the new touch could be an ongoing slide to the left
        else if (potentialSlideTransferCandidate(sensorCol+1)) {
          handleSlideTransferCandidate(sensorCol+1);
        }
        // only allow a certain number of touches in a single column to prevent cross talk
        else if (countTouchesInColumn() > MAX_TOUCHES_IN_COLUMN) {
          cellTouched(ignoredCell);
        }
        // this is really a new touch without any relationship to an ongoing slide
        // however, it could be the low row and in certain situations it doesn't allow new touches
        else if (!isLowRow() || allowNewTouchOnLowRow()) {
          initVelocity();
          calcVelocity(sensorCell->velocityZ);
          result = true;
        }
        else {
          cellTouched(untouchedCell);
        }

        break;
      default:
        initVelocity();
        calcVelocity(sensorCell->velocityZ);
        result = true;
        break;
    }
  }

  return result;
}

// Calculate the transposed note number for the current cell by taken the transposition settings into account
short cellTransposedNote(byte split) {
  return transposedNote(split, sensorCol, sensorRow);
}

short transposedNote(byte split, byte col, byte row) {
  return getNoteNumber(split, col, row) + Split[split].transposePitch + Split[split].transposeOctave;
}

// Check if the currently scanned cell is a focused cell
boolean isFocusedCell() {
  return isFocusedCell(sensorCol, sensorRow);
}

// Check if a specific cell is a focused cell
boolean isFocusedCell(byte col, byte row) {
  if (cell(col, row).channel < 1) {
    return false;
  }

  FocusCell& focused = focus(getSplitOf(col), cell(col, row).channel);
  return col == focused.col && row == focused.row;
}

// Check if X expression should be sent for this cell
boolean isXExpressiveCell() {
  return isFocusedCell();
}

boolean isXExpressiveCell(byte col, byte row) {
  return isFocusedCell(col, row);
}

// Check if Y expression should be sent for this cell
boolean isYExpressiveCell() {
  if (Split[sensorSplit].expressionForY == timbrePolyPressure) {
    return true;
  }
  else {
    return isFocusedCell();
  }
}

// Check if Z expression should be sent for this cell
boolean isZExpressiveCell() {
  if (Split[sensorSplit].expressionForZ == loudnessPolyPressure) {
    return true;
  }
  else {
    return isFocusedCell();
  }
}

byte takeChannel(byte split, byte row) {
  switch (Split[split].midiMode)
  {
    case channelPerNote:
    {
      return splitChannels[split].take();
    }

    case channelPerRow:
    {
      byte channel = Split[split].midiChanPerRow;
      if (Split[split].midiChanPerRowReversed) {
        channel += (NUMROWS - 1) - row;
      }
      else {
        channel += row;
      }
      if (channel > 16) {
        channel -= 16;
      }
      return channel;
    }

    case oneChannel:
    default:
    {
      return Split[split].midiChanMain;
    }
  }
}

void handleNonPlayingTouch() {
  switch (displayMode) {
    case displayNormal:
    case displaySplitPoint:
    case displayVolume:
    case displayReset:
    case displayAnimation:
    case displaySleep:
      // handled elsewhere
      break;
    case displayPerSplit:
      handlePerSplitSettingNewTouch();
      break;
    case displayPreset:
      handlePresetNewTouch();
      break;
    case displayBendRange:
      handleBendRangeNewTouch();
      break;
    case displayLimitsForY:
      handleLimitsForYNewTouch();
      break;
    case displayCCForY:
      handleCCForYNewTouch();
      break;
    case displayInitialForRelativeY:
      handleInitialForRelativeYNewTouch();
      break;
    case displayLimitsForZ:
      handleLimitsForZNewTouch();
      break;
    case displayCCForZ:
      handleCCForZNewTouch();
      break;
    case displayPlayedTouchModeConfig:
      handlePlayedTouchModeNewTouch();
      break;
    case displayCCForFader:
      handleCCForFaderNewTouch();
      break;
    case displayLowRowCCXConfig:
      handleLowRowCCXConfigNewTouch();
      break;
    case displayLowRowCCXYZConfig:
      handleLowRowCCXYZConfigNewTouch();
      break;
    case displayCCForSwitchCC65:
      handleCCForSwitchCC65ConfigNewTouch();
      break;
    case displayCCForSwitchSustain:
      handleCCForSwitchSustainConfigNewTouch();
      break;
    case displayCustomSwitchAssignment:
      handleCustomSwitchAssignmentConfigNewTouch();
      break;
    case displayLimitsForVelocity:
      handleLimitsForVelocityNewTouch();
      break;
    case displayValueForFixedVelocity:
      handleValueForFixedVelocityNewTouch();
      break;
    case displaySleepConfig:
      handleSleepConfigNewTouch();
      break;
    case displaySplitHandedness:
      handleSplitHandednessNewTouch();
      break;
    case displayRowOffset:
      handleRowOffsetNewTouch();
      break;
    case displayColOffset:
      handleColOffsetNewTouch();
      break;
    case displayGuitarTuning:
      handleGuitarTuningNewTouch();
      break;
    case displayMinUSBMIDIInterval:
      handleMinUSBMIDIIntervalNewTouch();
      break;
    case displayMIDIThrough:
      handleMIDIThroughNewTouch();
      break;
    case displaySensorSensitivityZ:
      handleSensorSensitivityZNewTouch();
      break;
    case displaySensorLoZ:
      handleSensorLoZNewTouch();
      break;
    case displaySensorFeatherZ:
      handleSensorFeatherZNewTouch();
      break;
    case displaySensorRangeZ:
      handleSensorRangeZNewTouch();
      break;
    case displayOctaveTranspose:
      handleOctaveTransposeNewTouch();
      break;
    case displayGlobal:
    case displayGlobalWithTempo:
      handleGlobalSettingNewTouch();
      break;
    case displayOsVersion:
      setDisplayMode(displayOsVersionBuild);
      updateDisplay();
      break;
    case displayOsVersionBuild:
      setDisplayMode(displayOsVersion);
      updateDisplay();
      break;
    case displayCalibration:
      initVelocity();
      break;
    case displayEditAudienceMessage:
      handleEditAudienceMessageNewTouch();
      break;
    case displaySequencerProjects:
      handleSequencerProjectsNewTouch();
      break;
    case displaySequencerDrum0107:
      handleSequencerDrum0107NewTouch();
      break;
    case displaySequencerDrum0814:
      handleSequencerDrum0814NewTouch();
      break;
    case displaySequencerColors:
      handleSequencerColorsNewTouch();
      break;
  }
}

// handleXYZupdate:
// Called when a cell is held, in order to read X, Y or Z movements and send MIDI messages as appropriate
// Returns a flag to indicate if the performance loop can be short-circuited
boolean handleXYZupdate() {
  // if the touch is in the control buttons column, ignore it
  if (sensorCol == 0 &&
     // except for user firmware mode where only the global settings button is ignored for continuous updates
     (!userFirmwareActive || sensorRow == GLOBAL_SETTINGS_ROW)) return false;

  // if this data point serves as a calibration sample, return immediately
  if (handleCalibrationSample()) return false;

  // some features need hold functionality
  if (sensorCell->velocity) {
    switch (displayMode) {
      case displayPerSplit:
        handlePerSplitSettingHold();
        return false;

      case displayPreset:
        handlePresetHold();
        return false;

      case displayGlobal:
      case displayGlobalWithTempo:
        handleGlobalSettingHold();
        return false;

      case displaySequencerProjects:
        handleSequencerProjectsHold();
        break;

      case displaySensorSensitivityZ:
        handleSensorSensitivityZHold();
        break;

      default:
        // other displays don't need hold features
        break;
    }
  }
  
  VelocityState velState = calcVelocity(sensorCell->velocityZ);

  // velocity calculation works in stages, handle each one
  boolean newVelocity = false;
  switch (velState) {
    // when the velocity is being calculated, the performance loop can be short-circuited
    case velocityCalculating:
      return true;

    case velocityNew:
      if (isPhantomTouchIndividual() || isPhantomTouchContextual()) {
        cellTouched(untouchedCell);
        return false;
      }

      // mark this as a valid new velocity and process it as such further down the method
      newVelocity = true;
      break;

    case velocityCalculated:
      // velocity has been calculated, no need to short-circuit anymore and we can continue
      // with the main touch logic
      break;
  }

  // only continue if the active display modes require finger tracking
  if (displayMode != displayNormal &&
      displayMode != displayVolume &&
      (displayMode != displaySplitPoint || splitButtonDown)) {
    // check if this should be handled as a non-playing touch
    if (newVelocity) {
      handleNonPlayingTouch();
      performContinuousTasks();
    }
    return false;
  }

  DEBUGPRINT((2,"handleXYZupdate"));
  DEBUGPRINT((2," col="));DEBUGPRINT((2,(int)sensorCol));
  DEBUGPRINT((2," row="));DEBUGPRINT((2,(int)sensorRow));
  DEBUGPRINT((2," velocityZ="));DEBUGPRINT((2,(int)sensorCell->velocityZ));
  DEBUGPRINT((2," pressureZ="));DEBUGPRINT((2,(int)sensorCell->pressureZ));
  DEBUGPRINT((2,"\n"));

  lastTouchMoment = millis();
    
  // turn off note handling and note expression features for low row, volume, cc faders and strumming
  boolean handleNotes = true;
  // in user firmware mode, everything is always encoded as MIDI notes and information
  if (userFirmwareActive) {
    handleNotes = true;
  }
  // in regular firmware mode, some features need special non-MIDI note handling
  else if (isLowRow() ||
      displayMode == displayVolume ||
      Split[sensorSplit].ccFaders ||
      Split[Global.currentPerSplit].sequencer ||
      isStrummingSplit(sensorSplit)) {
    handleNotes = false;
  }

  // this cell corresponds to a playing note
  if (newVelocity) {
    sensorCell->lastTouch = millis();
    sensorCell->didMove = false;
    sensorCell->lastMovedX = 0;
    sensorCell->lastValueX = INVALID_DATA;
    sensorCell->shouldRefreshX = true;
    sensorCell->initialX = INVALID_DATA;
    sensorCell->quantizationOffsetX = 0;
    sensorCell->fxdRateCountX = fxdPitchHoldSamples[sensorSplit];

    if (userFirmwareActive) {
      handleNewUserFirmwareTouch();
    }
    else if (controlModeActive) {
      handleNewControlModeTouch();
    }
    // is this cell used for low row functionality
    else if (isLowRow()) {
      lowRowStart();
    }
    // Split strum only triggers notes in the other split
    else if (isStrummingSplit(sensorSplit)) {
      handleSplitStrum();
    }
    else if (handleNotes) {
      short notenum = cellTransposedNote(sensorSplit);

      // if there was a previous note and automatic octave switching is enabled,
      // check if the conditions are met to change the octave up or down while playing
      if (latestNoteNumberForAutoOctave != -1 && isSwitchAutoOctavePressed(sensorSplit)) {
        short octaveChange = 0;

        // if the previous note was at least a perfect fifth lower, transpose one octave down
        // since the arpeggio would be in a downward movement
        if (notenum - latestNoteNumberForAutoOctave >= 7) {
          octaveChange = -12;
        }
        // if the previous note was at least a perfect fifth higher, transpose one octave up
        // since the arpeggio would be in a upward movement
        else if (notenum - latestNoteNumberForAutoOctave <= -7) {
          octaveChange = 12;
        }

        // apply the automatic octave change and adapt the note number
        if (octaveChange != 0) {
          Split[sensorSplit].transposeOctave = constrain(Split[sensorSplit].transposeOctave + octaveChange, -60, 60);
          notenum += octaveChange;

          // switching octaves might turn off some note cells since they fall outside of the MIDI note range
          updateDisplay();
        }
      }

      // if the note number is outside of MIDI range, don't start it
      if (notenum >= 0 && notenum <= 127) {
        prepareNewNote(notenum);
      }
    }
  }

  // we don't need to handle any expression in control mode
  if (controlModeActive && !newVelocity) {
    return false;
  }

  // get the processed expression data
  short valueX = INVALID_DATA;
  short valueY = INVALID_DATA;
  unsigned short valueZHi = handleZExpression();
  byte valueZ = scale1016to127(valueZHi, true);
  performContinuousTasks();

  // Only process x and y data when there's meaningful pressure on the cell
  if (sensorCell->isMeaningfulTouch() || (doQuantizeHold() && isQuantizeHoldStable())) {
    valueX = handleXExpression();
    if (valueX != INVALID_DATA && isLeftHandedSplit(sensorSplit)) {
      valueX = -1 * valueX;
    }

    performContinuousTasks();
    sensorCell->lastValueX = valueX;
  }

  short tempY = handleYExpression();;
  if (tempY == 0 || tempY == 127 || sensorCell->isMeaningfulTouch()) {
    valueY = tempY;
  }
  performContinuousTasks();

  // update the low row state, but not for the low row cells themselves when there's a new velocity
  // this is handled in lowRowStart, and immediately calling handleLowRowState will wrongly handle the
  // low row state transitions
  if ((!newVelocity || !isLowRow()) && !userFirmwareActive) {
    handleLowRowState(newVelocity, valueX, valueY, valueZ);
  }

  // the volume fader has its own operation mode
  if (displayMode == displayVolume) {
    if (sensorCell->isMeaningfulTouch()) {
      handleVolumeNewTouch(newVelocity);
    }
  }
  else if (Split[sensorSplit].ccFaders && !userFirmwareActive) {
    if (sensorCell->isMeaningfulTouch()) {
      handleFaderTouch(newVelocity);
    }
  }
  else if (Split[Global.currentPerSplit].sequencer && !userFirmwareActive) {
    if (sensorCell->isMeaningfulTouch()) {
      handleSequencerTouch(newVelocity);
    }
  }
  else if (handleNotes && sensorCell->hasNote()) {
    if (userFirmwareActive) {
      // don't send expression data for the control switches
      if (sensorCol != 0) {
        // Z-axis movements are encoded using Poly Pressure with the note as the column and the channel as the row
        if (userFirmwareZActive[sensorRow]) {
          midiSendPolyPressure(sensorCell->note, valueZ, sensorCell->channel);
        }

        // X-axis movements are encoded in 14-bit with MIDI CC 0-25 / 32-57 as the column and the channel as the row
        if (userFirmwareXActive[sensorRow] && valueX != INVALID_DATA) {
          short positionX = valueX + FXD_TO_INT(sensorCell->fxdInitialReferenceX());

          // compensate for the -85 offset at the left side since 0 is positioned at the center of the left-most cell
          positionX = positionX + 85;
          
          midiSendControlChange14BitUserFirmware(sensorCol, sensorCol+32, positionX, sensorCell->channel);
        }

        // Y-axis movements are encoded using MIDI CC 64-89 as the column and the channel as the row
        if (userFirmwareYActive[sensorRow] && valueY != INVALID_DATA) {
          midiSendControlChange(sensorCol+64, valueY, sensorCell->channel);
        }
      }
    }
    else {
      
      // if X-axis movements are enabled and it's a candidate for
      // X/Y expression based on the MIDI mode and the currently held down cells
      if (valueX != INVALID_DATA &&
          Split[sensorSplit].sendX && isXExpressiveCell() && !isLowRowBendActive(sensorSplit)) {

        int pitch = valueX;

        // if there are several touches for the same MIDI channel (for instance in one channel mode)
        // we average the X values to have only one global X value for those touches
        if (countTouchesForMidiChannel(sensorSplit, sensorCol, sensorRow) > 2) {

          // start with the current sensor's pitch and note
          int highestNotePitch = valueX;
          signed char highestNote = sensorCell->note;

          // start with the current sensor's X value
          long averagePitch = valueX;
          byte averageDivider = 1;

          // iterate over all the rows
          for (byte row = 0; row < NUMROWS; ++row) {

            // exclude the current sensor for the rest of the logic, we already
            // took it into account
            int32_t colsInRowTouched = colsInRowsTouched[row];
            if (row == sensorRow) {
              colsInRowTouched = colsInRowTouched & ~(1 << sensorCol);
            }

            // continue while there are touched columns in the row
            while (colsInRowTouched) {
              byte touchedCol = 31 - __builtin_clz(colsInRowTouched);
              
              // add the X value of the cell to the average that's being calculated if the cell
              // is on the same channel
              if (cell(touchedCol, row).touched == touchedCell &&
                  cell(touchedCol, row).lastValueX != INVALID_DATA &&
                  cell(touchedCol, row).channel == sensorCell->channel) {

                if (cell(touchedCol, row).note >= highestNote) {
                  highestNote = cell(touchedCol, row).note;
                  highestNotePitch = cell(touchedCol, row).lastValueX;
                }

                averagePitch += cell(touchedCol, row).lastValueX;
                averageDivider++;
              }
              // exclude the cell we just processed by flipping its bit
              colsInRowTouched &= ~(1 << touchedCol);
            }
          }

          // calculate the average pitch of the notes that exclude the highest note
          averagePitch = (averagePitch - highestNotePitch) / (averageDivider - 1);

          // use the pitch that has the most influence
          if (abs(highestNotePitch) > abs(averagePitch)) {
            pitch = highestNotePitch;
          }
          else {
            pitch = averagePitch;
          }
        }

        preSendPitchBend(sensorSplit, pitch, sensorCell->channel);
      }

      // if Y-axis movements are enabled and it's a candidate for
      // X/Y expression based on the MIDI mode and the currently held down cells
      if (valueY != INVALID_DATA &&
          Split[sensorSplit].sendY && isYExpressiveCell()) {
        preSendTimbre(sensorSplit, valueY, sensorCell->note, sensorCell->channel);
      }

      // send the note on if this in a newly calculated velocity
      if (newVelocity) {
        if (isStrummedSplit(sensorSplit)) {
          handleStrummedRowChange(true, 0);
        }
        else {
          sendNewNote();
        }

        // when the legato switch is pressed and this is the only new touch in the split,
        // release all the latched notes after the new note on message
        if (isSwitchLegatoPressed(sensorSplit) && !hasOtherTouchInSplit(sensorSplit)) {
          noteTouchMapping[sensorSplit].releaseLatched(sensorSplit);
        }
      }

      // if sensing Z is enabled...
      // send different pressure update depending on midiMode
      if (Split[sensorSplit].sendZ && isZExpressiveCell()) {
        preSendLoudness(sensorSplit, valueZ, valueZHi, sensorCell->note, sensorCell->channel);
      }

      // after the initial velocity, new velocity values are continuously being calculated simply based
      // on the Z data, during arpeggiation this is handled in the arpeggiator itself in order to have
      // snapshotted velocities that can be latched
      if (!isArpeggiatorEnabled(sensorSplit)) {
        sensorCell->velocity = calcPreferredVelocity(sensorCell->velocityZ);      
      }
    }
  }

  return false;
}

void handleSplitStrum() {
  // handle open strings by checking if no cells are touched in the strummed split,
  // this corresponds to checking of a fret is pushed down on a string, in which case is can't be open
  if (!hasTouchInSplitOnRow(otherSplit(), sensorRow)) {
    handleStrummedOpenRow(otherSplit(), cell(sensorCol, sensorRow).velocity);
  }
  // handle fretted strings
  else {
    handleStrummedRowChange(false, cell(sensorCol, sensorRow).velocity);
  }
}

void handleStrummedOpenRow(byte split, byte velocity) {
  // if a note is already playing for this open string, turn it off so that the exact same note
  // can be played, but with a different velocity
  if (virtualCell().hasNote()) {
    midiSendNoteOff(virtualCell().split, virtualCell().note, virtualCell().channel);
  }
  // since no note was already playing, determined what the note details are
  else {
    virtualCell().split = split;
    virtualCell().note = transposedNote(split, splitLowestEdge(virtualCell().split), sensorRow);
    virtualCell().channel = takeChannel(split, sensorRow);
  }

  // use the velocity of the strum touch
  virtualCell().velocity = velocity;

  if (Split[split].sendX && !isLowRowBendActive(split)) {
    resetLastMidiPitchBend(virtualCell().channel);
    preSendPitchBend(split, 0, virtualCell().channel);
  }
  if (Split[split].sendY) {
    preResetLastTimbre(split, virtualCell().note, virtualCell().channel);
    preSendTimbre(split, 0, virtualCell().note, virtualCell().channel);
  }
  if (Split[split].sendZ) {
    preResetLastLoudness(split, virtualCell().note, virtualCell().channel);
    preSendLoudness(split, 0, 0, virtualCell().note, virtualCell().channel);
  }

  // send a new MIDI note
  midiSendNoteOn(split, virtualCell().note, virtualCell().velocity, virtualCell().channel);
}

void handleStrummedRowChange(boolean newFretting, byte velocity) {
  // we use the bitmask of the touched columns in the current row, and turn off all the columns
  // that belong to the strumming split
  int32_t colsInSensorRowTouched = colsInRowsTouched[sensorRow];
  if (isStrummingSplit(LEFT)) {
    colsInSensorRowTouched &= ~((int32_t)(1 << Global.splitPoint) - 1);
  }
  else if (isStrummingSplit(RIGHT)) {
    colsInSensorRowTouched &= ((int32_t)(1 << Global.splitPoint) - 1);
  }

  byte highestNoteCol = 0;
  byte numNotesTouched = 0;

  // automatically turn of notes for open strings
  if (colsInSensorRowTouched && virtualCell().hasNote()) {
      virtualCell().releaseNote();
      numNotesTouched += 1;
  }

  // if this was not a new fretting and the change is coming from the strummed split,
  // it's a pull-off. The pulled-off cell is already set to untouched, but the note is still
  // sounding, take that into account.
  if (!newFretting && isStrummedSplit(sensorSplit) &&
      sensorCell->hasNote() && hasActiveMidiNote(sensorSplit, sensorCell->note, sensorCell->channel)) {
    numNotesTouched += 1;
  }

  // now we check each touched column in the row of the current sensor
  // we gradually flip the touched bits to zero until they're all turned off
  // this allows us to loop only over the touched columns, and none other
  while (colsInSensorRowTouched) {
    // we use the ARM Cortex-M3 instruction that reports the leading bit zeros of any number
    // we determine that what left-most bit is that is turned on by substracting the leading zero
    // count from the bitdepth of a 32-bit int
    byte touchedCol = 31 - __builtin_clz(colsInSensorRowTouched);
    TouchInfo& cell = cell(touchedCol, sensorRow);
    byte split = getSplitOf(touchedCol);
    if (cell.hasNote()) {
      if (hasActiveMidiNote(split, cell.note, cell.channel)) {
        numNotesTouched += 1;
      }

      // remembed the top-most touch of the row, which will trigger a new note
      if (highestNoteCol == 0) {
        highestNoteCol = touchedCol;
      }
      else {
        // turn off the notes for all the active touches
        midiSendNoteOff(split, cell.note, cell.channel);
      }
    }

    colsInSensorRowTouched &= ~(1 << touchedCol);
  }

  // trigger a new note for the top-most touch of the row
  if (highestNoteCol > 0) {
    // turn off open strings that are sounding
    if (virtualCell().hasNote()) {
      numNotesTouched += 1;
      virtualCell().releaseNote();
    }

    if (isStrummingSplit(sensorSplit) || (numNotesTouched && (!newFretting || sensorCol == highestNoteCol))) {
      TouchInfo& cell = cell(highestNoteCol, sensorRow);
      byte split = getSplitOf(highestNoteCol);
      midiSendNoteOff(split, cell.note, cell.channel);
      midiSendNoteOn(split, cell.note, velocity > 0 ? velocity : cell.velocity, cell.channel);
    }
  }

  if (isStrummedSplit(sensorSplit) &&
      !newFretting &&
      hasTouchInSplitOnRow(otherSplit(sensorSplit), sensorRow) &&
      !hasTouchInSplitOnRow(sensorSplit, sensorRow) && numNotesTouched == 1) {
    handleStrummedOpenRow(sensorSplit, velocity);
  }
}

boolean isStrummedSplit(byte split) {
  return Global.splitActive && Split[otherSplit(split)].strum;
}

boolean isStrummingSplit(byte split) {
  return Global.splitActive && Split[split].strum;
}

void prepareNewNote(signed char notenum) {
  byte channel = takeChannel(sensorSplit, sensorRow);
  sensorCell->note = notenum;
  sensorCell->channel = channel;
  sensorCell->octaveOffset = Split[sensorSplit].transposeOctave;
  
  // change the focused cell
  FocusCell& focused = focus(sensorSplit, channel);
  focused.col = sensorCol;
  focused.row = sensorRow;

  // reset the pitch bend and pressure right before sending the note on
  if (!userFirmwareActive) {
    if (Split[sensorSplit].sendX && isXExpressiveCell() && !isLowRowBendActive(sensorSplit)) {
      resetLastMidiPitchBend(sensorCell->channel);
      preSendPitchBend(sensorSplit, 0, sensorCell->channel);
    }
    if (Split[sensorSplit].sendZ && isZExpressiveCell()) {
      preResetLastLoudness(sensorSplit, sensorCell->note, sensorCell->channel);
    }
    if (Split[sensorSplit].sendY && isYExpressiveCell()) {
      preResetLastTimbre(sensorSplit, sensorCell->note, sensorCell->channel);
    }
  }

  // register the reverse mapping
  noteTouchMapping[sensorSplit].noteOn(notenum, channel, sensorCol, sensorRow);

  // highlight the touch animation if this is activated
  if (Split[sensorSplit].colorPlayed) {
    if (Split[sensorSplit].playedTouchMode == playedCell) {
      setLed(sensorCol, sensorRow, Split[sensorSplit].colorPlayed, cellOn, LED_LAYER_PLAYED);
    }
    else if (Split[sensorSplit].playedTouchMode == playedSame) {
      highlightPossibleNoteCells(sensorSplit, sensorCell->note);
    }
    else {
      startTouchAnimation(sensorCol, sensorRow, calcTouchAnimationSpeed(Split[sensorSplit].playedTouchMode, sensorCell->velocity));
    }
  }

  // keep track of the last note number
  latestNoteNumberForAutoOctave = notenum;
}

void sendNewNote() {
  if (!isArpeggiatorEnabled(sensorSplit)) {
    // if we've switched from pitch X enabled to pitch X disabled and the last
    // pitch bend value was not neutral, reset it first to prevent skewed pitches
    if (!Split[sensorSplit].sendX && hasPreviousPitchBendValue(sensorCell->channel)) {
      preSendPitchBend(sensorSplit, 0, sensorCell->channel);
    }

    // reset pressure to 0 before sending the note, the actually pressure value will
    // be sent right after the note on
    if (Split[sensorSplit].sendZ && isZExpressiveCell()) {
      preSendLoudness(sensorSplit, 0, 0, sensorCell->note, sensorCell->channel);
    }

    // if the same channel and note is already active, send a note off first
    // so that the new touch properly triggers a new note
    if (hasActiveMidiNote(sensorSplit, sensorCell->note, sensorCell->channel)) {
      midiSendNoteOff(sensorSplit, sensorCell->note, sensorCell->channel);
    }

    // send the note on
    midiSendNoteOn(sensorSplit, sensorCell->note, sensorCell->velocity, sensorCell->channel);
  }
}

void sendReleasedNote() {
  if (!isArpeggiatorEnabled(sensorSplit) && !isSwitchLegatoPressed(sensorSplit)) {
    // iterate over all the rows
    for (byte row = 0; row < NUMROWS; ++row) {

      // exclude the current sensor for the rest of the logic, we're looking
      // for other touches
      int32_t colsInRowTouched = colsInRowsTouched[row];
      if (row == sensorRow) {
        colsInRowTouched = colsInRowTouched & ~(1 << sensorCol);
      }

      // continue while there are touched columns in the row
      while (colsInRowTouched) {
        byte touchedCol = 31 - __builtin_clz(colsInRowTouched);
        
        if (cell(touchedCol, row).touched == touchedCell &&
            cell(touchedCol, row).note == sensorCell->note &&
            cell(touchedCol, row).channel == sensorCell->channel) {
          // if there is another touch active with the same exact note and channel,
          // don't send the note off for the released note
          return;
        }

        // exclude the cell we just processed by flipping its bit
        colsInRowTouched &= ~(1 << touchedCol);
      }
    }

    // if there are no other touches down with the same note and channel, send the note off message
    midiSendNoteOffWithVelocity(sensorSplit, sensorCell->note, sensorCell->velocity, sensorCell->channel);
  }
}

void handleNewUserFirmwareTouch() {
  sensorCell->note = sensorCol;
  sensorCell->channel = sensorRow+1;
  midiSendNoteOn(LEFT, sensorCell->note, sensorCell->velocity, sensorCell->channel);
}

void handleNewControlModeTouch() {
  Serial.write((byte)1);
  Serial.write((byte)sensorCol);
  Serial.write((byte)sensorRow);
  Serial.write("\n");

  sensorCell->note = sensorCol;
  sensorCell->channel = sensorRow+1;

  setLed(sensorCol, sensorRow, Split[Global.currentPerSplit].colorPlayed, cellOn, LED_LAYER_PLAYED);
}

unsigned short handleZExpression() {
  unsigned short preferredPressure = sensorCell->pressureZ;

  // handle pressure transition between adjacent cells if they are not playing their own note
  unsigned short adjacentZ = 0;
  if (cell(sensorCol-1, sensorRow).currentRawZ && !cell(sensorCol-1, sensorRow).hasNote()) {
    adjacentZ = cell(sensorCol-1, sensorRow).currentRawZ;
  }
  else if (cell(sensorCol+1, sensorRow).currentRawZ && !cell(sensorCol+1, sensorRow).hasNote()) {
    adjacentZ = cell(sensorCol+1, sensorRow).currentRawZ;
  }
  // the adjacent Z value is added the active cell's pressure to make
  // up for the pressure differential while moving across cells
  preferredPressure = constrain(preferredPressure + adjacentZ, 0, 1016);

  // the faster we move the slower the slew rate becomes,
  // if we're holding still the pressure changes are almost instant, if we're moving faster they are averaged out
  int32_t slewRate = sensorCell->fxdRateX;

  // adapt the slew rate based on the rate of change on the pressure, the smaller the change, the higher the slew rate
  slewRate += FXD_CONST_2 - FXD_DIV(abs(FXD_FROM_INT(preferredPressure) - sensorCell->fxdPrevPressure), FXD_FROM_INT(508));

  if (slewRate > FXD_CONST_1) {
    // we also keep track of the previous pressure on the cell and average it out with
    // the current pressure to smooth over the rate of change when transiting between cells
    int32_t fxdAveragedPressure = sensorCell->fxdPrevPressure;
    fxdAveragedPressure += FXD_DIV(FXD_FROM_INT(preferredPressure), slewRate);
    fxdAveragedPressure -= FXD_DIV(sensorCell->fxdPrevPressure, slewRate);
    sensorCell->fxdPrevPressure = fxdAveragedPressure;

    // calculate the final pressure value
    preferredPressure = constrain(FXD_TO_INT(fxdAveragedPressure), 0, 1016);
  }
  else {
    sensorCell->fxdPrevPressure = FXD_FROM_INT(preferredPressure);
  }

  return preferredPressure;
}

const int32_t fxdRateXSamples = FXD_FROM_INT(5);    // the number of samples over which the average rate of change of X is calculated

short handleXExpression() {
  sensorCell->refreshX();

  short movedX;
  int calibratedX = sensorCell->calibratedX();

  // determine if a slide transfer is in progress and which column it is with
  short transferCol = 0;
  if (cell(sensorCol-1, sensorRow).touched == transferCell) {
    transferCol = sensorCol-1;
  }
  else if (cell(sensorCol+1, sensorRow).touched == transferCell) {
    transferCol = sensorCol+1;
  }

  // if there is a slide transfer column, interpolate the X position based on the relative pressure
  // of the cells, this allows for a smoother transition as a finger slides over the groove between
  // cells and distributes the pressure
  if (transferCol != 0) {
    short totalZ = cell(transferCol, sensorRow).currentRawZ + sensorCell->currentRawZ;
    int32_t fxdTransferRatio = FXD_DIV(FXD_FROM_INT(cell(transferCol, sensorRow).currentRawZ), FXD_FROM_INT(totalZ));
    int32_t fxdCellRatio = FXD_CONST_1 - fxdTransferRatio;

    int32_t fxdTransferCalibratedX = FXD_MUL(FXD_FROM_INT(cell(transferCol, sensorRow).currentCalibratedX), fxdTransferRatio);
    int32_t fxdCellCalibratedX = FXD_MUL(FXD_FROM_INT(sensorCell->calibratedX()), fxdCellRatio);
    calibratedX = FXD_TO_INT(fxdTransferCalibratedX + fxdCellCalibratedX);
  }

  // calculate the distance from the initial X position
  if (!userFirmwareActive && Split[sensorSplit].pitchCorrectQuantize) {
    movedX = calibratedX - (FXD_TO_INT(sensorCell->fxdInitialReferenceX()) + sensorCell->quantizationOffsetX);

    // if initial quantize offset and quantize hold are active, ensure that movement on that cell will never exceed half the cell width
    // as soon as a finger transits to an adjacent cell during a slide, the quantization offset will be set to 0 and
    // fingers will track in absolute positions
    // this ensures that disregarding where you place your finger with pitch quantize on, target slides will always result
    // in the same absolute X position
    if (Split[sensorSplit].pitchCorrectHold != pitchCorrectHoldOff && sensorCell->quantizationOffsetX != 0) {
      int32_t fxdQuantRefDist = FXD_FROM_INT(calibratedX - sensorCell->quantizationOffsetX) - Device.calRows[sensorCol][0].fxdReferenceX;
      if (fxdQuantRefDist > 0) {
        if (fxdQuantRefDist > FXD_CALX_HALF_UNIT) {
          movedX = FXD_TO_INT(FXD_FROM_INT(movedX) - (fxdQuantRefDist - FXD_CALX_HALF_UNIT));
        }
      }
      else {
        if (abs(fxdQuantRefDist) > FXD_CALX_HALF_UNIT) {
          movedX = FXD_TO_INT(FXD_FROM_INT(movedX) - (fxdQuantRefDist + FXD_CALX_HALF_UNIT));
        }
      }
    }
  }
  // otherwise we use the intended centerpoint based on the calibration
  else {
    movedX = calibratedX - FXD_TO_INT(sensorCell->fxdInitialReferenceX());
  }

  short result = INVALID_DATA;

  // calculate how much change there was since the last X update
  short deltaX = abs(movedX - sensorCell->lastMovedX);

  // determine if the last X movement was a rogue sweep
  sensorCell->rogueSweepX = (deltaX >= ROGUE_SWEEP_X_THRESHOLD);
        
  if ((countTouchesInColumn() < 2 ||
       sensorCell->currentRawZ > (Device.sensorLoZ + SENSOR_PITCH_Z)) &&  // when there are multiple touches in the same column, reduce the pitch bend Z sensitivity to prevent unwanted pitch slides
      sensorCell->hasUsableX()) {                                         // if no phantom presses are active, send the pitch bend change, otherwise only send those changes that are small and gradual to prevent rogue pitch sweeps

    // calculate the average rate of X value changes over a number of samples
    sensorCell->fxdRateX -= FXD_DIV(sensorCell->fxdRateX, fxdRateXSamples);
    sensorCell->fxdRateX += FXD_DIV(FXD_FROM_INT(deltaX), fxdRateXSamples);

    // remember the last X movement
    sensorCell->lastMovedX = movedX;

    // if pitch quantize on hold is disabled, just output the current touch pitch
    if (!doQuantizeHold()) {
      result = movedX;
    }
    // if pitch quantize is active on hold, interpolate between the ideal pitch and the current touch pitch
    else {
      int32_t fxdMovedRatio = FXD_DIV(fxdPitchHoldSamples[sensorSplit] - sensorCell->fxdRateCountX, fxdPitchHoldSamples[sensorSplit]);
      if (fxdMovedRatio > FXD_CONST_1) fxdMovedRatio = FXD_CONST_1;
      else if (fxdMovedRatio < 0)      fxdMovedRatio = 0;
      int32_t fxdCorrectedRatio = FXD_CONST_1 - fxdMovedRatio;
      int32_t fxdQuantizedDistance = Device.calRows[sensorCol][0].fxdReferenceX - sensorCell->fxdInitialReferenceX();
      
      int32_t fxdInterpolatedX = FXD_MUL(FXD_FROM_INT(movedX), fxdMovedRatio) + FXD_MUL(fxdQuantizedDistance, fxdCorrectedRatio);

      result = FXD_TO_INT(fxdInterpolatedX);
    }

    // keep track of how many times the X changement rate drops below the threshold or above
    if (fxdRateXThreshold[sensorSplit] >= sensorCell->fxdRateX) {
      if (sensorCell->fxdRateCountX < fxdPitchHoldSamples[sensorSplit]) {
        sensorCell->fxdRateCountX += FXD_CONST_1;

        // if the pich has just stabilized, adapt the touch's initial X position so that pitch changes start from the stabilized pitch
        if (isQuantizeHoldStable()) {
          // ensure that the rate count can never exceed the pitch hold duration
          sensorCell->fxdRateCountX = fxdPitchHoldSamples[sensorSplit];

          if (Split[sensorSplit].pitchCorrectQuantize && Split[sensorSplit].pitchCorrectHold != pitchCorrectHoldOff) {
            sensorCell->quantizationOffsetX = calibratedX - FXD_TO_INT(Device.calRows[sensorCol][0].fxdReferenceX);
          }
        }
      }
    }
    else if (sensorCell->fxdRateCountX > 0) {
      if (sensorCell->fxdRateCountX > 0) {
        sensorCell->fxdRateCountX -= FXD_CONST_1;
      }
    }
  }

  return result;
}

boolean doQuantizeHold() {
  return !userFirmwareActive && Split[sensorSplit].pitchCorrectHold != pitchCorrectHoldOff;
}

boolean isQuantizeHoldStable() {
  return sensorCell->fxdRateCountX >= fxdPitchHoldSamples[sensorSplit];
}

short handleYExpression() {
  sensorCell->refreshY();

  short preferredTimbre = INVALID_DATA;
  if (Split[sensorSplit].relativeY) {
    preferredTimbre = constrain(Split[sensorSplit].initialRelativeY + (sensorCell->currentCalibratedY - sensorCell->initialY), 0, 127);
  }
  else {
    preferredTimbre = sensorCell->currentCalibratedY;
  }

  // the faster we move horizontally, the slower the slew rate becomes,
  // if we're holding still the timbre changes are almost instant, if we're moving faster they are averaged out
  int32_t slewRate = FXD_CONST_1 + sensorCell->fxdRateX;

  int32_t fxdAveragedTimbre;
  if (sensorCell->fxdPrevTimbre == FXD_CONST_255) {
    fxdAveragedTimbre = FXD_FROM_INT(preferredTimbre);
  }
  else {
    fxdAveragedTimbre = sensorCell->fxdPrevTimbre;
    fxdAveragedTimbre += FXD_DIV(FXD_FROM_INT(preferredTimbre), slewRate);
    fxdAveragedTimbre -= FXD_DIV(sensorCell->fxdPrevTimbre, slewRate);
  }
  sensorCell->fxdPrevTimbre = fxdAveragedTimbre;

  return FXD_TO_INT(fxdAveragedTimbre);
}

void releaseChannel(byte split, byte channel) {
  if (Split[split].midiMode == channelPerNote) {
    splitChannels[split].release(channel);
  }
}

boolean handleNonPlayingRelease() {
  if (sensorCell->velocity) {
    switch (displayMode) {
      case displayPerSplit:
        handlePerSplitSettingRelease();
        break;
      case displayPreset:
        handlePresetRelease();
        break;
      case displayBendRange:
        handleBendRangeRelease();
        break;
      case displayLimitsForY:
        handleLimitsForYRelease();
        break;
      case displayCCForY:
        handleCCForYRelease();
        break;
      case displayInitialForRelativeY:
        handleInitialForRelativeYRelease();
        break;
      case displayLimitsForZ:
        handleLimitsForZRelease();
        break;
      case displayCCForZ:
        handleCCForZRelease();
        break;
      case displayPlayedTouchModeConfig:
        handlePlayedTouchModeRelease();
        break;
      case displayCCForFader:
        handleCCForFaderRelease();
        break;
      case displayLowRowCCXConfig:
        handleLowRowCCXConfigRelease();
        break;
      case displayLowRowCCXYZConfig:
        handleLowRowCCXYZConfigRelease();
        break;
      case displayCCForSwitchCC65:
        handleCCForSwitchCC65ConfigRelease();
        break;
      case displayCCForSwitchSustain:
        handleCCForSwitchSustainConfigRelease();
        break;
      case displayCustomSwitchAssignment:
        handleCustomSwitchAssignmentConfigRelease();
        break;
      case displayLimitsForVelocity:
        handleLimitsForVelocityRelease();
        break;
      case displaySleepConfig:
        handleSleepConfigRelease();
        break;
      case displaySplitHandedness:
        handleSplitHandednessRelease();
        break;
      case displayRowOffset:
        handleRowOffsetRelease();
        break;
      case displayColOffset:
        handleColOffsetRelease();
        break;
      case displayGuitarTuning:
        handleGuitarTuningRelease();
        break;
      case displayMinUSBMIDIInterval:
        handleMinUSBMIDIIntervalRelease();
        break;
      case displayMIDIThrough:
        handleMIDIThroughRelease();
        break;
      case displayValueForFixedVelocity:
        handleValueForFixedVelocityRelease();
        break;
      case displaySensorSensitivityZ:
        handleSensorSensitivityZRelease();
        break;
      case displaySensorLoZ:
        handleSensorLoZRelease();
        break;
      case displaySensorFeatherZ:
        handleSensorFeatherZRelease();
        break;
      case displaySensorRangeZ:
        handleSensorRangeZRelease();
        break;
      case displayVolume:
        handleVolumeRelease();
        break;
      case displayOctaveTranspose:
        handleOctaveTransposeRelease();
        break;
      case displayGlobal:
      case displayGlobalWithTempo:
        handleGlobalSettingRelease();
        break;
      case displayEditAudienceMessage:
        handleEditAudienceMessageRelease();
        break;
      case displaySequencerProjects:
        handleSequencerProjectsRelease();
        break;
      case displaySequencerDrum0107:
        handleSequencerDrum0107Release();
        break;
      case displaySequencerDrum0814:
        handleSequencerDrum0814Release();
        break;
      case displaySequencerColors:
        handleSequencerColorsRelease();
        break;
      default:
        return false;
    }

    return true;
  }

  return false;
}

#define PENDING_RELEASE_CONTROL    1
#define PENDING_RELEASE_MOVEMENT   3
#define PENDING_RELEASE_EDITING    15

// Called when a touch is released to handle note off or other release events
void handleTouchRelease() {
  DEBUGPRINT((1,"handleTouchRelease"));
  DEBUGPRINT((1," col="));DEBUGPRINT((1,(int)sensorCol));
  DEBUGPRINT((1," row="));DEBUGPRINT((1,(int)sensorRow));
  DEBUGPRINT((1,"\n"));

  // if a release is pending, decrease the counter
  if (sensorCell->pendingReleaseCount > 0) {
    sensorCell->pendingReleaseCount--;
  }
  // if no release is pending, start a pending release
  else if (sensorCol == 0) {
    sensorCell->pendingReleaseCount = PENDING_RELEASE_CONTROL;
  }
  else if (isSequencerEditing()) {
    sensorCell->pendingReleaseCount = PENDING_RELEASE_EDITING;
  }
  else if (sensorCell->fxdRateX > PENDING_RELEASE_RATE_X) {
    sensorCell->pendingReleaseCount = PENDING_RELEASE_MOVEMENT;
  }

  // if a release is pending, don't perform the release logic yet
  if (sensorCell->pendingReleaseCount > 0) {
    return;
  }

  // remember whether this cell was ignored
  boolean wasIgnored = (sensorCell->touched == ignoredCell);

  // mark this cell as no longer touched
  cellTouched(untouchedCell);

  if (wasIgnored ||
      displayMode == displaySleep) {
    postTouchRelease();
    return;
  }

  // release open strings if no touches are down anymore
  handleOpenStringsRelease();

  // if touch release is in column 0, it's a command key release so handle it
  if (sensorCol == 0 &&
      // user firmware mode only handles the global settings command button
      (!userFirmwareActive || sensorRow == GLOBAL_SETTINGS_ROW)) {
    handleControlButtonRelease();
    postTouchRelease();
    return;
  }

  // Some of the displayModes handle Release events
  if (handleNonPlayingRelease()) {
    performContinuousTasks();
  }
  // check if calibration is active and its cell release logic needs to be executed
  else if (handleCalibrationRelease()) {
    // do nothing, calibration is handled elsewhere
  }
  // user firmware mode has its own mode of operation
  else if (userFirmwareActive) {
    midiSendNoteOffWithVelocity(LEFT, sensorCell->note, sensorCell->velocity, sensorCell->channel);
    sensorCell->clearMusicalData();
  }
  // control mode has its own mode of operation
  else if (controlModeActive) {
    if (sensorCell->hasNote()) {
      Serial.write((byte)0);
      Serial.write((byte)sensorCol);
      Serial.write((byte)sensorRow);
      Serial.write("\n");

      setLed(sensorCol, sensorRow, COLOR_OFF, cellOff, LED_LAYER_PLAYED);
    }
  }
  // CC faders have their own operation mode
  else if (Split[sensorSplit].ccFaders) {
    handleFaderRelease();
  }
  // sequencer has its own operation mode
  else if (Split[Global.currentPerSplit].sequencer) {
    handleSequencerRelease();
  }
  // is this cell used for low row functionality
  else if (isLowRow()) {
    lowRowStop();
  }
  else if (sensorCell->hasNote()) {

    // reset the pressure when the note is released and that setting is active
    if (Split[sensorSplit].sendZ && isZExpressiveCell()) {
      preSendLoudness(sensorSplit, 0, 0, sensorCell->note, sensorCell->channel);
    }

    // unregister the note <> cell mapping
    if (!isSwitchLegatoPressed(sensorSplit) && (!isArpeggiatorEnabled(sensorSplit) || !isSwitchLatchPressed(sensorSplit))) {
      noteTouchMapping[sensorSplit].noteOff(sensorCell->note, sensorCell->channel);
    }

    // send the Note Off
    if (isArpeggiatorEnabled(sensorSplit)) {
      if (!isSwitchLatchPressed(sensorSplit)) {
        handleArpeggiatorNoteOff(sensorSplit, sensorCell->note, sensorCell->channel);
      }
    }
    else {
      if (isStrummedSplit(sensorSplit)) {
        handleStrummedRowChange(false, sensorCell->velocity);
      }
      sendReleasedNote();
    }

    // unhighlight the touch animation if this is activated
    if (Split[sensorSplit].colorPlayed) {
      if (Split[sensorSplit].playedTouchMode == playedCell) {
        setLed(sensorCol, sensorRow, COLOR_OFF, cellOff, LED_LAYER_PLAYED);
      }
      // if no notes are active anymore, reset the highlighted cells
      else if (Split[sensorSplit].playedTouchMode == playedSame) {
        // calculate the difference between the octave offset when the note was turned on and the octave offset
        // that is currently in use on the split, since the octave can change on the fly, while playing,
        // hence changing the position of notes on the surface
        short octaveOffsetDifference = Split[sensorSplit].transposeOctave - sensorCell->octaveOffset;
        short realSensorNote = sensorCell->note + octaveOffsetDifference;

        // ensure that no other notes of the same value are still active
        boolean allNotesOff = true;

        // iterate over all the rows
        for (byte row = 0; row < NUMROWS && allNotesOff; ++row) {

          // continue while there are touched columns in the row
          int32_t colsInRowTouched = colsInRowsTouched[row];
          while (colsInRowTouched) {
            byte touchedCol = 31 - __builtin_clz(colsInRowTouched);
            
            // if another touch in the same split has the same note, the lights should remain lit
            if (!(sensorCol == touchedCol && sensorRow == row) &&
                sensorSplit == getSplitOf(touchedCol) &&
                cell(touchedCol, row).touched == touchedCell &&
                cell(touchedCol, row).note + Split[sensorSplit].transposeOctave - cell(touchedCol, row).octaveOffset == realSensorNote) {
              allNotesOff = false;
              break;
            }

            // exclude the cell we just processed by flipping its bit
            colsInRowTouched &= ~(1 << touchedCol);
          }
        }

        if (allNotesOff) {
          resetPossibleNoteCells(sensorSplit, realSensorNote);
        }
      }
    }

    // reset the pitch bend when the note is released and that setting is active
    if (Split[sensorSplit].pitchResetOnRelease && isXExpressiveCell() && !isLowRowBendActive(sensorSplit)) {
      preSendPitchBend(sensorSplit, 0, sensorCell->channel);
    }

    // If the released cell had focus, reassign focus to the latest touched cell
    if (isFocusedCell()) {
      setFocusCellToLatest(sensorSplit, sensorCell->channel);
    }

    releaseChannel(sensorSplit, sensorCell->channel);

    // Reset all this cell's musical data
    sensorCell->clearMusicalData();
  }

  postTouchRelease();
}

void postTouchRelease() {
  sensorCell->clearAllPhantoms();

  // reset velocity calculations
  sensorCell->vcount = 0;

  sensorCell->clearSensorData();

#ifdef TESTING_SENSOR_DISABLE
    sensorCell->disabled = true;
#endif  
}

void handleOpenStringsRelease() {
  if (cellsTouched == 0) {
    // turn off all the notes of sounding open strings since no touches are active at all anymore
    for (byte row = 0; row < NUMROWS; ++row) {
      virtualTouchInfo[row].releaseNote();
    }
  }
}

// nextSensorCell:
// Moves on to the next cell witin the total surface scan of all surface cells.

#define MAX_CELLCOUNT 201
byte CELLCOUNT = MAX_CELLCOUNT;
byte SCANNED_CELLS[MAX_CELLCOUNT][2];

// Columns and rows are scanned in non-sequential order to minimize sensor crosstalk
const byte SCANNED_CELLS_200[MAX_CELLCOUNT][2] = {
  {0, 0},
  {3, 4}, {7, 1}, {10, 5}, {13, 2}, {17, 6}, {20, 3}, {24, 7}, {1, 4}, {4, 0}, {8, 5}, {11, 1}, {14, 6}, {18, 2}, {21, 7}, {25, 3}, {2, 0}, {5, 4}, {9, 1}, {12, 5}, {15, 2}, {19, 6}, {22, 3}, {6, 7}, {16, 4}, {23, 0},
  {3, 0}, {7, 5}, {10, 1}, {13, 6}, {17, 2}, {20, 7}, {24, 3}, {1, 0}, {4, 4}, {8, 1}, {11, 5}, {14, 2}, {18, 6}, {21, 3}, {25, 7}, {2, 4}, {5, 0}, {9, 5}, {12, 1}, {15, 6}, {19, 2}, {22, 7}, {6, 3}, {16, 0}, {23, 4},
  {3, 5}, {7, 2}, {10, 6}, {13, 3}, {17, 7}, {20, 4}, {24, 0}, {1, 5}, {4, 1}, {8, 6}, {11, 2}, {14, 7}, {18, 3}, {21, 0}, {25, 4}, {2, 1}, {5, 5}, {9, 2}, {12, 6}, {15, 3}, {19, 7}, {22, 4}, {6, 0}, {16, 5}, {23, 1},
  {3, 1}, {7, 6}, {10, 2}, {13, 7}, {17, 3}, {20, 0}, {24, 4}, {1, 1}, {4, 5}, {8, 2}, {11, 6}, {14, 3}, {18, 7}, {21, 4}, {25, 0}, {2, 5}, {5, 1}, {9, 6}, {12, 2}, {15, 7}, {19, 3}, {22, 0}, {6, 4}, {16, 1}, {23, 5},
  {3, 6}, {7, 3}, {10, 7}, {13, 4}, {17, 0}, {20, 5}, {24, 1}, {1, 6}, {4, 2}, {8, 7}, {11, 3}, {14, 0}, {18, 4}, {21, 1}, {25, 5}, {2, 2}, {5, 6}, {9, 3}, {12, 7}, {15, 4}, {19, 0}, {22, 5}, {6, 1}, {16, 6}, {23, 2},
  {3, 2}, {7, 7}, {10, 3}, {13, 0}, {17, 4}, {20, 1}, {24, 5}, {1, 2}, {4, 6}, {8, 3}, {11, 7}, {14, 4}, {18, 0}, {21, 5}, {25, 1}, {2, 6}, {5, 2}, {9, 7}, {12, 3}, {15, 0}, {19, 4}, {22, 1}, {6, 5}, {16, 2}, {23, 6},
  {3, 7}, {7, 4}, {10, 0}, {13, 5}, {17, 1}, {20, 6}, {24, 2}, {1, 7}, {4, 3}, {8, 0}, {11, 4}, {14, 1}, {18, 5}, {21, 2}, {25, 6}, {2, 3}, {5, 7}, {9, 4}, {12, 0}, {15, 5}, {19, 1}, {22, 6}, {6, 2}, {16, 7}, {23, 3},
  {3, 3}, {7, 0}, {10, 4}, {13, 1}, {17, 5}, {20, 2}, {24, 6}, {1, 3}, {4, 7}, {8, 4}, {11, 0}, {14, 5}, {18, 1}, {21, 6}, {25, 2}, {2, 7}, {5, 3}, {9, 0}, {12, 4}, {15, 1}, {19, 5}, {22, 2}, {6, 6}, {16, 3}, {23, 7}
};
const byte SCANNED_CELLS_128[MAX_CELLCOUNT][2] = {
  {0, 0},
  {3, 4}, {7, 1}, {10, 5}, {13, 2}, {1, 4}, {4, 0}, {8, 5}, {11, 1}, {14, 6}, {2, 0}, {5, 4}, {9, 1}, {12, 5}, {15, 2}, {6, 7}, {16, 4},
  {3, 0}, {7, 5}, {10, 1}, {13, 6}, {1, 0}, {4, 4}, {8, 1}, {11, 5}, {14, 2}, {2, 4}, {5, 0}, {9, 5}, {12, 1}, {15, 6}, {6, 3}, {16, 0},
  {3, 5}, {7, 2}, {10, 6}, {13, 3}, {1, 5}, {4, 1}, {8, 6}, {11, 2}, {14, 7}, {2, 1}, {5, 5}, {9, 2}, {12, 6}, {15, 3}, {6, 0}, {16, 5},
  {3, 1}, {7, 6}, {10, 2}, {13, 7}, {1, 1}, {4, 5}, {8, 2}, {11, 6}, {14, 3}, {2, 5}, {5, 1}, {9, 6}, {12, 2}, {15, 7}, {6, 4}, {16, 1},
  {3, 6}, {7, 3}, {10, 7}, {13, 4}, {1, 6}, {4, 2}, {8, 7}, {11, 3}, {14, 0}, {2, 2}, {5, 6}, {9, 3}, {12, 7}, {15, 4}, {6, 1}, {16, 6},
  {3, 2}, {7, 7}, {10, 3}, {13, 0}, {1, 2}, {4, 6}, {8, 3}, {11, 7}, {14, 4}, {2, 6}, {5, 2}, {9, 7}, {12, 3}, {15, 0}, {6, 5}, {16, 2},
  {3, 7}, {7, 4}, {10, 0}, {13, 5}, {1, 7}, {4, 3}, {8, 0}, {11, 4}, {14, 1}, {2, 3}, {5, 7}, {9, 4}, {12, 0}, {15, 5}, {6, 2}, {16, 7},
  {3, 3}, {7, 0}, {10, 4}, {13, 1}, {1, 3}, {4, 7}, {8, 4}, {11, 0}, {14, 5}, {2, 7}, {5, 3}, {9, 0}, {12, 4}, {15, 1}, {6, 6}, {16, 3},
  {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, 
  {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, 
  {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, 
  {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}, {0, 0}
};

void initializeTouchHandling() {
  if (LINNMODEL == 200) {
    CELLCOUNT = 201;
    for (byte i = 0; i < MAX_CELLCOUNT; ++i) {
      SCANNED_CELLS[i][0] = SCANNED_CELLS_200[i][0];
      SCANNED_CELLS[i][1] = SCANNED_CELLS_200[i][1];
    }
  }
  else if (LINNMODEL == 128) {
    CELLCOUNT = 129;
    for (byte i = 0; i < MAX_CELLCOUNT; ++i) {
      SCANNED_CELLS[i][0] = SCANNED_CELLS_128[i][0];
      SCANNED_CELLS[i][1] = SCANNED_CELLS_128[i][1];
    }
  }
}

inline void nextSensorCell() {
  static byte controlRow = 0;

  sensorCol = SCANNED_CELLS[cellCount][0];
  sensorRow = SCANNED_CELLS[cellCount][1];
  if (++cellCount >= CELLCOUNT) {
    cellCount = 0;
  }

  // we're only scanning one of the eight control switches on each surface scan,
  // they don't need as many updates as the playing keys
  if (sensorCol == 0) {
    sensorRow = controlRow;
    if (++controlRow >= 8) {
      controlRow = 0;
    }
  }

  updateSensorCell();
}

inline void updateSensorCell() {
  sensorSplit = getSplitOf(sensorCol);
  sensorCell = &cell(sensorCol, sensorRow);
  // we're keeping track of the state of X, Y and Z so that we don't refresh it needlessly for finger tracking
  sensorCell->shouldRefreshData();
}


// getNoteNumber:
// computes MIDI note number from current row, column, row offset, octave button and transposition amount
byte getNoteNumber(byte split, byte col, byte row) {
  byte notenum = 0;

  // return the computed note based on the selected rowOffset
  short noteCol = col;
  if (isLeftHandedSplit(split)) {
    noteCol = (NUMCOLS - col);
  }

  notenum = determineRowOffsetNote(split, row) + (noteCol * Global.colOffset) - 1;

  return notenum - Split[split].transposeLights;
}

short determineRowOffsetNote(byte split, byte row) {
  if (Global.rowOffset <= 12) {                       // if rowOffset is set to between 0 and 12..

    short offset = Global.rowOffset == ROWOFFSET_OCTAVECUSTOM ? Global.customRowOffset : Global.rowOffset;

    // choose lowest to minimize disabled notes
    short range = Global.colOffset * (NUMCOLS - 1) + offset * (NUMROWS - 1);
    short lowest = 60 - range/2;

    if (lowest < 21)
    {
      lowest = 21;
    }

    if (lowest + range < 21)
    {
      lowest = 21 - range;
    }

    if (lowest > 120)
    {
      lowest = 120;
    }
    
    if (lowest + range > 120)
    {
      lowest = 120 - range;
    }

    if (Global.rowOffset == ROWOFFSET_NOOVERLAP) {    // no overlap mode
      byte lowCol, highCol;
      getSplitBoundaries(split, lowCol, highCol);

      offset = highCol - lowCol;                      // calculate the row offset based on the width of the split the column belongs to
      if (Global.splitActive && split == RIGHT) {     // if the right split is displayed, change the column so that it the lower left starting
        getSplitBoundaries(LEFT, lowCol, highCol);    // point starts at the same point as the left split, behaving as if there were two independent
        lowest = lowest - (highCol - lowCol);         // LinnStruments next to each-other
      }
    }
    else if (offset == -17) {                         // if custom row offset is set to inverted guitar tuning...
      offset = -5;                                    // standard guitar offset is 5 semitones

      if (row <= 1) {                                 // except from row 1 downwards where it's shifted by one
        lowest -= 1;
      }
    }
    else if (offset >= 12) {                          // start the octave offset one octave lower to prevent having disabled notes at the top in the default configuration
      lowest = 18;
    }
    else if (offset <= -12) {
      lowest = 18 - 7 * offset;
    }

    return lowest + (row * offset);
  }
  else if (Global.rowOffset == ROWOFFSET_GUITAR) {    // if rowOffset is set to guitar tuning...
    return Global.guitarTuning[row];
  }
  else {                                              // Global.rowOffset == ROWOFFSET_ZERO, rowOffset is set to zero...
    return 30;                                        // 30 = F#2, which is 10 semitones below guitar low E (E3/52). High E = E5/76
  }
}

void getSplitBoundaries(byte sp, byte& lowCol, byte& highCol) {
  // Set ranges of columns to be scanned (all of one split only)
  if (Global.splitActive) {                    // if Split mode is on
    if (sp == LEFT) {                   // and it's the left split
      lowCol = 1;                       // set column range to left split
      highCol = Global.splitPoint;
    }
    else {                              // if it's the right split
      lowCol = Global.splitPoint;       // set column range to right split
      highCol = NUMCOLS;
    }
  }
  else {                                // if Split mode is off
    lowCol = 1;                         // set column range to all columns
    highCol = NUMCOLS;
  }
}

void setFocusCellToLatest(byte sp, byte channel) {
  byte lowCol;                          // lowest column to be scanned
  byte highCol;                         // highest column to be scanned
  getSplitBoundaries(sp, lowCol, highCol);

  unsigned long latestTouch = 0;                 // temporarily holds the latest touch of all touched cells

  for (byte col = lowCol; col < highCol; ++col) {            // count through the columns
    for (byte row = 0; row < NUMROWS; ++row) {               // count through the rows within each column
      if (cell(col, row).touched == touchedCell &&           // if the addressed cell is touched...
          cell(col, row).channel == channel) {               // and uses the appropriate channel
        unsigned long last = cell(col, row).lastTouch;
        if (last > latestTouch) {                            // if this cell is touched later than any found so far...
          latestTouch = last;                                // then save it...
          focus(sp, channel).col = col;                      // and reassign focus to this cell
          focus(sp, channel).row = row;
        }
      }
    }
  }

  // at this point, all touched cells have been scanned and focus has been reassigned to the latest touched cell
  // if this was the last note to be released, reset the focused cell data
  if (latestTouch == 0) {
    focus(sp, channel).col = 0;   // column 0 are the control keys, so this combination can never be true for playing keys
    focus(sp, channel).row = 0;
  }
}

inline byte otherSplit() {
  return RIGHT-sensorSplit;
}

inline byte otherSplit(byte split) {
  return RIGHT-split;
}

inline byte splitLowestEdge(byte split) {
  if (isLeftHandedSplit(split)) {
    if (split == RIGHT) {
      return NUMCOLS - 1;
    }
    return Global.splitPoint - 1;
  }
  else {
    if (split == LEFT) {
      return 1;
    }
    return Global.splitPoint;
  }
}

inline boolean isLeftHandedSplit(byte split) {
  return Device.otherHanded && (Device.splitHandedness == reversedBoth || (split == LEFT && Device.splitHandedness == reversedLeft) || (split == RIGHT && Device.splitHandedness == reversedRight));
}

// If split mode is on and the specified column is in the right split, returns RIGHT, otherwise LEFT.
inline byte getSplitOf(byte col) {
  if (Global.splitActive && !Split[Global.currentPerSplit].sequencer) {
    if (col < Global.splitPoint) {
      return LEFT;
    }
    else {
      return RIGHT;
    }
  }
  else {
    return Global.currentPerSplit;
  }
}