{- |
We use a hierarchy of signal wrappers
in order to capture all features of a signal.

At the bottom there is the signal storage as described in "Synthesizer.Storage".
With the element type of the storage
you decide whether you want mono or stereo signal
("Synthesizer.Frame.Stereo"),
and you decide on the precision, fixed point vs. floating point and so on.
However, due to Haskell's flexible type system
you don't need to decide finally on a type for your signal processing routines.
E.g. mono and stereo signals can be handled together
using the "Algebra.Module" class from the numeric-prelude package.
(An algebraic module is a vector space
without requiring availability of a division of scalars).

You can use the storage types directly
using the functions from "Synthesizer.Plain.Signal"
and "Synthesizer.Generic.Signal" and its cousins.
This is in a way simple,
since you do not have bother with units and complicated types,
but you miss type safety and re-usability.
E.g. you have to give frequencies in ratios of the sampling rate.
If you later decide to change the sampling rate, you must rewrite all time and frequency values.
If you anticipate changes in sampling rate,
you may write those values as ratios of a global sampling rate
right from the start.
But you might want different sample rates
for some parts of the computation,
or you may want sample rates that have no time dimension,
but say, length dimension.
The advanced system described below handles all these cases for you.

Ok, we said that at the bottom, there is the signal storage.
The next level is the decision
whether the raw data is interpreted as straight or as cyclic signal.
Most of the signals you are using,
will be "Synthesizer.Dimensional.Straight.Signal".
Currently, "Synthesizer.Dimensional.Cyclic.Signal"
is only needed for Fourier transform and as input to oscillators.
To get a straight signal out of storablevector data,
you will write

> import qualified Synthesizer.Storable.Signal as Store
> import qualified Synthesizer.Dimensional.Straight.Signal as Straight
>
> type MySignal y = Straight.T Store.T y

Note that @Straight.T@ has the type constructor @Store.T@ as first argument,
not the entire storage type @Store.T@.
This way compositions of such wrappers are automatically Functors.
However, I'm not completely certain, that this is good,
since 'fmap' allows to do unintended things
(e.g. switch from a numeric to a non-numeric element type).

The next level copes with amplitudes and their units.
An amplitude and its unit are provided per signal, not per sample.
We think that it is the most natural way, and it is also an efficient one.
Since the signal might be a stereo signal,
the numeric type of the amplitude can differ from the storage element type.
Usually, the first and the latter one are related by an "Algebra.Module" constraint.
You get a signal with amplitude by

> import qualified Synthesizer.Dimensional.Amplitude.Signal as Amp
>
> type MySignal v y yv = Amp.T v y (Straight.T Store.T) yv

where @v@ is the dimension of the amplitude of type @y@.
The storage element type, a vector with respect to @y@, is of type @yv@.

In some cases, an amplitude with a physical dimension just makes no sense.
Imagine a control signal consisting of @Bool@ elements like a gate signal,
or a signal containing elements of an enumeration
for switching between signals depending on the time.

For some control signals the amplitude unit is one.
We call these signals flat.
In this case you can choose
whether you use an explicit amplitude with @Scalar@ dimension
or you use no amplitude wrapper at all.
Most signal processors handle both kinds of flat signals
by the corresponding type class in "Synthesizer.Dimensional.Abstraction.Flat".

There is a special signal type for Dirac impulses,
that does not fit to that scheme,
that is, it cannot be equipped with an amplitude.
See "Synthesizer.Dimensional.Rate.Dirac".


Last but not least we want to look on how to handle sample rates.
Our goal is to write signal processes
that do not depend on the sample rate.
E.g. we want to have an exponential decay with a half-life of one second.
A second means 44100 samples at 44100 Hz sample rate,
or 22050 samples at 22050 Hz sample rate.
We want to abstract from the particular number of samples
in order to be able generate a signal at any sample rate (i.e. quality) we like.
The ideal representation of a signal is be a real function,
and we try to come close to it.
(Not quite, because a Dirac impulse is not a real function,
but we need it as identity element of the convolution.)

To this end we can equip a discrete signal with a sample rate,
see "Synthesizer.Dimensional.RateWrapper".
This alone however, leads to several problems:

* When combining some signals,
  it is not clear how to cope with different sample rates.
  Say you want to mix signals @a@ and @b@.
  Shall @mix a b@ have the sample rate of @a@ or that of @b@ or a new one?
  How shall the signals convert to a new rate?
  Since an automatically chosen method
  can always be inappropriate (either too slow or too low quality),
  the caller have to explicitly give tell it to 'mix'.
  This is not only inconvenient for the caller,
  but also requires a lot of boilerplate code in functions like 'mix'.

* An alternative solution to the problem above is,
  to check before mixing whether sample rates are equal,
  and abort with an error if they differ.
  This way no decisions on the sample rate
  and subsequent conversions are necessary.
  This still needs boilerplate in signal processors.
  It also does not tell the user by types,
  whether a processor can handle differing sample rates.
  Generally, dynamic checks are both inefficient
  and an inferior way to indicate programming errors,
  since they are only catched at run-time, if at all.

* Both solutions suffer from the inconvenience
  to specify the sample rate in all leaves,
  e.g. @mix (oscillator 44100 10) (oscillator 44100 11)@.

Naturally, when you want to get a signal with rate 44100 Hz sample rate,
you perform all signal processes at this rate.
Even if want to use oversampling,
then you will perform all signal processes at the higher rate
and downsample only once at the end.
Thus we introduce a way
to run a set of signal processes in the context of a sample rate.
It is still sensible and possible
to escape from this context or enter it again.

* You need to be to enter a sample rate context
  with a signal read from disk,
  with a sample rate that is not known at compile time.
  You might also intensionally compute a control signal at a low sample rate
  and convert it to a sample rate context for filtering.
  Generally the scheme of functions that allow different sample rates is:
  Use the sample rate of the output signal as context.
  Take all signals with independent sample rate
  as inputs outside the context.
  The according function is 'Synthesizer.Dimensional.Rate.Filter.frequencyModulationDecoupled'.

* When you want to play a sound or write it to disk,
  you must choose a sample rate and fix the computation to that rate.
  This conversion however means to run the whole computation within one sample rate context,
  since everything in that context depends on the sample rate.
  The according function is 'Synthesizer.Dimensional.RateWrapper.runProcess'.

The sample rate context is provided by "Synthesizer.Dimensional.Process".
It is a Reader monad,
but we only need applicative functor methods for signal processing.
This context is equipped with the type parameter @s@,
just as we know it from the 'Control.Monad.ST.ST' monad.
It also serves the same purpose:
We tag both signals and the sample rate context with the type parameter @s@.
The @forall s@ constraint for @runProcess@ ensures,
that a signal with such a tag remains in the context.
You can only escape the sample rate context
by rendering the signal and attach the sample rate to the rendered signal.

The sample rate tag type is provided by
"Synthesizer.Dimensional.RatePhantom".
Haskell's type system does not allow to restrict the types that it can wrap.
So in principle you can abuse it to wrap many things.
However we do not provide such functions
and this way the wrappable types ar restricted anyway.
-}
module Synthesizer.Dimensional.Overview where