LinuxSampler::MidiInstrumentMapper Class Reference

Mapping MIDI bank/program numbers with real instruments. More...

#include <MidiInstrumentMapper.h>

List of all members.

Classes

struct  entry_t
 Defines the instrument and settings a MIDI bank MSB, LSB, program triple ought to be mapped to. More...

Public Types

enum  mode_t {
  ON_DEMAND = 0, ON_DEMAND_HOLD = 1, PERSISTENT = 2, VOID = 127,
  DONTCARE = 127
}
 

Defines the life-time strategy for an instrument.

More...

Static Public Member Functions

static void AddMidiInstrumentCountListener (MidiInstrumentCountListener *l)
 Registers the specified listener to be notified when the number of MIDI instruments on a particular MIDI instrument map is changed.
static void RemoveMidiInstrumentCountListener (MidiInstrumentCountListener *l)
 Removes the specified listener.
static void AddMidiInstrumentInfoListener (MidiInstrumentInfoListener *l)
 Registers the specified listener to be notified when a MIDI instrument in a MIDI instrument map is changed.
static void RemoveMidiInstrumentInfoListener (MidiInstrumentInfoListener *l)
 Removes the specified listener.
static void AddMidiInstrumentMapCountListener (MidiInstrumentMapCountListener *l)
 Registers the specified listener to be notified when the number of MIDI instrument maps is changed.
static void RemoveMidiInstrumentMapCountListener (MidiInstrumentMapCountListener *l)
 Removes the specified listener.
static void AddMidiInstrumentMapInfoListener (MidiInstrumentMapInfoListener *l)
 Registers the specified listener to be notified when the settings of a MIDI instrument map are changed.
static void RemoveMidiInstrumentMapInfoListener (MidiInstrumentMapInfoListener *l)
 Removes the specified listener.
static void AddOrReplaceEntry (int Map, midi_prog_index_t Index, entry_t Entry, bool bInBackground=false) throw (Exception)
 Adds a new entry to the given MIDI instrument map in case an entry with Index does not exist yet, otherwise it will replace the existing entry.
static entry_t GetEntry (int Map, uint MidiBank, uint MidiProg)
 Gets an entry from the MIDI instrument map.
static void RemoveEntry (int Map, midi_prog_index_t Index)
 Remove an existing entry from the MIDI instrument map.
static void RemoveAllEntries (int Map)
 Clear the whole given MIDI instrument map, that is delete all its entries.
static std::map
< midi_prog_index_t, entry_t
Entries (int Map) throw (Exception)
 Returns the currently existing MIDI instrument map entries of the given map with their current settings.
static std::vector< int > Maps ()
 Returns the IDs of all currently existing MIDI instrument maps.
static int AddMap (String MapName="") throw (Exception)
 Create a new MIDI instrument map.
static String MapName (int Map) throw (Exception)
 Returns the custom name of the given map.
static void RenameMap (int Map, String NewName) throw (Exception)
 Rename the given, already existing map.
static void RemoveMap (int Map)
 Delete the given map.
static void RemoveAllMaps ()
 Completely delete all existing maps.
static int GetMapCount ()
 Returns amount of currently available MIDI instrument maps.
static int GetInstrumentCount ()
 Returns the amount of currently available MIDI instruments in all maps.
static int GetInstrumentCount (int Map)
 Returns the amount of currently available MIDI instruments in the specified map.
static int GetDefaultMap ()
 Gets the ID of the default map.
static void SetDefaultMap (int MapId)
 Sets the default map.

Static Protected Member Functions

static void fireMidiInstrumentCountChanged (int MapId, int NewCount)
 Notifies listeners that the number of MIDI instruments on the specified MIDI instrument map has been changed.
static void fireMidiInstrumentInfoChanged (int MapId, int Bank, int Program)
 Notifies listeners that a MIDI instrument in a MIDI instrument map is changed.
static void fireMidiInstrumentMapCountChanged (int NewCount)
 Notifies listeners that the number of MIDI instrument maps has been changed.
static void fireMidiInstrumentMapInfoChanged (int MapId)
 Notifies listeners that the settings of a MIDI instrument map are changed.
static optional< entry_tGetEntry (int Map, midi_prog_index_t Index)

Friends

class EngineChannel

Detailed Description

Mapping MIDI bank/program numbers with real instruments.

