Miles Sound System SDK 7.2a

AIL_set_speaker_configuration

The function AIL_set_speaker_configuration establishes the listener-relative location of the speaker array, and the falloff power factor used for sample spatialization.

void AIL_set_speaker_configuration(
  HDIGDRIVER dig,
  MSSVECTOR3D const *array,
  S32 n_channels,
  F32 falloff_power
);

In Parameters

dig: indicates the HDIGDRIVER whose speaker configuration is to be set.
array: specifies an array of 3D unit vectors which point to the speakers corresponding to the logical channels in the current output configuration.
n_channels: specifies the number of speaker location entries actually submitted. This can be 0 if you only wish to set the falloff power.
falloff_power: specifies the falloff power factor to be used for sample positioning.

Discussion

When MSS opens an HDIGDRIVER in configurations other than DirectSound3D/EAX, it chooses a reasonable set of default positions for the speakers in the configuration. In most cases, the speakers with directional characteristics (i.e., other than the subwoofer/LFE channel) are arrayed at roughly-equal intervals around the unit circle. Sophisticated applications may wish to allow the user to alter MSS's speaker positions to match the positions of the actual speakers that surround the listener. You can call AIL_set_speaker_configuration to submit an array containing zero to n speaker locations, where n is the number of logical channels in the configuration as reported by AIL_speaker_configuration. The submitted speaker locations will replace the default locations chosen at driver initialization time.

You may also wish to specify a falloff power greater than 1.0 to exaggerate the movement of sounds between speakers. At 1.0, MSS's 3D pan function is constant in power. A sound will not appear to grow louder or software as it moves around the listener, providing it remains equidistant. Higher falloff powers can make games sound more 'interesting' due to increased apparent movement of sound sources... but this effect comes at the expense of level accuracy, as the sound will not tend to be as loud when it's positioned between speakers. The examms example program can help you judge the effect of different falloff powers.

You can use AIL_set_speaker_configuration to change the falloff power without supplying new speaker locations. To do this, simply pass 0 for n_channels and NULL for array.

This function will have no effect with per-voice hardware drivers that don't use the Miles software mixer. Currently, this applies only to the MSS_MC_DIRECTSOUND3D and MSS_MC_EAX? values from the MSS_MC_SPEC list, since these providers use DirectSound3D voices for output.

For a detailed understanding of speaker configurations, you should carefully review the How do I use multi-channel sound output in Miles? FAQ before attempting to use this function.

Group: Digital Audio Services
Related Functions: AIL_set_speaker_configuration, AIL_speaker_configuration
Related Basic Types: F32, HDIGDRIVER, MSS_MC_SPEC, S32, void
Related Structures: MSSVECTOR3D
Related FAQs: How do I use multi-channel sound output in Miles?