tspksvdc.obj, tspksvdl.obj function summary:
============================================

This list contains UNIX-like summaries for the routines that
are currently contained in tspksvdc.obj and tspksvdl.obj.


To use tspksvd?.obj (tspksvd = Tale SPeaKer Sampled Voice
Driver) the following items are required:

- IBM compatible PC/XT/AT with 80188 CPU or above
- a pc speaker of good quality (diameter >= 10 cm,
  mid-frequency band, linear frequency characteristic
  400 - 15000 Hz)


Depending on the memory model of your application choose
between tspksvdc.obj and tspksvdl.obj:

tspksvdc.obj is assembled for the COMPACT memory model.
This means that all calls to procedures must be declared as
NEAR while pointers to data are all FAR.

tspksvdl.obj is assembled for the LARGE memory model.
This means that all calls to procedures and pointers to data
must be declared as FAR.


tspksvd?.obj expects all parameters to be passed using C
calling conventions. The C calling mechanism looks like this:
When calling a routine, C takes the parameters for the
routine and pushes them onto the stack. For example:
x=routine(parmA,parmB);
Then it calls a routine named "_routine" (adds an underscore
to the head of the routine name).
The code at _routine saves the contents of the registers the
routine will use (except ax) and will execute the requested
function. After execution _routine restores the contents of
the registers (except ax) and passes back control to the
caller. Finally, the caller has to clean up the stack by
pulling the previously pushed parameters (in this case: parmA,
parmB) from it.

The ax register is never saved because sometimes it contains
a result (x in the example). To be more precise:
If the result is 8 bits wide, al will contain it.
If the result is 16 bits wide, ax will contain it.
If the result is 32 bits wide (e.g. a pointer), ax will contain
the lower 16 bits and dx the higher 16 bits.

This is what the C compiler does with our example (assuming
x, parmA, parmB are all 16 bits wide):
	...
	push parmB	;push parameters (Note: since C is a
	push parmA	;right-pusher it pushes parameters
			;from right to left)
	call _routine	;call _routine
	add sp,4	;take parameters from stack
	mov x,ax	;store result in x
	...


byte playspksv(ubyte rshift,byte offset,uword freq,udword len,ubyte far *wave);
play a sampled voice

FUNCTION:
Plays a sampled voice through the PC speaker. The voice is
expected to be made out of 8bit samples - each sample
occupying a byte of course.

playspksv() doesn't wait until the sampled voice is played
completly but returns control to the caller instantly. To wait
for a SV output to be finished use waitspksv().

playspksv() uses INT 08h to play the sampled voice. That means
that all system functions related to INT 08h are suspended
while the SV is playing. Especially the system clock is
stopped while a SV output is active. However if you have an AT
type PC the system time will be restored from your real time
clock after the voice output has finished.

INPUTS:
rshift: scale factor: 0 equals 100%   (no SV scaling)
		      1 equals  50%   (1-(1/2^1))*100
		      2 equals  75%   (1-(1/2^2))*100
		      3 equals  87,5% (1-(1/2^3))*100
		      ...
	Valid values for the scale factor range from 0-7.
	Use of the scale factor: The higher the playback
	frequency the lower the resolution of the samples
	have to be so that the voice output sounds natural.
	If the playback frequency is 4679Hz no scaling is
	needed (scale factor: 0 / 8bit sample resolution).
	For a frequency of 9395Hz the samples should be
	scaled down to 50% (scale factor: 1 / 4bit sample
	resolution). However if the samples are scaled to 50%
	their volume is only half of the original volume. Most
	often this is not desired. Therefore let's say you
	scale the sample values for 9395Hz to 75% (scale
	factor 2 / 6bit sample resolution) and use an offset
	(see below).
offset: sample offset correction. If the playback rate of a
	8bit sample is > 4679Hz it can't be replayed
	correctly via the PC speaker. To circumvent this
	problem an offset value can be used. The offset moves
	the value of each sample in a way that a 8bit sample
	replay up to 9394Hz sounds almost natural (for a PC
	speaker of course). The (signed!) offset value is for
	a higher frequency lower and for a lower frequency
	higher. Experiment! For higher frequencies (> 9395Hz)
	scale the samples down (using the rshift parameter)
	and use the offset in the same way I described it for
	the frequency band 4679Hz - 9394Hz.
freq: replay frequency. The replay frequency may range from
      4679Hz - 22050Hz.
len: length of sampled voice. You can play sampled voices
     having a length from 1 byte to 1,048,576 bytes. However
     please note that conventional DOS memory is limited to
     640KB.
*wave: pointer to sampled voice.

RESULT:
byte success: TRUE if everything is o.k.
	      FALSE if an error has occured (invalid
	      parameters passed to the procedure or a sampled
	      voice is still playing).

BUGS:
This procedure suspends system functions related to INT 08h
while a SV is playing.

SEE ALSO:
abortspksv(), queryspksv(), waitspksv()


byte resumespksv(void);
continue SV output

FUNCTION:
If output of a sampled voice was interrupted by using
abortspksv() it is possible to resume the SV output from where
it was stopped by calling this routine.

INPUTS:
none

RESULT:
byte success: TRUE if everything is o.k.
	      FALSE if the SV was not interrupted or the SV
	      was played completly.

BUGS:
none known

SEE ALSO:
abortspksv()


byte queryspksv(void);
check if a SV is currently playing.

FUNCTION:
This procedure checks if a sampled voice output is currently
active.

INPUTS:
none

RESULT:
byte svisplaying: FALSE if no sampled voice is currently
		  playing.
		  TRUE if a sampled voice is currently playing.

BUGS:
none known

SEE ALSO:
waitspksv()


void waitspksv(void);
wait until a SV output is completed

FUNCTION:
This function is used to wait until a sampled voice was played
completly. It returns to the caller after the SV output has
ended. If no SV is playing it returns to the caller instantly.
You can emulate the function of waitspksv() using this C code:
while (queryspksv());

INPUTS:
none

RESULT:
none

BUGS:
none known

SEE ALSO:
queryspksv()


byte abortspksv(void);
abort SV output

FUNCTION:
SV output can be aborted instantly using this function. It
is possible to resume SV output once it was aborted using
resumespksv().

INPUTS:
none

RESULT:
byte success: TRUE if SV was aborted successfully,
	      FALSE if not (no SV was currently playing).

BUGS:
none known

SEE ALSO:
playspksv(), resumespksv()