NOTES.TXT 55 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714
  1. Apogee Sound System
  2. Version 1.09
  3. by Jim Dos‚
  4. Revision notes
  5. When your game is in beta, you must fax me your beta reports with sound
  6. problems since I will not see them otherwise.
  7. Please be sure to include my name in the credits for your program. I'm
  8. not asking for a design or game programming credit, just credit for the
  9. sound system. This includes the credits screen, the manual, and the
  10. text files accompanying the game (if the credits for the game are listed
  11. in them). Thank you.
  12. NOTE: make sure that you unzipped the zip file using the "-d"
  13. parameter. This will create some directories that the demo needs.
  14. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  15. ³ Known problems: ³
  16. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  17. - GUS may crash on systems with a VMM since the GUS code does not lock
  18. any of its allocated memory.
  19. - GUS only supports IRQs below 8. At higher IRQs, the dos extender seems
  20. to be too slow.
  21. - PAS mixer does not have a linear sounding volume change.
  22. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  23. ³ To-do list: ³
  24. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  25. - Add support for playback of stereo sounds. If anyone needs this
  26. right away, let me know.
  27. - Add permanant debugging code to various modules.
  28. - If an error occurs loading a patch file, GUS code should return
  29. which file it is.
  30. - Finish this doc file. Music functions have to be documented using the
  31. new format.
  32. - Change current limit of one upper IRQ.
  33. - Get upper IRQ's working for GUS code.
  34. - Lock memory in GUS code.
  35. - Test code on OS/2 and Windows
  36. - Lookup table for PAS mixer for more linear volume change.
  37. - MOD music playback.
  38. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  39. ³ Revision History: ³
  40. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  41. 5/14/96
  42. - Version 1.12
  43. - Fixed a reverb bug where 8-bit fast reverb would round down to -infinity
  44. instead of 0. This caused a bit of noise since the mix buffer would
  45. only reduce down to -1 and 0.
  46. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  47. 5/10/96
  48. - Version 1.11
  49. - added function FX_EndLooping to break a looping sound out of its loop.
  50. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  51. 1/16/96
  52. - Modified Maketmb to chop off bits not relevant to OPL2 cards.
  53. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  54. 1/8/96
  55. - Version 1.09
  56. - ***** IMPORTANT *****
  57. Any code that is called by the sound system should be compiled with
  58. the -zu option. This tells the compiler to assume that SS is not
  59. equal to DS. This is required for any code that's called from the
  60. sound system while it's in an interrupt (I switch to a custom stack
  61. upon entering the interrupt). Any function that is used with
  62. TS_ScheduleTask or FX_SetCallBack should be compiled this way (you may
  63. want to put them in a separate module. I recommend doing this for
  64. USRHOOKS functions as well, in case you free a task from within a timer
  65. function (MUSIC_FadeVolume does this, so if you use it, USRHOOKS must
  66. be compiled with -zu).
  67. - The sound system now uses the ULTRAMID.INI in the current directory if
  68. it exists, otherwise it uses the one pointed to by the ULTRADIR environment
  69. variable.
  70. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  71. 1/4/96
  72. - Fixed a bug with fast 8-bit reverb. Also made a few optimizations to
  73. it.
  74. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  75. 12/18/95
  76. - Version 1.08
  77. - I'm a dumbass. I left a "strcat( InstrumentDirectory, name );"
  78. after locating the ULTRAMID.INI file for the Gravis Ultrasound. So
  79. if you haven't been able to initialize music in a while, you know
  80. who's to blame. :)
  81. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  82. 12/12/95
  83. - New utility called PS. Allows you to test a WAV, VOC, or raw sound
  84. file from the command line using the sound system. Check in the
  85. PS directory for the source code.
  86. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  87. 12/8/95
  88. - Version 1.07
  89. - Added adjustable delay on the reverb. The following functions allow
  90. you to manipulate the delay setting.
  91. int FX_GetMaxReverbDelay( void );
  92. int FX_GetReverbDelay( void );
  93. void FX_SetReverbDelay( int delay );
  94. The delay is measured in the number of samples to delay before the
  95. sound is regenerated. To calculate the delay in seconds, just do this:
  96. seconds = delay / mixingrate; (using floats, obviously). The minimum
  97. delay is 256 samples. The maximum depends on whether you're doing
  98. 16 bit or 8 bit, and stereo or mono mixing. Use FXGetMaxReverbDelay
  99. to get the maximum (after the FX_Init has been called). In 8-bit mono,
  100. the delay is about 1/2 of a second. The maximum delay is constrained
  101. by the size of the buffer I allocate to mix the sound in. If anyone
  102. wants longer delays, let me know and I can increase the buffer size
  103. for you (I'd probably make it adjustable by you).
  104. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  105. 12/6/95
  106. - 18 voice FM music on OPL3 cards.
  107. - FM music is no longer limited to MIDI channels 1 through 10. For
  108. backward compatability sake, the function MUSIC_SetMaxFMMidiChannel
  109. can be used to limit it, but why would anyone want to do that?
  110. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  111. 11/13/95
  112. - Fixed a bug with Adlib music where the default pitch bend range was
  113. set too low. Thanks Peter!
  114. - 1.06a library upload.
  115. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  116. 11/7/95
  117. - 1.06 update. Time sure flies...
  118. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  119. 8/21/95
  120. - 1.05 update.
  121. - Full EMIDI support.
  122. - Context sensitive music through EMIDI.
  123. - Added the ability to fastforward to a specific beat/measure or time
  124. in a song.
  125. - GUSMIDI.INI file no longer required (this may return, we're still debating).
  126. - Probably a few other things that I can't think of right now.
  127. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  128. 7/24/95
  129. - Changed GUS code to use software mixing instead of hardware mixing.
  130. GUS purists will hate me (if they found out), but it makes a lot more
  131. sense this way since I only have to maintain one playback method, plus
  132. it allows GUS owners to hear reverb and gives better control over panning.
  133. There may be other benefits, but I can't think of them right now.
  134. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  135. 5/31/95
  136. - Playback of 16-bit digitized sound now supported. Source data must
  137. be signed data. Still need to do GUS version, but I'm uploading it for
  138. Jason Blochowiak.
  139. - Reverb code rewritten in assembly. Still needs to be fine-tuned.
  140. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  141. 5/25/95
  142. - Using "option eliminate" with the sound library should no longer crash
  143. the linker.
  144. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  145. 5/8/95
  146. - Added some new functions:
  147. void FX_SetReverseStereo( int setting );
  148. int FX_GetReverseStereo( void );
  149. void FX_SetReverb( int reverb );
  150. void FX_SetFastReverb( int reverb );
  151. FX_SetReverseStereo and FX_GetReverseStereo allow you to swap the left
  152. and right channel volumes for people whose speakers are reversed. Zero
  153. is no swap, non-zero swaps channels.
  154. FX_SetReverb and FX_SetFastReverb set the amount of echo to mix into
  155. the sound. It's a very mechanical sounding echo, kind of like the spring
  156. reverb on guitar amps. The effect is much like the echo effects in
  157. Super Mario World on the SNES.
  158. FX_SetReverb accepts values from 0 to 255. 0 means no reverb and 255
  159. is 100% reverb (sound repeats infinitely). Values above 96 are probably
  160. overkill. Speedwise, reverb costs about as much as one sound effect.
  161. FX_SetFastReverb uses a bitwise shift instead of table lookup to scale
  162. the volume of the echo. A value of 0 is no echo, 1 is echo at half
  163. volume (equivalent to 128 with FX_SetReverb), 2 to 1/4 volume
  164. (equivalent to 64), etc. If you're not doing dynamic changes in reverb,
  165. this may be preferable since it's a bit faster.
  166. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  167. 4/7/95
  168. - void MUSIC_RegisterTimbreBank( unsigned char *timbres );
  169. Added the function MUSIC_RegisterTimbreBank to allow developers to use
  170. their own FM timbres on Sound Blaster and Adlib compatibles. Use the
  171. supplied utility MAKETMB to create data files using a script and IBK
  172. files. The resulting file can be loaded by the program at runtime and
  173. a pointer to it passed to MUSIC_RegisterTimbreBank. Afterwards, the
  174. memory can be deallocated (the audio library copies the supplied timbres
  175. over the default timbres.
  176. If you decide to use your own timbres, I can recommend a good shareware
  177. program that helps you to create them. Just give me a call.
  178. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  179. 3/17/95
  180. - Finished looping functions. Here is how to loop a sample:
  181. For a raw sample, use FX_PlayLoopedRaw. Here is it's definition:
  182. int FX_PlayLoopedRaw
  183. (
  184. char *ptr,
  185. unsigned long length,
  186. char *loopstart,
  187. char *loopend,
  188. unsigned rate,
  189. int pitchoffset,
  190. int vol,
  191. int left,
  192. int right,
  193. int priority,
  194. unsigned long callbackval
  195. );
  196. ptr is a pointer to the start of the sample. It can actually be
  197. later in the sample than the start of the loop. This is usefull for
  198. MOD players which may start a sample at an offset into the sound.
  199. length is the number of samples to play before the loop begins. In
  200. most cases, this will be ( loopend - ptr ). It may seem strange to be
  201. able to play past the end of the loop on the first time through the
  202. sound, but it's the most flexible.
  203. loopstart is a pointer to the start of the loop. The can be before
  204. or after the start of the sample.
  205. loopend is a pointer to the end of the loop. This points to the last
  206. sample to play in the loop.
  207. For a WAV file, use FX_PlayLoopedWAV.
  208. int FX_PlayLoopedWAV
  209. (
  210. char *ptr,
  211. long loopstart,
  212. long loopend,
  213. int pitchoffset,
  214. int vol,
  215. int left,
  216. int right,
  217. int priority,
  218. unsigned long callbackval
  219. );
  220. ptr is the start of the WAV file. WAV files currently do not have
  221. the flexibility that raw files do, in that the sound must start at the
  222. beginning of the WAV file. All looping is based past the beginning of
  223. the WAV file. The sound will loop after the sample pointed to by
  224. loopend.
  225. loopstart is the offset (not pointer) of the sample to begin the loop
  226. on. This must be a positive value. Any negative values or values past
  227. the end of the sound will cause the WAV to only play once.
  228. loopend is the offset (not pointer) of the sample to end the loop on
  229. (the sample will loop after this sample is played). If the offset is
  230. past the end of the sample, the loop end will be set to the last sample
  231. in the file.
  232. For a VOC file, use FX_PlayLoopedVOC.
  233. int FX_PlayLoopedVOC
  234. (
  235. char *ptr,
  236. long loopstart,
  237. long loopend,
  238. int pitchoffset,
  239. int vol,
  240. int left,
  241. int right,
  242. int priority,
  243. unsigned long callbackval
  244. );
  245. ptr is the start of the VOC file. VOC files currently do not have
  246. the flexibility that raw files do, in that the sound must start at the
  247. beginning of the VOC file. All looping is based past the beginning of
  248. the VOC file. Since VOC files can contain multiple blocks of data,
  249. looping samples will only play the first block of data.
  250. loopstart is the offset (not pointer) of the sample to begin the loop
  251. on. This must be a positive value. Any negative values or values past
  252. the end of the sound will cause the VOC to play normally.
  253. loopend is the offset (not pointer) of the sample to end the loop on
  254. (the sample will loop after this sample is played). If the offset is
  255. past the end of the sample, the loop end will be set to the last sample
  256. in the file.
  257. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  258. 3/16/95
  259. - I have changed the names of the two functions for playing VOCs. It just
  260. no longer makes sense to call them PlaySound when there are a variety of
  261. file formats supported.
  262. Here's an updated list of functions that play digitized sound:
  263. FX_PlayRaw : Plays raw sampled data once
  264. FX_PlayLoopedRaw : Plays raw sampled data with looping
  265. FX_PlayWAV : Plays a WAV file once
  266. FX_PlayLoopedWAV : Plays a WAV file with looping
  267. FX_PlayVOC3D : Plays a VOC file once using '3D' panning
  268. FX_PlayVOC : Plays a VOC file once
  269. FX_PlayLoopedVOC : Plays a VOC file with looping
  270. I'm thinking about moving the '3D' routines out of the library since
  271. they are really just panning tables. This way, users could create their
  272. own method.
  273. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  274. 3/15/95
  275. - Increased the reported maximum number of voices you can play on some cards
  276. to 32. Since all voice tables are dynamically allocated, you could have
  277. more, but anything beyond 16 is a bit ridiculous. The Gravis Ultrasound
  278. is limited to 24 currently, and any voices used for sound fx leaves fewer
  279. voices for music. In any case, 8 voices is the recommended maximum, but
  280. if you have reason to use more, go ahead.
  281. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  282. 3/14/95
  283. - Added special routines optimized to mix only 1 channel into stereo.
  284. Whenever the volume of the left or the right channel is zero for a
  285. voice, only one channel is mixed. This is especially useful if you
  286. intend to play a sound with the left and right channels' frequencies are
  287. slightly different. Peter Freese (from Q Studios, who are developing
  288. Blood) needs to do this for his Sonic Holography 3D sound library that
  289. he is developing.
  290. - Fixed a problem on the Sound Source. I noticed that pitches were higher
  291. than normal on the Sound Source, and discovered that it was possible to
  292. overflow the FIFO buffer without causing the overflow flag to be set.
  293. Since the Sound Source can only play sound at 7khz, I must poll the
  294. port to see if it's ready for sound. The overflow flag sometimes doesn't
  295. register imediatly, so I changed my routine to write only 14 samples at
  296. a time to the port. This causes the pitch to be nearly 7khz.
  297. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  298. 3/13/95
  299. - Increased the resolution of the volume levels that digitized sounds can
  300. play from 16 to 64. Since the volumes were passed in as 0 to 255, there
  301. is no need for users to change any code to take advantage of this.
  302. Although this requires more memory (in 16bit mode, 32k as opposed to 8k),
  303. it means smooth volume changes and allows for MOD playback.
  304. - Added new function for changing pitch: FX_SetFrequency. This allows you
  305. to change the rate that a sound is mixed at. This isn't very usefull for
  306. VOC playback since the VOC file can override the rate, it is very usefull
  307. for playback of raw data since you will already know the sampling rate.
  308. This is also usefull for MOD playback.
  309. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  310. 3/10/95
  311. - Added embedded looping commands for MIDI files. To loop a specific
  312. track, use controller 116 on any MIDI channel on that track with a value
  313. of 0 for infinite, or > 0 for the number of times to loop. To mark the
  314. end of a loop, use controller 117 with a value of 127. NOTE: Currently,
  315. you must put loop info on all tracks to if you want all of them to loop.
  316. This may seem like a pain at first, but I thought that it would give
  317. the musician extra flexibility. If no one likes this, I'll change it so
  318. that you only have to do one loop controller.
  319. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  320. 3/9/95
  321. - Added support for .WAV files and raw samples.
  322. - Added two new functions allowing the programmer to control the relative
  323. volume of each MIDI channel of a song. Use MUSIC_SetMidiChannelVolume
  324. to set the volume of a MIDI channel and MUSIC_ResetMidiChannelVolumes
  325. to restore all channels to full volume. I do not reset the volumes
  326. when you play a new song so that you can set the volume of all the
  327. channels before playing a song.
  328. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  329. 2/14/95
  330. - Found a potential bug where the pitch scaling function could go outside
  331. of the array bounds given certain pitch offsets.
  332. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  333. 2/4/95
  334. - Stereo FM temporarally commented out for ROTT. Seems to take too long on
  335. some computers and causes the mouse driver to miss interrupts.
  336. Have to contact Creative Labs to find out which chips have fast timings.
  337. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  338. 2/3/95
  339. - Added FX_VoiceAvailable. Checks if a voice can be played at the
  340. specified priority.
  341. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  342. 1/30/95
  343. - Version 1.02 uploaded for all current developers.
  344. - Various initialization routines improved.
  345. - Now performs checks to see if DMA and IRQ are working.
  346. - Added the ability to do custom Sound Blaster setup. Now users can enter
  347. the DMA, card address, and IRQ.
  348. - Fixed problem with SB16 and Sound Canvas Daughterboard. This was
  349. caused by an undocumented IRQ disable flag in the SB16.
  350. - GUS initialization no longer bombs if all the patches in GUSMIDI.INI
  351. could not be loaded. I was forced to do this due to the problems
  352. that can be caused by a slight error in the patch list. Gravis has changed
  353. the patch sizes over several versions making it difficult to create a patch
  354. list that works on all cards. Since the last patches loaded are percussion,
  355. these are the ones that will be affected.
  356. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  357. 1/11/95
  358. - Additive timbres now respond to volume changes.
  359. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  360. 1/7/95
  361. - Added better error checking and detection for AWE32.
  362. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  363. 1/4/95
  364. - Version 1.01 uploaded for all current developers.
  365. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  366. 12/20/94 - Version 1.01
  367. - Version built for Rise of the Triad.
  368. - Fixed some problems with MIDI playback on SoundScape. It was
  369. missing program changes (instruments).
  370. - GUS uses GUSMIDI.INI in local directory instead of ULTRAMID.INI.
  371. This is so that a custom patch list could be included with your
  372. game. If you own a GUS, copy the file ULTRAMIDI.INI from your
  373. ULTRASND\MIDI directory. I will come up with something more
  374. convenient in the future.
  375. - When command line parameter "ASSVER" used, the library returns
  376. an error when initialized. The error string will contain the
  377. version text. This was done so that your programs could perform
  378. their normal shutdown procedure before exiting to DOS.
  379. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  380. 12/15/94
  381. - Optimized mixing routines. 50% increase in 8-bit mono and stereo
  382. playback and 20%-30% increase in 16-bit playback.
  383. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  384. 11/28/94
  385. - Pitch tables are now linked in rather than generated at startup.
  386. This gets rid of any floating point code.
  387. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  388. 11/14/94
  389. - Added function FX_SoundsPlaying to report the number of voices
  390. playing.
  391. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  392. 11/13/94
  393. - Fixed problem with SoundScape where it wasn't reporting the MaxBits
  394. and MaxVoices properly.
  395. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  396. 11/6/94 - Version 1.00
  397. - SoundScape now automatically gets MIDI port address from SNDSCAPE.INI.
  398. - WaveBlaster now automatically gets MIDI port address from the BLASTER
  399. environment string.
  400. - TaskMan now locks the link list manager's memory in case FX_Init
  401. and MUSIC_Init are not called.
  402. - All developers must make sure that they ask for the midi port on the
  403. following cards: GenMidi, and SoundCanvas.
  404. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  405. 11/5/94
  406. - Made the GUSWAVE play voice routine allocate voice with a priority of
  407. 0, which tells gf1_play_digital to not attempt voice stealing. This
  408. prevents the music playback from stealing sound fx voices and was
  409. the source of the bug in Boppin' where voices would be cutoff.
  410. - VOC decoder now deals with block type 8 properly. Bug caused it to be
  411. ignored.
  412. - GUS set volume function now sets volume of all playing voices. Before,
  413. it would only set the volume for new voices.
  414. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  415. 10/31/94
  416. - Now keeping track of version number. From any game that uses the
  417. sound system, you can type "ASSVER" to get version number.
  418. - Added command line parameter "DEBUGGUS" to Gravis Ultrasound GUSWAVE
  419. to help track down a voice dropout problem. I'll eventually add similar
  420. parameters to other modules.
  421. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  422. 10/26/94
  423. - Added native support for the Ensoniq SoundScape. This card is capable
  424. of playing 8 and 16 bit stereo or mono data and uses wavetable synthesis
  425. for music. Please add this to your config.
  426. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  427. 10/23/94
  428. - Did some optimizing and found that for 16-bit mixing it is slightly
  429. quicker to use code to do harsh clipping than to use tables. This
  430. gets rid of a 64k lookup table I had. With 8-bit sound, it is quicker
  431. to use a table, but it only takes up 512 bytes.
  432. Here is the various mixing modes in order of fastest to slowest:
  433. 8-bit mono, 16-bit mono, 8-bit stereo, 16-bit stereo.
  434. Just for reference, 8-bit mono is only about 40% faster than 16-bit
  435. stereo. And considering that at 11khz, mixing is only called about
  436. 10 times a second, it's not an incredible difference.
  437. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  438. 10/20/94
  439. - Fixed the PAS slowdown bug. DMA channel was not being disabled after
  440. a PCM transfer. On some computers with PAS-16s, when the DMA circuitry
  441. in the PAS was turned off, it left the DRQ line on the DMA in a floating
  442. state, causing the DMA to do a continuous burst transfer, which would
  443. slow down the computer. This would not happen on other cards, since
  444. their DMA circuitry is always active.
  445. - Fixed the WaveBlaster bug. Bug caused by a problem with playing
  446. WaveBlaster music and Sound Blaster-16 that is completely undocumented
  447. in Creative Labs' developer kits.
  448. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  449. 10/4/94
  450. - Added several new cards to enum list in SNDCARDS.H. Unless you use all
  451. of these, you are not supporting all sound cards----PUT THEM IN!
  452. - AWE32 support for General MIDI.
  453. - Midi callback system for implimenting digital drums and other music-
  454. synced events.
  455. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  456. 9/7/94
  457. - All interrupt service routines now allocate their own 1024 byte stack
  458. in case Windows or OS/2 don't leave enough stack space. This was
  459. suggested by Steve Lepisto (Accursed Toys) who kindly supplied example
  460. code.
  461. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  462. 9/6/94
  463. - PC speaker sound fx can now be turned off by setting the volume to 0.
  464. - Turned off panning on the FM rhythm channel.
  465. - Found and fixed another FM panning bug.
  466. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  467. 9/2/94
  468. - Added ability to reroute data from a MIDI channel to a user function.
  469. Good for digital drums or animation synced to music.
  470. - Fixed a problem on the GUS with instruments that use tremelo. Only
  471. showed up when volume was set to 0.
  472. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  473. 9/1/94
  474. - Fixed the high volume notes on GUS.
  475. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  476. 8/26/94
  477. - Ummm, added revision notes! What follows is what I've added in the
  478. past few weeks.
  479. - Locked down memory on all cards except GUS.
  480. - Support for higher IRQ's on PAS and Sound Blaster. Requires Dos4gw Pro
  481. version 1.97.
  482. - Internal support for PAS mixer control (using MVSOUND.SYS). Requires
  483. Dos4gw Pro version 1.97.
  484. - FM pan position defaulted to full left. Only noticable if midi file
  485. didn't set its own pan positions. Now defaults to center.
  486. - Added stereo panning on FM music.
  487. - Added stereo detuning on FM music.
  488. - Added harsh clipping so that digitized sounds playback at same volume
  489. no matter how many voices are allocated. Could distort when many sounds
  490. are playing, but that's the price you pay.
  491. - Changed panning from sine tables to a linear attenuation ramp as you
  492. deviate from center.
  493. - GUS can now choose number of voices to use (used to be 8 no matter what).
  494. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  495. ³ Header files: ³
  496. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  497. There are four header files that you'll need: TASK_MAN.H, SNDCARDS.H,
  498. MUSIC.H and FX_MAN.H. MUSIC.H contains all functions that control music.
  499. FX_MAN.H contains all functions for control of digitized and synthesized
  500. sound. SNDCARDS.H contains sound card definitions and is brought in by
  501. MUSIC.H and FX_MAN.H. TASK_MAN.H is a module used for timer management.
  502. SNDCARDS.H defines the following enumerated type:
  503. typedef enum
  504. {
  505. SoundBlaster,
  506. ProAudioSpectrum,
  507. SoundMan16,
  508. Adlib,
  509. GenMidi, <--- Requires midi port
  510. SoundCanvas, <--- Requires midi port
  511. Awe32,
  512. WaveBlaster,
  513. SoundScape,
  514. UltraSound,
  515. SoundSource,
  516. TandySoundSource,
  517. PC,
  518. NumSoundCards
  519. } soundcardnames;
  520. These are used to select which card to use when initializing the routines.
  521. Do not use hard coded values since the value of these cards may change
  522. in future versions of the library. NumSoundCards is simply to identify
  523. how many cards are supported (since support for more cards may be added
  524. in the future).
  525. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  526. ³ Functions: ³
  527. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  528. In the functions that follow, TRUE is assumed to be the value returned by
  529. the expression ( 1 == 1 ) and FALSE is assumed to be the value returned
  530. by the expression ( !TRUE ). Using macros, you could define them this
  531. way:
  532. #define TRUE ( 1 == 1 )
  533. #define FALSE ( !TRUE )
  534. This method is used because it makes no assumptions on the value of the
  535. boolean expressions when they are evaluated by the compiler.
  536. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  537. ³ Sound Effects: ³
  538. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  539. The following cards will be supported for sound effects: SoundBlaster,
  540. ProAudioSpectrum, UltraSound, SoundSource, TandySoundSource, AWE32,
  541. SoundMan16, and the PC speaker.
  542. Functions that return an error status will return one of the following:
  543. FX_Ok (if the function was successfull), FX_Error (if an error occurred),
  544. or FX_Warning (if a non-critical error occurred).
  545. The number of the last error or warning is stored in the global variable
  546. FX_ErrorCode. Whether an error is worth exiting for is up to you. Check
  547. out the names of the possible errors in the header file.
  548. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  549. FX_ErrorString
  550. Synopsis:
  551. #include "fx_man.h"
  552. char *FX_ErrorString( int ErrorNumber );
  553. Description:
  554. The FX_ErrorString function maps the error number contained
  555. in ErrorNumber to a string describing the error.
  556. ErrorNumber can be the number of any error. If ErrorNumber is
  557. set to FX_Error or FX_Warning, FX_ErrorString will return the
  558. string corresponding with the last error that occurred.
  559. Returns:
  560. The FX_ErrorString function returns a pointer to the error message.
  561. This string of data should not be modified by the program.
  562. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  563. FX_SetupCard
  564. Synopsis:
  565. #include "fx_man.h"
  566. int FX_SetupCard( int SoundCard, fx_device *device );
  567. Description:
  568. The FX_SetupCard function is used to detect a sound card and
  569. get information on what the card can do.
  570. SoundCard:
  571. This is an int passed into the function and corresponds
  572. to the enumerated list of cards.
  573. device:
  574. This is the address of the data structure to store information
  575. about the card.
  576. Here is the definition of fx_device:
  577. typedef struct
  578. {
  579. int MaxVoices;
  580. int MaxSampleBits;
  581. int MaxChannels;
  582. } fx_device;
  583. MaxVoices:
  584. This is the recommended maximum number of digitized sound
  585. that can be played at once. 4 voices is adequate for most games,
  586. although 8 voices is great for games that have a lot of atmosphere
  587. sounds (like 3D games). You should offer an option to select the
  588. number of voices to use for people with slower machines.
  589. MaxSampleBits:
  590. This will be either 8 or 16, depending on whether you have an
  591. 8-bit or 16-bit sound card. The routines only support playback
  592. of 8-bit samples, but can mix them as 16-bit. This provides better
  593. quality sound, especially at low volumes, however it is slower since
  594. you have twice as much data to mix. You might want to offer this
  595. as an option to people with slower machines.
  596. MaxChannels:
  597. This will be 1 if you have a mono card and 2 if you have a stereo
  598. card. Again, offer this as a choice in case the user has a slow
  599. machine. If you are not using the panning capabilities of the
  600. sound system, choose mono sound since there would be no benefit
  601. in using stereo.
  602. Returns:
  603. The FX_SetupCard function will return FX_Ok if the sound card was
  604. detected succesfully, and FX_Error if the card was not found or
  605. could not be initialized.
  606. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  607. FX_Init
  608. Synopsis:
  609. #include "fx_man.h"
  610. int FX_Init( int SoundCard, int numvoices, int mixmode, int samplebits,
  611. unsigned mixrate );
  612. Description:
  613. The function FX_Init configures the sound engine by selecting the
  614. sound card, the maximum number of sounds that can play, and whether
  615. to mix the sound in 8 or 16 bits.
  616. SoundCard:
  617. This is an int passed into the function to select and corresponds
  618. to the enumerated list of cards.
  619. numvoices:
  620. This is the number of digitized sound that can be played at once.
  621. mixmode:
  622. This is the number of channels to mix the sound into. 1 for mono,
  623. 2 for stereo.
  624. samplebits:
  625. This should be either 8 or 16, depending on whether sound should
  626. be mixed in 8-bits or 16.
  627. mixrate:
  628. This selects the rate in hertz that sound should be mixed.
  629. Example:
  630. int status;
  631. fx_device device;
  632. status = FX_SetupCard( UltraSound, &device );
  633. if ( status != FX_Ok )
  634. {
  635. printf( "%s\n", FX_ErrorString( status ) );
  636. exit( 1 );
  637. }
  638. status = FX_Init( UltraSound, 8, 2, 16, 11000 );
  639. if ( status != FX_Ok )
  640. {
  641. printf( "%s\n", FX_ErrorString( status ) );
  642. exit( 1 );
  643. }
  644. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  645. FX_Shutdown
  646. Synopsis:
  647. #include "fx_man.h"
  648. int FX_Shutdown( void );
  649. Description:
  650. The function FX_Shutdown ends use of the sound card and restores
  651. any system resources that were used. This should be called when
  652. you exit to DOS, or when you change sound devices.
  653. Returns:
  654. The function FX_Shutdown returns FX_Ok if it was succesfull in
  655. shutting down the sound card and restoring resources. Otherwise,
  656. it returns FX_Error or FX_Warning.
  657. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  658. FX_SetCallBack
  659. Synopsis:
  660. #include "fx_man.h"
  661. int FX_SetCallBack( void ( *function )( unsigned long ) );
  662. Description:
  663. The function FX_SetCallBack instructs the engine to call the
  664. user-defined function when sounds stop playing.
  665. function:
  666. This is the function that the engine should call when a sound stops
  667. playing. The user-defined function should accept an unsigned long
  668. as it's parameter. The value passed to this function is a user-
  669. defined value identifying the sound that just finished playing and
  670. may be an actual pointer to a user-defined data structure.
  671. Returns:
  672. FX_SetCallBack returns FX_Error or FX_Warning when the assignment
  673. failed. Otherwise it returns FX_Ok.
  674. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  675. FX_SetVolume
  676. Synopsis:
  677. #include "fx_man.h"
  678. void FX_SetVolume( int volume );
  679. Description:
  680. The function FX_SetVolume sets the total volume of sound
  681. effects.
  682. volume:
  683. This is the volume to set the sound fx device to.
  684. Valid volumes are from 0 to 255.
  685. Returns:
  686. The function FX_SetVolume does not return a value.
  687. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  688. FX_GetVolume
  689. Synopsis:
  690. #include "fx_man.h"
  691. int FX_GetVolume( void );
  692. Description:
  693. The FX_GetVolume function returns the total volume of the sound fx
  694. device.
  695. Returns:
  696. If an error occurs, FX_GetVolume returns FX_Warning or FX_Error,
  697. otherwise it returns the total volume of sound effects. Valid
  698. volumes are from 0 to 255.
  699. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  700. ³ Playing Sounds: ³
  701. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  702. FX_PlaySound
  703. Synopsis:
  704. #include "fx_man.h"
  705. int FX_PlaySound( char *ptr, int pitchoffset, int vol, int left,
  706. int right, int priority, unsigned long callbackval );
  707. Description:
  708. The function FX_PlaySound begins playback of digitized sound.
  709. The sound data must be formated as a valid VOC sound file.
  710. ptr:
  711. This is the address to the VOC format sound data to be played.
  712. pitchoffset:
  713. This is the amount to transpose the pitch of the sound up or down
  714. measured in 1/100th's of a semitone. For example, to transpose
  715. the pitch up one octave use 1200. To transpose the pitch down
  716. one octave use -1200. For no transposition, use 0.
  717. vol:
  718. This is the volume of the sound in mono mode. Valid values range
  719. from 0 to 255. Note: A volume of 0 does not always mean total
  720. silence.
  721. left:
  722. This is the volume of the sound played through the left speaker in
  723. stereo mode. Valid values range is from 0 to 255. Note: A volume
  724. of 0 does not always mean total silence.
  725. right:
  726. This is the volume of the sound played through the right speaker
  727. in stereo mode. Valid values range from 0 to 255. Note: A volume
  728. of 0 does not always mean total silence.
  729. priority:
  730. This sets the order that sounds should be cancelled if a new sound
  731. is played when no voices are available. When this occurs, the
  732. oldest sound with the lowest priority is replaced with the new
  733. sound. If the new sound's priority is lower than all the sounds
  734. playing, then it will not be played.
  735. callbackval:
  736. This is the value that should be sent to the user-defined callback
  737. function when the sound ends. See FX_SetCallBack.
  738. Returns:
  739. If an error occurs, FX_PlaySound returns FX_Error, or FX_Warning.
  740. Otherwise, it returns a voice handle. To determine if a return value
  741. is a voice handle, check to see if it is greater than FX_Ok. Valid
  742. voice handles are always greater than FX_Ok. The most common error
  743. that can occur is when there are no voices and the new sound's
  744. priority was too low.
  745. The voice handle can be used later to stop the voice from playing or to
  746. test if the voice is still playing.
  747. Example:
  748. int voicehandle;
  749. voicehandle = FX_PlaySound( address, pitchoffset, vol, left, right,
  750. priority, callbackval );
  751. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  752. FX_Play3D
  753. Synopsis:
  754. #include "fx_man.h"
  755. int FX_Play3D( char *ptr, int pitchoffset, int angle, int distance,
  756. int priority, unsigned long callbackval );
  757. Description:
  758. The function FX_Play3D begins playback of digitized sound. The sound
  759. data must be formated as a valid VOC sound file.
  760. ptr:
  761. This is the address to the VOC sound data to be played.
  762. pitchoffset:
  763. This is the amount to transpose the pitch of the sound up or down
  764. measured in 1/100th's of a semitone. For example, to transpose
  765. the pitch up one octave use 1200. To transpose the pitch down
  766. one octave use -1200. For no transposition, use 0.
  767. angle:
  768. This is the clockwise angle of the sound in relation to the player
  769. from 0 to 31. 0 is center, 8 is full right, 16 is directly behind
  770. the listener, and 24 is full left.
  771. distance:
  772. This is the distance of the sound from the player. Valid values
  773. range from 0 to 255, with 255 being the furthest from the player
  774. (note: this does not mean silence on all cards).
  775. priority:
  776. This sets the order that sounds should be cancelled if a new sound
  777. is played when no voices are available. When this occurs, the
  778. oldest sound with the lowest priority is replaced with the new
  779. sound. If the new sound's priority is lower than all the sounds
  780. playing, then it will not be played.
  781. callbackval:
  782. This is the value that should be sent to the user-defined callback
  783. function when the sound ends. See FX_SetCallBack.
  784. Returns:
  785. If an error occurs, FX_Play3D returns FX_Error, or FX_Warning.
  786. Otherwise, it returns a voice handle. To determine if a return value
  787. is a voice handle, check to see if it is greater than FX_Ok. Valid
  788. voice handles are always greater than FX_Ok. The most common error
  789. that can occur is when there are no voices and the new sound's
  790. priority was too low.
  791. The voice handle can be used later to stop the voice from playing or to
  792. test if the voice is still playing.
  793. Example:
  794. int voicehandle;
  795. voicehandle = FX_Play3D( address, pitchoffset, angle, distance,
  796. priority, callbackval );
  797. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  798. FX_SetPan
  799. Synopsis:
  800. #include "fx_man.h"
  801. int FX_SetPan( int handle, int vol, int left, int right );
  802. Description:
  803. The function FX_SetPan sets the mono and stereo volumes of a
  804. currently playing sound. This can be used for sounds started
  805. with FX_PlaySound or FX_Play3D.
  806. handle:
  807. This is the voice handle of the sound. This is the value returned
  808. by FX_PlaySound and FX_Play3D.
  809. vol:
  810. This is the volume of the sound in mono mode. Range is from 0 to
  811. 255. Note: A volume of 0 does not always mean total silence.
  812. left:
  813. This is the volume of the sound played through the left speaker
  814. in stereo mode. Range is from 0 to 255. Note: A volume of 0
  815. does not always mean total silence.
  816. right:
  817. This is the volume of the sound played through the right speaker
  818. in stereo mode. Range is from 0 to 255. Note: A volume of 0
  819. does not always mean total silence.
  820. Returns:
  821. If the sound is no longer playing, FX_SetPan will return FX_Warning,
  822. otherwise, it will return FX_Ok.
  823. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  824. FX_Pan3D
  825. Synopsis:
  826. #include "fx_man.h"
  827. int FX_Pan3D( int handle, int angle, int distance );
  828. Description:
  829. The function FX_Pan3D sets the angle and the distance of a
  830. currently playing sound in relation to the player. This can
  831. be used for sounds started with FX_PlaySound or FX_Play3D.
  832. handle:
  833. This is the voice handle of the sound. This is the value
  834. returned by FX_PlaySound and FX_Play3D.
  835. angle:
  836. This is the clockwise angle of the sound in relation to the player
  837. from 0 to 31. 0 is center, 8 is full right, 16 is directly behind
  838. the listener, and 24 is full left.
  839. distance:
  840. This is the distance of the sound from the player. Valid values
  841. range from 0 to 255, with 255 being the furthest from the player
  842. (note: this does not mean silence on all cards).
  843. Returns:
  844. If the sound is no longer playing, FX_Pan3D will return FX_Warning,
  845. otherwise, it will return FX_Ok.
  846. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  847. FX_SetPitch
  848. Synopsis:
  849. #include "fx_man.h"
  850. int FX_SetPitch( int handle, int pitchoffset );
  851. Description:
  852. The function FX_SetPitch sets the pitch of a currently playing sound.
  853. handle:
  854. This is the voice handle of the sound. This is the value returned by
  855. FX_PlaySound and FX_Play3D.
  856. pitchoffset:
  857. This is the amount to transpose the pitch of the sound up or down
  858. measured in 1/100th's of a semitone. For example, to transpose
  859. the pitch up one octave use 1200. To transpose the pitch down
  860. one octave use -1200. For no transposition, use 0.
  861. Returns:
  862. If the sound is no longer playing, FX_SetPitch will return FX_Warning,
  863. otherwise, it will return FX_Ok.
  864. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  865. FX_SoundActive
  866. Synopsis:
  867. #include "fx_man.h"
  868. int FX_SoundActive( int handle );
  869. Description:
  870. The function FX_SoundActive tests if the sound with the specified
  871. handle is currently playing.
  872. handle:
  873. This is the voice handle of the sound to test. This is the value
  874. returned by FX_PlaySound and FX_Play3D.
  875. Returns:
  876. FX_SoundActive returns TRUE if the sound is playing, otherwise it
  877. returns FALSE.
  878. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  879. int FX_StopSound( int handle );
  880. FX_StopSound stops playback of the sound with the associated handle.
  881. If the return value is not equal to FX_Ok, the sound was not found.
  882. handle is the voice handle of the sound. This is the value returned by
  883. FX_PlaySound and FX_Play3D.
  884. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  885. FX_StopAllSounds
  886. Synopsis:
  887. #include "fx_man.h"
  888. int FX_StopAllSounds( void );
  889. Description:
  890. The function FX_StopAllSounds halts output of all playing sounds.
  891. Returns:
  892. FX_StopAllSounds returns FX_Warning or FX_Error if an error occured,
  893. otherwise, it returns FX_Ok.
  894. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  895. ³ Music Playback: ³
  896. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  897. The following cards are supported for music: SoundBlaster, ProAudioSpectrum,
  898. Adlib, GenMidi, WaveBlaster, UltraSound, SoundMan16, Awe32, and SoundCanvas.
  899. TandSoundSource, SoundSource and PC are not supported.
  900. Similar error codes are returned for music as for sound effects. The
  901. codes are MUSIC_Ok, MUSIC_Warning, and MUSIC_Error. The last error that
  902. occurred is stored in MUSIC_ErrorCode.
  903. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  904. char *MUSIC_ErrorString( int ErrorNumber );
  905. Same as FX_ErrorString, except for music.
  906. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  907. int MUSIC_Init( int SoundCard, int Address );
  908. MUSIC_Init select and initializes a sound card for music. If the card
  909. is not detected or some error occured, it returns MUSIC_Error.
  910. Address is only used for General Midi and Wave Blaster. It is the
  911. address of the MPU401 interface. For other cards, just use 0.
  912. The two most common values are 0x330, and 0x300. Doom and Raptor
  913. list other values, also. To be on the safe side, you might want to
  914. support them also. The other values are: 0x220, 0x230, 0x240, 0x250,
  915. 0x300, 0x320, 0x330, 0x332, 0x334, 0x336, 0x340, 0x360.
  916. Incidently, I recommend doing your config files as text files with the
  917. extension ".INI". This would allow people to manually enter certain
  918. settings. I suggest the extension becuase people are familiar with it
  919. from Windows. Check out the config file in Raptor sometime.
  920. Example:
  921. status = MUSIC_Init( GenMidi, 0x330 );
  922. if ( status != MUSIC_Ok )
  923. {
  924. printf( "Error - %s\n", MUSIC_ErrorString( MUSIC_Error ) );
  925. exit( 1 );
  926. }
  927. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  928. int MUSIC_Shutdown( void );
  929. Ends use of the selected music card.
  930. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  931. void MUSIC_SetVolume( int volume );
  932. Sets the total volume of music. Valid volumes are from 0 to 255.
  933. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  934. int MUSIC_GetVolume( void );
  935. Returns the total volume of music. Valid volumes are from 0 to 255.
  936. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  937. int MUSIC_PlaySong( unsigned char far *song, int loopflag );
  938. MUSIC_PlaySong begins playback of the midi file pointed to by song.
  939. Set loopflag to MUSIC_PlayOnce to play the song once, or to
  940. MUSIC_LoopSong to play it continuously. This is usefull for the Apogee
  941. fanfare music.
  942. Note: with MUSIC_PlayOnce, the song is simply paused at the end. You
  943. can call MUSIC_Continue to start it again. Although I stop playing songs
  944. when you call MUSIC_PlaySong again or MUSIC_Shutdown, I recommend you
  945. call MUSIC_StopSong when you are completly done. I chose to do it this
  946. way becuase MUSIC_StopSong will cut off sound immediatly. This allows the
  947. sounds to decay on their own before ending.
  948. Example:
  949. status = MUSIC_PlaySong( SongPtr, MUSIC_LoopSong );
  950. if ( status != MUSIC_Ok )
  951. {
  952. printf( "Error - %s\n", MUSIC_ErrorString( MUSIC_Error ) );
  953. exit( 1 );
  954. }
  955. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  956. void MUSIC_SetLoopFlag( int loopflag );
  957. MUSIC_SetLoopFlag allows you to change the type of looping after a song
  958. is started. This way, you can have the song end at the end of the song.
  959. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  960. int MUSIC_StopSong( void );
  961. MUSIC_StopSong halts playback of the the current song.
  962. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  963. void MUSIC_Pause( void );
  964. MUSIC_Pause temporarily pauses playback of the song. Use MUSIC_Continue
  965. to let the music continue.
  966. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  967. void MUSIC_Continue( void );
  968. MUSIC_Continue allows music to continue playing after a call to MUSIC_Pause
  969. or when the loopflag is set to MUSIC_PlayOnce and the song has finished.
  970. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  971. int MUSIC_SongPlaying( void );
  972. MUSIC_SongPlaying tests if a songs is playing. Calls to MUSIC_StopSong
  973. or MUSIC_Pause will cause this to send back FALSE.
  974. Example:
  975. // Play the fanfare music
  976. MUSIC_PlaySong( ApogeeFanfare, MUSIC_PlayOnce );
  977. // Hang out while it's playing
  978. while( MUSIC_SongPlaying() )
  979. {
  980. // Do nothing, or maybe check for a key.
  981. }
  982. // Stop the song when we're done
  983. MUSIC_StopSong();
  984. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  985. ³ Fade Functions: ³
  986. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  987. These functions are provided for you to fade the music in and out.
  988. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  989. int MUSIC_FadeVolume( int tovolume, int milliseconds );
  990. MUSIC_FadeVolume causes the volume of a song to gradually change to
  991. the specified volume.
  992. tovolume is the final volume the music should be at.
  993. milliseconds is the time, in milliseconds, in which to make the transition.
  994. Note: accuracy is only to 1/100 of a second.
  995. For example, to have the music fade in at the begining of a level :
  996. // First, make sure we start at 0.
  997. MUSIC_SetVolume( 0 );
  998. // Start the song
  999. MUSIC_PlaySong( Level1Music, MUSIC_LoopSong );
  1000. // Fade up to the level the user set the music at over a
  1001. // period of 4 seconds.
  1002. MUSIC_FadeVolume( UserSelectedVolumeLevel, 4000 );
  1003. PlayGame();
  1004. // At the end of the game or level, fade out over a period of 4 seconds.
  1005. MUSIC_FadeVolume( 0, 4000 );
  1006. while( MUSIC_FadeActive() )
  1007. {
  1008. // Hang around until fade is done
  1009. }
  1010. // Stop the song when we're done
  1011. MUSIC_StopSong();
  1012. Note: Even if you fade the music volume to 0, the music is still playing.
  1013. Remember to use MUSIC_StopSong() to end playback.
  1014. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1015. void MUSIC_StopFade( void );
  1016. MUSIC_StopFade is used if you want to stop the fade. When called, the
  1017. volume remains at the volume it had progressed to. You don't need to
  1018. call this function unless you have a reason to. I use this internally
  1019. and left it public in case someone needed it.
  1020. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1021. int MUSIC_FadeActive( void );
  1022. MUSIC_FadeActive returns a flag stating if a fade is in progress. This
  1023. is useful if you want to wait until the music has faded out before doing
  1024. something.
  1025. ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
  1026. ³ Timer Functions: ³
  1027. ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
  1028. Since my routines depend heavily on the timer, I have to assume I own
  1029. it. To make it easy for you to do timing, I wrote Task_Man to handle
  1030. all requests for the timer.
  1031. To use Task_Man, you must include "Task_Man.h".
  1032. Here's an example how to set up a simple counter running at 30 times
  1033. per second:
  1034. #include <stdio.h>
  1035. #include "task_man.h"
  1036. void TimeFunction( task *Task );
  1037. // Here's our timer function. It just increments a counter.
  1038. void TimeFunction
  1039. (
  1040. task *Task
  1041. )
  1042. {
  1043. int *Count;
  1044. Count = Task->data;
  1045. ( *Count )++;
  1046. }
  1047. void main
  1048. (
  1049. void
  1050. )
  1051. {
  1052. task *TimerTask;
  1053. int Count;
  1054. Count = 0;
  1055. // Schedule our timing task
  1056. TimerTask = TS_ScheduleTask( TimeFunction, 30, 1, &Count );
  1057. // Make sure we start it
  1058. TS_Dispatch();
  1059. while( !kbhit() )
  1060. {
  1061. printf( "Count = %d\n", Count );
  1062. }
  1063. // clear the key that was hit
  1064. getch();
  1065. // Hey, let's change it so it runs at 1000 times a second!
  1066. TS_SetTaskRate( TimerTask, 1000 );
  1067. while( !kbhit() )
  1068. {
  1069. printf( "Count = %d\n", Count );
  1070. }
  1071. // clear the key that was hit
  1072. getch();
  1073. // Stop the clock before we leave
  1074. TS_Terminate( TimerTask );
  1075. }
  1076. Try out that program to see how it works.
  1077. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1078. task *TS_ScheduleTask( void ( *Function )( task * ), int rate,
  1079. int priority, void *data );
  1080. TS_ScheduleTask add your function to the list of routines that use the
  1081. timer. You can it set to any rate you would normally be able to program
  1082. the PC's internal timer for.
  1083. rate is the number of times per second your routine should be called.
  1084. priority is used for when tasks occur simultaniously and must be called in
  1085. a specific order.
  1086. data allows you to pass variables into your timer. You could set up
  1087. several tasks using one function, but sending in pointers to different
  1088. data. Here's how to use it:
  1089. int Data1 = 0;
  1090. int Data2 = 100;
  1091. task *Timer1;
  1092. task *Timer2;
  1093. Timer1 = TS_ScheduleTask( Function, 100, 1, &Data1 );
  1094. Timer2 = TS_ScheduleTask( Function, 200, 1, &Data2 );
  1095. TS_Dispatch();
  1096. .
  1097. .
  1098. .
  1099. void Function
  1100. (
  1101. task *Task
  1102. )
  1103. {
  1104. int *data;
  1105. data = ( int * )Task->data;
  1106. *data++;
  1107. }
  1108. The task * that's passed in can also be used to control your task.
  1109. For example, to terminate your task after a certain period of time:
  1110. void Function
  1111. (
  1112. task *Task
  1113. )
  1114. {
  1115. int *data;
  1116. data = ( int * )Task->data;
  1117. *data++;
  1118. // After 100 times, this task commits suicide.
  1119. if ( *data > 100 )
  1120. {
  1121. TS_Terminate( Task );
  1122. }
  1123. }
  1124. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1125. void TS_Dispatch( void );
  1126. TS_Dispatch starts the timer on all waiting scheduled events. Several
  1127. events may be scheduled before calling TS_Dispatch.
  1128. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1129. int TS_Terminate( task *ptr );
  1130. TS_Terminate ends a task. Use this when your done with a task.
  1131. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
  1132. void TS_SetTaskRate( task *Task, int rate );
  1133. TS_SetTaskRate allows you to change the rate a task runs at after you've
  1134. started it up.
  1135. ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