USBD_Audio_MU_MixingCtrlSet

Description

Set one programmable mixing control.

Files

usbd_audio.h / usbd_audio.c

Prototype

void  USBD_Audio_MU_MixingCtrlSet (CPU_INT08U   class_nbr,
                                   CPU_INT08U   mu_id,
                                   CPU_INT08U   log_in_ch_nbr,
                                   CPU_INT08U   log_out_ch_nbr,
                                   USBD_ERR    *p_err);

Arguments

class_nbr

Class instance number.

mu_id

Mixer Unit ID.

log_in_ch_nbr

Logical input channel number.

log_out_ch_nbr

Logical output channel number.

p_err

Pointer to variable that will receive the return error code from this function.

USBD_ERR_NONE

USBD_ERR_CLASS_INVALID_NBR 

USBD_ERR_NULL_PTR

Returned Value

None.

Callers

Application.

Notes / Warnings

The Mixer Unit descriptor has a field called bmControls. The field  bmControls is interpreted by the host as a two-dimensional bit array representing a bitmap of which Mixer Unit controls are programmable or not. Called several times. the function USBD_Audio_MU_MixingCtrlSet() allows to set the programmable mixing controls within the bitmap. There are two different situations:

1. Mixer Unit has only non-programmable controls. 
2. Mixer Unit has non-programmable and programmable controls.

In the situation #1, the function USBD_Audio_MU_MixingCtrlSet() is not necessary. In the situation #2, the function is required for each programmable mixing control. To fully understand how to use the function, the way the Mixer Unit Descriptor reports its programmable controls in bmControls must be understood.

A Mixer Unit with 2 stereo Input pins and 1 stereo Output pin is considered. In Figure - Mixer Unit Example, u refers to logical input channels and v to logical output channel.

The following excerpt from section "4.3.2.3 Mixer Unit Descriptor" of audio 1.0 specification explains how the programmable controls are reported in  bmControls:

"This bitmap must be interpreted as a two-dimensional bit array that has a row for each logical input channel and a column for each logical output channel. If a bit at position [u, v] is set, this means that the Mixer Unit contains a programmable mixing Control that connects input channel u to output channel v. If bit [u, v] is clear, this indicates that the connection between input channel u and output channel v is non-programmable. Its fixed value can be retrieved through the appropriate request. The valid range for u is from one to n. The valid range for v is from one to m. The bmControls field stores the bit array row after row where the MSb of the first byte corresponds to the connection between input channel 1 and output channel 1. If (n x m) is not an integer multiple of 8, the bit array is padded with zeros until an integer number of bytes is occupied."

n represents the number of logical input channels and m the number of logical output channels. 

Listing - Mixer Unit with Non-Programmable and Programmable Controls shows the situation #2 where Mixer Unit has non-programmable and programmable controls. We consider that left logical input channels can be mixed in left logical output channel and right logical input channels can be mixed in right logical output channel. Table - Representation of Mixer Unit Programmable Controls gives a representation of the programmable controls for our example:

As stated by the excerpt, the 2D bit array is stored row after row. Table - Representation of Mixer Unit Programmable Controls would produce the following bmControls field:

In this example, bmControls has a size of 1 byte requiring no zeros padding.

The resulting USBD_Audio_MU_MixingCtrlSet() calling sequence would be (for clarity, the error handling is not shown in this code snippet):

USBD_ERR    err;
CPU_INT08U  audio_nbr;

audio_nbr = USBD_Audio_Add(APP_CFG_USBD_AUDIO_NBR_ENTITY,
                          &USBD_Audio_DrvCommonAPI_Template,
                           DEF_NULL,
                          &err);

MU11_ID = USBD_Audio_MU_Add(audio_nbr,
                           &USBD_MU11_Cfg,
                           &USBD_Audio_DrvMU_API_Template,
                           &err);

USBD_Audio_MU_MixingCtrlSet(audio_nbr, MU11_ID, 1u, 1u, &err);
USBD_Audio_MU_MixingCtrlSet(audio_nbr, MU11_ID, 2u, 2u, &err);
USBD_Audio_MU_MixingCtrlSet(audio_nbr, MU11_ID, 3u, 1u, &err);
USBD_Audio_MU_MixingCtrlSet(audio_nbr, MU11_ID, 4u, 2u, &err);