src/engines/LFO.h

/*
 * Copyright (c) 2019 Christian Schoenebeck
 *
 * http://www.linuxsampler.org
 *
 * This file is part of LinuxSampler and released under the same terms.
 * See README file for details.
 */

#ifndef LS_LFO_H
#define LS_LFO_H

#include "../common/global.h"
#include "../common/optional.h"

namespace LinuxSampler {

    // *************** types ***************
    // *

    /** @brief Low Frequency Oscillator (public API class)
     *
     * Generalized, convenient cluster class encapsulating all the sampler's
     * Low Frequency Oscillator implementations.
     *
     * @b NOTE: This class is @b NOT used by the sampler at all! This class is
     * solely exported to the sampler's public API to allow third-party apps
     * (e.g. Gigedit) to use our LFO implementations (e.g. for visualizing an
     * LFO's wave form in an instrument editor GUI application) in a convenient
     * way and by an unified API, and exactly with same LFO wave form values
     * that would be generated by the sampler at playback time.
     *
     * @b NOTE: For sampler internal purposes use the template variant class
     * LFOCluster for efficiency reasons instead! See the discussion on
     * LFOCluster for details why.
     */
    class LFO {
    public:
        /**
         * Oscillator's fundamental function type / wave form type.
         */
        enum wave_t {
            wave_sine,
            wave_triangle,
            wave_saw,
            wave_square,
        };

        /**
         * Whether the LFO should have positive AND negative value range
         * (signed) or only a positive value range (unsigned).
         */
        enum range_type_t {
            range_signed,  ///< LFO's level will wave between -max ... +max
            range_unsigned ///< LFO's level will wave between 0 ... +max
        };

        /**
         * Defines the start level of the LFO wave within the given value range.
         */
        enum start_level_t {
            start_level_max, ///< wave starts from given maximum level
            start_level_mid, ///< wave starts from the middle of the given value range
            start_level_min  ///< wave starts from given minimum level
        };

        struct SetupOpt {
            optional<wave_t> waveType; ///< LFO's fundamental function type, that its wave form type, e.g. sine, triangle, saw, etc. (default: sine)
            optional<range_type_t> rangeType;
            optional<float> frequency; ///< frequency of the oscillator in Hz (default: 1 Hz)
            optional<float> phase; ///< optional phase displacement of the LFO function in degrees, between 0��..360�� (default: 0��)
            optional<start_level_t> startLevel; ///< on which initial value level the LFO wave should start (default: start_level_mid)
            optional<uint16_t> internalDepth; ///< firm, internal oscillator's amplitude (0..1200, default: 0)
            optional<uint16_t> midiControllerDepth; ///< defines how strong the external MIDI controller has influence on the oscillator's amplitude (0..1200, default: 0)
            optional<bool> flipPolarity; ///< if true: inverts the oscillator wave vertically (default: false)
            optional<float> samplerate; ///< sample rate to be assumed by the LFO (default: 44100)
            optional<float> maxValue;
        };

        /** @brief Constructs LFO with default values.
         *
         * Initializes the LFO with default values for all LFO parameters
         * (that is for e.g. frequency, sample rate, wave form type, etc.).
         *
         * You should call setup() afterwards to actually initialize the LFO
         * with the desired parameters.
         */
        LFO();

        /** @brief Frees LFO's resources.
         *
         * De-allocates all resources previously been allocated by this LFO
         * object.
         */
        virtual ~LFO();

        /**
         * Setup the LFO with the relevant parameters (e.g. frequency, wave
         * form type, etc.).
         */
        void setup(const SetupOpt& opt);

        /**
         * Calculates exactly one sample point of the LFO wave.
         *
         * @returns next LFO level
         */
        float render();

        /**
         * Update LFO depth with a new external MIDI controller value.
         *
         * @param midiCCValue - new MIDI controller value (0..127)
         */
        void setMIDICtrlValue(uint8_t midiCCValue);

    private:
        struct LFOPriv* SELF;
    };

} // namespace LinuxSampler

