src/engines/FxSend.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2008 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_FXSEND_H
#define LS_FXSEND_H

#include "../common/global.h"
#include "../drivers/audio/AudioChannel.h"
#include "EngineChannel.h"

#include <vector>

namespace LinuxSampler {

    // just symbol prototyping
    class EngineChannel;

    /** @brief Engine Channel Effect Send
     *
     * This class is used to manage effect sends on Engine Channels. An effect
     * send is used to route sampler channel's audio signals to either sampler
     * external effect processors or to sampler internal effect processors.
     * Each effect send entity can define an arbitrary MIDI controller number
     * which can alter the effect send's send level.
     *
     * Regarding sampler internal effects: only master effects are supported
     * ATM, no insert effects yet. See AudioOutputDevice regarding management
     * of master effects, since master effects only live in the context of
     * exactly @e ONE AudioOutputDevice.
     *
     * Note: effect sends cannot be routed to a different AudioOutputDevice
     * than assigned to the FxSend's EngineChannel. Also note that an effect
     * send always has as much audio channels as its EngineChannel.
     */
    class FxSend {
        public:
            /**
             * Constructor. By default all effect send channels are routed to
             * the @e last available audio channels on the EngineChannel's
             * AudioOutputDevice.
             *
             * @param pEngineChannel - engine channel on which the effect send
             *                         is added to
             * @param MidiCtrl - MIDI controller number which can alter the
             *                   effect send level
             * @param Name - (optional) name for the effect send entity
             *
             * @throws Exception - in case no free ID could be found on
             *                     given EngineChannel or @a MidiCtrl is
             *                     invalid
             */
            FxSend(EngineChannel* pEngineChannel, uint8_t MidiCtrl, String Name = "") throw (Exception);

            /**
             * Index of the master effect chain this FX send is routed to or
             * -1 if FX send is not routed to a master effect.
             */
            int DestinationMasterEffectChain() const;

            /**
             * Index of the master effect of the master effect chain given by
             * DestinationMasterEffectChain(), in case FX send is routed to
             * a master effect or -1 otherwise.
             */
            int DestinationMasterEffect() const;

            /**
             * Route this FX send to the given master effect given by index
             * @a iEffect of the master effect chain given by @a iChain .
             *
             * If you want to remove the routing of an FX send, currently
             * directed to a master effect processor, and want to route it
             * directly to an audio output device channel instead, then set
             * both arguments to @c -1 .
             *
             * @throw Exception - if given effect / effect chain doesn't exist
             * @see AudioOutputDevice::MasterEffectChain()
             */
            void SetDestinationMasterEffect(int iChain, int iEffect) throw (Exception);

            /**
             * Returns the audio output device's audio channel to which effect
             * send's channel \a SrcChan is currently routed to.
             */
            int DestinationChannel(int SrcChan);

            /**
             * Alters the routing of an audio channel.
             *
             * @param SrcChan - the effect send's source channel
             * @param DstChan - the audio output device's destination channel
             * @throws Exception - in case arguments out of range
             */
            void SetDestinationChannel(int SrcChan, int DstChan) throw (Exception);

            /**
             * Should be called by the engine channel whenever the amount of
             * audio channel has changed, so the FxSend object can adjust the
             * amount of channels to that new number and establish default
             * routings for new channels if needed.
             */
            void UpdateChannels();

            /**
             * The effect send's current send level ( usually a value between
             * @c 0.0f and @c 1.0f ).
             */
            float Level();

            /**
             * Alter the effect send's send level ( usually a value between
             * @c 0.0f and @c 1.0f ).
             */
            void SetLevel(float f);

            /**
             * Alter the effect send's send level by supplying the MIDI
             * controller's MIDI value. This method is usually only called
             * by the engine channel.
             */
            void SetLevel(uint8_t iMidiValue);

            /**
             * Reset send level to the default send level (i.e. due to a
             * MIDI "reset all controllers" message).
             */
            void Reset();

            /**
             * Returns the MIDI controller number which can alter the effect
             * send's send level.
             */
            uint8_t MidiController();

