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