Miles Sound System SDK 7.2a

AIL_set_sample_file

The function AIL_set_sample_file initializes a sample's address, length, type, and flags to prepare for playback of memory-resident sound data.

S32 AIL_set_sample_file(
  HSAMPLE S,
  void const * file_image,
  S32 block
);

In Parameters

S: indicates the sample to prepare for .VOC or .WAV file playback.
file_image: points to the start of the file image in memory.
block: specifies a block number to play in the file. block is ignored with formats for which MSS does not support multiple blocks, such as the .WAV format. Use 0 as a default value for most applications.

Returns

0 if the file could not be parsed or if the desired block was not found; otherwise, a non-zero return value indicates the sample handle was successfully prepared for file playback.

Discussion

This function can parse a VOC file, uncompressed .WAV file, IMA ADPCM compressed .WAV file, .WAV-wrapped XMA file (on the Xbox 360), Ogg Vorbis file, .WAV-wrapped MPEG Layer 3 file, or Xbox ADPCM file on the original Xbox.

This function is identical to the AIL_allocate_file_sample function found in pre-MSS 7 releases, except that it uses an existing HSAMPLE handle rather than allocating a new one. AIL_set_sample_file is more appropriate for applications which need to maintain control over file handle management for memory-resident .VOC or .WAV file playback.

This function will process an MPEG Layer-3 file only if it is wrapped in a Microsoft WAVE header wrapper. To play a standard MP3 file image, use the AIL_set_named_sample_file function instead.

It is not necessary to call AIL_init_sample, AIL_set_sample_playback_rate, or AIL_set_sample_address when using this function. The HSAMPLE is initialized automatically by the system, just as if AIL_init_sample had been called explicitly.

Group: Digital Audio Services
Related Functions: AIL_allocate_sample_handle, AIL_init_sample, AIL_sample_buffer_available, AIL_set_named_sample_file, AIL_set_sample_3D_position, AIL_set_sample_address, AIL_set_sample_file, AIL_set_sample_info, AIL_set_sample_playback_rate, AIL_start_sample
Related Basic Types: HSAMPLE, S32, void const *
Related FAQs: How can I play two HSAMPLEs from the same memory address?, How do I play a digital sound?, How do I set a DSP filter on a sample?, How do I use multi-channel sound output in Miles?, What is MPEG Audio and MP3?, What's the best way to port my older Miles application to MSS 7?, When can I free the memory I gave to MSS?