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 "../../common/global.h"
#include "../../common/optional.h"
#include "midi.h"
#include "../../engines/InstrumentManager.h"

#include <map>

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.
            };

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

} // namespace LinuxSampler

#endif // __LS_MIDIINSTRUMENTMAPPER_H__
1	schoenebeck	947	/***************************************************************************
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 "../../common/global.h"
25			#include "../../common/optional.h"
26			#include "midi.h"
27			#include "../../engines/InstrumentManager.h"
28
29			#include <map>
30
31			namespace LinuxSampler {
32
33			// just symbol prototyping
34			class MidiInputPort;
35
36			/** @brief Mapping MIDI bank/program numbers with real instruments.
37			*
38			* By default (that is on startup) the sampler will simply ignore all
39			* MIDI program change messages. The MidiInstrumentMapper allows to map
40			* arbitrary (MIDI bank MSB, MIDI bank LSB, MIDI program) triples with
41			* an actual (Sampler Engine, Instrument File, Index) triple, so the
42			* sampler knows which instrument to load on the respective MIDI program
43			* change messages.
44	schoenebeck	973	*
45			* The sampler allows to manage arbitrary amount of MIDI instrument
46			* maps. For example you might create (at least) two MIDI instrument
47			* maps: one for "normal" instruments and one for drumkits.
48	schoenebeck	947	*/
49			class MidiInstrumentMapper {
50			public:
51			/**
52			* Defines the life-time strategy for an instrument.
53			*/
54			enum mode_t {
55			ON_DEMAND = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
56			ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
57			PERSISTENT = 2, ///< Instrument will immediately be loaded and kept all the time.
58			VOID = 127 ///< Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.
59			};
60
61			/**
62			* Defines the instrument and settings a MIDI bank MSB, LSB,
63			* program triple ought to be mapped to.
64			*/
65			struct entry_t {
66			String EngineName; ///< The sampler engine to be used.
67			String InstrumentFile; ///< File name of the instrument to be loaded.
68			uint InstrumentIndex; ///< Index of the instrument within its file.
69			mode_t LoadMode; ///< Life-time strategy of instrument.
70			float Volume; ///< Global volume factor for this instrument.
71	schoenebeck	973	String Name; ///< Display name that should be associated with this mapping entry.
72	schoenebeck	947	};
73
74			/**
75	schoenebeck	973	* Adds a new entry to the given MIDI instrument map in case
76	schoenebeck	947	* an entry with \a Index does not exist yet, otherwise it will
77			* replace the existing entry. Note that some given settings
78			* might simply be ignored or might change the settings of other
79			* entries in the map (i.e. because another instrument in the
80			* map is part of the same file and the respective sampler
81			* engine does not allow to use different LoadModes for
82			* instruments of the same file). Note that in case of a
83			* PERSISTENT LoadMode argument the given instrument will
84			* immediately be loaded, that means by default this method will
85			* block until the whole instrument was loaded completely. You
86			* can override this behavior by setting \a bInBackground to
87			* true, so the instrument will be loaded in a separate thread
88			* (in that case you won't catch loading errors though, i.e. if
89			* the file does not exist or might be corrupt for example).
90			*
91	schoenebeck	973	* @param Map - map index
92	schoenebeck	947	* @param Index - unique index of the new entry to add
93			* @param Entry - the actual instrument and settings
94	schoenebeck	973	* @param bInBackground - avoid this method to block for long time
95			* @throws Exception - if the given map or engine type does not
96			* exist or instrument loading failed
97	schoenebeck	947	*/
98	schoenebeck	973	static void AddOrReplaceEntry(int Map, midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);
99	schoenebeck	947
100			/**
101			* Remove an existing entry from the MIDI instrument map.
102			*
103	schoenebeck	973	* @param Map - map index
104	schoenebeck	947	* @param Index - index of entry to delete
105			*/
106	schoenebeck	973	static void RemoveEntry(int Map, midi_prog_index_t Index);
107	schoenebeck	947
108			/**
109	schoenebeck	973	* Clear the whole given MIDI instrument map, that is delete all
110			* its entries.
111			*
112			* @param Map - map index
113	schoenebeck	947	*/
114	schoenebeck	973	static void RemoveAllEntries(int Map);
115	schoenebeck	947
116			/**
117			* Returns the currently existing MIDI instrument map entries
118	schoenebeck	973	* of the given map with their current settings.
119			*
120			* @param Map - map index
121			* @throws Exception - in case \a Map does not exist
122	schoenebeck	947	*/
123	schoenebeck	973	static std::map<midi_prog_index_t,entry_t> Entries(int Map) throw (Exception);
124	schoenebeck	947
125	schoenebeck	973	/**
126			* Returns the IDs of all currently existing MIDI instrument
127			* maps.
128			*/
129			static std::vector<int> Maps();
130
131			/**
132			* Create a new MIDI instrument map. Optionally you can assign
133			* a custom name for the map. Map names don't have to be unique.
134			*
135			* @param MapName - (optional) name for the map
136			* @returns ID of the new map
137			* @throws Exception - if there's no free map ID left
138			*/
139			static int AddMap(String MapName = "") throw (Exception) ;
140
141			/**
142			* Returns the custom name of the given map.
143			*
144			* @param Map - map index
145			* @throws Exception - if given map does not exist
146			*/
147			static String MapName(int Map) throw (Exception);
148
149			/**
150			* Rename the given, already existing map. Map names don't have
151			* to be unique.
152			*
153			* @param Map - map index
154			* @param NewName - the map's new name to be assigned
155			* @throws Exception - if the given map does not exist
156			*/
157			static void RenameMap(int Map, String NewName) throw (Exception);
158
159			/**
160			* Delete the given map.
161			*
162			* @param Map - ID of the map to delete
163			*/
164			static void RemoveMap(int Map);
165
166			/**
167			* Completely delete all existing maps.
168			*/
169			static void RemoveAllMaps();
170
171	schoenebeck	947	protected:
172	schoenebeck	973	static optional<entry_t> GetEntry(int Map, midi_prog_index_t Index); // shall only be used by MidiInputPort ATM (see source comment)
173	schoenebeck	947	friend class MidiInputPort; // allow MidiInputPort to access GetEntry()
174			};
175
176			} // namespace LinuxSampler
177
178			#endif // __LS_MIDIINSTRUMENTMAPPER_H__