Miles Sound System SDK 7.2a

AIL_set_sample_3D_distances

The function AIL_set_sample_3D_distances sets the minimum and maximum distances for a given sample handle.

void AIL_set_sample_3D_distances(
  HSAMPLE S,
  F32 max_dist,
  F32 min_dist,
  S32 auto_3D_wet_atten
);

In Parameters

S: indicates the sample handle whose distances are to be set.
max_dist: is the distance at which the sound will be clipped to silence. Note that this parameter does not affect the volume falloff curve.
min_dist: is the distance at which the sound will be at maximum volume. That is, any sound that is this distance or closer to the listener will be at maximum volume.
auto_3D_wet_atten: determines whether environmental reverb effects on this HSAMPLE will be attenuated along with the HSAMPLE itself as the source recedes from the listener's location. Most applications should set this parameter to a nonzero value to enable automatic attenuation of the wet mix.

Discussion

Since sound effects should always be normalized to use the maximum resolution of the sound's bit depth (8-bit or 16-bit), you'll need to use the minimum and maximum sample distances to make each sound "feel correct" as it approaches and moves away from the listener.

For example, a bumblebee could have a minimum-distance characteristic of 0.25, and maximum distance of one meter. In contrast, a jet plane might have a minimum distance of a hundred meters (where it's loudest) and a maximum distance of two thousand meters (where it's clipped to silence).

You can override the system's default 3D-distance attenuation behavior by registering a custom falloff function with AIL_register_falloff_function_callback. By default, as a sound approaches the listener, each time the distance between the listener and the sound is halved, the volume of the sound is doubled. This means that any sound at the maximum distance or greater from the listener is silent, any sound within the minimum distance is the maximum volume, and in between the minimum and maximum distances, the volume is set to one half as loud each time the distance from the listener to the minimum distance is doubled.

Another way to look at it is that if your minimum distance was 1, then at 2 your volume would be 50%, at 4 your volume would be 25%, at 8 your volume would be 12.5%, etc. Basically, just remember that it is not a linear falloff!

This is why you can't use zero for the minimum distance with the default MSS falloff-calculation mechanism in place - the sound volume would fall off infinitely fast and you'd never hear anything.

Note that the maximum distance doesn't affect the volume falloff curve! The maximum distance just establishes a hard clip point where the volume is forced to zero.

Also note that some DirectSound drivers don't implement the maximum distance correctly with the DSBCAPS_MUTE3DATMAXDISTANCE flag. At the maximum distance on these drivers, the volume doesn't drop to zero -- instead, it just stops falling off.

Example files that use this function: examms.cpp

Group: Digital Audio Services
Related Functions: AILFALLOFFCB, AIL_active_sample_count, AIL_calculate_3D_channel_levels, AIL_register_falloff_function_callback, AIL_sample_3D_distances, AIL_set_3D_distance_factor, AIL_set_3D_rolloff_factor, AIL_set_sample_3D_cone, AIL_set_sample_3D_position
Related Basic Types: F32, HSAMPLE, MILES_OPEN_DIGITAL_FLAGS, S32, void
Related FAQs: How do I play a 3D digital sound?, How do I use multi-channel sound output in Miles?, My 3D sound isn't falling off like I expected - what's going on?, What's the best way to port my older Miles application to MSS 7?