home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 25 / CD_ASCQ_25_1095.iso / dos / prg / dwstk200 / dws.bi next >
Text File  |  1995-08-01  |  11KB  |  274 lines
  1. '******************************************************************************
  2. 'File:      dws.bi
  3. 'Version:   2.00
  4. 'Tab stops: every 2 columns
  5. 'Project:   The Sound ToolKit
  6. 'Copyright: 1994-1995 DiamondWare, Ltd.  All rights reserved.
  7. 'Written:   by Erik Lorenzen, Keith Weiner, and Don Lemons
  8. 'Purpose:   Contains declarations for the DW Sound ToolKit
  9. 'History:   94/08/24 DL Started translation
  10. '           94/08/30 KW Modified
  11. '           94/11/12 DL Re-Translated
  12. '           94/11/26 EL Edited for clarity and funtionality
  13. '           94/11/27 EL Finalized for 1.0
  14. '           95/03/19 EL Finalized for 1.01, Added new CONST dwsBUSY
  15. '           95/04/06 EL Finalized for 1.02, Added new define dwsIRQDISABLED
  16. '           95/06/06 EL Finalized for 1.03, (no changes)
  17. '           95/07/23 EL Finalized for 1.04, (no changes)
  18. '           95/08/01 EL Finalized for 2.00, (no changes)
  19. '
  20. '******************************************************************************
  21.  
  22.  
  23.  
  24. '******************************************************************************
  25. ' The following is the complete list of possible values for dwsErrNo.
  26. ' dwsErrNo may be set by any dws function.  Check its value whenever
  27. ' the return value of a dws function is 0 (error).
  28.  
  29. CONST dwsEZERO                                                    =  0
  30.  
  31. ' The following 3 errors may be triggered by any dws function
  32. CONST dwsNOTINITTED                                         =  1
  33. CONST dwsALREADYINITTED                                 =  2
  34. CONST dwsNOTSUPPORTED                                     =  3
  35.  
  36. 'The following 4 errors may be triggered by dwsDetectHardWare
  37. CONST dwsDetectHardwareUNSTABLESYSTEM     =  4
  38. CONST dwsDetectHardwareBADBASEPORT            =  5
  39. CONST dwsDetectHardwareBADDMA                     =  6
  40. CONST dwsDetectHardwareBADIRQ                     =  7
  41.  
  42. 'The following error may be triggered by dwsKill
  43. CONST dwsKillCANTUNHOOKISR                            =  8
  44.  
  45. 'The following error may be triggered by any dwsX (mixer) function
  46. CONST dwsXBADINPUT                                            =  9
  47.  
  48. 'The following 3 errors may be triggered by any dwsD (dig) function
  49. CONST dwsDNOTADWD                                             =  10
  50. CONST dwsDNOTSUPPORTEDVER                             =  11
  51. CONST dwsDINTERNALERROR                                 =  12
  52.  
  53. 'The following error may be triggered by dwsDPlay
  54. CONST dwsDPlayNOSPACEFORSOUND                     =  13
  55.  
  56. 'The following 2 errors may be triggered by dwsDSetRate
  57. CONST dwsDSetRateFREQTOLOW                            =  14
  58. CONST dwsDSetRateFREQTOHIGH                         =  15
  59.  
  60. 'The following 3 errors may be triggered by dwsMPlay
  61. CONST dwsMPlayNOTADWM                                     =  16
  62. CONST dwsMPlayNOTSUPPORTEDVER                     =  17
  63. CONST dwsMPlayINTERNALERROR                         =  18
  64.  
  65. 'The following error may be triggered by any dws_ function
  66. '(except dws_ErrNo and dws_Init) if called from an Interrupt
  67. 'Service Routine (ISR).  If you're not sure whether this applies
  68. 'to you: it probably doesn't.
  69. CONST dwsBUSY                                                     =  19
  70.  
  71. 'The following error may be triggered by dws_Init, dws_Kill,
  72. 'and dws_DetectHardware.  It will only occur if interrupts are
  73. 'disabled.  Interrupts must be enabled when calling.  If you're
  74. 'not sure whether this applies to you: it probably doesn't.
  75. CONST dwsIRQDISABLED                                        =  20
  76.  
  77.  
  78. '------------------------------------------------------------------------------
  79.  
  80.  
  81. 'The follwing section defines bitfields which are used by various
  82. 'dws functions.  Each bit in a bitfield, by definition, may be
  83. 'set/reset independantly of all other bits.
  84.  
  85. 'The following 2 consts indicate the capabilities of the user's hardware
  86. CONST dwscapabilityFM                                     =  1
  87. CONST dwscapabilityDIG                                    =  2
  88.  
  89. 'The following 2 consts indicate the status of specified digital sounds
  90. CONST dwsDSOUNDSTATUSPLAYING                        =  1
  91. CONST dwsDSOUNDSTATUSSEQUENCED                    =  2
  92.  
  93. 'The following 2 consts indicate the status of music playback
  94. CONST dwsMSONGSTATUSPLAYING                         =  1
  95. CONST dwsMSONGSTATUSPAUSED                            =  2
  96. '******************************************************************************
  97.  
  98.  
  99.  
  100. 'The following section TYPEs the structs used by the STK.  In each
  101. 'case, the user must create an instance of the struct prior to making
  102. 'a call to an STK function which takes a pointer to it.  The STK does
  103. 'not keep a pointer to any of these structs internally; after the call
  104. 'returns, you may deallocate it, if you wish.
  105.  
  106.  
  107. 'NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  108.  
  109.  
  110. 'dws_DetectHardWare can be told _not_ to autodetect particular values
  111. 'about the installed hardware.  This is useful if detecting DMA channel,
  112. 'for example, consistently causes a machine lockup.  To override the
  113. 'autodetect for a setting, set the corresponding field in this struct
  114. 'to the correct value.  Otherwise, set the field to ffff hex.  Since
  115. 'the autodetect is reliable, this is the recommended course of action,
  116. 'except in cases of known problems.
  117. TYPE dwsDETECTOVERRIDES
  118.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  119.  
  120.     digdma         AS INTEGER          'DMA channel
  121.     digirq         AS INTEGER          'IRQ level
  122.  
  123.     reserved     AS STRING * 10  'reserved
  124.  
  125. END TYPE
  126.  
  127.  
  128. 'A pointer to this struct is passed to dwsDetectHardWare, which fills
  129. 'it in.  It is then passed unmodified to dwsInit.  If you plan on
  130. 'writing this struct out to a file, it's important that you write
  131. 'the entire contents.  There is information (for internal STK use only)
  132. 'in the reserved[] field!
  133. TYPE dwsDETECTRESULTS
  134.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  135.     capability AS INTEGER          'see CONSTs, above
  136.  
  137.     'The following 3 fields are only valid if FM music is supported
  138.     mustyp         AS INTEGER          '0=none, 1=OPL2
  139.     musnchan     AS INTEGER          '1=mono
  140.     musnvoice  AS INTEGER          'number of voices supported by hardware (11 for FM)
  141.  
  142.     'The following 2 fields are only valid if digitized sound is supported
  143.     dignbits     AS INTEGER          '0=none, 8=8 bit
  144.     dignchan     AS INTEGER          '1=mono
  145.  
  146.     digdma         AS INTEGER          'DMA channel
  147.     digirq         AS INTEGER          'IRQ level
  148.  
  149.     mixtyp         AS INTEGER          '1=software, 2+ is hardware
  150.  
  151.     reserved     AS STRING * 44  'there are important values in here...
  152.  
  153. END TYPE
  154.  
  155.  
  156. 'A pointer to this struct is passed as a parameter to dws_Init.  This
  157. 'allows the user to tell the STK to use less than the full capabilities
  158. 'of the installed sound hardware, and/or the user's sound board
  159. 'may not support every feature of the STK.
  160. TYPE dwsIDEAL
  161.     musictyp     AS INTEGER          '0=No Music, 1=OPL2
  162.  
  163.     digtyp         AS INTEGER          '0=No Dig, 8=8bit
  164.     digrate      AS INTEGER          'sampling rate, in Hz
  165.     dignvoices AS INTEGER          'number of voices (up to 16)
  166.     dignchan     AS INTEGER          '1=mono
  167.  
  168.     reserved     AS STRING * 6
  169.  
  170. END TYPE
  171.  
  172.  
  173. 'A pointer to this struct is passed to dwsDPlay.
  174. 'Note that the soundnum field is filled in by dws_DPlay as a return value.
  175. TYPE dwsDPLAY
  176.     snd              AS LONG                 'pointer to buffer which holds a .DWD file
  177.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  178.     priority     AS INTEGER          'higher numbers mean higher priority
  179.     presnd         AS INTEGER          'soundnum to sequence sound _after_
  180.     soundnum     AS INTEGER          'dws_DPlay returns a snd number from 10-65535
  181.  
  182.     reserved     AS STRING * 20
  183.  
  184. END TYPE
  185.  
  186.  
  187. 'A pointer to this struct is passed to dwsMPlay.
  188. TYPE dwsMPLAY
  189.     track          AS LONG                 'pointer to buffer which holds a .DWM file
  190.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  191.  
  192.     reserved     AS STRING * 10
  193.  
  194. END TYPE
  195. '******************************************************************************
  196.  
  197.  
  198. '******************************************************************************
  199.  
  200. 'This function is callable at any time.  It returns the number of the
  201. 'last error which occured.
  202. DECLARE FUNCTION dwsErrNo%                     ALIAS "DWS_ERRNO"                    ()
  203. '------------------------------------------------------------------------------
  204.  
  205.  
  206. 'This subroutine is called at the end of the timer ISR (interrupt service
  207. 'routine).  If you're using the optional DWT (DW Timer), this happens
  208. 'automagically.  If you wrote your own timer handler routine, you must
  209. 'call this function regularly.
  210. DECLARE SUB          dwsUpdate                     ALIAS "DWS_UPDATE"                 ()
  211. '------------------------------------------------------------------------------
  212.  
  213.  
  214. 'The following functions have boolean return values.  A return of 0 (false)
  215. 'indicates an error.  If this occurs, check dwsErrNo for more info.
  216. DECLARE FUNCTION dwsDetectHardWare%  ALIAS "DWS_DETECTHARDWARE" (SEG dov AS dwsDetectOverrides, SEG dres AS dwsDetectResults)
  217.  
  218. DECLARE FUNCTION dwsInit%                      ALIAS "DWS_INIT"                     (SEG dres AS dwsDetectResults, SEG idl AS dwsIdeal)
  219.  
  220.  
  221. 'If the program has called dws_Init, it _MUST_ call dws_Kill before it
  222. 'terminates.
  223. '
  224. 'NB: Trap critical errors.  Don't let DOS put up the
  225. '    "Abort, Retry, Fail?" text.  ('sides, it'll destroy your pretty gfx)
  226. DECLARE FUNCTION dwsKill%                      ALIAS "DWS_KILL"                     ()
  227.  
  228.  
  229. 'The following 3 functions comprise the mixer section of the STK.  A
  230. 'value of 0 turns a channel off; a value of 255 is the loudest.
  231. DECLARE FUNCTION dwsXMaster%                 ALIAS "DWS_XMASTER"                (BYVAL volume%)
  232.  
  233. DECLARE FUNCTION dwsXMusic%                  ALIAS "DWS_XMUSIC"                 (BYVAL volume%)
  234.  
  235. DECLARE FUNCTION dwsXDig%                      ALIAS "DWS_XDIG"                     (BYVAL volume%)
  236.  
  237.  
  238. 'The following 10 functions comprise the digitized sound functions of
  239. 'the STK.  See the documentation for complete details.
  240. DECLARE FUNCTION dwsDPlay%                     ALIAS "DWS_DPLAY"                    (SEG dply AS dwsDPlay)
  241.  
  242. DECLARE FUNCTION dwsDSoundStatus%      ALIAS "DWS_DSOUNDSTATUS"     (BYVAL soundnumber%, SEG result%)
  243.  
  244. DECLARE FUNCTION dwsDSetRate%              ALIAS "DWS_DSETRATE"             (BYVAL frequency%)
  245.  
  246. DECLARE FUNCTION dwsDGetRate%              ALIAS "DWS_DGETRATE"             (SEG result%)
  247.  
  248. 'This function is callable at any time.
  249. DECLARE FUNCTION dwsDGetRateFromDWD% ALIAS "DWS_DGETRATEFROMDWD"(BYVAL pointer&, SEG result%)
  250.  
  251. DECLARE FUNCTION dwsDDiscard%              ALIAS "DWS_DDISCARD"             (BYVAL soundnum%)
  252.  
  253. DECLARE FUNCTION dwsDDiscardAO%          ALIAS "DWS_DDISCARDAO"         (BYVAL pointer&)
  254.  
  255. DECLARE FUNCTION dwsDClear%                  ALIAS "DWS_DCLEAR"                 () 'Affects all sounds
  256.  
  257. DECLARE FUNCTION dwsDPause%                  ALIAS "DWS_DPAUSE"                 () 'Affects all sounds
  258.  
  259. DECLARE FUNCTION dwsDUnPause%              ALIAS "DWS_DUNPAUSE"             () 'Affects all sounds
  260.  
  261.  
  262. 'The following 5 functions comprise the music functions of the STK.
  263. 'See the documentation for complete details.
  264. DECLARE FUNCTION dwsMPlay%                     ALIAS "DWS_MPLAY"                    (SEG mply AS dwsMPlay)
  265.  
  266. DECLARE FUNCTION dwsMSongStatus%         ALIAS "DWS_MSONGSTATUS"        (SEG result%)
  267.  
  268. DECLARE FUNCTION dwsMClear%                  ALIAS "DWS_MCLEAR"                 ()
  269.  
  270. DECLARE FUNCTION dwsMPause%                  ALIAS "DWS_MPAUSE"                 ()
  271.  
  272. DECLARE FUNCTION dwsMUnPause%              ALIAS "DWS_MUNPAUSE"             ()
  273. '******************************************************************************
  274.