drivers/midi/MidiInstrumentMapper.h

/***************************************************************************
 *                                                                         *
 *   Copyright (C) 2006 Christian Schoenebeck                              *
 *                                                                         *
 *   This library is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This library is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this library; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_MIDIINSTRUMENTMAPPER_H__
#define __LS_MIDIINSTRUMENTMAPPER_H__

#include <map>

#include "midi.h"
#include "../../EventListeners.h"
#include "../../common/global.h"
#include "../../common/optional.h"
#include "../../engines/InstrumentManager.h"

namespace LinuxSampler {

    // just symbol prototyping
    class MidiInputPort;

    /** @brief 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.
     */
    class MidiInstrumentMapper {
        public:
            /**
             * Defines the life-time strategy for an instrument.
             */
            enum mode_t {
                ON_DEMAND      = 0,  ///< Instrument will be loaded when needed, freed once not needed anymore.
                ON_DEMAND_HOLD = 1,  ///< Instrument will be loaded when needed and kept even if not needed anymore.
                PERSISTENT     = 2,  ///< Instrument will immediately be loaded and kept all the time.
                VOID           = 127 ///< Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.
            };

            /**
             * Defines the instrument and settings a MIDI bank MSB, LSB,
             * program triple ought to be mapped to.
             */
            struct entry_t {
                String EngineName;      ///< The sampler engine to be used.
                String InstrumentFile;  ///< File name of the instrument to be loaded.
                uint   InstrumentIndex; ///< Index of the instrument within its file.
                mode_t LoadMode;        ///< Life-time strategy of instrument.
                float  Volume;          ///< Global volume factor for this instrument.
                String Name;            ///< Display name that should be associated with this mapping entry.
            };

            /**
             * Registers the specified listener to be notified when the number
             * of MIDI instruments on a particular MIDI instrument map is changed.
             */
            static void AddMidiInstrumentCountListener(MidiInstrumentCountListener* l);

            /**
             * Removes the specified listener.
             */
            static void RemoveMidiInstrumentCountListener(MidiInstrumentCountListener* l);

            /**
             * Registers the specified listener to be notified when
             * a MIDI instrument in a MIDI instrument map is changed.
             */
            static void AddMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);

            /**
             * Removes the specified listener.
             */
            static void RemoveMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);

            /**
             * Registers the specified listener to be notified
             * when the number of MIDI instrument maps is changed.
             */
            static void AddMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);

            /**
             * Removes the specified listener.
             */
            static void RemoveMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);

            /**
             * Registers the specified listener to be notified when
             * the settings of a MIDI instrument map are changed.
             */
            static void AddMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);

            /**
             * Removes the specified listener.
             */
            static void RemoveMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);

            /**
             * Adds a new entry to the given MIDI instrument map in case
             * an entry with \a 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 \a 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).
             *
             * @param Map   - map index
             * @param Index - unique index of the new entry to add
             * @param Entry - the actual instrument and settings
             * @param bInBackground - avoid this method to block for long time
             * @throws Exception - if the given map or engine type does not
             *                     exist or instrument loading failed
             */
            static void AddOrReplaceEntry(int Map, midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);

            /**
             * Remove an existing entry from the MIDI instrument map.
             *
             * @param Map   - map index
             * @param Index - index of entry to delete
             */
            static void RemoveEntry(int Map, midi_prog_index_t Index);

            /**
             * Clear the whole given MIDI instrument map, that is delete all
             * its entries.
             *
             * @param Map - map index
             */
            static void RemoveAllEntries(int Map);

            /**
             * Returns the currently existing MIDI instrument map entries
             * of the given map with their current settings.
             *
             * @param Map - map index
             * @throws Exception - in case \a Map does not exist
             */
            static std::map<midi_prog_index_t,entry_t> Entries(int Map) throw (Exception);

            /**
             * Returns the IDs of all currently existing MIDI instrument
             * maps.
             */
            static std::vector<int> Maps();

            /**
             * Create a new MIDI instrument map. Optionally you can assign
             * a custom name for the map. Map names don't have to be unique.
             *
             * @param MapName - (optional) name for the map
             * @returns ID of the new map
             * @throws Exception - if there's no free map ID left
             */
            static int AddMap(String MapName = "") throw (Exception) ;

            /**
             * Returns the custom name of the given map.
             *
             * @param Map - map index
             * @throws Exception - if given map does not exist
             */
            static String MapName(int Map) throw (Exception);

            /**
             * Rename the given, already existing map. Map names don't have
             * to be unique.
             *
             * @param Map - map index
             * @param NewName - the map's new name to be assigned
             * @throws Exception - if the given map does not exist
             */
            static void RenameMap(int Map, String NewName) throw (Exception);

            /**
             * Delete the given map.
             *
             * @param Map - ID of the map to delete
             */
            static void RemoveMap(int Map);

            /**
             * Completely delete all existing maps.
             */
            static void RemoveAllMaps();

        protected:
            /**
             * Notifies listeners that the number of MIDI instruments
             * on the specified MIDI instrument map has been changed.
             * @param MapId The numerical ID of the MIDI instrument map.
             * @param NewCount The new number of MIDI instruments.
             */
            static void fireMidiInstrumentCountChanged(int MapId, int NewCount);

            /**
             * Notifies listeners that a MIDI instrument
             * in a MIDI instrument map is changed.
             * @param MapId The numerical ID of the MIDI instrument map.
             * @param Bank The index of the MIDI bank, containing the instrument.
             * @param Program The MIDI program number of the instrument.
             */
            static void fireMidiInstrumentInfoChanged(int MapId, int Bank, int Program);

             /**
             * Notifies listeners that the number of MIDI instrument maps has been changed.
             * @param NewCount The new number of MIDI instrument maps.
             */
            static void fireMidiInstrumentMapCountChanged(int NewCount);

            /**
             * Notifies listeners that the settings of a MIDI instrument map are changed.
             */
            static void fireMidiInstrumentMapInfoChanged(int MapId);

            static optional<entry_t> GetEntry(int Map, midi_prog_index_t Index); // shall only be used by MidiInputPort ATM (see source comment)
            friend class MidiInputPort; // allow MidiInputPort to access GetEntry()

        private:
            static ListenerList<MidiInstrumentCountListener*> llMidiInstrumentCountListeners;
            static ListenerList<MidiInstrumentInfoListener*> llMidiInstrumentInfoListeners;
            static ListenerList<MidiInstrumentMapCountListener*> llMidiInstrumentMapCountListeners;
            static ListenerList<MidiInstrumentMapInfoListener*> llMidiInstrumentMapInfoListeners;
    };

} // namespace LinuxSampler

