home *** CD-ROM | disk | FTP | other *** search
/ C++ Games Programming / CPPGAMES.ISO / digmid / real / digplay.h < prev    next >
C/C++ Source or Header  |  1994-01-03  |  9KB  |  156 lines
  1. /*****************************************************************************/
  2. /* DIGPLAY.H    C prototype header for the DIGPAK API link layer                             */
  3. /*                        DIGPLAY.ASM.    Because sound cards playback sound via DMA             */
  4. /*                        addresses passed must be in the first 1mb of address space.      */
  5. /*                                                                                                                                                     */
  6. /*                        See DIGPKAPI.DOC for complete DIGPAK documentation.                      */
  7. /*                                                                                                                                                     */
  8. /*                                                                                                                                                     */
  9. /*        Written by John W. Ratcliff (c) 1994                                                                     */
  10. /*             Compuserve: 70253,3237                                                                                          */
  11. /*             Genie: J.RATCLIFF3                                                                                                  */
  12. /*             BBS: 1-314-939-0200                                                                                                 */
  13. /*             Addresss:                                                                                                                     */
  14. /*                     747 Napa Lane                                                                                                     */
  15. /*                     St. Charles, MO 63304                                                                                     */
  16. /*                                                                                                                                                     */
  17. /*        A $500 per product license fee applies to all commercial software          */
  18. /*        products distributed with ANY DIGPAK drivers.                                                  */
  19. /*                                                                                                                                                     */
  20. /*        To pay a license, simply write a check for $500 payable to                         */
  21. /*                The Audio Solution, 747 Napa Lane, St. Charles, MO 63304                     */
  22. /*                with a copy of your commerical product.  You will receive a signed */
  23. /*                license agreement from The Audio Solution shortly thereafter.          */
  24. /*                This license fee applies specifically to the inclusion with your     */
  25. /*                distribution disk any of the DIGPAK drivers from The Audio Solution*/
  26. /*                These drivers are copyrighted works, created by me, to enhance the */
  27. /*                use of sound and music in DOS based commercial software.    The          */
  28. /*                license fees collected are used to maintain the drivers and keep     */
  29. /*                the BBS running.    There is a seperate license fee for the use          */
  30. /*                and distribution of MIDPAK drivers.                                                              */
  31. /*                                                                                                                                                     */
  32. /*                See accompaning documentation regarding license fees for MIDPAK      */
  33. /*                distribution.  You would be ill-advised to distribute a commercial */
  34. /*                product containing either DIGPAK and/or MIDPAK drivers without         */
  35. /*                having paid the distribution license fee.  Since your product would*/
  36. /*                contain unlicensed copyrighted software from The Audio Solution,     */
  37. /*                your product could be required to be immediately removed from retail*/
  38. /*                distribution.  I doubt this is going to be a problem.  Clearly if  */
  39. /*                your product is enhanced by the use of these drivers, your company */
  40. /*                can easily afford a nominal license fee of $500 in exchange for      */
  41. /*                getting the use of several man-years of software engineering             */
  42. /*                resources.                                                                                                                 */
  43. /*****************************************************************************/
  44.  
  45. /* Bit flags to denote audio driver capabilities. */
  46. /* returned by the AudioCapabilities call.                */
  47. #define PLAYBACK 1    // Bit zero true if can play audio in the background.
  48. #define MASSAGE  2    // Bit one is true if data is massaged.
  49. #define FIXEDFREQ 4   // Bit two is true if driver plays at fixed frequency.
  50. #define USESTIMER 8   // Bit three is true, if driver uses timer.
  51. #define SHARESTIMER 16 // Bit 4, timer can be shared
  52. #define STEREOPAN 64    // Bit 6, supports stereo panning.
  53. #define STEREOPLAY 128 // Bit 7, supports 8 bit PCM stereo playback.
  54. #define AUDIORECORD 256 // Bit 8, supports audio recording!
  55. #define DMABACKFILL 512  // Bit 9, support DMA backfilling.
  56. #define PCM16 1024            // Bit 10, supports 16 bit digital audio.
  57. #define PCM16STEREO 2048 // Bit 11, driver support 16 bit digital sound
  58. // All digpak drivers which support 16 bit digital sound ASSUME 16 bit
  59. // SIGNED data, whereas all 8 bit data is assumed UNSIGNED.  This correlates
  60. // exactly to the hardware specifcations for most all DMA driven PC sound
  61. // cards, including SB16, Gravis UltraSound and ProAudio Spectrum 16 sound cards.
  62.  
  63. typedef struct
  64. {
  65.     char far *sound;         // address of audio data. IMPORANT SEE NOTE BELOW!!!!!!!!!!
  66.     unsigned short sndlen; // Length of audio sample.
  67.     short far *IsPlaying; // Address of play status flag.
  68.     short frequency;    // Playback frequency. recommended 11khz.
  69. } SNDSTRUC;
  70.  
  71. /**  !!! IMPORTANT NOT REGARDING THE SOUND ENTRY IN THE SOUND STRUCTURE !!! **/
  72. /**  Since this sound structure is in the identical format as that used in    **/
  73. /**  real-mode, this entry is NOT a flat-model 32 bit address but in real     **/
  74. /**  mode offset:segment format, in the first 1mb of address space.  The        **/
  75. /**  sound effect cannot be greater than 64k in length!                                         **/
  76. /**  Use the DOSCALLS function call RealPtr to convert the 32 bit flat            **/
  77. /**  address into offset:segment format.    Example: snd->sound = RealPtr(data)*/
  78. /**  which will convert the low 1mb flat addres 'data' into offset:segment   */
  79. /**  format and store it into the 'sound' entry of the SNDSTRUC structure    */
  80. /**  pointed to by 'snd'.  'snd' MUST be in the first 1mb of address space as*/
  81. /**  well.    'snd' is passed as a flat-model address, and DIGPAK 3.4 drivers  */
  82. /**  will treat it as such so long as the SetDMPIMode has been set on.    This */
  83. /**  is done automatically by LOADER.C during the InitDigPak call.                     */
  84.  
  85. extern short    cdecl far DigPlay(SNDSTRUC far *sndplay); // 688h -> Play 8 bit digitized sound.
  86. extern short    cdecl far SoundStatus(void);    // 689h -> Report sound driver status.
  87. extern void cdecl far MassageAudio(SNDSTRUC far *sndplay); // 68Ah -> Preformat 8 bit digitized sound.
  88. extern void cdecl far DigPlay2(SNDSTRUC far *sndplay); // 68Bh -> Play preformatted data.
  89. extern short    cdecl far AudioCapabilities(void); // 68Ch -> Report audio driver capabilities.
  90. extern void cdecl far StopSound(void); // 68Fh -> Stop current sound from playing.
  91. extern short    cdecl far PostAudioPending(SNDSTRUC far *sndplay);
  92.  
  93. #define NOTPLAYING 0  // No sound is playing.
  94. #define PLAYINGNOTPENDING 1 // Playing a sound, but no sound is pending.
  95. #define PENDINGSOUND 2            // Playing, and a sound is pending.
  96. extern short    cdecl far AudioPendingStatus(void);
  97.  
  98. #define FULLRIGHT 0
  99. #define FULLLEFT 127
  100. #define FRONTANDCENTER 64
  101. extern short    cdecl far SetStereoPan(short panvalue); // 0-127, 0 full right.
  102.                                                                 //             64 full volume both.
  103.                                                                 //            127 full volume left.
  104.  
  105.  
  106. #define PCM_8_MONO 0
  107. #define PCM_8_STEREO 1
  108. #define PCM_16_MONO 2
  109. #define PCM_16_STEREO 3
  110. extern short cdecl far SetPlayMode(short playmode);
  111. // Return 0 if mode not available, 1 if mode set.
  112.  
  113. extern short cdecl far SetRecordMode(short mode); // Set audio recording mode.
  114.  
  115. extern short far * cdecl far PendingAddress(void); // Reports the far address of the pending
  116. // flag.    If this memory location pointed to by this address is 1 that means
  117. // a pending sound effect is still pending.  When this becomes zero, then your
  118. // application software can post the next piece of audio to play.  It is
  119. // preferable to use this semaphore to know when to post the next buffer
  120. // rather than to use the AudioPendingStatus call.
  121.  
  122. extern short far * cdecl far ReportSemaphoreAddress(void); // Reports the far address of the DigPak
  123. // semaphore.  If this semaphore is true, then DigPak is currently active
  124. // and you shouldn't post any DigPak calls.  This is EXTREMELY important if
  125. // you are trying to invoke DigPak functions via a hardware interrupt, where
  126. // you could potentially have interrupted DigPak itself.
  127.  
  128. extern short cdecl far ReportVersionNumber(void); // Report the DigPak version number.
  129. // Return code is times 100, meaning that version 3.1 would be returned
  130. // as the decimal number 310.  This function wasn't supported prior to
  131. // version 3.1 release, so it will be returned as 0, for versions prior
  132. // to 3.1.
  133.  
  134. extern short cdecl far SetBackFillMode(short mode); // Turn DMA backfill mode on/off, return code
  135. // of 1 means mode was set.  Return code of 0 means driver doesn't support
  136. // DMA backfill.
  137.  
  138. extern unsigned short cdecl far ReportDMAC(void); // Report current DMA counter.
  139.  
  140. extern short cdecl far VerifyDMA(char far *data,short length); // Verify this buffer block
  141. // doesn't cross a 64k boundary.  Return code of 1 means the block is OK.
  142. // return code of 0 means the block can't be used, try another.
  143.  
  144. extern void cdecl far NullSound(char far *sound,short sndlen,short null);
  145.  
  146. /* Support routines */
  147. extern void cdecl far WaitSound(void); // Wait until sound playback completed.
  148. extern short    cdecl far CheckIn(void);     // Is sound driver available? 0 no, 1 yes.
  149.  
  150. extern void cdecl far SetDPMIMode(short mode); // Set DPMI addressing mode for DIGPAK
  151.  
  152. extern void cdecl far DigPakIdentityString(char *str);
  153.  
  154. extern short    cdecl far InitDP(short segment); // Bootstrap hardware.
  155. extern void cdecl far DeInitDP(short segment); // Uninitialize DIGPAK
  156.