home *** CD-ROM | disk | FTP | other *** search
/ The Disc (Australian) 2 / TheDiscIssue2.iso / demos / lem3d / sound / drivers / drivers.doc < prev    next >
Encoding:
Text File  |  1994-11-05  |  18.0 KB  |  477 lines
  1.  
  2.  
  3. ;   P.C. Sound card 'Generation 2' music & sound effect drivers
  4.  
  5. ;   (c) 1992-94 Tony Williams / Sound Images
  6.  
  7.  
  8. ;   start date    01.05.92
  9. ;   version         1.11x 
  10. ;   version date  27.10.94
  11.  
  12.  
  13.  
  14. ;   Overview
  15. ;   --------
  16.  
  17. ;   The drivers are supplied as a binary image , which is intended to be loaded
  18. ;   at the start of a normalised segment by the programmer . ( That means that
  19. ;   the code is at address zero in the segment , on a paragraph boundary ) .
  20. ;   All memory allocation etc. has to be controlled by the programmer , and no
  21. ;   tests are made to determine whether the file is complete in memory , or has
  22. ;   been overwritten .
  23.  
  24. ;   A separate file is supplied for each sound format supported , which can be
  25. ;   accessed without knowledge of which sound card is being used . All functions
  26. ;   of the driver are invisible to the programmer and problems which occur
  27. ;   between different sound hardware are tackled within the driver . Obviously ,
  28. ;   a simple internal bleeper cannot handle as many channels simultaneously as
  29. ;   a sound card , but the driver code should make these problems unimportant
  30. ;   to the programmer .
  31.  
  32.  
  33. ;   Installing the drivers
  34. ;   ----------------------
  35.  
  36. ;   BEWARE :-
  37.  
  38. ;   Auto-detection has been causing some problems . In discussion with several
  39. ;   other musician/programmers it has been established that no guarantee can be
  40. ;   given that auto-detection will work on all combinations of hardware in all
  41. ;   machines . A figure of ninety-something percent success appears universal ,
  42. ;   but it is always best to ask the user for some input for information on port
  43. ;   addresses . The Soundblaster card has been the worst offender up to now ,
  44. ;   but as sound cards become more and more sophisticated , I expect more and
  45. ;   larger problems to arise ( Multi-Media / CD-ROMS etc. will all use differing
  46. ;   irq's DMA channels ad-nauseam )
  47.  
  48. ;   In keeping with the aim of making things easy for the programmer (that's the
  49. ;   theory , at least ) auto-detection is available , but can be overridden on
  50. ;   any or all of the modules as the programmer chooses . I strongly advise a
  51. ;   menu and a configuration file which can keep the players' choices . This is,
  52. ;   in my opinion the most satisfactory ( and fool-proof ) option . For more
  53. ;   details on auto-detection within the drivers , see the initialise function
  54. ;   below .
  55.  
  56.  
  57.  
  58. ;   Accessing driver functions
  59. ;   --------------------------
  60.  
  61. ;   At the start of the file ( at offsets 0 and 4 ) there are two entry points
  62. ;   to the sound service routine . At offset zero is the entry point you should
  63. ;   call via a CALL DWORD , and at offset 4 is the entry point to be called from
  64. ;   a software interrupt . This version returns with an IRET so do not use this
  65. ;   except via a software interrupt .
  66.  
  67. ;   The start of the file looks like this :-
  68.  
  69. ;far_call_entry:        call    music_service        ; service the call
  70. ;                       retf                         ; forced FAR return
  71.  
  72. ;int_call_entry:        call    music_service
  73. ;                       iret                         ; INTERRUPT return
  74.  
  75.  
  76. ;   Music_service is called with AH holding a function number - these are listed
  77. ;   below . In most cases other parameters are passed in AL , and in a few extra
  78. ;   parameters where necessary . In most cases , AL will return an error code .
  79. ;   If AL returns a 0 ( zero ) then the function has been processed successfully .
  80. ;   If AL holds any other value , there has been an error of some sort .
  81. ;   See below for details .
  82. ;   In all cases , all registers except AX are preserved . Expect AH to be
  83. ;   corrupt unless specified as a returned parameter by the function .
  84.  
  85. ;****************
  86. ;Driver functions
  87. ;****************
  88.  
  89. ;-----------------------
  90. ;Function 0 - Initialise
  91. ;-----------------------
  92.  
  93. ;   entry : ah = 0
  94.  
  95. ;       dx = port address \
  96. ;       ch = DMA channel    if dx = zero driver will attempt auto-detect ,
  97. ;       cl = irq level    /         ignoring these values
  98.  
  99. ;   exit :  al = 0 if initialise ok
  100. ;           al = 1 if initialise failed ( e.g sound card not available )
  101. ;           al = 2 on Soundblaster if FM sound is ok , but DSP gave an error
  102. ;           al = 3 on multi-channel Soundblaster driver found invalid samples file
  103.  
  104. ;   This function is very important ! Until this function has been successfully
  105. ;   completed , NO OTHER FUNCTIONS WILL OPERATE . If another function is
  106. ;   accessed without Initialisation , ax will return -2 .
  107. ;   It is important to note that on the Roland LAPC-1 card , Initialise takes
  108. ;   several seconds if a large bank of sounds has to be downloaded , using the
  109. ;   MIDI bus ( 31250 baud serial ) .
  110. ;   On some cards , an irq is generated for some data transfers . In these
  111. ;   cases , the interrupt level is established during Initialise and the
  112. ;   relevant irq is re-vectored . Be careful not to disable the irq in
  113. ;   register 21h which may be used during sample playback etc.
  114.  
  115. ;   If Initialise is entered with zero in dx , auto-detection will be
  116. ;   attempted , and ch/cl will be ignored .
  117. ;   If dx holds any non-zero value , it is taken to be an I/O port address for
  118. ;   the particular sound card . Be very careful here , as all the cards have a
  119. ;   different I/O address ( except for Adlib compatibles ) and entering with a
  120. ;   non-zero value which isn't the correct address will give you at best a
  121. ;   silent output , and at worst , a crash or hang .
  122.  
  123. ;   The I/O port / irq / DMA available values are as follows .
  124.  
  125. ;       I/O port base address        irq                   DMA
  126.  
  127. ;  Adlib        388h               not used             not used
  128.  
  129. ;  Roland       330h               not used but         not used
  130. ;                             various are available
  131. ;                                 on the hardware
  132.  
  133.  
  134. ;  Soundblaster 210h               2/3/5 or 7 (default)    1
  135. ;               220h (default)
  136. ;               230h
  137. ;               240h
  138. ;               250h
  139. ;               260h
  140. ;               270h
  141.  
  142. ;  Soundblaster Pro / 16
  143. ;               220h (default)     2/7/10 or 5 (default)   0/3 or
  144. ;               240h                                        1 (default)
  145.  
  146.  
  147. ;  Gravis Ultrasound/Max
  148. ;               If you are using Ultramid.exe then this will read the
  149. ;               settings from the enviroment string.
  150.  
  151. ;  AWE 32
  152.  
  153. ;-------------------
  154. ;Function 1 - Remove
  155. ;-------------------
  156.  
  157. ;   entry : ah = 1
  158.  
  159. ;   exit :  al = 0 if removed ok
  160. ;           al = 1 if remove encountered an error ( unlikely )
  161. ;           ah = corrupt
  162.  
  163. ;  Where interrupt vectors have been altered for DMA or similar , Remove sets
  164. ;  them back to the state they were in before Initialise , also prohibiting
  165. ;  other functions . Note that Remove does not remove the driver from memory ,
  166. ;  or the timer imterrupts , that is up to you , the game programmer .
  167.  
  168. ;---------------------------
  169. ;Function 2 - Set Timer Rate
  170. ;---------------------------
  171.  
  172. ;  entry : ah = 2
  173. ;  cx = timer rate constant
  174.  
  175. ;  exit :  al = 0 if timer rate calculations were successful
  176. ;          al = 1 if an error occurred , e.g timer rate out of range
  177. ;          ah = corrupt
  178.  
  179. ;  It has always been a problem with music drivers in games that the game takes
  180. ;  obvious priority over the music . e.g. if the game needs a particular rate
  181. ;  timer interrupt , the music has be called at that speed . This obviously
  182. ;  gives rise to big problems with musical tempo . These drivers use a
  183. ;  semi-intelligent system which appears < so far > to the ear to play the
  184. ;  music accurately at a large range of timer rates . I have not tested to
  185. ;  extremes , but I expect most game programmers to prefer a 60Hz or 70Hz
  186. ;  timer , which is the same rate as the monitor frame update . This would
  187. ;  approximate to a timer constant of 4277h which is the default for the
  188. ;  drivers . NOTE that this function only informs the driver the timer rate
  189. ;  you are calling the sound update , it DOES NOT SET ANY HARDWARE TIMER
  190. ;  REGISTERS OR VECTORS .
  191.  
  192. ;  This function finds it necessary to disable interrupts while it performs
  193. ;  some calculations , to avoid being interrupted by the update routine which
  194. ;  may attempt to play some music with the internal speed constants
  195. ;  half-calculated . The state of the interrupt enable is preserved by PUSHF
  196. ;  and POPF commands .
  197.  
  198. ;  For those who are unfamiliar with the timer hardware , the constant can be
  199. ;  calculated thus : 1192180 < the timer clock rate > / call rate in Hz .
  200.  
  201. ;  There is obviously some difference between video cards / monitors , as I
  202. ;  calculate my monitor to run at a rate equivalent to a 4277h timer constant ,
  203. ;  which is why the drivers default to that , although the formula above gives
  204. ;  a value of 4287h . It may be that the time between an interrupt request
  205. ;  being generated and that interrupt being serviced is 'lost' . Anyone who
  206. ;  knows more about this , please let me know .
  207.  
  208.  
  209. ;  common values for CX on entry :-
  210.  
  211. ;       70 Hz  = 4287h   (approx VGA video update rate)
  212. ;       60 Hz  = 4D9Dh   (approx EGA video update rate)
  213. ;       50 Hz  = 5D23h   (approx CGA / Tandy video update rate)
  214.  
  215. ;-------------------
  216. ;Function 3 - Update
  217. ;-------------------
  218.  
  219. ;  entry : ah = 3
  220.  
  221. ;  exit :  al = 0 if everything ok
  222. ;          al = 1 if an error occurred , in most cases an error will stop
  223. ;               all sound ( the exceptions would probably crash !! )
  224. ;          ax = -2 if call attempts re-entry , i.e. routine interrupts itself .
  225.  
  226. ;  This is the "refresh" function which is mostly called at 50Hz on other
  227. ;  machines . These drivers are designed to process all tunes and effects
  228. ;  within this routine to avoid the problems which may occur when Update
  229. ;  interrupts another music function .
  230.  
  231.  
  232. ;------------------------------
  233. ;Function 4 - Initialise a tune
  234. ;------------------------------
  235.  
  236. ;  entry : ah = 4
  237. ;  al = tune number , from 1 upwards
  238.  
  239. ;  exit :  al = 0 if everything ok
  240. ;          al = 1 if an error occurred , usually tune number out of range
  241.  
  242.  
  243. ;  This function "cues up" a tune to start the next time the driver is updated .
  244.  
  245.  
  246.  
  247. ;---------------------------
  248. ;Function 6 - Stop all sound
  249. ;---------------------------
  250.  
  251. ;  entry : ah = 6
  252.  
  253. ;  exit :  al = 0 if everything ok
  254. ;          al = 1 if an error occurred . Very , very unlikely
  255.  
  256.  
  257. ;  This function stops all tunes and sound effects .
  258.  
  259. ;------------------------
  260. ;Function 7 - Stop a tune
  261. ;------------------------
  262.  
  263. ;  entry : ah = 7
  264.  
  265. ;  exit :  al = 0 if everything ok
  266. ;          al = 1 if an error occurred . Very , very unlikely
  267.  
  268.  
  269. ;  This function stops the current tune but NOT sound effects .
  270.  
  271.  
  272. ;-------------------------------------
  273. ;Function 9 - Ask if a tune is playing
  274. ;-------------------------------------
  275.  
  276. ;  entry : ah = 9
  277.  
  278. ;  exit :  al = number of the current tune
  279. ;          al = 0 if NO tune is playing
  280.  
  281. ;  All this function does is : mov al,[current tune] , and returns .
  282.  
  283.  
  284.  
  285. ;------------------------------------------------
  286. ;Function 11 - Count how many effects are running
  287. ;------------------------------------------------
  288.  
  289. ;  entry : ah = 11
  290.  
  291. ;  exit :  al = how many effects are playing
  292.  
  293.  
  294. ;  This function just counts how many tracks are running effects .
  295.  
  296.  
  297. ;-------------------------------------------
  298. ;Function 12 - fetch offset of format string
  299. ;-------------------------------------------
  300.  
  301. ;  entry : ah = 12
  302.  
  303. ;  exit :  bx = offset within the segment where an ASCIIz string is , which tells
  304. ;               you which format the driver supports (Adlib/Soundblaster etc.)
  305. ;          al = 0 if function performed ok
  306.  
  307.  
  308. ;--------------------------------------------
  309. ;Function 13 - fetch offset of version string
  310. ;--------------------------------------------
  311.  
  312. ;  entry : ah = 13
  313.  
  314. ;  exit :  bx = offset within the segment where an ASCIIz string is , which tells
  315. ;               you which version of the driver this is ( v1.09 22.12.93 ) .
  316. ;               al = 0 if function performed ok
  317.  
  318. ;-----------------------------------------
  319. ;Function 14 - set the volume of an effect
  320. ;-----------------------------------------
  321.  
  322. ;  entry : ah = 14
  323. ;          al = effect number
  324. ;          cl = volume 0-7Fh
  325.  
  326. ;  exit :  al = 0 if volume set
  327. ;          al = 1 if effect is not running
  328.  
  329. ;  Sets the volume of the channel which is running the effect in AL .
  330.  
  331. ;------------------------------
  332. ;Function 15 - start a fade-out
  333. ;------------------------------
  334.  
  335. ;  entry : ah = 15
  336. ;          cx = number of update calls fade-out should take
  337.  
  338. ;  exit :  al = 0 if calculated successfully
  339.            al = 1 if calculation gave an error
  340.  
  341. ;  The value in cx is used to calculate how much the volume should decrease each
  342. ;  frame . This is only an approximate value , as different sound cards will
  343. ;  sound different at different volumes , and the fade will definitely not sound
  344. ;  the same on each card . In particular , it may seem that the sound is
  345. ;  inaudible when the volume is still at around 20% . However , a simple fade is
  346. ;  far preferable to a sudden stop , so try using a fade over a period of around
  347. ;  3 or 4 seconds , rather than just stopping the tune . To determine whether
  348. ;  the fade has completed , use the ASK_TUNE function which will return a zero
  349. ;  in AL when the tune has been faded completely and then switched off .
  350.  
  351. ;  WARNINGS :   As this function uses a MASTER volume control , it fades out
  352. ;               both tunes and sound effects .
  353. ;               On certain sound cards , including Adlib , the extra processing
  354. ;               needed to output volumes every frame may be considerable .
  355.  
  356. ;---------------------------------------------
  357. ;Function 16 - set multi-channel playback rate
  358. ;---------------------------------------------
  359.  
  360. ;  entry : ah = 16
  361. ;          cx = playback frequency in Hz ( default is 11025 )
  362.  
  363. ;  exit :  al = 0 if playback rate set successfully
  364. ;          al = 1 if driver is not multi-channel sample player
  365. ;          al = 2 if calculation gave an error
  366. ;          cx = playback frequency set by the driver in Hz . See note below .
  367.  
  368. ;  This function is specific to the Soundblaster multi-channel sample player ,
  369. ;  and sets up the rate at which the samples are combined and output .
  370. ;  The  higher the rate , the better the sound , and the more processor time
  371. ;  is used .
  372.  
  373. ;  N.B. The Adlib Gold Card ( and maybe others in the future ) can only play
  374. ;  back at a few fixed rates . The driver finds the nearest available one to
  375. ;  that requested .
  376. ;  Available rates for Adlib Gold are 44100,22050,11025 and 7350 Hz .
  377. ;  I suggest that 11025 Hz is a good compromise between processor time and
  378. ;  sound quality ( and also should be supported by all future additions ! )
  379.  
  380. ;----------------------------------
  381. ;Function 17 - play a single sample
  382. ;----------------------------------
  383.  
  384. ;  entry : ah = 17
  385. ;          al = channel number 0-3
  386. ;          es:di = REAL MODE segment:offset of sample
  387. ;          cl = volume 0-7Fh
  388. ;          N.B. sample data must NOT cross a segment boundary , as the
  389. ;               processing overhead to check this would amount to around 500
  390. ;               extra opcodes per frame . Yes , there is a good reason for
  391. ;               having these awkward restrictions !!!!
  392.  
  393. ;  exit :  al = 0 if sample started ok
  394. ;          al = 1 if samples not supported on this format
  395. ;          al = 2 if channel number out of range
  396. ;          al = -1 if function was not in range of driver
  397. ;          al = 3 if any other error
  398.  
  399. ;  the normal multi-channel stuff still applies
  400.  
  401.  
  402. ;---------------------------
  403. ;Function 18 - stop a sample
  404. ;---------------------------
  405.  
  406. ;  entry : ah = 18
  407. ;          al = channel number 0-3
  408.  
  409. ; Stop the sample currently playing on channel al
  410.  
  411. ;-----------------------------------------
  412. ;Function 19 - get sample pointer position
  413. ;-----------------------------------------
  414.  
  415. ;  entry : ah = 19
  416. ;          al = channel number 0-3
  417.  
  418. ;  exit :  bx = current pointer within sample , of data next to be output
  419.  
  420. ;  returns bx as the address within the sample where the output routine has
  421. ;  reached . This can be used to determine whether a particular channel is
  422. ;  playing a sample , as the return value of -1 will always signify a channel
  423. ;  which is stopped .
  424.  
  425. ;---------------------------------
  426. ;Function 20 - set sample channels
  427. ;---------------------------------
  428.  
  429. ;  entry : ah = 20
  430. ;          al = how many channels 1/2/4
  431.  
  432. ;  exit :  al = 0 if channels set ok
  433. ;          al = 1 if invalid number of channels requested
  434.  
  435. ;  The routine which combines samples can be set to handle 1 , 2 , or 4 channels
  436. ;  at a time . There are some points to note here :-
  437. ;  If output is set to 1 or 2 channels , the others are ignored , and no error
  438. ;  is generated . Channels are processed in the normal way , except for the main
  439. ;  output routine . Obviously more channels = more processing .
  440. ;  This function silences all channels .
  441.  
  442. ;------------------------------
  443. ;Function 21 - set sample pitch
  444. ;------------------------------
  445.  
  446. ;  entry : ah = 21
  447. ;          al = channel 0-3
  448. ;          bx = new frequency in Hertz
  449. ;          cx = note frequency in Hertz (262 approximates to middle C
  450. ;                                        440 is international A )
  451.  
  452.  
  453. ;  exit :  al = 0 if pitch set ok
  454. ;          al = 1 if calculation gave out-of-range value
  455.  
  456. ;  The output routine steps through the data at a rate calculated relative to
  457. ;  processing speed , sample rate etc . This bodge just sets the sample rate
  458. ;  value , which is usually fetched from the sample header , to any value
  459. ;  you fancy , in Hertz .
  460.  
  461. ;-------------------------------
  462. ;Function 22 - set master volume
  463. ;-------------------------------
  464.  
  465. ;  entry : ah = 22
  466. ;          cx = volume level , maximum value is 256 , and minimum 0 .
  467.  
  468. ;  exit :  al = 0 if volume set ok
  469. ;          al = 1 if some sort of error occurred
  470.  
  471. ;  N.B. this function does not affect the volume of samples
  472.  
  473.    This function only applies to the ordinary soundblaster and to none of the
  474.    other cards.
  475.  
  476. ; end of DRIVERS.DOC file
  477.