AudioRingBuffer.h

//
//  AudioRingBuffer.h
//  libraries/audio/src
//
//  Created by Stephen Birarda on 2/1/13.
//  Copyright 2013 High Fidelity, Inc.
//
//  Distributed under the Apache License, Version 2.0.
//  See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
//
 
#ifndef hifi_AudioRingBuffer_h
#define hifi_AudioRingBuffer_h
 
#include "AudioConstants.h"
 
#include <QtCore/QIODevice>
 
#include <SharedUtil.h>
#include <NodeData.h>
 
const int DEFAULT_RING_BUFFER_FRAME_CAPACITY = 10;
 
template <class T>
class AudioRingBufferTemplate {
    using Sample = T;
    static const int SampleSize = sizeof(Sample);
 
public:
    AudioRingBufferTemplate(int numFrameSamples, int numFramesCapacity = DEFAULT_RING_BUFFER_FRAME_CAPACITY);
    ~AudioRingBufferTemplate();
 
    // disallow copying
    AudioRingBufferTemplate(const AudioRingBufferTemplate&) = delete;
    AudioRingBufferTemplate(AudioRingBufferTemplate&&) = delete;
    AudioRingBufferTemplate& operator=(const AudioRingBufferTemplate&) = delete;
 
    void clear();
 
    void reset();
 
    // FIXME: discards any data in the buffer
    void resizeForFrameSize(int numFrameSamples);
 
    // Reading and writing to the buffer uses minimal shared data, such that
    // in cases that avoid overwriting the buffer, a single producer/consumer
    // may use this as a lock-free pipe (see audio-client/src/AudioClient.cpp).
    // IMPORTANT: Avoid changes to the implementation that touch shared data unless you can
    // maintain this behavior.
 
    int readSamples(Sample* destination, int maxSamples);
 
    int appendSamples(Sample* destination, int maxSamples, bool append = true);
 
    void skipSamples(int maxSamples) { shiftReadPosition(std::min(maxSamples, samplesAvailable())); }
 
    int writeSamples(const Sample* source, int maxSamples);
 
    int addSilentSamples(int maxSamples);
 
    int readData(char* destination, int maxSize);
 
    int appendData(char* destination, int maxSize);
 
    int writeData(const char* source, int maxSize);
 
    Sample& operator[](const int index) { return *shiftedPositionAccomodatingWrap(_nextOutput, index); }
    const Sample& operator[] (const int index) const { return *shiftedPositionAccomodatingWrap(_nextOutput, index); }
 
    void shiftReadPosition(unsigned int numSamples) { _nextOutput = shiftedPositionAccomodatingWrap(_nextOutput, numSamples); }
 
    int samplesAvailable() const;
    int framesAvailable() const { return (_numFrameSamples == 0) ? 0 : samplesAvailable() / _numFrameSamples; }
    float getNextOutputFrameLoudness() const { return getFrameLoudness(_nextOutput); }
 
 
    int getNumFrameSamples() const { return _numFrameSamples; }
    int getFrameCapacity() const { return _frameCapacity; }
    int getSampleCapacity() const { return _sampleCapacity; }
    int getOverflowCount() const { return _overflowCount; }
 
    class ConstIterator {
    public:
        ConstIterator() :
            _bufferLength(0),
            _bufferFirst(NULL),
            _bufferLast(NULL),
            _at(NULL) {}
        ConstIterator(Sample* bufferFirst, int capacity, Sample* at) :
            _bufferLength(capacity),
            _bufferFirst(bufferFirst),
            _bufferLast(bufferFirst + capacity - 1),
            _at(at) {}
        ConstIterator(const ConstIterator& rhs) = default;
 
        bool isNull() const { return _at == NULL; }
 
        bool operator==(const ConstIterator& rhs) { return _at == rhs._at; }
        bool operator!=(const ConstIterator& rhs) { return _at != rhs._at; }
        const Sample& operator*() { return *_at; }
 
        ConstIterator& operator=(const ConstIterator& rhs) {
            _bufferLength = rhs._bufferLength;
            _bufferFirst = rhs._bufferFirst;
            _bufferLast = rhs._bufferLast;
            _at = rhs._at;
            return *this;
        }
        ConstIterator& operator++() {
            _at = (_at == _bufferLast) ? _bufferFirst : _at + 1;
            return *this;
        }
        ConstIterator operator++(int) {
            ConstIterator tmp(*this);
            ++(*this);
            return tmp;
        }
        ConstIterator& operator--() {
            _at = (_at == _bufferFirst) ? _bufferLast : _at - 1;
            return *this;
        }
        ConstIterator operator--(int) {
            ConstIterator tmp(*this);
            --(*this);
            return tmp;
        }
        const Sample& operator[] (int i) {
            return *atShiftedBy(i);
        }
        ConstIterator operator+(int i) {
            return ConstIterator(_bufferFirst, _bufferLength, atShiftedBy(i));
        }
        ConstIterator operator-(int i) {
            return ConstIterator(_bufferFirst, _bufferLength, atShiftedBy(-i));
        }
 
        void readSamples(Sample* dest, int numSamples) {
            auto samplesToEnd = _bufferLast - _at + 1;
 
            if (samplesToEnd >= numSamples) {
                memcpy(dest, _at, numSamples * SampleSize);
                _at += numSamples;
            } else {
                auto samplesFromStart = numSamples - samplesToEnd;
                memcpy(dest, _at, samplesToEnd * SampleSize);
                memcpy(dest + samplesToEnd, _bufferFirst, samplesFromStart * SampleSize);
 
                _at = _bufferFirst + samplesFromStart;
            }
        }
        void readSamplesWithFade(Sample* dest, int numSamples, float fade) {
            Sample* at = _at;
            for (int i = 0; i < numSamples; i++) {
                *dest = (float)*at * fade;
                ++dest;
                at = (at == _bufferLast) ? _bufferFirst : at + 1;
            }
        }
 
 
    private:
        Sample* atShiftedBy(int i) {
            i = (_at - _bufferFirst + i) % _bufferLength;
            if (i < 0) {
                i += _bufferLength;
            }
            return _bufferFirst + i;
        }
 
        int _bufferLength;
        Sample* _bufferFirst;
        Sample* _bufferLast;
        Sample* _at;
    };
 
    ConstIterator nextOutput() const {
        return ConstIterator(_buffer, _bufferLength, _nextOutput);
    }
    ConstIterator lastFrameWritten() const {
        return ConstIterator(_buffer, _bufferLength, _endOfLastWrite) - _numFrameSamples;
    }
 
    int writeSamples(ConstIterator source, int maxSamples);
    int writeSamplesWithFade(ConstIterator source, int maxSamples, float fade);
 
    float getFrameLoudness(ConstIterator frameStart) const;
 
protected:
    Sample* shiftedPositionAccomodatingWrap(Sample* position, int numSamplesShift) const;
    float getFrameLoudness(const Sample* frameStart) const;
 
    int _numFrameSamples;
    int _frameCapacity;
    int _sampleCapacity;
    int _bufferLength; // actual _buffer length (_sampleCapacity + 1)
    int _overflowCount{ 0 }; // times the ring buffer has overwritten data
 
    Sample* _nextOutput{ nullptr };
    Sample* _endOfLastWrite{ nullptr };
    Sample* _buffer{ nullptr };
};
 
// expose explicit instantiations for scratch/mix buffers
using AudioRingBuffer = AudioRingBufferTemplate<int16_t>;
using AudioMixRingBuffer = AudioRingBufferTemplate<float>;
 
#endif // hifi_AudioRingBuffer_h