msfilter.h 23.3 KB
Newer Older
aymeric's avatar
aymeric committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
/*
mediastreamer2 library - modular sound and video processing and streaming
Copyright (C) 2006  Simon MORLAT (simon.morlat@linphone.org)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program 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 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

#ifndef msfilter_h
#define msfilter_h

#include "mscommon.h"
#include "msqueue.h"
#include "allfilters.h"

/**
 * @file msfilter.h
 * @brief mediastreamer2 msfilter.h include file
 *
 * This file provide the API needed to create, link,
 * unlink, find and destroy filter.
 *
 * It also provides definitions if you wish to implement
 * your own filters.
 *
 */

/**
 * @defgroup mediastreamer2_filter Filter API - manage mediastreamer2 filters.
 * @ingroup mediastreamer2_api
 * @{
 */

/**
 * Structure for filter's methods (init, preprocess, process, postprocess, uninit).
 * @var MSFilterFunc
 */
typedef void (*MSFilterFunc)(struct _MSFilter *f);

/**
 * Structure for filter's methods used to set filter's options.
 * @var MSFilterMethodFunc
 */
typedef int (*MSFilterMethodFunc)(struct _MSFilter *f, void *arg);

/**
 * Structure for filter's methods used as a callback to notify events.
 * @var MSFilterNotifyFunc
 */
61
typedef void (*MSFilterNotifyFunc)(void *userdata, struct _MSFilter *f, unsigned int id, void *arg);
aymeric's avatar
aymeric committed
62 63 64 65 66 67 68

struct _MSFilterMethod{
	int id;
	MSFilterMethodFunc method;
};


Ghislain MARY's avatar
Ghislain MARY committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
/**
 * 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.
**/
enum _MSFilterInterfaceId{
	MSFilterInterfaceBegin=16384,
	MSFilterPlayerInterface, /**<Player interface, used to control playing of files.*/
	MSFilterRecorderInterface,/**<Recorder interface, used to control recording of stream into files.*/
	MSFilterVideoDisplayInterface,/**<Video display interface, used to control the rendering of raw pictures onscreen.*/
	MSFilterEchoCancellerInterface,/**Echo canceller interface, used to control echo canceller implementations.*/
	MSFilterVideoDecoderInterface,/**<Video decoder interface*/
	MSFilterVideoCaptureInterface,/**<Video capture interface*/
	MSFilterAudioDecoderInterface,/**<Audio Decoder interface*/
	MSFilterVideoEncoderInterface,/**<Video encoder interface*/
	MSFilterAudioCaptureInterface,/**<Interface for audio capture filters*/
	MSFilterAudioPlaybackInterface,/**Interface for audio playback filters.*/
	MSFilterAudioEncoderInterface,/**<Video encoder interface*/
};

90 91
/**
 * Interface IDs, used to generate method names (see MS_FILTER_METHOD macro).
92
 *
93 94 95
**/
typedef enum _MSFilterInterfaceId MSFilterInterfaceId;

aymeric's avatar
aymeric committed
96 97 98 99 100
/**
 * Structure for holding filter's methods to set filter's options.
 * @var MSFilterMethod
 */
typedef struct _MSFilterMethod MSFilterMethod;
101 102 103 104
/**
 * Filter's category
 *
 */
aymeric's avatar
aymeric committed
105
enum _MSFilterCategory{
106
	/**others*/
aymeric's avatar
aymeric committed
107
	MS_FILTER_OTHER,
108
	/**used by encoders*/
aymeric's avatar
aymeric committed
109
	MS_FILTER_ENCODER,
110
	/**used by decoders*/
111 112 113
	MS_FILTER_DECODER,
	/**used by capture filters that perform encoding*/
	MS_FILTER_ENCODING_CAPTURER,
114 115
	/**used by filters that perform decoding and rendering */
	MS_FILTER_DECODER_RENDERER
aymeric's avatar
aymeric committed
116 117 118 119 120 121 122 123
};

