Creating Pass Filter Plugins

Kst provides header files to simplify the implementation of pass filter plugins. The use of these header files is described below.

Header Files

The pass filter header file is located in kst/plugins/pass_filters of the Kst source tarball. The file is named filters.h To use this file, include it in the source code for your plugin:

#include <../filters.h>

(by convention, we will place the source code for the plugin one directory below where the header files are).

Required Functions

The filters.h header file contains a single function that calculates the Fourier transform of a supplied function, applies the supplied filter to the Fourier transform, and then calculates the inverse Fourier transform of the filtered Fourier transform. To supply the filter, the following function needs to be implemented in the source code for your plugin:

double filter_calculate( double dFreqValue, const double inScalars[] )

This function should calculate the filtered amplitude for the frequency dFreqValue. inScalars[] will contain the unaltered input scalars for the plugin, specified in the XML file. Most likely inScalars[] will contain cutoff frequencies or other properties of the filter. For example, to implement a Butterworth high-pass filter, filter_calculate could be implemented as follows:

double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;
  if( dFreqValue > 0.0 ) {
    dValue = 1.0 / ( 1.0 +
    		pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }
  return dValue;
}

Calling the Filter Function

Once the required filter_calculate has been implemented, the filter function from the header file can be called:

kst_pass_filter( inArrays, inArrayLens, inScalars, outArrays, outArrayLens, outScalars );

The arguments supplied to the exported C function can usually be passed to kst_pass_filter without modification. However, there are a few restrictions on the arguments:

inArrays[0] must contain the array of data to filter.
inScalars should contain the filter-specific parameters to be used by the filter_calculate function.

After the function call, outArrays[0] will contain the filtered array of data, and outArrayLens will be set appropriately. The kst_pass_filter function does not use outScalars.

Example

The following is an example of a pass filter plugin that implements the Butterworth high-pass filter.

/*
 *  Butterworth low pass filter plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the GPL.
 */

#include <stdlib.h>
#include <math.h>
#include "../filters.h"

extern "C" int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
		const double inScalars[],
		double *outArrays[], int outArrayLens[],
		double outScalars[]);

int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
		const double inScalars[],
		double *outArrays[], int outArrayLens[],
		double outScalars[])
{
  int iReturn;

  iReturn = kst_pass_filter( inArrays,
                             inArrayLens,
                             inScalars,
                             outArrays,
                             outArrayLens,
                             outScalars );

  return iReturn;
}

double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;

  if( dFreqValue > 0.0 ) {
    dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }

  return dValue;
}