Miles Sound System SDK 7.2a

AIL_register_falloff_function_callback

The function AIL_register_falloff_function_callback allows an application to override the system's default distance-based attenuation calculations for 3D-enabled samples.

AILFALLOFFCB AIL_register_falloff_function_callback(
  HSAMPLE S,
  AILFALLOFFCB falloff_function
);

In Parameters

S: indicates the sample for which the 3D falloff-function handler is to be installed.
falloff_function: should be set to the address of a user callback function which calculates the distance-based attenuation scalar for an HSAMPLE. A value of NULL restores the system's default (DirectSound3D-style) distance-calculation behavior.

Returns

The address of the previously-installed falloff-function handler (which may be a function internal to MSS if no previous user callback has been registered).

Discussion

When calculating how much to attenuate the volume of a 3D-enabled HSAMPLE based on its distance from the listener, the Miles Sound System normally uses an algorithm similar to the one that DirectSound3D and other standard 3D-sound APIs have traditionally employed. Specifically, the HSAMPLE's level is reduced by a linear scale factor of 0.5 (6 dB) for each doubling of the distance between the emitter and the listener's minimum-distance boundary. The default MSS falloff-function handler looks like this:


   F32 AILCALLBACK default_falloff_function (HSAMPLE   S, 
                                             F32       distance,
                                             F32       rolloff_factor,
                                             F32       min_dist,
                                             F32       max_dist)
   {
      return min_dist / (min_dist + (rolloff_factor * (distance - min_dist)));
   }

It's important to note that user falloff functions have no effect on 3D-hardware processed HSAMPLEs. These include HSAMPLEs played through EAX/DirectSound3D providers, as well as HSAMPLEs played on the original Xbox when the driver has been opened with the AIL_OPEN_DIGITAL_NEED_HW_3D, AIL_OPEN_DIGITAL_NEED_FULL_3D, or AIL_OPEN_DIGITAL_NEED_LIGHT_3D flags.

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: AILFALLOFFCB, AIL_sample_3D_distances, AIL_set_sample_3D_distances
Related Basic Types: HSAMPLE
Related FAQs: What's the deal with callbacks - are they threads, interrupts, system timers, or what?