==================================================================
       =                                                                =
       =    FSSound v1.4 -- A sound module for FS98, CFS and FS2000     =
       =                                                                =
       = Copyright (c) 1999-2000 by Daniel Steiner <[email protected]> =
       =                                                                =
       ==================================================================


The FSSound module enables you to play back sound files in Microsoft Flight Simulator 98, Flight Simulator 2000 and Combat Flight Simulator gauges trough an easy to use interface. Check the header file and the examples to figure out how to use it (read the comments!).


available versions:
-------------------
1) Developer version (this version)
2) End user version (included in the FSSoundEndUser.zip file, see distribution rules below)
3) Source code version


installation:
-------------
1) Copy the FSSound.dll file to the modules subfolder of your Flight Simulator installation.
2) I'd bet you know what to do with all the other files. Since the module is built with the GNU C compiler, I don't have a clue whether one of the provided import libraries (FSSound_msvc.lib or FSSound_bor.lib) works for you. If it doesn't, you should be able to build a new one with the tools that come with your compiler. Something like "LIB /OUT:FSSound.lib /DEF:FSSound.def" should actually do the job for the Microsoft compiler and "IMPLIB -c FSSound.lib FSSound.dll" should work for the Borland compiler. If you use the GNU Compiler Suite you can use the libfssound.a import library which DOES work.


some things you should know:
----------------------------
1) The macros that are used in the example are provided for convenience only and don't have to be used. However, you should check the play macros to find out more about error handling.

2) The paths to the wave file need to be specified relative to the main installation directory of FS (not the sound, modules or gauges subfolder).

3) If you don't have hardware that does the sound mixing, you should use the same format for all wave files. Else, the CPU needs to convert them on the fly while mixing (normally 8bit, 22kHz and mono should be good enough).

4) Before sounds can be played back, they need to be registered by calling the appropriate method.

5) The module will only play back resources of type "SOUND". Check the example to see how resources can be used.

6) Since the FSSound module is not unloaded, when the user selects an other panel (which nobody hopes), it is absolutely necessary to unregister sounds that are no longer needed. Else, you start filling the sound card memory and later the main memory with sound data, that is no longer referenced and that can never be played back again anyway, until the user of your panel decides to or is forced to close FS.

7) The volume is specified in hundredths of decibels. So 0 (0dB, the default) means maximum volume and -10000 (-100dB) means silence. Note: Even when the volume is set to the minimum and you cannot hear the sound any more, the mixing process consumes CPU cycles that FS could use for better things. So: stop play back when you mute the sound.

8) The pan is also specified in hundredths of decibels. A value of -10000 (-100dB) means full left, 10000 (100dB) means full right and 0 (0dB) means both channels are at full volume. When you give (e.g.) 3412 as parameter, the left channel is attenuated by 34.12dB and the sound source appears to be more to the right.

9) The frequency is specified in hertz. The value must be between 100Hz and 100000Hz. The special value 0Hz resets the frequency to the default as in the sound file.

10) Do not mess around with the FSSound struct. Usually, the FSSound module knows better what to do with its data than you ;-)


Have a lot of fun with this module and feel free to provide any kind of feedback!
Daniel Steiner


--------------------------------------------------------------------------------
Distribution rules:
FSSound and all parts of it are freeware and not Public Domain software.
It may NOT be included or used in any commercial or shareware package without a written agreement from the author.
It may NOT be distributed on any kind of media, such as CDROM, disk or other without a written agreement from the author.
It may NOT be uploaded to any online library and may not be published on the Internet without a written agreement from the author.
It may be included in a freeware panel package free of charge, if the copyright information is clearly marked in the documentation and if ALL files contained in the FSSoundEndUser.zip archive are included with your panel package.