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.
     */
    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			*/
33			class LFO {
34			public:
35			/**
36			* Oscillator's fundamental function type / wave form type.
37			*/
38			enum wave_t {
39			wave_sine,
40			wave_triangle,
41			wave_saw,
42			wave_square,
43			};
44
45			/**
46			* Whether the LFO should have positive AND negative value range
47			* (signed) or only a positive value range (unsigned).
48			*/
49			enum range_type_t {
50			range_signed, ///< LFO's level will wave between -max ... +max
51			range_unsigned ///< LFO's level will wave between 0 ... +max
52			};
53
54			/**
55			* Defines the start level of the LFO wave within the given value range.
56			*/
57			enum start_level_t {
58			start_level_max, ///< wave starts from given maximum level
59			start_level_mid, ///< wave starts from the middle of the given value range
60			start_level_min ///< wave starts from given minimum level
61			};
62
63			struct SetupOpt {
64			optional<wave_t> waveType; ///< LFO's fundamental function type, that its wave form type, e.g. sine, triangle, saw, etc. (default: sine)
65			optional<range_type_t> rangeType;
66			optional<float> frequency; ///< frequency of the oscillator in Hz (default: 1 Hz)
67			optional<float> phase; ///< optional phase displacement of the LFO function in degrees, between 0��..360�� (default: 0��)
68			optional<start_level_t> startLevel; ///< on which initial value level the LFO wave should start (default: start_level_mid)
69			optional<uint16_t> internalDepth; ///< firm, internal oscillator's amplitude (0..1200, default: 0)
70			optional<uint16_t> midiControllerDepth; ///< defines how strong the external MIDI controller has influence on the oscillator's amplitude (0..1200, default: 0)
71			optional<bool> flipPolarity; ///< if true: inverts the oscillator wave vertically (default: false)
72			optional<float> samplerate; ///< sample rate to be assumed by the LFO (default: 44100)
73			optional<float> maxValue;
74			};
75
76			/** @brief Constructs LFO with default values.
77			*
78			* Initializes the LFO with default values for all LFO parameters
79			* (that is for e.g. frequency, sample rate, wave form type, etc.).
80			*
81			* You should call setup() afterwards to actually initialize the LFO
82			* with the desired parameters.
83			*/
84			LFO();
85
86			/** @brief Frees LFO's resources.
87			*
88			* De-allocates all resources previously been allocated by this LFO
89			* object.
90			*/
91			virtual ~LFO();
92
93			/**
94			* Setup the LFO with the relevant parameters (e.g. frequency, wave
95			* form type, etc.).
96			*/
97			void setup(const SetupOpt& opt);
98
99			/**
100			* Calculates exactly one sample point of the LFO wave.
101			*
102			* @returns next LFO level
103			*/
104			float render();
105
106			/**
107			* Update LFO depth with a new external MIDI controller value.
108			*
109			* @param midiCCValue - new MIDI controller value (0..127)
110			*/
111			void setMIDICtrlValue(uint8_t midiCCValue);
112
113			private:
114			struct LFOPriv* SELF;
115			};
116
117			} // namespace LinuxSampler
118
119			#endif // LS_LFO_H