Miles Sound System SDK 7.2a

AILFALLOFFCB

The function AILFALLOFFCB specifies a user-defined 3D distance-based falloff function callback.

F32 AILCALLBACK AILFALLOFFCB(
  HSAMPLE sample,
  F32 distance,
  F32 rolloff_factor,
  F32 min_distance,
  F32 max_distance
);

In Parameters

sample: indicates the HSAMPLE for which the callback is being issued.
distance: indicates the distance (in user units) between the emitter and listener.
rolloff_factor: indicates the rolloff factor. This value defaults to 1.0, but can be altered by calling AIL_set_3D_rolloff_factor.
min_distance: indicates the sample's minimum distance, as defined by the most recent call to AIL_set_sample_3D_distances.
max_distance: indicates the sample's maximum distance, as defined by the most recent call to AIL_set_sample_3D_distances.

Returns

This callback should return a value from 0.0 to 1.0, which will be treated as a linear amplitude scalar during the system's internal volume calculations. The equivalent gain in dB will be 20 * log10 (value) -- for example, a 6-dB power attenuation value would correspond to a returned value of 0.5.

Discussion

Note that falloff-function callbacks are invoked during background HSAMPLE processing. You should be careful not to make any API calls from within a falloff-function callback that could affect the state of the HSAMPLE or its corresponding HDIGDRIVER. If you do anything other than basic 3D state queries, undefined behavior may result. If in doubt about whether a particular action may safely be performed from within a falloff-function callback, contact RAD Game Tools for assistance.

Group: Digital Audio Services
Related Functions: AIL_register_falloff_function_callback, AIL_set_3D_rolloff_factor, AIL_set_sample_3D_distances
Related Basic Types: F32, HSAMPLE