Miles Sound System SDK 7.2a

AIL_allocate_sample_handle

The function AIL_allocate_sample_handle searches for a free sample handle and returns it to the application for use in the playback of digital audio data.

HSAMPLE AIL_allocate_sample_handle(
  HDIGDRIVER dig
);

In Parameters

dig: specifies which digital audio driver is to play the audio data associated with the sample handle.

Returns

A handle to an available sample slot, or NULL if all sample handles have already been allocated.

Discussion

Each digital audio driver, when installed, is provided with a number of sample handles. Sample handles are reusable descriptors for application audio data at any moment in time, each instance of a playing digital sample must be associated with a sample handle. The number of sample handles allocated, hence the maximum number of HSAMPLE sample handles available from AIL_allocate_sample_handle, is determined by the DIG_MIXER_CHANNELS preference. This value is normally 64, but can be set to any value by use of the AIL_set_preference function prior to driver installation.

When a per-voice digital output option such as DirectSound3D or EAX is selected, the number of available HSAMPLE handles is limited by hardware... and is typically much smaller than 64! You must check the return value from AIL_allocate_sample_handle rather than simply assuming that DIG_MIXER_CHANNELS handles will be available under all conditions.

After loading a digital audio driver, the application should allocate as many sample handles as it will require, based on the maximum number of simultaneous sound effects needed. When a sound effect is to be played, the application calls AIL_sample_status for each of its allocated sample handles, searching for one with the status SMP_DONE. This indicates that the system is either finished playing the last audio sample assigned to the sample handle, or that the sample handle has been allocated but not yet used to play a sample. Assuming an available sample handle is found, the next step is to call AIL_init_sample to prepare the sample handle for use with new data, followed by calls to set the address, size, playback volume, and other playback information. (Alternatively, file images may be passed directly to MSS with the AIL_set_sample_file and AIL_set_named_sample_file functions.) Playback of the sample data will begin when AIL_start_sample is called.

The number of simultaneously-playing samples which should be allowed by the application varies. Products which can afford to dedicate more CPU time to sound-effects processing may permit the maximum number of available sample handles to be active at once. In reality, however, the human ear has a very difficult time sorting out more than eight or ten sounds at once, and too many additional sounds are likely to waste processor time without conveying any meaningful information to the user.

Example files that use this function: SSTEST.C, DBTEST.C, DIGPLAY.C, EXAMMS.CPP

Group: Digital Audio Services
Related Functions: AIL_allocate_sample_handle, AIL_end_sample, AIL_init_sample, AIL_output_filter_driver_property, AIL_release_sample_handle, AIL_sample_buffer_available, AIL_sample_status, AIL_set_named_sample_file, AIL_set_preference, AIL_set_sample_file, AIL_start_sample, AIL_stop_sample
Related Basic Types: HDIGDRIVER, HSAMPLE, MILES_DIGITAL_STATUS, MILES_PREFERENCES
Related FAQs: How can I play two HSAMPLEs from the same memory address?, How do I play a digital sound?