sjero.net Git - linphone/blob - linphone/mediastreamer2/include/mediastreamer2/msfilter.h

   1 /*
   2 mediastreamer2 library - modular sound and video processing and streaming
   3 Copyright (C) 2006  Simon MORLAT (simon.morlat@linphone.org)
   4
   5 This program is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU General Public License
   7 as published by the Free Software Foundation; either version 2
   8 of the License, or (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18 */
  19
  20 #ifndef msfilter_h
  21 #define msfilter_h
  22
  23 #include "mscommon.h"
  24 #include "msqueue.h"
  25 #include "allfilters.h"
  26
  27 /**
  28  * @file msfilter.h
  29  * @brief mediastreamer2 msfilter.h include file
  30  *
  31  * This file provide the API needed to create, link,
  32  * unlink, find and destroy filter.
  33  *
  34  * It also provides definitions if you wish to implement
  35  * your own filters.
  36  *
  37  */
  38
  39 /**
  40  * @defgroup mediastreamer2_filter Filter API - manage mediastreamer2 filters.
  41  * @ingroup mediastreamer2_api
  42  * @{
  43  */
  44
  45 /**
  46  * Structure for filter's methods (init, preprocess, process, postprocess, uninit).
  47  * @var MSFilterFunc
  48  */
  49 typedef void (*MSFilterFunc)(struct _MSFilter *f);
  50
  51 /**
  52  * Structure for filter's methods used to set filter's options.
  53  * @var MSFilterMethodFunc
  54  */
  55 typedef int (*MSFilterMethodFunc)(struct _MSFilter *f, void *arg);
  56
  57 /**
  58  * Structure for filter's methods used as a callback to notify events.
  59  * @var MSFilterNotifyFunc
  60  */
  61 typedef void (*MSFilterNotifyFunc)(void *userdata , unsigned int id, void *arg);
  62
  63 struct _MSFilterMethod{
  64         int id;
  65         MSFilterMethodFunc method;
  66 };
  67
  68
  69 /**
  70  * Structure for holding filter's methods to set filter's options.
  71  * @var MSFilterMethod
  72  */
  73 typedef struct _MSFilterMethod MSFilterMethod;
  74
  75 enum _MSFilterCategory{
  76         MS_FILTER_OTHER,
  77         MS_FILTER_ENCODER,
  78         MS_FILTER_DECODER
  79 };
  80
  81 /**
  82  * Structure to describe filter's category.
  83  * <PRE>
  84  *     MS_FILTER_OTHER
  85  *     MS_FILTER_ENCODER
  86  *     MS_FILTER_DECODER
  87  * </PRE>
  88  * @var MSFilterCategory
  89  */
  90 typedef enum _MSFilterCategory MSFilterCategory;
  91
  92 enum _MSFilterFlags{
  93         MS_FILTER_IS_PUMP = 1
  94 };
  95
  96 typedef enum _MSFilterFlags MSFilterFlags;
  97
  98 struct _MSFilterDesc{
  99         MSFilterId id;  /* the id declared in allfilters.h */
 100         const char *name; /* filter name */
 101         const char *text; /*some descriptive text*/
 102         MSFilterCategory category;
 103         const char *enc_fmt; /* must be set if MS_FILTER_ENCODER/MS_FILTER_DECODER */
 104         int ninputs; /*number of inputs */
 105         int noutputs; /*number of outputs */
 106         MSFilterFunc init;
 107         MSFilterFunc preprocess;        /* called once before processing */
 108         MSFilterFunc process;           /* called every tick to do the filter's job*/
 109         MSFilterFunc postprocess;       /*called once after processing */
 110         MSFilterFunc uninit;
 111         MSFilterMethod *methods;
 112         unsigned int flags;
 113 };
 114
 115 /**
 116  * Structure for filter's description.
 117  * @var MSFilterDesc
 118  */
 119 typedef struct _MSFilterDesc MSFilterDesc;
 120
 121 struct _MSFilter{
 122         MSFilterDesc *desc;
 123         /*protected attributes */
 124         ms_mutex_t lock;
 125         MSQueue **inputs;
 126         MSQueue **outputs;
 127         MSFilterNotifyFunc notify;
 128         void *notify_ud;
 129         void *data;
 130         struct _MSTicker *ticker;
 131         /*private attributes */
 132         uint32_t last_tick;
 133         bool_t seen;
 134 };
 135
 136
 137 /**
 138  * Structure to create/link/unlink/destroy filter's object.
 139  * @var MSFilter
 140  */
 141 typedef struct _MSFilter MSFilter;
 142
 143 struct _MSConnectionPoint{
 144         MSFilter *filter;
 145         int pin;
 146 };
 147
 148 /**
 149  * Structure that represents a connection point of a MSFilter
 150  * @var MSConnectionPoint
 151  */
 152 typedef struct _MSConnectionPoint MSConnectionPoint;
 153
 154 struct _MSConnectionHelper{
 155         MSConnectionPoint last;
 156 };
 157
 158 /**
 159  * Structure that holds data when using the ms_connection_helper_* functions.
 160  * @var MSConnectionHelper
 161 **/
 162 typedef struct _MSConnectionHelper MSConnectionHelper;
 163
 164
 165 #ifdef __cplusplus
 166 extern "C"{
 167 #endif
 168
 169 /**
 170  * Register a filter description. (plugins use only!)
 171  *
 172  * When you build your own plugin, this method will
 173  * add the encoder or decoder to the internal list
 174  * of supported codec. Then, this plugin can be used
 175  * transparently from the application.
 176  *
 177  * ms_filter_get_encoder, ms_filter_get_decoder,
 178  * ms_filter_create_encoder, ms_filter_create_decoder
 179  * and ms_filter_codec_supported
 180  * can then be used as if the codec was internally.
 181  * supported.
 182  *
 183  * @param desc    a filter description.
 184  */
 185 void ms_filter_register(MSFilterDesc *desc);
 186
 187 /**
 188  * Retrieve encoders according to codec name.
 189  *
 190  * Internal supported codecs:
 191  *    PCMU, PCMA, speex, gsm
 192  * Existing Public plugins:
 193  *    iLBC
 194  *
 195  * @param mime    A string indicating the codec.
 196  *
 197  * Returns: a MSFilterDesc if successfull, NULL otherwise.
 198  */
 199 MSFilterDesc * ms_filter_get_encoder(const char *mime);
 200
 201 /**
 202  * Retrieve decoders according to codec name.
 203  *
 204  * Internal supported codecs:
 205  *    PCMU, PCMA, speex, gsm
 206  * Existing Public plugins:
 207  *    iLBC
 208  *
 209  * @param mime    A string indicating the codec.
 210  *
 211  * Returns: a MSFilterDesc if successfull, NULL otherwise.
 212  */
 213 MSFilterDesc * ms_filter_get_decoder(const char *mime);
 214
 215 /**
 216  * Create encoder filter according to codec name.
 217  *
 218  * Internal supported codecs:
 219  *    PCMU, PCMA, speex, gsm
 220  * Existing Public plugins:
 221  *    iLBC
 222  *
 223  * @param mime    A string indicating the codec.
 224  *
 225  * Returns: a MSFilter if successfull, NULL otherwise.
 226  */
 227 MSFilter * ms_filter_create_encoder(const char *mime);
 228
 229 /**
 230  * Create decoder filter according to codec name.
 231  *
 232  * Internal supported codecs:
 233  *    PCMU, PCMA, speex, gsm
 234  * Existing Public plugins:
 235  *    iLBC
 236  *
 237  * @param mime    A string indicating the codec.
 238  *
 239  * Returns: a MSFilter if successfull, NULL otherwise.
 240  */
 241 MSFilter * ms_filter_create_decoder(const char *mime);
 242
 243 /**
 244  * Check if a encode or decode filter exists for a codec name.
 245  *
 246  * Internal supported codecs:
 247  *    PCMU, PCMA, speex, gsm
 248  * Existing Public plugins:
 249  *    iLBC
 250  *
 251  * @param mime    A string indicating the codec.
 252  *
 253  * Returns: TRUE if successfull, FALSE otherwise.
 254  */
 255 bool_t ms_filter_codec_supported(const char *mime);
 256
 257 /**
 258  * Create decoder filter according to a filter's MSFilterId.
 259  *
 260  * @param id     A MSFilterId identifier for the filter.
 261  *
 262  * Returns: a MSFilter if successfull, NULL otherwise.
 263  */
 264 MSFilter *ms_filter_new(MSFilterId id);
 265
 266 /**
 267  * Create decoder filter according to a filter's name.
 268  *
 269  * @param name   A name for the filter.
 270  *
 271  * Returns: a MSFilter if successfull, NULL otherwise.
 272  */
 273 MSFilter *ms_filter_new_from_name(const char *name);
 274
 275 /**
 276  * Create decoder filter according to a filter's description.
 277  *
 278  * The primary use is to create your own filter's in your
 279  * application and avoid registration inside mediastreamer2.
 280  *
 281  * @param desc   A MSFilterDesc for the filter.
 282  *
 283  * Returns: a MSFilter if successfull, NULL otherwise.
 284  */
 285 MSFilter *ms_filter_new_from_desc(MSFilterDesc *desc);
 286
 287 /**
 288  * Link one OUTPUT pin from a filter to an INPUT pin of another filter.
 289  *
 290  * All data coming from the OUTPUT pin of one filter will be distributed
 291  * to the INPUT pin of the second filter.
 292  *
 293  * @param f1   A MSFilter object containing the OUTPUT pin
 294  * @param pin1 An index of an OUTPUT pin.
 295  * @param f2   A MSFilter object containing the INPUT pin
 296  * @param pin2 An index of an INPUT pin.
 297  *
 298  * Returns: 0 if sucessful, -1 otherwise.
 299  */
 300 int ms_filter_link(MSFilter *f1, int pin1, MSFilter *f2, int pin2);
 301
 302 /**
 303  * Unlink one OUTPUT pin from a filter to an INPUT pin of another filter.
 304  *
 305  * @param f1   A MSFilter object containing the OUTPUT pin
 306  * @param pin1 An index of an OUTPUT pin.
 307  * @param f2   A MSFilter object containing the INPUT pin
 308  * @param pin2 An index of an INPUT pin.
 309  *
 310  * Returns: 0 if sucessful, -1 otherwise.
 311  */
 312 int ms_filter_unlink(MSFilter *f1, int pin1, MSFilter *f2, int pin2);
 313
 314 /**
 315  * Call a filter's method to set or get options.
 316  *
 317  * @param f    A MSFilter object.
 318  * @param id   A private filter ID for the option.
 319  * @param arg  A private user data for the filter.
 320  *
 321  * Returns: 0 if successfull, -1 otherwise.
 322  */
 323 int ms_filter_call_method(MSFilter *f, unsigned int id, void *arg);
 324
 325 /**
 326  * Call a filter's method to set options.
 327  *
 328  * @param f    A MSFilter object.
 329  * @param id   A private filter ID for the option.
 330  *
 331  * Returns: 0 if successfull, -1 otherwise.
 332  */
 333 int ms_filter_call_method_noarg(MSFilter *f, unsigned int id);
 334
 335 /**
 336  * Set a callback on filter's to be informed of private filter's event.
 337  *
 338  * @param f        A MSFilter object.
 339  * @param fn       A MSFilterNotifyFunc that will be called.
 340  * @param userdata A pointer to private data.
 341  *
 342  * Returns: 0 if successfull, -1 otherwise.
 343  */
 344 void ms_filter_set_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata);
 345
 346 /**
 347  * Get MSFilterId's filter.
 348  *
 349  * @param f        A MSFilter object.
 350  *
 351  * Returns: MSFilterId if successfull, -1 otherwise.
 352  */
 353 MSFilterId ms_filter_get_id(MSFilter *f);
 354
 355
 356 /**
 357  * Obtain the list of current filter's neighbours, ie filters that are part of same graph.
 358  *
 359  * Returns: a MSList of MSFilter, that needs to be freed by the caller when no more needed.
 360 **/
 361 MSList * ms_filter_find_neighbours(MSFilter *me);
 362
 363 /**
 364  * Destroy a filter object.
 365  *
 366  * @param f        A MSFilter object.
 367  *
 368  */
 369 void ms_filter_destroy(MSFilter *f);
 370
 371 /**
 372  * Initialize a MSConnectionHelper.
 373  *
 374  * @param h A MSConnectionHelper, usually (but not necessarily) on stack
 375  *
 376 **/
 377 void ms_connection_helper_start(MSConnectionHelper *h);
 378
 379 /**
 380  * \brief Enter a MSFilter to be connected into the MSConnectionHelper object.
 381  *
 382  * This functions enters a MSFilter to be connected into the MSConnectionHelper
 383  * object and connects it to the last entered if not the first one.
 384  * The MSConnectionHelper is useful to reduce the amount of code necessary to create graphs in case
 385  * the connections are made in an ordered manner and some filters are present conditionally in graphs.
 386  * For example, instead of writing
 387  * \code
 388  * ms_filter_link(f1,0,f2,1);
 389  * ms_filter_link(f2,0,f3,0);
 390  * ms_filter_link(f3,1,f4,0);
 391  * \endcode
 392  * You can write:
 393  * \code
 394  * MSConnectionHelper h;
 395  * ms_connection_helper_start(&h);
 396  * ms_connection_helper_link(&h,f1,-1,0);
 397  * ms_connection_helper_link(&h,f2,1,0);
 398  * ms_connection_helper_link(&h,f3,0,1);
 399  * ms_connection_helper_link(&h,f4,0,-1);
 400  * \endcode
 401  * Which is a bit longer to write here, but now imagine f2 needs to be present in the graph only
 402  * in certain conditions: in the first case you have rewrite the two first lines, in the second case
 403  * you just need to replace the fourth line by:
 404  * \code
 405  * if (my_condition) ms_connection_helper_link(&h,f2,1,0);
 406  * \endcode
 407  *
 408  * @param h a connection helper
 409  * @param f a MSFilter
 410  * @param inpin an input pin number with which the MSFilter needs to connect to previously entered MSFilter
 411  * @param outpin an output pin number with which the MSFilter needs to be connected to the next entered MSFilter
 412  *
 413  * Returns: the return value of ms_filter_link() that is called internally to this function.
 414 **/
 415 int ms_connection_helper_link(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin);
 416
 417
 418 /**
 419  * \brief Enter a MSFilter to be disconnected into the MSConnectionHelper object.
 420  * Process exactly the same way as ms_connection_helper_link() but calls ms_filter_unlink() on the
 421  * entered filters.
 422 **/
 423 int ms_connection_helper_unlink(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin);
 424
 425 /* I define the id taking the lower bits of the address of the MSFilterDesc object,
 426 the method index (_cnt_) and the argument size */
 427 /* I hope using this to avoid type mismatch (calling a method on the wrong filter)*/
 428 #define MS_FILTER_METHOD_ID(_id_,_cnt_,_argsize_) \
 429         (  (((unsigned long)(_id_)) & 0xFFFF)<<16 | (_cnt_<<8) | (_argsize_ & 0xFF ))
 430
 431 #define MS_FILTER_METHOD(_id_,_count_,_argtype_) \
 432         MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_))
 433
 434 #define MS_FILTER_METHOD_NO_ARG(_id_,_count_) \
 435         MS_FILTER_METHOD_ID(_id_,_count_,0)
 436
 437
 438 #define MS_FILTER_BASE_METHOD(_count_,_argtype_) \
 439         MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,sizeof(_argtype_))
 440
 441 #define MS_FILTER_BASE_METHOD_NO_ARG(_count_) \
 442         MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,0)
 443
 444 #define MS_FILTER_EVENT(_id_,_count_,_argtype_) \
 445         MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_))
 446
 447 #define MS_FILTER_EVENT_NO_ARG(_id_,_count_)\
 448         MS_FILTER_METHOD_ID(_id_,_count_,0)
 449
 450 /* some MSFilter base generic methods:*/
 451 #define MS_FILTER_SET_SAMPLE_RATE       MS_FILTER_BASE_METHOD(0,int)
 452 #define MS_FILTER_GET_SAMPLE_RATE       MS_FILTER_BASE_METHOD(1,int)
 453 #define MS_FILTER_SET_BITRATE           MS_FILTER_BASE_METHOD(2,int)
 454 #define MS_FILTER_GET_BITRATE           MS_FILTER_BASE_METHOD(3,int)
 455 #define MS_FILTER_GET_NCHANNELS         MS_FILTER_BASE_METHOD(5,int)
 456 #define MS_FILTER_SET_NCHANNELS         MS_FILTER_BASE_METHOD(6,int)
 457 #define MS_FILTER_ADD_FMTP              MS_FILTER_BASE_METHOD(7,const char)
 458 #define MS_FILTER_ADD_ATTR              MS_FILTER_BASE_METHOD(8,const char)
 459 #define MS_FILTER_SET_MTU               MS_FILTER_BASE_METHOD(9,int)
 460 #define MS_FILTER_GET_MTU               MS_FILTER_BASE_METHOD(10,int)
 461
 462
 463 /* more specific methods: to be moved into implementation specific header files*/
 464 #define MS_FILTER_SET_FRAMESIZE         MS_FILTER_BASE_METHOD(11,int)
 465 #define MS_FILTER_SET_FILTERLENGTH      MS_FILTER_BASE_METHOD(12,int)
 466 #define MS_FILTER_SET_OUTPUT_SAMPLE_RATE MS_FILTER_BASE_METHOD(13,int)
 467 #define MS_FILTER_ENABLE_DIRECTMODE     MS_FILTER_BASE_METHOD(14,int)
 468 #define MS_FILTER_ENABLE_VAD            MS_FILTER_BASE_METHOD(15,int)
 469 #define MS_FILTER_GET_STAT_DISCARDED    MS_FILTER_BASE_METHOD(16,int)
 470 #define MS_FILTER_GET_STAT_MISSED       MS_FILTER_BASE_METHOD(17,int)
 471 #define MS_FILTER_GET_STAT_INPUT        MS_FILTER_BASE_METHOD(18,int)
 472 #define MS_FILTER_GET_STAT_OUTPUT       MS_FILTER_BASE_METHOD(19,int)
 473 #define MS_FILTER_ENABLE_AGC            MS_FILTER_BASE_METHOD(20,int)
 474 #define MS_FILTER_SET_PLAYBACKDELAY MS_FILTER_BASE_METHOD(21,int)
 475 #define MS_FILTER_ENABLE_HALFDUPLEX MS_FILTER_BASE_METHOD(22,int)
 476 #define MS_FILTER_SET_VAD_PROB_START MS_FILTER_BASE_METHOD(23,int)
 477 #define MS_FILTER_SET_VAD_PROB_CONTINUE MS_FILTER_BASE_METHOD(24,int)
 478 #define MS_FILTER_SET_MAX_GAIN  MS_FILTER_BASE_METHOD(25,int)
 479
 480 #define MS_CONF_SPEEX_PREPROCESS_MIC    MS_FILTER_EVENT(MS_CONF_ID, 1, void*)
 481 #define MS_CONF_CHANNEL_VOLUME  MS_FILTER_EVENT(MS_CONF_ID, 3, void*)
 482
 483 #define MS_SPEEX_EC_PREPROCESS_MIC      MS_FILTER_EVENT(MS_SPEEX_EC_ID, 1, void*)
 484 #define MS_SPEEX_EC_ECHO_STATE  MS_FILTER_EVENT(MS_SPEEX_EC_ID, 2, void*)
 485 /** @} */
 486
 487 /*private methods*/
 488 void ms_filter_process(MSFilter *f);
 489 void ms_filter_preprocess(MSFilter *f, struct _MSTicker *t);
 490 void ms_filter_postprocess(MSFilter *f);
 491 bool_t ms_filter_inputs_have_data(MSFilter *f);
 492 void ms_filter_notify(MSFilter *f, unsigned int id, void *arg);
 493 void ms_filter_notify_no_arg(MSFilter *f, unsigned int id);
 494 #define ms_filter_lock(f)       ms_mutex_lock(&(f)->lock)
 495 #define ms_filter_unlock(f)     ms_mutex_unlock(&(f)->lock)
 496 void ms_filter_unregister_all(void);
 497
 498 #ifdef __cplusplus
 499 }
 500 #endif
 501
 502 /* used by awk script in Makefile.am to generate alldescs.c */
 503 #define MS_FILTER_DESC_EXPORT(desc)
 504
 505 /* xgettext markup */
 506 #define N_(String) String
 507
 508 #endif