home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / c / dmkit / flat / digplay.h < prev    next >
Encoding:
Text File  |  1993-12-31  |  11.5 KB  |  200 lines
  1. /*****************************************************************************/
  2. /* DIGPLAY.H    C prototype header for flat-model DIGPAK interface layer             */
  3. /*                        DIGPLAY.ASM.    Because DIGPAK is a real-mode program all              */
  4. /*                        addresses passed must be in the first 1mb of address space.      */
  5. /*                        When filling the Sound Structure with the address of a sound     */
  6. /*                        effect to play, it MUST be in offset:segment format.                     */
  7. /*                        However the address of the sound structure itself, as passed     */
  8. /*                        to DigPlay, etc, is a flat-address in the FIRST 1MB of address */
  9. /*                        space.    This is an absolute requirement because DIGPAK drivers */
  10. /*                        are still all real-mode code!  Include the header file to          */
  11. /*                        DOSCALLS.H and link to DOSCALLS.OBJ.    This gives you basic         */
  12. /*                        memory management (low dos memory allocation) and pointer type */
  13. /*                        conversion resources without being dependent on any parituclar */
  14. /*                        compiler vendor's C link libraries.                            */
  15. /*                                                                                                                                                     */
  16. /*                        See DIGPKAPI.DOC for complete DIGPAK documentation.                      */
  17. /*                                                                                                                                                     */
  18. /*                        Look at the simple PLAYSOUND routine in TEST.C to see how          */
  19. /*                        the SNDSTRUC is set up and allocated.  Also see how memory         */
  20. /*                        for the sound effect is allocated in the first 1mb of address  */
  21. /*                        space.                                                                                                                 */
  22. /*                                                                                                                                                     */
  23. /*                        DIGPLAY.ASM, flat-model link layer to DIGPAK functions.              */
  24. /*                        written using Borland Assembler in IDEAL mode.    Assumes              */
  25. /*                        a DPMI with a flat model address space where selectors                 */
  26. /*                        DS and ES always point to flat address 0000000000000h!                 */
  27. /*                        Written and tested with DOS4GW and Watcom C.    Uses                         */
  28. /*                        standard C calling convention.    Getting this to work                     */
  29. /*                        under any other DPMI is an excercise left for ths student.         */
  30. /*                                                                                                                                                     */
  31. /*            Warning!! The Watcom compiler passes 4 bytes on the stack      */
  32. /*                        to a cdecl external routine, even if the parameter is only         */
  33. /*                        a char.  All of these assembly routines have been defined          */
  34. /*                        this way.  If you are using a compiler that passes different     */
  35. /*                        size arguments to cdecl routines, you may want to double             */
  36. /*                        check for compatibilities sake.                                                              */
  37. /*                                                                                                                                                     */
  38. /*                        The FLAT-MODEL DIGPAK DOES NOT SUPPORT 8253 TIMER BASED              */
  39. /*                        DRIVERS!    Their interrupt requirements are too excessive             */
  40. /*                        and create too many incompatibility problems for protected         */
  41. /*                        mode applications.                                                                                         */
  42. /*                                                                                                                                                     */
  43. /*                        Previously DIGPAK drivers always handled the address of the      */
  44. /*                        sound structure passed in DS:SI.    Since DS is a selector             */
  45. /*                        in protected mode, I had to add a mode switch to DIGPAK to         */
  46. /*                        pass the flat model address of the sound structure in ESI.         */
  47. /*                        To do this required I make a version change to DIGPAK.    You      */
  48. /*                        will need at least v3.4 DIGPAK drivers to have the SetDPMIMode */
  49. /*                        32 bit register API function call.                                                         */
  50. /*                        LOADER.C and DIGPLAY.ASM handle all of this setup for you.         */
  51. /*                        Just look at the sample application TEST.C                                         */
  52. /*                                                                                                                                                     */
  53. /*        Written by John W. Ratcliff (c) 1994                                                                     */
  54. /*             Compuserve: 70253,3237                                                                                          */
  55. /*             Genie: J.RATCLIFF3                                                                                                  */
  56. /*             BBS: 1-314-939-0200                                                                                                 */
  57. /*             Addresss:                                                                                                                     */
  58. /*                     747 Napa Lane                                                                                                     */
  59. /*                     St. Charles, MO 63304                                                                                     */
  60. /*                                                                                                                                                     */
  61. /*        A $500 per product license fee applies to all commercial software          */
  62. /*        products distributed with ANY DIGPAK drivers.                                                  */
  63. /*                                                                                                                                                     */
  64. /*        To pay a license, simply write a check for $500 payable to                         */
  65. /*                The Audio Solution, 747 Napa Lane, St. Charles, MO 63304                     */
  66. /*                with a copy of your commerical product.  You will receive a signed */
  67. /*                license agreement from The Audio Solution shortly thereafter.          */
  68. /*                This license fee applies specifically to the inclusion with your     */
  69. /*                distribution disk any of the DIGPAK drivers from The Audio Solution*/
  70. /*                These drivers are copyrighted works, created by me, to enhance the */
  71. /*                use of sound and music in DOS based commercial software.    The          */
  72. /*                license fees collected are used to maintain the drivers and keep     */
  73. /*                the BBS running.    There is a seperate license fee for the use          */
  74. /*                and distribution of MIDPAK drivers.                                                              */
  75. /*                                                                                                                                                     */
  76. /*                See accompaning documentation regarding license fees for MIDPAK      */
  77. /*                distribution.  You would be ill-advised to distribute a commercial */
  78. /*                product containing either DIGPAK and/or MIDPAK drivers without         */
  79. /*                having paid the distribution license fee.  Since your product would*/
  80. /*                contain unlicensed copyrighted software from The Audio Solution,     */
  81. /*                your product could be required to be immediately removed from retail*/
  82. /*                distribution.  I doubt this is going to be a problem.  Clearly if  */
  83. /*                your product is enhanced by the use of these drivers, your company */
  84. /*                can easily afford a nominal license fee of $500 in exchange for      */
  85. /*                getting the use of several man-years of software engineering             */
  86. /*                resources.                                                                                                                 */
  87. /*****************************************************************************/
  88.  
  89. /* Bit flags to denote audio driver capabilities. */
  90. /* returned by the AudioCapabilities call.                */
  91. #define PLAYBACK 1    // Bit zero true if can play audio in the background.
  92. #define MASSAGE  2    // Bit one is true if data is massaged.
  93. #define FIXEDFREQ 4   // Bit two is true if driver plays at fixed frequency.
  94. #define USESTIMER 8   // Bit three is true, if driver uses timer.
  95. #define SHARESTIMER 16 // Bit 4, timer can be shared
  96. #define STEREOPAN 64    // Bit 6, supports stereo panning.
  97. #define STEREOPLAY 128 // Bit 7, supports 8 bit PCM stereo playback.
  98. #define AUDIORECORD 256 // Bit 8, supports audio recording!
  99. #define DMABACKFILL 512  // Bit 9, support DMA backfilling.
  100. #define PCM16 1024            // Bit 10, supports 16 bit digital audio.
  101. #define PCM16STEREO 2048 // Bit 11, driver support 16 bit digital sound
  102. // All digpak drivers which support 16 bit digital sound ASSUME 16 bit
  103. // SIGNED data, whereas all 8 bit data is assumed UNSIGNED.  This correlates
  104. // exactly to the hardware specifcations for most all DMA driven PC sound
  105. // cards, including SB16, Gravis UltraSound and ProAudio Spectrum 16 sound cards.
  106.  
  107. typedef struct
  108. {
  109.     char *sound;         // address of audio data. IMPORANT SEE NOTE BELOW!!!!!!!!!!
  110.     unsigned short sndlen; // Length of audio sample.
  111.     short *IsPlaying; // Address of play status flag.
  112.     short frequency;    // Playback frequency. recommended 11khz.
  113. } SNDSTRUC;
  114.  
  115. /**  !!! IMPORTANT NOT REGARDING THE SOUND ENTRY IN THE SOUND STRUCTURE !!! **/
  116. /**  Since this sound structure is in the identical format as that used in    **/
  117. /**  real-mode, this entry is NOT a flat-model 32 bit address but in real     **/
  118. /**  mode offset:segment format, in the first 1mb of address space.  The        **/
  119. /**  sound effect cannot be greater than 64k in length!                                         **/
  120. /**  Use the DOSCALLS function call RealPtr to convert the 32 bit flat            **/
  121. /**  address into offset:segment format.    Example: snd->sound = RealPtr(data)*/
  122. /**  which will convert the low 1mb flat addres 'data' into offset:segment   */
  123. /**  format and store it into the 'sound' entry of the SNDSTRUC structure    */
  124. /**  pointed to by 'snd'.  'snd' MUST be in the first 1mb of address space as*/
  125. /**  well.    'snd' is passed as a flat-model address, and DIGPAK 3.4 drivers  */
  126. /**  will treat it as such so long as the SetDMPIMode has been set on.    This */
  127. /**  is done automatically by LOADER.C during the InitDigPak call.                     */
  128.  
  129. extern short    cdecl DigPlay(SNDSTRUC *sndplay); // 688h -> Play 8 bit digitized sound.
  130. extern short    cdecl SoundStatus(void);    // 689h -> Report sound driver status.
  131. extern void cdecl MassageAudio(SNDSTRUC *sndplay); // 68Ah -> Preformat 8 bit digitized sound.
  132. extern void cdecl DigPlay2(SNDSTRUC *sndplay); // 68Bh -> Play preformatted data.
  133. extern short    cdecl AudioCapabilities(void); // 68Ch -> Report audio driver capabilities.
  134. extern void cdecl StopSound(void); // 68Fh -> Stop current sound from playing.
  135. extern short    cdecl PostAudioPending(SNDSTRUC *sndplay);
  136.  
  137. #define NOTPLAYING 0  // No sound is playing.
  138. #define PLAYINGNOTPENDING 1 // Playing a sound, but no sound is pending.
  139. #define PENDINGSOUND 2            // Playing, and a sound is pending.
  140. extern short    cdecl AudioPendingStatus(void);
  141.  
  142. #define FULLRIGHT 0
  143. #define FULLLEFT 127
  144. #define FRONTANDCENTER 64
  145. extern short    cdecl SetStereoPan(short panvalue); // 0-127, 0 full right.
  146.                                                                 //             64 full volume both.
  147.                                                                 //            127 full volume left.
  148.  
  149.  
  150. #define PCM_8_MONO 0
  151. #define PCM_8_STEREO 1
  152. #define PCM_16_MONO 2
  153. #define PCM_16_STEREO 3
  154. extern short cdecl SetPlayMode(short playmode);
  155. // Return 0 if mode not available, 1 if mode set.
  156.  
  157. extern short cdecl SetRecordMode(short mode); // Set audio recording mode.
  158.  
  159. extern short * cdecl PendingAddress(void); // Reports the far address of the pending
  160. // flag.    If this memory location pointed to by this address is 1 that means
  161. // a pending sound effect is still pending.  When this becomes zero, then your
  162. // application software can post the next piece of audio to play.  It is
  163. // preferable to use this semaphore to know when to post the next buffer
  164. // rather than to use the AudioPendingStatus call.
  165.  
  166. extern short * cdecl ReportSemaphoreAddress(void); // Reports the far address of the DigPak
  167. // semaphore.  If this semaphore is true, then DigPak is currently active
  168. // and you shouldn't post any DigPak calls.  This is EXTREMELY important if
  169. // you are trying to invoke DigPak functions via a hardware interrupt, where
  170. // you could potentially have interrupted DigPak itself.
  171.  
  172. extern short cdecl ReportVersionNumber(void); // Report the DigPak version number.
  173. // Return code is times 100, meaning that version 3.1 would be returned
  174. // as the decimal number 310.  This function wasn't supported prior to
  175. // version 3.1 release, so it will be returned as 0, for versions prior
  176. // to 3.1.
  177.  
  178. extern short cdecl SetBackFillMode(short mode); // Turn DMA backfill mode on/off, return code
  179. // of 1 means mode was set.  Return code of 0 means driver doesn't support
  180. // DMA backfill.
  181.  
  182. extern unsigned short cdecl ReportDMAC(void); // Report current DMA counter.
  183.  
  184. extern short cdecl VerifyDMA(char *data,short length); // Verify this buffer block
  185. // doesn't cross a 64k boundary.  Return code of 1 means the block is OK.
  186. // return code of 0 means the block can't be used, try another.
  187.  
  188. extern void cdecl NullSound(char *sound,short sndlen,short null);
  189.  
  190. /* Support routines */
  191. extern void cdecl WaitSound(void); // Wait until sound playback completed.
  192. extern short    cdecl CheckIn(void);     // Is sound driver available? 0 no, 1 yes.
  193.  
  194. extern void cdecl SetDPMIMode(short mode); // Set DPMI addressing mode for DIGPAK
  195.  
  196. extern void cdecl DigPakIdentityString(char *str);
  197.  
  198. extern short    cdecl InitDP(char *digpak); // Bootstrap hardware.
  199. extern void cdecl DeInitDP(char *digpak); // Uninitialize DIGPAK
  200.