/**
 * Structure to describe filter's category.
 * <PRE>
 *     MS_FILTER_OTHER
 *     MS_FILTER_ENCODER
 *     MS_FILTER_DECODER
124 125
 *     MS_FILTER_ENCODING_CAPTURER
 *     MS_FILTER_DECODING_RENDERER
aymeric's avatar
aymeric committed
126 127 128 129 130
 * </PRE>
 * @var MSFilterCategory
 */
typedef enum _MSFilterCategory MSFilterCategory;

131 132 133
/**
 * Filter's flags controlling special behaviours.
**/
134
enum _MSFilterFlags{
135
	MS_FILTER_IS_PUMP = 1 /**< The filter must be called in process function every tick.*/
136 137
};

138 139 140
/**
 * Filter's flags controlling special behaviours.
**/
141 142
typedef enum _MSFilterFlags MSFilterFlags;

143 144 145 146 147 148 149

struct _MSFilterStats{
	const char *name; /*<filter name*/
	uint64_t elapsed; /*<cumulative number of nanoseconds elapsed */
	unsigned int count; /*<number of time the filter is called for processing*/
};

150
typedef struct _MSFilterStats MSFilterStats;
151

aymeric's avatar
aymeric committed
152
struct _MSFilterDesc{
153 154 155 156 157 158 159 160 161 162 163 164 165 166
	MSFilterId id;	/**< the id declared in allfilters.h */
	const char *name; /**< the filter name*/
	const char *text; /**< short text describing the filter's function*/
	MSFilterCategory category; /**< filter's category*/
	const char *enc_fmt; /**< sub-mime of the format, must be set if category is MS_FILTER_ENCODER or MS_FILTER_DECODER */
	int ninputs; /**< number of inputs */
	int noutputs; /**< number of outputs */
	MSFilterFunc init; /**< Filter's init function*/
	MSFilterFunc preprocess; /**< Filter's preprocess function, called one time before starting to process*/
	MSFilterFunc process; /**< Filter's process function, called every tick by the MSTicker to do the filter's job*/
	MSFilterFunc postprocess; /**< Filter's postprocess function, called once after processing (the filter is no longer called in process() after)*/
	MSFilterFunc uninit; /**< Filter's uninit function, used to deallocate internal structures*/
	MSFilterMethod *methods; /**<Filter's method table*/
	unsigned int flags; /**<Filter's special flags, from the MSFilterFlags enum.*/
aymeric's avatar
aymeric committed
167 168 169 170 171 172 173 174 175
};

/**
 * Structure for filter's description.
 * @var MSFilterDesc
 */
typedef struct _MSFilterDesc MSFilterDesc;

struct _MSFilter{
176
	MSFilterDesc *desc; /**<Back pointer to filter's descriptor.*/
177
	/*protected attributes, do not move or suppress any of them otherwise plugins will be broken */
aymeric's avatar
aymeric committed
178
	ms_mutex_t lock;
179 180
	MSQueue **inputs; /**<Table of input queues.*/
	MSQueue **outputs;/**<Table of output queues */
181 182
	void *padding[2]; /**Unused - to be reused later when new protected fields have to added*/
	void *data; /**< Pointer used by the filter for internal state and computations.*/
183
	struct _MSTicker *ticker; /**<Pointer to the ticker object. It is not NULL when being called process()*/
184 185
	/*private attributes, they can be moved and changed at any time*/
	MSList *notify_callbacks;
aymeric's avatar
aymeric committed
186
	uint32_t last_tick;
187
	MSFilterStats *stats;
188
	int postponed_task; /*number of postponed tasks*/
aymeric's avatar
aymeric committed
189 190 191 192 193
	bool_t seen;
};


/**
194
 * Structure of filter's object.
aymeric's avatar
aymeric committed
195 196 197 198
 * @var MSFilter
 */
typedef struct _MSFilter MSFilter;

