src/engines/EngineChannel.h

/***************************************************************************
 *                                                                         *
 *   Copyright (C) 2005 - 2020 Christian Schoenebeck                       *
 *                                                                         *
 *   This program 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 program 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 program; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __LS_ENGINECHANNEL_H__
#define __LS_ENGINECHANNEL_H__

#include "../EventListeners.h"
#include "../drivers/audio/AudioOutputDevice.h"
#include "../drivers/midi/midi.h"
#include "../drivers/midi/MidiInputDevice.h"
#include "../drivers/midi/MidiInputPort.h"
#include "../drivers/midi/VirtualMidiDevice.h"
#include "Engine.h"
#include "FxSend.h"

namespace LinuxSampler {

    // just symbol prototyping
    class Sampler;
    class SamplerChannel;
    class AudioOutputDevice;
    class MidiInputPort;
    class FxSend;


    /** @brief Channel Interface for LinuxSampler Sampler Engines
     *
     * Every sampler engine can be used on several sampler channels and
     * usually the same Engine instance is used on multiple sampler
     * channels. For this every sampler engine must also implement a class
     * which handles all channel dependant parameters and channel
     * dependant execution code.
     *
     * This abstract base interface class defines all mandatory methods
     * which have to be implemented by all engine channel implementations.
     */
    class EngineChannel {
        public:

            /////////////////////////////////////////////////////////////////
            // abstract methods
            //     (these have to be implemented by the descendant)

            // general sampler part management
            virtual void    Reset() = 0;
            virtual void    SendNoteOn(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel) = 0;
            virtual void    SendNoteOn(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual void    SendNoteOff(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel) = 0;
            virtual void    SendNoteOff(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual void    SendPitchbend(int Pitch, uint8_t MidiChannel) = 0;
            virtual void    SendPitchbend(int Pitch, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual void    SendControlChange(uint8_t Controller, uint8_t Value, uint8_t MidiChannel) = 0;
            virtual void    SendControlChange(uint8_t Controller, uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual void    SendProgramChange(uint8_t Program) = 0;
            virtual void    SendChannelPressure(uint8_t Value, uint8_t MidiChannel) = 0;
            virtual void    SendChannelPressure(uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual void    SendPolyphonicKeyPressure(uint8_t Key, uint8_t Value, uint8_t MidiChannel) = 0;
            virtual void    SendPolyphonicKeyPressure(uint8_t Key, uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
            virtual bool    StatusChanged(bool bNewStatus = false) = 0;
            virtual float   Volume() = 0;
            virtual void    Volume(float f) = 0;
            virtual float   Pan() = 0;
            virtual void    Pan(float f) = 0;
            virtual uint    Channels() = 0;

            // audio driver management
            virtual void    Connect(AudioOutputDevice* pAudioOut) = 0;
            virtual void    DisconnectAudioOutputDevice() = 0;
            virtual AudioOutputDevice* GetAudioOutputDevice() = 0;
            virtual void    SetOutputChannel(uint EngineAudioChannel, uint AudioDeviceChannel) = 0;
            virtual int     OutputChannel(uint EngineAudioChannel) = 0;

            // MIDI driver management
            virtual void    Connect(MidiInputPort* pMidiPort) = 0;
            virtual void    Disconnect(MidiInputPort* pMidiPort) = 0;
            virtual void    DisconnectAllMidiInputPorts() = 0;
            virtual uint    GetMidiInputPortCount() = 0;
            virtual MidiInputPort* GetMidiInputPort(uint index) = 0;
            virtual midi_chan_t MidiChannel() = 0;
            virtual void    SetMidiChannel(midi_chan_t MidiChannel) = 0;
            // (deprecated MIDI driver management methods)
            virtual void    Connect(MidiInputPort* pMidiPort, midi_chan_t MidiChannel) DEPRECATED_API = 0;
            virtual void    DisconnectMidiInputPort() DEPRECATED_API = 0;
            virtual MidiInputPort* GetMidiInputPort() DEPRECATED_API = 0;

            // virtual MIDI driver management (i.e. virtual on-screen MIDI keyboards)
            virtual void    Connect(VirtualMidiDevice* pDevice) = 0;
            virtual void    Disconnect(VirtualMidiDevice* pDevice) = 0;

            // instrument (sound file) management
            virtual void    PrepareLoadInstrument(const char* FileName, uint Instrument) = 0;
            virtual void    LoadInstrument() = 0;
            virtual String  InstrumentFileName() = 0; ///< Returns the file name of the currently loaded instrument. Equivalent as calling InstrumentFileName(0).
            virtual String  InstrumentFileName(int index);
            virtual String  InstrumentName() = 0;
            virtual int     InstrumentIndex() = 0;
            virtual int     InstrumentStatus() = 0;

            // sampler format / sampler engine implementation details
            virtual Engine* GetEngine() = 0;
            virtual String  EngineName() = 0;

            // effect routing
            virtual FxSend* AddFxSend(uint8_t MidiCtrl, String Name = "") throw (Exception) = 0;
            virtual FxSend* GetFxSend(uint FxSendIndex) = 0;
            virtual uint    GetFxSendCount() = 0;
            virtual void    RemoveFxSend(FxSend* pFxSend) = 0;


            /////////////////////////////////////////////////////////////////
            // normal methods
            //     (usually not to be overridden by descendant)

            /**
             * Sets the mute state of this channel.
             *
             * @param state - specifies the mute state of this sampler channel.
             * @throws Exception - if state does not contain valid
             * value.
             */
            void SetMute(int state) throw (Exception);

            /**
             * Determines whether this channel is muted.
             *
             * @returns 1 if the channel is muted, 0 if the channel is not muted
             * and -1 if the channel is muted because of presence of at least
             * one solo channel.
             */
            int GetMute();

            /**
             * Sets the solo state of this channel.
             *
             * @param solo - specifies whether this is a solo channel.
             */
            void SetSolo(bool solo);

            /**
             * Determines whether this is a solo channel.
             *
             * @returns true if this is a solo channel, false otherwise.
             */
            bool GetSolo();

            /**
             * Returns current MIDI program (change) number of this
             * EngineChannel.
             */
            uint8_t GetMidiProgram();

            /**
             * Change EngineChannel's MIDI program.
             */
            void SetMidiProgram(uint8_t Program);

            /**
             * Returns current MIDI bank MSB (coarse) number of this
             * EngineChannel.
             */
            uint8_t GetMidiBankMsb();

            /**
             * Change current MIDI bank MSB (coarse) number of this
             * EngineChannel.
             */
            void SetMidiBankMsb(uint8_t BankMSB);

            /**
             * Returns current MIDI bank LSB (fine) number of this
             * EngineChannel.
             */
            uint8_t GetMidiBankLsb();

            /**
             * Change current MIDI bank LSB (fine) number of this
             * EngineChannel.
             */
            void SetMidiBankLsb(uint8_t BankLSB);

            /**
             * Returns true if this EngineChannel is using no MIDI
             * instrument map at all, that is if it will ignore all MIDI
             * program change messages.
             *
             * @see UsesDefaultMidiInstrumentMap()
             * @see GetMidiInstrumentMap()
             */
            bool UsesNoMidiInstrumentMap();

            /**
             * Returns true if this EngineChannel is using the default MIDI
             * instrument map for handling MIDI program changes.
             *
             * @see UsesNoMidiInstrumentMap()
             * @see GetMidiInstrumentMap()
             */
            bool UsesDefaultMidiInstrumentMap();

            /**
             * Returns ID of the MIDI instrument map currently used by this
             * EngineChannel to handle MIDI program changes. You should
             * always call @c UsesNoMidiInstrumentMap() and
             * @c UsesDefaultMidiInstrumentMap() before calling this method
             * to check if this EngineChannel is probably using the default
             * map or no map at all, because in these two particular cases
             * this method would throw an exception!
             *
             * @throws Exception - if EngineChannel is set to no map at all
             *                     or is set to the default map
             * @see UsesNoMidiInstrumentMap()
             * @see UsesDefaultMidiInstrumentMap()
             */
            int GetMidiInstrumentMap() throw (Exception);

            /**
             * Let this EngineChannel use no MIDI instrument map at all,
             * that is to let it ignore all MIDI program change messages.
             *
             * @see SetMidiInstrumentMapToDefault()
             * @see SetMidiInstrumentMap()
             */
            void SetMidiInstrumentMapToNone();

            /**
             * Let this EngineChannel use the default MIDI instrument map to
             * handle MIDI program changes.
             *
             * @see SetMidiInstrumentMapToNone()
             * @see SetMidiInstrumentMap()
             */
            void SetMidiInstrumentMapToDefault();

            /**
             * Set a specific MIDI instrument map this EngineChannel should
             * use to handle MIDI program changes.
             *
             * @see SetMidiInstrumentMapToNone()
             * @see SetMidiInstrumentMapToDefault()
             *
             * @throws Exception - in case given map does not exist
             */
            void SetMidiInstrumentMap(int MidiMap) throw (Exception);

            /**
             * Set MIDI Registered Parameter Number (RPN)
             * (upper 7 bits / coarse).
             */
            void SetMidiRpnParameterMsb(uint8_t ParamMSB);

            /**
             * Set MIDI Registered Parameter Number (RPN)
             * (lower 7 bits / fine).
             */
            void SetMidiRpnParameterLsb(uint8_t ParamLSB);

            /**
             * Reset to no RPN parameter currently selected.
             */
            void ResetMidiRpnParameter();

            /**
             * Set MIDI Non-Registered Parameter Number (NRPN)
             * (upper 7 bits / coarse).
             */
            void SetMidiNrpnParameterMsb(uint8_t ParamMSB);

            /**
             * Set MIDI Non-Registered Parameter Number (NRPN)
             * (lower 7 bits / fine).
             */
            void SetMidiNrpnParameterLsb(uint8_t ParamLSB);

            /**
             * Reset to no NRPN parameter currently selected.
             */
            void ResetMidiNrpnParameter();

            /**
             * Get currently selected MIDI Registered Parameter Number
             * (RPN), this method will return the already merged 14 bit
             * parameter number (MSB and LSB value combined).
             *
             * @e WARNING: you have to call @c ResetMidiRpnParameter()
             * after using this value, otherwise all subsequent MIDI CC #6
             * (Data) messages are interpreted as RPN value messages.
             *
             * @returns currently selected (14 bit) RPN number, a negative
             *          value if no RPN parameter currently selected
             */
            int GetMidiRpnParameter();

            /**
             * Get currently selected MIDI Non-Registered Parameter Number
             * (NRPN), this method will return the already merged 14 bit
             * value (MSB and LSB value combined).
             *
             * @e WARNING: you have to call @c ResetMidiNrpnParameter()
             * after using this value, otherwise all subsequent MIDI CC #6
             * (Data) messages are interpreted as NRPN value messages.
             *
             * @returns currently selected (14 bit) NRPN number, a negative
             *          value if no NRPN parameter currently selected
             */
            int GetMidiNrpnParameter();

             /**
             * Registers the specified listener to be notified when the number
             * of effect sends on this channel is changed.
             */
            void AddFxSendCountListener(FxSendCountListener* l);

            /**
             * Removes the specified listener.
             */
            void RemoveFxSendCountListener(FxSendCountListener* l);

            /**
             * Removes all listeners.
             */
            void RemoveAllFxSendCountListeners();

            /**
             * Gets the current number of active voices.
             */
            uint GetVoiceCount();

            /**
             * Sets the current number of active voices.
             */
            void SetVoiceCount(uint Voices);

            /**
             * Gets the current number of active disk streams.
             */
            uint GetDiskStreamCount();

            /**
             * Sets the current number of active disk streams.
             */
            void SetDiskStreamCount(uint Streams);

            SamplerChannel* GetSamplerChannel();

            void SetSamplerChannel(SamplerChannel* pChannel);

            /** Returns the sampler to which this channel belongs */
            Sampler* GetSampler();

            /**
             * Performs a program change on the channel.
             *
             * This method is not real-time safe.
             */
            void ExecuteProgramChange(uint32_t Program);


            // Deprecated APIs
            // (these public methods might be removed in future) ...

            /**
             * Set MIDI Registered Parameter Number (RPN) Controller
             * (upper 8 bits / coarse).
             *
             * @deprecated Use SetMidiRpnParameterMsb() instead.
             */
            void SetMidiRpnControllerMsb(uint8_t CtrlMSB) DEPRECATED_API;

            /**
             * Set MIDI Registered Parameter Number (RPN) Controller
             * (lower 8 bits / fine).
             *
             * @deprecated Use SetMidiRpnParameterLsb() instead.
             */
            void SetMidiRpnControllerLsb(uint8_t CtrlLSB) DEPRECATED_API;

            /**
             * Reset to no RPN controller currently selected.
             *
             * @deprecated Use ResetMidiRpnParameter() instead.
             */
            void ResetMidiRpnController() DEPRECATED_API;

            /**
             * Set MIDI Non-Registered Parameter Number (NRPN) Controller
             * (upper 8 bits / coarse).
             *
             * @deprecated Use SetMidiNrpnParameterMsb() instead.
             */
            void SetMidiNrpnControllerMsb(uint8_t CtrlMSB) DEPRECATED_API;

            /**
             * Set MIDI Non-Registered Parameter Number (NRPN) Controller
             * (lower 8 bits / fine).
             *
             * @deprecated Use SetMidiNrpnParameterLsb() instead.
             */
            void SetMidiNrpnControllerLsb(uint8_t CtrlLSB) DEPRECATED_API;

            /**
             * Reset to no NRPN controller currently selected.
             *
             * @deprecated Use ResetMidiNrpnParameter() instead.
             */
            void ResetMidiNrpnController() DEPRECATED_API;

            /**
             * Get currently selected MIDI Registered Parameter Number
             * (RPN) Controller, this method will return the already merged
             * value (MSB and LSB value).
             *
             * @e WARNING: you have to call @c ResetMidiRpnController()
             * after using this value, otherwise all subsequent MIDI CC #6
             * (Data) messages are interpreted as RPN controller value
             * messages.
             *
             * @returns currently selected RPN controller number, a negative
             *          value if no RPN controller currently selected
             *
             * @deprecated Use GetMidiRpnParameter() instead.
             */
            int GetMidiRpnController() DEPRECATED_API;

            /**
             * Get currently selected MIDI Non-Registered Parameter Number
             * (NRPN) Controller, this method will return the already merged
             * value (MSB and LSB value).
             *
             * @e WARNING: you have to call @c ResetMidiNrpnController()
             * after using this value, otherwise all subsequent MIDI CC #6
             * (Data) messages are interpreted as NRPN controller value
             * messages.
             *
             * @returns currently selected NRPN controller number, a negative
             *          value if no NRPN controller currently selected
             *
             * @deprecated Use GetMidiNrpnParameter() instead.
             */
            int GetMidiNrpnController() DEPRECATED_API;

        protected:
            EngineChannel();
            virtual ~EngineChannel(); // MUST only be destroyed by EngineChannelFactory

            /**
             * Notifies listeners that the number of effect sends
             * on a this channel is changed.
             * @param ChannelId The numerical ID of the sampler channel.
             * @param NewCount The new number of sampler channels.
             */
            void fireFxSendCountChanged(int ChannelId, int NewCount);

            friend class EngineChannelFactory;

        private:
            struct private_data_t;
            private_data_t* const p;
    };

} // namespace LinuxSampler

#endif // __LS_ENGINECHANNEL_H__
1	/***************************************************************************
2	* *
3	* Copyright (C) 2005 - 2020 Christian Schoenebeck *
4	* *
5	* This program 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 program 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 program; 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_ENGINECHANNEL_H__
22	#define __LS_ENGINECHANNEL_H__
23
24	#include "../EventListeners.h"
25	#include "../drivers/audio/AudioOutputDevice.h"
26	#include "../drivers/midi/midi.h"
27	#include "../drivers/midi/MidiInputDevice.h"
28	#include "../drivers/midi/MidiInputPort.h"
29	#include "../drivers/midi/VirtualMidiDevice.h"
30	#include "Engine.h"
31	#include "FxSend.h"
32
33	namespace LinuxSampler {
34
35	// just symbol prototyping
36	class Sampler;
37	class SamplerChannel;
38	class AudioOutputDevice;
39	class MidiInputPort;
40	class FxSend;
41
42
43	/** @brief Channel Interface for LinuxSampler Sampler Engines
44	*
45	* Every sampler engine can be used on several sampler channels and
46	* usually the same Engine instance is used on multiple sampler
47	* channels. For this every sampler engine must also implement a class
48	* which handles all channel dependant parameters and channel
49	* dependant execution code.
50	*
51	* This abstract base interface class defines all mandatory methods
52	* which have to be implemented by all engine channel implementations.
53	*/
54	class EngineChannel {
55	public:
56
57	/////////////////////////////////////////////////////////////////
58	// abstract methods
59	// (these have to be implemented by the descendant)
60
61	// general sampler part management
62	virtual void Reset() = 0;
63	virtual void SendNoteOn(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel) = 0;
64	virtual void SendNoteOn(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel, int32_t FragmentPos) = 0;
65	virtual void SendNoteOff(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel) = 0;
66	virtual void SendNoteOff(uint8_t Key, uint8_t Velocity, uint8_t MidiChannel, int32_t FragmentPos) = 0;
67	virtual void SendPitchbend(int Pitch, uint8_t MidiChannel) = 0;
68	virtual void SendPitchbend(int Pitch, uint8_t MidiChannel, int32_t FragmentPos) = 0;
69	virtual void SendControlChange(uint8_t Controller, uint8_t Value, uint8_t MidiChannel) = 0;
70	virtual void SendControlChange(uint8_t Controller, uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
71	virtual void SendProgramChange(uint8_t Program) = 0;
72	virtual void SendChannelPressure(uint8_t Value, uint8_t MidiChannel) = 0;
73	virtual void SendChannelPressure(uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
74	virtual void SendPolyphonicKeyPressure(uint8_t Key, uint8_t Value, uint8_t MidiChannel) = 0;
75	virtual void SendPolyphonicKeyPressure(uint8_t Key, uint8_t Value, uint8_t MidiChannel, int32_t FragmentPos) = 0;
76	virtual bool StatusChanged(bool bNewStatus = false) = 0;
77	virtual float Volume() = 0;
78	virtual void Volume(float f) = 0;
79	virtual float Pan() = 0;
80	virtual void Pan(float f) = 0;
81	virtual uint Channels() = 0;
82
83	// audio driver management
84	virtual void Connect(AudioOutputDevice* pAudioOut) = 0;
85	virtual void DisconnectAudioOutputDevice() = 0;
86	virtual AudioOutputDevice* GetAudioOutputDevice() = 0;
87	virtual void SetOutputChannel(uint EngineAudioChannel, uint AudioDeviceChannel) = 0;
88	virtual int OutputChannel(uint EngineAudioChannel) = 0;
89
90	// MIDI driver management
91	virtual void Connect(MidiInputPort* pMidiPort) = 0;
92	virtual void Disconnect(MidiInputPort* pMidiPort) = 0;
93	virtual void DisconnectAllMidiInputPorts() = 0;
94	virtual uint GetMidiInputPortCount() = 0;
95	virtual MidiInputPort* GetMidiInputPort(uint index) = 0;
96	virtual midi_chan_t MidiChannel() = 0;
97	virtual void SetMidiChannel(midi_chan_t MidiChannel) = 0;
98	// (deprecated MIDI driver management methods)
99	virtual void Connect(MidiInputPort* pMidiPort, midi_chan_t MidiChannel) DEPRECATED_API = 0;
100	virtual void DisconnectMidiInputPort() DEPRECATED_API = 0;
101	virtual MidiInputPort* GetMidiInputPort() DEPRECATED_API = 0;
102
103	// virtual MIDI driver management (i.e. virtual on-screen MIDI keyboards)
104	virtual void Connect(VirtualMidiDevice* pDevice) = 0;
105	virtual void Disconnect(VirtualMidiDevice* pDevice) = 0;
106
107	// instrument (sound file) management
108	virtual void PrepareLoadInstrument(const char* FileName, uint Instrument) = 0;
109	virtual void LoadInstrument() = 0;
110	virtual String InstrumentFileName() = 0; ///< Returns the file name of the currently loaded instrument. Equivalent as calling InstrumentFileName(0).
111	virtual String InstrumentFileName(int index);
112	virtual String InstrumentName() = 0;
113	virtual int InstrumentIndex() = 0;
114	virtual int InstrumentStatus() = 0;
115
116	// sampler format / sampler engine implementation details
117	virtual Engine* GetEngine() = 0;
118	virtual String EngineName() = 0;
119
120	// effect routing
121	virtual FxSend* AddFxSend(uint8_t MidiCtrl, String Name = "") throw (Exception) = 0;
122	virtual FxSend* GetFxSend(uint FxSendIndex) = 0;
123	virtual uint GetFxSendCount() = 0;
124	virtual void RemoveFxSend(FxSend* pFxSend) = 0;
125
126
127	/////////////////////////////////////////////////////////////////
128	// normal methods
129	// (usually not to be overridden by descendant)
130
131	/**
132	* Sets the mute state of this channel.
133	*
134	* @param state - specifies the mute state of this sampler channel.
135	* @throws Exception - if state does not contain valid
136	* value.
137	*/
138	void SetMute(int state) throw (Exception);
139
140	/**
141	* Determines whether this channel is muted.
142	*
143	* @returns 1 if the channel is muted, 0 if the channel is not muted
144	* and -1 if the channel is muted because of presence of at least
145	* one solo channel.
146	*/
147	int GetMute();
148
149	/**
150	* Sets the solo state of this channel.
151	*
152	* @param solo - specifies whether this is a solo channel.
153	*/
154	void SetSolo(bool solo);
155
156	/**
157	* Determines whether this is a solo channel.
158	*
159	* @returns true if this is a solo channel, false otherwise.
160	*/
161	bool GetSolo();
162
163	/**
164	* Returns current MIDI program (change) number of this
165	* EngineChannel.
166	*/
167	uint8_t GetMidiProgram();
168
169	/**
170	* Change EngineChannel's MIDI program.
171	*/
172	void SetMidiProgram(uint8_t Program);
173
174	/**
175	* Returns current MIDI bank MSB (coarse) number of this
176	* EngineChannel.
177	*/
178	uint8_t GetMidiBankMsb();
179
180	/**
181	* Change current MIDI bank MSB (coarse) number of this
182	* EngineChannel.
183	*/
184	void SetMidiBankMsb(uint8_t BankMSB);
185
186	/**
187	* Returns current MIDI bank LSB (fine) number of this
188	* EngineChannel.
189	*/
190	uint8_t GetMidiBankLsb();
191
192	/**
193	* Change current MIDI bank LSB (fine) number of this
194	* EngineChannel.
195	*/
196	void SetMidiBankLsb(uint8_t BankLSB);
197
198	/**
199	* Returns true if this EngineChannel is using no MIDI
200	* instrument map at all, that is if it will ignore all MIDI
201	* program change messages.
202	*
203	* @see UsesDefaultMidiInstrumentMap()
204	* @see GetMidiInstrumentMap()
205	*/
206	bool UsesNoMidiInstrumentMap();
207
208	/**
209	* Returns true if this EngineChannel is using the default MIDI
210	* instrument map for handling MIDI program changes.
211	*
212	* @see UsesNoMidiInstrumentMap()
213	* @see GetMidiInstrumentMap()
214	*/
215	bool UsesDefaultMidiInstrumentMap();
216
217	/**
218	* Returns ID of the MIDI instrument map currently used by this
219	* EngineChannel to handle MIDI program changes. You should
220	* always call @c UsesNoMidiInstrumentMap() and
221	* @c UsesDefaultMidiInstrumentMap() before calling this method
222	* to check if this EngineChannel is probably using the default
223	* map or no map at all, because in these two particular cases
224	* this method would throw an exception!
225	*
226	* @throws Exception - if EngineChannel is set to no map at all
227	* or is set to the default map
228	* @see UsesNoMidiInstrumentMap()
229	* @see UsesDefaultMidiInstrumentMap()
230	*/
231	int GetMidiInstrumentMap() throw (Exception);
232
233	/**
234	* Let this EngineChannel use no MIDI instrument map at all,
235	* that is to let it ignore all MIDI program change messages.
236	*
237	* @see SetMidiInstrumentMapToDefault()
238	* @see SetMidiInstrumentMap()
239	*/
240	void SetMidiInstrumentMapToNone();
241
242	/**
243	* Let this EngineChannel use the default MIDI instrument map to
244	* handle MIDI program changes.
245	*
246	* @see SetMidiInstrumentMapToNone()
247	* @see SetMidiInstrumentMap()
248	*/
249	void SetMidiInstrumentMapToDefault();
250
251	/**
252	* Set a specific MIDI instrument map this EngineChannel should
253	* use to handle MIDI program changes.
254	*
255	* @see SetMidiInstrumentMapToNone()
256	* @see SetMidiInstrumentMapToDefault()
257	*
258	* @throws Exception - in case given map does not exist
259	*/
260	void SetMidiInstrumentMap(int MidiMap) throw (Exception);
261
262	/**
263	* Set MIDI Registered Parameter Number (RPN)
264	* (upper 7 bits / coarse).
265	*/
266	void SetMidiRpnParameterMsb(uint8_t ParamMSB);
267
268	/**
269	* Set MIDI Registered Parameter Number (RPN)
270	* (lower 7 bits / fine).
271	*/
272	void SetMidiRpnParameterLsb(uint8_t ParamLSB);
273
274	/**
275	* Reset to no RPN parameter currently selected.
276	*/
277	void ResetMidiRpnParameter();
278
279	/**
280	* Set MIDI Non-Registered Parameter Number (NRPN)
281	* (upper 7 bits / coarse).
282	*/
283	void SetMidiNrpnParameterMsb(uint8_t ParamMSB);
284
285	/**
286	* Set MIDI Non-Registered Parameter Number (NRPN)
287	* (lower 7 bits / fine).
288	*/
289	void SetMidiNrpnParameterLsb(uint8_t ParamLSB);
290
291	/**
292	* Reset to no NRPN parameter currently selected.
293	*/
294	void ResetMidiNrpnParameter();
295
296	/**
297	* Get currently selected MIDI Registered Parameter Number
298	* (RPN), this method will return the already merged 14 bit
299	* parameter number (MSB and LSB value combined).
300	*
301	* @e WARNING: you have to call @c ResetMidiRpnParameter()
302	* after using this value, otherwise all subsequent MIDI CC #6
303	* (Data) messages are interpreted as RPN value messages.
304	*
305	* @returns currently selected (14 bit) RPN number, a negative
306	* value if no RPN parameter currently selected
307	*/
308	int GetMidiRpnParameter();
309
310	/**
311	* Get currently selected MIDI Non-Registered Parameter Number
312	* (NRPN), this method will return the already merged 14 bit
313	* value (MSB and LSB value combined).
314	*
315	* @e WARNING: you have to call @c ResetMidiNrpnParameter()
316	* after using this value, otherwise all subsequent MIDI CC #6
317	* (Data) messages are interpreted as NRPN value messages.
318	*
319	* @returns currently selected (14 bit) NRPN number, a negative
320	* value if no NRPN parameter currently selected
321	*/
322	int GetMidiNrpnParameter();
323
324	/**
325	* Registers the specified listener to be notified when the number
326	* of effect sends on this channel is changed.
327	*/
328	void AddFxSendCountListener(FxSendCountListener* l);
329
330	/**
331	* Removes the specified listener.
332	*/
333	void RemoveFxSendCountListener(FxSendCountListener* l);
334
335	/**
336	* Removes all listeners.
337	*/
338	void RemoveAllFxSendCountListeners();
339
340	/**
341	* Gets the current number of active voices.
342	*/
343	uint GetVoiceCount();
344
345	/**
346	* Sets the current number of active voices.
347	*/
348	void SetVoiceCount(uint Voices);
349
350	/**
351	* Gets the current number of active disk streams.
352	*/
353	uint GetDiskStreamCount();
354
355	/**
356	* Sets the current number of active disk streams.
357	*/
358	void SetDiskStreamCount(uint Streams);
359
360	SamplerChannel* GetSamplerChannel();
361
362	void SetSamplerChannel(SamplerChannel* pChannel);
363
364	/** Returns the sampler to which this channel belongs */
365	Sampler* GetSampler();
366
367	/**
368	* Performs a program change on the channel.
369	*
370	* This method is not real-time safe.
371	*/
372	void ExecuteProgramChange(uint32_t Program);
373
374
375	// Deprecated APIs
376	// (these public methods might be removed in future) ...
377
378	/**
379	* Set MIDI Registered Parameter Number (RPN) Controller
380	* (upper 8 bits / coarse).
381	*
382	* @deprecated Use SetMidiRpnParameterMsb() instead.
383	*/
384	void SetMidiRpnControllerMsb(uint8_t CtrlMSB) DEPRECATED_API;
385
386	/**
387	* Set MIDI Registered Parameter Number (RPN) Controller
388	* (lower 8 bits / fine).
389	*
390	* @deprecated Use SetMidiRpnParameterLsb() instead.
391	*/
392	void SetMidiRpnControllerLsb(uint8_t CtrlLSB) DEPRECATED_API;
393
394	/**
395	* Reset to no RPN controller currently selected.
396	*
397	* @deprecated Use ResetMidiRpnParameter() instead.
398	*/
399	void ResetMidiRpnController() DEPRECATED_API;
400
401	/**
402	* Set MIDI Non-Registered Parameter Number (NRPN) Controller
403	* (upper 8 bits / coarse).
404	*
405	* @deprecated Use SetMidiNrpnParameterMsb() instead.
406	*/
407	void SetMidiNrpnControllerMsb(uint8_t CtrlMSB) DEPRECATED_API;
408
409	/**
410	* Set MIDI Non-Registered Parameter Number (NRPN) Controller
411	* (lower 8 bits / fine).
412	*
413	* @deprecated Use SetMidiNrpnParameterLsb() instead.
414	*/
415	void SetMidiNrpnControllerLsb(uint8_t CtrlLSB) DEPRECATED_API;
416
417	/**
418	* Reset to no NRPN controller currently selected.
419	*
420	* @deprecated Use ResetMidiNrpnParameter() instead.
421	*/
422	void ResetMidiNrpnController() DEPRECATED_API;
423
424	/**
425	* Get currently selected MIDI Registered Parameter Number
426	* (RPN) Controller, this method will return the already merged
427	* value (MSB and LSB value).
428	*
429	* @e WARNING: you have to call @c ResetMidiRpnController()
430	* after using this value, otherwise all subsequent MIDI CC #6
431	* (Data) messages are interpreted as RPN controller value
432	* messages.
433	*
434	* @returns currently selected RPN controller number, a negative
435	* value if no RPN controller currently selected
436	*
437	* @deprecated Use GetMidiRpnParameter() instead.
438	*/
439	int GetMidiRpnController() DEPRECATED_API;
440
441	/**
442	* Get currently selected MIDI Non-Registered Parameter Number
443	* (NRPN) Controller, this method will return the already merged
444	* value (MSB and LSB value).
445	*
446	* @e WARNING: you have to call @c ResetMidiNrpnController()
447	* after using this value, otherwise all subsequent MIDI CC #6
448	* (Data) messages are interpreted as NRPN controller value
449	* messages.
450	*
451	* @returns currently selected NRPN controller number, a negative
452	* value if no NRPN controller currently selected
453	*
454	* @deprecated Use GetMidiNrpnParameter() instead.
455	*/
456	int GetMidiNrpnController() DEPRECATED_API;
457
458	protected:
459	EngineChannel();
460	virtual ~EngineChannel(); // MUST only be destroyed by EngineChannelFactory
461
462	/**
463	* Notifies listeners that the number of effect sends
464	* on a this channel is changed.
465	* @param ChannelId The numerical ID of the sampler channel.
466	* @param NewCount The new number of sampler channels.
467	*/
468	void fireFxSendCountChanged(int ChannelId, int NewCount);
469
470	friend class EngineChannelFactory;
471
472	private:
473	struct private_data_t;
474	private_data_t* const p;
475	};
476
477	} // namespace LinuxSampler
478
479	#endif // __LS_ENGINECHANNEL_H__