Miles Sound System SDK 7.2a

AIL_minimum_sample_buffer_size

The function AIL_minimum_sample_buffer_size returns the minimum usable buffer size for use with the low-level streaming function AIL_load_sample_buffer.

S32 AIL_minimum_sample_buffer_size(
  HDIGDRIVER dig,
  S32 playback_rate,
  S32 format
);

In Parameters

dig: specifies which digital audio driver is to be used for low-level streaming audio playback.
playback_rate: specifies the intended playback rate in samples per second.
format: specifies the format of the audio data to be played. See AIL_init_sample for a description of the available audio formats.

Returns

The lowest usable size in bytes for each of the individual buffers used by the AIL_load_sample_buffer function.

Discussion

When playing uncompressed PCM data, MSS's built-in low-level streaming mechanism (namely, the AIL_sample_buffer_available and AIL_load_sample_buffer functions) cannot be used with buffers which are smaller than the hardware half-buffer size used at the hardware level, because the hardware buffer can be filled with sample data only at its beginning and half-buffer points. The AIL_minimum_sample_buffer_size function returns the smallest PCM buffer size which can be used with a given driver configuration.

The value returned by this function is a minimum value, which will typically range from 2K to 8K bytes. Use of smaller buffers is likely to cause audio dropouts. It is permissible, and often advisable, to use larger buffer sizes than that recommended by AIL_minimum_sample_buffer_size. For example, applications which are unable to poll the AIL_sample_buffer_available function frequently may need to employ buffer sizes of 16K, 32K, or greater.

In calculating the minimum usable buffer size, this function takes into account the difference between the driver's hardware playback rate and the sample's playback rate, as well as any conversions between 8-bit and 16-bit or mono and stereo formats that automatically occur during playback. Consequently, the value returned may be greater or less than the actual hardware half-buffer size. If the playback rate will be varied during the low-level streaming process, the highest rate to be used should be passed to AIL_minimum_sample_buffer_size so that the buffer size can accommodate variations at playback time.

Buffers which are smaller than the minimum size can be used under three conditions: (1) when the final fragment of sample data is being submitted; (2) when compressed data (.MP3, .OGG, etc.) is being played; and (3) when AIL_set_sample_buffer_count is used to make more than two low-level streaming buffers available for a given HSAMPLE. In general, as long as the mixer has enough data to avoid starvation in the interval(s) before the next time the buffers are serviced, dropouts will not occur.

Applications which play synchronized audio-video streams with small audio chunks (less than 4-8K) must be designed to queue video and/or audio frame data in memory, in order to present audio buffers of sufficient size to the low-level streaming playback routines.

Example files that use this function: DBTEST.C

Group: Digital Audio Services
Related Functions: AIL_init_sample, AIL_load_sample_buffer, AIL_minimum_sample_buffer_size, AIL_sample_buffer_available, AIL_sample_buffer_info, AIL_set_sample_buffer_count
Related Basic Types: HDIGDRIVER, S32