drivers/midi/MidiInstrumentMapper.h

/***************************************************************************
 *                                                                         *
 *   Copyright (C) 2006 - 2009 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 "../../EventListeners.h"
#include "../../common/global.h"
#include "../../common/optional.h"
#include "../../engines/InstrumentManager.h"
#include "midi.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.
                #if !defined(WIN32)
                VOID           = 127, ///< @deprecated use DONTCARE instead!
                #endif
                DONTCARE       = 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);

            /**
             * Gets an entry from the MIDI instrument map.
             *
             * @param Map   - map index
             * @param Index - index of entry to retrieve
             */
            static entry_t GetEntry(int Map, uint MidiBank, uint MidiProg);

            /**
             * 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();

            /**
             * Returns amount of currently available MIDI instrument maps.
             */
            static int GetMapCount();

            /**
             * Returns the amount of currently available MIDI instruments in all maps.
             * @param Map - ID of the map
             */
            static int GetInstrumentCount();

            /**
             * Returns the amount of currently available MIDI instruments in the specified map.
             * @param Map - ID of the map
             */
            static int GetInstrumentCount(int Map);

            /**
             * 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.
             * @return The ID of the default map or -1 if the there are no maps added.
             */
            static int GetDefaultMap();

            /**
             * Sets the default map.
             * @param MapId The ID of the new default map.
             */
            static void SetDefaultMap(int MapId);

        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 EngineChannel ATM (see source comment)
            friend class EngineChannel; // allow EngineChannel to access GetEntry()

        private:
            /**
             * Sets the load mode of the specified entry.
             * The following field should be set before calling this method:
             * pEntry->EngineName, pEntry->InstrumentFile, pEntry->InstrumentIndex
             */
            static void SetLoadMode(entry_t* pEntry);

            static ListenerList<MidiInstrumentCountListener*> llMidiInstrumentCountListeners;
            static ListenerList<MidiInstrumentInfoListener*> llMidiInstrumentInfoListeners;
            static ListenerList<MidiInstrumentMapCountListener*> llMidiInstrumentMapCountListeners;
            static ListenerList<MidiInstrumentMapInfoListener*> llMidiInstrumentMapInfoListeners;
            
            static int DefaultMap;
    };

} // namespace LinuxSampler

