AIL_speaker_configuration

The function AIL_speaker_configuration returns an array of 3D vectors describing the listener-relative locations of the array of speakers associated with the current output format, plus some additional information about the format.

MSSVECTOR3D * AIL_speaker_configuration(
  HDIGDRIVER dig,
  S32 *n_physical_channels,
  S32 *n_logical_channels,
  F32 *falloff_power,
  MSS_MC_SPEC *channel_spec
);

In Parameters

dig

indicates the HDIGDRIVER whose configuration information is to be returned.

Out Parameters

n_physical_channels

specifies a pointer to a variable of type S32 which will receive the number of physical output channels. This may be less than the number of logical channels used elsewhere by MSS, in the case of a matrix provider such as Dolby or SRS that multiplexes several logical channels onto two physical channels. It will be zero if a per-voice output filter is in use.

n_logical_channels

specifies a pointer to a variable of type S32 which will receive the number of output channels the Miles mixer will write to. It will be zero if a per-voice output filter is in use.

falloff_power

specifies a pointer to a variable of type F32 which will receive the falloff power in use by the Miles mixer. This will not be meaningful if a per-voice output filter is in use.

channel_spec

specifies a pointer to a variable of type MSS_MC_SPEC which will receive the channel specification that was actually opened by AIL_open_digital_driver or AIL_quick_startup.

Returns

The array of n_logical_channels 3D vectors describing the listener-relative positions of the speakers associated with the current output format.

Discussion

This function lets you retrieve the configuration information resulting from the last successful call to AIL_open_digital_driver or AIL_quick_startup. If you pass MSS_MC_USE_SYSTEM_CONFIG to these functions, you can call AIL_speaker_configuration to discover what was actually chosen by the system.

MSS_MC_SPEC enum	Physical/logical channels	Logical SPEAKER_ array
MSS_MC_DIRECTSOUND3D	0/0	NA
MSS_MC_EAX2	0/0	NA
MSS_MC_EAX3	0/0	NA
MSS_MC_EAX4	0/0	NA
MSS_MC_MONO	1/1	FL
MSS_MC_STEREO	2/2	FL,FR
MSS_MC_HEADPHONES	2/2	FL,FR
MSS_MC_40_DISCRETE	4/4	FL,FR,BL,BR
MSS_MC_DOLBY_SURROUND	2/3	FL,FR,BC
MSS_MC_SRS_CIRCLE_SURROUND	2/7	FL,FR,FC,LF,BL,BR,BC
MSS_MC_51_DISCRETE	6/6	FL,FR,FC,LF,BL,BR
MSS_MC_61_DISCRETE	7/7	FL,FR,FC,LF,BL,BR,BC
MSS_MC_71_DISCRETE	8/8	FL,FR,FC,LF,BL,BR,SL,SR
MSS_MC_81_DISCRETE	9/9	FL,FR,FC,LF,BL,BR,BC,SL,SR

You can obtain the number of physical and logical channels in use by calling AIL_speaker_configuration, as well as the MSS_MC_SPEC value passed to (or chosen by) AIL_open_digital_driver. As can be seen in the table above, these will be identical for all conventional (non-matrix) discrete formats, while matrix formats such as Dolby and SRS Circle Surround(r) can map three or more logical channels onto two physical channels. DirectSound3D and EAX will report zero physical channels and zero logical channels, since Windows insulates the application from these details.

For a detailed understanding of per-channel level control, 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_calculate_3D_channel_levels, AIL_open_digital_driver, AIL_quick_startup, AIL_set_speaker_configuration, AIL_speaker_configuration
Related Basic Types: F32, HDIGDRIVER, MSS_MC_SPEC, S32
Related Structures: MSSVECTOR3D
Related FAQs: How do I use multi-channel sound output in Miles?

For technical support, e-mail Miles3@radgametools.com
© Copyright 1991-2007 RAD Game Tools, Inc. All Rights Reserved.