# DSP Filtering

## Functions
DLLEXPORT TECELLA_ERRNUM CALL | tecella_sw_filter_enable (TECELLA_HNDL h, bool enable, int channel=TECELLA_ALLCHAN)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_sw_filter_auto_downsample (TECELLA_HNDL h, bool enable, int channel=TECELLA_ALLCHAN)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_sw_filter_set (TECELLA_HNDL h, double *kernel, int kernel_size, int channel=TECELLA_ALLCHAN)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_sw_filter_set_box (TECELLA_HNDL h, int width, int channel=TECELLA_ALLCHAN)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_sw_filter_set_lanczos (TECELLA_HNDL h, double width, int quality=3, int channel=TECELLA_ALLCHAN)

## Detailed Description

TecellaAmp provides convenience functions for various downsampling filters and user-defined FIR filters.

## Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_sw_filter_auto_downsample | ( | TECELLA_HNDL | h,
|  | bool | enable,
|  | int | channel = `TECELLA_ALLCHAN` |
| ) |  |  |

Enables/Disables auto downsampling using a box filter. Comes into play when the sample_period_multiplier in tecella_acquire_start is not 1. The box filter is used in conjunction with the user defined filter.

Parameters:

  | h | A handle to an initialized device.
  | enable | If true, filtering is enabled. If false, filtering is disabled.
  | channel | The channel on which to enable/disable filtering.

DLLEXPORT TECELLA_ERRNUM CALL tecella_sw_filter_enable | ( | TECELLA_HNDL | h,
|  | bool | enable,
|  | int | channel = `TECELLA_ALLCHAN` |
| ) |  |  |

Enables/Disables filtering.

Parameters:

  | h | A handle to an initialized device.
  | enable | If true, filtering is enabled. If false, filtering is disabled.
  | channel | The channel on which to enable/disable filtering.

DLLEXPORT TECELLA_ERRNUM CALL tecella_sw_filter_set | ( | TECELLA_HNDL | h,
|  | double * | kernel,
|  | int | kernel_size,
|  | int | channel = `TECELLA_ALLCHAN` |
| ) |  |  |

Sets a kernel to be convolved with incoming samples at the native sampling frequency. Note: The kernel will be normalized before it is stored in the API to prevent unwanted scaling.

Parameters:

  | h | A handle to an initialized device.
  | kernel | An array of doubles that define the kernel.
  | kernel_size | The number of elements in the kernel array.
  | channel | Applies the filter to this channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_sw_filter_set_box | ( | TECELLA_HNDL | h,
|  | int | width,
|  | int | channel = `TECELLA_ALLCHAN` |
| ) |  |  |

Sets a simple nearest-neighbor averaging filter. This acts as a low pass filter that doesn't have much ringing, but will not preserve peaks as well as a Lanczos filter.

Parameters:

  | h | A handle to an initialized device.
  | width | The number of samples to average together.
  | channel | Applies the filter to this channel.

DLLEXPORT TECELLA_ERRNUM CALL tecella_sw_filter_set_lanczos | ( | TECELLA_HNDL | h,
|  | double | width,
|  | int | quality = `3`,
|  | int | channel = `TECELLA_ALLCHAN` |
| ) |  |  |

Sets a Lanczos filter kernel, which approximates the ideal low pass filter. It preserves peaks well, however it may result in ringing near sharp edges. For an explanation of Lanczos filters, see: http://en.wikipedia.org/wiki/Lanczos_resampling

Parameters:

  | h | A handle to an initialized device.
  | width | 1/width is the effective cutoff frequency of the Lanczos filter. If downsampling, set width equal to the number of samples being decimated. Using a width that is not a whole number will prevent the zeroes from falling exactly on a sample.
  | quality | Must be 1 or greater. There are deminishing returns after 3. Corresponds to the "a" coefficient usually used in texts when describing a Lanczos filter.
  | channel | Applies the filter to this channel. Note: The final size of the Lanczos filter will be width*quality.