Miles Sound System SDK 7.2a

AIL_calculate_3D_channel_levels

The function AIL_calculate_3D_channel_levels gives your application direct access to the Miles 3D sound-positioner function.

S32 AIL_calculate_3D_channel_levels(
  HDIGDRIVER dig,
  F32 *channel_levels,
  MSS_SPEAKER * *speaker_array,
  MSSVECTOR3D const *src_pos,
  MSSVECTOR3D const *src_face,
  MSSVECTOR3D const *src_up,
  F32 src_inner_angle,
  F32 src_outer_angle,
  F32 src_outer_volume,
  F32 src_max_dist,
  F32 src_min_dist,
  MSSVECTOR3D const *listen_pos,
  MSSVECTOR3D const *listen_face,
  MSSVECTOR3D const *listen_up,
  F32 rolloff_factor,
  MSSVECTOR3D const *doppler_velocity,
  F32 *doppler_shift
);

In Parameters

dig: specifies the digital audio driver from which to acquire the listener-relative speaker location and falloff-power parameters.
src_pos: specifies the effective 3D position of an audio emitter (source) object.
src_face: specifies the source object's facing direction (front vector).
src_up: specifies the source object's up vector.
src_inner_angle: is the inner angle of the source's sound cone in degrees (0 to 360). If the listener is within this angle of this sample, then the sound is at its normal volume (based on its volume, distance, occlusion, etc). The src_inner_angle value should always be smaller than, or equal to, src_outer_angle. A value of 360.0 disables cone attenuation entirely.
src_outer_angle: is the outer angle of the source's sound cone in degrees (0 to 360). If the listener is outside the inner angle but still inside the outer angle, then the effective volume is scaled linearly from no scaling (when close to the inner angle) to the outer_volume value (when close or greater than the outer angle).
src_outer_volume: is the amount to scale the normal volume to when outside the outer angle. A value of 0 means the normal volume is scaled all the way to zero. A volume of 1.0 means that the normal volume isn't scaled at all (and you wouldn't hear a difference when inside or outside of the cone).
src_max_dist: is the distance from the source position to the listener position at which the sound will be clipped to silence. Note that this parameter does not affect the volume falloff curve.
src_min_dist: is the distance from the source position to the listener position 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.
listen_pos: specifies the effective 3D position of the listener object.
listen_face: specifies the listener object's facing direction (front vector).
listen_up: specifies the listener object's up vector.
rolloff_factor: specifies how fast 3D audio will fall off with distance. The default is 1.0, which implies no change to the "real-world" falloff speed. You can double the falloff rate by using 2.0, and you can turn off the falloff completely by using 0.0.
doppler_velocity: specifies the relative velocity of the source relative to (i.e., subtracted from) that of the listener, or NULL if no Doppler-shift calculations are desired.

Out Parameters

channel_levels: specifies a pointer to an array of at least MAX_SPEAKERS single-precision floating-point variables which will receive the calculated channel levels, from 0.0 to 1.0.
speaker_array: specifies a pointer to a variable of type MSS_SPEAKER * which will receive the address of the array of speaker locations corresponding to each channel_levels entry. (This array is internal to MSS, and is always the same for a given HDIGDRIVER).
doppler_shift: returns the factor by which the sample or stream's playback rate should be modified to implement the doppler_velocity parameter. This parameter can be NULL if no Doppler-shift calculations are desired.

Returns

The number of entries written to the channel_levels array (as well as the number of entries in the array whose location is written to *speaker_array). This will be the same as the n_logical_channels value returned by AIL_speaker_configuration.

Discussion

This function gives you the ability to position sounds in 3D space yourself without going through the normal Miles 3D sample/listener API. Its output consists of two parallel arrays, channel_levels and speaker_array, which are suitable for use as the levels and dest_speaker_indexes inputs to the AIL_set_sample_channel_levels function. Additionally, an optional Doppler-shift factor that can be applied with AIL_set_sample_playback_rate is also returned.

You can use this function in cases where you don't want MSS to maintain its own copy of an HSAMPLE's 3D state for any reason, or when you wish to modify the results of the default 3D positioning algorithm used by the library. An example might be an application requiring multiple "listeners" on the same physical platform; e.g., a split-screen multiplayer title.

For details on sound positions, cones, and distance attenuation, refer to the AIL_set_sample_3D_position, AIL_set_sample_3D_cone, AIL_set_sample_3D_distances, and AIL_set_3D_rolloff_factor functions. For simplicity's sake, most applications should use these functions rather than calling AIL_calculate_3D_channel_levels manually.

Note that the auto_3D_wet_atten parameter in AIL_set_sample_3D_distances has no corresponding functionality when AIL_calculate_3D_channel_levels is used. If you need to scale wet-reverb attenuation based on distance while using AIL_calculate_3D_channel_levels, you'll need to perform the calculation separately and pass the result to AIL_set_sample_reverb_levels.

For more information on channel-based control functions such as this one, you can review the How do I use multi-channel sound output in Miles? FAQ.

Group: Digital Audio Services
Related Functions: AIL_calculate_3D_channel_levels, AIL_set_3D_rolloff_factor, AIL_set_sample_3D_cone, AIL_set_sample_3D_distances, AIL_set_sample_3D_position, AIL_set_sample_channel_levels, AIL_set_sample_playback_rate, AIL_set_sample_reverb_levels, AIL_speaker_configuration
Related Basic Types: F32, HDIGDRIVER, MSS_SPEAKER, S32
Related Structures: MSSVECTOR3D
Related FAQs: How do I use multi-channel sound output in Miles?