Miles Sound System SDK 7.2a

AIL_set_sample_volume_pan

The function AIL_set_sample_volume_pan controls a sample's playback volume level and pan.

void AIL_set_sample_volume_pan(
  HSAMPLE S,
  F32 volume,
  F32 pan
);

In Parameters

S: indicates the sample whose volume is to be set.
volume: is a volume level from 0 (minimum) to 1.0 (maximum) in loudness (0.5 is 10 dB down).
pan: is a power pan level from 0 (hard-left) to 1.0 (hard-right).

Discussion

The volume setting is linear in loudness (not amplitude) - using 0.5 is equivalent to 10 dB down. Use AIL_set_sample_volume_levels to set volumes linear in amplitude.

All sample volume scaling occurs at full sample precision.

When a sample handle is initialized by AIL_init_sample, the sample's volume value is set to 1.0 and the pan value is set to 0.5.

The pan setting is a power pan (DLS standard). Sliding the pan from left to right adjusts the internal volume as well, such that the sound feels like it remains at the same power as it pans across the speakers.

Pan has no effect when mono audio data is played with mono sound ouput. When mono audio data is played with stereo hardware, the panpot setting determines the sample's location in the stereo field. When stereo data is played with stereo hardware, the panpot setting acts as a stereo balance control, determining the relative volume levels in the left and right channels. At 0.5, the balance control is considered at midrange, and no attenuation takes place in either channel.

You won't hear pan changes unless you open the digital driver in modes with 2 or more output channels. Make sure you use 2 channels, or a multispeaker-compatible MSS_MC_SPEC value, in your call to AIL_open_digital_driver.

Finally, note that for mono samples that will undergo 3D positioning, you should always use a pan value of 0.5. Any other pan value will cause the 3D positioner to favor one speaker or the other in each successive multichannel pair.

Example files that use this function: SSTEST.C

Group: Digital Audio Services
Related Functions: AIL_digital_master_volume_level, AIL_init_sample, AIL_open_digital_driver, AIL_sample_51_volume_pan, AIL_sample_buffer_available, AIL_sample_volume_pan, AIL_set_digital_master_volume_level, AIL_set_sample_51_volume_pan, AIL_set_sample_low_pass_cut_off, AIL_set_sample_reverb_levels, AIL_set_sample_volume_levels
Related Basic Types: F32, HSAMPLE, MSS_MC_SPEC, void
Related FAQs: How do I use multi-channel sound output in Miles?, I used an older version of Miles and now my volume and pan calls are weird - what's going on? And what's with the two types of volume functions?