199
struct _MSConnectionPoint{
200 201
	MSFilter *filter; /**<Pointer to filter*/
	int pin; /**<Pin index on the filter*/
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
};

/**
 * Structure that represents a connection point of a MSFilter
 * @var MSConnectionPoint
 */
typedef struct _MSConnectionPoint MSConnectionPoint;

struct _MSConnectionHelper{
	MSConnectionPoint last;
};

/**
 * Structure that holds data when using the ms_connection_helper_* functions.
 * @var MSConnectionHelper
**/
typedef struct _MSConnectionHelper MSConnectionHelper;

aymeric's avatar
aymeric committed
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240

#ifdef __cplusplus
extern "C"{
#endif

/**
 * 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.
 *
 * @param desc    a filter description.
 */
Simon Morlat's avatar
Simon Morlat committed
241
MS2_PUBLIC void ms_filter_register(MSFilterDesc *desc);
aymeric's avatar
aymeric committed
242

243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
/**
 * Retrieve capture filter that supports encoding to codec name.
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilterDesc if successfull, NULL otherwise.
 */
MS2_PUBLIC MSFilterDesc * ms_filter_get_encoding_capturer(const char *mime);

/**
 * Retrieve render filter that supports decoding to codec name.
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilterDesc if successfull, NULL otherwise.
 */
MS2_PUBLIC MSFilterDesc * ms_filter_get_decoding_renderer(const char *mime);

aymeric's avatar
aymeric committed
261 262 263 264 265 266 267 268 269 270 271 272
/**
 * Retrieve encoders according to codec name.
 *
 * Internal supported codecs:
 *    PCMU, PCMA, speex, gsm
 * Existing Public plugins:
 *    iLBC
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilterDesc if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
273
MS2_PUBLIC MSFilterDesc * ms_filter_get_encoder(const char *mime);
aymeric's avatar
aymeric committed
274 275 276 277 278 279 280 281 282 283 284 285 286

/**
 * Retrieve decoders according to codec name.
 *
 * Internal supported codecs:
 *    PCMU, PCMA, speex, gsm
 * Existing Public plugins:
 *    iLBC
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilterDesc if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
287
MS2_PUBLIC MSFilterDesc * ms_filter_get_decoder(const char *mime);
aymeric's avatar
aymeric committed
288

289 290 291 292 293 294 295 296 297
/**
 * 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.
 *
 * @param name The filter name.
**/
MS2_PUBLIC MSFilterDesc *ms_filter_lookup_by_name(const char *filter_name);
298

299 300 301 302 303 304 305 306
/**
 * 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.
 * @param id a filter interface id
 * @returns a newly allocated MSList of #MSFilterDesc.
**/
MSList *ms_filter_lookup_by_interface(MSFilterInterfaceId id);

aymeric's avatar
aymeric committed
307 308 309 310 311 312 313 314 315 316 317 318
/**
 * Create encoder filter according to codec name.
 *
 * Internal supported codecs:
 *    PCMU, PCMA, speex, gsm
 * Existing Public plugins:
 *    iLBC
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
319
MS2_PUBLIC MSFilter * ms_filter_create_encoder(const char *mime);
aymeric's avatar
aymeric committed
320 321 322 323 324 325 326 327 328 329 330 331 332

/**
 * Create decoder filter according to codec name.
 *
 * Internal supported codecs:
 *    PCMU, PCMA, speex, gsm
 * Existing Public plugins:
 *    iLBC
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: a MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
333
MS2_PUBLIC MSFilter * ms_filter_create_decoder(const char *mime);
aymeric's avatar
aymeric committed
334 335 336 337 338 339 340 341 342 343 344 345 346

/**
 * Check if a encode or decode filter exists for a codec name.
 *
 * Internal supported codecs:
 *    PCMU, PCMA, speex, gsm
 * Existing Public plugins:
 *    iLBC
 *
 * @param mime    A string indicating the codec.
 *
 * Returns: TRUE if successfull, FALSE otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
347
MS2_PUBLIC bool_t ms_filter_codec_supported(const char *mime);
aymeric's avatar
aymeric committed
348 349 350 351 352 353 354 355

/**
 * Create decoder filter according to a filter's MSFilterId.
 *
 * @param id     A MSFilterId identifier for the filter.
 *
 * Returns: a MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
356
MS2_PUBLIC MSFilter *ms_filter_new(MSFilterId id);
aymeric's avatar
aymeric committed
357 358 359 360 361 362 363 364

/**
 * Create decoder filter according to a filter's name.
 *
 * @param name   A name for the filter.
 *
 * Returns: a MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
365
MS2_PUBLIC MSFilter *ms_filter_new_from_name(const char *name);
aymeric's avatar
aymeric committed
366 367 368 369 370 371

/**
 * 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.
372
 *
aymeric's avatar
aymeric committed
373 374 375 376
 * @param desc   A MSFilterDesc for the filter.
 *
 * Returns: a MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
377
MS2_PUBLIC MSFilter *ms_filter_new_from_desc(MSFilterDesc *desc);
aymeric's avatar
aymeric committed
378 379 380 381 382 383 384 385 386 387 388 389

/**
 * 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.
 *
 * @param f1   A MSFilter object containing the OUTPUT pin
 * @param pin1 An index of an OUTPUT pin.
 * @param f2   A MSFilter object containing the INPUT pin
 * @param pin2 An index of an INPUT pin.
 *
390
 * Returns: 0 if sucessful, -1 otherwise.
aymeric's avatar
aymeric committed
391
 */
Simon Morlat's avatar
Simon Morlat committed
392
MS2_PUBLIC int ms_filter_link(MSFilter *f1, int pin1, MSFilter *f2, int pin2);
aymeric's avatar
aymeric committed
393 394 395 396 397 398 399 400 401

/**
 * Unlink one OUTPUT pin from a filter to an INPUT pin of another filter.
 *
 * @param f1   A MSFilter object containing the OUTPUT pin
 * @param pin1 An index of an OUTPUT pin.
 * @param f2   A MSFilter object containing the INPUT pin
 * @param pin2 An index of an INPUT pin.
 *
402
 * Returns: 0 if sucessful, -1 otherwise.
aymeric's avatar
aymeric committed
403
 */
Simon Morlat's avatar
Simon Morlat committed
404
MS2_PUBLIC int ms_filter_unlink(MSFilter *f1, int pin1, MSFilter *f2, int pin2);
aymeric's avatar
aymeric committed
405 406 407 408 409 410 411 412 413 414

/**
 * Call a filter's method to set or get options.
 *
 * @param f    A MSFilter object.
 * @param id   A private filter ID for the option.
 * @param arg  A private user data for the filter.
 *
 * Returns: 0 if successfull, -1 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
415
MS2_PUBLIC int ms_filter_call_method(MSFilter *f, unsigned int id, void *arg);
aymeric's avatar
aymeric committed
416 417 418 419 420

/**
 * Call a filter's method to set options.
 *
 * @param f    A MSFilter object.
Simon Morlat's avatar
Simon Morlat committed
421
 * @param id   A method ID.
aymeric's avatar
aymeric committed
422 423 424
 *
 * Returns: 0 if successfull, -1 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
425
MS2_PUBLIC int ms_filter_call_method_noarg(MSFilter *f, unsigned int id);
aymeric's avatar
aymeric committed
426

Simon Morlat's avatar
Simon Morlat committed
427 428 429 430 431 432 433 434 435 436 437

/**
 * Returns whether the filter implements a given method
 *
 * @param f    A MSFilter object.
 * @param id   A method ID.
 *
 * Returns: 0 if successfull, -1 otherwise.
 */
MS2_PUBLIC bool_t ms_filter_has_method(MSFilter *f, unsigned int id);

aymeric's avatar
aymeric committed
438 439
/**
 * Set a callback on filter's to be informed of private filter's event.
440 441 442
 * This callback is called from the filter's MSTicker, unless a global event queue
 * is created to receive all filter's notification asynchronously.
 * See ms_event_queue_new() for details.
aymeric's avatar
aymeric committed
443 444 445 446
 *
 * @param f        A MSFilter object.
 * @param fn       A MSFilterNotifyFunc that will be called.
 * @param userdata A pointer to private data.
447
 * @deprecated use ms_filter_add_notify_callback()
aymeric's avatar
aymeric committed
448
 *
449 450 451 452 453 454 455 456 457 458 459 460 461 462
 */
//MS2_PUBLIC void ms_filter_set_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata);

/**
 * 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.
 *
 * @param f        A MSFilter object.
 * @param fn       A MSFilterNotifyFunc that will be called.
 * @param userdata A pointer to private data.
 * @param synchronous boolean that indicates whether this callback must be called synchronously.
 * @deprecated use ms_filter_add_notify_callback()
463
 *
aymeric's avatar
aymeric committed
464
 */
465
MS2_PUBLIC void ms_filter_add_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata, bool_t synchronous);
aymeric's avatar
aymeric committed
466