            /**
             * Alter the MIDI controller number which should alter the effect
             * send's send level.
             *
             * @param MidiCtrl - MIDI controller number
             * @throws Exception - if MIDI controller number is invalid
             */
            void SetMidiController(uint8_t MidiCtrl) throw (Exception);

            /**
             * Returns the (optional) name of this effect send entity.
             */
            String Name();

            /**
             * Sets the name of this effect send entity.
             * @param Name The new name of this effect send entity.
             */
            void SetName(String Name);

            /**
             * Returns the (at least sampler-channel-) unique ID of the
             * effect send instance. This is actually not used by the engine
             * at all. It is at the moment only used by the LSCP server to
             * associate an unique numerical ID with each effect send entity.
             */
            uint Id();

            /**
             * Determines whether the effect send's settings are changed.
             */
            bool IsInfoChanged();

            /**
             * Sets whether the effect send's settings are changed.
             */
            void SetInfoChanged(bool b);

        protected:
            EngineChannel*   pEngineChannel;
            int              iMasterEffectChain;
            int              iMasterEffect;
            std::vector<int> Routing;
            uint8_t          MidiFxSendController;
            String           sName;
            uint             iId;
            float            fLevel;
            bool             bInfoChanged;  // Determines whether there are changes to the settings.
    };

} // namespace LinuxSampler

