How to use SAMPLE.H
                           -------------------

        Sample.H provides some functions for sample playing. This file
        explains how to use the header file in your own programs.

        The routines are compiled with TC 2.0 and they will work with
        other Borland compilers without changes. I'm not sure if they will
        work with MS C, Quick C or Lattice C, but it's worth trying.

        Anyway, the header file is included the following way:

        #include <sample.h>

        You must place the sample.h in your normal header file directory.
        (For example C:\tc\include)

        Functions:
        ----------

        s_load("name.smp");             Loads a sample called 'name.smp'.
                                        If there's not enough memory or
                                        if the sample is missing, returns
                                        S_ERROR. Otherwise returns S_OK.

        s_init(x,y);                    Initializes the sound device x at
                                        address y. Use DAC, SB, PIIP (PC
                                        speaker) or DEFAULT as the device
                                        name. Y is the port address of the
                                        sound device. Possible values for
                                        DAC are 0x278, 0x378, 0x3bc and
                                        constant values LPT1, LPT2, LPT3
                                        and LPT4. The function will find
                                        the LPT addresses itself. The same
                                        effect can be achieved by using
                                        the get_lpt(x) function. Sound
                                        Blaster can be located in port
                                        addresses from 0x220 to 0x260.
                                        DEFAULT value is 0x220. PC speaker
                                        has only one possible address, so
                                        with it use DEFAULT as y argument.
                                        If initialization was succesful,
                                        returns S_OK, otherwise S_ERROR.

        s_play(x);                      Starts sample playing. The speed
                                        (In cycles per second) is specified in
                                        argument x. It can be up to 65535 Hz.
                                        The DEFAULT value is 8 kHz (The same
                                        as DEFR). WARNING: Over 16 kHz sampling
                                        rates may sound a bit odd with PC
                                        speaker ;v>

        s_stop();                       Stops sample playing. This function
                                        doesn't reset the sound device, so
                                        the output can be started again with
                                        s_play. Restores timer speed and
                                        sets its time right.

        s_clear();                      Closes the sound device and frees
                                        allocated memory blocks. After calling
                                        this function you shouldn't try to
                                        play the sample again.

        The constants are explained in the header file. The following functions
        may be useful but it's not necessary to use them because samples can
        be loaded, played & cleared with the functions above.

        settimer(x);                    Sets the internal clock speed to x.

        resettimer();                   Resets the clock speed to normal.

        resetSB(x);                     Resets Sound Blaster at 0x220...0x260.

        get_lpt(x);                     Returns LPTx's port number.

        bcd2d(x);                       Converts BCD-numbers to decimal.

        Of course it's easiest just to look at example.c!

        Tips:
        -----

        1. Keyword DEFAULT can be used instead of all numeric values.
        For example:

        s_init(DEFAULT,DEFAULT);
        s_play(DEFAULT);

        Initializes PC speaker and plays sample at 8 kHz.

        2. You can detect SB by trying all of its possible port addresses
        and checking whether it returns S_ERROR or S_OK:

        address=-1;
        for(n=0x220;n<0x270;n+=0x10)
                if(s_init(SB,n)==S_OK)
                        address=n;

        If SB was found, the variable 'address' differs from -1.

        3. Current sample byte can be found at address s_current[s_cnt];
        It's VERY easy to code a simple scope by using this byte. You could
        also define the following:
        #define SBYTE s_current[s_cnt]
        This way you could always find the current sample byte with label
        SBYTE.

        Thanks to following guys:
        -------------------------

        Yzi             -       For lending SBDK & other stuff
        Pete/Fit        -       For BCD-things and realtime-clock routine

                          -= 25th Sep 1993 Marq/Fit =-