<html>
<body>
<p>
<h2>ProSound Sampledriver Interface</h2>
The ProSound sampledriver interface is provided by ProSound to allow a consistent user-interface to the sampledrivers.<br>

The sampledrivers themselves are fxs which (during initialising) install themselves as sampledrivers by calling the ProSound_SampleDriver code.<br>

The interface allows recording of 1-4 channels simultaneously; the sampledriver interface maps ProSound-tracks to sampledriver-channels.<br>

Playback of a single track is possible at the same time as recording (to one or more tracks) takes place. Playback and sampling are syncronised to approx. 1-2 cs.<br>

<p>
<h4>How it works</h4>
The sampledriver must provide 3 routines (init, kill and poll) which are used by the sampledriver interface to communicate with the sampledriver.<br>

The init code is called to start sampling. This should return immediately after sampling has been started.<br>

The kill code is called when sampling has ended.<br>

The poll code is called to read sample data. Internally, the sampledriver should use double-buffering of the sampledata. The poll code returns a pointer to a list of pointers to the buffers holding the sample-data - one buffer for each channel. If a buffer pointer is 0, it is ignored, otherwise the samples are written to the appropriate track.<br>
The sampledriver will usually just sample from all channels, and leave it to the interface to ignore the unused channels, eg. ProSound (or the user) may want to use a stereo sampledriver to sample to a single-track project.

<p>
<h4>Installing a driver</h4>
The sampledriver is usually installed when the fx is initialised:<br>
The fx checks to see if the necessary hardware/modules/etc are present in the computer, loads whatever modules it needs and finally calls the internal routine ProSound_SampleDriver with R1 pointing to a SDB (sampledriver block).<br>

If the driver cannot initialise (a module is missing or the samplerboard is missing or something like that) the fx may choose not to install the driver (by not calling ProSound_SampleDriver) or it may still install the driver, but set bit 3 (disabled) in the sampledriver flag word (at offset 12 in the SDB).<br>
Please notice that ProSound v1.03i and earlier ignores the disabled bit and so may call the drivers init code even though it's disabled. The driver should respond by returning with R0 &lt&gt 0. You may however assume that noone is using v1.03 anymore...

<p>
<h4>ProSound_SampleDriver</h4>
This code installs a sampledriver.

<pre>
On entry
                R0  =   0 (install)
                R1  =>  SDB (sampledriver block)
                        +0      Offset to init code
                        +4      Offset to kill code
                        +8      Offset to poll code
                        +12     Flags
                                Bit 0-1    =>  <number of channels>-1
                                Bit 2 set  =>  don't allow playback       (1)
                                Bit 3 set  =>  disabled
                                Bit 6 set  =>  can only sample to RAM;
                                Bit 16 set =>  cannot sample multitasking (1)
                                Bit 17 set =>  cannot rehearse            (1)
                                Bit 18 set =>  supports driver-setup      (2)
                                All other bits must be clear
                        +16     Offset to name (max. 30 chars)

                        (ProSound_SampleDriver changes all offsets to
                        pointers)
 On exit
                R0  =   0 (installed OK) or &lt&gt 0 (not installed)
</pre>

(1) bits marked with (1) are ignored and assumed set when sampling to RAM.<br>
(2) if bit 18 is set, the 'Driver...' icon in the Record window will be un-shaded. When the user clicks on this icon, the sampledriver should open a window allowing the user to specify things like input, gain etc.


<h4>Sampledriver block</h4>

