Creating Pass Filter Plugins

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).

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;
}

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

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:

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.

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;
}