#endif // LS_LFO_H
1	schoenebeck	3612	/*
2			* Copyright (c) 2019 Christian Schoenebeck
3			*
4			* http://www.linuxsampler.org
5			*
6			* This file is part of LinuxSampler and released under the same terms.
7			* See README file for details.
8			*/
9
10			#ifndef LS_LFO_H
11			#define LS_LFO_H
12
13			#include "../common/global.h"
14			#include "../common/optional.h"
15
16			namespace LinuxSampler {
17
18			// ************* types *************
19			// *
20
21			/** @brief Low Frequency Oscillator (public API class)
22			*
23			* Generalized, convenient cluster class encapsulating all the sampler's
24			* Low Frequency Oscillator implementations.
25			*
26			* @b NOTE: This class is @b NOT used by the sampler at all! This class is
27			* solely exported to the sampler's public API to allow third-party apps
28			* (e.g. Gigedit) to use our LFO implementations (e.g. for visualizing an
29			* LFO's wave form in an instrument editor GUI application) in a convenient
30			* way and by an unified API, and exactly with same LFO wave form values
31			* that would be generated by the sampler at playback time.
32	schoenebeck	3625	*
33			* @b NOTE: For sampler internal purposes use the template variant class
34			* LFOCluster for efficiency reasons instead! See the discussion on
35			* LFOCluster for details why.
36	schoenebeck	3612	*/
37			class LFO {
38			public:
39			/**
40			* Oscillator's fundamental function type / wave form type.
41			*/
42			enum wave_t {
43			wave_sine,
44			wave_triangle,
45			wave_saw,
46			wave_square,
47			};
48
49			/**
50			* Whether the LFO should have positive AND negative value range
51			* (signed) or only a positive value range (unsigned).
52			*/
53			enum range_type_t {
54			range_signed, ///< LFO's level will wave between -max ... +max
55			range_unsigned ///< LFO's level will wave between 0 ... +max
56			};
57
58			/**
59			* Defines the start level of the LFO wave within the given value range.
60			*/
61			enum start_level_t {
62			start_level_max, ///< wave starts from given maximum level
63			start_level_mid, ///< wave starts from the middle of the given value range
64			start_level_min ///< wave starts from given minimum level
65			};
66
67			struct SetupOpt {
68			optional<wave_t> waveType; ///< LFO's fundamental function type, that its wave form type, e.g. sine, triangle, saw, etc. (default: sine)
69			optional<range_type_t> rangeType;
70			optional<float> frequency; ///< frequency of the oscillator in Hz (default: 1 Hz)
71			optional<float> phase; ///< optional phase displacement of the LFO function in degrees, between 0��..360�� (default: 0��)
72			optional<start_level_t> startLevel; ///< on which initial value level the LFO wave should start (default: start_level_mid)
73			optional<uint16_t> internalDepth; ///< firm, internal oscillator's amplitude (0..1200, default: 0)
74			optional<uint16_t> midiControllerDepth; ///< defines how strong the external MIDI controller has influence on the oscillator's amplitude (0..1200, default: 0)
75			optional<bool> flipPolarity; ///< if true: inverts the oscillator wave vertically (default: false)
76			optional<float> samplerate; ///< sample rate to be assumed by the LFO (default: 44100)
77			optional<float> maxValue;
78			};
79
80			/** @brief Constructs LFO with default values.
81			*
82			* Initializes the LFO with default values for all LFO parameters
83			* (that is for e.g. frequency, sample rate, wave form type, etc.).
84			*
85			* You should call setup() afterwards to actually initialize the LFO
86			* with the desired parameters.
87			*/
88			LFO();
89
90			/** @brief Frees LFO's resources.
91			*
92			* De-allocates all resources previously been allocated by this LFO
93			* object.
94			*/
95			virtual ~LFO();
96
97			/**
98			* Setup the LFO with the relevant parameters (e.g. frequency, wave
99			* form type, etc.).
100			*/
101			void setup(const SetupOpt& opt);
102
103			/**
104			* Calculates exactly one sample point of the LFO wave.
105			*
106			* @returns next LFO level
107			*/
108			float render();
109
110			/**
111			* Update LFO depth with a new external MIDI controller value.
112			*
113			* @param midiCCValue - new MIDI controller value (0..127)
114			*/
115			void setMIDICtrlValue(uint8_t midiCCValue);
116
117			private:
118			struct LFOPriv* SELF;
119			};
120
121			} // namespace LinuxSampler
122
123			#endif // LS_LFO_H