Miles Sound System SDK 7.2a

AIL_register_SOB_callback

The function AIL_register_SOB_callback arranges for callback service to be provided to an application's function just before a block of sample data is merged into the hardware buffer.

AILSAMPLECB AIL_register_SOB_callback(
  HSAMPLE S,
  AILSAMPLECB SOB
);

In Parameters

S: indicates the sample for which start-of-block (SOB) callback service is desired.
SOB: should be set to the address of the callback function which is to be invoked just before the audio data at AIL_sample_position is merged into the hardware buffer for playback. A value of NULL cancels start-of-block callbacks.

Returns

The address of the previously-installed SOB callback function handler.

Discussion

The Miles Sound System digital audio mixer operates on the application's audio data in small chunks, called blocks. Part of the system's responsibility is to poll the hardware buffers in the background to determine when the next block of audio data from the application should be processed and copied into an empty hardware half-buffer. As an example, consider a hardware driver which is configured to play 16-bit audio at 20,000 Hz with a pair of 1,000-byte half-buffers. The driver's data rate is 40,000 bytes per second, implying a half-buffer playback rate of 40,000 / 1,000, or 40 buffer transitions per second.

At a rate of 40 times per second, then, a sample block equivalent to one half-buffer's worth of data is fetched from the application's sample data buffer at the current playback position. The samples are resampled if necessary to conform to the driver's hardware rate, converted between 8-bit and 16-bit formats where appropriate, mathematically scaled for volume and panpot control, algebraically added to data from other active samples, clipped, and copied into the driver's empty half-buffer to be played as soon as the other half-buffer finishes playing.

Consequently, any change made to a sample's playback characteristics - be it a change in volume, panpot value, pitch, start/stop status, or playback position - must wait until the next half-buffer transition occurs before it can take effect. Certain applications, such as those employing synchronized video playback, may find it useful to set up a start-of-block callback handler with this function so they can be informed of exactly when their data is about to be processed. After the start-of-block callback occurs, the first data sample point at the current sample position (as reported by AIL_sample_position) is guaranteed to be transferred to the sound hardware in one half-buffer period or less. This period of "uncertainty" amounts to one to two half-buffer periods if the application merely relies on the time of its AIL_start_sample call to determine its audio playback timing, since a total of two hardware half-buffer transitions must occur before data from the sample is actually passed to the sound hardware.

Most MSS functions can be safely invoked from within callback functions. Exceptions include driver-installation or driver-shutdown functions and any other functions which may perform OS or BIOS calls, such as AIL_init_sequence. These exceptions are noted in the descriptions of the functions involved. If in doubt about whether a particular action may safely be performed from within a callback function, contact RAD Game Tools for assistance.

Under Win32 and Win64 on waveOut, the MSS architecture permits a sound effect to be started with essentially zero latency as long as no other sound effects are currently being played. On the other hand, latency times incurred for samples which must be injected into an already-running mixer stream may be much higher than even the worst figures obtained in the DOS version of MSS . Consequently, it is important when beginning video playback or any other latency-critical activity to ensure that no previous digital audio effects have been played for at least a few hundred milliseconds prior to starting playback of the critical sound effect or stream.

On a Win32 or Win64 system with a DirectSound driver installed, MSS will take advantage of the high-performance Microsoft DirectSound buffer mechanism to eliminate these latency problems.

Group: Digital Audio Services
Related Functions: AILSAMPLECB, AIL_init_sequence, AIL_register_EOB_callback, AIL_register_EOS_callback, AIL_sample_position, AIL_start_sample
Related Basic Types: HSAMPLE
Related FAQs: What's the deal with callbacks - are they threads, interrupts, system timers, or what?