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

            /**
             * Adds a new entry to the sampler's 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 Index - unique index of the new entry to add
             * @param Entry - the actual instrument and settings
             * @throws Exception - if the given engine type does not exist or instrument loading failed
             */
            static void AddOrReplaceMapping(midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);

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

            /**
             * Clear the whole MIDI instrument map, that is delete all
             * entries.
             */
            static void RemoveAllMappings();

            /**
             * Returns the currently existing MIDI instrument map entries
             * with their current settings.
             */
            static std::map<midi_prog_index_t,entry_t> Mappings();

        protected:
            static optional<entry_t> GetEntry(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	/***************************************************************************
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	*/
45	class MidiInstrumentMapper {
46	public:
47	/**
48	* Defines the life-time strategy for an instrument.
49	*/
50	enum mode_t {
51	ON_DEMAND = 0, ///< Instrument will be loaded when needed, freed once not needed anymore.
52	ON_DEMAND_HOLD = 1, ///< Instrument will be loaded when needed and kept even if not needed anymore.
53	PERSISTENT = 2, ///< Instrument will immediately be loaded and kept all the time.
54	VOID = 127 ///< Don't care, let it up to the InstrumentManager to decide for an appropriate LoadMode.
55	};
56
57	/**
58	* Defines the instrument and settings a MIDI bank MSB, LSB,
59	* program triple ought to be mapped to.
60	*/
61	struct entry_t {
62	String EngineName; ///< The sampler engine to be used.
63	String InstrumentFile; ///< File name of the instrument to be loaded.
64	uint InstrumentIndex; ///< Index of the instrument within its file.
65	mode_t LoadMode; ///< Life-time strategy of instrument.
66	float Volume; ///< Global volume factor for this instrument.
67	String Name; ///< Display name that should be associated with this mapping.
68	};
69
70	/**
71	* Adds a new entry to the sampler's MIDI instrument map in case
72	* an entry with \a Index does not exist yet, otherwise it will
73	* replace the existing entry. Note that some given settings
74	* might simply be ignored or might change the settings of other
75	* entries in the map (i.e. because another instrument in the
76	* map is part of the same file and the respective sampler
77	* engine does not allow to use different LoadModes for
78	* instruments of the same file). Note that in case of a
79	* PERSISTENT LoadMode argument the given instrument will
80	* immediately be loaded, that means by default this method will
81	* block until the whole instrument was loaded completely. You
82	* can override this behavior by setting \a bInBackground to
83	* true, so the instrument will be loaded in a separate thread
84	* (in that case you won't catch loading errors though, i.e. if
85	* the file does not exist or might be corrupt for example).
86	*
87	* @param Index - unique index of the new entry to add
88	* @param Entry - the actual instrument and settings
89	* @throws Exception - if the given engine type does not exist or instrument loading failed
90	*/
91	static void AddOrReplaceMapping(midi_prog_index_t Index, entry_t Entry, bool bInBackground = false) throw (Exception);
92
93	/**
94	* Remove an existing entry from the MIDI instrument map.
95	*
96	* @param Index - index of entry to delete
97	*/
98	static void RemoveMapping(midi_prog_index_t Index);
99
100	/**
101	* Clear the whole MIDI instrument map, that is delete all
102	* entries.
103	*/
104	static void RemoveAllMappings();
105
106	/**
107	* Returns the currently existing MIDI instrument map entries
108	* with their current settings.
109	*/
110	static std::map<midi_prog_index_t,entry_t> Mappings();
111
112	protected:
113	static optional<entry_t> GetEntry(midi_prog_index_t Index); // shall only be used by MidiInputPort ATM (see source comment)
114	friend class MidiInputPort; // allow MidiInputPort to access GetEntry()
115	};
116
117	} // namespace LinuxSampler
118
119	#endif // __LS_MIDIINSTRUMENTMAPPER_H__