Buffer.h

Go to the documentation of this file.

//
//  $Id: Buffer.h 718 2012-04-15 23:59:35Z weegreenblobbie $
//
//  Nsound is a C++ library and Python module for audio synthesis featuring
//  dynamic digital filters. Nsound lets you easily shape waveforms and write
//  to disk or plot them. Nsound aims to be as powerful as Csound but easy to
//  use.
//
//  Copyright (c) 2004-Present Nick Hilton
//
//  weegreenblobbie_yahoo_com (replace '_' with '@' and '.')
//

//
//  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 Library General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
#ifndef _NSOUND_BUFFER_H_
#define _NSOUND_BUFFER_H_

#include <Nsound/Nsound.h>
#include <Nsound/BufferSelection.h>

#include <cmath>
#include <iostream>
#include <string>
#include <vector>

namespace Nsound
{

typedef std::vector< uint32 > Uint32Vector;
typedef std::vector< float64 > FloatVector;

// Forward declaration
class AudioStream;

//
class Buffer
{
    public:

    // Forward declaration
    class circular_iterator;

    typedef FloatVector::iterator         iterator;
    typedef FloatVector::const_iterator   const_iterator;

    //
    Buffer();
    explicit Buffer(uint32 chunk_size);

    //
    explicit Buffer(const FloatVector & list);

    //
    Buffer(const std::string & filename, uint32 chunk_size = 4096);

    ~Buffer();

    //
    Buffer(const Buffer & rhs);

    //
    void
    abs();

    //
    Buffer
    getAbs() const
    { Buffer temp(*this); temp.abs(); return temp; };

    // add()
    //
    //
    //
    void
    add(const Buffer & buffer,
        uint32 offset = 0,
        uint32 n_samples = 0);

    //
    uint32
    argmax() const;

    //
    uint32
    argmin() const;

    //
    inline
    iterator
    begin()
    { return data_.begin(); };

    //
    inline
    const_iterator
    begin() const
    { return data_.begin(); };

    //
    inline
    circular_iterator
    cbegin()
    { return circular_iterator(data_.begin(), data_.end()); };

    //
    inline
    circular_iterator
    cbegin() const
    { return circular_iterator(data_.begin(), data_.end()); };

    //
    inline
    iterator
    end()
    { return data_.end(); };

    //
    inline
    const_iterator
    end() const
    { return data_.end(); };

    //
    inline
    uint32
    getNBytes() const
    { return bytes_per_sample_ * data_.size(); };

    //
    void
    exp();

    //
    Buffer
    getExp() const
    { Buffer temp(*this); temp.exp(); return temp; };

    //
    void
    convolve(const Buffer & H);

    //
    Buffer
    getConvolve(const Buffer & H) const;

    //
    void
    dB();

    //
    Buffer
    getdB() const
    { Buffer temp(*this); temp.dB(); return temp; };

    //
    void
    derivative(uint32 n);

    //
    Buffer
    getDerivative(uint32 n) const
    { Buffer temp(*this); temp.derivative(n); return temp; };

    //
    void
    downSample(uint32 n);

    //
    Buffer
    getDownSample(uint32 n) const;

    //
    Uint32Vector
    findPeaks(
        uint32 window_size = 0,
        const float64 & min_height = 0.0) const;

//~    Experimental, doesn't work yet
//~    ///////////////////////////////////////////////////////////////////////////
//~    //! Returns the estimated fundamental frequency of the Buffer.
//~    Buffer
//~    findPitch(const float64 & sample_rate);

    //
    inline
    uint32
    getLength() const
    { return data_.size(); };

    //
    void
    limit(const float64 & min, const float64 & max);

    //
    void
    limit(const Buffer & min, const Buffer & max);

    //
    Buffer
    getLimit(const float64 & min, const float64 & max) const
    { Buffer temp(*this); temp.limit(min, max); return temp; };

    //
    Buffer
    getLimit(const Buffer & min, const Buffer & max) const
    { Buffer temp(*this); temp.limit(min, max); return temp; };

