Oscil.h

/*
 * Oscil.h
 *
 * Oscil.h owes much to AF_precision_synthesis.pde, 2009, Adrian Freed.
 *
 * This file is part of Mozzi.
 *
 * Copyright 20009 Arian Freed
 * 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 OSCIL_H_
#define OSCIL_H_
 
#include "Arduino.h"
#include "MozziHeadersOnly.h"
#include "mozzi_fixmath.h"
#include "FixMath.h"
#include "mozzi_pgmspace.h"
 
#ifdef OSCIL_DITHER_PHASE
#include "mozzi_rand.h"
#endif
 
// fractional bits for oscillator index precision
#define OSCIL_F_BITS 16
#define OSCIL_F_BITS_AS_MULTIPLIER 65536
 
// phmod_proportion is an 15n16 fixed-point number
#define OSCIL_PHMOD_BITS 16
 
//template <unsigned int NUM_TABLE_CELLS, unsigned int UPDATE_RATE, bool DITHER_PHASE=false>
template <uint16_t NUM_TABLE_CELLS, uint16_t UPDATE_RATE>
class Oscil
{
 
 
public:
    Oscil(const int8_t * TABLE_NAME):table(TABLE_NAME)
    {}
 
 
    Oscil()
    {}
 
 
    inline
    int8_t next()
    {
        incrementPhase();
        return readTable();
    }
 
 
    void setTable(const int8_t * TABLE_NAME)
    {
        table = TABLE_NAME;
    }
 
 
    // This could be called in the control interrupt, so phase_fractional should really be volatile,
    // but that could limit optimisation.  Since phase_fractional gets changed often in updateAudio()
    // (in loop()), it's probably worth keeping it nonvolatile until it causes problems
    void setPhase(unsigned int phase)
    {
        phase_fractional = (uint32_t)phase << OSCIL_F_BITS;
    }
 
    // This could be called in the control interrupt, so phase_fractional should really be volatile,
    // but that could limit optimisation.  Since phase_fractional gets changed often in updateAudio()
    // (in loop()), it's probably worth keeping it nonvolatile until it causes problems
    void setPhaseFractional(uint32_t phase)
    {
        phase_fractional = phase;
    }
 
 
    uint32_t getPhaseFractional()
    {
        return phase_fractional;
    }
 
 
 
    // PM: cos((angle += incr) + change)
    // FM: cos(angle += (incr + change))
    // The ratio of deviation to modulation frequency is called the "index of modulation". ( I = d / Fm )
    inline
    int8_t phMod(Q15n16 phmod_proportion)
    {
        incrementPhase();
        return FLASH_OR_RAM_READ<const int8_t>(table + (((phase_fractional+(phmod_proportion * NUM_TABLE_CELLS))>>OSCIL_F_BITS) & (NUM_TABLE_CELLS - 1)));
    }
 
 
  template <int8_t NI, int8_t NF, uint8_t RANGE>
    inline
  int8_t phMod(SFix<NI,NF,RANGE> phmod_proportion)
    {
      return phMod(SFix<15,16>(phmod_proportion).asRaw());
    }
 
 
  
    inline
    int8_t phMod(SFix<15,16> phmod_proportion)
    {
      return phMod(phmod_proportion.asRaw());
    }
 
 
    inline
    void setFreq (int frequency) {
        // TB2014-8-20 change this following Austin Grossman's suggestion on user list
        // https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/mozzi-users/u4D5NMzVnQs/pCmiWInFvrkJ
        //phase_increment_fractional = ((((uint32_t)NUM_TABLE_CELLS<<ADJUST_FOR_NUM_TABLE_CELLS)*frequency)/UPDATE_RATE) << (OSCIL_F_BITS - ADJUST_FOR_NUM_TABLE_CELLS);
        // to this:
        phase_increment_fractional = ((uint32_t)frequency) * ((OSCIL_F_BITS_AS_MULTIPLIER*NUM_TABLE_CELLS)/UPDATE_RATE);
    }
 
 
    inline
    void setFreq(float frequency)
    { // 1 us - using float doesn't seem to incur measurable overhead with the oscilloscope
        phase_increment_fractional = (uint32_t)((((float)NUM_TABLE_CELLS * frequency)/UPDATE_RATE) * OSCIL_F_BITS_AS_MULTIPLIER);
    }
 
 
        template <int8_t NI, int8_t NF, uint64_t RANGE>
        inline
        void setFreq(UFix<NI,NF,RANGE> frequency)
        {
        setFreq_Q16n16(UFix<16,16>(frequency).asRaw());
        }
 
  
  
    inline
    void setFreq_Q24n8(Q24n8 frequency)
    {
        //phase_increment_fractional = (frequency* (NUM_TABLE_CELLS>>3)/(UPDATE_RATE>>6)) << (F_BITS-(8-3+6));
// TB2016-10-2 line below might have been left in accidentally while making the 2014 change below, remove for now
//      phase_increment_fractional = (((((uint32_t)NUM_TABLE_CELLS<<ADJUST_FOR_NUM_TABLE_CELLS)>>3)*frequency)/(UPDATE_RATE>>6))
//                                   << (OSCIL_F_BITS - ADJUST_FOR_NUM_TABLE_CELLS - (8-3+6));
 
        // TB2014-8-20 change this following Austin Grossman's suggestion on user list
        // https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/mozzi-users/u4D5NMzVnQs/pCmiWInFvrkJ
        if ((256UL*NUM_TABLE_CELLS) >= UPDATE_RATE) {
            phase_increment_fractional = ((uint32_t)frequency) * ((256UL*NUM_TABLE_CELLS)/UPDATE_RATE);
        } else {
            phase_increment_fractional = ((uint32_t)frequency) / (UPDATE_RATE/(256UL*NUM_TABLE_CELLS));
        }
    }
 
  template <uint64_t RANGE>
  inline
  void setFreq(UFix<24,8,RANGE> frequency)
        {
      setFreq_Q24n8(frequency.asRaw());
      }
 
 
    inline
    void setFreq_Q16n16(Q16n16 frequency)
    {
        //phase_increment_fractional = ((frequency * (NUM_TABLE_CELLS>>7))/(UPDATE_RATE>>6)) << (F_BITS-16+1);
        // TB2014-8-20 change this following Austin Grossman's suggestion on user list
        // https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/mozzi-users/u4D5NMzVnQs/pCmiWInFvrkJ
        //phase_increment_fractional = (((((uint32_t)NUM_TABLE_CELLS<<ADJUST_FOR_NUM_TABLE_CELLS)>>7)*frequency)/(UPDATE_RATE>>6))
        //                             << (OSCIL_F_BITS - ADJUST_FOR_NUM_TABLE_CELLS - 16 + 1);
        if (NUM_TABLE_CELLS >= UPDATE_RATE) {
            phase_increment_fractional = ((uint32_t)frequency) * (NUM_TABLE_CELLS/UPDATE_RATE);
        } else {
            phase_increment_fractional = ((uint32_t)frequency) / (UPDATE_RATE/NUM_TABLE_CELLS);
        }
    }
 
 
  template <uint64_t RANGE>
   inline
  void setFreq(UFix<16,16,RANGE> frequency)
        {
      setFreq_Q16n16(frequency.asRaw());
      }
 
  
 
  template <int8_t NI, int8_t NF, uint64_t RANGE>
        inline
  void setFreq(SFix<NI,NF,RANGE> frequency)
        {
      setFreq_Q16n16(UFix<16,16>(frequency).asRaw());
        }
  
/*
    inline
    void setFreqMidi(int8_t note_num) {
        setFreq_Q16n16(mtof(note_num));
    }
*/
    inline
    int8_t atIndex(unsigned int index)
    {
        return FLASH_OR_RAM_READ<const int8_t>(table + (index & (NUM_TABLE_CELLS - 1)));
    }
 
 
    inline
    uint32_t phaseIncFromFreq(int frequency)
    {
        // TB2014-8-20 change this following Austin Grossman's suggestion on user list
        // https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/mozzi-users/u4D5NMzVnQs/pCmiWInFvrkJ
        //return (((uint32_t)frequency * NUM_TABLE_CELLS)/UPDATE_RATE) << OSCIL_F_BITS;
        return ((uint32_t)frequency) * ((OSCIL_F_BITS_AS_MULTIPLIER*NUM_TABLE_CELLS)/UPDATE_RATE);
    }
 
 
    inline
    void setPhaseInc(uint32_t 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 | 1); // odd phase incr, attempt to reduce frequency spurs in output
        phase_fractional += phase_increment_fractional;
    }
 
 
    inline
    int8_t readTable()
    {
#ifdef OSCIL_DITHER_PHASE
        return FLASH_OR_RAM_READ<const int8_t>(table + (((phase_fractional + ((int)(xorshift96()>>16))) >> OSCIL_F_BITS) & (NUM_TABLE_CELLS - 1)));
#else
        return FLASH_OR_RAM_READ<const int8_t>(table + ((phase_fractional >> OSCIL_F_BITS) & (NUM_TABLE_CELLS - 1)));
        //return FLASH_OR_RAM_READ<int8_t>(table + (((phase_fractional >> OSCIL_F_BITS) | 1 ) & (NUM_TABLE_CELLS - 1))); odd phase, attempt to reduce frequency spurs in output
#endif
    }
 
 
    uint32_t phase_fractional;
    uint32_t phase_increment_fractional;
    const int8_t * table;
 
};
 
 
#endif /* OSCIL_H_ */