By default (that is on startup) the sampler will simply ignore all MIDI program change messages. The MidiInstrumentMapper allows to map arbitrary (MIDI bank MSB, MIDI bank LSB, MIDI program) triples with an actual (Sampler Engine, Instrument File, Index) triple, so the sampler knows which instrument to load on the respective MIDI program change messages.

The sampler allows to manage arbitrary amount of MIDI instrument maps. For example you might create (at least) two MIDI instrument maps: one for "normal" instruments and one for drumkits.

Definition at line 48 of file MidiInstrumentMapper.h.


Member Enumeration Documentation

Defines the life-time strategy for an instrument.

Enumerator:
ON_DEMAND 

Instrument will be loaded when needed, freed once not needed anymore.

ON_DEMAND_HOLD 

Instrument will be loaded when needed and kept even if not needed anymore.

PERSISTENT 

Instrument will immediately be loaded and kept all the time.

VOID 
Deprecated:
use DONTCARE instead!
DONTCARE 

Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.

Definition at line 53 of file MidiInstrumentMapper.h.


Member Function Documentation

static int LinuxSampler::MidiInstrumentMapper::AddMap ( String  MapName = ""  )  throw (Exception) [static]

Create a new MIDI instrument map.

Optionally you can assign a custom name for the map. Map names don't have to be unique.

Parameters:
MapName - (optional) name for the map
Returns:
ID of the new map
Exceptions:
Exception - if there's no free map ID left
static void LinuxSampler::MidiInstrumentMapper::AddMidiInstrumentCountListener ( MidiInstrumentCountListener l  )  [static]

Registers the specified listener to be notified when the number of MIDI instruments on a particular MIDI instrument map is changed.

static void LinuxSampler::MidiInstrumentMapper::AddMidiInstrumentInfoListener ( MidiInstrumentInfoListener l  )  [static]

Registers the specified listener to be notified when a MIDI instrument in a MIDI instrument map is changed.

static void LinuxSampler::MidiInstrumentMapper::AddMidiInstrumentMapCountListener ( MidiInstrumentMapCountListener l  )  [static]

Registers the specified listener to be notified when the number of MIDI instrument maps is changed.

static void LinuxSampler::MidiInstrumentMapper::AddMidiInstrumentMapInfoListener ( MidiInstrumentMapInfoListener l  )  [static]

Registers the specified listener to be notified when the settings of a MIDI instrument map are changed.

static void LinuxSampler::MidiInstrumentMapper::AddOrReplaceEntry ( int  Map,
midi_prog_index_t  Index,
entry_t  Entry,
bool  bInBackground = false 
) throw (Exception) [static]

Adds a new entry to the given MIDI instrument map in case an entry with Index does not exist yet, otherwise it will replace the existing entry.