    //
    void
    log();

    //
    Buffer
    getLog() const
    { Buffer temp(*this); temp.log(); return temp; };

    //
    void
    log10();

    //
    Buffer
    getLog10() const
    { Buffer temp(*this); temp.log10(); return temp; };

    //
    float64
    getMax() const;

    //
    float64
    getMaxMagnitude() const;

    //
    float64
    getMean() const;

    //
    float64
    getMin() const;

    //
    void
    normalize();

    //
    Buffer
    getNormalize() const
    { Buffer temp(*this); temp.normalize(); return temp; };

    //
    Buffer
    getSignalEnergy(uint32 window_size) const;

    //
    float64
    getStd() const;

    //
    float64
    getSum() const;

    //
    void
    zNorm();

    //
    Buffer
    getZNorm() const
    { Buffer temp(*this); temp.zNorm(); return temp; };

    //
    BufferSelection
    operator()(const BooleanVector & bv);

    Buffer &
    operator=(const Buffer & rhs);

    boolean
    operator==(const Buffer & rhs) const;

    boolean
    operator!=(const Buffer & rhs) const;

    inline
    const float64
    operator[](uint32 index) const
    { return data_[index]; };

    inline
    float64 &
    operator[](uint32 index)
    { return data_[index]; };

    //
    Buffer &
    operator<<(const AudioStream & rhs);

    //
    Buffer &
    operator<<(const Buffer & rhs);

    Buffer &
    operator<<=(const Buffer & rhs);

    inline
    Buffer &
    operator<<(const float64 & d)
    { data_.push_back(d); return *this; };

    inline
    Buffer &
    operator<<=(const float64 & d)
    { data_.push_back(d); return *this; };

    //
    Buffer & operator+=(const Buffer & rhs);

    //
    Buffer & operator-=(const Buffer & rhs);

    //
    Buffer & operator*=(const Buffer & rhs);

    //
    Buffer & operator/=(const Buffer & rhs);

    //
    Buffer & operator^=(const Buffer & powers);

    //
    Buffer & operator+=(const float64 & d);

    //
    Buffer & operator-=(const float64 & d);

    //
    Buffer & operator*=(const float64 & d);

    //
    Buffer & operator/=(const float64 & d);

    //
    Buffer & operator^=(const float64 & power);

    #ifndef SWIG


        friend
        std::ostream &
        operator<<(std::ostream & out,const Buffer & rhs);
    #endif

    //
    BooleanVector operator>(const float64 & rhs);

    //
    BooleanVector operator>=(const float64 & rhs);

    //
    BooleanVector operator<(const float64 & rhs);

    //
    BooleanVector operator<=(const float64 & rhs);

    //
    BooleanVector operator==(const float64 & rhs);

    //
    BooleanVector operator!=(const float64 & rhs);

    //~    ///////////////////////////////////////////////////////////////////////////
    //~    //! EXPERIMENTAL!  Transforms the Buffer to the frequency domain and shifts it by n_bins_to_shift and then transforms it back to the time domain.
    //~    //
    //~    //! \par Example:
    //~    //! \code
    //~    //! // C++
    //~    //! Buffer b1("california.wav");
    //~    //! b1.pitchShift(2048, 2048, 2);
    //~    //!
    //~    //! // Python
    //~    //! b1 = Buffer("california.wav")
    //~    //! b1.pitchShift(2048, 2048, 2)
    //~    //! \endcode
    //~    void
    //~    pitchShift(uint32 window_size, uint32 fft_size, int32 n_bins_to_shift );
    //~
    //~    ///////////////////////////////////////////////////////////////////////////
    //~    //! EXPERIMENTAL!  Transforms a copy of the Buffer to the frequency domain and shifts it by n_bins_to_shift and then transforms it back to the time domain.
    //~    //
    //~    //! \par Example:
    //~    //! \code
    //~    //! // C++
    //~    //! Buffer b1("california.wav");
    //~    //! Buffer b2 = b1.getPitchShift(2048, 2048, 2);
    //~    //!
    //~    //! // Python
    //~    //! b1 = Buffer("california.wav")
    //~    //! b2 = b1.getPitchShift(2048, 2048, 2)
    //~    //! \endcode
    //~    Buffer
    //~    getPitchShift(uint32 window_size, uint32 fft_size, int32 n_bins_to_shift) const
    //~    { Buffer temp(*this);
    //~        temp.pitchShift(window_size, fft_size, n_bins_to_shift); return temp;};

