SBDOS v1.0 Distribution
-------------------------

Michael Fulbright (msf@skaro.as.arizona.edu)


INTRO
-----

This distribution is derived from Steve Haehnichen's Sblast-BSD-1.4
package for 386 UN*Xes to drive the Creative Labs(tm) Sound Blaster
Pro(tm) (SBPro) card.  It should also work with the regular model as
well (see APPENDIX 1).  I have converted the Sblast-BSD code into a set
of linkable subroutines callable from MSC 5.1.  I believe it should be
fairly straightfoward to make this package work with other MSDOS
compilers.  I will discuss this point below in the section OTHER
COMPILERS.

Be sure to read the other documentation files included, these are
the original files that came with SBlast-BSD v1.4.

THIS CODE IS EXPERIENTAL - YOU ARE FREE TO DO WITH IT WHAT YOU WILL BUT
I CAN NOT BE HELP RESPONSIBLE FOR DAMAGES/ETC.

REQUIREMENTS
------------

To fully utilize this package a SBPro is required, however, the SB is
also supported.  This package supports recording and playing back
samples with both cards.  The highest rate available with the SB,
however, is around 22khz, while with the SBPro is approximately 44khz.
Also, the mixer functions will only work if you have a SBPro, as the SB
has no on-board mixer.  If you own a SB I believe you will also have to
have a DSP v2.0 or higher, although I dont have an earlier board so I
havent tested it.

I am currently stuck using MSC 5.1 in the LARGE model, so if you have a
later compiler from Microsoft then these routines should work out of the
box if your compiler is backwards compatable.  I think the Borland
compilers should work as well, although I think some changes will be
required.  If someone has a Borland compiler and gets this working
please let me know what changes were required. I havent tried to get
these routines to work in any memory model other than LARGE, so I dont
make any guarantees about other memory models.


FILES
-----

The following source files should be in this distribution:

SB_DRIVE.C - Main driver, contains all callable routines
RECORDER.C - Example file, records from the Mic input
PLAYER.C   - Example file, plays raw or .VOC files
RAW2VOC.C  - Stick a .VOC header on a raw sound file
GETOPT.C   - GNU option parser, needed for RECORDER.C and PLAYER.C

SBLAST.H   - These two files contain constants and struct definitions
SB_REGS.H  -    needed for calling SB_DRIVE routines.
GETOPT.H   - Not needed, but should be distributed with GETOPT.C

Also you should have the following documents:

COPYING    - GNU policy, needed for GETOPT.* files
INSTALL    - Original docs for Sblast-BSD v1.4 distribution
README     -    "       "
README.2   - This file
VOCFILE.TXT - Info on the .VOC file format

And a sample sound file

SAMPLE.VOC - nice test sound


GETTING STARTED
---------------

I havent created a Makefile for the test programs since everything
is small and people use so many different make utilities.

First you need to look in SB_REGS.H and near the top set the #define
SB_DMA_CHAN to whatever your card is set to.  The factory default is 1.

Next edit both recorder.c and player.c. Look for two lines which are
something like

dev.addr = 0x220;
dev.irq  = 7;

Change these two lines to whatever your card is setup for.  The factory
defaults are 0x220 and 7.  The file INSTALL contains some useful
information about the setup of your card.  If you arent sure how yor
card is setup then one thing is too check your environment for the
variable BLASTER.  You can check this by going into DOS and typing

SET

Look for the variable BLASTER which should look something like

BLASTER=A220 I7 D1 T2

which means my card uses address 0x220, irq 7 and DMA channel 1.

For those of you with Sound Blasters (not Pros) see Appendix 1 before
proceeding.

If you still dont know how your card is setup I wouldnt go any farther
till you find out.


COMPILING THE TEST PROGRAMS
---------------------------

BE SURE YOU'VE READ THE SECTION "GETTING STARTED" FIRST!

Once you've made the changes given above, you can try out the example
programs. If your compiler is MSC 5.1 or compat, then do the following
to compile

cl /AL /Ox player.c getopt.c sb_drive.c

If all goes well then compile the second program

cl /AL /Ox recorder.c getopt sb_drive

