Although its name refers to FSX, this gauge will also work in FS2004. It is heavily based on dsd_xml_sound3.gau.
The most important change in gauge function is the way it handles volume settings. Previous versions of the gauge used a range from 0 to 100 to get/set volume levels. I have changed this to the range used by DirectSound, -10000 (representing very, very quiet) to 0 (representing full volume). If this change is going to cause you problems with your existing code, you can set a variable (L:Old Volume Control) to force the gauge back to the old method of handling volume settings. See below.
For those who haven’t used earlier versions of the gauge, each sound is controlled by a separate XML L:Variable (hereinafter referred to as an LVar.) You control the sound by setting the control variable (LVar) to the value that corresponds to the action you want. You assign LVars to sounds using a configuration file. Specify the configuration file in panel.cfg, as a fifth parameter for the “Sound” gauge element – see the example above. The gauge will follow the following methods in evaluating a supplied configuration file string:
1. You specify a relative path by starting it with a ‘dot’ – see the sample syntax, above. This dot effectively anchors us in the main FS folder. In the example above, the .ini file is located in the main FS gauges folder, and it is called dsd_xml_sound.ini. You are not limited to the FS gauges folder, you may specify any folder you like Your only challenge is ensuring the end user has the folder you specify in their FS folder system. This is the method used by previous versions of the sound gauge.
2. Alternatively, you may construct an absolute path to your configuration file. The gauge will look up its own path qualified name. By stripping off the name of the gauge itself, we are left with the path to the specific folder where the gauge is installed. To this path name, you will add the specific folder and file name for your configuration file. For example, my usual test aircraft is installed in a folder called:
Installing the gauge in the panel folder, and specifying a configuration file thusly:
gauge37=dsd_fsx_xml_sound!Sound, 2,2,2,2, dsd_fsx_test_sound.ini
will result in a configuration specification of
D:fsxAircraftb777_300paneldsd_fsx_test_sound.ini – placing the configuration file in the aircraft’s panel folder, with the sound gauge
Please note that with this method, there is no ‘dot’ at the beginning of the panel.cfg parameter string, but the string starts with a / or character. The gauge will treat the / and characters equivalently.
3. If the gauge does not find a dot or slash character at the beginning of the parameter string, it will search the string for a colon character “:” If it finds one, it will assume that you have provided a complete path including drive letter, to the configuration file and will attempt to load it without any adjustments.
I don’t recommend this approach for anything other than private use on your own computer. Specifying a configuration file string like “D:fsxgaugessound_config.ini” is asking for trouble if you are distributing the panel. We really don’t know where the end user has installed FS.
4. If the gauge does not find a “:” character, it will presume that you are attempting to specify a path in the same manner as in procedure 2, above. It will append the supplied parameter string to the path where the gauge is loaded from, providing the slash character as necessary. Staying with the example of my test aircraft, with the gauge loaded from the panel folder, providing a configuration file string like this:
gauge37=dsd_fsx_xml_sound!Sound, 2,2,2,2, panel_soundsdsd_fsx_test_sound.ini
will result in a configuration specification of
5. Default configuration file. If no configuration file is specified, or if the gauge cannot find the file specified, it will use the default name. The gauge will look up its own path qualified name (in case you or the end user have renamed it,) strip off the “.gau” file extension, and add “.ini” The default configuration file is therefore in the same folder as the gauge, with the same base name. This method should reduce the requirement to specify the configuration file in a great many cases. Note that if the gauge is using the default because you did not specify a configuration file, it will simply do so without further ado. However, if it is using the default because it could not find the file you specified, it will pop up a Windows message box telling you so.
Creating the Configuration File
The configuration file is used for a number of things. The most important of these is establishing paring between the sounds you want to play and the LVars you will use to control those sounds. If you look at the sample .ini file listing at the end of this document, you will find that it contains three section headings. Of these, one is labeled [Sounds] and one is labeled [LVars]. Each has a listing of numbered entries. The numbering is how the link between sound and LVar is established. Please note that that is the only significance to the numbering of the entries. The sound at entry Sound00 is matched with the LVar at Lvar00, the sound at entry Sound01 is matched with the LVar at Lvar01, etc.
As you may have gathered by now, in specifying LVars in the configuration file, you just supply the bare name. You do not add “L:” at the beginning, or “, number” at the end. This has nothing to do with how you will access the variables in XML, it is only relevant to the way a C/C++ gauge works with these variables.
When you are creating entries for the sounds themselves in your configuration file, you can, if you wish, specify a volume to be applied to the sound when it is loaded. See the first two sound entries in the sample .ini file below. This option is useful if you, or the end user of your product, feel a particular sound or sounds, as recorded, are too loud. You can specify the volume to be used and thus not have to bother setting it within your gauge. Specifying a volume setting in this way will not preclude you from changing the volume level later.
When you are specifying sounds in the configuration file, the gauge will follow the same protocols for specifying sound names as it does for specifying the configuration file name. You can use a relative path (starting with a “dot” and referring to a folder within the FS folder tree) or you can construct an absolute path, using the path to the configuration file as a base ( by specifying a or / as the first character of the parameter string, or by listing a folder and file without the leading slash.) See the first sound setting in the sample .ini file below. It specifies a folder called PanelSounds, located within the folder where the configuration file is found, as the location for the sound file.
The gauge will not verify individual sound names at gauge load time. However, it will use a Windows message box to notify the user that a particular sound cannot be found when an attempt is made to play the sound.
The settings in the third group, [Config] are each reviewed later.
Working with sounds
To control a given sound, it is just a matter of setting its corresponding LVar to the value listed below for the action you want:
1 (>L:SomeXMLControlVar, number) will play the sound once, with no changes made to volume or pan settings.
0 (>L:SomeOtherXMLControlVar, number) will stop the sound if it is playing.
8 (>L:YetAnotherXMLControlVar, number) will first retrieve the current volume and pan input settings. It will then apply them to the sound in question, and finally, with start playing the sound in looping mode.
Gauge control variables can use the following values:
0 - Stop Sound
1 - Play sound once, without changing the existing volume or pan settings.
2 - Play sound as a loop, without changing the existing volume or pan settings.
3 - Set the sound's volume, using the setting found in the specified VolumeIn variable, see below.
4 - Get the sound's current volume setting, placing it in the specified VolumeOut variable.
5 - Set the sound's pan, using the setting found in the specified PanIn variable.
6 - Get the sound's current pan setting, placing it in the specified PanOut variable.
7 - Play sound once, but first set the volume and pan to the settings found in the VolumeIn and PanIn variables.
8 - Play sound as a loop, but first set the volume and pan to the settings found in the VolumeIn and PanIn variables.
9 - Get sound's looping status. Will return 1 if a playing sound is looping, 0 if the sound is in play once mode or is not playing at all.
10 – Unload a sound. Sounds will be automatically unloaded on gauge exit, but if the sound file is large, and you are done with it, you might want to unload it immediately, and reclaim the memory. This command may also be useful during testing. You can make changes to a sound and reload it, without reloading the whole panel.
11 – Load a sound, using the Windows voice device. By default the gauge will use the Windows sound device for playing sounds. If you want to use the Windows voice device (typically a second sound card, or USB sound device) you can use the value of 11 to load the sound for playing on the voice device. All of the other commands, if they have to load a sound before carrying out their own function, will load the sound for the Windows sound device