#endif // __LS_MIDIINSTRUMENTMAPPER_H__
1	schoenebeck	947	/***************************************************************************
2			* *
3	persson	1924	* Copyright (C) 2006 - 2009 Christian Schoenebeck *
4	schoenebeck	947	* *
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	iliev	1130	#include <map>
25
26			#include "../../EventListeners.h"
27	schoenebeck	947	#include "../../common/global.h"
28			#include "../../common/optional.h"
29			#include "../../engines/InstrumentManager.h"
30	persson	1713	#include "midi.h"
31	schoenebeck	947
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	schoenebeck	973	*
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	schoenebeck	947	*/
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	senoner	1481	#if !defined(WIN32)
60			VOID = 127, ///< @deprecated use DONTCARE instead!
61			#endif
62			DONTCARE = 127 ///< Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.
63	schoenebeck	947	};
64
65			/**
66			* Defines the instrument and settings a MIDI bank MSB, LSB,
67			* program triple ought to be mapped to.
68			*/
69			struct entry_t {
70			String EngineName; ///< The sampler engine to be used.
71			String InstrumentFile; ///< File name of the instrument to be loaded.
72			uint InstrumentIndex; ///< Index of the instrument within its file.
73			mode_t LoadMode; ///< Life-time strategy of instrument.
74			float Volume; ///< Global volume factor for this instrument.
75	schoenebeck	973	String Name; ///< Display name that should be associated with this mapping entry.
76	schoenebeck	947	};
77
78			/**
79	iliev	1130	* Registers the specified listener to be notified when the number
80			* of MIDI instruments on a particular MIDI instrument map is changed.
81			*/
82			static void AddMidiInstrumentCountListener(MidiInstrumentCountListener* l);
83
84			/**
85			* Removes the specified listener.
86			*/
87			static void RemoveMidiInstrumentCountListener(MidiInstrumentCountListener* l);
88
89			/**
90			* Registers the specified listener to be notified when
91			* a MIDI instrument in a MIDI instrument map is changed.
92			*/
93			static void AddMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);
94
95			/**
96			* Removes the specified listener.
97			*/
98			static void RemoveMidiInstrumentInfoListener(MidiInstrumentInfoListener* l);
99
100			/**
101			* Registers the specified listener to be notified
102			* when the number of MIDI instrument maps is changed.
103			*/
104			static void AddMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);
105
106			/**
107			* Removes the specified listener.
108			*/
109			static void RemoveMidiInstrumentMapCountListener(MidiInstrumentMapCountListener* l);
110
111			/**
112			* Registers the specified listener to be notified when
113			* the settings of a MIDI instrument map are changed.
114			*/
115			static void AddMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);
116
117			/**
118			* Removes the specified listener.
119			*/
120			static void RemoveMidiInstrumentMapInfoListener(MidiInstrumentMapInfoListener* l);
121
122			/**
123	schoenebeck	973	* Adds a new entry to the given MIDI instrument map in case
124	schoenebeck	947	* an entry with \a Index does not exist yet, otherwise it will
125			* replace the existing entry. Note that some given settings
126			* might simply be ignored or might change the settings of other
127			* entries in the map (i.e. because another instrument in the
128			* map is part of the same file and the respective sampler
129			* engine does not allow to use different LoadModes for
130			* instruments of the same file). Note that in case of a
131			* PERSISTENT LoadMode argument the given instrument will
132			* immediately be loaded, that means by default this method will
133			* block until the whole instrument was loaded completely. You
134			* can override this behavior by setting \a bInBackground to
135			* true, so the instrument will be loaded in a separate thread
136			* (in that case you won't catch loading errors though, i.e. if
137			* the file does not exist or might be corrupt for example).
138			*
139	schoenebeck	973	* @param Map - map index
140	schoenebeck	947	* @param Index - unique index of the new entry to add
141			* @param Entry - the actual instrument and settings
142	schoenebeck	973	* @param bInBackground - avoid this method to block for long time
143			* @throws Exception - if the given map or engine type does not
144			* exist or instrument loading failed
145	schoenebeck	947	*/
146	schoenebeck	973	static void AddOrReplaceEntry(int Map, midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);
147	schoenebeck	947
148			/**
149	iliev	1763	* Gets an entry from the MIDI instrument map.
150			*
151			* @param Map - map index
152			* @param Index - index of entry to retrieve
153			*/
154			static entry_t GetEntry(int Map, uint MidiBank, uint MidiProg);
155
156			/**
157	schoenebeck	947	* Remove an existing entry from the MIDI instrument map.
158			*
159	schoenebeck	973	* @param Map - map index
160	schoenebeck	947	* @param Index - index of entry to delete
161			*/
162	schoenebeck	973	static void RemoveEntry(int Map, midi_prog_index_t Index);
163	schoenebeck	947
164			/**
165	schoenebeck	973	* Clear the whole given MIDI instrument map, that is delete all
166			* its entries.
167			*
168			* @param Map - map index
169	schoenebeck	947	*/
170	schoenebeck	973	static void RemoveAllEntries(int Map);
171	schoenebeck	947
172			/**
173			* Returns the currently existing MIDI instrument map entries
174	schoenebeck	973	* of the given map with their current settings.
175			*
176			* @param Map - map index
177			* @throws Exception - in case \a Map does not exist
178	schoenebeck	947	*/
179	schoenebeck	973	static std::map<midi_prog_index_t,entry_t> Entries(int Map) throw (Exception);
180	schoenebeck	947
181	schoenebeck	973	/**
182			* Returns the IDs of all currently existing MIDI instrument
183			* maps.
184			*/
185			static std::vector<int> Maps();
186
187			/**
188			* Create a new MIDI instrument map. Optionally you can assign
189			* a custom name for the map. Map names don't have to be unique.
190			*
191			* @param MapName - (optional) name for the map
192			* @returns ID of the new map
193			* @throws Exception - if there's no free map ID left
194			*/
195			static int AddMap(String MapName = "") throw (Exception) ;
196
197			/**
198			* Returns the custom name of the given map.
199			*
200			* @param Map - map index
201			* @throws Exception - if given map does not exist
202			*/
203			static String MapName(int Map) throw (Exception);
204
205			/**
206			* Rename the given, already existing map. Map names don't have
207			* to be unique.
208			*
209			* @param Map - map index
210			* @param NewName - the map's new name to be assigned
211			* @throws Exception - if the given map does not exist
212			*/
213			static void RenameMap(int Map, String NewName) throw (Exception);
214
215			/**
216			* Delete the given map.
217			*
218			* @param Map - ID of the map to delete
219			*/
220			static void RemoveMap(int Map);
221
222			/**
223			* Completely delete all existing maps.
224			*/
225			static void RemoveAllMaps();
226
227	schoenebeck	1695	/**
228			* Returns amount of currently available MIDI instrument maps.
229			*/
230	iliev	1135	static int GetMapCount();
231
232			/**
233	iliev	1763	* Returns the amount of currently available MIDI instruments in all maps.
234			* @param Map - ID of the map
235			*/
236			static int GetInstrumentCount();
237
238			/**
239			* Returns the amount of currently available MIDI instruments in the specified map.
240			* @param Map - ID of the map
241			*/
242			static int GetInstrumentCount(int Map);
243
244			/**
245	iliev	1135	* Gets the ID of the default map.
246			* For now, the default map is the first available map. When
247			* the default map is removed, the default map becomes the next available map.
248			* @return The ID of the default map or -1 if the there are no maps added.
249			*/
250			static int GetDefaultMap();
251
252			/**
253			* Sets the default map.
254			* @param MapId The ID of the new default map.
255			*/
256			static void SetDefaultMap(int MapId);
257
258	schoenebeck	947	protected:
259	iliev	1130	/**
260			* Notifies listeners that the number of MIDI instruments
261			* on the specified MIDI instrument map has been changed.
262			* @param MapId The numerical ID of the MIDI instrument map.
263			* @param NewCount The new number of MIDI instruments.
264			*/
265			static void fireMidiInstrumentCountChanged(int MapId, int NewCount);
266
267			/**
268			* Notifies listeners that a MIDI instrument
269			* in a MIDI instrument map is changed.
270			* @param MapId The numerical ID of the MIDI instrument map.
271			* @param Bank The index of the MIDI bank, containing the instrument.
272			* @param Program The MIDI program number of the instrument.
273			*/
274			static void fireMidiInstrumentInfoChanged(int MapId, int Bank, int Program);
275
276			/**
277			* Notifies listeners that the number of MIDI instrument maps has been changed.
278			* @param NewCount The new number of MIDI instrument maps.
279			*/
280			static void fireMidiInstrumentMapCountChanged(int NewCount);
281
282			/**
283			* Notifies listeners that the settings of a MIDI instrument map are changed.
284			*/
285			static void fireMidiInstrumentMapInfoChanged(int MapId);
286
287	persson	1924	static optional<entry_t> GetEntry(int Map, midi_prog_index_t Index); // shall only be used by EngineChannel ATM (see source comment)
288			friend class EngineChannel; // allow EngineChannel to access GetEntry()
289	iliev	1130
290			private:
291	iliev	1763	/**
292			* Sets the load mode of the specified entry.
293			* The following field should be set before calling this method:
294			* pEntry->EngineName, pEntry->InstrumentFile, pEntry->InstrumentIndex
295			*/
296			static void SetLoadMode(entry_t* pEntry);
297
298	iliev	1130	static ListenerList<MidiInstrumentCountListener*> llMidiInstrumentCountListeners;
299			static ListenerList<MidiInstrumentInfoListener*> llMidiInstrumentInfoListeners;
300			static ListenerList<MidiInstrumentMapCountListener*> llMidiInstrumentMapCountListeners;
301			static ListenerList<MidiInstrumentMapInfoListener*> llMidiInstrumentMapInfoListeners;
302	iliev	1135
303			static int DefaultMap;
304	schoenebeck	947	};
305
306			} // namespace LinuxSampler
307
308			#endif // __LS_MIDIINSTRUMENTMAPPER_H__