src/effects/EffectChain.h

/***************************************************************************
 *                                                                         *
 *   Copyright (C) 2008 - 2010 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_EFFECTCHAIN_H
#define LS_EFFECTCHAIN_H

#include "Effect.h"

namespace LinuxSampler {

// just symbol prototyping
class AudioOutputDevice;

/**
 * Container for a series of effects. The effects are sequentially processed,
 * that is the output of the first effect is passed to the input of the next
 * effect in the chain and so on.
 */
class EffectChain {
public:
    /**
     * Constructor.
     *
     * @param pDevice - audio output context for the effects, providing
     *                  informations like samplerate
     * @param iEffectChainId - (optional) numerical ID of the effect chain,
     *                         intended for master effect chains, unique among
     *                         all master effect chains which share the same
     *                         audio output device
     */
    EffectChain(AudioOutputDevice* pDevice, int iEffectChainId = -1);

    /**
     * Add the given effect to the end of the effect chain.
     */
    void AppendEffect(Effect* pEffect);

    /**
     * Insert the given effect into the position given by @a iChainPos .
     *
     * @throw Exception - if given position is invalid
     */
    void InsertEffect(Effect* pEffect, int iChainPos) throw (Exception);

    /**
     * Remove effect at chain position @a iChainPos from the effect chain.
     *
     * @throws Exception - if given position is invalid
     */
    void RemoveEffect(int iChainPos) throw (Exception);

    /**
     * Sequentially render the whole effects chain. The final signal
     * will be available in the output channels of the last effect in
     * the chain after this call, which then has to be copied to the
     * desired destination (e.g. the AudioOutputDevice's output channels).
     */
    void RenderAudio(uint Samples);

    /**
     * Returns effect at chain position @a iChainPos .
     */
    Effect* GetEffect(int iChainPos) const;

    /**
     * Returns amount of effects this effect chain currently contains.
     */
    int EffectCount() const;

    /**
     * Enable / disable the given effect. Currently, disabled effects are
     * automatically bypassed. We might add explicit "bypass" control in
     * future though.
     *
     * @throw Exception - if chain position is invalid
     */
    void SetEffectActive(int iChainPos, bool bOn) throw (Exception);

    /**
     * Whether the given effect is currently enabled.
     */
    bool IsEffectActive(int iChainPos) const;

    /**
     * Clears the audio input and output channels of all effects in the chain.
     */
    void ClearAllChannels();

    /**
     * Returns numerical ID of this effect chain, intended for master effect
     * chains. The ID is unique among all master effect chains which share the
     * same audio output device.
     *
     * There is no ID for insert effect chains, since a sampler channel
     * always provides exactly one insert effect chain.
     *
     * @returns id equal or larger than zero if master effect chain, negative
     *          number if this is an insert effect chain
     */
    int ID() const;

private:
    struct _ChainEntry {
        Effect* pEffect;
        bool    bActive;
    };

    std::vector<_ChainEntry> vEntries;
    AudioOutputDevice*       pDevice;
    int                      iID;
};

} // namespace LinuxSampler

#endif // LS_EFFECTCHAIN_H
1	schoenebeck	1722	/***************************************************************************
2			* *
3	schoenebeck	2135	* Copyright (C) 2008 - 2010 Christian Schoenebeck *
4	schoenebeck	1722	* *
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_EFFECTCHAIN_H
22			#define LS_EFFECTCHAIN_H
23
24			#include "Effect.h"
25
26			namespace LinuxSampler {
27
28			// just symbol prototyping
29			class AudioOutputDevice;
30
31			/**
32			* Container for a series of effects. The effects are sequentially processed,
33			* that is the output of the first effect is passed to the input of the next
34			* effect in the chain and so on.
35			*/
36			class EffectChain {
37			public:
38			/**
39			* Constructor.
40			*
41			* @param pDevice - audio output context for the effects, providing
42			* informations like samplerate
43	schoenebeck	2135	* @param iEffectChainId - (optional) numerical ID of the effect chain,
44			* intended for master effect chains, unique among
45			* all master effect chains which share the same
46			* audio output device
47	schoenebeck	1722	*/
48	schoenebeck	2135	EffectChain(AudioOutputDevice* pDevice, int iEffectChainId = -1);
49	schoenebeck	1722
50			/**
51			* Add the given effect to the end of the effect chain.
52			*/
53			void AppendEffect(Effect* pEffect);
54
55			/**
56			* Insert the given effect into the position given by @a iChainPos .
57			*
58			* @throw Exception - if given position is invalid
59			*/
60			void InsertEffect(Effect* pEffect, int iChainPos) throw (Exception);
61
62			/**
63			* Remove effect at chain position @a iChainPos from the effect chain.
64			*
65			* @throws Exception - if given position is invalid
66			*/
67			void RemoveEffect(int iChainPos) throw (Exception);
68
69			/**
70			* Sequentially render the whole effects chain. The final signal
71			* will be available in the output channels of the last effect in
72			* the chain after this call, which then has to be copied to the
73			* desired destination (e.g. the AudioOutputDevice's output channels).
74			*/
75			void RenderAudio(uint Samples);
76
77			/**
78			* Returns effect at chain position @a iChainPos .
79			*/
80			Effect* GetEffect(int iChainPos) const;
81
82			/**
83			* Returns amount of effects this effect chain currently contains.
84			*/
85			int EffectCount() const;
86
87			/**
88			* Enable / disable the given effect. Currently, disabled effects are
89			* automatically bypassed. We might add explicit "bypass" control in
90			* future though.
91			*
92			* @throw Exception - if chain position is invalid
93			*/
94			void SetEffectActive(int iChainPos, bool bOn) throw (Exception);
95
96			/**
97			* Whether the given effect is currently enabled.
98			*/
99			bool IsEffectActive(int iChainPos) const;
100
101			/**
102			* Clears the audio input and output channels of all effects in the chain.
103			*/
104			void ClearAllChannels();
105
106	schoenebeck	2135	/**
107			* Returns numerical ID of this effect chain, intended for master effect
108			* chains. The ID is unique among all master effect chains which share the
109			* same audio output device.
110			*
111			* There is no ID for insert effect chains, since a sampler channel
112			* always provides exactly one insert effect chain.
113			*
114			* @returns id equal or larger than zero if master effect chain, negative
115			* number if this is an insert effect chain
116			*/
117			int ID() const;
118
119	schoenebeck	1722	private:
120			struct _ChainEntry {
121			Effect* pEffect;
122			bool bActive;
123			};
124
125			std::vector<_ChainEntry> vEntries;
126			AudioOutputDevice* pDevice;
127	schoenebeck	2135	int iID;
128	schoenebeck	1722	};
129
130			} // namespace LinuxSampler
131
132			#endif // LS_EFFECTCHAIN_H