467 468 469 470 471 472 473 474 475 476 477
/**
 * Remove a notify callback previously entered with ms_filter_add_notify_callback()
 *
 * @param f        A MSFilter object.
 * @param fn       A MSFilterNotifyFunc that will be called.
 * @param userdata A pointer to private data.
 * @param synchronous boolean that indicates whether this callback must be called synchronously.
 * @deprecated use ms_filter_add_notify_callback()
 *
 */
MS2_PUBLIC void ms_filter_remove_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata);
478

aymeric's avatar
aymeric committed
479 480 481 482 483 484 485
/**
 * Get MSFilterId's filter.
 *
 * @param f        A MSFilter object.
 *
 * Returns: MSFilterId if successfull, -1 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
486
MS2_PUBLIC MSFilterId ms_filter_get_id(MSFilter *f);
aymeric's avatar
aymeric committed
487

488 489 490 491 492 493

/**
 * 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.
**/
Simon Morlat's avatar
Simon Morlat committed
494
MS2_PUBLIC MSList * ms_filter_find_neighbours(MSFilter *me);
495

aymeric's avatar
aymeric committed
496 497 498 499 500 501
/**
 * Destroy a filter object.
 *
 * @param f        A MSFilter object.
 *
 */
Simon Morlat's avatar
Simon Morlat committed
502
MS2_PUBLIC void ms_filter_destroy(MSFilter *f);
aymeric's avatar
aymeric committed
503

