| Miles Sound System SDK 7.2a |
The function AIL_open_digital_driver opens a digital driver to play 2D digital audio.
HDIGDRIVER AIL_open_digital_driver( U32 frequency, S32 bits, S32 channels, U32 flags ); |
If successful, this function returns a non-zero handle to a digital driver. If the driver failed to open, then 0 is returned (use AIL_last_error for the cause).
This function will open a digital driver on any of the Miles platforms.
Important: the channels parameter does not specify the number of available mixer voices! The number of mixer voices is determined by the value of the DIG_MIXER_CHANNELS preference at the time this function is called.
When using the MSS_MC_USE_SYSTEM_CONFIG flag for the channels parameter, the output configuration is determined as follows (note that not all of the speaker systems are supported on all platforms):
| Operating System Reports | Equivalent MSS_MC_SPEC Value |
|---|---|
| Headphones | MSS_MC_HEADPHONES |
| Mono speaker | MSS_MC_MONO |
| Quad speakers | MSS_MC_40_DISCRETE |
| Stereo speakers | MSS_MC_STEREO |
| Surround speakers | MSS_MC_SRS_CIRCLE_SURROUND |
| 5.1 speakers | MSS_MC_51_DISCRETE |
| 6.1 speakers | MSS_MC_61_DISCRETE |
| 5.1 speakers | MSS_MC_51_DISCRETE |
| 8.1 speakers | MSS_MC_81_DISCRETE |
You can query the chosen MSS_MC_SPEC value by calling AIL_speaker_configuration on the returned HDIGDRIVER. Unfortunately, the control-panel or other system setting may not reflect the user's actual hardware configuration. Worst, from the sound driver's point of view, the configuration may be determined by a separate, proprietary applet -- which may or may not keep itself synchronized with the operating system settings. Further, the limited range of operating system values don't begin to address all of the possible configurations (for example, under Windows there is no option for 6.1 speakers). Therefore, it's best not to rely solely on the OS to report a meaningful speaker-configuration value; we strongly recommend offering the user the ability to select an MSS_MC_ configuration directly as part of your application's sound-options dialog. So, default to MSS_MS_USE_SYSTEM_CONFIG, but give the user the ability to override.
Also on Win32 and Win64, make sure that you have created an HWND before calling this function (DirectSound requires this).
Note that under Win32 and Win64, MSS will try DirectSound first, and then fall back to waveOut if DirectSound failed to open or was using emulation mode. If you want to force DirectSound or waveOut specifically, use the AIL_OPEN_DIGITAL_FORCE_PREFERENCE flag.
On Win32 and Win64, you can use the two preferences, DIG_PREFERRED_WO_DEVICE and DIG_PREFERRED_DS_DEVICE, to force AIL_open_digital_driver and AIL_quick_startup to use a specific waveOut device ID or DirectSound LPGUID. This allows you to enumerate and open a specific sound card (or even multiple sound cards) if necessary.
Under the original Xbox, this function will open the DirectSound system.
The Xbox hardware always uses a fixed 48 Khz, 16-bit output, so the frequency, bits, and channels don't specify the output mode, but instead specify the default format of each sound buffer. You should set these parameters to those of the majority of your sound samples (if not, Miles will simply reset the format when you start the sound which is a little less efficient).
Under the Xbox 360, this function will open the XAudio system.
On the Nintendo Wii, the driver is always opened in 32038 Hz 16-bit mode.
On the Sony PS2, the driver is always opened in 48 kHz 16-bit stereo mode. The only meaningful configurations are MSS_MC_STEREO, MSS_MC_40_DTS, and MSS_MC_51_DTS.
On the Sony PS3, the driver is always opened in 48 kHz, 32-bit floating point. The only meaningful configurations are MSS_MC_STEREO, MSS_MC_51_DISCRETE, and MSS_MC_71_DISCRETE.
Under MacOS, MSS will use the Sound Manager. There have been many versions of the Sound Manager, some of which behave better than others. If you have trouble, try downloading the latest version of QuickTime - this will get you the latest version of Sound Manager.
Under DOS, MSS will set the sound format preferences and then call AIL_install_DIG_INI to load a real-mode DOS driver.
For an understanding of the options available with the output_channels parameter, see the How do I use multi-channel sound output in Miles? FAQ.
Example files that use this function: EXAMMS.CPP
Group:
Digital Audio Services
Related Sections:
Miles DTS Provider for the Sony PS2, Miles Dolby Surround Provider, Miles SRS Circle Surround Provider
Related Functions:
AIL_HWND, AIL_close_digital_driver, AIL_digital_output_filter, AIL_get_DirectSound_info, AIL_install_DIG_INI, AIL_install_DIG_driver_file, AIL_last_error, AIL_open_digital_driver, AIL_output_filter_driver_property, AIL_quick_handles, AIL_quick_startup, AIL_set_DirectSound_HWND, AIL_set_sample_playback_rate, AIL_set_sample_volume_pan, AIL_speaker_configuration
Related Basic Types:
HDIGDRIVER, MILES_OPEN_DIGITAL_FLAGS, MILES_PREFERENCES, MSS_MC_SPEC, MSS_PLATFORM_PROPERTY, S32, U32
Related FAQs:
How do I initialize the Miles Sound System for use?, How do I use multi-channel sound output in Miles?, I'm setting a preference and it isn't having any effect - what's going on?, My 3D audio is a lot louder than my 2D audio - what can I do?, My application is crashing - what should I try?, What's the best way to port my older Miles application to MSS 7?
For technical support, e-mail Miles3@radgametools.com
© Copyright 1991-2007 RAD Game Tools, Inc. All Rights Reserved.