/*
  MidiSynth, MIDI synthesiser, a repacement for the Acorn MIDI module

  instruments.h - Instrument definitions

  created  15/01/10
  1.0      14/06/14
*/

#ifndef instrument_h
#define instrument_h


/*
Instrument Data Tables
----------------------
*/

#define ENV_RATE  500                          // envelope sample rate in Hz
#define RETRIG(x) ((int)((ENV_RATE/(x))+0.5))  // envelope retrigger rate in Hz
#define MOD(x)    ((int)((((x)*(1<<SIN_BITS)/ENV_RATE)*(1<<FIX))+0.5)) // modulation oscillator rate in Hz

#define NAME_LEN  24  // maximum length of names for instruments and waves including terminating null.

/*

Envelopes
---------

decay/sustain/release time constants are Q16, i.e. 65535 max

  step = Q16 / (ENV_RATE * time_constant in seconds)
       = 65536 * 1000 / 500 / TC (where TC is the required time constant in ms)
       = 131072 / TC

  time to reach x% of target
      step  TC(63.2%) 50%    90%
        13  10sec     6.9sec 23sec
       131  1sec      690ms  2.3sec
      1311  100ms     69ms   230ms
     13107  10ms      6.9ms  23ms

  %target = 100 * (1 - exp(-t/TC))

note. Step variables are defined as signed 16bit so don't set to higher than 32767.
      This means the minimum time constant is 4ms.

attack/decay targets are Q15, i.e. 32767 max

Modulation Oscillator
---------------------

 mod_rate = x * (1<<16) / ENV_RATE
          = x * 131.072

    where x is the desired frequency in Hz, (maximum = ENV_RATE / 2)

Retrigger rate
--------------

 count = ENV_RATE / x

    where x is the desired retrigger rate in Hz

Glide Filter
------------
  Q15 - step = Q15 / (ENV_RATE * time_constant in seconds)
  step = Q15 - Q15 / (ENV_RATE * time_constant in seconds)
       = 32768 - 32768 * 1000 / 500 / TC (where TC is the required time constant in ms)
       = 32768 - 65536 / TC

    TC(ms) = 65536 / (32768 - step)

  time to reach x% of target
      step  TC(63.2%) 50%    90%
     32762  10sec     6.9sec 23sec
     32703  1sec      690ms  2.3sec
     32113  100ms     69ms   230ms
     26215  10ms      6.9ms  23ms
     16384  4ms
         0  2ms
*/

// Instrument definition
// -------------------------------

#define NUM_TONES 2  // number of tone sources per generator

// Delay-Attack-Hold-Decay-Sustain-Release envelope definition
typedef struct env_s
{
  short int          // range for all envelope parameters is 0 to 32767
    delay,           // (delay * 2) ms, envelope delay time
    attack_step,     // (16384 / step) ms, attack time (linear)
    attack_target,   // attack target, linear, max = 0dB
    hold,            // (hold * 2) ms, attack target hold time
    decay_step,      // (131072 / step) ms, decay time constant (exponential)
    decay_target,    // decay target, linear, max = 0dB
    sustain_step,    // (131072 / step) ms, sustain time constant (exponential)
    release_step;    // (131072 / step) ms, release time constant (exponential)
} env_t;

// Tone generator definition
typedef struct tone_s
{
  short int
    number,          // tone wavetable number
    pitch,           // final pitch offset from key, midi key number, can be negative
    initial_pitch,   // starting point for glide, signed offset, if 0 use last key pitch (useful for mono)
    glide;           // pitch glide time constant, 0 = fastest, 32767 = slowest

  env_t env;         // envelope
} tone_t;

// Instrument definition
typedef struct ins_s
{
  char name[NAME_LEN]; // instrument name

  tone_t
    wave[NUM_TONES]; // tone generators

  env_t
    noise_env,       // noise generator envelope
    filter_env;      // filter envelope

  unsigned int
    switches;        // see below

  short int
    filter_fc,       // filter cutoff, midi key number, can be negative
    filter_q,        // filter resonance, 1023 = oscilate to 0 = overdamped.
    retrig,          // retrigger count in envelope periods
    mod_wave,        // modulation wavetable number
    mod_rate,        // modulation rate
    mod_depth,       // modulation amplitude
    fm_depth,        // FM modulation depth, tone1 = modulator, tone2 = carrier
    detune,          // tone 1 to 2 detune, 0 = none, 1023 = approx. 1 semitone
    gain;            // overall gain, Q10, 1024 = x1 or 0dB

  unsigned char
    master_env,      // 0=none, 1=wave[0], 2=wave[1], 3=filter, 4=noise
    spare;           // (unused)

} ins_t;


