PM123 Filter Plugins

Filter plugins must implement and export the functions defined in filter_plug.h. The interface has changed with plugin level 2. Although they look very similar they are completely different.

Interface level 3 (current)

     ULONG DLLENTRY filter_init(void** f, FILTER_PARAMS2* params)

• f - Allocate any chunk of memory necessary for the filter's function. This pointer will be passed to the any other function call into the filter plugin.
• Make a copy of all fields in the FILTER_PARAMS2 structure that you need later or copy the entire structure.
• Replace the entry points in the FILTER_PARAMS2 structure that you want to virtualize. Keep in mind that implementing a no-op will at least require to replace the first parameter a to each function by params->f. If yo do not change a individual function pointer the plugin manager will do this job for you.
• return value - 0 means the filter was initialized successfully. Any other value indicates an error and filter_uninit will not be called in this case.

A level 3 filter plugin may completely virtualize the output of data. It may change the sampling rate, it may change the number of bytes per samples or even the time axis. See the output plugin interface description for detailed information on the different functions.

     void DLLENTRY filter_update(void* f, const FILTER_PARAMS2* params)

This function is called to update the procedure entry points and the callback pointers that you received at the filter_init call. This will be used to load and/or unload filters at runtime by future versions of PM123. Be sure that the replacement of the entry points is an atomic operation.

     BOOL DLLENTRY filter_uninit(void* f)

Uninitialize the plugin, free any storage related to f and return TRUE unless you are in real big trouble.

Interface level 1 (supported by proxy)

     ULONG DLLENTRY filter_init  (void** f, FILTER_PARAMS* params)
     BOOL  DLLENTRY filter_uninit(void*  f)

• f - Allocate any chunk of memory necessary for the filter's function. This pointer will be passed to the other filter_play_samples. At the very least, you need to allocate memory to keep the in memory the location of output_play_samples and it's parameter f.
• return value - 0 means the filter was initialized successfully.

The filter_init function is called when filter plugin is about to be used. Multiple filter plugins are chained, so the pointers to output_play_samples and it's parameter f, might belong to another filter plugin and not necessarily to the active output plugin.

     int DLLENTRY filter_play_samples(void* f, FORMAT_INFO* format, char* buf,
                                      int len, int posmarker)

• format - format of buf.
• buf - data to play.
• len - length of buf in bytes.
• posmarker - position marker to return with output_playing_pos.
• return value - the number of bytes from len processed. ie.: 0 == error.

This function is called by the decoder or a previous in chain filter plugin to filter samples. Note that this function's prototype is identical to output_play_samples. This makes it possible to chain filter plugins.

Once you have modified the data in satisfactory way, call the output_play_samples function with it's parameter f received from the init function, and use it with the modified samples of your filter plugin.