home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Game Programming Gurus / Tricks_of_the_Game_Programming_Gurus_SAMS_Publishing_1994.iso / digipak / theaudio / midpkapi.doc < prev    next >
Text File  |  1994-01-03  |  14KB  |  352 lines
  1.  
  2.                   MIDPAK
  3.  
  4.                 written by
  5.  
  6.               John W. Ratcliff
  7.  
  8.               Copyright (c) 1994
  9.  
  10.               The Audio Solution
  11.  
  12.  
  13. The MIDI driver MIDPAK hooks into user interrupt vector 66h to provide a
  14. clean clear programmers interface. This document describes the two ways
  15. you can access the midi sound package.    The first is the interrupt
  16. level interface.  The second is a link library interface that provides a
  17. set of C or assembly language callable functions to access not only the
  18. digitized sound drivers but also provides usefull support routines.
  19. These glue code functions are located in the source file MIDPAK.ASM.
  20.  
  21. MIDPAK uses the same interupt vector as DIGPAK.  DIGPAK describes the
  22. complete set of Digitized sound drivers provided by THE Audio Solution.
  23. MIDPAK is fully compatible with DIGPAK.  If your application needs to
  24. play back both MIDI music and digitized sound you simply first load the
  25. digitized sound driver you need, and then load the MIDPAK midi driver on
  26. top of it.  The MIDPAK driver detects the presence of the DIGPAK sound
  27. driver and re-routes all calls through it.  If the digitized sound
  28. hardware does not support independent playback of digitized sound (DMA
  29. support: SoundBlaster, and ProAudio Spectrum do.) then MIDI music
  30. playback will shut down while the digitized sound effect is playing.
  31. MIDI music playback will continue once the digitized sound effect has
  32. completed.  This is completely transparent to the running application.
  33.  
  34. MIDPAK uses the set of MIDI sound drivers developed by Miles Design
  35. Incorporated.  These drivers vary in size and can be noted by the
  36. extension of .ADV.  MIDPAK will always load the sound driver MUSIC.ADV
  37. when started.  The application should copy the apropriate sound driver
  38. over as MUSIC.ADV before loading MIDPAK.
  39.  
  40. MIDPAK does not play .MID files directly.  You must convert the MIDI
  41. file (with the extension of .MID) into an eXtended MIDI file (.XMI)
  42. by using the program MIDIFORM or the MENU utility.  The Miles
  43. eXtended MIDI drivers support MIDI channels 2-9 melodic and channel 10
  44. for percussions.
  45.  
  46. ***********************************************************************
  47. *************** INT 66h Interface Specification ***********************
  48. ***********************************************************************
  49.  
  50. Function #1: UnloadMidPak, removes the MIDPAK tsr from memory, NOT TO BE
  51.               USED by APPLICATION software!
  52.  
  53.     INPUT:    AX = 700h    Command number.
  54.     OUTPUT:         None.
  55.  
  56.  
  57. Function #2: DigPakAvailable, determine whether or not a digpak sound driver
  58.                   as available, underneath the MIDPAK driver.
  59.  
  60.     INPUT: AX = 701h    Command number.
  61.     OUTPUT:AX = 0        Digpak is not available.
  62.            AX = 1        Digpak is available.
  63.  
  64. Function #3: PlaySequence, plays a sequence from the currently registered
  65.                xmidi file.
  66.  
  67.     INPUT: AX = 702h    Command number.
  68.            BX = SEQ     Sequence number, numbered starting from zero.
  69.  
  70.     OUTPUT:AX = 1        Sequence is being played.
  71.            AX = 0        Sequence not available.
  72.  
  73. Function #4: SegueSequence, register a new sequence to be segueded in at the
  74.             next trigger event, with the activation
  75.             code specified.  If the activation code passed is
  76.             a -1, then this sequence will be changed to at the
  77.             next trigger.
  78.  
  79.     INPUT:    AX = 703h    Command number.
  80.         BX = SEQ    Sequence number to segue to.
  81.         CX = ACT    Activation event code, -1 means next trigger.
  82.  
  83.  
  84. Function #5, RegisterXmidi, Register an XMIDI file by address for playback.
  85.  
  86.     INPUT:    AX = 704h    Command number.
  87.         BX = Offset    Offset portion of far address of XMIDI data.
  88.         CX = Segment    Segment portion of far address of XMIDI data.
  89.         SI = Low len    Low word of length of XMIDI data.
  90.         DI = High len    High word of length of XMIDI data.
  91.  
  92.     OUTPUT: AX = 0        Unable to register XMIDI data.
  93.         AX = 1        XMIDI file registered resident.  This means
  94.                 that the XMIDI file was able to be held
  95.                 entirely in MIDPAK's internal buffer area.
  96.                 The application can throw away the memory
  97.                 associated with this XMIDI file because
  98.                 MIDPAK has made a copy of it for itself.
  99.                 This is very useful in virtual memory
  100.                 environments where the application program
  101.                 does not always have fixed addresses in
  102.                 memory.  It also allows MIDPAK to play
  103.                 back MIDI files in the background from DOS.
  104.  
  105.         AX = 2        XMIDI file was registered to the appilcation.
  106.                 The caller is responsible for making sure that
  107.                 this fixed memory address is always contains
  108.                 the data as passed.
  109.  
  110. Function #6:    MidiStop, stop playing current MIDI sequence.
  111.  
  112.     INPUT    AX = 705h    Command.
  113.  
  114.     OUTPUT: None.
  115.  
  116. Function #7:    Unsed
  117.  
  118. Function #8:    ReportTriggerCount -> returns trigger event counter, 
  119.                     and last event code.
  120.  
  121.     INPUT:    AX = 707h    Command number.
  122.  
  123.     OUTPUT: AX = COUNT    Count of # of callbacks, since last reset.
  124.         DX = ID     Event ID of last callback.
  125.                 See callback trigger in XMIDI spec.
  126.  
  127. Function #9:    ResetTriggerCount -> reset's the trigger event counter to zero.
  128.  
  129.     INPUT:    AX = 708h    Command number.
  130.  
  131.     OUTPUT: None.
  132.  
  133. Function #10:    OBSOLETE FUNCTION.
  134.  
  135.  
  136. Function #11:    OBSOLETE FUNCTION
  137.  
  138. Function #12:    ResumePlaying -> resume playing stopped sequence.
  139.  
  140.     INPUT:    AX = 70Bh    Command number.
  141.  
  142. Function #13:    SequenceStatus -> report sequence status.
  143.  
  144.     INPUT:    AX = 70Ch    Command number.
  145.     OUTPUT: AX = Status.
  146.         SEQ_STOPPED 0        // equates for SequenceStatus()
  147.         SEQ_PLAYING 1        // Sequence is currently playing.
  148.         SEQ_DONE 2        // A sequence is DONE playing.
  149.  
  150. Function #14:    RegisterXmidiFile( register by filename)
  151.  
  152.     INPUT:    AX = 70Dh    Command number.
  153.         BX = Offset    Offset portion of filename address.
  154.         CX = Segment    Segment portion of filename address.
  155.  
  156. Function #15:    RelativeVolume->
  157.  
  158.     INPUT:    AX = 70Eh    Command number.
  159.  
  160.     OUTPUT: AX = VOL    Current relative volume.
  161.  
  162. Function #16:    SetRelativeVolume->
  163.  
  164.     INPUT:    AX = 70Fh    Command number.
  165.  
  166.  
  167. Function #17:    BootstrapMidPak
  168.  
  169.     INPUT:    AX = 710h    Command number.
  170.         BX:CX -> segment,offset of ADV driver.
  171.         DX:SI -> segment,offset of AD file.
  172.  
  173. Function #18: PollMidPak
  174.  
  175.     INPUT:    AX = 711h
  176.  
  177.     This function is used in conjunction with PMIDPAK.COM.    PMIDPAK is
  178.     the polled version of MIDPAK.  Normal MIDPAK steals either the timer
  179.     interrupt or the real-time clock interrupt and services it as a rate
  180.     of 120 hertz.  However, some more advanced application want to service
  181.     the hardware interrupts themselves, may want to play back the music
  182.     at a different quantization rate, or may want to sync the service
  183.     rate to graphics routines, to avoid any potential of their graphics
  184.     routines being interrupted by the music.
  185.  
  186.     After MIDPAK is installed it restores the timer interrupt vector and
  187.     is aquiecent until the application program invokes int 66h with the
  188.     command 0711h.    You should invoke this interrupt at 120 hertz or
  189.     to the quantization rate you used when running MIDIFORM.  When
  190.     running MIDIFORM you can specify a quantization rate for your music
  191.     other than the default of 120 hertz.  As you lower the quantization
  192.     rate you will here some degradation in the quality of the music
  193.     since ASDR will not be responding as quickly.  Reducing it to say
  194.     60 hertz won't make much of a noticable difference, but reducing it
  195.     to 15 to 30 hertz will cause noticable degradation.  Obviously running
  196.     many channels of MIDI music out of an FM synthesis device like an
  197.     Adlib is going to take some CPU.  By re-quantiziing your music and
  198.     servicing MIDPAK at the rate you are comforatble with, you can
  199.     balance machine resources nicely yourself.
  200.  
  201. Function #19: MidpakClock
  202.  
  203.     INPUT:    AX = 712h
  204.  
  205.     OUTPUT: AX:DX Current heartbeat count since MidPak startup.
  206.         120 hertz heart beat, application can use this for
  207.         timing.
  208.         BX:CX -> forms the far address pointing to this
  209.              heartbeat counter.
  210.              BX-> is the offset portion.
  211.              CX-> is the segment portion.
  212.  
  213.     This function reports the heartbeat counter for MidPak.  Starting
  214.     at zero since MidPak startup, this value is the long word result of
  215.     the heartbeat counter for MidPak.  A 120 hertz timer that your
  216.     application software can use for timing (in a polled fashion).
  217.  
  218.  
  219. Function #20: TriggerCountAddress
  220.  
  221.     INPUT:    AX = 713h
  222.  
  223.     OUTPUT: AX:DX form for address to point to the integer TriggerCount.
  224.               This is the counter that gets incremented each time
  225.               a Controller 119 is encountered in the midi file.
  226.  
  227.  
  228. Function #21: EventIDAddress
  229.  
  230.     INPUT:    AX = 714h
  231.  
  232.     OUTPUT: AX:DX form an address to point to the integer EventID,
  233.               with is the EventID of the last controller 119
  234.               trigger event encountered.
  235.  
  236. Function #22: Undocumented
  237.  
  238. Function #23: ReportSequenceNumber
  239.  
  240.     INPUT:    AX = 716h
  241.  
  242.     OUTPUT: Report currently playing sequence number.
  243.  
  244.  
  245. extern short     cdecl CheckMidiIn(void); // Returns 1 if MIDPAK is installed, 0 if not.
  246. extern short     cdecl DigPakAvailable(void);      // Returns 1 if DIGPAK is installed, 0 if not.
  247.  
  248. /****************************************************************************/
  249. /* These flags are returned by the XMIDI registration call.              */
  250. /****************************************************************************/
  251. #define FAILURE_TO_REGISTER 0     // Xmidi file registration failed.
  252. #define REGISTERED_RESIDENT 1   // Resident driver holds midi file now.
  253.                     // The application can throw away the memory
  254.                     // if it wants to.
  255. #define REGISTERED_APPLICATION 2  // Driver didn't have a big enough buffer
  256.                       // area reserved to hold the audio data
  257.                       // so the application is responsible for
  258.                       // keeping the memory for this sequence
  259.                       // while it is registered.
  260.  
  261. extern short     cdecl PlaySequence(short seqnum); // Play a particular sequence number from
  262.                       // the currently registered xmidi file.
  263.  
  264. #define NEXT_CALLBACK -1     // Activation on next callback.
  265.  
  266. extern short     cdecl SegueSequence(short seqnum,short activate);
  267.                     // Switch sequence to this sequence when next
  268.                     // callback trigger event is hit with the
  269.                     // event number equal to activate.         If activate
  270.                     // is set to -1 then the next event causes the
  271.                     // segue to occur.
  272.  
  273. extern short     cdecl RegisterXmidi(char      *xmidi,long int size);
  274.                     // Registers an extended midi file for playback.
  275.                     // This call will register all sequences.
  276.  
  277. extern short     cdecl MidiStop(void);      // Stop playing current sequence.
  278.  
  279. extern long int  cdecl ReportCallbackTrigger(void); // Low word is trigger count.
  280.                            // High word is last event ID.
  281.  
  282. extern void  cdecl ResetCallbackCounter(void);     // Reset callback counter to zero.
  283.  
  284. extern void  cdecl ResumePlaying(void);      // Resume playing last sequence.
  285.  
  286. #define SEQ_STOPPED 0          // equates for SequenceStatus()
  287. #define SEQ_PLAYING 1
  288. #define SEQ_DONE 2
  289. extern short      cdecl SequenceStatus(void);      // Report current sequence play status.
  290.  
  291. extern short      cdecl RelativeVolume(short vol); // Report current volume.
  292.  
  293. extern void  cdecl SetRelativeVolume(short vol,short time); // Set volume, over time period.
  294.  
  295. #define NOBUFFER 1          // No resident buffer available.
  296. #define FILENOTFOUND 2          // The file was not found.
  297. #define FILETOBIG 3          // The file exceeds the reserved buffer size.
  298. #define REGISTRATIONERROR 4     // Error registering the XMI file.
  299.  
  300. extern short      cdecl RegisterXmidiFile(char *fname); // Register by filename.
  301.  
  302. extern void  cdecl PollMidPak(void); // Poll MidPak for music processing.
  303.  
  304. extern long int  cdecl MidPakClock(void); // Return MIDPAK heartbeat count (120hz)
  305.  
  306. extern long int  * cdecl MidPakClockAddress(void); // Return address of midpak clock.
  307.  
  308. extern short     *  cdecl TriggerCountAddress(void); // Report address of trigger count.
  309.  
  310. extern short     *  cdecl EventIDAddress(void); // Report address of event id.
  311.  
  312. extern short     cdecl ReportSequenceNumber(void);
  313.  
  314. extern short     cdecl InitMP(char *midpak,char *adv,char      *ad); // Init MIDI driver.
  315. extern void cdecl DeInitMP(char *midpak); // Unload a previously loaded sound driver.
  316.  
  317.  
  318. ***************************************************************************
  319.  
  320.           Written by John W. Ratcliff (c) 1994
  321.                Compuserve: 70253,3237
  322.                Genie: J.RATCLIFF3
  323.                BBS: 1-314-939-0200
  324.                Addresss:
  325.               747 Napa Lane
  326.               St. Charles, MO 63304
  327.  
  328. A $500 per product license fee applies to all commercial software
  329. products distributed with ANY MIDPAK drivers.
  330.  
  331. To pay a license, simply write a check for $500 payable to The Audio
  332. Solution, 747 Napa Lane, St. Charles, MO 63304 with a copy of your
  333. commerical product.  You will receive a signed license agreement from
  334. The Audio Solution shortly thereafter. This license fee applies
  335. specifically to the inclusion with your distribution disk any of the
  336. MIDPAK drivers from The Audio Solution These drivers are copyrighted
  337. works, created by me, to enhance the use of sound and music in DOS based
  338. commercial software.  The license fees collected are used to maintain
  339. the drivers and keep the BBS running.  There is a seperate license fee
  340. for the use and distribution of MIDPAK drivers.
  341.  
  342. See accompaning documentation regarding license fees for DIGPAK
  343. distribution.  You would be ill-advised to distribute a commercial
  344. product containing either DIGPAK and/or MIDPAK drivers without having
  345. paid the distribution license fee.  Since your product would contain
  346. unlicensed copyrighted software from The Audio Solution, your product
  347. could be required to be immediately removed from retail distribution.  I
  348. doubt this is going to be a problem.  Clearly if your product is
  349. enhanced by the use of these drivers, your company can easily afford a
  350. nominal license fee of $500 in exchange for getting the use of several
  351. man-years of software engineering resources.
  352.