voice_modulation_sources.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/audio/instrument_envelope.hpp>
#include <pulp/audio/voice_modulation_buffer.hpp>
#include <pulp/signal/lfo.hpp>
 
#include <array>
#include <cmath>
#include <cstdint>
#include <span>
#include <vector>
 
namespace pulp::audio {

enum class VoiceLfoPhasePolicy : std::uint8_t {
    FreeRunning,
    Retrigger,
};
 
struct VoiceLfoSourceSpec {
    bool enabled = false;
    pulp::signal::Lfo::Wave wave = pulp::signal::Lfo::Wave::sine;
    VoiceLfoPhasePolicy phase_policy = VoiceLfoPhasePolicy::Retrigger;
    double rate_hz = 5.0;
    float depth = 1.0f;
    bool unison_phase_spread = false;
    std::uint32_t seed = 1;
};
 
struct VoiceEnvelopeSourceSpec {
    bool enabled = false;
    AhdsrEnvelopeConfig envelope{};
};
 
struct VoiceModulationSourcesConfig {
    double sample_rate = 48000.0;
    std::uint32_t max_frames = 0;
    VoiceLfoSourceSpec lfo{};
    VoiceEnvelopeSourceSpec envelope{};
};

template <std::size_t MaximumVoices>
class VoiceModulationSources {
    static_assert(MaximumVoices > 0, "VoiceModulationSources needs at least one voice");
    static_assert(MaximumVoices <= 256, "VoiceModulationSources bounds voice count at 256");
    static constexpr std::uint32_t kMaxFrames = 1u << 20;
 
public:
    VoiceModulationSources() = default;

    bool prepare(const VoiceModulationSourcesConfig& config) noexcept {
        if (!config_valid(config))
            return false;
        try {
            scratch_.resize(config.max_frames);
        } catch (...) {
            return false;
        }
        config_ = config;
        config_.envelope.envelope.sample_rate = config.sample_rate;
        for (std::size_t i = 0; i < MaximumVoices; ++i) {
            auto& lfo = lfos_[i];
            lfo.set_mode(config.lfo.phase_policy == VoiceLfoPhasePolicy::FreeRunning
                             ? pulp::signal::Lfo::Mode::free
                             : pulp::signal::Lfo::Mode::retrig);
            lfo.set_wave(config.lfo.wave);
            lfo.set_rate_hz(config.lfo.rate_hz);
            lfo.set_seed(config.lfo.seed + static_cast<std::uint32_t>(i));
            lfo.set_phase_offset(config.lfo.unison_phase_spread
                                     ? static_cast<double>(i) / static_cast<double>(MaximumVoices)
                                     : 0.0);
            lfo.prepare(config.sample_rate);
            if (config.envelope.enabled && !envelopes_[i].prepare(config_.envelope.envelope))
                return false;
        }
        prepared_ = true;
        return true;
    }

    void release() noexcept {
        scratch_.clear();
        scratch_.shrink_to_fit();
        prepared_ = false;
    }

    void reset() noexcept {
        for (std::size_t i = 0; i < MaximumVoices; ++i) {
            lfos_[i].reset();
            envelopes_[i].reset();
        }
    }
 
    bool prepared() const noexcept { return prepared_; }
    const VoiceModulationSourcesConfig& config() const noexcept { return config_; }

    bool set_lfo_rate_hz(double rate_hz) noexcept {
        if (!prepared() || !std::isfinite(rate_hz) || !(rate_hz > 0.0))
            return false;
        config_.lfo.rate_hz = rate_hz;
        for (auto& lfo : lfos_)
            lfo.set_rate_hz(rate_hz);
        return true;
    }

    bool set_lfo_depth(float depth) noexcept {
        if (!prepared() || !std::isfinite(depth))
            return false;
        config_.lfo.depth = depth;
        return true;
    }

    void set_lfo_wave(pulp::signal::Lfo::Wave wave) noexcept {
        if (!prepared())
            return;
        config_.lfo.wave = wave;
        for (auto& lfo : lfos_)
            lfo.set_wave(wave);
    }

    void note_on(std::size_t voice_index) noexcept {
        if (voice_index >= MaximumVoices)
            return;
        lfos_[voice_index].retrigger();
        envelopes_[voice_index].note_on();
    }

    void note_off(std::size_t voice_index) noexcept {
        if (voice_index >= MaximumVoices)
            return;
        envelopes_[voice_index].note_off();
    }

