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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 */ 19 20 #ifndef msfilter_h 21 #define msfilter_h 22 23 #include "mediastreamer2/mscommon.h" 24 #include "mediastreamer2/msqueue.h" 25 #include "mediastreamer2/allfilters.h" 26 #include "mediastreamer2/formats.h" 27 28 /** 29 * @file msfilter.h 30 * @brief mediastreamer2 msfilter.h include file 31 * 32 * This file provide the API needed to create, link, 33 * unlink, find and destroy filter. 34 * 35 * It also provides definitions if you wish to implement 36 * your own filters. 37 * 38 */ 39 40 /** 41 * @addtogroup mediastreamer2_filter 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, struct _MSFilter *f, unsigned int id, void *arg); 62 63 struct _MSFilterMethod{ 64 unsigned int id; 65 MSFilterMethodFunc method; 66 }; 67 68 69 /** 70 * Interface IDs, used to generate method names (see MS_FILTER_METHOD macro). 71 * The purpose of these interfaces is to allow different filter implementations to share the same methods, by implementing the method definitions for these interfaces. 72 * 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, 73 * each implementation can just implement the MS_VIDEO_ENCODER_REQ_VFU method of the MSFilterVideoEncoderInterface. 74 **/ 75 enum _MSFilterInterfaceId{ 76 MSFilterInterfaceBegin=16384, 77 MSFilterPlayerInterface, /**<Player interface, used to control playing of files.*/ 78 MSFilterRecorderInterface,/**<Recorder interface, used to control recording of stream into files.*/ 79 MSFilterVideoDisplayInterface,/**<Video display interface, used to control the rendering of raw pictures onscreen.*/ 80 MSFilterEchoCancellerInterface,/**Echo canceller interface, used to control echo canceller implementations.*/ 81 MSFilterVideoDecoderInterface,/**<Video decoder interface*/ 82 MSFilterVideoCaptureInterface,/**<Video capture interface*/ 83 MSFilterAudioDecoderInterface,/**<Audio Decoder interface*/ 84 MSFilterVideoEncoderInterface,/**<Video encoder interface*/ 85 MSFilterAudioCaptureInterface,/**<Interface for audio capture filters*/ 86 MSFilterAudioPlaybackInterface,/**Interface for audio playback filters.*/ 87 MSFilterAudioEncoderInterface,/**<Video encoder interface*/ 88 MSFilterVoidInterface,/**<Void source/sink interface*/ 89 }; 90 91 /** 92 * Interface IDs, used to generate method names (see MS_FILTER_METHOD macro). 93 * 94 **/ 95 typedef enum _MSFilterInterfaceId MSFilterInterfaceId; 96 97 /** 98 * Structure for holding filter's methods to set filter's options. 99 * @var MSFilterMethod 100 */ 101 typedef struct _MSFilterMethod MSFilterMethod; 102 /** 103 * Filter's category 104 * 105 */ 106 enum _MSFilterCategory{ 107 /**others*/ 108 MS_FILTER_OTHER, 109 /**used by encoders*/ 110 MS_FILTER_ENCODER, 111 /**used by decoders*/ 112 MS_FILTER_DECODER, 113 /**used by capture filters that perform encoding*/ 114 MS_FILTER_ENCODING_CAPTURER, 115 /**used by filters that perform decoding and rendering */ 116 MS_FILTER_DECODER_RENDERER 117 }; 118 119 /** 120 * Structure to describe filter's category. 121 * <PRE> 122 * MS_FILTER_OTHER 123 * MS_FILTER_ENCODER 124 * MS_FILTER_DECODER 125 * MS_FILTER_ENCODING_CAPTURER 126 * MS_FILTER_DECODING_RENDERER 127 * </PRE> 128 * @var MSFilterCategory 129 */ 130 typedef enum _MSFilterCategory MSFilterCategory; 131 132 /** 133 * Filter's flags controlling special behaviours. 134 **/ 135 enum _MSFilterFlags{ 136 MS_FILTER_IS_PUMP = 1, /**< The filter must be called in process function every tick.*/ 137 /*...*/ 138 /*private flags: don't use it in filters.*/ 139 MS_FILTER_IS_ENABLED = 1<<31 /*<Flag to specify if a filter is enabled or not. Only enabled filters are returned by function ms_filter_get_encoder */ 140 }; 141 142 /** 143 * Filter's flags controlling special behaviours. 144 **/ 145 typedef enum _MSFilterFlags MSFilterFlags; 146 147 148 struct _MSFilterStats{ 149 const char *name; /*<filter name*/ 150 uint64_t elapsed; /*<cumulative number of nanoseconds elapsed */ 151 unsigned int count; /*<number of time the filter is called for processing*/ 152 }; 153 154 typedef struct _MSFilterStats MSFilterStats; 155 156 struct _MSFilterDesc{ 157 MSFilterId id; /**< the id declared in allfilters.h */ 158 const char *name; /**< the filter name*/ 159 const char *text; /**< short text describing the filter's function*/ 160 MSFilterCategory category; /**< filter's category*/ 161 const char *enc_fmt; /**< sub-mime of the format, must be set if category is MS_FILTER_ENCODER or MS_FILTER_DECODER */ 162 int ninputs; /**< number of inputs */ 163 int noutputs; /**< number of outputs */ 164 MSFilterFunc init; /**< Filter's init function*/ 165 MSFilterFunc preprocess; /**< Filter's preprocess function, called one time before starting to process*/ 166 MSFilterFunc process; /**< Filter's process function, called every tick by the MSTicker to do the filter's job*/ 167 MSFilterFunc postprocess; /**< Filter's postprocess function, called once after processing (the filter is no longer called in process() after)*/ 168 MSFilterFunc uninit; /**< Filter's uninit function, used to deallocate internal structures*/ 169 MSFilterMethod *methods; /**<Filter's method table*/ 170 unsigned int flags; /**<Filter's special flags, from the MSFilterFlags enum.*/ 171 }; 172 173 /** 174 * Structure for filter's description. 175 * @var MSFilterDesc 176 */ 177 typedef struct _MSFilterDesc MSFilterDesc; 178 179 struct _MSFilter{ 180 MSFilterDesc *desc; /**<Back pointer to filter's descriptor.*/ 181 /*protected attributes, do not move or suppress any of them otherwise plugins will be broken */ 182 ms_mutex_t lock; 183 MSQueue **inputs; /**<Table of input queues.*/ 184 MSQueue **outputs;/**<Table of output queues */ 185 struct _MSFactory *factory;/**<the factory that created this filter*/ 186 void *padding; /**Unused - to be reused later when new protected fields have to added*/ 187 void *data; /**< Pointer used by the filter for internal state and computations.*/ 188 struct _MSTicker *ticker; /**<Pointer to the ticker object. It is not NULL when being called process()*/ 189 /*private attributes, they can be moved and changed at any time*/ 190 MSList *notify_callbacks; 191 uint32_t last_tick; 192 MSFilterStats *stats; 193 int postponed_task; /*number of postponed tasks*/ 194 bool_t seen; 195 }; 196 197 198 /** 199 * Structure of filter's object. 200 * @var MSFilter 201 */ 202 typedef struct _MSFilter MSFilter; 203 204 struct _MSConnectionPoint{ 205 MSFilter *filter; /**<Pointer to filter*/ 206 int pin; /**<Pin index on the filter*/ 207 }; 208 209 /** 210 * Structure that represents a connection point of a MSFilter 211 * @var MSConnectionPoint 212 */ 213 typedef struct _MSConnectionPoint MSConnectionPoint; 214 215 struct _MSConnectionHelper{ 216 MSConnectionPoint last; 217 }; 218 219 /** 220 * Structure that holds data when using the ms_connection_helper_* functions. 221 * @var MSConnectionHelper 222 **/ 223 typedef struct _MSConnectionHelper MSConnectionHelper; 224 225 226 #ifdef __cplusplus 227 extern "C"{ 228 #endif 229 230 /** 231 * Register a filter description. (plugins use only!) 232 * 233 * When you build your own plugin, this method will 234 * add the encoder or decoder to the internal list 235 * of supported codec. Then, this plugin can be used 236 * transparently from the application. 237 * 238 * ms_filter_get_encoder, ms_filter_get_decoder, 239 * ms_filter_create_encoder, ms_filter_create_decoder 240 * and ms_filter_codec_supported 241 * can then be used as if the codec was internally. 242 * supported. 243 * 244 * @param desc a filter description. 245 * @deprecated use ms_factory_register_filter(). 246 */ 247 MS2_PUBLIC MS2_DEPRECATED void ms_filter_register(MSFilterDesc *desc); 248 249 250 251 /** 252 * Retrieve capture filter that supports encoding to codec name. 253 * 254 * @param mime A string indicating the codec. 255 * 256 * @return a MSFilterDesc if successfull, NULL otherwise. 257 * @deprecated use ms_factory_get_encoding_capturer(). 258 */ 259 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoding_capturer(const char *mime); 260 261 /** 262 * Retrieve render filter that supports decoding to codec name. 263 * 264 * @param mime A string indicating the codec. 265 * 266 * @returns a MSFilterDesc if successfull, NULL otherwise. 267 * @deprecated use ms_factory_get_decoding_renderer() 268 */ 269 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoding_renderer(const char *mime); 270 271 /** 272 * Retrieve encoders according to codec name. 273 * 274 * 275 * @param mime A string indicating the codec. 276 * 277 * @return a MSFilterDesc if successfull, NULL otherwise. 278 * @deprecated use ms_factory_get_encoder(). 279 */ 280 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoder(const char *mime); 281 282 /** 283 * Retrieve decoders according to codec name. 284 * 285 * 286 * @param mime A string indicating the codec. 287 * 288 * @return a MSFilterDesc if successfull, NULL otherwise. 289 * @deprecated use ms_factory_get_decoder(). 290 */ 291 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoder(const char *mime); 292 293 /** 294 * Lookup a mediastreamer2 filter using its name. 295 * If found, the descriptor (MSFilterDesc) is returned. 296 * This descriptor can be used to instanciate the filter using ms_filter_new_from_desc() 297 * This function can be useful to query the presence of a filter loaded as a plugin, for example. 298 * 299 * @param filter_name The filter name. 300 * @return a MSFilterDesc or NULL if no match. 301 * @deprecated use ms_factory_lookup_filter_by_name(). 302 **/ 303 MS2_PUBLIC MS2_DEPRECATED MSFilterDesc *ms_filter_lookup_by_name(const char *filter_name); 304 305 /** 306 * Returns a list of filter descriptions implementing a given interface. 307 * The list itself must be freed by the caller of this function, but not the MSFilterDesc pointed by the list elements. 308 * @param id a filter interface id 309 * @return a newly allocated MSList of #MSFilterDesc. 310 * @deprecated use ms_factory_lookup_filter_by_interface(). 311 **/ 312 MS2_PUBLIC MS2_DEPRECATED MSList *ms_filter_lookup_by_interface(MSFilterInterfaceId id); 313 314 /** 315 * Create encoder filter according to codec name. 316 317 * @param mime A string indicating the codec. 318 * 319 * @return a MSFilter if successfull, NULL otherwise. 320 * @deprecated use ms_factory_create_encoder(). 321 */ 322 MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_encoder(const char *mime); 323 324 /** 325 * Create decoder filter according to codec name. 326 * 327 * 328 * @param mime A string indicating the codec. 329 * 330 * @return a MSFilter if successfull, NULL otherwise. 331 * @deprecated use ms_factory_create_decoder(). 332 */ 333 MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_decoder(const char *mime); 334 335 /** 336 * Check if both an encoder and a decoder filter exists for a codec name. 337 * 338 * @param mime A string indicating the codec. 339 * 340 * @return TRUE if successfull, FALSE otherwise. 341 * @deprecated use ms_factory_codec_supported(). 342 */ 343 MS2_PUBLIC MS2_DEPRECATED bool_t ms_filter_codec_supported(const char *mime); 344 345 /** 346 * Create decoder filter according to a filter's MSFilterId. 347 * 348 * @param id A MSFilterId identifier for the filter. 349 * 350 * @returns a MSFilter if successfull, NULL otherwise. 351 * @deprecated use ms_factory_create_filter(). 352 */ 353 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new(MSFilterId id); 354 355 /** 356 * Create decoder filter according to a filter's name. 357 * 358 * @param name A name for the filter. 359 * 360 * @return a MSFilter if successfull, NULL otherwise. 361 * @deprecated use ms_factory_create_filter_from_name(). 362 */ 363 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_name(const char *name); 364 365 /** 366 * Create decoder filter according to a filter's description. 367 * 368 * The primary use is to create your own filter's in your 369 * application and avoid registration inside mediastreamer2. 370 * 371 * @param desc A MSFilterDesc for the filter. 372 * 373 * @return a MSFilter if successfull, NULL otherwise. 374 * @deprecated use ms_factory_create_filter_from_desc() 375 */ 376 MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_desc(MSFilterDesc *desc); 377 378 /** 379 * Link one OUTPUT pin from a filter to an INPUT pin of another filter. 380 * 381 * All data coming from the OUTPUT pin of one filter will be distributed 382 * to the INPUT pin of the second filter. 383 * 384 * @param f1 A MSFilter object containing the OUTPUT pin 385 * @param pin1 An index of an OUTPUT pin. 386 * @param f2 A MSFilter object containing the INPUT pin 387 * @param pin2 An index of an INPUT pin. 388 * 389 * Returns: 0 if sucessful, -1 otherwise. 390 */ 391 MS2_PUBLIC int ms_filter_link(MSFilter *f1, int pin1, MSFilter *f2, int pin2); 392 393 /** 394 * Unlink one OUTPUT pin from a filter to an INPUT pin of another filter. 395 * 396 * @param f1 A MSFilter object containing the OUTPUT pin 397 * @param pin1 An index of an OUTPUT pin. 398 * @param f2 A MSFilter object containing the INPUT pin 399 * @param pin2 An index of an INPUT pin. 400 * 401 * Returns: 0 if sucessful, -1 otherwise. 402 */ 403 MS2_PUBLIC int ms_filter_unlink(MSFilter *f1, int pin1, MSFilter *f2, int pin2); 404 405 /** 406 * Call a filter's method to set or get options. 407 * 408 * @param f A MSFilter object. 409 * @param id A private filter ID for the option. 410 * @param arg A private user data for the filter. 411 * 412 * Returns: 0 if successfull, -1 otherwise. 413 */ 414 MS2_PUBLIC int ms_filter_call_method(MSFilter *f, unsigned int id, void *arg); 415 416 /** 417 * Call a filter's method to set options. 418 * 419 * @param f A MSFilter object. 420 * @param id A method ID. 421 * 422 * Returns: 0 if successfull, -1 otherwise. 423 */ 424 MS2_PUBLIC int ms_filter_call_method_noarg(MSFilter *f, unsigned int id); 425 426 427 /** 428 * Returns whether the filter implements a given method 429 * 430 * @param f A MSFilter object. 431 * @param id A method ID. 432 * 433 * Returns: TRUE if method is implemented, FALSE otherwise. 434 */ 435 MS2_PUBLIC bool_t ms_filter_has_method(MSFilter *f, unsigned int id); 436 437 /** 438 * Returns whether a filter implements a given interface. 439 * @param f a MSFilter object 440 * @param id an interface id. 441 * 442 * Returns TRUE if interface is implemented, FALSE, otherwise. 443 **/ 444 MS2_PUBLIC bool_t ms_filter_implements_interface(MSFilter *f, MSFilterInterfaceId id); 445 446 /** 447 * Returns whether a filter implements a given interface, based on the filter's descriptor. 448 * @param f a MSFilter object 449 * @param id an interface id. 450 * 451 * Returns TRUE if interface is implemented, FALSE, otherwise. 452 **/ 453 MS2_PUBLIC bool_t ms_filter_desc_implements_interface(MSFilterDesc *desc, MSFilterInterfaceId id); 454 455 456 /** 457 * Set a callback on filter's to be informed of private filter's event. 458 * This callback is called from the filter's MSTicker, unless a global event queue 459 * is created to receive all filter's notification or synchronous flag is TRUE. 460 * See ms_event_queue_new() for details. 461 * 462 * @param f A MSFilter object. 463 * @param fn A MSFilterNotifyFunc that will be called. 464 * @param userdata A pointer to private data. 465 * @param synchronous boolean that indicates whether this callback must be called synchronously. 466 * 467 */ 468 MS2_PUBLIC void ms_filter_add_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata, bool_t synchronous); 469 470 /** 471 * Remove a notify callback previously entered with ms_filter_add_notify_callback() 472 * 473 * @param f A MSFilter object. 474 * @param fn A MSFilterNotifyFunc that will be called. 475 * @param userdata A pointer to private data. 476 * 477 */ 478 MS2_PUBLIC void ms_filter_remove_notify_callback(MSFilter *f, MSFilterNotifyFunc fn, void *userdata); 479 480 /** 481 * Get MSFilterId's filter. 482 * 483 * @param f A MSFilter object. 484 * 485 * Returns: MSFilterId if successfull, -1 otherwise. 486 */ 487 MS2_PUBLIC MSFilterId ms_filter_get_id(MSFilter *f); 488 489 /** 490 * Get filter's name. 491 * @param[in] f #MSFilter object 492 * @return The name of the filter. 493 */ 494 MS2_PUBLIC const char * ms_filter_get_name(MSFilter *f); 495 496 497 /** 498 * Obtain the list of current filter's neighbours, ie filters that are part of same graph. 499 * 500 * Returns: a MSList of MSFilter, that needs to be freed by the caller when no more needed. 501 **/ 502 MS2_PUBLIC MSList * ms_filter_find_neighbours(MSFilter *me); 503 504 /** 505 * Destroy a filter object. 506 * 507 * @param f A MSFilter object. 508 * 509 */ 510 MS2_PUBLIC void ms_filter_destroy(MSFilter *f); 511 512 /** 513 * Initialize a MSConnectionHelper. 514 * 515 * @param h A MSConnectionHelper, usually (but not necessarily) on stack 516 * 517 **/ 518 MS2_PUBLIC void ms_connection_helper_start(MSConnectionHelper *h); 519 520 /** 521 * \brief Enter a MSFilter to be connected into the MSConnectionHelper object. 522 * 523 * This functions enters a MSFilter to be connected into the MSConnectionHelper 524 * object and connects it to the last entered if not the first one. 525 * The MSConnectionHelper is useful to reduce the amount of code necessary to create graphs in case 526 * the connections are made in an ordered manner and some filters are present conditionally in graphs. 527 * For example, instead of writing 528 * \code 529 * ms_filter_link(f1,0,f2,1); 530 * ms_filter_link(f2,0,f3,0); 531 * ms_filter_link(f3,1,f4,0); 532 * \endcode 533 * You can write: 534 * \code 535 * MSConnectionHelper h; 536 * ms_connection_helper_start(&h); 537 * ms_connection_helper_link(&h,f1,-1,0); 538 * ms_connection_helper_link(&h,f2,1,0); 539 * ms_connection_helper_link(&h,f3,0,1); 540 * ms_connection_helper_link(&h,f4,0,-1); 541 * \endcode 542 * Which is a bit longer to write here, but now imagine f2 needs to be present in the graph only 543 * in certain conditions: in the first case you have rewrite the two first lines, in the second case 544 * you just need to replace the fourth line by: 545 * \code 546 * if (my_condition) ms_connection_helper_link(&h,f2,1,0); 547 * \endcode 548 * 549 * @param h a connection helper 550 * @param f a MSFilter 551 * @param inpin an input pin number with which the MSFilter needs to connect to previously entered MSFilter 552 * @param outpin an output pin number with which the MSFilter needs to be connected to the next entered MSFilter 553 * 554 * Returns: the return value of ms_filter_link() that is called internally to this function. 555 **/ 556 MS2_PUBLIC int ms_connection_helper_link(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin); 557 558 559 /** 560 * \brief Enter a MSFilter to be disconnected into the MSConnectionHelper object. 561 * Process exactly the same way as ms_connection_helper_link() but calls ms_filter_unlink() on the 562 * entered filters. 563 **/ 564 MS2_PUBLIC int ms_connection_helper_unlink(MSConnectionHelper *h, MSFilter *f, int inpin, int outpin); 565 566 567 /** 568 * \brief Enable processing time measurements statistics for filters. 569 * 570 **/ 571 MS2_PUBLIC MS2_DEPRECATED void ms_filter_enable_statistics(bool_t enabled); 572 573 574 /** 575 * \brief Reset processing time statistics for filters. 576 * 577 **/ 578 MS2_PUBLIC MS2_DEPRECATED void ms_filter_reset_statistics(void); 579 580 /** 581 * \brief Retrieves statistics for running filters. 582 * Returns a list of MSFilterStats 583 **/ 584 MS2_PUBLIC MS2_DEPRECATED const MSList * ms_filter_get_statistics(void); 585 586 /** 587 * \brief Logs runtime statistics for running filters. 588 * 589 **/ 590 MS2_PUBLIC MS2_DEPRECATED void ms_filter_log_statistics(void); 591 592 593 594 595 /* I define the id taking the lower bits of the address of the MSFilterDesc object, 596 the method index (_cnt_) and the argument size */ 597 /* I hope using this to avoid type mismatch (calling a method on the wrong filter)*/ 598 #define MS_FILTER_METHOD_ID(_id_,_cnt_,_argsize_) \ 599 ( (((unsigned long)(_id_)) & 0xFFFF)<<16 | (_cnt_<<8) | (_argsize_ & 0xFF )) 600 601 /** 602 * Macro to create a method id, unique per filter. 603 * First argument shall be the filter's ID (MSFilterId) or interface ID (MSFilterInterfaceId). 604 * Second argument is the method index within the context of the filter. It should start from 0 and increment for each new method. 605 * Third argument is the argument type of the method, for example "int", "float" or any structure. 606 **/ 607 #define MS_FILTER_METHOD(_id_,_count_,_argtype_) \ 608 MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_)) 609 610 /** 611 * Same as MS_FILTER_METHOD, but for method that do not take any argument. 612 **/ 613 #define MS_FILTER_METHOD_NO_ARG(_id_,_count_) \ 614 MS_FILTER_METHOD_ID(_id_,_count_,0) 615 616 617 #define MS_FILTER_BASE_METHOD(_count_,_argtype_) \ 618 MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,sizeof(_argtype_)) 619 620 #define MS_FILTER_BASE_METHOD_NO_ARG(_count_) \ 621 MS_FILTER_METHOD_ID(MS_FILTER_BASE_ID,_count_,0) 622 623 #define MS_FILTER_EVENT(_id_,_count_,_argtype_) \ 624 MS_FILTER_METHOD_ID(_id_,_count_,sizeof(_argtype_)) 625 626 #define MS_FILTER_EVENT_NO_ARG(_id_,_count_)\ 627 MS_FILTER_METHOD_ID(_id_,_count_,0) 628 629 630 #define MS_FILTER_BASE_EVENT(_count_,_argtype_) \ 631 MS_FILTER_EVENT(MS_FILTER_BASE_ID,_count_,_argtype_) 632 633 #define MS_FILTER_BASE_EVENT_NO_ARG(_count_) \ 634 MS_FILTER_EVENT_NO_ARG(MS_FILTER_BASE_ID,_count_) 635 636 /** 637 * some MSFilter base generic methods: 638 **/ 639 /** 640 * Set filter output/input sampling frequency in hertz 641 */ 642 #define MS_FILTER_SET_SAMPLE_RATE MS_FILTER_BASE_METHOD(0,int) 643 /** 644 * Get filter output/input sampling frequency in hertz 645 */ 646 647 #define MS_FILTER_GET_SAMPLE_RATE MS_FILTER_BASE_METHOD(1,int) 648 /** 649 * Set filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead 650 */ 651 #define MS_FILTER_SET_BITRATE MS_FILTER_BASE_METHOD(2,int) 652 /** 653 * Get filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead 654 */ 655 #define MS_FILTER_GET_BITRATE MS_FILTER_BASE_METHOD(3,int) 656 #define MS_FILTER_GET_NCHANNELS MS_FILTER_BASE_METHOD(5,int) 657 #define MS_FILTER_SET_NCHANNELS MS_FILTER_BASE_METHOD(6,int) 658 /** 659 * Set codec dependent attributes as taken from the SDP 660 */ 661 #define MS_FILTER_ADD_FMTP MS_FILTER_BASE_METHOD(7,const char) 662 663 #define MS_FILTER_ADD_ATTR MS_FILTER_BASE_METHOD(8,const char) 664 #define MS_FILTER_SET_MTU MS_FILTER_BASE_METHOD(9,int) 665 #define MS_FILTER_GET_MTU MS_FILTER_BASE_METHOD(10,int) 666 /**Filters can return their latency in milliseconds (if known) using this method:*/ 667 #define MS_FILTER_GET_LATENCY MS_FILTER_BASE_METHOD(11,int) 668 669 typedef struct _MSPinFormat{ 670 uint16_t pin; 671 const MSFmtDescriptor *fmt; 672 }MSPinFormat; 673 674 /** 675 * Obtain the format of a filter on a given input 676 */ 677 #define MS_FILTER_GET_INPUT_FMT MS_FILTER_BASE_METHOD(30,MSPinFormat) 678 /** 679 * Set the format of a filter on a given input 680 */ 681 #define MS_FILTER_SET_INPUT_FMT MS_FILTER_BASE_METHOD(31,MSPinFormat) 682 /** 683 * Obtain the format of a filter on a given output 684 */ 685 #define MS_FILTER_GET_OUTPUT_FMT MS_FILTER_BASE_METHOD(32,MSPinFormat) 686 /** 687 * Set the format of a filter on a given output 688 */ 689 #define MS_FILTER_SET_OUTPUT_FMT MS_FILTER_BASE_METHOD(33,MSPinFormat) 690 691 692 /** 693 * MSFilter generic events 694 **/ 695 #define MS_FILTER_OUTPUT_FMT_CHANGED MS_FILTER_BASE_EVENT_NO_ARG(0) /**<triggered whenever a filter decides to change its output format for one or more more output pins*/ 696 697 698 /* DEPRECATED specific methods: to be moved into implementation specific header files - DO NOT USE IN NEW CODE*/ 699 #define MS_FILTER_SET_FILTERLENGTH MS_FILTER_BASE_METHOD(12,int) 700 #define MS_FILTER_SET_OUTPUT_SAMPLE_RATE MS_FILTER_BASE_METHOD(13,int) 701 #define MS_FILTER_ENABLE_DIRECTMODE MS_FILTER_BASE_METHOD(14,int) 702 #define MS_FILTER_ENABLE_VAD MS_FILTER_BASE_METHOD(15,int) 703 #define MS_FILTER_GET_STAT_DISCARDED MS_FILTER_BASE_METHOD(16,int) 704 #define MS_FILTER_GET_STAT_MISSED MS_FILTER_BASE_METHOD(17,int) 705 #define MS_FILTER_GET_STAT_INPUT MS_FILTER_BASE_METHOD(18,int) 706 #define MS_FILTER_GET_STAT_OUTPUT MS_FILTER_BASE_METHOD(19,int) 707 #define MS_FILTER_ENABLE_AGC MS_FILTER_BASE_METHOD(20,int) 708 #define MS_FILTER_SET_PLAYBACKDELAY MS_FILTER_BASE_METHOD(21,int) 709 #define MS_FILTER_ENABLE_HALFDUPLEX MS_FILTER_BASE_METHOD(22,int) 710 #define MS_FILTER_SET_VAD_PROB_START MS_FILTER_BASE_METHOD(23,int) 711 #define MS_FILTER_SET_VAD_PROB_CONTINUE MS_FILTER_BASE_METHOD(24,int) 712 #define MS_FILTER_SET_MAX_GAIN MS_FILTER_BASE_METHOD(25,int) 713 #define MS_VIDEO_CAPTURE_SET_AUTOFOCUS MS_FILTER_BASE_METHOD(26,int) 714 /* pass value of type MSRtpPayloadPickerContext copied by the filter*/ 715 #define MS_FILTER_SET_RTP_PAYLOAD_PICKER MS_FILTER_BASE_METHOD(27,void*) 716 #define MS_FILTER_SET_OUTPUT_NCHANNELS MS_FILTER_BASE_METHOD(28,int) 717 718 719 /** @} */ 720 721 /*protected/ private methods*/ 722 MS2_PUBLIC void ms_filter_process(MSFilter *f); 723 MS2_PUBLIC void ms_filter_preprocess(MSFilter *f, struct _MSTicker *t); 724 MS2_PUBLIC void ms_filter_postprocess(MSFilter *f); 725 MS2_PUBLIC bool_t ms_filter_inputs_have_data(MSFilter *f); 726 MS2_PUBLIC void ms_filter_notify(MSFilter *f, unsigned int id, void *arg); 727 MS2_PUBLIC void ms_filter_notify_no_arg(MSFilter *f, unsigned int id); 728 void ms_filter_clear_notify_callback(MSFilter *f); 729 void ms_filter_clean_pending_events(MSFilter *f); 730 #define ms_filter_lock(f) ms_mutex_lock(&(f)->lock) 731 #define ms_filter_unlock(f) ms_mutex_unlock(&(f)->lock) 732 MS2_PUBLIC void ms_filter_unregister_all(void); 733 734 struct _MSFilterTask{ 735 MSFilter *f; 736 MSFilterFunc taskfunc; 737 }; 738 typedef struct _MSFilterTask MSFilterTask; 739 MS2_PUBLIC void ms_filter_task_process(MSFilterTask *task); 740 741 /** 742 * Allow a filter to request the ticker to call him the tick after. 743 * The ticker will call the taskfunc prior to all filter's process func. 744 **/ 745 MS2_PUBLIC void ms_filter_postpone_task(MSFilter *f, MSFilterFunc taskfunc); 746 747 #ifdef __cplusplus 748 } 749 #endif 750 751 #include "mediastreamer2/msinterfaces.h" 752 #include "mediastreamer2/msfactory.h" 753 /* used by awk script in Makefile.am to generate alldescs.c */ 754 #define MS_FILTER_DESC_EXPORT(desc) 755 756 #endif 757