

                          
                      
                            
                             
                                 
                        
                         

                               Version 1.1

 A user-friendly MIDI playing Library, based upon QMIDI v4.1 by Jesse Dorland

                       Designed for QuickBasic 4.5

                          Programmed By IceWolf

   Project Began: 27th December 2000       v1.1 Finished: 6th January 2001
    


==============================================================================
  What Is MIDILib?
==============================================================================
  MIDI Library is a QB 4.5 Library which can play standard MIDI files using
the SBMIDI driver.
    It is designed for Microsoft QuickBasic 4.5, but I expect it will also
work with PDS (if the libraries are rebuilt) or most other languages (via the
OBJ file(.
  I created it because I was unhappy with QMIDI 4.1, as you had to allocate
a handle even if you only wanted to load one MIDI at a time (which is almost
always), and the error checking wasn't brilliant (eg, call UnloadMIDI while a
song was still playing and it'd continue, even though the memory had been
released).
  This library didn't take long to write, but is difficult to crash and easy
to use. It also will not require too much rewriting of code to convert a file
which uses QMIDI to use MIDILib.



==============================================================================
  Why use this instead of QMIDI?
==============================================================================
  This library was created with one purpose - to make a more 'friendly'
version of QMIDI. With QMIDI, omitting error checks in your program can cause 
some annoying problems, and as a programmer you would have to write a lots
more code. The MIDILib library already contains error checking code and is a
lot more stable than QMIDI, and is difficult, to crash (in fact, the only way
I know of is to try to load a file from an unready drive). The only time an
error check is necessary is after calling DetectDrivers, DetectSettings or
LoadMIDI, but even if you don't and an error occurs, the program will still
function, but probably without any music. Also, errors do not (usually) halt
execution, as they often do in QB.



==============================================================================
  Known Bugs, Problems and Limitations
==============================================================================
   It will only load MIDI files into Base Memory. This is because if the
    library is used in conjunction with other libraries which use EMS, the
    MIDI EMS page would need to remain mapped or it would crash (I assume?
    If I'm wrong, please let me know and I will include EMS support).
   Only one MIDI file can be loaded at a time. This is because it's not
    really necessary as MIDI's don't take long to load, and because Base
    Memory is being used, loading more than one MIDI would seriously reduce
    the memory available to the program.
   Some MIDI files sound different than they do in Windows - this is not
    my fault, but because the SBMIDI driver uses its own instrument set, and
    these sometimes differ slightly. Blame Creative Labs.
   Changing the volume on older sound cards is not supported (mostly because
    I doubt anyone has such an old card, and I couldn't be bothered to write
    the code if no-one's going to use it). If anyone has an older sound card,
    send me an e-mail and I will add support for you.
   Trying to load a file from a drive that isn't ready (such as a floppy
    drive that has no disk in) causes the computer to hang up. This is caused
    by the DOS interrupt 21h, function 4E. I'm currently unsure as to how to
    use DOS functions to check whether a drive is ready, so if anyone knows
    how, please send me an e-mail (please don't say 'use ON ERROR GOSUB ...
    as I'm trying to avoid using this).


==============================================================================
   What's new in Version 1.1?
==============================================================================
    
   A lot of bugs with Sound Blaster Pro/Pro 2 sound cards have been fixed,
    especially as I forgot to write the SetVolume routine for these cards!
    (I have an SB16, so I forgot a lot of the testing on these).

   Some redundant code has been removed.

   Re-wrote the code which checks whether the MIDI the user attempts to load
    actually exists, so it doesn't cause a QB error if the path or drive is
    invalid.
  
   Some extra error messages have been added, one warning if DetectSettings
    has not been called, another warning if the user tries to use an invalid
    path or drive, and another that 

   Added an extra function to tell you the filename of the MIDI that is in
    memory, and another to return the current library version.

   SetVolume and GetVolume now check the parameters to see if they're out of
    range. The volume parameter also gets fixed if it goes out of range, so
    you can just read the volume and increase it without using a check in
    your program to check it hasn't gone over the maximum volume allowed.



==============================================================================
Explanation Of SUB's and FUNCTION's
==============================================================================

    DECLARE SUB DetectSettings ()

    Detects the settings of the sound card by reading the contents of the
    BLASTER environment variable. In a future version, I'll edit this sub so
    it will detect the card even if the BLASTER variable isn't set.

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

    DECLARE SUB DetectDrivers ()

    Detects which IRQ the SBMIDI and SBSIM drivers are loaded into.

------------------------------------------------------------------------------
    
    DECLARE SUB LoopMIDI ()

    Determines whether a MIDI has reached the end, and if so loops it back to
    the beginning.

------------------------------------------------------------------------------
    
    DECLARE SUB LoadMIDI (Filename$)
    
    Loads a MIDI into memory. It will load a MIDI file of just about any size
    as long there is enough free base memory to hold it.

    Filename$ is the filename of the MIDI to load.

------------------------------------------------------------------------------
    
    DECLARE SUB PlayMIDI ()

    Begins playing the loaded MIDI file.

------------------------------------------------------------------------------
    
    DECLARE SUB ReverseStereo (Switch%)

    Reverses the output to the left and right stereo channels.
    
    A Switch% value of 0 sets them to normal, whereas a value of one reverses
    them.

------------------------------------------------------------------------------
    
    DECLARE SUB SetVolume (Which%, Vol%, Mode%)

    Changes the volume of a particular channel.

    Which% determines which channel to change. See below for more info.
    Vol% is the new volume level.
    Mode% determines whether the Vol% is to be treated as a true value, a
    value between 0 and 31, or a value between 0 and 15. See below for more
    information.

------------------------------------------------------------------------------
    
    DECLARE SUB StopMIDI ()

    Stops the MIDI which is playing.

------------------------------------------------------------------------------
    
    DECLARE SUB UnloadMIDI ()

    Frees the memory used by the MIDI, and also calls StopMIDI if it's still
    playing.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION CurrentMIDI$ (Switch%)

    Returns the filename of the MIDI file that's been loaded into memory.

    If Switch% is 0, it returns the exact filename as was used when calling
    LoadMIDI, any other value causes it to return the filename in DOS 8:3
    format (eg. "FBATTLE.MID" rather than "C:\QB45\FBATTLE.MID"), though if
    the filename or extension are less than 8 or 3 characters, they're not
    padded out with spaces (eg. "ABCD.EF" doesn't become "ABCD    .ED ").

------------------------------------------------------------------------------
    
    DECLARE FUNCTION GetVolume% (Which%, Mode%)

    Returns the current volume of a particular channel.

    See below for explanations of Which% and Mode%.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION MIDIError$ ()

    Returns a string describing the error that occured in the most recently
    called routine. See below for a list.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION MIDIErrorOccured% ()

    Returns the number of the error that occured, or 0 if there was no error.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION MIDITime! ()

    Returns how long the MIDI has been playing, in seconds.

-----------------------------------------------------------------------------
    
    DECLARE FUNCTION MusicDone ()

    Returns TRUE (-1) if the music has reached the end, FALSE (0) if it's
    still playing.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION SoundCard$ ()

    Returns a string containing the type of sound card detected.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION SoundCardType% ()

    Returns a number detailing the type of sound card detected.

------------------------------------------------------------------------------
    
    DECLARE FUNCTION Version$ ()

    Returns a string containing the version number of the library, eg "1.1".

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


                                                   
==============================================================================
  Explanation of Which% and Mode% for SetVolume and GetVolume
==============================================================================

    Which% determines which volume to use (eg, master volume, voice volume)
    and also which channel to use (either left or right). Some constants have
    been defined in the include file to make this easier.

    Mode% determines how the volume value is to be treated. A mode of 0 means
    the value is treated as a true value. A true value is specific to your
    particular sound card, and can be between 0 and 15 or 0 and 31. A mode of
    1 treats the value as a value between 0 and 31. This makes it sound card
    independent, as even if your sound card can only handle values between 0
    and 15, then it will still give similar volumes to a card which can work
    with values between 0 and 31. A mode of 2 is similar to a mode of 1, but
    it treats the volume as a value between 0 and 15, therefore being sound
    card independant, but sacrifices the accuracy of sound cards which can
    handle values between 0 and 31.



==============================================================================
  Table of values for Which%, Mode%, and Error message list
==============================================================================

Which% - 0, Master Volume, Left Channel
         1, Master Volume, Right Channel
         2, Voice Volume, Left Channel
         3, Voice Volume, Right Channel
         4, Music Volume, Left Channel
         5, Music Volume, Right Channel

Mode%  - 0, A true value, can vary depending on sound card.
         1, A value between 0 and 31, with 0 representing the minimum and 31
            representing the maximum possible values. Sound card independant.
         2, As for Mode% = 2, but uses a value between 0 and 15 instead.

Error Messages
   #0, "Operation Successful."
   #1, "The SBMIDI Driver could not be detected."
   #2, "The BLASTER environment variable is not set."
   #3, "DetectSettings has not been called."
   #4, "A MIDI file has not been loaded."
   #5, "A MIDI file is already playing."
   #6, "No MIDI file is playing."
   #7, "The file could not be found."
   #8, "There was insufficient memory to complete the operation."
   #9, "The MIDI is not paused."
  #10, "Your Sound card does not support volume alteration."
  #11, "Support for older sound cards not yet included."
  #12, "Path not found."
  #13, "Unknown error."



==============================================================================
  Credits
==============================================================================
  Thanks are due to the following:-
    Jesse Dorland, for creating QMIDI 4.1, which provided the basis for the
      MIDILib library.
    Angelo Mottola for inspiring a couple of routines, such as MIDIError$.
    Peter Norton for Norton Guides, which enabled me to understand the DOS
      Interrupt 21h, functions 1A, 4E and 4F.
    Webmaster Cid, of www.eyesonff.com from which I downloaded most of the
      Final Fantasy MIDI files.
    Whoever sequenced the MIDI files included with the Library (some contain
    credits as Text Events or Track names).
    Jorden, and everyone else at Future Software Programming for distributing
      the library.



==============================================================================
  Contact Information
==============================================================================
  If you encounter any problems when using this library, have a question or a
suggestion, want to report a bug, or for anything else, then you can send an 
e-mail to IceWolf@SimonsMail.Com.