// bit locations of switches
//                       bit      value       description
//                       ---    ----------    ----------------------------
#define LOWPASS           0  // 0x00000001    lowpass filter                     )
#define BANDPASS          1  // 0x00000002    bandpass filter                    )
#define HIGHPASS          2  // 0x00000004    highpass filter                    )
#define FILTERED_TONE     3  // 0x00000008    filtered tone generator            ) accessed by sample rate interrupt
#define TONE1_OUT         4  // 0x00000010    tone 1 output enable               )
#define TONE2_OUT         5  // 0x00000020    tone 2 output enable               )
#define TONE_RING_MOD     6  // 0x00000040    tone 1 and tone 2 ring modulation  )
#define PITCH1_MOD        7  // 0x00000080    tone 1 pitch modulation
#define PITCH2_MOD        8  // 0x00000100    tone 2 pitch modulation
#define AMP1_MOD          9  // 0x00000200    tone 1 amplitude modulation (unsigned, or DSB full carrier)
#define AMP1_RING        10  // 0x00000400    tone 1 amplitude modulation (signed, or DSB suppressed carrier)
#define AMP2_MOD         11  // 0x00000800    tone 2 amplitude modulation (unsigned, or DSB full carrier)
#define AMP2_RING        12  // 0x00001000    tone 2 amplitude modulation (signed, or DSB suppressed carrier)
#define NOISE_MOD        13  // 0x00002000    noise amplitude modulation
#define FILTER_MOD       14  // 0x00004000    filter pitch modulation
#define WAVE_RETRIGGER   15  // 0x00008000    tone envelope retrigger
#define NOISE_RETRIGGER  16  // 0x00010000    noise envelope retrigger
#define FILTER_RETRIGGER 17  // 0x00020000    filter envelope retrigger
#define PITCH_TRACK      18  // 0x00040000    tone pitch key track
#define FILTER_TRACK     19  // 0x00080000    filter frequency key track
#define WAVE_ENV_TRACK   20  // 0x00100000    tone envelope time constant pitch track
#define NOISE_ENV_TRACK  21  // 0x00200000    noise envelope time constant pitch track
#define FILTER_ENV_TRACK 22  // 0x00400000    filter envelope time constant pitch track
#define INV_FILTER_ENV   23  // 0x00800000    inverted filter envelope
#define DEFINED_LENGTH   24  // 0x01000000    defined length, no key up required
#define MONO_SCAN        25  // 0x02000000    monophonic keyboard scan

#define ACTIVE           31  // 0x80000000    set if generator active


/*
   ----------------------------------
       Instrument definitions
   ----------------------------------

 In general, if a parameter is unused, or not required, set its value to zero.
 An instrument with all parameters set to zero will produce no sound.

 Instrument Banks and Bank Maps
 ------------------------------

 A bank selects 128 instruments and consists of indexes to the array of instruments. A zero index
 is used to indicate an empty location so valid indexes start from 1 and need to have 1 subtracted
 before accsessing the instrument array. The indexes are 16 bit to allow access of up to 64k
 instruments. If a zero index is selected, the bank 0 instrument will be used.

 Bank maps are used to select the above banks.
 There are two maps, one for pitched instruments, and one for drum kits. A zero entry means the
 bank is not defined, and bank 0 is used.
 Up to 128 Instrument banks and up to 128 drum kits can be defined. The indexes are 8 bit.

 The first entry in an instrument and bank definition is the 24 byte name in ascii.

 Wave definitions are a single cycle of the waveform. They are band limited and start on a zero
 crossing. They contain 1024 x 16 bit samples with a 24 byte wave name at the start of the definition.
 A waveform can be used by more than one instrument definition.

 Memory usage.
 Banks: 256 + 24 = 280 bytes each.
 Bank Maps: 128 x 2 maps = 256 bytes.
 Instruments: 104 + 24 = 128 bytes each.
 Waveforms: 2048 + 24 = 2072 bytes each.

 Instrument storage
 ------------------

 Instruments are accsessed by   ins_t pitched_instrument = instrument[bank[banks[lo]-1].ins[prg]-1];
 Percussion on channel 10 by    ins_t percussion_instrument = instrument[bank[kits[prg]-1].ins[key]-1];
 A zero index is used to denote an empty entry so valid indexes in banks, kits and bank, start at 1.
*/

// wave table
typedef struct wtbl_s
{
  const short int *wave;     // pointer to wave data
  const char name[NAME_LEN]; // wave name
} wtbl_t;

#endif

