Sample.h

/*
 * Sample.h
 *
 * This file is part of Mozzi.
 *
 * Copyright 2012-2024 Tim Barrass and the Mozzi Team
 *
 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
 *
 */
 
#ifndef SAMPLE_H_
#define SAMPLE_H_
 
#include "MozziHeadersOnly.h"
#include "mozzi_fixmath.h"
#include "mozzi_pgmspace.h"
 
// fractional bits for sample index precision
#define SAMPLE_F_BITS 16
#define SAMPLE_F_BITS_AS_MULTIPLIER 65536
 
// phmod_proportion is an 1n15 fixed-point number only using
// the fractional part and the sign bit
#define SAMPLE_PHMOD_BITS 16
 
enum interpolation {INTERP_NONE, INTERP_LINEAR};
 
template <unsigned int NUM_TABLE_CELLS, unsigned int UPDATE_RATE, uint8_t INTERP=INTERP_NONE>
class Sample
{
 
public:
 
    Sample(const int8_t * TABLE_NAME):table(TABLE_NAME),endpos_fractional((unsigned long) NUM_TABLE_CELLS << SAMPLE_F_BITS) // so isPlaying() will work
    {
        setLoopingOff();
        //rangeWholeSample();
    }
 
 
 
    Sample():endpos_fractional((unsigned long) NUM_TABLE_CELLS << SAMPLE_F_BITS)
    {
        setLoopingOff();
        //rangeWholeSample();
    }
 
 
    inline
    void setTable(const int8_t * TABLE_NAME)
    {
        table = TABLE_NAME;
    }
 
 
    inline
    void setStart(unsigned int startpos)
    {
        startpos_fractional = (unsigned long) startpos << SAMPLE_F_BITS;
    }
 
 
    inline
    void start()
    {
        phase_fractional = startpos_fractional;
        if(paused) setPaused(false);
    }
 
 
    inline
    void start(unsigned int startpos)
    {
        setStart(startpos);
        start();
    }
 
    inline
    void setPaused(bool to_pause = true) 
    {
        paused = to_pause; 
    }
 
    inline
    bool isPaused() const { return paused; }
 
 
    inline
    void setEnd(unsigned int end)
    {
        endpos_fractional = (unsigned long) end << SAMPLE_F_BITS;
    }
 
 
    inline
    void rangeWholeSample()
    {
        startpos_fractional = 0;
        endpos_fractional = (unsigned long) NUM_TABLE_CELLS << SAMPLE_F_BITS;
    }
 
 
    inline
    void setLoopingOn()
    {
        looping=true;
    }
 
 
    inline
    void setLoopingOff()
    {
        looping=false;
    }
 
 
 
    inline
    int8_t next() { // 4us
 
        if (paused) return 0;
        if (phase_fractional>=endpos_fractional){
            if (looping) {
                phase_fractional = startpos_fractional + (phase_fractional - endpos_fractional);
            }else{
                return 0;
            }
        }
        int8_t out;
        if(INTERP==INTERP_LINEAR){
            // WARNNG this is hard coded for when SAMPLE_F_BITS is 16
            unsigned int index = phase_fractional >> SAMPLE_F_BITS;
            out = FLASH_OR_RAM_READ<const int8_t>(table + index);
            int8_t difference = FLASH_OR_RAM_READ<const int8_t>((table + 1) + index) - out;
            int8_t diff_fraction = (int8_t)(((((unsigned int) phase_fractional)>>8)*difference)>>8); // (unsigned int) phase_fractional keeps low word, then>> for only 8 bit precision
            out += diff_fraction;
        }else{
            out = FLASH_OR_RAM_READ<const int8_t>(table + (phase_fractional >> SAMPLE_F_BITS));
        }
        incrementPhase();
        return out;
    }
 
 
    inline
    boolean isPlaying(){
        return phase_fractional<endpos_fractional && !paused;
    }
 
 
    // Not readjusted for arbitrary table length yet
    //
    //  Returns the next sample given a phase modulation value.
    // @param phmod_proportion phase modulation value given as a proportion of the wave. The
    // phmod_proportion parameter is a Q15n16 fixed-point number where to fractional
    // n16 part represents -1 to 1, modulating the phase by one whole table length in
    // each direction.
    // @return a sample from the table.
    //
    // inline
    // int8_t phMod(long phmod_proportion)
    // {
    //  incrementPhase();
    //  return FLASH_OR_RAM_READ<const int8_t>(table + (((phase_fractional+(phmod_proportion * NUM_TABLE_CELLS))>>SAMPLE_SAMPLE_F_BITS) & (NUM_TABLE_CELLS - 1)));
    // }
 
 
 
    inline
    void setFreq (int frequency) {
        phase_increment_fractional = ((((unsigned long)NUM_TABLE_CELLS<<ADJUST_FOR_NUM_TABLE_CELLS)*frequency)/UPDATE_RATE) << (SAMPLE_F_BITS - ADJUST_FOR_NUM_TABLE_CELLS);
    }
 
 
    inline
    void setFreq(float frequency)
    { // 1 us - using float doesn't seem to incur measurable overhead with the oscilloscope
        phase_increment_fractional = (unsigned long)((((float)NUM_TABLE_CELLS * frequency)/UPDATE_RATE) * SAMPLE_F_BITS_AS_MULTIPLIER);
    }
 
 
    inline
    void setFreq_Q24n8(Q24n8 frequency)
    {
        //phase_increment_fractional = (frequency* (NUM_TABLE_CELLS>>3)/(UPDATE_RATE>>6)) << (F_BITS-(8-3+6));
        phase_increment_fractional = (((((unsigned long)NUM_TABLE_CELLS<<ADJUST_FOR_NUM_TABLE_CELLS)>>3)*frequency)/(UPDATE_RATE>>6))
                                         << (SAMPLE_F_BITS - ADJUST_FOR_NUM_TABLE_CELLS - (8-3+6));
    }
 
 
    inline
    int8_t atIndex(unsigned int index)
    {
        return FLASH_OR_RAM_READ<const int8_t>(table + index);
    }
 
 
    inline
    unsigned long phaseIncFromFreq(unsigned int frequency)
    {
        return (((unsigned long)frequency * NUM_TABLE_CELLS)/UPDATE_RATE) << SAMPLE_F_BITS;
    }
 
 
    inline
    void setPhaseInc(unsigned long phaseinc_fractional)
    {
        phase_increment_fractional = phaseinc_fractional;
    }
 
 
private:
 
 
static const uint8_t ADJUST_FOR_NUM_TABLE_CELLS = (NUM_TABLE_CELLS<2048) ? 8 : 0;
 
 
    inline
    void incrementPhase()
    {
        phase_fractional += phase_increment_fractional;
    }
 
 
    volatile unsigned long phase_fractional;
    volatile unsigned long phase_increment_fractional;
    const int8_t * table;
    bool looping;
    bool paused{false};
    unsigned long startpos_fractional, endpos_fractional;
};
 
 
#endif /* SAMPLE_H_ */