    //
    void
    plot(const std::string & title = "Buffer") const;

    //
    const
    float64 *
    getPointer() const
    { return &(data_[0]); }

    //
    float64 *
    getPointer()
    { return &(data_[0]); }

    //
    void
    preallocate(uint32 n);

    //
    void
    readWavefile(const char * filename);

    //
    void
    resample(const float64 & factor)
    { *this = getResample(factor, 10, 5.0); };

    //
    void
    resample(const Buffer & factor)
    { *this = getResample(factor, 10, 5.0); };

    //
    Buffer
    getResample(
        const float64 & factor,
        const uint32 N = 10,
        const float64 & beta = 5.0) const;

    //
    Buffer
    getResample(
        const Buffer & factor,
        const uint32 N = 10,
        const float64 & beta = 5.0) const;

    //
    Buffer
    getResample(
        const uint32 L,
        const uint32 M,
        const uint32 N = 10,
        const float64 & beta = 5.0) const;

    //
    void
    reverse();

    //
    Buffer
    getReverse() const
    { Buffer temp(*this); temp.reverse(); return temp; };

    //
    void
    round();

    //
    Buffer
    getRound() const
    { Buffer temp(*this); temp.round(); return temp; };

    //
    BufferSelection
    select(const uint32 start_index, const uint32 stop_index);

    //
    void
    smooth(uint32 n_passes, uint32 n_samples_per_average);

    //
    Buffer
    getSmooth(uint32 n_passes, uint32 n_samples_per_average) const
    { Buffer temp(*this); temp.smooth(n_passes, n_samples_per_average); return temp; };

    //
    void
    speedUp(const float64 & step_size);

    //
    Buffer
    getSpeedUp(const float64 & step_size) const
    { Buffer temp(*this); temp.speedUp(step_size); return temp; };

    //
    void
    speedUp(const Buffer & step_size);

    //
    Buffer
    getSpeedUp(const Buffer & step_size) const
    { Buffer temp(*this); temp.speedUp(step_size); return temp; };

    //
    void
    sqrt();

    //
    Buffer
    getSqrt() const
    { Buffer temp(*this); temp.sqrt(); return temp; };

    //
    Buffer
    subbuffer(uint32 start_index, uint32 n_samples = 0) const;

    //
    void
    upSample(uint32 n);

    //
    Buffer
    getUpSample(uint32 n) const;

    //
    void
    writeWavefile(const char * filename) const;

    #ifndef SWIG


    //
    class circular_iterator
    {
        public:

        circular_iterator()
            : begin_(), end_(), iter_(){};

        circular_iterator(const circular_iterator & copy);

        circular_iterator(const FloatVector & v);

        circular_iterator(
            const FloatVector::const_iterator & begin,
            const FloatVector::const_iterator & end);

        circular_iterator &
        operator++();

        circular_iterator &
        operator+=(const int32 i);

        circular_iterator
        operator+(const int32 i);

        circular_iterator &
        operator--();

        circular_iterator &
        operator-=(const int32 i);

        circular_iterator
        operator-(const int32 i);

        circular_iterator &
        operator=(const circular_iterator & rhs);

        boolean
        operator==(const circular_iterator & rhs)
        { return iter_ == rhs.iter_; };

        boolean
        operator!=(const circular_iterator & rhs)
        { return iter_ != rhs.iter_; };

        boolean
        operator==(const FloatVector::const_iterator & rhs)
        { return iter_ == rhs; };