504 505 506 507 508 509
/**
 * Initialize a MSConnectionHelper.
 *
 * @param h A MSConnectionHelper, usually (but not necessarily) on stack
 *
**/
Simon Morlat's avatar
Simon Morlat committed
510
MS2_PUBLIC void ms_connection_helper_start(MSConnectionHelper *h);
511 512 513

/**
 * \brief Enter a MSFilter to be connected into the MSConnectionHelper object.
514
 *
515 516
 * This functions enters a MSFilter to be connected into the MSConnectionHelper
 * object and connects it to the last entered if not the first one.
517
 * The MSConnectionHelper is useful to reduce the amount of code necessary to create graphs in case
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
 * the connections are made in an ordered manner and some filters are present conditionally in graphs.
 * For example, instead of writing
 * \code
 * ms_filter_link(f1,0,f2,1);
 * ms_filter_link(f2,0,f3,0);
 * ms_filter_link(f3,1,f4,0);
 * \endcode
 * You can write:
 * \code
 * MSConnectionHelper h;
 * ms_connection_helper_start(&h);
 * ms_connection_helper_link(&h,f1,-1,0);
 * ms_connection_helper_link(&h,f2,1,0);
 * ms_connection_helper_link(&h,f3,0,1);
 * ms_connection_helper_link(&h,f4,0,-1);
 * \endcode
 * 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:
 * \code
 * if (my_condition) ms_connection_helper_link(&h,f2,1,0);
 * \endcode
 *
541
 * @param h a connection helper
542 543 544
 * @param f a MSFilter
 * @param inpin an input pin number with which the MSFilter needs to connect to previously entered MSFilter
 * @param outpin an output pin number with which the MSFilter needs to be connected to the next entered MSFilter
545
 *
546 547
 * Returns: the return value of ms_filter_link() that is called internally to this function.
**/
Simon Morlat's avatar
Simon Morlat committed
548
MS2_PUBLIC int ms_connection_helper_link(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin);
549 550 551 552


