mServe Documentation
mServe Filters
mServe Filters
The mServe Filters API is planned for mServe 0.2 and currently in the design
stage.
Contents
- Basics
- API for Decoders
- API for Filter Chain Modifiers
- API for Filter Plug-ins
The basic structure is the filter_chain, which is a linked list. Each filter in
the list does its stuff (optionally using a buffer), and then calls the next
filter in the chain. The last link in the chain is always the output plugin (or,
rather an adapter that buffers the data for output by the output thread).
void filter_push_data(decode_ctx *, const void *data, uint length);
void filter_set_format(decode_ctx *, int freq, SampleFormat fmt, int channels);
The decoder should call filter_set_format and filter_push_data to send data
to the output thread. The data traverses the chain and ends up in a buffer
for playback by the output thread. set_format should have been called before
calling push_data (There is no default format).
void filter_lock();
void filter_unlock();
All filter chain modifying functions should (must) call filter_lock before
altering the filter chains, and filter_unlock when done with them.
filter_info *get_filter_info(const char *name);
filter_chain *filter_chain_create(filter_info *, const char *arg);
To add a filter into the chain, first you must retrieve the filter_info
pointer for the filter. Then, you must create a filter_chain structure
for insertion into the chain.
void filter_chain_insert_after(filter_chain *old, filter_chain *new_chain);
void filter_chain_insert_before(filter_chain *old, filter_chain *new_chain);
filter_chain *filter_chain_get_first();
filter_chain *filter_chain_get_last();
When the filter chain has been created, call an insert function to insert
it into the chain. To insert a chain at the end or beginning of the chain,
either take the return from get_first/last and give it to insert_*, or pass
a NULL argument. To insert the chain at any other position, traverse the chain
returned from get_first/last and call insert when you have found the one you
want.
void filter_chain_remove(filter_chain *);
void filter_chain_destroy(filter_chain *);
Call remove to remove the reference to the chain link from the chain. All its
resources will remain, so that the filter_chain can be inserted at another
location in the chain.
Call destroy to free all associated resources and the filter_chain. The pointer
is no longer valid. The filter's deinit function is called for the filter_chain.
The plugin file is a .so file, with one symbol exported:
extern filter_info *filter_get_info();
The function should return a filled filter_info structure for the plugin. The
name field of the filter_info must correspond to the filename of the plugin.
|