        boolean
        operator!=(const FloatVector::const_iterator & rhs)
        { return iter_ != rhs; };

        inline
        const FloatVector::value_type
        operator*() const
        { return *iter_; };

        void
        reset()
        { iter_ = begin_; };

        protected:

        FloatVector::const_iterator begin_;
        FloatVector::const_iterator end_;
        FloatVector::const_iterator iter_;

    }; // const_circular_iterator
    #endif

    float64
    get_at_index(int32 index) const;

    void
    set_at_index(int32 index, const float64 & d);

    void swig_hook(){};

    static
    Buffer
    ones(const uint32 n_samples);

    static
    Buffer
    rand(const uint32 n_samples);

    static
    Buffer
    zeros(const uint32 n_samples);

    protected:

    Buffer
    getResample_(
        const uint32 L,
        const uint32 M,
        const uint32 N,
        const float64 & beta) const;

    // DOXME
    enum MathOperator
    {
            ADD,
            SUBTRACT,
            MULTIPLY,
            DIVIDE,
            POW
    };

    Buffer &
    vectorOperator(const Buffer & rhs, MathOperator op);

    Buffer &
    scalarOperator(const float64 & d, MathOperator op);

    FloatVector data_;

    static const uint32 bytes_per_sample_ = sizeof(float64);

}; // class Buffer



// Non class methods

inline Buffer operator+(const Buffer & lhs, const Buffer & rhs)
{
    Buffer temp(lhs);
    return temp += rhs;
}

inline Buffer operator-(const Buffer & lhs, const Buffer & rhs)
{
    Buffer temp(lhs);
    return temp -= rhs;
}

inline Buffer operator*(const Buffer & lhs, const Buffer & rhs)
{
    Buffer temp(lhs);
    return temp *= rhs;
}

inline Buffer operator/(const Buffer & lhs, const Buffer & rhs)
{
    Buffer temp(lhs);
    return temp /= rhs;
}

inline Buffer operator^(const Buffer & lhs, const Buffer & rhs)
{
    Buffer temp(lhs);
    return temp ^= rhs;
}

// Scalar operators

inline Buffer operator+(const Buffer & lhs, const float64 & d)
{
    Buffer temp(lhs);
    return temp += d;
}

inline Buffer operator-(const Buffer & lhs, const float64 & d)
{
    Buffer temp(lhs);
    return temp -= d;
}

inline Buffer operator*(const Buffer & lhs, const float64 & d)
{
    Buffer temp(lhs);
    return temp *= d;
}

inline Buffer operator/(const Buffer & lhs, const float64 & d)
{
    Buffer temp(lhs);
    return temp /= d;
}

//
inline Buffer operator^(const Buffer & lhs, const float64 & d)
{
    Buffer temp(lhs);
    return temp ^= d;
}

// Reverse scalar operators

inline Buffer operator+(const float64 & d, const Buffer & rhs)
{
    return rhs + d;
}

inline Buffer operator-(const float64 & d, const Buffer & rhs)
{
    return (rhs * -1.0) + d;
}

inline Buffer operator*(const float64 & d, const Buffer & rhs)
{
    return rhs * d;
}

inline Buffer operator/(const float64 & d, const Buffer & rhs)
{
    Buffer temp(rhs);

    uint32 size = rhs.getLength();

    for(uint32 i = 0; i < size; ++i)
    {
        temp[i] = d / rhs[i];
    }

    return temp;
}

inline Buffer operator^(const float64 & d, const Buffer & rhs)
{
    Buffer temp(rhs);

    uint32 size = rhs.getLength();

    for(uint32 i = 0; i < size; ++i)
    {
        temp[i] = ::pow(d ,rhs[i]);
    }

    return temp;
}

// DOXME
typedef std::vector<Buffer>   BufferVector;
typedef std::vector<Buffer *> BufferPointerVector;

// Friends
std::ostream &
operator<<(std::ostream & out, const Buffer & rhs);

}; // Namespace Nsound


// :mode=c++: jEdit modeline
#endif