/**
 * \brief Enter a MSFilter to be disconnected into the MSConnectionHelper object.
553
 * Process exactly the same way as ms_connection_helper_link() but calls ms_filter_unlink() on the
554 555
 * entered filters.
**/
Simon Morlat's avatar
Simon Morlat committed
556
MS2_PUBLIC int ms_connection_helper_unlink(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin);
557

558 559

/**
Simon Morlat's avatar
Simon Morlat committed
560
 * \brief Enable processing time measurements statistics for filters.
561 562
 *
**/
Simon Morlat's avatar
Simon Morlat committed
563
MS2_PUBLIC void ms_filter_enable_statistics(bool_t enabled);
564

Simon Morlat's avatar
Simon Morlat committed
565 566 567 568 569

/**
 * \brief Reset processing time statistics for filters.
 *
**/
Simon Morlat's avatar
Simon Morlat committed
570
MS2_PUBLIC void ms_filter_reset_statistics(void);
571

572 573 574 575
/**
 * \brief Retrieves statistics for running filters.
 * Returns a list of MSFilterStats
**/
Simon Morlat's avatar
Simon Morlat committed
576
MS2_PUBLIC const MSList * ms_filter_get_statistics(void);
577

Simon Morlat's avatar
Simon Morlat committed
578 579
/**
 * \brief Logs runtime statistics for running filters.
580
 *
Simon Morlat's avatar
Simon Morlat committed
581
**/
Simon Morlat's avatar
Simon Morlat committed
582
MS2_PUBLIC void ms_filter_log_statistics(void);
583 584


aymeric's avatar
aymeric committed
585 586 587 588 589 590
/* I define the id taking the lower bits of the address of the MSFilterDesc object,
the method index (_cnt_) and the argument size */
/* I hope using this to avoid type mismatch (calling a method on the wrong filter)*/
#define MS_FILTER_METHOD_ID(_id_,_cnt_,_argsize_) \
	(  (((unsigned long)(_id_)) & 0xFFFF)<<16 | (_cnt_<<8) | (_argsize_ & 0xFF ))

591
/**
592
 * Macro to create a method id, unique per filter.
593 594 595 596
 * 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.
**/
aymeric's avatar
aymeric committed
597 598 599
#define MS_FILTER_METHOD(_id_,_count_,_argtype_) \
	MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_))

600 601 602
/**
 * Same as MS_FILTER_METHOD, but for method that do not take any argument.
**/
aymeric's avatar
aymeric committed
603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618
#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)

619 620 621 622 623 624
/**
 *  some MSFilter base generic methods:
 **/
/**
 * Set filter output/input sampling frequency in hertz
 */
aymeric's avatar
aymeric committed
625
#define MS_FILTER_SET_SAMPLE_RATE	MS_FILTER_BASE_METHOD(0,int)
626 627 628 629
/**
 * Get filter output/input sampling frequency in hertz
 */

aymeric's avatar
aymeric committed
630
#define MS_FILTER_GET_SAMPLE_RATE	MS_FILTER_BASE_METHOD(1,int)
631 632 633
/**
 * Set filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead
 */