#endif // LS_FXSEND_H
1	/***************************************************************************
2	* *
3	* LinuxSampler - modular, streaming capable sampler *
4	* *
5	* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	* Copyright (C) 2005 - 2008 Christian Schoenebeck *
7	* *
8	* This library is free software; you can redistribute it and/or modify *
9	* it under the terms of the GNU General Public License as published by *
10	* the Free Software Foundation; either version 2 of the License, or *
11	* (at your option) any later version. *
12	* *
13	* This library is distributed in the hope that it will be useful, *
14	* but WITHOUT ANY WARRANTY; without even the implied warranty of *
15	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16	* GNU General Public License for more details. *
17	* *
18	* You should have received a copy of the GNU General Public License *
19	* along with this library; if not, write to the Free Software *
20	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
21	* MA 02111-1307 USA *
22	***************************************************************************/
23
24	#ifndef LS_FXSEND_H
25	#define LS_FXSEND_H
26
27	#include "../common/global.h"
28	#include "../drivers/audio/AudioChannel.h"
29	#include "EngineChannel.h"
30
31	#include <vector>
32
33	namespace LinuxSampler {
34
35	// just symbol prototyping
36	class EngineChannel;
37
38	/** @brief Engine Channel Effect Send
39	*
40	* This class is used to manage effect sends on Engine Channels. An effect
41	* send is used to route sampler channel's audio signals to either sampler
42	* external effect processors or to sampler internal effect processors.
43	* Each effect send entity can define an arbitrary MIDI controller number
44	* which can alter the effect send's send level.
45	*
46	* Regarding sampler internal effects: only master effects are supported
47	* ATM, no insert effects yet. See AudioOutputDevice regarding management
48	* of master effects, since master effects only live in the context of
49	* exactly @e ONE AudioOutputDevice.
50	*
51	* Note: effect sends cannot be routed to a different AudioOutputDevice
52	* than assigned to the FxSend's EngineChannel. Also note that an effect
53	* send always has as much audio channels as its EngineChannel.
54	*/
55	class FxSend {
56	public:
57	/**
58	* Constructor. By default all effect send channels are routed to
59	* the @e last available audio channels on the EngineChannel's
60	* AudioOutputDevice.
61	*
62	* @param pEngineChannel - engine channel on which the effect send
63	* is added to
64	* @param MidiCtrl - MIDI controller number which can alter the
65	* effect send level
66	* @param Name - (optional) name for the effect send entity
67	*
68	* @throws Exception - in case no free ID could be found on
69	* given EngineChannel or @a MidiCtrl is
70	* invalid
71	*/
72	FxSend(EngineChannel* pEngineChannel, uint8_t MidiCtrl, String Name = "") throw (Exception);
73
74	/**
75	* Index of the master effect chain this FX send is routed to or
76	* -1 if FX send is not routed to a master effect.
77	*/
78	int DestinationMasterEffectChain() const;
79
80	/**
81	* Index of the master effect of the master effect chain given by
82	* DestinationMasterEffectChain(), in case FX send is routed to
83	* a master effect or -1 otherwise.
84	*/
85	int DestinationMasterEffect() const;
86
87	/**
88	* Route this FX send to the given master effect given by index
89	* @a iEffect of the master effect chain given by @a iChain .
90	*
91	* If you want to remove the routing of an FX send, currently
92	* directed to a master effect processor, and want to route it
93	* directly to an audio output device channel instead, then set
94	* both arguments to @c -1 .
95	*
96	* @throw Exception - if given effect / effect chain doesn't exist
97	* @see AudioOutputDevice::MasterEffectChain()
98	*/
99	void SetDestinationMasterEffect(int iChain, int iEffect) throw (Exception);
100
101	/**
102	* Returns the audio output device's audio channel to which effect
103	* send's channel \a SrcChan is currently routed to.
104	*/
105	int DestinationChannel(int SrcChan);
106
107	/**
108	* Alters the routing of an audio channel.
109	*
110	* @param SrcChan - the effect send's source channel
111	* @param DstChan - the audio output device's destination channel
112	* @throws Exception - in case arguments out of range
113	*/
114	void SetDestinationChannel(int SrcChan, int DstChan) throw (Exception);
115
116	/**
117	* Should be called by the engine channel whenever the amount of
118	* audio channel has changed, so the FxSend object can adjust the
119	* amount of channels to that new number and establish default
120	* routings for new channels if needed.
121	*/
122	void UpdateChannels();
123
124	/**
125	* The effect send's current send level ( usually a value between
126	* @c 0.0f and @c 1.0f ).
127	*/
128	float Level();
129
130	/**
131	* Alter the effect send's send level ( usually a value between
132	* @c 0.0f and @c 1.0f ).
133	*/
134	void SetLevel(float f);
135
136	/**
137	* Alter the effect send's send level by supplying the MIDI
138	* controller's MIDI value. This method is usually only called
139	* by the engine channel.
140	*/
141	void SetLevel(uint8_t iMidiValue);
142
143	/**
144	* Reset send level to the default send level (i.e. due to a
145	* MIDI "reset all controllers" message).
146	*/
147	void Reset();
148
149	/**
150	* Returns the MIDI controller number which can alter the effect
151	* send's send level.
152	*/
153	uint8_t MidiController();
154
155	/**
156	* Alter the MIDI controller number which should alter the effect
157	* send's send level.
158	*
159	* @param MidiCtrl - MIDI controller number
160	* @throws Exception - if MIDI controller number is invalid
161	*/
162	void SetMidiController(uint8_t MidiCtrl) throw (Exception);
163
164	/**
165	* Returns the (optional) name of this effect send entity.
166	*/
167	String Name();
168
169	/**
170	* Sets the name of this effect send entity.
171	* @param Name The new name of this effect send entity.
172	*/
173	void SetName(String Name);
174
175	/**
176	* Returns the (at least sampler-channel-) unique ID of the
177	* effect send instance. This is actually not used by the engine
178	* at all. It is at the moment only used by the LSCP server to
179	* associate an unique numerical ID with each effect send entity.
180	*/
181	uint Id();
182
183	/**
184	* Determines whether the effect send's settings are changed.
185	*/
186	bool IsInfoChanged();
187
188	/**
189	* Sets whether the effect send's settings are changed.
190	*/
191	void SetInfoChanged(bool b);
192
193	protected:
194	EngineChannel* pEngineChannel;
195	int iMasterEffectChain;
196	int iMasterEffect;
197	std::vector<int> Routing;
198	uint8_t MidiFxSendController;
199	String sName;
200	uint iId;
201	float fLevel;
202	bool bInfoChanged; // Determines whether there are changes to the settings.
203	};
204
205	} // namespace LinuxSampler
206
207	#endif // LS_FXSEND_H