mediastreamer2 5.2.0
|
Filter API to manage mediastreamer2 filters. More...
Data Structures | |
struct | _MSFilterMethod |
struct | _MSFilterStats |
struct | _MSFilterDesc |
struct | _MSFilter |
struct | _MSConnectionPoint |
struct | _MSConnectionHelper |
struct | _MSPinFormat |
Macros | |
#define | MS_FILTER_METHOD_ID(_id_, _cnt_, _argsize_) (unsigned int)(((((unsigned int)(_id_)) & 0xFFFF)<<16) | (((unsigned int)(_cnt_))<<8) | (((unsigned int)_argsize_) & 0xFF)) |
#define | MS_FILTER_METHOD(_id_, _count_, _argtype_) MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_)) |
#define | MS_FILTER_METHOD_NO_ARG(_id_, _count_) MS_FILTER_METHOD_ID(_id_,_count_,0) |
#define | MS_FILTER_BASE_METHOD(_count_, _argtype_) MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,sizeof(_argtype_)) |
#define | MS_FILTER_BASE_METHOD_NO_ARG(_count_) MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,0) |
#define | MS_FILTER_EVENT(_id_, _count_, _argtype_) MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_)) |
#define | MS_FILTER_EVENT_NO_ARG(_id_, _count_) MS_FILTER_METHOD_ID(_id_,_count_,0) |
#define | MS_FILTER_BASE_EVENT(_count_, _argtype_) MS_FILTER_EVENT(MS_FILTER_BASE_ID,_count_,_argtype_) |
#define | MS_FILTER_BASE_EVENT_NO_ARG(_count_) MS_FILTER_EVENT_NO_ARG(MS_FILTER_BASE_ID,_count_) |
#define | MS_FILTER_SET_SAMPLE_RATE MS_FILTER_BASE_METHOD(0,int) |
#define | MS_FILTER_GET_SAMPLE_RATE MS_FILTER_BASE_METHOD(1,int) |
#define | MS_FILTER_SET_BITRATE MS_FILTER_BASE_METHOD(2,int) |
#define | MS_FILTER_GET_BITRATE MS_FILTER_BASE_METHOD(3,int) |
#define | MS_FILTER_GET_NCHANNELS MS_FILTER_BASE_METHOD(5,int) |
#define | MS_FILTER_SET_NCHANNELS MS_FILTER_BASE_METHOD(6,int) |
#define | MS_FILTER_ADD_FMTP MS_FILTER_BASE_METHOD(7,const char) |
#define | MS_FILTER_ADD_ATTR MS_FILTER_BASE_METHOD(8,const char) |
#define | MS_FILTER_SET_MTU MS_FILTER_BASE_METHOD(9,int) |
#define | MS_FILTER_GET_MTU MS_FILTER_BASE_METHOD(10,int) |
#define | MS_FILTER_GET_LATENCY MS_FILTER_BASE_METHOD(11,int) |
#define | MS_FILTER_GET_INPUT_FMT MS_FILTER_BASE_METHOD(30,MSPinFormat) |
#define | MS_FILTER_SET_INPUT_FMT MS_FILTER_BASE_METHOD(31,MSPinFormat) |
#define | MS_FILTER_GET_OUTPUT_FMT MS_FILTER_BASE_METHOD(32,MSPinFormat) |
#define | MS_FILTER_SET_OUTPUT_FMT MS_FILTER_BASE_METHOD(33,MSPinFormat) |
#define | MS_FILTER_OUTPUT_FMT_CHANGED MS_FILTER_BASE_EVENT_NO_ARG(0) |
#define | MS_FILTER_SET_FILTERLENGTH MS_FILTER_BASE_METHOD(12,int) |
#define | MS_FILTER_SET_OUTPUT_SAMPLE_RATE MS_FILTER_BASE_METHOD(13,int) |
#define | MS_FILTER_ENABLE_DIRECTMODE MS_FILTER_BASE_METHOD(14,int) |
#define | MS_FILTER_ENABLE_VAD MS_FILTER_BASE_METHOD(15,int) |
#define | MS_FILTER_GET_STAT_DISCARDED MS_FILTER_BASE_METHOD(16,int) |
#define | MS_FILTER_GET_STAT_MISSED MS_FILTER_BASE_METHOD(17,int) |
#define | MS_FILTER_GET_STAT_INPUT MS_FILTER_BASE_METHOD(18,int) |
#define | MS_FILTER_GET_STAT_OUTPUT MS_FILTER_BASE_METHOD(19,int) |
#define | MS_FILTER_ENABLE_AGC MS_FILTER_BASE_METHOD(20,int) |
#define | MS_FILTER_SET_PLAYBACKDELAY MS_FILTER_BASE_METHOD(21,int) |
#define | MS_FILTER_ENABLE_HALFDUPLEX MS_FILTER_BASE_METHOD(22,int) |
#define | MS_FILTER_SET_VAD_PROB_START MS_FILTER_BASE_METHOD(23,int) |
#define | MS_FILTER_SET_VAD_PROB_CONTINUE MS_FILTER_BASE_METHOD(24,int) |
#define | MS_FILTER_SET_MAX_GAIN MS_FILTER_BASE_METHOD(25,int) |
#define | MS_VIDEO_CAPTURE_SET_AUTOFOCUS MS_FILTER_BASE_METHOD(26,int) |
#define | MS_FILTER_SET_RTP_PAYLOAD_PICKER MS_FILTER_BASE_METHOD(27,void*) |
#define | MS_FILTER_SET_OUTPUT_NCHANNELS MS_FILTER_BASE_METHOD(28,int) |
Typedefs | |
typedef void(* | MSFilterFunc) (struct _MSFilter *f) |
typedef int(* | MSFilterMethodFunc) (struct _MSFilter *f, void *arg) |
typedef void(* | MSFilterNotifyFunc) (void *userdata, struct _MSFilter *f, unsigned int id, void *arg) |
typedef enum _MSFilterInterfaceId | MSFilterInterfaceId |
typedef struct _MSFilterMethod | MSFilterMethod |
typedef enum _MSFilterCategory | MSFilterCategory |
typedef enum _MSFilterFlags | MSFilterFlags |
typedef struct _MSFilterStats | MSFilterStats |
typedef struct _MSFilterDesc | MSFilterDesc |
typedef struct _MSFilter | MSFilter |
typedef struct _MSConnectionPoint | MSConnectionPoint |
typedef struct _MSConnectionHelper | MSConnectionHelper |
typedef struct _MSPinFormat | MSPinFormat |
Enumerations | |
enum | _MSFilterInterfaceId { MSFilterInterfaceBegin =16384 , MSFilterPlayerInterface , MSFilterRecorderInterface , MSFilterVideoDisplayInterface , MSFilterEchoCancellerInterface , MSFilterVideoDecoderInterface , MSFilterVideoCaptureInterface , MSFilterAudioDecoderInterface , MSFilterVideoEncoderInterface , MSFilterAudioCaptureInterface , MSFilterAudioPlaybackInterface , MSFilterAudioEncoderInterface , MSFilterVADInterface , MSFilterVoidInterface } |
enum | _MSFilterCategory { MS_FILTER_OTHER , MS_FILTER_ENCODER , MS_FILTER_DECODER , MS_FILTER_ENCODING_CAPTURER , MS_FILTER_DECODER_RENDERER } |
enum | _MSFilterFlags { MS_FILTER_IS_PUMP = 1 , MS_FILTER_IS_ENABLED = 1<<31 } |
Functions | |
void | ms_filter_register (MSFilterDesc *desc) |
MSFilterDesc * | ms_filter_get_encoding_capturer (const char *mime) |
MSFilterDesc * | ms_filter_get_decoding_renderer (const char *mime) |
MSFilterDesc * | ms_filter_get_encoder (const char *mime) |
MSFilterDesc * | ms_filter_get_decoder (const char *mime) |
MSFilterDesc * | ms_filter_lookup_by_name (const char *filter_name) |
MSList * | ms_filter_lookup_by_interface (MSFilterInterfaceId id) |
MSFilter * | ms_filter_create_encoder (const char *mime) |
MSFilter * | ms_filter_create_decoder (const char *mime) |
bool_t | ms_filter_codec_supported (const char *mime) |
MSFilter * | ms_filter_new (MSFilterId id) |
MSFilter * | ms_filter_new_from_name (const char *name) |
MSFilter * | ms_filter_new_from_desc (MSFilterDesc *desc) |
int | ms_filter_link (MSFilter *f1, int pin1, MSFilter *f2, int pin2) |
int | ms_filter_unlink (MSFilter *f1, int pin1, MSFilter *f2, int pin2) |
int | ms_filter_call_method (MSFilter *f, unsigned int id, void *arg) |
int | ms_filter_call_method_noarg (MSFilter *f, unsigned int id) |
bool_t | ms_filter_has_method (MSFilter *f, unsigned int id) |
bool_t | ms_filter_implements_interface (MSFilter *f, MSFilterInterfaceId id) |
bool_t | ms_filter_desc_implements_interface (MSFilterDesc *desc, MSFilterInterfaceId id) |
void | ms_filter_add_notify_callback (MSFilter *f, MSFilterNotifyFunc fn, void *userdata, bool_t synchronous) |
void | ms_filter_remove_notify_callback (MSFilter *f, MSFilterNotifyFunc fn, void *userdata) |
MSFilterId | ms_filter_get_id (MSFilter *f) |
const char * | ms_filter_get_name (MSFilter *f) |
MSList * | ms_filter_find_neighbours (MSFilter *me) |
struct _MSTicker * | ms_filter_get_ticker (MSFilter *f) |
void | ms_filter_destroy (MSFilter *f) |
void | ms_connection_helper_start (MSConnectionHelper *h) |
int | ms_connection_helper_link (MSConnectionHelper *h, MSFilter *f, int inpin, int outpin) |
Enter a MSFilter to be connected into the MSConnectionHelper object. | |
int | ms_connection_helper_unlink (MSConnectionHelper *h, MSFilter *f, int inpin, int outpin) |
Enter a MSFilter to be disconnected into the MSConnectionHelper object. Process exactly the same way as ms_connection_helper_link() but calls ms_filter_unlink() on the entered filters. | |
void | ms_filter_enable_statistics (bool_t enabled) |
Enable processing time measurements statistics for filters. | |
void | ms_filter_reset_statistics (void) |
Reset processing time statistics for filters. | |
const MSList * | ms_filter_get_statistics (void) |
Retrieves statistics for running filters. Returns a list of MSFilterStats. | |
void | ms_filter_log_statistics (void) |
Logs runtime statistics for running filters. | |
Filter API to manage mediastreamer2 filters.
This section documents the API needed to create, link, unlink, find and destroy filters.
It also provides definitions if you wish to implement your own filters.
#define MS_FILTER_ADD_FMTP MS_FILTER_BASE_METHOD(7,const char) |
Set codec dependent attributes as taken from the SDP
#define MS_FILTER_GET_BITRATE MS_FILTER_BASE_METHOD(3,int) |
Get filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead
#define MS_FILTER_GET_INPUT_FMT MS_FILTER_BASE_METHOD(30,MSPinFormat) |
Obtain the format of a filter on a given input
#define MS_FILTER_GET_LATENCY MS_FILTER_BASE_METHOD(11,int) |
Filters can return their latency in milliseconds (if known) using this method:
#define MS_FILTER_GET_OUTPUT_FMT MS_FILTER_BASE_METHOD(32,MSPinFormat) |
Obtain the format of a filter on a given output
#define MS_FILTER_GET_SAMPLE_RATE MS_FILTER_BASE_METHOD(1,int) |
Get filter output/input sampling frequency in hertz
#define MS_FILTER_METHOD | ( | _id_, | |
_count_, | |||
_argtype_ | |||
) | MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_)) |
Macro to create a method id, unique per filter. First argument shall be the filter's ID (MSFilterId) or interface ID (MSFilterInterfaceId). Second argument is the method index within the context of the filter. It should start from 0 and increment for each new method. Third argument is the argument type of the method, for example "int", "float" or any structure.
#define MS_FILTER_METHOD_NO_ARG | ( | _id_, | |
_count_ | |||
) | MS_FILTER_METHOD_ID(_id_,_count_,0) |
Same as MS_FILTER_METHOD, but for method that do not take any argument.
#define MS_FILTER_OUTPUT_FMT_CHANGED MS_FILTER_BASE_EVENT_NO_ARG(0) |
MSFilter generic events triggered whenever a filter decides to change its output format for one or more more output pins
#define MS_FILTER_SET_BITRATE MS_FILTER_BASE_METHOD(2,int) |
Set filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead
#define MS_FILTER_SET_INPUT_FMT MS_FILTER_BASE_METHOD(31,MSPinFormat) |
Set the format of a filter on a given input
#define MS_FILTER_SET_OUTPUT_FMT MS_FILTER_BASE_METHOD(33,MSPinFormat) |
Set the format of a filter on a given output
#define MS_FILTER_SET_SAMPLE_RATE MS_FILTER_BASE_METHOD(0,int) |
some MSFilter base generic methods: Set filter output/input sampling frequency in hertz
Structure that holds data when using the ms_connection_helper_* functions.
Structure that represents a connection point of a MSFilter
Structure of filter's object.
Structure to describe filter's category.
MS_FILTER_OTHER MS_FILTER_ENCODER MS_FILTER_DECODER MS_FILTER_ENCODING_CAPTURER MS_FILTER_DECODING_RENDERER
Structure for filter's description.
typedef enum _MSFilterFlags MSFilterFlags |
Filter's flags controlling special behaviours.
MSFilterFunc |
Structure for filter's methods (init, preprocess, process, postprocess, uninit).
typedef enum _MSFilterInterfaceId MSFilterInterfaceId |
Interface IDs, used to generate method names (see MS_FILTER_METHOD macro).
Structure for holding filter's methods to set filter's options.
MSFilterMethodFunc |
Structure for filter's methods used to set filter's options.
MSFilterNotifyFunc |
Structure for filter's methods used as a callback to notify events.
enum _MSFilterCategory |
enum _MSFilterFlags |
enum _MSFilterInterfaceId |
Interface IDs, used to generate method names (see MS_FILTER_METHOD macro). The purpose of these interfaces is to allow different filter implementations to share the same methods, by implementing the method definitions for these interfaces. For example every video encoder implementation would need a method to request the generation of a key frame. Instead of having each implementation defining its own method to do this, each implementation can just implement the MS_VIDEO_ENCODER_REQ_VFU method of the MSFilterVideoEncoderInterface.
int ms_connection_helper_link | ( | MSConnectionHelper * | h, |
MSFilter * | f, | ||
int | inpin, | ||
int | outpin | ||
) |
Enter a MSFilter to be connected into the MSConnectionHelper object.
This functions enters a MSFilter to be connected into the MSConnectionHelper object and connects it to the last entered if not the first one. The MSConnectionHelper is useful to reduce the amount of code necessary to create graphs in case the connections are made in an ordered manner and some filters are present conditionally in graphs. For example, instead of writing
You can write:
Which is a bit longer to write here, but now imagine f2 needs to be present in the graph only in certain conditions: in the first case you have rewrite the two first lines, in the second case you just need to replace the fourth line by:
h | a connection helper |
f | a MSFilter |
inpin | an input pin number with which the MSFilter needs to connect to previously entered MSFilter |
outpin | an output pin number with which the MSFilter needs to be connected to the next entered MSFilter |
Returns: the return value of ms_filter_link() that is called internally to this function.
void ms_connection_helper_start | ( | MSConnectionHelper * | h | ) |
Initialize a MSConnectionHelper.
h | A MSConnectionHelper, usually (but not necessarily) on stack |
void ms_filter_add_notify_callback | ( | MSFilter * | f, |
MSFilterNotifyFunc | fn, | ||
void * | userdata, | ||
bool_t | synchronous | ||
) |
Set a callback on filter's to be informed of private filter's event. This callback is called from the filter's MSTicker, unless a global event queue is created to receive all filter's notification or synchronous flag is TRUE. See ms_event_queue_new() for details.
f | A MSFilter object. |
fn | A MSFilterNotifyFunc that will be called. |
userdata | A pointer to private data. |
synchronous | boolean that indicates whether this callback must be called synchronously. |
int ms_filter_call_method | ( | MSFilter * | f, |
unsigned int | id, | ||
void * | arg | ||
) |
Call a filter's method to set or get options.
f | A MSFilter object. |
id | A private filter ID for the option. |
arg | A private user data for the filter. |
Returns: 0 if successfull, -1 otherwise.
int ms_filter_call_method_noarg | ( | MSFilter * | f, |
unsigned int | id | ||
) |
Call a filter's method to set options.
f | A MSFilter object. |
id | A method ID. |
Returns: 0 if successfull, -1 otherwise.
bool_t ms_filter_codec_supported | ( | const char * | mime | ) |
Check if both an encoder and a decoder filter exists for a codec name.
mime | A string indicating the codec. |
MSFilter * ms_filter_create_decoder | ( | const char * | mime | ) |
Create decoder filter according to codec name.
mime | A string indicating the codec. |
MSFilter * ms_filter_create_encoder | ( | const char * | mime | ) |
Create encoder filter according to codec name.
mime | A string indicating the codec. |
bool_t ms_filter_desc_implements_interface | ( | MSFilterDesc * | desc, |
MSFilterInterfaceId | id | ||
) |
Returns whether a filter implements a given interface, based on the filter's descriptor.
f | a MSFilter object |
id | an interface id. |
Returns TRUE if interface is implemented, FALSE, otherwise.
void ms_filter_destroy | ( | MSFilter * | f | ) |
Destroy a filter object.
f | A MSFilter object. |
MSList * ms_filter_find_neighbours | ( | MSFilter * | me | ) |
Obtain the list of current filter's neighbours, ie filters that are part of same graph.
Returns: a MSList of MSFilter, that needs to be freed by the caller when no more needed.
MSFilterDesc * ms_filter_get_decoder | ( | const char * | mime | ) |
Retrieve decoders according to codec name.
mime | A string indicating the codec. |
MSFilterDesc * ms_filter_get_decoding_renderer | ( | const char * | mime | ) |
Retrieve render filter that supports decoding to codec name.
mime | A string indicating the codec. |
MSFilterDesc * ms_filter_get_encoder | ( | const char * | mime | ) |
Retrieve encoders according to codec name.
mime | A string indicating the codec. |
MSFilterDesc * ms_filter_get_encoding_capturer | ( | const char * | mime | ) |
Retrieve capture filter that supports encoding to codec name.
mime | A string indicating the codec. |
MSFilterId ms_filter_get_id | ( | MSFilter * | f | ) |
Get MSFilterId's filter.
f | A MSFilter object. |
Returns: MSFilterId if successfull, -1 otherwise.
const char * ms_filter_get_name | ( | MSFilter * | f | ) |
Returns the MSTicker that is currently running this filter. It might be NULL, if the filter has not been attached to a ticker for running.
bool_t ms_filter_has_method | ( | MSFilter * | f, |
unsigned int | id | ||
) |
Returns whether the filter implements a given method
f | A MSFilter object. |
id | A method ID. |
Returns: TRUE if method is implemented, FALSE otherwise.
bool_t ms_filter_implements_interface | ( | MSFilter * | f, |
MSFilterInterfaceId | id | ||
) |
Returns whether a filter implements a given interface.
f | a MSFilter object |
id | an interface id. |
Returns TRUE if interface is implemented, FALSE, otherwise.
Link one OUTPUT pin from a filter to an INPUT pin of another filter.
All data coming from the OUTPUT pin of one filter will be distributed to the INPUT pin of the second filter.
f1 | A MSFilter object containing the OUTPUT pin |
pin1 | An index of an OUTPUT pin. |
f2 | A MSFilter object containing the INPUT pin |
pin2 | An index of an INPUT pin. |
Returns: 0 if sucessful, -1 otherwise.
MSList * ms_filter_lookup_by_interface | ( | MSFilterInterfaceId | id | ) |
Returns a list of filter descriptions implementing a given interface. The list itself must be freed by the caller of this function, but not the MSFilterDesc pointed by the list elements.
id | a filter interface id |
MSFilterDesc * ms_filter_lookup_by_name | ( | const char * | filter_name | ) |
Lookup a mediastreamer2 filter using its name. If found, the descriptor (MSFilterDesc) is returned. This descriptor can be used to instanciate the filter using ms_filter_new_from_desc() This function can be useful to query the presence of a filter loaded as a plugin, for example.
filter_name | The filter name. |
MSFilter * ms_filter_new | ( | MSFilterId | id | ) |
Create decoder filter according to a filter's MSFilterId.
id | A MSFilterId identifier for the filter. |
MSFilter * ms_filter_new_from_desc | ( | MSFilterDesc * | desc | ) |
Create decoder filter according to a filter's description.
The primary use is to create your own filter's in your application and avoid registration inside mediastreamer2.
desc | A MSFilterDesc for the filter. |
MSFilter * ms_filter_new_from_name | ( | const char * | name | ) |
Create decoder filter according to a filter's name.
name | A name for the filter. |
void ms_filter_register | ( | MSFilterDesc * | desc | ) |
Register a filter description. (plugins use only!)
When you build your own plugin, this method will add the encoder or decoder to the internal list of supported codec. Then, this plugin can be used transparently from the application.
ms_filter_get_encoder, ms_filter_get_decoder, ms_filter_create_encoder, ms_filter_create_decoder and ms_filter_codec_supported can then be used as if the codec was internally. supported.
desc | a filter description. |
void ms_filter_remove_notify_callback | ( | MSFilter * | f, |
MSFilterNotifyFunc | fn, | ||
void * | userdata | ||
) |
Remove a notify callback previously entered with ms_filter_add_notify_callback()
f | A MSFilter object. |
fn | A MSFilterNotifyFunc that will be called. |
userdata | A pointer to private data. |
Unlink one OUTPUT pin from a filter to an INPUT pin of another filter.
f1 | A MSFilter object containing the OUTPUT pin |
pin1 | An index of an OUTPUT pin. |
f2 | A MSFilter object containing the INPUT pin |
pin2 | An index of an INPUT pin. |
Returns: 0 if sucessful, -1 otherwise.