linuxsampler 2.3.1
LinuxSampler::MidiInstrumentMapper Class Reference

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

#include <MidiInstrumentMapper.h>

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_tEntries (int Map) throw (Exception)
 Returns the currently existing MIDI instrument map entries of the given map with their current settings.
 
static std::vector< intMaps ()
 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 50 of file MidiInstrumentMapper.h.

Member Enumeration Documentation

◆ mode_t

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 55 of file MidiInstrumentMapper.h.

Member Function Documentation

◆ AddMap()

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

◆ AddMidiInstrumentCountListener()

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.

◆ AddMidiInstrumentInfoListener()

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.

◆ AddMidiInstrumentMapCountListener()

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

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

◆ AddMidiInstrumentMapInfoListener()

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.

◆ AddOrReplaceEntry()

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
Index- unique index of the new entry to add
Entry- the actual instrument and settings
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

◆ Entries()

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

◆ fireMidiInstrumentCountChanged()

static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentCountChanged ( int  MapId,
int  NewCount 
)
staticprotected

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

Parameters
MapIdThe numerical ID of the MIDI instrument map.
NewCountThe new number of MIDI instruments.

◆ fireMidiInstrumentInfoChanged()

static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentInfoChanged ( int  MapId,
int  Bank,
int  Program 
)
staticprotected

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

Parameters
MapIdThe numerical ID of the MIDI instrument map.
BankThe index of the MIDI bank, containing the instrument.
ProgramThe MIDI program number of the instrument.

◆ fireMidiInstrumentMapCountChanged()

static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentMapCountChanged ( int  NewCount)
staticprotected

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

Parameters
NewCountThe new number of MIDI instrument maps.

◆ fireMidiInstrumentMapInfoChanged()

static void LinuxSampler::MidiInstrumentMapper::fireMidiInstrumentMapInfoChanged ( int  MapId)
staticprotected

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

◆ GetDefaultMap()

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.

◆ GetEntry() [1/2]

static optional< entry_t > LinuxSampler::MidiInstrumentMapper::GetEntry ( int  Map,
midi_prog_index_t  Index 
)
staticprotected

◆ GetEntry() [2/2]

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
Index- index of entry to retrieve

◆ GetInstrumentCount() [1/2]

static int LinuxSampler::MidiInstrumentMapper::GetInstrumentCount ( )
static

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

Parameters
Map- ID of the map

◆ GetInstrumentCount() [2/2]

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

◆ GetMapCount()

static int LinuxSampler::MidiInstrumentMapper::GetMapCount ( )
static

Returns amount of currently available MIDI instrument maps.

◆ MapName()

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

◆ Maps()

static std::vector< int > LinuxSampler::MidiInstrumentMapper::Maps ( )
static

Returns the IDs of all currently existing MIDI instrument maps.

◆ RemoveAllEntries()

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

◆ RemoveAllMaps()

static void LinuxSampler::MidiInstrumentMapper::RemoveAllMaps ( )
static

Completely delete all existing maps.

◆ RemoveEntry()

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
Index- index of entry to delete

◆ RemoveMap()

static void LinuxSampler::MidiInstrumentMapper::RemoveMap ( int  Map)
static

Delete the given map.

Parameters
Map- ID of the map to delete

◆ RemoveMidiInstrumentCountListener()

static void LinuxSampler::MidiInstrumentMapper::RemoveMidiInstrumentCountListener ( MidiInstrumentCountListener l)
static

Removes the specified listener.

◆ RemoveMidiInstrumentInfoListener()

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

Removes the specified listener.

◆ RemoveMidiInstrumentMapCountListener()

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

Removes the specified listener.

◆ RemoveMidiInstrumentMapInfoListener()

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

Removes the specified listener.

◆ RenameMap()

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
NewName- the map's new name to be assigned
Exceptions
Exception- if the given map does not exist

◆ SetDefaultMap()

static void LinuxSampler::MidiInstrumentMapper::SetDefaultMap ( int  MapId)
static

Sets the default map.

Parameters
MapIdThe ID of the new default map.

Friends And Related Symbol Documentation

◆ EngineChannel

Definition at line 288 of file MidiInstrumentMapper.h.


The documentation for this class was generated from the following file: