FSSound -- A sound module for FS98, CFS and FS2000       =

Copyright (c) 1999-2000 by Daniel Steiner <[email protected]> =


This module allows 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 modified example from the FS98 SDK to figure out how to use it (read the comments!).


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 that module and feel free to provide any kind of feedback!
Daniel Steiner


--------------------------------------------------------------------------------
Distribution rules:
This package 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 its author.
It may NOT be distributed on any kind of media, such as CDROM, disk or other without a written agreement from its author.
It may NOT be uploaded to any online library and may not be published on the Internet without a written agreement from its author.
It may be included in a freeware panel package free of charge, if the copyright information and this distribution rules are marked clearly in the documentation of the package.