home *** CD-ROM | disk | FTP | other *** search
/ Sound, Music & MIDI Collection 2 / SMMVOL2.bin / PROG / MK1_23.ZIP / MID-KIT.DOC < prev    next >
Encoding:
Text File  |  1995-08-17  |  15.8 KB  |  388 lines
  1. -----------------------------------------------------------------------------
  2.                 *** MID-KIT ver 1.23 Documentation ***
  3. -----------------------------------------------------------------------------
  4.  
  5. First of all, I'd like to thank Jean-Paul Mikkers, for letting me use some
  6. of his source code for the mixing routines.  Without them, MID-KIT would not
  7. be what it is today.  He has a great Mod player library, if any of you are
  8. interested.  To contact him, write to:
  9.             Jean-Paul Mikkers
  10.             mikmak@stack.urc.tue.nl
  11.  
  12.    MID-KIT is shareware.  If you would like to use MID-KIT in your own
  13. commercial software, please send in the registration form "REGISTER.FRM".
  14.    
  15.    Registering MID-KIT entitles you to free upgrades, up to ver 1.99.  
  16. Once 2.0 comes out, you will need to only pay a $10 upgrade fee.  MID-KIT is
  17. only $50!  No royalties must be paid, even if your product goes to the shelf.
  18. It would be nice of you to include my name in the credits :-).  So please
  19. register, it helps me improve the player engine, and it helps you get a 
  20. better sound system.  By any means, if you are not happy with MID-KIT, then
  21. tell me why!  I need to know of any bugs, or such.  Please rspond to:
  22.    
  23.     John Pollard
  24.     Compuserve:  74723,1626
  25.     Internet  :  74723.1626@compuserve.com  
  26.     
  27.     Address   :  John Pollard
  28.                  P.O. BOX 692044
  29.                  Tulsa, OK 74169-2044
  30.              
  31.     Phone     :  1 (918) 234-1420
  32.    
  33.    If you are a member of compuserve, you can register right online!  Just
  34.    GO swreg.  Registration ID: 7061.
  35. -----------------------------------------------------------------------------
  36.                           **INTRODUCTION**
  37. -----------------------------------------------------------------------------
  38.    
  39.    MID-KIT is a MIDI engine, for Sound Blasters & %100 compatibles.  MID-KIT 
  40. can also play 32 sound effects at the same time!  That's right, you can have 
  41. midi songs playing in the background, while 32 sound effects play.  That does 
  42. not mean you must use all 32 channels.  About 8 channels, is good enough a 
  43. normal game.  
  44.  
  45.    FEATURES:
  46.    Support for all SB & %100 compatibles up to SB16.
  47.      
  48.      MIDI Player:
  49.         Drum support.
  50.         Supports Pitch bends.
  51.         After-Touch midi message support.
  52.         Can use SB mixer if availible, else will mix in real-time.
  53.         Can play multi-track midi files.
  54.      DIGI Player:
  55.         Plays any size .wav file!
  56.         Supports looping sound effects.
  57.         Support 16 - Bit .wav files.
  58.         Stereo, and 16 bit support.
  59.         Stereo panning effects.
  60.         Up to 32 channels of sound!
  61.  
  62.    
  63.    Will Feature in the future:
  64.         MPU-401 support.
  65.         More sound cards (GUS.  Be sure and bug me about this, if you want it.)
  66.         OPL3.
  67.         Much MORE!!!
  68.         This thing is new, give me some time!!!!!!!
  69.         If you want Gravis Ultra-sound support, then give me a ring!  I've
  70.           got the code for a driver.  Just need some motivation to add it in..
  71.  
  72.    
  73.    You must convert the MIDI files into a format understood by MID-KIT.  I've
  74. included a utility to do so.  The utility is call "MID2MKS.EXE".  Just type
  75. MID2MKS input.mid output.mks.  That's it!.  Then use the MKS loaders to load
  76. them up!  
  77.  
  78.    MID-KIT uses a .MKI file (Mid Kit Instrument file) for playing the FM 
  79. sounds for a .MKS (midi converted file, see above).  Upon initiation, of the
  80. sound system, you must load in a .mki file.  MKI files are stored in a  
  81. structure called mki_file (see midkit.h for details).  The routine
  82. MK_LoadMKI(mki_file *mki), loads in a file called "MID-KIT.MKI".  You must 
  83. load in this file, before using any MKS play routines, or MID-KIT won't be 
  84. able to play any notes.  You don't need to do this, if your not initiating the
  85. sound system for midi playing.
  86.  
  87.    A .MKI files consist of 1 general midi .ibk file, and 1 percussion .ibk
  88. file.  I've included a utility to convert 2 .ibk's into an .MKI file.  The
  89. utility is called "IBK2MKI.EXE".  Just type IBK2MKI in1.ibk in2.ibk out.mki.
  90. The output file must be called MID-KIT.MKI for unregistered versions of
  91. MID-KIT.  I've included 1 general midi .ibk (gm1.ibk), and a percussion .ibk
  92. (perc.ibk).  It only uses the first 3 instruments of the percussion .ibk.
  93. These 3 instruments, define how it will play the drum sounds.  I suggest just
  94. using the "perc.ibk" file I've included.  You can use any general midi .ibk 
  95. you want.
  96.  
  97.    You don't have to use both the MIDI player, and the DIGI player.  You can
  98. use either one, or both.  This means you can mix libraries if you want to. 
  99.  
  100.    MID-KIT uses a timer interrupt, to call it's routines.  You can install
  101. the sound system using this timer, or you may use your own.  If you decide  
  102. to use your own, you must call MK_Update(), 72.8 times/sec.  If you want to
  103. use MID-KIT's timer, use MK_StartTimer() after initiating the sound system. 
  104. NOTE - If MID-KIT return's 0 (no sound card) when you initiate MID-KIT, 
  105. you can still install the timer.  This is usefull, when someone does not have 
  106. a sound card, but would still like to play.  You can call all functions, 
  107. as ussual.  If you do install the timer, a variable "MK_Timer" will be 
  108. incremented 72.8 times per second.  
  109.  
  110.    NOTE - If MID-KIT detects digitized sound, but no FM chip, or vice versa.
  111. It will play anyone it detects.  Also, if you do not want to use the midi
  112. player, and just digital sound.  Install just for digital sound, or vice 
  113. versa.  You can call MK_Update() at any speed you like, if you're just using
  114. the DIGI routines.  You'll have to adjust the playback frequency though.
  115.    
  116.    When you start up MK_StartTimer(), a variable MK_Timer, will be incremented
  117. every 72.8 times per second.  You can allways check the value of this vari-
  118. able for game timing. 
  119.  
  120.   Please see the file "MIDWAV.C" for a complete explanation of how to use the
  121. midi play routines, and the sound effects routines.
  122.  
  123.   MID-KIT uses a cool ERROR system.  If a function was to return an error 
  124.   value, it would return 1 on succes, and 0 on failure.  If it returned a 0,
  125.   then it would have set the "mkerr" variable.  Look at the midwav.c for an 
  126.   example on this error system.... 
  127.  
  128.  
  129.    MID-KIT is very easy to use!  Check out these MID-KIT commands below!
  130.  
  131.                            - Page 1 -
  132. *****************************************************************************
  133. *****************     MID-KIT Initializing Routines       *******************
  134. *****************************************************************************
  135. /////////////////////////////////////////////////////////////////////////////
  136. -MK_Init(UBYTE flag, int num_voices) 
  137.  
  138.  You must call this routine before calling any other MID-KIT routine.
  139.  
  140.  flag        = How MID-KIT will be initialized.  Setting certain bits of
  141.                this flag, will change the way MID-KIT installs itself.
  142.                Just | (bit-wise or) the values you want together.  The 
  143.                Avialible flags are: 
  144.                MK_MIDI - Selects MIDI play.
  145.                MK_DIGI - Selects Digital sound effects playing.
  146.                MK_AUTO - Auto detects the card.
  147.                
  148.                NOTE - See below about auto-detecting.
  149.                
  150.  num_voices  = The number of voices MID-KIT should open for mixing (1-32);
  151.                
  152.                Eaxmple:
  153.                MK_Init(MK_MIDI | MK_AUTO | MK_DIGI, 10);
  154.                
  155.                This will intialize MID-KIT using midi, digital sounds, with 
  156.                10 channels of digital sound effects. It will auto-detect your
  157.                soundcard...   IF YOU DO NOT AUTO-DETECT, THEN YOU MUST SET 
  158.                THESE VARIABLES:
  159.                
  160.                sb_port =0x220;
  161.                sb_irq  =5;
  162.                sb_lodma=1;
  163.                sb_hidma=5;         // this is for sb16's and up...
  164.  
  165.                Set them to whatever you save in your config files, etc...
  166.  
  167. /////////////////////////////////////////////////////////////////////////////
  168. -MK_Exit(void)
  169.  
  170.  You must call this before exiting your program. 
  171. /////////////////////////////////////////////////////////////////////////////
  172. -MK_StartTimer(void)
  173.  
  174.  Call this after initiating the sound system.  Starting up the timer, will 
  175.  increment a variable MK_Timer, every 72.8 times per second. 
  176. /////////////////////////////////////////////////////////////////////////////
  177. -MK_StopTimer(void)
  178.  
  179.  You MUST! call this routine, before you program exits, if you've installed
  180.  MID-KIT's timer.
  181.  
  182. /////////////////////////////////////////////////////////////////////////////
  183. -MK_Update(void)
  184.  
  185.  If the custom MID-KIT timer is not installed, this routine must be called
  186.  72.8 times/sec.
  187.  
  188. *****************************************************************************
  189. *****************   Voice Routines and Wave play routines *******************
  190. *****************************************************************************
  191.  
  192. /////////////////////////////////////////////////////////////////////////////
  193. -MK_VoiceSetVolume(UBYTE voice,
  194.                    UBYTE vol)
  195.  
  196.  Sets the volume of a voice.
  197.  
  198.  voice = The voice that you are going to set the volume of.
  199.          This must be from 0 - the number of voices defined when you initiate
  200.          the sound system
  201.  vol   = The actual volume of the voice (0-64)
  202.  
  203. /////////////////////////////////////////////////////////////////////////////
  204. -MK_VoiceSetFrequency(UBYTE voice,
  205.                       ULONG frq)
  206.  
  207.  Sets the frequency of a voice.
  208.  
  209.  voice = The voice to change.
  210.  frq   = The actual frequency the voice will play sounds.
  211.  
  212. ////////////////////////////////////////////////////////////////////////////
  213. -MK_VoiceSetPanning(UBYTE voice,
  214.                     ULONG pan)
  215.  
  216.  Sets the panning position of a voice.
  217.  
  218.  voice = The voice to change.
  219.  pan   = The new panning posistion for the voice.
  220.          1-255 - from left to right 
  221.          1     = FULL Left 
  222.          255   = FULL Right.
  223.  
  224. ////////////////////////////////////////////////////////////////////////////
  225. -MK_VoiceStop(UBYTE voice)
  226.  
  227.  Stops a sound effect from playing on a certain voice.
  228.  
  229.  voice = The voice to stop playing.
  230. ////////////////////////////////////////////////////////////////////////////
  231. -MK_VoiceActive(UBYTE voice)
  232.  
  233.  This return a 1 if the voice is playing a sound effect, or 0 if it's not.
  234.  
  235.   voice = The voice to check.
  236. ////////////////////////////////////////////////////////////////////////////
  237. -MK_VoicePlay(UBYTE voice,
  238.               WORD handle,
  239.               ULONG start,
  240.               ULONG size,
  241.               ULONG reppos,
  242.               ULONG repend,
  243.               UWORD flags)
  244.  
  245.  Plays a sound effect (a previously loaded .wav file), on a certain voice.
  246.  
  247.  voice  = The voice to play the sound effect on.
  248.  handle = The handle defined in the SAMPLE structure.
  249.  start  = The start posistion defined in the SAMPLE structure.
  250.  size   = The size defined in the SAMPLE structure.
  251.  reppos = If the repeat flag is set, then this is where it start repeating.
  252.  repend = If the repeat flag is set, then this is where it stops repeating.
  253.  flags  = The flags defined in the SAMPLE structure.
  254.           Please see midkit.h, for info on these flags.
  255.  EXAMPLE:
  256.      #include"midkit.h"
  257.      #include"mtypes.h"
  258.      #include"mwav.h"
  259.      #include<stdio.h>
  260.      
  261.      SAMPLE *s;                        // define a sound effect.
  262.      
  263.      void main(void)
  264.      { /*
  265.       Initialize soundcard parameters.. you _have_ to do this
  266.       before calling MD_Init(), and it's illegal to change them
  267.       after you've called MD_Init()
  268.        
  269.       Initiate for digital routines, midi routines, 8 voices, and install
  270.       MID-KITs custom timer (72.8 hz / interupt 8).
  271.       */
  272.       mk_mixfreq      =44100;                   // standard mixing freq
  273.       mk_dmabufsize   =4000;                    // standard dma buf size
  274.       mk_mode         =BITS16|STEREO;           // standard mixing mode
  275.       
  276.       // auto-detect all perameters.....     
  277.       
  278.       if (!MK_Init(MK_DIGI | MK_MIDI | MK_AUTO, 8) )
  279.          printf("Driver ERROR: %s",mkerr);
  280.       else 
  281.         printf("Found Sound Blaster at port %0x, irq %i",sb_port,sb_irq);
  282.  
  283.       MK_StartTimer();               // install custom timer...
  284.                                      // variable MK_Timer will be incremented
  285.                                      // 72.8 times per second.
  286.  
  287.       if ((s=MK_LoadWave("sample.wav"))==NULL); // load the wave file   
  288.       {   printf("Wave Loader ERROR: %s",mkerr);
  289.           exit(-1);
  290.       }
  291.       MK_VoiceSetVolume(0,64);                 // set volumes and freqency's.
  292.       MK_SetFrequency(0,12000);
  293.       MK_SetPanning(0,100);
  294.       MK_VoicePlay(0,s->handle,s->start,s->size,0,0,s->flags);
  295.       while (!kbhit() );
  296.       MK_FreeWave(s);
  297.       MK_Exit();
  298.       }
  299.  
  300.                             - Page 2 -
  301.  
  302. *****************************************************************************
  303. *****************       Wave Loading Routines             *******************
  304. *****************************************************************************
  305. ////////////////////////////////////////////////////////////////////////////
  306. -MK_LoadWave(char *filename)
  307.  Loads a wave file into a SAMPLE structure.
  308.  EXAMPLE:
  309.     SAMPLE *s;
  310.     s=MK_LoadWave("sample.wav");
  311.  
  312. ////////////////////////////////////////////////////////////////////////////
  313. -MK_FreeWave(SAMPLE *si)
  314.  Frees a previously allocated SAMPLE structure.
  315.  EXAMPLE:
  316.     SAMPLE *s;
  317.     s=MK_LoadWave("sample.wav");
  318.     MK_FreeWave(s);
  319. ////////////////////////////////////////////////////////////////////////////
  320.  
  321. *****************************************************************************
  322. *****************  MIDI Playing routines (.MKS files)     *******************
  323. *****************************************************************************
  324.  
  325. NOTE - You must convert midi files, to mid-kit's own format.
  326.        Use MID2MKS.EXE to do this.....
  327.  
  328. ////////////////////////////////////////////////////////////////////////////
  329. -MK_LoadMKI(mki_file *mki);
  330.  
  331.  Loads an .MKI bank file.
  332.  You must do this before any MKS play routine, or it will play wrong.
  333.  
  334.  EXAMPLE:
  335.      mki_file mki;
  336.      MK_LoadMKI(&mki);                  // load in the MID-KIT.MKI data file
  337. ////////////////////////////////////////////////////////////////////////////
  338.  
  339. -MK_LoadMKS(char *name, mdk_file *mdk);
  340.  
  341.  Loads a .mks file.  For playing.
  342.  
  343.  EXAMPLE:
  344.      mks_file mks;
  345.      mki_file mki;
  346.      MK_LoadMKI(&mki);                   // load in the MID-KIT.MKI data file
  347.      MK_LoadMKS("hero.mks", &mks);       // load in the song
  348.  
  349. ////////////////////////////////////////////////////////////////////////////
  350. -MK_PlayMKS(mks_file *mks, mki_file *mki);
  351.  
  352.  Plays a mks file.
  353.  
  354.  EXAMPLE:
  355.      mks_file mks;
  356.      mki_file mki;
  357.      
  358.      MK_LoadMKI(&mki);                   // load in the MID-KIT.MKI data file
  359.      MK_LoadMKS("hero.mks", &mks);
  360.      
  361.      
  362.      MK_PlayMKS(&mks, &mki);
  363.      
  364.      MK_SetMusicVol(60);                // volume can be from 1-130
  365.      
  366.      ( Of course, you must initialize the sound system.  Look at the support
  367.        file "MIDWAV.C" for further info.)
  368.  
  369. ////////////////////////////////////////////////////////////////////////////
  370. -MK_SetMusicVol(int vol)
  371.  You must set this after playing a .mks song.
  372.  uses:
  373.  vol = 1-130   (1=min, 130=max)
  374.  
  375.  returns - 1 on succes, 0 on out of range volume....
  376.  
  377. ////////////////////////////////////////////////////////////////////////////
  378. -MK_FreeMKS(mdk_file *mks);
  379.  
  380.  Frees an allocated mks file.
  381.  
  382. ////////////////////////////////////////////////////////////////////////////
  383. -MK_StopMKS(void);
  384.  
  385.  Stops the current playing song file from playing.
  386.  Call this before playing other mks files.
  387. ////////////////////////////////////////////////////////////////////////////
  388.