Note that some given settings might simply be ignored or might change the settings of other entries in the map (i.e. because another instrument in the map is part of the same file and the respective sampler engine does not allow to use different LoadModes for instruments of the same file). Note that in case of a PERSISTENT LoadMode argument the given instrument will immediately be loaded, that means by default this method will block until the whole instrument was loaded completely. You can override this behavior by setting bInBackground to true, so the instrument will be loaded in a separate thread (in that case you won't catch loading errors though, i.e. if the file does not exist or might be corrupt for example).

Parameters:
Map - map index
Parameters:
Index - unique index of the new entry to add
Parameters:
Entry - the actual instrument and settings
Parameters:
bInBackground - avoid this method to block for long time
Exceptions:
Exception - if the given map or engine type does not exist or instrument loading failed
static std::map<midi_prog_index_t,entry_t> LinuxSampler::MidiInstrumentMapper::Entries ( int  Map  )  throw (Exception) [static]

Returns the currently existing MIDI instrument map entries of the given map with their current settings.

Parameters:
Map - map index
Exceptions:
Exception - in case Map does not exist
static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentCountChanged ( int  MapId,
int  NewCount 
) [static, protected]

Notifies listeners that the number of MIDI instruments on the specified MIDI instrument map has been changed.

Parameters:
MapId The numerical ID of the MIDI instrument map.
Parameters:
NewCount The new number of MIDI instruments.
static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentInfoChanged ( int  MapId,
int  Bank,
int  Program 
) [static, protected]

Notifies listeners that a MIDI instrument in a MIDI instrument map is changed.

Parameters:
MapId The numerical ID of the MIDI instrument map.
Parameters:
Bank The index of the MIDI bank, containing the instrument.
Parameters:
Program The MIDI program number of the instrument.
static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentMapCountChanged ( int  NewCount  )  [static, protected]

Notifies listeners that the number of MIDI instrument maps has been changed.

Parameters:
NewCount The new number of MIDI instrument maps.
static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentMapInfoChanged ( int  MapId  )  [static, protected]

Notifies listeners that the settings of a MIDI instrument map are changed.

static int LinuxSampler::MidiInstrumentMapper::GetDefaultMap (  )  [static]

Gets the ID of the default map.

For now, the default map is the first available map. When the default map is removed, the default map becomes the next available map.

Returns:
The ID of the default map or -1 if the there are no maps added.
static optional<entry_t> LinuxSampler::MidiInstrumentMapper::GetEntry ( int  Map,
midi_prog_index_t  Index 
) [static, protected]
static entry_t LinuxSampler::MidiInstrumentMapper::GetEntry ( int  Map,
uint  MidiBank,
uint  MidiProg 
) [static]

Gets an entry from the MIDI instrument map.

Parameters:
Map - map index
Parameters:
Index - index of entry to retrieve
static int LinuxSampler::MidiInstrumentMapper::GetInstrumentCount ( int  Map  )  [static]

Returns the amount of currently available MIDI instruments in the specified map.

Parameters:
Map - ID of the map
static int LinuxSampler::MidiInstrumentMapper::GetInstrumentCount (  )  [static]

Returns the amount of currently available MIDI instruments in all maps.

Parameters:
Map - ID of the map
static int LinuxSampler::MidiInstrumentMapper::GetMapCount (  )  [static]

Returns amount of currently available MIDI instrument maps.

static String LinuxSampler::MidiInstrumentMapper::MapName ( int  Map  )  throw (Exception) [static]

Returns the custom name of the given map.

Parameters:
Map - map index
Exceptions:
Exception - if given map does not exist
static std::vector<int> LinuxSampler::MidiInstrumentMapper::Maps (  )  [static]

Returns the IDs of all currently existing MIDI instrument maps.

static void LinuxSampler::MidiInstrumentMapper::RemoveAllEntries ( int  Map  )  [static]

Clear the whole given MIDI instrument map, that is delete all its entries.

Parameters:
Map - map index
static void LinuxSampler::MidiInstrumentMapper::RemoveAllMaps (  )  [static]

Completely delete all existing maps.

static void LinuxSampler::MidiInstrumentMapper::RemoveEntry ( int  Map,
midi_prog_index_t  Index 
) [static]

Remove an existing entry from the MIDI instrument map.

Parameters:
Map - map index
Parameters:
Index - index of entry to delete
static void LinuxSampler::MidiInstrumentMapper::RemoveMap ( int  Map  )  [static]

Delete the given map.

Parameters:
Map - ID of the map to delete
static void LinuxSampler::MidiInstrumentMapper::RemoveMidiInstrumentCountListener ( MidiInstrumentCountListener l  )  [static]

Removes the specified listener.

static void LinuxSampler::MidiInstrumentMapper::RemoveMidiInstrumentInfoListener ( MidiInstrumentInfoListener l  )  [static]

Removes the specified listener.

static void LinuxSampler::MidiInstrumentMapper::RemoveMidiInstrumentMapCountListener ( MidiInstrumentMapCountListener l  )  [static]

Removes the specified listener.

static void LinuxSampler::MidiInstrumentMapper::RemoveMidiInstrumentMapInfoListener ( MidiInstrumentMapInfoListener l  )  [static]

Removes the specified listener.

static void LinuxSampler::MidiInstrumentMapper::RenameMap ( int  Map,
String  NewName 
) throw (Exception) [static]

Rename the given, already existing map.

Map names don't have to be unique.

Parameters:
Map - map index
Parameters:
NewName - the map's new name to be assigned
Exceptions:
Exception - if the given map does not exist
static void LinuxSampler::MidiInstrumentMapper::SetDefaultMap ( int  MapId  )  [static]

Sets the default map.

Parameters:
MapId The ID of the new default map.

Friends And Related Function Documentation

friend class EngineChannel [friend]

Definition at line 286 of file MidiInstrumentMapper.h.


The documentation for this class was generated from the following file:
Generated on Sat Jan 28 08:43:18 2012 for linuxsampler by  doxygen 1.6.3