Miles Sound System SDK 7.2a

AIL_set_sample_channel_levels

The function AIL_set_sample_channel_levels scales the output contribution from each source channel in the specified HSAMPLE to each speaker.

void AIL_set_sample_channel_levels(
  HSAMPLE S,
  MSS_SPEAKER const * source_speaker_indexes,
  MSS_SPEAKER const * dest_speaker_indexes,
  F32 const * level_array,
  S32 n_levels
);

In Parameters

S: indicates the HSAMPLE for which the channel levels are to be set.
source_speaker_indexes: specifies an array of one or more channels in the source data.
dest_speaker_indexes: specifies an array of one or more speakers.
level_array: specifies an array of coefficients from 0.0 to 1.0 which will scale the output of the HSAMPLE at each combination of source/destination channels specified by the corresponding source_speaker_indexes and dest_speaker_indexes entries.
n_levels: specifies the number of entries in level_array, source_speaker_indexes, and dest_speaker_indexes.

Discussion

This function allows the application to provide scale factors that determine the routing between the specified sample's source channels and the driver's logical output channels. The input arrays must all have the same number of elements, specified by n_levels. They can be as simple as three single-entry arrays that establish the level of a single channel at a single speaker, or a completely-general matrix where audio from any number of source channels is steered to any number of destination speakers. References to channels that are not present in the source or destination will simply be ignored.

Here's an example of how you might implement a simple downmix function that maps the center channel in a 3.0-channel source sample to the front-left and front-right speakers in a stereo output configuration:


  MSS_SPEAKER downmix_source_list[] = { MSS_SPEAKER_FRONT_CENTER, MSS_SPEAKER_FRONT_CENTER };
  MSS_SPEAKER downmix_dest_list[] =   { MSS_SPEAKER_FRONT_LEFT,   MSS_SPEAKER_FRONT_RIGHT  };
  F32         downmix_level_list[] =  { 0.5F,                     0.5F                     };
  AIL_set_sample_channel_levels(S,
                                downmix_source_list,
                                downmix_dest_list,
                                downmix_level_list,
                                2);

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 Xbox 1 and the MSS_MC_DIRECTSOUND3D and MSS_MC_EAX? values from the MSS_MC_SPEC list.

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.

Most applications won't need to set channel levels explicitly. To handle mono samples in a multichannel environment, it's often best to let Miles' built-in 3D positioning code do the work for you! (If an HSAMPLE has been assigned a 3D position with AIL_set_sample_3D_position, any values the application writes to the channel-level array will be multiplied with the results of the 3D-positioning calculations.)

This function is not recommended for use with stereo samples. Standard stereo samples cannot be cross-routed (left-to-right and vice versa) with this function, since stereo source data has its own dedicated mixer path. Multichannel samples, however, can be routed arbitrarily, since they're processed internally as a stack of discrete mono samples.

Group: Digital Audio Services
Related Functions: AIL_calculate_3D_channel_levels, AIL_open_stream, AIL_sample_51_volume_levels, AIL_sample_51_volume_pan, AIL_sample_channel_levels, AIL_sample_output_levels, AIL_set_sample_3D_position, AIL_set_sample_51_volume_levels, AIL_set_sample_51_volume_pan
Related Basic Types: F32, HSAMPLE, MSS_MC_SPEC, MSS_SPEAKER, S32, void
Related FAQs: How do I use multi-channel sound output in Miles?