aymeric's avatar
aymeric committed
634
#define MS_FILTER_SET_BITRATE		MS_FILTER_BASE_METHOD(2,int)
635 636 637
/**
 * Get filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead
 */
aymeric's avatar
aymeric committed
638 639 640
#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)
641 642 643
/**
 * Set codec dependent attributes as taken from the SDP
 */
aymeric's avatar
aymeric committed
644
#define MS_FILTER_ADD_FMTP		MS_FILTER_BASE_METHOD(7,const char)
645

aymeric's avatar
aymeric committed
646 647 648
#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)
649 650
/**Filters can return their latency in milliseconds (if known) using this method:*/
#define MS_FILTER_GET_LATENCY	MS_FILTER_BASE_METHOD(11,int)
aymeric's avatar
aymeric committed
651

652

653
/* more specific methods: to be moved into implementation specific header files*/
aymeric's avatar
aymeric committed
654 655 656 657 658 659 660 661 662
#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)
aymeric's avatar
aymeric committed
663
#define MS_FILTER_SET_PLAYBACKDELAY MS_FILTER_BASE_METHOD(21,int)
664 665 666
#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)
667
#define MS_FILTER_SET_MAX_GAIN  MS_FILTER_BASE_METHOD(25,int)
668
#define MS_VIDEO_CAPTURE_SET_AUTOFOCUS MS_FILTER_BASE_METHOD(26,int)
jehan's avatar
jehan committed
669
/* pass value of type MSRtpPayloadPickerContext copied by the filter*/
670 671
#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)
672

673
#define MS_CONF_SPEEX_PREPROCESS_MIC	MS_FILTER_EVENT(MS_CONF_ID, 1, void*)
674 675
#define MS_CONF_CHANNEL_VOLUME	MS_FILTER_EVENT(MS_CONF_ID, 3, void*)

aymeric's avatar
aymeric committed
676 677
/** @} */

678
/*protected/ private methods*/
679 680 681 682 683 684
MS2_PUBLIC void ms_filter_process(MSFilter *f);
MS2_PUBLIC void ms_filter_preprocess(MSFilter *f, struct _MSTicker *t);
MS2_PUBLIC void ms_filter_postprocess(MSFilter *f);
MS2_PUBLIC bool_t ms_filter_inputs_have_data(MSFilter *f);
MS2_PUBLIC void ms_filter_notify(MSFilter *f, unsigned int id, void *arg);
MS2_PUBLIC void ms_filter_notify_no_arg(MSFilter *f, unsigned int id);
685
void ms_filter_clear_notify_callback(MSFilter *f);
686
void ms_filter_clean_pending_events(MSFilter *f);
aymeric's avatar
aymeric committed
687 688
#define ms_filter_lock(f)	ms_mutex_lock(&(f)->lock)
#define ms_filter_unlock(f)	ms_mutex_unlock(&(f)->lock)
689
MS2_PUBLIC void ms_filter_unregister_all(void);
aymeric's avatar
aymeric committed
690

691 692 693 694 695
struct _MSFilterTask{
	MSFilter *f;
	MSFilterFunc taskfunc;
};
typedef struct _MSFilterTask MSFilterTask;
696
MS2_PUBLIC void ms_filter_task_process(MSFilterTask *task);
697 698 699 700 701

/**
 * Allow a filter to request the ticker to call him the tick after.
 * The ticker will call the taskfunc prior to all filter's process func.
**/
702
MS2_PUBLIC void ms_filter_postpone_task(MSFilter *f, MSFilterFunc taskfunc);
703

aymeric's avatar
aymeric committed
704 705 706 707
#ifdef __cplusplus
}
#endif

708 709
#include "msinterfaces.h"

aymeric's avatar
aymeric committed
710 711 712 713
/* used by awk script in Makefile.am to generate alldescs.c */
#define MS_FILTER_DESC_EXPORT(desc)

#endif