Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# dc_elimination.h

struct dcoe_chan_state_t

  DC Offset Elimination (DCOE) State.

  This is the required state information for a single channel to which the DC offset elimination filter is to be applied.

  To apply the DC offset elimination filter to multiple channels simultaneously, an array of `dcoe_chan_state_t` should be used.

  `dcoe_state_init()` is used once to initialize an array of state objects, and `dcoe_filter()` is used on each consecutive sample to apply the filter and get the resulting output sample.

  DC offset elimination is an IIR filter. The state must persist between time steps.

  Use in lib_mic_array

    Typical users of lib_mic_array will not need to directly use this type or any functions which take it as a parameter.

    The C++ class template `mic_array::DcoeSampleFilter`, if used in an application’s mic array unit, will allocate, initialize and apply the DCOE filter automatically.

  With MicArray Prefabs

    The MicArray prefab `mic_array::prefab::BasicMicArray` has a `bool` template parameter `USE_DCOE` which indicates whether the `mic_array::DcoeSampleFilter` should be used. If `true`, DCOE will be enabled.

  With Vanilla API

    When using the ‘vanilla’ API, DCOE is enabled by default. To disable DCOE when using this API, add a preprocessor definition to the compiler flags, setting `MIC_ARRAY_CONFIG_USE_DC_ELIMINATION` to `0`.

  Public Members

  int64_t prev_y

    Previous output sample value.

void dcoe_state_init(dcoe_chan_state_t state[], const unsigned chan_count)

  Initialize DCOE states.

  The DC offset elimination state needs to be intialized before the filter can be applied. This function initializes it.

  For correct behavior, the state vector `state` must persist between audio samples and is supplied with each call to `dcoe_filter()`.

  Parameters:

    - state – [in] Array of `dcoe_chan_state_t` to be initialized.

    - chan_count – [in] Number of elements in `state`.

void dcoe_filter(int32_t new_output[], dcoe_chan_state_t state[], int32_t new_input[], const unsigned chan_count)

  Apply DCOE filter.

  Applies the DC offset elimination filter to get a new output sample and updates the filter state.

  For correct behavior, this function should be called once per sample (here “sample” refers to a vector-valued quantity containing one element for each audio channel) of that stream.

  The index of each array (`state`, `new_input` and `new_output`) corresponds to the audio channel. The update associated with each audio channel is independent of each other audio channel.

  The equation used for each channel is:

      y[t] = R * y[t-1] + x[t] - x[t-1]

  where `t` is the current sample time index, `y[]` is the output signal, `x[]` is the input signal, and `R` is `(252.0/256)`.

  To filter a sample in-place use the same array for both the `new_input` and `new_output` arguments.

  Parameters:

    - new_output – [out] Array into which the output sample will be placed.

    - state – [in] DC offset elimination state vector.

    - new_input – [in] New input sample.

    - chan_count – [in] Number of channels to be processed.