<html>
<h2>StudioSound DSP Interface v1.00</h2><br>
The DSP interface in <i>StudioSound</i> allows audio-effects to be added to StudioSound as <i>plug-ins</i>. StudioSound handles most of the user-interface to the plug-in to ensure a consistent look of all effects.<br>
StudioSound calls the effect-code to apply the effect to a number samples; the samples are always 16 bit stereo and are stored in a circular buffer holding the samples and the previous 0.5 seconds of samples, thus allowing effects like reverb and echo.<br>
Up to 4 effects can be applied to each track in StudioSound.<br>

The following restrictions apply to all plug-ins, although it wasn't described in v1.00 of the plug-in interface documentation:
<ul>
<li>The parameter values must be in the range 0 - 1023 (ie. 10 bits)
<li>StudioSound must be allowed to alter the header after having loaded the plug-in, ie. the plug-in must not assume anything about the layout of the header after loading
<li>When offering less than the maximum number of parameters, the unused parameters must be the highest numbered
</ul>

<p><h3>Interface</h3><br>
The plug-ins are stored in the directory <i>!StudioSnd.SoftDSP</i>. Each plug-in is stored as a Data file with a 32 words header:<br>
<pre>
        Word    Meaning
        0       Flags
        1       Offset to effects title (max 15 chars)
        2       Offset to start code
        3       Offset to kill code
        4       Offset to parameter1 definition or 0
        5       Offset to parameter2 definition or 0
        6       Offset to parameter3 definition or 0
        7       Offset to parameter1 code or 0
        8       Offset to parameter2 code or 0
        9       Offset to parameter3 code or 0
        10      Offset to prepare code
        11      Offset to create code
        12      Offset to helpful Drawfile or 0
        13      Size of helpful Drawfile or 0
        14      Offset to copyright string
        15      Offset to date/version string (eg. '0.00 (01-Jan-1997)')
        16      Offset to helpstring or 0
        17      0
        18 - 31 Reserved
</pre>
StudioSound might change the contents of the header after having loaded the effect.<br>

<p><h4>Flags</h4>
<pre>
Bit 0 - 7       effect type - allocated by Oregan
                0       Highpass
                1       Lowpass
                2       BassBoost
                3       TrebleBoost
                4       Vibrato
                5       Rumble
                6       AutoPan
                8       NoiseGate
                9       Clipping
                10      Reverb
                11      Echo
                16-19   Used by Are Leisteds parametric eq
</pre>

<p><h4>Effect title</h4>
This is the title of the effect, max 20 chars 0-terminated.

<p><h4>Start code</h4>
This is called when StudioSound has loaded the effect.

<pre>
On entry
        -
On exit
        R0  =   0 (initialised OK)
    or  R0  =&gt;  Error block
</pre>

<p><h4>Kill code</h4>
This is called when StudioSound removes the effect from the RMA.

<p><h4>Parameter definition</h4>
The parameter definitions use 7 words each:

<pre>
        Word   Meaning
        0      Default value (0-1023)
        1      Minimum allowed value (0-1023)
        2      Maximum allowed value (0-1023)
        3      Unit string, 0 - 4 chars, padded with 0s to fill
               all 4 bytes
        4 - 6  Parameter name, max 11 chars, 0-terminated
        7      Offset (from start of parameter definition) to
               help string or 0
</pre>

The values are NOT in the specified unit, but should be considered indices into a large table of allowed values; the values are converted to text by the parameter code.<br>