<pre>
 Word 0         Init code.
                This is called to initialise the sampledriver. The driver
                should initialise the hardware, claim memory etc.
                On entry
                        R0  =>  List of tracks (when sampling to tracks)
                                +0      Track to use for channel#1
                                +4      Track to use for channel#2 or 0
                                +8      Track to use for channel#3 or 0
                                +12     Track to use for channel#4 or 0
                    or  R0  =>  List of buffers (when sampling to RAM)
                                +0      Pointer to buffer for channel#1
                                +4      Pointer to buffer for channel#2 or 0
                        R1  =   Frequency
                        R2  =>  SDB
                        R3  =   Flags
                                Bit 0 set => rehearsing (see Notes)
                                Bit 1 set => playing track simultaneously
                                Bit 2 set => multitasking
                                Bit 3 set => computer is quite fast (RiscPC)
                        R4  =   Buffer size (samples) when sampling to RAM

                On exit
                        R0  =   0 (OK) or &lt&gt 0 (abort)

                If any of the track pointers are 0, that track will not be
                used and thus the sampledriver need not sample from that
                channel.
                The channel count indicates how many channels to sample
                from (1-<number of channels>).


 Word 1         Kill code.
                This is called when the poll code has been called for the
                last time. The driver should release memory etc.
                On entry
                        -

                On exit
                        -


 Word 2         Poll code.
                This is called as often as possible. The driver should
                check if there are any samples to write, and resample
                these to the track-frequency if necessary.
                On entry
                        R0  =>  List of tracks (when sampling to tracks)
                                +0      Track to use for channel#1
                                +4      Track to use for channel#2 or 0
                                +8      Track to use for channel#3 or 0
                                +12     Track to use for channel#4 or 0
                    or  R0  =>  List of buffers (when sampling to RAM)
                                +0      Pointer to buffer for channel#1
                                +4      Pointer to buffer for channel#2 or 0
                        R1  =   Frequency
                        R2  =   Sample position on track
                        R4  =   Buffer size (samples) when sampling to RAM

                On exit
                        R0  =>  List of pointer to samplebuffers or 0
                                +0      Pointer to buffer for channel#1
                                +4      Pointer to buffer for channel#2
                                +8      Pointer to buffer for channel#3
                                +12     Pointer to buffer for channel#4
                        R1  =   Number of samples in each buffer (can be 0)

                Any of the bufferpointers may be 0.
                The channel count indicates how many channels to sample
                from (1-<number of channels>).

 Word 3         Flags.

 Word 4         Offset to sampledriver name.
</pre>


<h4>Sampling to RAM</h4>
If bit 6 of the flag word is set, the sampledriver can only sample to RAM, ie. no discactivity is possible at the same time. In this case, R0 on entry to the init code will hold a pointer to a list of buffers, and R4 will hold the size of the buffers. The init code should initialise the hardware and start sampling and return when the buffers are full. ProSound will then write the samples to the tracks.<br>
The poll code will never be called.<br>
Recording to more than 2 tracks is not supported.


<p>
<h4>Notes</h4>

<h6>Rehearsing</h6>
When bit 0 of the flags is set on entry to the init code, the user is rehearsing. To improve the VU-meter-display, the sample buffer should be much smaller when rehearsing than when recording. A sample buffer size of 0.05-0.2 seconds is recommended. If a track is played simultaneously or if rehearsing is multitasking, slower machines may not be able to handle very small buffer sizes.<br>

 The Eagle sampledrivers use this formula to select a buffersize for rehearsing:
<pre>
        buffersize = 6 cs
        if playing       then buffersize += 2 cs
        if multitasking  then buffersize += 2 cs
        if slow-computer then buffersize += 4 cs
</pre>

<h6>Allocating buffers</h6>
Usually a sampledriver will use two sets of buffers:<br>
One set is filled under interrupt by the sampler code. These buffers should be allocated from the RMA or from a dynamic area. When one of these buffers is full, the samples are copied (and possibly converted to 16 bit and resampled in the process) to the second set of buffers which are then passed to ProSound and from there written to the tracks. The second set of buffers may be allocated from the heap (using the call Heap_AllocateBlock).


<h6>VU meters</h6>
The VU meters are updated whenever the sampledrivers poll code returns sampled data to the sampledriver interface. However, if the sampledriver have access to the samples at regular intervals between passing the samples to the interface, it may want to call ProSound_Monitor,1 more often to provide a smoother updated display.
</body>
</html>