    VoiceModulationResult append_lfo_lane(std::size_t voice_index,
                                          VoiceModulationBuffer& destination,
                                          VoiceModulationTarget target,
                                          VoiceModulationRate rate,
                                          std::uint32_t frame_count) noexcept {
        if (voice_index >= MaximumVoices)
            return {false, VoiceModulationStatus::InvalidTarget};
        if (!prepared_)
            return {false, VoiceModulationStatus::NotPrepared};
        if (!destination.prepared())
            return {false, VoiceModulationStatus::NotPrepared};
        if (!block_bounds_valid(destination, frame_count))
            return {false, VoiceModulationStatus::InvalidFrameCount};
        if (!config_.lfo.enabled)
            return {false, VoiceModulationStatus::InvalidTarget};
        auto& lfo = lfos_[voice_index];
        const float depth = config_.lfo.depth;
        if (rate == VoiceModulationRate::AudioRate) {
            auto reservation = destination.reserve_audio_rate(target);
            if (!reservation.ok)
                return {false, reservation.status};
            for (std::uint32_t frame = 0; frame < frame_count; ++frame)
                reservation.values[frame] = depth * lfo.next();
            return {true, VoiceModulationStatus::Ok};
        }
        for (std::uint32_t frame = 0; frame < frame_count; ++frame)
            scratch_[frame] = depth * lfo.next();
        return destination.add_constant(target, scratch_[0]);
    }

    VoiceModulationResult append_envelope_lane(std::size_t voice_index,
                                               VoiceModulationBuffer& destination,
                                               VoiceModulationTarget target,
                                               VoiceModulationRate rate,
                                               std::uint32_t frame_count) noexcept {
        if (voice_index >= MaximumVoices)
            return {false, VoiceModulationStatus::InvalidTarget};
        if (!prepared_)
            return {false, VoiceModulationStatus::NotPrepared};
        if (!destination.prepared())
            return {false, VoiceModulationStatus::NotPrepared};
        if (!block_bounds_valid(destination, frame_count))
            return {false, VoiceModulationStatus::InvalidFrameCount};
        if (!config_.envelope.enabled)
            return {false, VoiceModulationStatus::InvalidTarget};
        auto& envelope = envelopes_[voice_index];
        if (rate == VoiceModulationRate::AudioRate) {
            auto reservation = destination.reserve_audio_rate(target);
            if (!reservation.ok)
                return {false, reservation.status};
            envelope.render(std::span<float>(reservation.values, frame_count));
            return {true, VoiceModulationStatus::Ok};
        }
        envelope.render(std::span<float>(scratch_.data(), frame_count));
        return destination.add_constant(target, scratch_[0]);
    }

    VoiceModulationResult write_voice(std::size_t voice_index,
                                      VoiceModulationBuffer& destination,
                                      VoiceModulationTarget lfo_target,
                                      VoiceModulationTarget envelope_target,
                                      VoiceModulationRate rate,
                                      std::uint32_t frame_count) noexcept {
        if (voice_index >= MaximumVoices)
            return {false, VoiceModulationStatus::InvalidTarget};
        if (!prepared_)
            return {false, VoiceModulationStatus::NotPrepared};
        if (!destination.prepared())
            return {false, VoiceModulationStatus::NotPrepared};
        if (!block_bounds_valid(destination, frame_count))
            return {false, VoiceModulationStatus::InvalidFrameCount};
        if (!config_.lfo.enabled || !config_.envelope.enabled)
            return {false, VoiceModulationStatus::InvalidTarget};
        if (lfo_target == envelope_target)
            return {false, VoiceModulationStatus::DuplicateTarget};
        if (destination.max_lanes() < 2)
            return {false, VoiceModulationStatus::LaneOverflow};
        auto result = destination.begin_block(frame_count);
        if (!result.ok)
            return result;
        result = append_lfo_lane(voice_index, destination, lfo_target, rate, frame_count);
        if (!result.ok)
            return result;
        return append_envelope_lane(voice_index, destination, envelope_target, rate, frame_count);
    }
 
private:
    static bool config_valid(const VoiceModulationSourcesConfig& config) noexcept {
        if (!(config.sample_rate > 0.0) || !std::isfinite(config.sample_rate))
            return false;
        if (config.max_frames == 0 || config.max_frames > kMaxFrames)
            return false;
        if (!std::isfinite(config.lfo.rate_hz) || !(config.lfo.rate_hz > 0.0))
            return false;
        if (!std::isfinite(config.lfo.depth))
            return false;
        return true;
    }
 
    static bool block_bounds_valid(const VoiceModulationBuffer& destination,
                                   std::uint32_t frame_count) noexcept {
        return frame_count != 0 && frame_count <= destination.max_frames();
    }
 
    std::array<pulp::signal::Lfo, MaximumVoices> lfos_;
    std::array<AhdsrEnvelope, MaximumVoices> envelopes_;
    std::vector<float> scratch_;
    VoiceModulationSourcesConfig config_{};
    bool prepared_ = false;
};
 
}  // namespace pulp::audio