This section describes all functions available for MIDAS initialization and configuration.
BOOL MIDASclose(void)
Uninitializes MIDAS Digital Audio System.
None.
This function uninitializes all MIDAS Digital Audio System components, deallocates all resources allocated, and shuts down all MIDAS processing. This function must always be called before exiting under MS-DOS and is also strongly recommended under other operating systems. After this function has been called, no MIDAS function may be called unless MIDAS is initialized again.
TRUE if successful, FALSE if not.
All
BOOL MIDASconfig(void)
Runs manual MIDAS setup.
None.
This function runs the manual MIDAS Digital Audio System configuration. It queries the sound card to use and desired sound quality and output mode from the user. The setup entered can be saved do disk with MIDASsaveConfig and loaded back with MIDASloadConfig, or written to registry with MIDASwriteConfigRegistry and read back with MIDASreadConfigRegistry. These functions can be used to create a simple external setup program, or just save the settings between two runs of the program. After this function has been called, MIDASsetOption can be used to change the output mode options, to, for example, force mono output.
This function returns TRUE if the setup was completed successfully, FALSE if not. The setup can fail for two reasons: either the user aborted it by pressing escape or clicking Cancel, or an error occured. As errors during the setup are extremely unlikely, it is safe to simply exit the program if this function returns FALSE. MIDASgetLastError can be used to check if an error occured -- if the return value is zero, the user just pressed cancelled the setup.
This function must be called before MIDASinit, but after MIDASstartup.
TRUE if successful, FALSE if not (the user cancelled the configuration, or an error occurred)
MS-DOS, Win32
MIDASsaveConfig, MIDASloadConfig, MIDASsetOption, MIDASgetOption, MIDASinit, MIDASwriteConfigRegistry, MIDASreadConfigRegistry
BOOL MIDASdetectSoundCard(void)
Attempts to detect the sound card to use.
None.
[MS-DOS only]
This function attempts to detect the sound card that should be used. It will set up MIDAS to use the detected card, and return TRUE if a sound card was found, FALSE if not. If this function returns FALSE, you should run MIDASconfig to let the user manually select the sound card. Note that you can use MIDAS even if no sound card has been selected - MIDAS will just not play sound in that case.
If no sound card has been manually set up, MIDASinit will automatically detect it, or use No Sound if none is available. Therefore this function does not have to be called if manual setup will not be used.
Note that, as there is no way to safely autodetect the Windows Sound System cards under MS-DOS, MIDAS will not attempt to detect them at all. If you do not provide a manual setup possibility to your program (via MIDASconfig), WSS users will not be able to get any sound. The computer may also have several sound cards, and the user may wish not to use the one automatically detected by MIDAS. Therefore it is a very good idea to include an optional manual sound setup to all programs.
This discussion naturally applies to MS-DOS only, under Win32 and Linux MIDAS uses the sound card through the system audio devices, and no sound card selection or setup is necessary.
TRUE if a sound card was detected, FALSE if not.
MS-DOS
DWORD MIDASgetDisplayRefreshRate(void)
Gets the current display refresh rate.
None.
This function tries to determine the current display refresh rate. It is used with MIDASsetTimerCallbacks to set a display-synchronized timer callback. It returns the current display refresh rate in milliHertz (ie. 1000*Hz, 50Hz becomes 50000, 70Hz 70000 etc), or 0 if it could not determine the refresh rate. The refresh rate may be unavailable when running under Win95 or a similar OS, or when the VGA card does return Vertical Retraces correctly (as some SVGA cards do in SVGA modes). Therefore it is important to check the return value, and substitute some default value if it is zero.
Unlike most other MIDAS functions, this function must be called before MIDASinit is called, as the MIDAS timer may interfere with the measurements.
Note that the display refresh rate is display mode specific. Therefore you need to set up the display mode with which you want to use display-synchronized timer callbacks before calling this function. Also, if your application uses several display modes, you must get the display refresh rate for each mode separately, and remove and restart the display-synchronized timer callbacks at each mode change.
This function is only available in MS-DOS.
The current display refresh rate, in milliHertz, or 0 if unavailable.
MS-DOS
DWORD MIDASgetOption(int option)
Gets a MIDAS option.
This function reads the current value of a MIDAS option. The different number codes for different options are described above.
TRUE if successful, FALSE if not.
All
BOOL MIDASinit(void)
Initializes MIDAS Digital Audio System.
None.
This function initializes all MIDAS Digital Audio System components, and sets up the API. Apart from configuration functions, this function must be called before any other MIDAS functions are used.
If this function fails with no apparent reason, it is very probable that some other application is using the sound card hardware or the user has badly mis-configured MIDAS. Therefore, if this function fails, it is recommended to give the user a possibility to close other applications and retry, continue with no sound (set option MIDAS_OPTION_FORCE_NO_SOUND), or possibly re-configure MIDAS.
TRUE if successful, FALSE if not.
All
BOOL MIDASloadConfig(char *fileName)
Load MIDAS setup from disk.
This function loads MIDAS setup from disk. The setup must have been saved with MIDASsaveConfig. MIDASsetOption can be used afterwards to change, for example, the output mode.
This function must be called before MIDASinit, but after MIDASstartup.
TRUE if successful, FALSE if not.
MS-DOS, Win32
BOOL MIDASreadConfigRegistry(DWORD key, char *subKey);
Reads MIDAS configuration from a registry key.
This function reads the MIDAS configuration from a registry key. The configuration must have been written there with MIDASwriteConfigRegistry. MIDASsetOption can be used afterwards to chance, for example, the output mode, and MIDASconfig to prompt the user for new settings.
This function must be called before MIDASinit, but after MIDASstartup.
TRUE if successful, FALSE if not.
Win32
MIDASconfig, MIDASwriteConfigRegistry
BOOL MIDASsaveConfig(char *fileName)
Saves the MIDAS setup to a file.
This function saves the MIDAS setup entered with MIDASconfig to a file on disk. It can be then loaded with MIDASloadConfig.
TRUE if successful, FALSE if not.
MS-DOS, Win32
BOOL MIDASsetOption(int option, DWORD value)
Sets a MIDAS option.
This function sets a value to a MIDAS option. The different number codes for different options are described above. All MIDAS configuration options must be set with this function before MIDASinit is called.
TRUE if successful, FALSE if not.
All
BOOL MIDASstartup(void)
Prepares MIDAS Digital Audio System for initialization and use.
None.
This function sets all MIDAS Digital Audio System configuration variables to default values and prepares MIDAS for use. It must be called before any other MIDAS function, including MIDASinit and MIDASsetOption, is called. After this function has been called, MIDASclose can be safely called at any point and any number of times, regardless of whether MIDAS has been initialized or not. After calling this function, you can use MIDASsetOption to change MIDAS configuration before initializing MIDAS with MIDASinit, or call MIDASconfig to prompt the user for configuration options.
TRUE if successful, FALSE if not.
All
MIDASsetOption, MIDASinit, MIDASclose
BOOL MIDASwriteConfigRegistry(DWORD key, char *subKey);
Writes the MIDAS configuration to a registry key.
This function saves the current MIDAS configuration, usually entered with MIDASconfig to a registry key. The configuration can then be read with MIDASreadConfigRegistry.
TRUE if successful, FALSE if not.
Win32
MIDASconfig, MIDASreadConfigRegistry