AudioBuffer.h

Go to the documentation of this file.

/*
 * AudioBuffer.h
 *
 * Copyright (c) 2026 Dalton Messmer <messmer.dalton/at/gmail.com>
 *
 * This file is part of LMMS - https://lmms.io
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public
 * License along with this program (see COPYING); if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301 USA.
 *
 */
 
#ifndef LMMS_AUDIO_BUFFER_H
#define LMMS_AUDIO_BUFFER_H
 
#include <bitset>
#include <memory_resource>
 
#include "AudioBufferView.h"
#include "ArrayVector.h"
#include "LmmsTypes.h"
#include "lmms_constants.h"
#include "lmms_export.h"
 
namespace lmms
{

class LMMS_EXPORT AudioBuffer
{
public:
        using ChannelFlags = std::bitset<MaxChannelsPerAudioBuffer>;

        class ChannelGroup
        {
        public:
                ChannelGroup() = default;
                ChannelGroup(float** buffers, ch_cnt_t channels)
                        : m_buffers{buffers}
                        , m_channels{channels}
                {}
 
                auto buffers() const -> const float* const* { return m_buffers; }
                auto buffers() -> float** { return m_buffers; }
 
                auto buffer(ch_cnt_t channel) const -> const float*
                {
                        assert(channel < m_channels);
                        return m_buffers[channel];
                }
 
                auto buffer(ch_cnt_t channel) -> float*
                {
                        assert(channel < m_channels);
                        return m_buffers[channel];
                }
 
                auto channels() const -> ch_cnt_t { return m_channels; }
 
                void setBuffers(float** newBuffers) { m_buffers = newBuffers; }
                void setChannels(ch_cnt_t channels) { m_channels = channels; }
 
                // TODO: Future additions: Group names, type (main/aux), speaker arrangements (for surround sound), ...
 
        private:
                float** m_buffers = nullptr;

                ch_cnt_t m_channels = 0;
        };
 
        AudioBuffer() = delete;
 
        AudioBuffer(const AudioBuffer&) = delete;
        AudioBuffer(AudioBuffer&&) noexcept = default;
        auto operator=(const AudioBuffer&) -> AudioBuffer& = delete;
        auto operator=(AudioBuffer&&) noexcept -> AudioBuffer& = default;

        explicit AudioBuffer(f_cnt_t frames, ch_cnt_t channels = DEFAULT_CHANNELS,
                std::pmr::memory_resource* resource = std::pmr::get_default_resource());

        template<class F>
        AudioBuffer(f_cnt_t frames, ch_cnt_t channels, group_cnt_t groups,
                std::pmr::memory_resource* resource, F&& groupVisitor)
                : AudioBuffer{frames, channels, resource}
        {
                setGroups(groups, std::forward<F>(groupVisitor));
        }

        void allocateInterleavedBuffer();
 
        auto hasInterleavedBuffer() const -> bool { return !m_interleavedBuffer.empty(); }

        static auto allocationSize(f_cnt_t frames, ch_cnt_t channels,
                bool withInterleavedBuffer = false) -> std::size_t;

        auto groupCount() const -> group_cnt_t { return static_cast<group_cnt_t>(m_groups.size()); }
 
        auto group(group_cnt_t index) const -> const ChannelGroup& { return m_groups[index]; }
        auto group(group_cnt_t index) -> ChannelGroup& { return m_groups[index]; }

        auto allBuffers() const -> PlanarBufferView<const float>
        {
                return {m_accessBuffer.data(), totalChannels(), m_frames};
        }

        auto allBuffers() -> PlanarBufferView<float>
        {
                return {m_accessBuffer.data(), totalChannels(), m_frames};
        }

        auto groupBuffers(group_cnt_t index) const -> PlanarBufferView<const float>
        {
                assert(index < groupCount());
                const ChannelGroup& g = m_groups[index];
                return {g.buffers(), g.channels(), m_frames};
        }

        auto groupBuffers(group_cnt_t index) -> PlanarBufferView<float>
        {
                assert(index < groupCount());
                ChannelGroup& g = m_groups[index];
                return {g.buffers(), g.channels(), m_frames};
        }

        auto buffer(ch_cnt_t channel) const -> std::span<const float>
        {
                return {m_accessBuffer[channel], m_frames};
        }

        auto buffer(ch_cnt_t channel) -> std::span<float>
        {
                return {m_accessBuffer[channel], m_frames};
        }

        auto totalChannels() const -> ch_cnt_t { return static_cast<ch_cnt_t>(m_accessBuffer.size()); }

        auto frames() const -> f_cnt_t { return m_frames; }

        auto interleavedBuffer() const -> InterleavedBufferView<const float, 2>
        {
                assert(hasInterleavedBuffer());
                return {m_interleavedBuffer.data(), m_frames};
        }

        auto interleavedBuffer() -> InterleavedBufferView<float, 2>
        {
                assert(hasInterleavedBuffer());
                return {m_interleavedBuffer.data(), m_frames};
        }

        auto addGroup(ch_cnt_t channels) -> ChannelGroup*;

        template<class F>
        void setGroups(group_cnt_t groups, F&& groupVisitor)
        {
                static_assert(std::is_invocable_r_v<ch_cnt_t, F, group_cnt_t, ChannelGroup&>,
                        "groupVisitor is passed the group index + group reference and must return the group's channel count");
 
                m_groups.clear();
                ch_cnt_t ch = 0;
                for (group_cnt_t idx = 0; idx < groups; ++idx)
                {
                        auto& group = m_groups.emplace_back();
 
                        const auto channels = groupVisitor(idx, group);
                        if (channels == 0) { throw std::runtime_error{"group cannot have zero channels"}; }
 
                        group.setBuffers(&m_accessBuffer[ch]);
                        group.setChannels(channels);
 
                        ch += channels;
                        if (ch > this->totalChannels())
                        {
                                throw std::runtime_error{"sum of group channel counts exceeds total channels"};
                        }
                }
        }

        auto silenceFlags() const -> const ChannelFlags& { return m_silenceFlags; }

        void assumeNonSilent(ch_cnt_t channel) { m_silenceFlags[channel] = false; }

        void enableSilenceTracking(bool enabled);
        auto silenceTrackingEnabled() const -> bool { return m_silenceTrackingEnabled; }

        void mixSilenceFlags(const AudioBuffer& other);

        auto hasSignal(const ChannelFlags& channels) const -> bool;

        auto hasAnySignal() const -> bool;

        void sanitize(const ChannelFlags& channels, ch_cnt_t upperBound = MaxChannelsPerAudioBuffer);

        void sanitizeAll();

        auto updateSilenceFlags(const ChannelFlags& channels, ch_cnt_t upperBound = MaxChannelsPerAudioBuffer) -> bool;

        auto updateAllSilenceFlags() -> bool;

        void silenceChannels(const ChannelFlags& channels, ch_cnt_t upperBound = MaxChannelsPerAudioBuffer);

        void silenceAllChannels();

        auto absPeakValue(ch_cnt_t channel) const -> float;
 
private:
        std::pmr::vector<float> m_sourceBuffer;

        std::pmr::vector<float*> m_accessBuffer;

        std::pmr::vector<float> m_interleavedBuffer;

        ArrayVector<ChannelGroup, MaxGroupsPerAudioBuffer> m_groups;

        f_cnt_t m_frames = 0;

        ChannelFlags m_silenceFlags;
 
        bool m_silenceTrackingEnabled = false;
};
 
} // namespace lmms
 
#endif // LMMS_AUDIO_BUFFER_H