BASS.NET API for the Un4seen BASS Audio LibraryBassMixBASS_Mixer_ChannelSetMatrix Method BASS.NET API for the Un4seen BASS Audio Library
Sets a channel's mixing matrix, if it has one.

Namespace: Un4seen.Bass.AddOn.Mix
Assembly: Bass.Net (in Bass.Net.dll) Version: 2.4.12.0
Syntax

[DllImportAttribute("bassmix.dll", CharSet = CharSet.Unicode)]
public static bool BASS_Mixer_ChannelSetMatrix(
	int handle,
	float[,] matrix
)

Parameters

handle
Type: SystemInt32
The mixer source channel handle (which was add via BASS_Mixer_StreamAddChannel(Int32, Int32, BASSFlag) or BASS_Mixer_StreamAddChannelEx(Int32, Int32, BASSFlag, Int64, Int64)) beforehand).
matrix
Type: SystemSingle
The 2-dimensional array (float[,]) of the mixing matrix.

Return Value

Type: Boolean
If successful, a is returned, else is returned. Use BASS_ErrorGetCode to get the error code.
Remarks

Normally when mixing channels, the source channels are sent to the output in the same order - the left input is sent to the left output, and so on. Sometimes something a bit more complex than that is required. For example, if the source has more channels than the output, you may want to "downmix" the source so that all channels are present in the output. Equally, if the source has fewer channels than the output, you may want to "upmix" it so that all output channels have sound. Or you may just want to rearrange the channels. Matrix mixing allows all of these.

A matrix mixer is created on a per-source basis (you can mix'n'match normal and matrix mixing), by using the BASS_MIXER_MATRIX and/or BASS_MIXER_DOWNMIX flag when calling BASS_Mixer_StreamAddChannel(Int32, Int32, BASSFlag) or BASS_Mixer_StreamAddChannelEx(Int32, Int32, BASSFlag, Int64, Int64). The matrix itself is a 2-dimensional array of floating-point mixing levels, with the source channels on one axis, and the output channels on the other. Some simple examples are shown below.

The Matrix layout:

HorizontalThe Input channels (e.g. 1,0 = left-on,right-off).
VerticalThe Output channels (e.g. 1,0 = left-on,right-off).
       ---------> (Input)           ---------> (Input)
      |    L  R                    |    L  R
      | L  1  0                    |LF  1  0
      | R  0  1                    |RF  0  1
      v                            |LR  1  0
(Output)                           |RR  0  1
                                   v
                              (Output)

When streaming multi-channel sample data, the channel order of each sample is as follows:

3 channelsleft-front, right-front, center.
4 channelsleft-front, right-front, left-rear/side, right-rear/side.
6 channels(5.1)left-front, right-front, center, LFE, left-rear/side, right-rear/side.
8 channels(7.1)left-front, right-front, center, LFE, left-rear/side, right-rear/side, left-rear center, right-rear center.

When using matrix mixing, the source channel's volume attribute still has effect, but the pan attribute doesn't. Whenever necessary, panning changes can be achieved by modifying the matrix.

Do NOT use .Net jagged arrays, but only two-dimensional C-style arrays - as shown in the examples below!

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not plugged into a mixer.
BASS_ERROR_NOTAVAILThe channel is not using matrix mixing.

Examples

The following example shows how to use Matrix mixing (stereo to quad matrix):
VB
' the source stream
Dim streamA As Integer = Bass.BASS_StreamCreateFile(_fileName, 0, 0, BASSFlag.BASS_STREAM_DECODE)
' create a 4-channel mixer stream
Dim i As BASS_CHANNELINFO = Bass.BASS_ChannelGetInfo(streamA)
Dim mixer As Integer = BassMix.BASS_Mixer_StreamCreate(i.freq, 4, BASSFlag.BASS_DEFAULT)
' add the source stream to the mixer with the matrix option
BassMix.BASS_Mixer_StreamAddChannel(mixer, streamA, BASSFlag.BASS_MIXER_MATRIX)
' define a mixing matrix for the source stream
Dim matrix(,) As Single = { ' stereo to quad matrix
                    {1, 0}, ' left in = left front out
                    {0, 1}, ' right in = right front out
                    {1, 0}, ' left in = left rear out
                    {0, 1}  ' right in = right rear out
                   }
BassMix.BASS_Mixer_ChannelSetMatrix(streamA, matrix)
' and play it
Bass.BASS_ChannelPlay(mixer, False)
// the source stream
int streamA = Bass.BASS_StreamCreateFile(_fileName, 0, 0, BASSFlag.BASS_STREAM_DECODE);
// create a 4-channel mixer stream
BASS_CHANNELINFO i = Bass.BASS_ChannelGetInfo(streamA);
int mixer = BassMix.BASS_Mixer_StreamCreate(i.freq, 4, BASSFlag.BASS_DEFAULT );
// add the source stream to the mixer with the matrix option
BassMix.BASS_Mixer_StreamAddChannel(mixer, streamA, BASSFlag.BASS_MIXER_MATRIX);
// define a mixing matrix for the source stream
float[,] matrix = { // stereo to quad matrix
            {1, 0}, // left in = left front out
            {0, 1}, // right in = right front out
            {1, 0}, // left in = left rear out
            {0, 1}  // right in = right rear out
           };
// apply the matrix
BassMix.BASS_Mixer_ChannelSetMatrix(streamA, matrix);
// and play it
Bass.BASS_ChannelPlay(mixer, false);
Here are some more matrix examples...
// In = stereo, Out = stereo
float[,] matrix = { 
                {1, 0}, // left out = left in
                {0, 1}, // right out = right in
        };

// In = stereo, Out = swapped stereo
float[,] matrix = { 
                {0, 1}, // left out = right in
                {1, 0}, // right out = left in
        };

// In = stereo, Out = mono
float[,] matrix = { 
                {0.5f, 0.5f} // mono out = half left + right in
        };

// In = stereo, Out = quadraphonic (4 channels)
float[,] matrix = { // stereo to quad matrix
                        {1, 0}, // left-front out = left in
                        {0, 1}, // right-front out = right in
                        {1, 0}, // left rear out = left in
                        {0, 1}  // right rear out = right in
        };

// In = mono, Out = quadraphonic (4 channels)
float[,] matrix = { // mono to quad matrix
                         {1}, // left-front out = mono in
                           {1}, // right-front out = mono in
                           {1}, // left rear out = mono in
                           {1}  // right rear out = mono in
        };
See Also

Reference