home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / sound / digpak / digpkapi.doc < prev    next >
Encoding:
Text File  |  1993-07-30  |  10.6 KB  |  243 lines
  1.  
  2.              Version 3.3 DigPak
  3.  
  4.                  written by
  5.  
  6.               John W. Ratcliff
  7.  
  8. THIS DOCUMENTATION IS FOR THE SBDIRECT, PUBLIC DOMAIN VERSION OF
  9. DIGPAK ONLY.  THIS DOES NOT GIVE YOU THE RIGHTS TO USE OR DISTRIBUTE
  10. ANY DIGPAK DRIVERS.  ONLY THIS VERSION IS BEING RELEASED IN THE PUBLIC
  11. DOMAIN.
  12.  
  13.  RELEASED INTO THE PUBLIC DOMAIN, August 1, 1993
  14.  I WILL PROVIDE NO TECHNICAL SUPPORT FOR THIS CODE, THIS DOES NOT GIVE YOU
  15.  THE RIGHT TO USE OR DISTRIBUTE DIGPAK DRIVERS.  YOU MAY USE THIS ONLY IN
  16.  CONJUNCTIONS WITH THE SBDIRECT.ASM HARD CODED SOUNDBLASTER DRIVE PROVIDED
  17.  WITHIN.  USE AT YOUR OWN RISK.  RELEASED SO THAT YOU MAY PROVIDE TURNKEY
  18.  DIGITAL SOUND APPLICATIONS THAT ARE SOUNDBLASTER COMPATIBLE.  I REQUEST
  19.  THAT ANY SOFTWARE DEVELOPED THAT MAKES USE OF THIS DRIVER, HAVE A COPY
  20.  SENT TO ME ON MY BBS AT 1-314-939-0200.  YOU CAN LEAVE ME E-MAIL ON
  21.  COMPUSERVE AT 70253,3237, OR ON GENIE AS J.RATCLIFF3. I CANNOT STRESS
  22.  ENOUGH, THAT I CANNOT PROVIDE TECHNICAL SUPPORT FOR THIS CODE.  YOU DO
  23.  NOT HAVE RIGHTS TO USE OTHER DIGPAK DRIVERS ANY ANY WAY.  THIS TURNKEY
  24.  SOUNDBLASTER IS THE ONLY THING BEING RELEASED IN THE PUBLIC DOMAIN.
  25.  BUG FIXES OR IMPROVMENTS TO THIS CODE MUST BE FOWARDED TO ME ON MY BBS
  26.  
  27. Includes one set of sources that works in all memory models.  Full
  28. MIDPAK compatible support.
  29.  
  30. The set of digitized sound drivers hook into user interrupt vector 66h
  31. to provide a clean clear programmers interface. This document describes
  32. the two ways you can access the digitized sound package.  The first is
  33. the interrupt level interface.    The second is a link library interface
  34. that provides a set of C or assembly language callable functions to
  35. access not only the digitized sound drivers but also provides usefull
  36. support routines.  These glue code functions are located in the source
  37. file DIGPLAY.ASM.
  38.  
  39.     ************** VERSION 3.1 CHANGES ***************
  40.  
  41. int far *ReportPendingAddress(void); // Reports the far address of the pending
  42. // flag.    If this memory location pointed to by this address is 1 that means
  43. // a pending sound effect is still pending.  When this becomes zero, then your
  44. // application software can post the next piece of audio to play.  It is
  45. // preferable to use this semaphore to know when to post the next buffer
  46. // rather than to use the AudioPendingStatus call.
  47.  
  48. int far *ReportSemaphoreAddress(void); // Reports the far address of the DigPak
  49. // semaphore.  If this semaphore is true, then DigPak is currently active
  50. // and you shouldn't post any DigPak calls.  This is EXTREMELY important if
  51. // you are trying to invoke DigPak functions via a hardware interrupt, where
  52. // you could potentially have interrupted DigPak itself.
  53.  
  54. int far ReportVersionNumber(void); // Report the DigPak version number.
  55. // Return code is times 100, meaning that version 3.1 would be returned
  56. // as the decimal number 310.  This function wasn't supported prior to
  57. // version 3.1 release, so it will be returned as 0, for versions prior
  58. // to 3.1.
  59.  
  60. ***********************************************************************
  61. *************** INT 66h Interface Specification ***********************
  62. ***********************************************************************
  63.  
  64. When invoking digplay functions to play sound you pass the address of
  65. a sound structure (SNDSTRUC) that contains the basic information
  66. describing the sound effect you wish to play.
  67.  
  68.  
  69. typedef struct
  70. {
  71.     unsigned char far *sound; // Far address of audio data.
  72.     unsigned int     sndlen;  // Length of audio sample.
  73.     int far *IsPlaying;      // Address of play status flag.
  74.     int    frequency;      // Playback frequency.
  75. } SNDSTRUC;
  76.  
  77. ********* DIGPAK functions ************************************
  78.  
  79. Function #1: DigPlay, Play an 8 bit digitized sound.
  80.  
  81.     INPUT:    AX = 688h    Command number.
  82.         DS:SI         Point to a sound structure that
  83.                  describes the sound effect to be played.
  84.  
  85. Function #2: SoundStatus, Check current status of sound driver.
  86.           and report VERSION number of the driver, 3.1 and later.
  87.  
  88.     INPUT:    AX = 689h
  89.     OUTPUT: AX = 0         No sound is playing.
  90.            = 1         Sound effect currently playing.
  91.         DX = 0         No sound is looping.
  92.            = 1         A sound effect is looping.
  93.         BX = version Starting with version 3.1, the BX register
  94.                  of the SoundStatus call will return the
  95.                  version number.  The version number is in
  96.                  decimal, and multiplied times 100.  Meaning
  97.                  a return of 310, is equal to version 3.10.
  98.                  Versions before 3.1, did not set the BX
  99.                  register to anything, so you should zero
  100.                  out the BX register before you check the
  101.                  version number.  If the BX register is still
  102.                  zero, then the DigPak driver loaded is less
  103.                  than 3.1.
  104.  
  105.  
  106. Function #3: MassageAudio, Preformat audio data into ouptut hardware format.
  107.  
  108.     INPUT:    AX = 68Ah
  109.         DS:SI         Point to address of sound structure.
  110.  
  111. Function #4: DigPlay2, Play preformatted audio data.
  112.  
  113.     INPUT:    AX = 68Bh
  114.         DS:SI         Point to address of sound structure.
  115.  
  116. Function #8: StopSound, stop currently playing sound.
  117.  
  118.     INPUT: AX = 68Fh
  119.     OUTPUT: None.
  120.  
  121.           Will cause any currently playing sound effect to be
  122.           terminated.
  123.  
  124.  
  125. FUNCTION #14: PostAudioPending
  126.  
  127.     INPUT: AX = 695h
  128.            DS:SI -> sound structure, preformated data.
  129.  
  130.     OUTPUT: AX = 0    Sound was started playing.
  131.         AX = 1    Sound was posted as pending to play.
  132.         AX = 2    Already a sound effect pending, this one not posted.
  133.  
  134. FUNCTION #15: AudioPendingStatus
  135.  
  136.     INPUT:    AX = 696h
  137.  
  138.     OUTPUT: AX = 0 No sound is playing.
  139.         AX = 1 Sound playing, sound pending.
  140.         AX = 2 Sound playing, no sound pending.
  141.  
  142. FUNCTION #18:    Report Pending Status Flag adddress and Semaphore address.
  143.  
  144.     int far *ReportPendingAddress(void);
  145.     Reports the far address of the pending flag.  If this memory location
  146.     pointed to by this address is 1 that means a pending sound effect is
  147.     still pending.    When this becomes zero, then your application software
  148.     can post the next piece of audio to play.  It is preferable to use this
  149.     semaphore to know when to post the next buffer rather than to use the
  150.     AudioPendingStatus call.
  151.  
  152.     int far *ReportSemaphoreAddress(void);
  153.  
  154.     Report the address of the DigPak semaphore.  This returns a far
  155.     address to a word location inside DigPak.  When this is true,
  156.     then DigPak is currently active, and you shouldn't invoke any
  157.     DigPak function from a hardware interrupt at this time.
  158.  
  159.     INPUT: AX=699h
  160.     OUTPUT: AX:DX -> form far Address of Pending status flag.
  161.         BX:DX -> form far address of digpak semaphore
  162.  
  163. ***********************************************************************
  164. ** DigPlay, linkable interface to the Digitized Sound Package.      *****
  165. ***********************************************************************
  166. The file DIGPLAY.ASM is a small assembly language source file that
  167. provides C compatible procedure calls to hook into the Digitized
  168. Sound Package.    DIGPLAY.ASM uses one include file called PROLOGUE.MAC.
  169. This is a macro header file that defines some basic useful assembly
  170. language macros.
  171.  
  172. DIGPLAY.ASM is written in Turbo Assebmler's IDEAL mode.  The MASM syntax
  173. for 8086 assembler is abhorent.  The Turbo Assembler IDEAL mode offers
  174. true local labels, real data structures, typecasting, automatic argument
  175. passing, and local memory allocation. Turbo Assembler in IDEAL mode
  176. provides many of the features of a high-level langauge.  Turbo Assembler
  177. and Turbo Debugger combined are without question the most powerful
  178. assembly language tools available for any 8086 programmer.  The last I
  179. checked, Turbo Assembler and Turbo Debugger sold for less than $99.
  180. Recently Microsoft released a new version of MASM that finally provides
  181. some of the features that Turbo Assembler has had for over three years;
  182. and requires a new assembly language syntax.  For these reasons I can
  183. no longer consider MASM the standard for 8086 DOS based assemblers and
  184. that it why you will find all assembly language source code here
  185. provided in Turbo Assembler IDEAL mode format.    If you do not have
  186. Turbo Assembler simply link to one of the two following object modules.
  187.  
  188. All these link layer procedures are defined as far calls and accept far
  189. addresses for all pointers passed.  The reason for this is so that you
  190. can link to one object module regardless of the memory model you are
  191. working in.
  192.  
  193. The C prototype header file for DigPlay support functions are as follows:
  194.  
  195.  
  196. typedef struct
  197. {
  198.   char far *sound;     // address of audio data.
  199.   unsigned int sndlen; // Length of audio sample.
  200.   int far  *IsPlaying; // Address of play status flag.
  201.   int       frequency;  // Playback frequency.
  202. } SNDSTRUC;
  203.  
  204. int  far DigPlay(SNDSTRUC far *sndplay); // 688h -> Play 8 bit digitized sound.
  205. int  far SoundStatus(void);  // 689h -> Report sound driver status.
  206. void far MassageAudio(SNDSTRUC far *sndplay); // 68Ah -> Preformat 8 bit digitized sound.
  207. void far DigPlay2(SNDSTRUC far *sndplay); // 68Bh -> Play preformatted data.
  208. void far StopSound(void); // 68Fh -> Stop current sound from playing.
  209. int  far PostAudioPending(SNDSTRUC far *sndplay);
  210.  
  211. #define NOTPLAYING 0  // No sound is playing.
  212. #define PLAYINGNOTPENDING 1 // Playing a sound, but no sound is pending.
  213. #define PENDINGSOUND 2            // Playing, and a sound is pending.
  214. int  far AudioPendingStatus(void);
  215.  
  216. int far *ReportPendingAddress(void); // Reports the far address of the pending
  217. // flag.    If this memory location pointed to by this address is 1 that means
  218. // a pending sound effect is still pending.  When this becomes zero, then your
  219. // application software can post the next piece of audio to play.  It is
  220. // preferable to use this semaphore to know when to post the next buffer
  221. // rather than to use the AudioPendingStatus call.
  222.  
  223. int far *ReportSemaphoreAddress(void); // Reports the far address of the DigPak
  224. // semaphore.  If this semaphore is true, then DigPak is currently active
  225. // and you shouldn't post any DigPak calls.  This is EXTREMELY important if
  226. // you are trying to invoke DigPak functions via a hardware interrupt, where
  227. // you could potentially have interrupted DigPak itself.
  228.  
  229. int far ReportVersionNumber(void); // Report the DigPak version number.
  230. // Return code is times 100, meaning that version 3.1 would be returned
  231. // as the decimal number 310.  This function wasn't supported prior to
  232. // version 3.1 release, so it will be returned as 0, for versions prior
  233. // to 3.1.
  234.  
  235. /* Support routines */
  236. void far WaitSound(void); // Wait until sound playback completed.
  237. int  far CheckIn(void);   // Is sound driver available? 0 no, 1 yes.
  238.  
  239. int  far LoadSoundDriver(char far *address);  // Load a sound driver by filename, 1 success 0 fail.
  240. void far UnloadSoundDriver(void); // Unload a previously loaded sound driver.
  241.  
  242.  
  243.