#endif // __LS_MIDIINSTRUMENTMAPPER_H__
1	/***************************************************************************
2	* *
3	* Copyright (C) 2006 Christian Schoenebeck *
4	* *
5	* This library is free software; you can redistribute it and/or modify *
6	* it under the terms of the GNU General Public License as published by *
7	* the Free Software Foundation; either version 2 of the License, or *
8	* (at your option) any later version. *
9	* *
10	* This library is distributed in the hope that it will be useful, *
11	* but WITHOUT ANY WARRANTY; without even the implied warranty of *
12	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13	* GNU General Public License for more details. *
14	* *
15	* You should have received a copy of the GNU General Public License *
16	* along with this library; if not, write to the Free Software *
17	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
18	* MA 02111-1307 USA *
19	***************************************************************************/
20
21	#ifndef __LS_MIDIINSTRUMENTMAPPER_H__
22	#define __LS_MIDIINSTRUMENTMAPPER_H__
23
24	#include <map>
25
26	#include "midi.h"
27	#include "../../EventListeners.h"
28	#include "../../common/global.h"
29	#include "../../common/optional.h"
30	#include "../../engines/InstrumentManager.h"
31
32	namespace LinuxSampler {
33
34	// just symbol prototyping
35	class MidiInputPort;
36
37	/** @brief Mapping MIDI bank/program numbers with real instruments.
38	*
39	* By default (that is on startup) the sampler will simply ignore all
40	* MIDI program change messages. The MidiInstrumentMapper allows to map
41	* arbitrary (MIDI bank MSB, MIDI bank LSB, MIDI program) triples with
42	* an actual (Sampler Engine, Instrument File, Index) triple, so the
43	* sampler knows which instrument to load on the respective MIDI program
44	* change messages.
45	*
46	* The sampler allows to manage arbitrary amount of MIDI instrument
47	* maps. For example you might create (at least) two MIDI instrument
48	* maps: one for "normal" instruments and one for drumkits.
49	*/
50	class MidiInstrumentMapper {
51	public:
52	/**
53	* Defines the life-time strategy for an instrument.
54	*/
55	enum mode_t {
56	ON_DEMAND = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
57	ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
58	PERSISTENT = 2, ///< Instrument will immediately be loaded and kept all the time.
59	VOID = 127 ///< Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.
60	};
61
62	/**
63	* Defines the instrument and settings a MIDI bank MSB, LSB,
64	* program triple ought to be mapped to.
65	*/
66	struct entry_t {
67	String EngineName; ///< The sampler engine to be used.
68	String InstrumentFile; ///< File name of the instrument to be loaded.
69	uint InstrumentIndex; ///< Index of the instrument within its file.
70	mode_t LoadMode; ///< Life-time strategy of instrument.
71	float Volume; ///< Global volume factor for this instrument.
72	String Name; ///< Display name that should be associated with this mapping entry.
73	};
74
75	/**
76	* Registers the specified listener to be notified when the number
77	* of MIDI instruments on a particular MIDI instrument map is changed.
78	*/
79	static void AddMidiInstrumentCountListener(MidiInstrumentCountListener* l);
80
81	/**
82	* Removes the specified listener.
83	*/
84	static void RemoveMidiInstrumentCountListener(MidiInstrumentCountListener* l);
85
86	/**
87	* Registers the specified listener to be notified when
88	* a MIDI instrument in a MIDI instrument map is changed.
89	*/
90	static void AddMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);
91
92	/**
93	* Removes the specified listener.
94	*/
95	static void RemoveMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);
96
97	/**
98	* Registers the specified listener to be notified
99	* when the number of MIDI instrument maps is changed.
100	*/
101	static void AddMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);
102
103	/**
104	* Removes the specified listener.
105	*/
106	static void RemoveMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);
107
108	/**
109	* Registers the specified listener to be notified when
110	* the settings of a MIDI instrument map are changed.
111	*/
112	static void AddMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);
113
114	/**
115	* Removes the specified listener.
116	*/
117	static void RemoveMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);
118
119	/**
120	* Adds a new entry to the given MIDI instrument map in case
121	* an entry with \a Index does not exist yet, otherwise it will
122	* replace the existing entry. Note that some given settings
123	* might simply be ignored or might change the settings of other
124	* entries in the map (i.e. because another instrument in the
125	* map is part of the same file and the respective sampler
126	* engine does not allow to use different LoadModes for
127	* instruments of the same file). Note that in case of a
128	* PERSISTENT LoadMode argument the given instrument will
129	* immediately be loaded, that means by default this method will
130	* block until the whole instrument was loaded completely. You
131	* can override this behavior by setting \a bInBackground to
132	* true, so the instrument will be loaded in a separate thread
133	* (in that case you won't catch loading errors though, i.e. if
134	* the file does not exist or might be corrupt for example).
135	*
136	* @param Map - map index
137	* @param Index - unique index of the new entry to add
138	* @param Entry - the actual instrument and settings
139	* @param bInBackground - avoid this method to block for long time
140	* @throws Exception - if the given map or engine type does not
141	* exist or instrument loading failed
142	*/
143	static void AddOrReplaceEntry(int Map, midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);
144
145	/**
146	* Remove an existing entry from the MIDI instrument map.
147	*
148	* @param Map - map index
149	* @param Index - index of entry to delete
150	*/
151	static void RemoveEntry(int Map, midi_prog_index_t Index);
152
153	/**
154	* Clear the whole given MIDI instrument map, that is delete all
155	* its entries.
156	*
157	* @param Map - map index
158	*/
159	static void RemoveAllEntries(int Map);
160
161	/**
162	* Returns the currently existing MIDI instrument map entries
163	* of the given map with their current settings.
164	*
165	* @param Map - map index
166	* @throws Exception - in case \a Map does not exist
167	*/
168	static std::map<midi_prog_index_t,entry_t> Entries(int Map) throw (Exception);
169
170	/**
171	* Returns the IDs of all currently existing MIDI instrument
172	* maps.
173	*/
174	static std::vector<int> Maps();
175
176	/**
177	* Create a new MIDI instrument map. Optionally you can assign
178	* a custom name for the map. Map names don't have to be unique.
179	*
180	* @param MapName - (optional) name for the map
181	* @returns ID of the new map
182	* @throws Exception - if there's no free map ID left
183	*/
184	static int AddMap(String MapName = "") throw (Exception) ;
185
186	/**
187	* Returns the custom name of the given map.
188	*
189	* @param Map - map index
190	* @throws Exception - if given map does not exist
191	*/
192	static String MapName(int Map) throw (Exception);
193
194	/**
195	* Rename the given, already existing map. Map names don't have
196	* to be unique.
197	*
198	* @param Map - map index
199	* @param NewName - the map's new name to be assigned
200	* @throws Exception - if the given map does not exist
201	*/
202	static void RenameMap(int Map, String NewName) throw (Exception);
203
204	/**
205	* Delete the given map.
206	*
207	* @param Map - ID of the map to delete
208	*/
209	static void RemoveMap(int Map);
210
211	/**
212	* Completely delete all existing maps.
213	*/
214	static void RemoveAllMaps();
215
216	protected:
217	/**
218	* Notifies listeners that the number of MIDI instruments
219	* on the specified MIDI instrument map has been changed.
220	* @param MapId The numerical ID of the MIDI instrument map.
221	* @param NewCount The new number of MIDI instruments.
222	*/
223	static void fireMidiInstrumentCountChanged(int MapId, int NewCount);
224
225	/**
226	* Notifies listeners that a MIDI instrument
227	* in a MIDI instrument map is changed.
228	* @param MapId The numerical ID of the MIDI instrument map.
229	* @param Bank The index of the MIDI bank, containing the instrument.
230	* @param Program The MIDI program number of the instrument.
231	*/
232	static void fireMidiInstrumentInfoChanged(int MapId, int Bank, int Program);
233
234	/**
235	* Notifies listeners that the number of MIDI instrument maps has been changed.
236	* @param NewCount The new number of MIDI instrument maps.
237	*/
238	static void fireMidiInstrumentMapCountChanged(int NewCount);
239
240	/**
241	* Notifies listeners that the settings of a MIDI instrument map are changed.
242	*/
243	static void fireMidiInstrumentMapInfoChanged(int MapId);
244
245	static optional<entry_t> GetEntry(int Map, midi_prog_index_t Index); // shall only be used by MidiInputPort ATM (see source comment)
246	friend class MidiInputPort; // allow MidiInputPort to access GetEntry()
247
248	private:
249	static ListenerList<MidiInstrumentCountListener*> llMidiInstrumentCountListeners;
250	static ListenerList<MidiInstrumentInfoListener*> llMidiInstrumentInfoListeners;
251	static ListenerList<MidiInstrumentMapCountListener*> llMidiInstrumentMapCountListeners;
252	static ListenerList<MidiInstrumentMapInfoListener*> llMidiInstrumentMapInfoListeners;
253	};
254
255	} // namespace LinuxSampler
256
257	#endif // __LS_MIDIINSTRUMENTMAPPER_H__