v0.18 alpha RISC os Digital Signal Processor

 Risc os Digital Signal Processor
   (C) 2017 A.V.Bartram

  THIS SOFTWARE IS PROVIDED  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  IN NO EVENT SHALL A.V.Bartram BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL
  ,SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO
  ),PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS
  ;OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

NOTE: This is alpha quality software and may not work on all RISC OS systems
      and may contain bugs


n.b. 1) *RMLOAD rdsp
        from the bin directory
     2) Then set directory in the examples directory
     3) Run the BASIC example programs.

Release status: Alpha
Version: 0.17

Features:
* 8 channel 16 bit audio
  > Each channel features:
    + Synthesiser & Sample playback.
  > Synthesiser features:
    + 364 playable frequencies
    + 4 wavetypes that can be AND'ed together:
      - Pulse wave between 1% and 50% duty cycle i.e. up to a square wave
      - Saw wave
      - Triangle wave
      - Modulatable noise
    * A low pass filter with Q.
    + Pulse width modulation
    + A 3 stage envelope in the style of the BBC Micro 3 stage envelope
      that can modulate : PWM or Filter or Pitch or Amplitude.
    + A 4 stage ADSR envelope that is locked to amplitude but can also
      modulate : PWM or filter or Pitch.
    + Channel modes including:
       - Oscillator synchronised tuning
       - XOR (ring modulation) between adjacent channels.
       - Channel muting.
   > Sample playback features
    + Play back PCM samples through the oscillator of the synthesiser at one of
      364 frequencies.
* Up to 256 envelope commands
* Up to 256 loaded 16 bit 44 khz samples via WAV format support.
* SOUND and ENVELOPE command integration
  SOUND command has some limited legacy support by default
  SOUND 1,-15,208,100 plays a square wave at the A above middle C
                      on channel 1.
                      n.b. Eqivalent to SOUND 1,-15,137,100 on the BBC Micro.
  SOUND 0,-15,0,100   plays a pulse wave of the same frequency as the BBC Micro
                      and noise and modulatable noise is mapped similarly.
                      n.b. This actually plays back on channel 8.

  In actual fact the RDSP sound command has the following fields:
  SOUND PFIC,TTVV,FRNN,DDDD
    P = Pan (not in current alpha)
    F = Flags : &10 - Synchronise, &20 - Mute, &40 - XOR with previous channel
    I = Instrument : &00 - Waveform, &10 - Envelope, &20 - Sample
    C = Channel : 1 to 8 (or the BBC Micro noise 0 channel implemented above)

    T = Tone : Waveform mask or Envelope number or Sample number
               n.b. a waveform of 0xff is disallowed in order to support
                    legacy OS Word 7 behaviour.
               The following waveforms may be selected via a bitmask.
               RDSP will AND the resulting WAVs together
               &01 to &1f : Pulse wave from ~1% to a square wave
               &20        : Saw wave i.e. a 'ramp'.
               &40        : Triangle wave
               &80        : Modulatable noise

    V = Volume : 0 to 255 or -15 to -1

    F = Low pass filter cut off : 0xf to 0x0
    R = Resonance - bits 12,11,10
    N = Note - Range 0 to 364

    D = Duration of sound in 20ths of a second.

  ENVELOPE command has different parameters for RDSP:
  ENVELOPE N,W,F,O,T,S2,S13,D1,D2,D3,A,D,S,R
  N = envelope number (1 to 127)
  W = Same as sound command however 255 is allowed.
  F = Most signficant 4 bits specify filter cut off
      where 0xf0 is fully open and 0x00 is closed
      Least signficant 4 bits specify Q
  O = envelope modulation options :
      0x01 - ADSR pitch modulation
      0x02 - ADSR fiter modulation
      0x04 - ADSR PWM modulation
      0x08 - 3 stage envelope amplitude modulation
      0x10 - 3 stage envelope pitch modulation
      0x20 - 3 stage envelope filter modulation
      0x40 - 3 stage envelope pulse width modulation
      0x80 - Loop 3 stage envelope
  T = time of 3 stage envelope in 100ths of a second
  S2 = number of steps in stage 2 of 3 stage envelope
  S13 = number of steps in stage 1 and 3 of 3 stage envelope
  D1 = modulation of parameters selected by O for 3 stage envelope in stage 1
  D2 = modulation of parameters selected by O for 3 stage envelope in stage 2
  D3 = modulation of parameters selected by O for 3 stage envelope in stage 3
  A = ADSR attack amount. Larger values are longer
  D = Decay amount. Larger values relative to S are supposed to create a pluck
      effect.
  S = Sustain volume proportion. The duration is set by the sound command 'D'
      Larger values are lounder and sustain volume is proportional to 'V'
      in the sound command.
  R = Release time. Larger values are longer


* Shared delay (echo) effect that can be mixed into individual channels

Pending features (planned for next alpha release):
 * Capability to link a looped sample as waveform in envelope commands
 * Improved legacy sound integration e.g. legacy envelope command integration
 * Capability to play back on hardware that does not support 44khz audio.
 * Master volume control
 * Stereo pan
 * Chorus effect
 * Overdrive effect
 * Warm effect

Known Alpha Bugs:
 * Whilst attack,sustain and release work correctly, decay has little effect and should probably be logarithmic.


