src/engines/FxSend.h

/***************************************************************************
 *                                                                         *
 *   LinuxSampler - modular, streaming capable sampler                     *
 *                                                                         *
 *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
 *   Copyright (C) 2005 - 2010 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 (by routing the effect send to dedicated
     * audio output channels of the sampler channel's audio output device) or
     * to sampler internal effect processors (send effects). Each effect send
     * entity can define an arbitrary MIDI controller number which can alter
     * the effect send's send level.
     *
     * Regarding sampler internal effects: See AudioOutputDevice regarding
     * management of send effects, since send 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 send effect chain this FX send is routed to or
             * -1 if FX send is not routed to a send effect.
             */
            int DestinationEffectChain() const;

            /**
             * Index of the send effect of the send effect chain given by
             * DestinationEffectChain(), in case FX send is routed to
             * a send effect or -1 otherwise. This is the effect chain
             * position, not the effect ID!
             */
            int DestinationEffectChainPosition() const;

            /**
             * Route this FX send to the given send effect given by index
             * @a iChainPos of the send effect chain given by @a iChain .
             *
             * If you want to remove the routing of an FX send, currently
             * directed to a send 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 chain or effect chain position
             *                    doesn't exist
             *
             * @see AudioOutputDevice::SendEffectChain()
             */
            void SetDestinationEffect(int iChain, int iChainPos) throw (Exception);

            /**
             * @deprecated This method will be removed, use DestinationEffectChain() instead!
             */
            int DestinationMasterEffectChain() const DEPRECATED_API;

            /**
             * @deprecated This method will be removed, use DestinationEffectChainPosition() instead!
             */
            int DestinationMasterEffect() const DEPRECATED_API;

            /**
             * @deprecated This method will be removed, use SetDestinationEffect() instead!
             */
            void SetDestinationMasterEffect(int iChain, int iChainPos) throw (Exception) DEPRECATED_API;

            /**
             * 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. By default all audio
             * channels of an effect send are routed in consecutive same order
             * to its destination. You can use this method to change this
             * default routing. If this effect send is routed to an internel
             * effect, then @a DstChan is the input channel of that destination
             * effect. Otherwise, if this effect send is not routed to an
             * internal effect, then @a DstChan is the output channel of the
             * sampler channel's audio output device.
             *
             * @param SrcChan - the effect send's source channel
             * @param DstChan - the audio output device's destination channel
             *                  or send effect's input 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              iDestinationEffectChain;
            int              iDestinationEffectChainPos;
            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	schoenebeck	1001	/***************************************************************************
2			* *
3			* LinuxSampler - modular, streaming capable sampler *
4			* *
5			* Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck *
6	schoenebeck	2137	* Copyright (C) 2005 - 2010 Christian Schoenebeck *
7	schoenebeck	1001	* *
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	schoenebeck	1722	* send is used to route sampler channel's audio signals to either sampler
42	schoenebeck	2137	* external effect processors (by routing the effect send to dedicated
43			* audio output channels of the sampler channel's audio output device) or
44			* to sampler internal effect processors (send effects). Each effect send
45			* entity can define an arbitrary MIDI controller number which can alter
46			* the effect send's send level.
47	schoenebeck	1001	*
48	schoenebeck	2137	* Regarding sampler internal effects: See AudioOutputDevice regarding
49			* management of send effects, since send effects only live in the context
50			* of exactly @e ONE AudioOutputDevice.
51	schoenebeck	1722	*
52	schoenebeck	1001	* Note: effect sends cannot be routed to a different AudioOutputDevice
53			* than assigned to the FxSend's EngineChannel. Also note that an effect
54			* send always has as much audio channels as its EngineChannel.
55			*/
56			class FxSend {
57			public:
58			/**
59			* Constructor. By default all effect send channels are routed to
60			* the @e last available audio channels on the EngineChannel's
61			* AudioOutputDevice.
62			*
63			* @param pEngineChannel - engine channel on which the effect send
64			* is added to
65			* @param MidiCtrl - MIDI controller number which can alter the
66			* effect send level
67			* @param Name - (optional) name for the effect send entity
68	schoenebeck	1017	*
69	schoenebeck	1026	* @throws Exception - in case no free ID could be found on
70			* given EngineChannel or @a MidiCtrl is
71			* invalid
72	schoenebeck	1001	*/
73	schoenebeck	1017	FxSend(EngineChannel* pEngineChannel, uint8_t MidiCtrl, String Name = "") throw (Exception);
74	schoenebeck	1001
75			/**
76	schoenebeck	2137	* Index of the send effect chain this FX send is routed to or
77			* -1 if FX send is not routed to a send effect.
78	schoenebeck	1722	*/
79	schoenebeck	2137	int DestinationEffectChain() const;
80	schoenebeck	1722
81			/**
82	schoenebeck	2137	* Index of the send effect of the send effect chain given by
83			* DestinationEffectChain(), in case FX send is routed to
84			* a send effect or -1 otherwise. This is the effect chain
85			* position, not the effect ID!
86	schoenebeck	1722	*/
87	schoenebeck	2137	int DestinationEffectChainPosition() const;
88	schoenebeck	1722
89			/**
90	schoenebeck	2137	* Route this FX send to the given send effect given by index
91			* @a iChainPos of the send effect chain given by @a iChain .
92	schoenebeck	1722	*
93			* If you want to remove the routing of an FX send, currently
94	schoenebeck	2137	* directed to a send effect processor, and want to route it
95	schoenebeck	1722	* directly to an audio output device channel instead, then set
96			* both arguments to @c -1 .
97			*
98	schoenebeck	2137	* @throw Exception - if given effect chain or effect chain position
99			* doesn't exist
100			*
101			* @see AudioOutputDevice::SendEffectChain()
102	schoenebeck	1722	*/
103	schoenebeck	2137	void SetDestinationEffect(int iChain, int iChainPos) throw (Exception);
104	schoenebeck	1722
105			/**
106	schoenebeck	2137	* @deprecated This method will be removed, use DestinationEffectChain() instead!
107			*/
108			int DestinationMasterEffectChain() const DEPRECATED_API;
109
110			/**
111			* @deprecated This method will be removed, use DestinationEffectChainPosition() instead!
112			*/
113			int DestinationMasterEffect() const DEPRECATED_API;
114
115			/**
116			* @deprecated This method will be removed, use SetDestinationEffect() instead!
117			*/
118			void SetDestinationMasterEffect(int iChain, int iChainPos) throw (Exception) DEPRECATED_API;
119
120			/**
121	schoenebeck	1001	* Returns the audio output device's audio channel to which effect
122			* send's channel \a SrcChan is currently routed to.
123			*/
124			int DestinationChannel(int SrcChan);
125
126			/**
127	schoenebeck	2137	* Alters the routing of an audio channel. By default all audio
128			* channels of an effect send are routed in consecutive same order
129			* to its destination. You can use this method to change this
130			* default routing. If this effect send is routed to an internel
131			* effect, then @a DstChan is the input channel of that destination
132			* effect. Otherwise, if this effect send is not routed to an
133			* internal effect, then @a DstChan is the output channel of the
134			* sampler channel's audio output device.
135	schoenebeck	1001	*
136			* @param SrcChan - the effect send's source channel
137			* @param DstChan - the audio output device's destination channel
138	schoenebeck	2137	* or send effect's input channel
139	schoenebeck	1001	* @throws Exception - in case arguments out of range
140			*/
141			void SetDestinationChannel(int SrcChan, int DstChan) throw (Exception);
142
143			/**
144			* Should be called by the engine channel whenever the amount of
145			* audio channel has changed, so the FxSend object can adjust the
146			* amount of channels to that new number and establish default
147			* routings for new channels if needed.
148			*/
149			void UpdateChannels();
150
151			/**
152			* The effect send's current send level ( usually a value between
153			* @c 0.0f and @c 1.0f ).
154			*/
155			float Level();
156
157			/**
158			* Alter the effect send's send level ( usually a value between
159			* @c 0.0f and @c 1.0f ).
160			*/
161			void SetLevel(float f);
162
163			/**
164			* Alter the effect send's send level by supplying the MIDI
165			* controller's MIDI value. This method is usually only called
166			* by the engine channel.
167			*/
168			void SetLevel(uint8_t iMidiValue);
169
170			/**
171	schoenebeck	1040	* Reset send level to the default send level (i.e. due to a
172			* MIDI "reset all controllers" message).
173			*/
174			void Reset();
175
176			/**
177	schoenebeck	1001	* Returns the MIDI controller number which can alter the effect
178			* send's send level.
179			*/
180			uint8_t MidiController();
181
182			/**
183			* Alter the MIDI controller number which should alter the effect
184			* send's send level.
185			*
186			* @param MidiCtrl - MIDI controller number
187			* @throws Exception - if MIDI controller number is invalid
188			*/
189			void SetMidiController(uint8_t MidiCtrl) throw (Exception);
190
191			/**
192			* Returns the (optional) name of this effect send entity.
193			*/
194			String Name();
195
196			/**
197	iliev	1135	* Sets the name of this effect send entity.
198			* @param Name The new name of this effect send entity.
199			*/
200			void SetName(String Name);
201
202			/**
203	schoenebeck	1001	* Returns the (at least sampler-channel-) unique ID of the
204			* effect send instance. This is actually not used by the engine
205			* at all. It is at the moment only used by the LSCP server to
206			* associate an unique numerical ID with each effect send entity.
207			*/
208			uint Id();
209
210	iliev	1108	/**
211			* Determines whether the effect send's settings are changed.
212			*/
213			bool IsInfoChanged();
214
215			/**
216			* Sets whether the effect send's settings are changed.
217			*/
218			void SetInfoChanged(bool b);
219
220	schoenebeck	1001	protected:
221			EngineChannel* pEngineChannel;
222	schoenebeck	2137	int iDestinationEffectChain;
223			int iDestinationEffectChainPos;
224	schoenebeck	1001	std::vector<int> Routing;
225			uint8_t MidiFxSendController;
226			String sName;
227			uint iId;
228			float fLevel;
229	iliev	1108	bool bInfoChanged; // Determines whether there are changes to the settings.
230	schoenebeck	1001	};
231
232			} // namespace LinuxSampler
233
234			#endif // LS_FXSEND_H