Here is the new version of the header file, based on your feedback.
The main changes are:
- The create_filter() function now receives the channel maps for input
and output.
- The create_filter() function receives a kill_filter() function and a
module pointer
which makes it possible for the filter to initiate unloading of the
module if it
detects that it is no longer applicable.
- An output_changed() function was added which communicates current sink
and port name to the filter, so that it can detect if the output has
changed.
Also I did a bit of cleanup and added a few more comments. Hope it looks
better now.
Regards
Georg
/***
This file is part of PulseAudio.
PulseAudio is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License,
or (at your option) any later version.
PulseAudio is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
***/
/* Channel positions copied from pulseaudio channelmap.h */
enum channel_position {
CHANNEL_POSITION_INVALID = -1,
CHANNEL_POSITION_MONO = 0,
CHANNEL_POSITION_FRONT_LEFT, /**< Apple, Dolby call this 'Left' */
CHANNEL_POSITION_FRONT_RIGHT, /**< Apple, Dolby call this 'Right' */
CHANNEL_POSITION_FRONT_CENTER, /**< Apple, Dolby call this 'Center' */
CHANNEL_POSITION_LEFT = CHANNEL_POSITION_FRONT_LEFT,
CHANNEL_POSITION_RIGHT = CHANNEL_POSITION_FRONT_RIGHT,
CHANNEL_POSITION_CENTER = CHANNEL_POSITION_FRONT_CENTER,
CHANNEL_POSITION_REAR_CENTER, /**< Microsoft calls this 'Back Center', Apple calls this 'Center Surround', Dolby calls this 'Surround Rear Center' */
CHANNEL_POSITION_REAR_LEFT, /**< Microsoft calls this 'Back Left', Apple calls this 'Left Surround' (!), Dolby calls this 'Surround Rear Left' */
CHANNEL_POSITION_REAR_RIGHT, /**< Microsoft calls this 'Back Right', Apple calls this 'Right Surround' (!), Dolby calls this 'Surround Rear Right' */
CHANNEL_POSITION_LFE, /**< Microsoft calls this 'Low Frequency', Apple calls this 'LFEScreen' */
CHANNEL_POSITION_SUBWOOFER = CHANNEL_POSITION_LFE,
CHANNEL_POSITION_FRONT_LEFT_OF_CENTER, /**< Apple, Dolby call this 'Left Center' */
CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER, /**< Apple, Dolby call this 'Right Center */
CHANNEL_POSITION_SIDE_LEFT, /**< Apple calls this 'Left Surround Direct', Dolby calls this 'Surround Left' (!) */
CHANNEL_POSITION_SIDE_RIGHT, /**< Apple calls this 'Right Surround Direct', Dolby calls this 'Surround Right' (!) */
CHANNEL_POSITION_AUX0,
CHANNEL_POSITION_AUX1,
CHANNEL_POSITION_AUX2,
CHANNEL_POSITION_AUX3,
CHANNEL_POSITION_AUX4,
CHANNEL_POSITION_AUX5,
CHANNEL_POSITION_AUX6,
CHANNEL_POSITION_AUX7,
CHANNEL_POSITION_AUX8,
CHANNEL_POSITION_AUX9,
CHANNEL_POSITION_AUX10,
CHANNEL_POSITION_AUX11,
CHANNEL_POSITION_AUX12,
CHANNEL_POSITION_AUX13,
CHANNEL_POSITION_AUX14,
CHANNEL_POSITION_AUX15,
CHANNEL_POSITION_AUX16,
CHANNEL_POSITION_AUX17,
CHANNEL_POSITION_AUX18,
CHANNEL_POSITION_AUX19,
CHANNEL_POSITION_AUX20,
CHANNEL_POSITION_AUX21,
CHANNEL_POSITION_AUX22,
CHANNEL_POSITION_AUX23,
CHANNEL_POSITION_AUX24,
CHANNEL_POSITION_AUX25,
CHANNEL_POSITION_AUX26,
CHANNEL_POSITION_AUX27,
CHANNEL_POSITION_AUX28,
CHANNEL_POSITION_AUX29,
CHANNEL_POSITION_AUX30,
CHANNEL_POSITION_AUX31,
CHANNEL_POSITION_TOP_CENTER, /**< Apple calls this 'Top Center Surround' */
CHANNEL_POSITION_TOP_FRONT_LEFT, /**< Apple calls this 'Vertical Height Left' */
CHANNEL_POSITION_TOP_FRONT_RIGHT, /**< Apple calls this 'Vertical Height Right' */
CHANNEL_POSITION_TOP_FRONT_CENTER, /**< Apple calls this 'Vertical Height Center' */
CHANNEL_POSITION_TOP_REAR_LEFT, /**< Microsoft and Apple call this 'Top Back Left' */
CHANNEL_POSITION_TOP_REAR_RIGHT, /**< Microsoft and Apple call this 'Top Back Right' */
CHANNEL_POSITION_TOP_REAR_CENTER, /**< Microsoft and Apple call this 'Top Back Center' */
CHANNEL_POSITION_MAX
};
/* Function called when the filter detects a condition to unload the filter. */
typedef void (*Kill_Filter_Function)(void *module);
/* Filter plugin structure */
typedef struct filter_plugin {
const char *name; /* Name of the filter. Used to identify the filter. */
const char *desc_head; /* Leading part of description string used for the
* sink and sink input description in PA. */
const char *filter_type; /* Name for the type of filter, used as suffix for
* the sink name if the name is derived from the
* master sink. */
unsigned input_channels; /* Number of audio input channels, 0 if variable */
unsigned output_channels; /* Number of audio output channels, 0 if variable */
size_t max_chunk_size; /* Maximum chunk size in bytes that the filter will
* accept, 0 for default */
size_t fixed_block_size; /* Block size in frames for fixed block size filters,
* 0 if block size is variable */
uint64_t max_latency; /* Maximum latency allowed for the sink, 0 if unused */
bool disable_rewind; /* True when rewinding is disabled */
/* Functions defined by the filter */
/* Initializes a new filter instance and returns a handle to it. Passes the number of
* input and output channels, the corresponding channel positions and the sample rate
* to the filter. kill_filter can be called by the filter if it detects a condition
* that makes it necessary to remove the filter. kill_filter must be called with
* the module pointer as argument. */
void *(*create_filter)(unsigned input_channels, int *input_map,
unsigned output_channels, int *output_map,
Kill_Filter_Function kill_filter, void *module, unsigned sample_rate);
/* Deletes filter instance. */
void (*delete_filter)(void *filter_handle);
/* Activates filter. Returns 0 on success and a negative errror code on failure.
* May be NULL. */
int (*activate_filter)(void *filter_handle);
/* Deactivates filter. May be NULL. */
void (*deactivate_filter)(void *filter_handle);
/* Callback to process a chunk of data by the filter. May be NULL */
void (*process_chunk)(float *src, float *dst, unsigned count, void *filter_handle);
/* Callback to retrieve additional latency caused by the filter. May be NULL */
uint64_t (*get_extra_latency)(void *filter_handle);
/* Callback to rewind the filter when pulseaudio requests it. May be NULL.
* Amount indicates the number of bytes to roll back. The filter state must
* not be reset, but seamlessly restored to the specified point in the past
* (which is the filter's responsibility to keep).
* If it is not possible to do so, the best option is to disable rewinding
* completely and limit the latency. */
void (*rewind_filter)(size_t amount, void *filter_handle);
/* If not NULL, this function is called whenever the active port of a sink or
* the sink itself changes. It is used to communicate the currently active port
* and sink to the filter. */
void (*output_changed)(const char *sink_name, const char *port_name, void *filter_handle);
/* If set, this function is called in thread context when an update of the
* filter parameters is requested, may be NULL. The function must replace
* the currently used parameter structure by the new structure and return
* a pointer to the old structure so that it can be freed in the main thread
* using parameter_free(). If the old structure can be re-used, the function
* may return NULL. */
void *(*update_filter_parameters)(void *parameters, void *filter_handle);
/* Frees a parameter structure. May only be NULL, if update_filter_parameters()
* is also NULL or if update_filter_parameters() always returns NULL. */
void (*parameter_free)(void *parameters);
/* The following functions can be provided to set and get parameters. The parameter
* structure is defined by the filter and should contain all parameters that are
* configurable by the user. The host code makes no assumption on the contents
* of the structure but only passes references. The host implements a message
* handler which supports the following messages that use the functions below:
* parameter-get - Retrieve a single parameter.
* parameter-set - Set a single parameter.
* parameter-get-all - Retrieve all parameters as a list in message format.
* parameter-set-all - Set all parameters simultaneously.
* parameter-get-description - Returns a filter description and a list that describes
* all parameters. Example of the list element format:
* {{Identifier}{Type}{default}{min}{max}}
* The last message can be used to get information about the filter or to implement
* a filter control GUI that is independent of the filter type.
* If filter_message_handler() is defined, all other messages are passed on to the
* filter. The get functions are expected to return a string in the message handler
* format while the set functions receive plain strings. On failure, all get/set
* functions will return NULL. */
/* Get the value of the parameter described by identifier. The value shall be returned
* as a string enclosed in double curly braces. The identifier may be any string that
* the filter recognizes like a name or index, depending on the implementation of this
* function. */
char *(*parameter_get)(const char *identifier, void *filter_handle);
/* Sets the value of the parameter described by identifier. The value is expected as
* a string. The identifier may be any string that the filter recognizes like a name
* or index. Returns a parameter structure filled with all current parameter values,
* reflecting the updated parameter, so that the structure can be passed to
* update_filter_parameters(). update_filter_parameters() will replace the current
* parameter set with the new structure. */
void *(*parameter_set)(const char *identifier, const char *value, void *filter_handle);
/* Returns a list of the values of all filter parameters. Each parameter must be enclosed
* in curly braces and there must be braces around the whole list. */
char *(*parameter_get_all)(void *filter_handle);
/* Expects an array of all filter parameter values as strings and returns a parameter
* structure that can be passed to update_filter_parameters(). See set_parameter().
* If all_params is NULL, the function should return a default set of parameters. */
void *(*parameter_set_all)(const char **all_params, int param_count, void *filter_handle);
/* Returns a parameter description string as described above. */
char *(*parameter_get_description)(void *filter_handle);
/* Handler for additional messages. */
int (*filter_message_handler)(const char *message, char *message_parameters, char **response, void *filter_handle);
} filter_plugin;
/* Datatype corresponding to the get_Filter_Info() function. */
typedef const struct filter_plugin *(*Filter_Info_Function)(unsigned long Index);
_______________________________________________
pulseaudio-discuss mailing list
pulseaudio-discuss@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss
