1 /*
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      *
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      */
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
124