
20020225 meeting notes [cc, rwb] for device/bank rework
-------------------------------------------------------

From the user perspective:

 * Current bank/program dialog remains (renamed from Manage Devices
   to something like Manage Banks, Manage Programs or Manage Presets).

 * Bank/program dialog allows editing of banks and programs for each
   device but nothing else (not adding or removing devices, not
   renaming devices, nothing).

 * New Manage Devices dialog which enumerates the devices (a list
   of names entirely under the user's control -- user can add, remove
   and rename) and associates each with a "Connection" (chosen from a
   dropdown of ALSA ports) and "Channels" (All or a subset of 1-16).
   Connection and Channels are settable in this dialog.

 * The default list of Devices (when you start up a fresh install of
   RG) contains one per ALSA port, with some dummy names and a GM map
   on each.

 * Instrument dropdown offers one entry per Device, and where a Device
   listens on more than one channel, it offers a submenu of Instruments
   corresponding to the channels for that Device.

From the code perspective:

 * Current Device classes remain, but internally become associated
   with ALSA Port + Channel Map instead of ALSA Client.

 * Current Instrument classes remain more or less unchanged.

 * Devices continue to have only user-provided name and a number
   counted up from zero -- i.e. the connection between Device and
   Port/Channel Map is entirely reconfigurable -- how does this
   affect saving/loading?  Save .rg files with the current config
   for Connections in them, but permit reload regardless of whether
   they match the current setup or not?


Implementation notes
~~~~~~~~~~~~~~~~~~~~

On the sequencer side, MappedDevice is just a container for
MappedInstruments.  These are concretely related to the ALSA
read/write destination via the AlsaPort list in AlsaDriver, which maps
instrument numbers onto ALSA ports.

On the GUI side, everything is already set up with the device list and
instrument sublists in pretty much the way we want; the problem is
just that the devices are being mapped directly onto concrete
MappedDevices.

We have two possibilities:

 1. The sequencer maintains the mapping of devices to "connections",
 where either

    a. the MappedDevice is the "connection" and a new Device class is
    introduced on the sequencer side to represent the virtual Device, or

    b. the MappedDevice becomes the virtual Device on the sequencer
    side and a new Connection class is introduced

 2. The GUI maintains the mapping of devices to "connections".  The
 Device class continues to be the virtual Device, the MappedDevice
 remains concrete, but a new class on the GUI side is introduced to be
 the thing that gets converted to the MappedDevice when communicating
 with the sequencer.

I had thought option 2 looked easier to implement in our current
scheme, but now I think it has problems with Instrument management
(because the Instruments are originated at the sequencer, and so must
have a virtual Device to associate with).  I suspect option 1b may be
the best bet.  It's certainly the most elegant.


Implementation strategy
~~~~~~~~~~~~~~~~~~~~~~~

Ultimately we're working towards allowing the sequencer to specify
whether it's able to support device reconnection (i.e. with ALSA it
should be, but with the existing ArtsDriver which we don't want to
change it shouldn't).  A sequencer able to support device reconnection
should be able to supply a list of the available Connections (just
names, presumably -- corresponding to ALSA ports in this case) and
offer an API for reassociating a Device with a new Connection, as well
as for creating and deleting Devices.  All this stuff would be used by
the GUI's Manage Devices dialog only (i.e. nothing else in the GUI
would care whether the sequencer has reconnectable devices or not) and
be available to external processes for automation through DCOP.

 1. Create a new Driver class (ExperimentalAlsaDriver or something).
 It should return one Device per ALSA port and the usual 16 Instruments
 for that Device, but internally should also maintain a map of
 Connections between Devices and actual ALSA ports (in other words, the
 Devices it returns should simply be the default set in the new scheme).
 Test.  Don't provide any reconnection API.

 2. Implement DCOP-based reconnection API -- should in theory be
 pretty trivial... shouldn't it?

    * Change names so as to make it clearer that the default name for
      each MIDI Device is indeed only a default (the port name probably
      shouldn't really be part of the name, but should be appended by
      querying the Connection for the Device).  I think we need a very
      simple Connection structure that contains only a string (connection
      name): we query the driver to find out which connection a given
      device has, and to find out the list of all connections (this is
      what should happen on sync()), and to actually connect a device to
      a connection.  Un-re-connectable drivers would just refuse the
      latter function (and report that they're un-re-connectable).
 
 3. Then worry about channel groups.  I'm very vague on this still.

 4. ???

 5. Profit!


Some more observations
~~~~~~~~~~~~~~~~~~~~~~

 * The name you give a Device and the banks and programs you assign to
   it are entirely between you, the GUI and the .rg file.  The sequencer
   never knows about them.  The sequencer provides default names on
   startup ("Hardware MIDI Device 2"), but autoload.rg and any other .rg
   file you load should override them -- if the devices in those files are
   actually named -- I'm inclined to think the default autoload.rg should
   include several devices but not name them -- there's a complication
   generally in how you deal with devices listed in autoload that
   outnumber the available connections -- one possible hack might be to
   show them only if they have names (and then without a connection). Ew.
   Room for experimentation.

 * Adding and removing Devices _from the GUI_ needs to percolate through
   to the sequencer, which has to add and remove the Devices in its list
   and then inform the GUI which needs to update cleanly (i.e. not by
   simply clearing out the Studio and starting again).  This is probably
   the trickiest point as it doesn't seem to work correctly now either.

 * Adding and removing ALSA clients (the hotplug thing) is not actually
   a case of adding or removing devices but of adding or removing
   connections.  When a connection is removed, the sequencer should
   simply set any devices connected to it to an unconnected state.  When
   a connection is added, we could just assign the first unconnected
   device to it, and only create a new device if we have no unconnected
   ones.  Then update to GUI as before.

