Miles Sound System SDK 7.2a

AIL_init_sample

The function AIL_init_sample prepares a sample handle for playback of audio data.

S32 AIL_init_sample(
  HSAMPLE S,
  S32 format,
  U32 flags
);

In Parameters

S: indicates the sample handle to prepare for audio playback.
format: should be set to one of the MILES_DIGITAL_FORMAT equates.
flags: should be set to a combination of the MILES_DIGITAL_FLAGS equates.

Returns

Nonzero if the sample handle initialization succeeded; zero if a failure occurred.

Discussion

This function initializes all parameters associated with a sample handle to a set of nominal values. It should be called immediately after allocating a sample handle with AIL_allocate_sample_handle, as well as anytime an existing sample handle is used to play a new audio data sample. (Applications that play audio file images directly with AIL_set_sample_file or AIL_set_named_sample_file do not need to call AIL_init_sample at all.)

AIL_init_sample initializes the sample's playback information as follows:

The sample's status is set to SMP_DONE.

Any filters applied to the sample are disconnected.

The starting addresses of both the primary and secondary sample buffers are set to NULL, and their lengths are set to 0. Consequently, normal single-buffer playback is enabled.

The sample's position counter is set to 0 (start-of-sample).

The sample's loop counter is set to 1 (no looping).

The sample playback rate is initialized to 11025 Hz.

The sample's volume value is set to 1.0.

The sample's wet mix level is set to 0.0 and its dry mix level is set to 1.0. Occlusion, obstruction, and exclusion levels are all set to 0.0.

If the sample was under 3D positional control (i.e., the application has called AIL_set_sample_3D_position on it), it is returned to normal 2D-only mode, with its channel levels under application control. (The channel level scalars themselves are all set to 1.0.) All of the sample's internal 3D-positional data members are reset to nominal values (position at origin, up=+Y, face=+X, no emission cone, minimum distance 1.0, maximum distance 200.0, 3D auto wet-attenuation flag=TRUE).

The sample's panpot value is set to 0.5 (dead center) on a scale of 0 (hard left) to 1.0 (hard right).

The start-of-block, end-of-buffer, and end-of-sample callbacks are all canceled.

Since AIL_init_sample resets parameters such as volume, pan location, loop count, and other playback characteristics, it should appear before any calls to functions such as AIL_set_sample_volume_pan or AIL_set_sample_loop_count, or these functions will have no effect. Of course, only values which the application wishes to change from their defaults need to be set prior to calling AIL_start_sample.

None of the digital audio library functions alter or modify application sample data in any way. The same sample data may safely be passed to other drivers (or even used more than once per driver) without being reloaded into memory.

Note that stereo data is normally encountered in LR (left-to-right, in order of ascending memory location) order. If RL data from a nonstandard source is played, the DIG_PCM_ORDER flag should be set. Stereo data is not supported by the original Xbox HDIGDRIVERs when hardware 3D is enabled.

In all cases, the MSS digital playback system acts as an arbitrator between the application's data format and the limitations of the hardware in use. For example, if an attempt is made to play 16-bit 44 kHz signed stereo data with a basic mono 8-bit unsigned-PCM Sound Blaster card installed, MSS will mix the left and right channels together, scale each channel's amplitude according to the sample panpot setting, truncate the lower 8 bits of each sample, and invert the sign of the remaining 8 bits while undersampling the input data to conform to the hardware sample rate in use - all without the knowledge or intervention of the application program.

Again, it is not necessary to call this function if AIL_set_named_sample_file, AIL_set_sample_file or AIL_set_sample_info is used to play memory-resident files directly.

This function will not normally fail unless a memory-allocation failure occurs while attempting to allocate the (relatively-small) arrays associated with level-scaling and other per-channel properties. If AIL_init_sample returns 0 for failure, the AIL_last_error function may be called to obtain the error description.

Example files that use this function: SSTEST.C

Group: Digital Audio Services
Related Functions: AIL_allocate_sample_handle, AIL_init_sample, AIL_last_error, AIL_minimum_sample_buffer_size, AIL_sample_buffer_available, AIL_set_named_sample_file, AIL_set_sample_3D_position, AIL_set_sample_51_volume_pan, AIL_set_sample_address, AIL_set_sample_file, AIL_set_sample_info, AIL_set_sample_loop_count, AIL_set_sample_volume_levels, AIL_set_sample_volume_pan, AIL_start_sample, AIL_stream_info
Related Basic Types: DIGDRVSTAGE, HSAMPLE, MILES_DIGITAL_FLAGS, MILES_DIGITAL_FORMAT, MILES_DIGITAL_STATUS, S32, U32
Related FAQs: How do I set a DSP filter on a sample?, How do I use multi-channel sound output in Miles?, What's the best way to port my older Miles application to MSS 7?