Miles Sound System SDK 7.2a

AIL_digital_handle_release

The function AIL_digital_handle_release temporarily releases the hardware digital handle (either the HWAVEOUT handle, the DirectSound object, or the Sound Manager buffer) back to the system.

S32 AIL_digital_handle_release(
  HDIGDRIVER dig
);

In Parameters

dig: indicates the driver to release to the system.

Returns

Non-zero on success. Zero if the dig parameter is null or invalid, or if a per-voice output filter (e.g., DirectSound3D or EAX) is in use.

Discussion

On Windows, this function is usually used with the AIL_digital_handle_release function in the WM_ACTIVATEAPP message processing code to allow other applications to play digital sound.

On MacOS, other applications can always still play audio - that is, Sound Manager can still be used by other applications when Miles is using it.

This function will automatically pause any samples that are currently playing. These samples will then be automatically restarted when AIL_digital_handle_reacquire is called.

This function is also a convenient way to play Video for Windows AVI files inside an MSS application.

Under MacOS 9, this function must not be invoked from an interrupt-based callback function.

This function is not supported under the MS-DOS, Xbox, Wii, Sony PS2 or Sony PS3 versions of MSS.

Under Windows, this function will fail, returning zero, if a per-voice hardware provider such as a DirectSound3D or EAX output filter is in use. Because the system can't guarantee that we'll be able to reassign hardware voices to all active HSAMPLEs, supporting automatic release/reacquire capability isn't practical when we're not doing the mixing ourselves. In general, we strongly recommend that your application maintain its own 'shadow' state for its playing HSAMPLEs. Use MSS to render your application's audio state -- not to store it. The examms.cpp demo program offers a useful illustration of this technique. It can shut down and reopen its HDIGDRIVER, restoring its complete playback state from application-owned structures without using AIL_digital_handle_release or AIL_digital_handle_reacquire at all.

Group: Digital Audio Services
Related Functions: AIL_digital_handle_reacquire, AIL_digital_handle_release, AIL_open_input
Related Basic Types: HDIGDRIVER, MILES_DIGITAL_STATUS, S32