====== Control Changes ======

The code that sends out Control Changes in Rosegarden is pretty convoluted.  This document points out the key areas of interest.  Hopefully this will ease future maintenance.

Note that code related to sending out Bank Selects and Program Changes can be found along with the code related to Control Changes.  This will be pointed out below.

===== Allow Reset All Controllers (CC 121) =====

This preference sends a CC 121 at file load and at playback in the middle of a Segment.  The 121 happens prior to sending any other controllers to set up the channel.

The user can turn this on and off in the MIDI preferences:

  Edit > Preferences... > MIDI > General tab

The MIDI preferences are displayed by the ''MIDIConfigurationPage'' class.  The preference itself is stored in Rosegarden.conf as follows:

  [Sequencer_Options]
  allowresetallcontrollers=true

===== Force Channel Setups =====

This is a preference that is only available via the Rosegarden.conf file.

  [Sequencer_Options]
  forceChannelSetups=false

When set to true, channel setups will be sent out every time play is pressed.  If outside of a Segment, the channel setups will be based on the track values in the Instrument Parameters panel (MIPP).

The default for this preference is false.

===== Manage Controllers dialog =====

To get there: Studio > Manage MIDI Devices > pick a playback device > Controllers...

The ''ControlEditorDialog'' class is the "Manage Controllers" dialog.
    
//A better name for this class might be "''ManageControllers''".//
    
Controllers can be added, modified and deleted here.  Deleting a controller here will prevent it from ever being sent out at composition load time, and playback time.

===== MIDI Instrument Parameters =====

The ''MIDIInstrumentParameterPanel'' class is the "Instrument Parameters" panel that appears in the lower left when a MIDI track is selected.  Here the user can adjust the initial settings for the various controllers that were configured in the "Manage Controllers" dialog for a Device.

===== Controller Rulers =====

The ''ControllerEventsRuler'' class provides the controller rulers that can be displayed in both the Matrix and Notation editors.  These can be enabled from both editors by:

  View > Rulers > Add Control Ruler > ...

Or for the pitchbend ruler:

  View > Rulers > Show Pitch Bend Ruler

===== Controller Sequence dialog =====

The ''PitchbendSequenceDialog'' class provides both the controller sequence dialogs and the "PitchBend Sequence" dialog.

These dialogs are accessible from both the Matrix and Notation editors:

  Controllers > Insert Controller Sequence...
  Controllers > Insert Pitch Bend Sequence...

Both of these dialogs require that a note be selected in order to launch them.  The menu items will be disabled if no note is selected.  Also, for the controller sequence dialog, a controller ruler must be enabled and selected.

===== Control Changes at Composition Load =====

Call diagram.  ">" means "calls".

<file>
- RosegardenMainWindow::setDocument()
  > RosegardenDocument::initialiseStudio()
    > RosegardenDocument::sendChannelSetups()  (added January 2021)
      > Instrument::sendChannelSetup()
</file>

==== RosegardenMainWindow::setDocument() ====

  * Called when a new Composition is loaded.
  * Calls ''RosegardenDocument::initialiseStudio()''

==== RosegardenDocument::initialiseStudio() ====

  * Calls ''RosegardenDocument::sendChannelSetups()''

==== RosegardenDocument::sendChannelSetups() ====

  * Added January 2021.
  * Calls ''Instrument::sendChannelSetup()''

==== Instrument::sendChannelSetup() ====

  * Sends the channel setups at file load time.
  * Sends BS/PC for the channel as well.
  * This also might be the code that sends channel setups at the beginning of a MIDI File export.

===== Control Changes at Playback =====

<file>
- InternalSegmentMapper::makeReady()
  > InternalSegmentMapper::getControllers()
    > InternalSegmentMapper::getControllerValue()
      > ControllerContextMap::getControllerValue()
  > ChannelManager::makeReady()
</file>

==== InternalSegmentMapper::makeReady() ====

  * Calls ''InternalSegmentMapper::getControllers()'' to get the controllers that are needed for a channel setup.
  * Calls ''ChannelManager::makeReady()'' to set up the channel.

==== InternalSegmentMapper::getControllers() ====

  * Eventually calls ''ControllerContextMap::getControllerValue()'' which gets the current CC values when in the middle of a Segment.

==== ControllerContextMap ====

  * A map of CC values over the course of a ''Segment''.
  * Can be queried to find out the last CC that was sent prior to a given time.

==== ChannelManager::makeReady() ====

  * If playback is starting in the middle of the ''Segment'', sends out a channel setup.

===== Control Changes at MIDI File Export =====

If changes are made to the way CCs are sent, MIDI export needs to be regression tested to make sure nothing breaks.

<file>
- MidiFile::convertToMidi()
  > MappedBufMetaIterator::fetchFixedChannelSetup(inserter)
    > InternalSegmentMapper::insertChannelSetup(inserter)
      > ChannelManager::insertChannelSetup(TrackId, RealTime, ...)
</file>