Example of a typical high-pass filter:
<pre>
        Word
        0      Default value = 12
        1      Minimum value = 0
        2      Maximum value = 72
        3      Unit string 'Hz&lt;&amp;00&gt;&lt;&amp;00&gt;'
        4      Parameter name 'Frequency'
        7      Help string offset (eg. 'Frequenices will be
               attenuated by 6dB for each octave they are below
               the cut-frequency')
</pre>
The parameter code will convert the current value (in the range 0-72) to a string specifying the frequency; value=0 is returned as '50', value=72 is converted to '3200' (72 seminotes=6 octaves) and thus the default value is '100'.<br>


<p><h4>Parameter code</h4>
The parameter code is called to convert a value to a string; it is called when the user alters a parameter and when loading a project which uses this plug-in.

<pre>
On entry
        R0  =   Value (in the range specified in the parameter definition)
        R1  =&gt;  Parameter block, one word for each parameter
        R2  =   Project frequency

On exit
        R0  =&gt;  String (max 11-&lt;unitstringlength&gt; chars, 0-terminated)
    or  R0  =   0 (value is not allowed)
</pre>
StudioSound will read the string and append the unitstring to it - the length of the resulting string can be no longer than 11 chars.<br>


<p><h4>Prepare code</h4>
The prepare code is called to read the amount of memory needed for the code:
<pre>
On entry
        R0  =&gt;  Parameter block, one word for each parameter
        R2  =   Project frequency

On exit
        R0  =   Size of effect code
</pre>

<p><h4>Create code</h4>
The create code is called to assemble the effect:
<pre>
On entry
        R0  =&gt;  Parameter block
        R1  =&gt;  Block in RMA to assemble code in
        R2  =   Project frequency
        R3  =&gt;  Sinetable (8192 values of SIN(0) - SIN(2*PI), each
                entry uses 16 bits and holds 16384*SIN(value))
</pre>

When the effect code is called, the registers are setup like this:
<pre>
On entry
        R0  =   Index (in the project) of first sample in the buffer
        R1  =&gt;  Start of sample buffer
        R2  =   Size of sample buffer (samples)
        R3  =   Index (in buffer) of first sample to apply the effect
                to (inclusive)
        R4  =   Index (in buffer) of last sample to apply the effect
                to (exclusive)
        R5  =   Flags
                Bit 0 set =&gt; the samples from R3 to R4 contain silence
                Bit 1 set =&gt; the rest of the buffer contains silence
                Bit 2 set =&gt; left=right for the samples from R3 to R4
                Bit 3 set =&gt; left=right for the rest of the samples
        R13 =&gt;  User mode stack
        R14 =   Return address

On exit
        R0  =   Clipping flags
                Bit 0 set =&gt; clipping on left channel
                Bit 1 set =&gt; clipping on right channel
                Bit 2 set =&gt; no samples affected at all
                Bit 3 set =&gt; samples are still mono
        R1 - R12 must be preserved
</pre>

The effect should use the flags in R5 whenever possible - eg. most effects will return immediately if bit 0 and 1 both are set.<br>
The buffer in R1 is a circular buffer which holds at least an extra 0.5 second of samples before the first sample.<br>

The following pseudo-code should be used when applying the effect:
<pre>
 current=first
 while current&lt;&gt;last
   /* apply effect here */
   buffer(current)=processedvalue        /* write value */
   current+=1                            /* next sample */
   if current=size then current=0        /* wrap */
 endwhile

 /* to read a value from the buffer */
 readsample(buffer,size,which)
   if which&lt;0 then which+=size
   =buffer(which)
</pre>

The effect is allowed to read any sample from the buffer, up to 0.5 seconds before the first sample it is applied to, eg:
<pre>
 current=first
 reverbdelay=0.4                         /* delay in seconds */
 while current&lt;&gt;last
   this=readsample(buffer,size,current)
   delay=readsample(buffer,size,current-reverbdelay*frequency)
   processedvalue=0.8*this+0.2*delay     /* simple reverb */
   buffer(current)=processedvalue        /* write value */
   current+=1                            /* next sample */
   if current=size then sample=0         /* wrap */
 endwhile
</pre>

<p><h4>Helpful Drawfile</h4>
The helpful Drawfile is optional. It should be approx. 800x600 OS units but any size is possible.<br>
The Drawfile is currently ignored.<br>


<p><h4>Copyright string</h4>
This is a 0-terminated string, max 32 chars.<br>


<p><h4>Date/version string</h4>
This is a 0-terminated string in the usual Acorn version number format - eg. '1.00 (01-Jan-1997)'<br>


<p><h4>Help string</h4>
This is a 0-terminated string, max 200 chars. It is passed to !Help if StudioSound supports interactive help.<br>


<p><h4>Save choices</h4>
This is called when the user saves the choices in StudioSound.<br>
<pre>
On entry
        R0  =&gt;  Buffer (1024 bytes)

On exit
        R0  =   Number of bytes written to the buffer
</pre>
StudioSound will handle the writing to the choices file.<br>


<p><h4>Load choices</h4>
When the choices file is loaded and if it contains data which was saved by this DSP effect, this code is called.<br>
<pre>
 On entry
        R0  =&gt;  Buffer holding the saved choices
        R1  =   Number of bytes in the buffer
</pre>

</html>
