/[svn]/linuxsampler/trunk/src/drivers/midi/MidiInstrumentMapper.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/drivers/midi/MidiInstrumentMapper.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1135 - (show annotations) (download) (as text)
Thu Mar 29 09:40:45 2007 UTC (13 years, 4 months ago) by iliev
File MIME type: text/x-c++hdr
File size: 12449 byte(s)
* Added new LSCP command - SET FX_SEND NAME
* The default map is now the first available map

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 static int GetMapCount();
217
218 /**
219 * Gets the ID of the default map.
220 * For now, the default map is the first available map. When
221 * the default map is removed, the default map becomes the next available map.
222 * @return The ID of the default map or -1 if the there are no maps added.
223 */
224 static int GetDefaultMap();
225
226 /**
227 * Sets the default map.
228 * @param MapId The ID of the new default map.
229 */
230 static void SetDefaultMap(int MapId);
231
232 protected:
233 /**
234 * Notifies listeners that the number of MIDI instruments
235 * on the specified MIDI instrument map has been changed.
236 * @param MapId The numerical ID of the MIDI instrument map.
237 * @param NewCount The new number of MIDI instruments.
238 */
239 static void fireMidiInstrumentCountChanged(int MapId, int NewCount);
240
241 /**
242 * Notifies listeners that a MIDI instrument
243 * in a MIDI instrument map is changed.
244 * @param MapId The numerical ID of the MIDI instrument map.
245 * @param Bank The index of the MIDI bank, containing the instrument.
246 * @param Program The MIDI program number of the instrument.
247 */
248 static void fireMidiInstrumentInfoChanged(int MapId, int Bank, int Program);
249
250 /**
251 * Notifies listeners that the number of MIDI instrument maps has been changed.
252 * @param NewCount The new number of MIDI instrument maps.
253 */
254 static void fireMidiInstrumentMapCountChanged(int NewCount);
255
256 /**
257 * Notifies listeners that the settings of a MIDI instrument map are changed.
258 */
259 static void fireMidiInstrumentMapInfoChanged(int MapId);
260
261 static optional<entry_t> GetEntry(int Map, midi_prog_index_t Index); // shall only be used by MidiInputPort ATM (see source comment)
262 friend class MidiInputPort; // allow MidiInputPort to access GetEntry()
263
264 private:
265 static ListenerList<MidiInstrumentCountListener*> llMidiInstrumentCountListeners;
266 static ListenerList<MidiInstrumentInfoListener*> llMidiInstrumentInfoListeners;
267 static ListenerList<MidiInstrumentMapCountListener*> llMidiInstrumentMapCountListeners;
268 static ListenerList<MidiInstrumentMapInfoListener*> llMidiInstrumentMapInfoListeners;
269
270 static int DefaultMap;
271 };
272
273 } // namespace LinuxSampler
274
275 #endif // __LS_MIDIINSTRUMENTMAPPER_H__

  ViewVC Help
Powered by ViewVC