(Note - since we've already compiled getopt and sb_drive no need to
	do it again.)

First I would test the 'player' program first. Try the following command

player sample.voc

If you dont hear anything check that your card is setup ok (volume up,
speaker connected, ect). If that doesnt help then contact me.

If that works then now you can try recording with the program 'recorder'.
Try the following (make sure your microphone is connected):

record a.voc

The program will prompt you to hit return to start recording, and will
stop recording when you press a key.  To play back what you just
recorded try

player a.voc.

Look at the source code for both programs, there are many options
controlling the data rate and volume.  Stereo output doesnt seem to work
for me, if someone knows how to record/playback in stereo I would like
to know how!

Also included is raw2voc.c, which shows how to create a .VOC header.


WRITING YOUR OWN PROGRAMS
-------------------------

Look at the two sample programs for ideas.  Read through the SB_DRIVE.C
code as well as the two include files SB_REGS.H and SBLAST.H.  There is
a wealth of information there, and its how I learned what I know about
programming the SB.  Let me add a few comments.

The first thing to do when writing a program is to call sb_probe() to
see if a card exists.  If there is a card then call sb_attach() to set
things up.  You should make sure sb_unattach() is called when your
program exits.  I have done that with MSC by using the atexit() function
to ensure sb_unattach() is run whenever the program exits.  This
function is supposed to be ANSI compatable, so most compilers should
support it, but check your docs.

The sampling parameters are controlled by calls to functions starting
with dsp_.  For example, dsp_set_speed sets the sampling/playback rate.
Read through the SB_DRIVE.C program to get a feeling for the commands
available.  In addition, for those with a SB Pro the mixer_* routines
control the onboard mixer, allowing one to enable/disable filters,
increase/decrease the volume levels of all inputs and outputs
independently, and other neat stuff.  These functions WILL NOT work with
a regular Sound Blaster.

I hope to have some more programs using these routines out soon.  I
think if you spend some time reading the source you can figure it out,
and then you can change it to how you would have done it if it so
strikes you.  I'm releasing this code under the same arrangement as the
original author.  I would like to hear about any changes you make or
problems you have making it work.



OTHER COMPILERS
---------------

I'm not familiar with other compilers, but I think I can anticipate some
potential problems.

1) sb_intr: In SB_DRIVE.C there is a routine called sb_intr.  This
	    function services the interupt which occurs when a dma
	    function is completed.  Make sure the function declaration
	    is correct for your compiler, as your compiler must know to
	    do some special things since this is an interupt handler.

2) init_timers:  This routine figures out how many loops/sec your machine
		 can do. Its used for various timing applications in the
		 code. The routine _bios_timeofday() returns the #
		 of timer ticks since midnight, where there are 18.3 ticks
		 a second. Your compiler may have a different way to
		 call this BIOS service.

3) Pointers: I assume that far pointers are stored in a segment:offset
	     format in unsigned longs.  Your compiler may do this
	     differently (I cant see why, but..) so make sure this is
	     how yours does it.  The function find_dma_buffers() in
	     particular will die on this.


APPENDIX 1 - Regular Sound Blaster Owners
-----------------------------------------

These routines assume a SBPro is installed. You can use these
routines, however, as long as no calls are made to the mixer_* functions.
Also, you must not run things in HIGH SPEED MODE. I think a change
will be required in dsp_open() to remove a reference to dsp_set_stereo(),
which wont work on SB. If someone does get these routines to
work with a SB please let me know what changes you made.


----------------------------------------------------------------------------

You can reach me at msf@skaro.as.arizona.edu with questions and comments.
I am always interested in more information about the SB or Pro.
If anyone wants to use the FM or MIDI functions which appear in the
original Sblast-BSD v1.4, I dont think the conversion would be difficult.
I you see what I did for the DSP functions then I think it would be
straightforward to convert the FM/MIDI routines as well. Let me know if you
want help. I didnt convert that code because I really wasnt sure what to
do with them.  Also, in the future I would like to try to get some
routines working under the DJGPP compiler, so if anyone knows anything
about that please forward the info to me.

ENJOY!
Michael Fulbright
msf@skaro.as.arizona.edu
