1 /* 2 * GPAC - Multimedia Framework C SDK 3 * 4 * Authors: Jean Le Feuvre 5 * Copyright (c) Telecom ParisTech 2017-2019 6 * All rights reserved 7 * 8 * This file is part of GPAC / filters sub-project 9 * 10 * GPAC is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU Lesser General Public License as published by 12 * the Free Software Foundation; either version 2, or (at your option) 13 * any later version. 14 * 15 * GPAC is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License for more details. 19 * 20 * You should have received a copy of the GNU Lesser General Public 21 * License along with this library; see the file COPYING. If not, write to 22 * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 23 * 24 */ 25 26 #ifndef _GF_FILTERS_H_ 27 #define _GF_FILTERS_H_ 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #include <gpac/tools.h> 34 #include <gpac/list.h> 35 #include <gpac/events.h> 36 #include <gpac/user.h> 37 #include <gpac/constants.h> 38 #include <gpac/download.h> 39 #include <gpac/main.h> 40 41 //for offsetof() 42 #include <stddef.h> 43 44 /*! 45 \file "gpac/filters.h" 46 \brief Filter management of GPAC. 47 48 This file contains all exported functions for filter management of the GPAC framework. 49 */ 50 51 /*! 52 \addtogroup filters_grp Filter Management 53 \brief Filter Management of GPAC. 54 55 API Documentation of the filter managment system of GPAC. 56 57 The filter management in GPAC is built using the following core objects: 58 - \ref GF_FilterSession in charge of 59 loading filters from register, managing argument parsing and co 60 resolving filter graphs to handle PID connection(s) 61 tracking data packets and properties exchanged on PIDs 62 scheduling tasks between filters 63 ensuring thread-safe filter state: a filter may be called from any thread in the session (unless explicitely asked not to), but only by a single thread at any time. 64 - \ref __gf_filter_register static structure describing possible entry points of the filter, possible arguments and input output PID capabilities. 65 Each filter share the same API (register definition) regardless of its type: source/sink, mux/demux, encode/decode, raw media processing, encoded media processing, ... 66 - \ref GF_Filter is an instance of the filter register. A filter implementation typical tasks are: 67 accepting new input PIDs (for non source filters) 68 defining new output PIDs (for non sink filters), applying any property change due to filter processing 69 consuming packets on the input PIDs 70 dispatching packets on the output PIDs 71 - \ref GF_FilterPid handling the connections between two filters. 72 PID natively supports fan-out (one filter PID connecting to multiple destinations). 73 A PID is in charge of dispatching packets to possible destinations and storing PID properties in sync with dispatched packets. 74 Whenever PID properties change, the next packet sent on that PID is associated with the new state, and the destination filter(s) will be called 75 upon fetching the new packet. This is the one of the two reentrant code of a filter, the other one being the \ref GF_FEVT_INFO_UPDATE event. 76 When blocking mode is not disabled at the session filter, a PID is also in charge of managing its occupancy through either a number of packets or the 77 cumulated duration of the packets it is holding. 78 Whenever a PID holds too much data, it enters a blocking state. A filter with ALL its output PIDs in a blocked state won't be scheduled 79 for processing. This is a semi-blocking design, which imply that if a filter has one of its PIDs in a non blocking state, it will be scheduled for processing. If a PID has multiple destinations and one of the destination consumes faster than the other one, the filter is currently not blocking (this might change in the near future). 80 A PID is in charge of managing the packet references across filters, by performing memory management of allocated data packets 81 (avoid alloc/free at each packet but rather recycle the memory) and tracking shared packets references. 82 - \ref GF_FilterPacket holding data to dispatch from a filter on a given PID. 83 Packets are always associated to a single output PID, ie it is not possible for a filter to send one packet to multiple PIDs, the data has to be cloned. 84 Packets have default attributes such as timestamps, size, random access status, start/end frame, etc, as well as optional properties. 85 All packets are reference counted. 86 A packet can hold allocated block on the output PID, a pointer to some filter internal data, a data reference to a single input packet, or a frame interface object used for accessing data or OpenGL textures of the emitting filter. 87 Packets holding data references rather than copy are notified back to their creators upon destruction. 88 - \ref __gf_prop_val holding various properties for a PID or a packet 89 Properties can be copied/merged between input and output PIDs, or input and output packets. These properties are reference counted. 90 Two kinds of properties are defined, built-in ones which use a 32 bit identifier (usually a four character code), and user properties identified by a string. 91 PID properties are defined by the filter creating the PID. They can be overridden/added after being set by the filter by specifying fragment properties 92 in the filter arguments. For example \code fin=src=myfile.foo:#FEXT=bar \endcode will override the file extension property (FEXT) foo to bar AFTER the PID is being defined. 93 - \ref __gf_filter_event used to pass various events (play/stop/buffer requirements/...) up and down the filter chain. 94 This part of the API will likely change in the future, being merged with the global GF_Event of GPAC. 95 96 97 GPAC comes with a set of built-in filters in libgpac. It is also possible to define external filters in dynamic libraries. GPAC will look for such libraries 98 in folders listed in GPAC config file section core, key mod-dirs. The files SHALL be named gf_* and export a function called RegisterFilter 99 with the following prototype: 100 101 \param fsess is set to NULL unless meta filters are listed, in which case the filter register should list all possible meta filters it supports 102 \return a GF_FilterRegister structure used for instantiating the filter. 103 const GF_FilterRegister *RegisterFilter(GF_FilterSession *fsess); 104 105 */ 106 107 /*! \hideinitializer 108 A packet byte offset is set to this value when not valid 109 */ 110 #define GF_FILTER_NO_BO 0xFFFFFFFFFFFFFFFFUL 111 /*! \hideinitializer 112 A packet timestamp (Decoding or Composition) is set to this value when not valid 113 */ 114 #define GF_FILTER_NO_TS 0xFFFFFFFFFFFFFFFFUL 115 116 /*! \hideinitializer 117 Filter Session object 118 */ 119 typedef struct __gf_filter_session GF_FilterSession; 120 121 /*! \hideinitializer 122 Filter object 123 */ 124 typedef struct __gf_filter GF_Filter; 125 /*! \hideinitializer 126 Filter PID object 127 */ 128 typedef struct __gf_filter_pid GF_FilterPid; 129 130 /*! \hideinitializer 131 Filter Packet object 132 */ 133 typedef struct __gf_filter_pck GF_FilterPacket; 134 /*! 135 Filter Packet destructor function prototype 136 */ 137 typedef void (*gf_fsess_packet_destructor)(GF_Filter *filter, GF_FilterPid *PID, GF_FilterPacket *pck); 138 139 /*! 140 Filter Event object 141 */ 142 typedef union __gf_filter_event GF_FilterEvent; 143 144 /*! 145 Filter Session Task object 146 */ 147 typedef struct __gf_fs_task GF_FSTask; 148 149 /*! 150 Filter Register object 151 */ 152 typedef struct __gf_filter_register GF_FilterRegister; 153 /*! 154 Filter Property object 155 */ 156 typedef struct __gf_prop_val GF_PropertyValue; 157 158 /*! 159 Filter Property Reference object, used for info query only 160 */ 161 typedef struct __gf_prop_entry GF_PropertyEntry; 162 163 /*! 164 \addtogroup fs_grp Filter Session 165 \ingroup filters_grp 166 \brief Filter Session 167 168 The GPAC filter session object allows building media pipelines using multiple sources and destinations and arbitrary filter chains. 169 170 Filters are described through a \ref __gf_filter_register structure. A set of built-in filters are available, and user-defined filters can be added or removed at runtime. 171 172 The filter session keeps an internal graph representation of all available filters and their possible input connections, which is used when resolving connections between filters. 173 174 The number of \ref GF_FilterCapability matched between registries defines the weight of the connection. 175 176 Paths from an instantiated filter are enabled/disabled based on the source PID capabilities. 177 178 Paths to destination are recomputed for each destination, based on the instantiated destination filter capabilities. 179 180 The graph edges are then enabled in the possible subgraphs allowed by the destination capabilities, and unused filter registries (without enabled input connections) are removed from the graph. 181 182 The resulting weighted graph is then solved using Dijkstra's algorithm, using filter priority in case of weight equality. 183 184 The filter session works by default in a semi-blocking state. Whenever output PID buffers on a filter are all full, the filter is marked as blocked and not scheduled for processing. Whenever one output PID buffer is not full, the filter unblocks. 185 186 This implies that PID buffers may grow quite large if a filter is consuming data from a PID at a much faster rate than another filter consuming from that same PID. 187 * @{ 188 */ 189 190 191 /*! Filter session scheduler type */ 192 typedef enum 193 { 194 /*! In this mode, the scheduler does not use locks for packet and property queues. Main task list is mutex-protected */ 195 GF_FS_SCHEDULER_LOCK_FREE=0, 196 /*! In this mode, the scheduler uses locks for packet and property queues. Defaults to lock-free if no threads are used. Main task list is mutex-protected */ 197 GF_FS_SCHEDULER_LOCK, 198 /*! In this mode, the scheduler does not use locks for packet and property queues, nor for the main task list */ 199 GF_FS_SCHEDULER_LOCK_FREE_X, 200 /*! In this mode, the scheduler uses locks for packet and property queues even if single-threaded (test mode) */ 201 GF_FS_SCHEDULER_LOCK_FORCE, 202 /*! In this mode, the scheduler uses direct dispatch and no threads, trying to nest task calls within task calls */ 203 GF_FS_SCHEDULER_DIRECT 204 } GF_FilterSchedulerType; 205 206 /*! Flag set to indicate meta filters should be loaded. A meta filter is a filter providing various subfilters. 207 The subfilters are usually not exposed as filters, only the parent one is. 208 When set, all subfilters are exposed. This should only be set when inspecting filters help*/ 209 #define GF_FS_FLAG_LOAD_META 1<<1 210 /*! Flag set to disable the blocking mode of the filter session. The default is a semi-blocking mode, cf \ref gf_filter_pid_would_block*/ 211 #define GF_FS_FLAG_NO_BLOCKING 1<<2 212 /*! Flag set to disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (less memory occupancy but slower)*/ 213 #define GF_FS_FLAG_NO_GRAPH_CACHE 1<<3 214 /*! Flag set to disable main thread. Such sessions shall be run using \ref gf_fs_run_step*/ 215 #define GF_FS_FLAG_NO_MAIN_THREAD 1<<4 216 /*! Flag set to disable session regulation (no sleep)*/ 217 #define GF_FS_FLAG_NO_REGULATION 1<<5 218 /*! Flag set to disable data probe*/ 219 #define GF_FS_FLAG_NO_PROBE (1<<6) 220 /*! Flag set to disable source reassignment (e.g. switching from fin to ffdmx) in PID resolution*/ 221 #define GF_FS_FLAG_NO_REASSIGN (1<<7) 222 /*! Flag set to print enabled/disabled edges for debug of PID resolution*/ 223 #define GF_FS_FLAG_PRINT_CONNECTIONS (1<<8) 224 /*! Flag set to disable argument checking*/ 225 #define GF_FS_FLAG_NO_ARG_CHECK (1<<9) 226 /*! Disables reservoir for packets and properties, uses much less memory but much more alloc/free*/ 227 #define GF_FS_FLAG_NO_RESERVOIR (1<<10) 228 /*! Throws an error if any PID in the filter graph cannot be linked. The default behaviour is tu run the session even when some PIDs are not connected*/ 229 #define GF_FS_FLAG_FULL_LINK (1<<11) 230 231 /*! Creates a new filter session. This will also load all available filter registers not blacklisted. 232 \param nb_threads number of extra threads to allocate. A negative value means all core used by session (eg nb_cores-1 extra threads) 233 \param type scheduler type 234 \param flags set of above flags for the session. Modes set by flags cannot be changed at runtime 235 \param blacklist string containing comma-separated names of filters to disable 236 \return the created filter session 237 */ 238 GF_FilterSession *gf_fs_new(s32 nb_threads, GF_FilterSchedulerType type, u32 flags, const char *blacklist); 239 240 /*! Creates a new filter session, loading parameters from gpac config. This will also load all available filter registers not blacklisted. 241 \param flags set of flags for the session. Only \ref GF_FS_FLAG_LOAD_META and \ref GF_FS_FLAG_NO_MAIN_THREAD are used, other flags 242 \return the created filter session 243 */ 244 GF_FilterSession *gf_fs_new_defaults(u32 flags); 245 246 /*! Destructs the filter session 247 \param session the filter session to destruct 248 */ 249 void gf_fs_del(GF_FilterSession *session); 250 /*! Loads a given filter by its register name. Filter are created using their register name, with options appended as a list of colon-separated Name=Value pairs. 251 Value can be omitted for booleans, defaulting to true (eg :noedit). Using '!' before the name negates the result (eg :!moof_first). 252 Name can be omitted for enumerations (eg :disp=pbo is equivalent to :pbo), provided that filter developers pay attention to not reuse enum names in one filter. 253 254 \param session filter session 255 \param name name and arguments of the filter register to instantiate. 256 \param err_code set to error code if any - may be NULL. If initially set to GF_EOS, disables log messages. 257 \return created filter or NULL if filter register cannot be found 258 */ 259 GF_Filter *gf_fs_load_filter(GF_FilterSession *session, const char *name, GF_Err *err_code); 260 261 /*! Checks if a filter register exists by name. 262 \param session filter session 263 \param name name of the filter register to check. 264 \return GF_TRUE if a filter register exists with the given name, GF_FALSE otherwise 265 */ 266 Bool gf_fs_filter_exists(GF_FilterSession *session, const char *name); 267 268 /*! Runs the session 269 \param session filter session 270 \return error if any, or GF_EOS. The last errors can be retrieved using \ref gf_fs_get_last_connect_error and \ref gf_fs_get_last_process_error 271 */ 272 GF_Err gf_fs_run(GF_FilterSession *session); 273 274 /*! The default separator set used*/ 275 #define GF_FS_DEFAULT_SEPS ":=#,!@" 276 277 /*! Sets the set of separators to use when parsing args 278 \param session filter session 279 \param separator_set filter session. 280 The first char is used to separate argument names - default is ':' 281 The second char, if present, is used to separate names and values - default is '=' 282 The third char, if present, is used to separate fragments for PID sources - default is '#' 283 The fourth char, if present, is used for list separators (sourceIDs, gfreg, ...) - default is ',' 284 The fifth char, if present, is used for boolean negation - default is '!' 285 The sixth char, if present, is used for LINK directives - default is '@' 286 \return error if any 287 */ 288 GF_Err gf_fs_set_separators(GF_FilterSession *session, const char *separator_set); 289 290 /*! Sets the maximum length of a filter chain dynamically loaded to solve connection between two filters 291 \param session filter session 292 \param max_chain_length sets maximum chain length when resolving filter links. 293 Default value is 6 ([ in -> ] demux -> reframe -> decode -> encode -> reframe -> mux [ -> out ]) 294 (filter chains loaded for adaptation (eg pixel format change, audio resample) are loaded after the link resolution) 295 Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually 296 \return error if any 297 */ 298 GF_Err gf_fs_set_max_resolution_chain_length(GF_FilterSession *session, u32 max_chain_length); 299 300 /*! Sets the maximum sleep time when postponing tasks. 301 \param session filter session 302 \param max_sleep maximum sleep time in milliseconds. 0 means yield only. 303 \return error if any 304 */ 305 GF_Err gf_fs_set_max_sleep_time(GF_FilterSession *session, u32 max_sleep); 306 307 /*! gets the maximum filter chain lengtG 308 \param session filter session 309 \return maximum chain length when resolving filter links. 310 */ 311 u32 gf_fs_get_max_resolution_chain_length(GF_FilterSession *session); 312 313 /*! Runs session in non blocking mode: process all tasks of oldest scheduled filter, process any pending PID connections and returns. 314 This can only be used if the flag \ref GF_FS_FLAG_NO_MAIN_THREAD was specified at session creation time 315 \param session filter session 316 */ 317 void gf_fs_run_step(GF_FilterSession *session); 318 319 /*! Stops the session, waiting for all additional threads to complete 320 \param session filter session 321 \return error if any 322 */ 323 GF_Err gf_fs_stop(GF_FilterSession *session); 324 325 /*! Gets the number of available filter registries (not blacklisted) 326 \param session filter session 327 \return number of filter registries 328 */ 329 u32 gf_fs_filters_registers_count(GF_FilterSession *session); 330 331 /*! Returns the register at the given index 332 \param session filter session 333 \param idx index of register, from 0 to \ref gf_fs_filters_registers_count 334 \return the register object, or NULL if index is out of bounds 335 */ 336 const GF_FilterRegister *gf_fs_get_filter_register(GF_FilterSession *session, u32 idx); 337 338 /*! Registers the test filters used for unit tests 339 \param session filter session 340 */ 341 void gf_fs_register_test_filters(GF_FilterSession *session); 342 343 /*! Loads a source filter from a URL and arguments 344 \param session filter session 345 \param url URL of the source to load. Can be a local file name, a full path (/.., \\...) or a full URL with scheme (eg http://, tcp://) 346 \param args arguments for the filter, see \ref gf_fs_load_filter 347 \param parent_url parent URL of the source, or NULL if none 348 \param err if not NULL, is set to error code if any 349 \return the filter loaded or NULL if error 350 */ 351 GF_Filter *gf_fs_load_source(GF_FilterSession *session, const char *url, const char *args, const char *parent_url, GF_Err *err); 352 353 /*! Loads a destination filter from a URL and arguments 354 \param session filter session 355 \param url URL of the source to load. Can ba a local file name, a full path (/.., \\...) or a full URL with scheme (eg http://, tcp://) 356 \param args arguments for the filter, see \ref gf_fs_load_filter 357 \param parent_url parent URL of the source, or NULL if none 358 \param err if not NULL, is set to error code if any 359 \return the filter loaded or NULL if error 360 */ 361 GF_Filter *gf_fs_load_destination(GF_FilterSession *session, const char *url, const char *args, const char *parent_url, GF_Err *err); 362 363 /*! Returns the last error which happened during a PID connection 364 \param session filter session 365 \return the error code if any 366 */ 367 GF_Err gf_fs_get_last_connect_error(GF_FilterSession *session); 368 369 /*! Returns the last error which happened during a filter process 370 \param session filter session 371 \return the error code if any 372 */ 373 GF_Err gf_fs_get_last_process_error(GF_FilterSession *session); 374 375 /*! Adds a user-defined register to the session 376 \param session filter session 377 \param freg filter register to add 378 */ 379 void gf_fs_add_filter_register(GF_FilterSession *session, const GF_FilterRegister *freg); 380 381 /*! Removes a user-defined register from the session 382 \param session filter session 383 \param freg filter register to remove 384 */ 385 void gf_fs_remove_filter_register(GF_FilterSession *session, GF_FilterRegister *freg); 386 387 /*! Posts a user task to the session 388 \param session filter session 389 \param task_execute the callback function for the task. The callback can return GF_TRUE to reschedule the task, in which case the task will be rescheduled 390 immediately or after reschedule_ms. 391 \param udta_callback callback user data passed back to the task_execute function 392 \param log_name log name of the task. If NULL, default is "user_task" 393 \return the error code if any 394 */ 395 GF_Err gf_fs_post_user_task(GF_FilterSession *session, Bool (*task_execute) (GF_FilterSession *fsess, void *callback, u32 *reschedule_ms), void *udta_callback, const char *log_name); 396 397 /*! Aborts the session. This can be called within a callback task to stop the session. Do NOT use \ref gf_fs_stop from within a user task callback, this will deadlock the session 398 \param session filter session 399 \param do_flush if set to true, sources will be forced into end of stream and all emitted packets will be processed. Otherwise everything is discarded, potentially breaking output files 400 \return the error code if any 401 */ 402 GF_Err gf_fs_abort(GF_FilterSession *session, Bool do_flush); 403 /*! Checks if the session is processing its last task. This can be called within a callback task to check if this is the last task, in order to avoid rescheduling the task 404 \param session filter session 405 \return GF_TRUE if no more task, GF_FALSE otherwise 406 */ 407 Bool gf_fs_is_last_task(GF_FilterSession *session); 408 409 /*! Checks if a given MIME type is supported as input 410 \param session filter session 411 \param mime MIME type to query 412 \return GF_TRUE if MIME is supported 413 */ 414 Bool gf_fs_mime_supported(GF_FilterSession *session, const char *mime); 415 416 417 /*! Sets UI callback event 418 \param session filter session 419 \param ui_event_proc the event proc callback function. Its return value depends on the event type, usually 0 420 \param cbk_udta pointer passed back to callback 421 */ 422 void gf_fs_set_ui_callback(GF_FilterSession *session, Bool (*ui_event_proc)(void *opaque, GF_Event *event), void *cbk_udta); 423 424 /*! Prints stats to logs using \code LOG_APP@LOG_INFO \endcode 425 \param session filter session 426 */ 427 void gf_fs_print_stats(GF_FilterSession *session); 428 429 /*! Prints connections between loaded filters in the session to logs using \code LOG_APP@LOG_INFO \endcode 430 \param session filter session 431 */ 432 void gf_fs_print_connections(GF_FilterSession *session); 433 434 /*! Prints all possible connections between filter registries to logs using \code LOG_APP@LOG_INFO \endcode 435 \param session filter session 436 \param filter_name if not null, only prints input connection for this filter register 437 \param print_fn optional callback function for print, otherwise print to stderr 438 */ 439 void gf_fs_print_all_connections(GF_FilterSession *session, char *filter_name, void (*print_fn)(FILE *output, GF_SysPrintArgFlags flags, const char *fmt, ...) ); 440 441 /*! Checks the presence of an input capability and an output capability in a target register. The caps are matched only if they belong to the same bundle. 442 \param filter_reg filter register to check 443 \param in_cap_code capability code (property type) of input capability to check 444 \param in_cap capabiility value of input capability to check 445 \param out_cap_code capability code (property type) of output capability to check 446 \param out_cap capability value of output capability to check 447 \param exact_match_only if true returns TRUE only if exact match (code and value), otherwise return TRUE if caps code are matched 448 \return GF_TRUE if filter register has such a match, GF_FALSE otherwise 449 */ 450 Bool gf_fs_check_filter_register_cap(const GF_FilterRegister *filter_reg, u32 in_cap_code, GF_PropertyValue *in_cap, u32 out_cap_code, GF_PropertyValue *out_cap, Bool exact_match_only); 451 452 453 /*! Enables or disables filter reporting 454 \param session filter session 455 \param reporting_on if GF_TRUE, reporting will be enabled 456 */ 457 void gf_fs_enable_reporting(GF_FilterSession *session, Bool reporting_on); 458 459 /*! Locks global session mutex - mostly used to query filter reports and avoids concurrent destruction of a filter 460 \param session filter session 461 \param do_lock if GF_TRUE, session is locked, otherwise session is unlocked 462 */ 463 void gf_fs_lock_filters(GF_FilterSession *session, Bool do_lock); 464 465 /*! Gets number of active filters in the session 466 \param session filter session 467 \return number of active filters 468 */ 469 u32 gf_fs_get_filters_count(GF_FilterSession *session); 470 471 /*! Type of filter*/ 472 typedef enum 473 { 474 /*! Unknown filter type*/ 475 GF_FS_STATS_FILTER_UNKNOWN, 476 /*! raw input (file, socket, pipe) filter type*/ 477 GF_FS_STATS_FILTER_RAWIN, 478 /*! demultiplexer filter type*/ 479 GF_FS_STATS_FILTER_DEMUX, 480 /*! decoder filter type*/ 481 GF_FS_STATS_FILTER_DECODE, 482 /*! encoder filter type*/ 483 GF_FS_STATS_FILTER_ENCODE, 484 /*! multiplexer filter type*/ 485 GF_FS_STATS_FILTER_MUX, 486 /*! raw output (file, socket, pipe) filter type*/ 487 GF_FS_STATS_FILTER_RAWOUT, 488 } GF_FSFilterType; 489 490 /*! Filter statistics object*/ 491 typedef struct 492 { 493 /*!filter object*/ 494 const GF_Filter *filter; 495 /*!set if filter is only an alias, in which case all remaining fields of the structure are not set*/ 496 const GF_Filter *filter_alias; 497 498 /*!number of tasks executed by this filter*/ 499 u64 nb_tasks_done; 500 /*!number of packets processed by this filter*/ 501 u64 nb_pck_processed; 502 /*!number of bytes processed by this filter*/ 503 u64 nb_bytes_processed; 504 /*!number of packets sent by this filter*/ 505 u64 nb_pck_sent; 506 /*!number of hardware frames packets sent by this filter*/ 507 u64 nb_hw_pck_sent; 508 /*!number of processing errors in the lifetime of the filter*/ 509 u32 nb_errors; 510 511 /*!number of bytes sent by this filter*/ 512 u64 nb_bytes_sent; 513 /*!number of microseconds this filter was active*/ 514 u64 time_process; 515 /*!percentage of data processed (between 0 and 100), otherwise unknown (-1)*/ 516 s32 percent; 517 /*!last status report from filter, null if session reporting is not enabled*/ 518 const char *status; 519 /*!set to GF_TRUE of status or percent changed since last query for this filter, GF_FALSE otherwise*/ 520 Bool report_updated; 521 /*!filter name*/ 522 const char *name; 523 /*!filter register name*/ 524 const char *reg_name; 525 /*!filter register ID*/ 526 const char *filter_id; 527 /*!set to GF_TRUE if filter is done processing*/ 528 Bool done; 529 /*!number of input PIDs*/ 530 u32 nb_pid_in; 531 /*!number of input packets processed*/ 532 u64 nb_in_pck; 533 /*!number of output PIDs*/ 534 u32 nb_pid_out; 535 /*!number of output packets sent*/ 536 u64 nb_out_pck; 537 /*!set to GF_TRUE if filter has seen end of stream*/ 538 Bool in_eos; 539 /*!set to GF_TRUE if filter has seen end of stream*/ 540 GF_FSFilterType type; 541 /*!set to streamtype of output PID if single output, GF_STREAM_UNKNOWN otherwise*/ 542 u32 stream_type; 543 /*!set to codecid of output PID if single output, GF_CODECID_NONE otherwise*/ 544 u32 codecid; 545 } GF_FilterStats; 546 547 /*! Gets number of active filters in the session 548 \param session filter session 549 \param idx index of filter to query 550 \param stats statistics for filter 551 \return error code if any 552 */ 553 GF_Err gf_fs_get_filter_stats(GF_FilterSession *session, u32 idx, GF_FilterStats *stats); 554 555 556 /*! Enumerates filter and meta-filter arguments not matched in the session 557 \param session filter session 558 \param idx index of argument to query, 0 being first argument; this value is automatically incremented 559 \param argname set to argument name 560 \param argtype set to argument type: 0 was a filter param (eg:arg=val), 1 was a global arg (eg --arg=val) and 2 was a global meta arg (eg -+arg=val) 561 \return GF_TRUE if success, GF_FALSE if nothing more to enumerate 562 */ 563 Bool gf_fs_enum_unmapped_options(GF_FilterSession *session, u32 *idx, char **argname, u32 *argtype); 564 565 566 567 /*! Flags for argument update event*/ 568 typedef enum 569 { 570 /*! the update event can be sent down the source chain*/ 571 GF_FILTER_UPDATE_DOWNSTREAM = 1<<1, 572 /*! the update event can be sent up the filter chain*/ 573 GF_FILTER_UPDATE_UPSTREAM = 1<<2, 574 } GF_EventPropagateType; 575 576 /*! Enumerates filter and meta-filter arguments not matched in the session 577 \param session filter session 578 \param fid ID of filter on which to send the update, NULL if filter is set 579 \param filter filter on which to send the update, NULL if fid is set 580 \param name name of filter option to update 581 \param val value of filter option to update 582 \param propagate_mask propagation flags - 0 means no propagation 583 */ 584 585 void gf_fs_send_update(GF_FilterSession *session, const char *fid, GF_Filter *filter, const char *name, const char *val, GF_EventPropagateType propagate_mask); 586 587 /*! @} */ 588 589 590 /*! 591 \addtogroup fs_props Filter Properties 592 \ingroup filters_grp 593 \brief PID and filter properties 594 595 Documents the property object used for PID and packets. 596 @{ 597 */ 598 599 /*! Property types*/ 600 typedef enum 601 { 602 /*! not allowed*/ 603 GF_PROP_FORBIDEN=0, 604 /*! signed 32 bit integer*/ 605 GF_PROP_SINT, 606 /*! unsigned 32 bit integer*/ 607 GF_PROP_UINT, 608 /*! signed 64 bit integer*/ 609 GF_PROP_LSINT, 610 /*! unsigned 64 bit integer*/ 611 GF_PROP_LUINT, 612 /*! boolean*/ 613 GF_PROP_BOOL, 614 /*! 32 bit / 32 bit fraction*/ 615 GF_PROP_FRACTION, 616 /*! 64 bit / 64 bit fraction*/ 617 GF_PROP_FRACTION64, 618 /*! float (Fixed) number*/ 619 GF_PROP_FLOAT, 620 /*! double number*/ 621 GF_PROP_DOUBLE, 622 /*! 2D signed integer vector*/ 623 GF_PROP_VEC2I, 624 /*! 2D double number vector*/ 625 GF_PROP_VEC2, 626 /*! 3D signed integer vector*/ 627 GF_PROP_VEC3I, 628 /*! 3D double number vector*/ 629 GF_PROP_VEC3, 630 /*! 4D signed integer vector*/ 631 GF_PROP_VEC4I, 632 /*! 4D double number vector*/ 633 GF_PROP_VEC4, 634 /*! Video Pixel format*/ 635 GF_PROP_PIXFMT, 636 /*! Audio PCM format*/ 637 GF_PROP_PCMFMT, 638 /*! string property, memory is duplicated when setting the property and managed internally*/ 639 GF_PROP_STRING, 640 /*! string property, memory is NOT duplicated when setting the property but is then managed (and free) internally. 641 Only used when setting a property, the type then defaults to GF_PROP_STRING*/ 642 GF_PROP_STRING_NO_COPY, 643 /*! data property, memory is duplicated when setting the property and managed internally*/ 644 GF_PROP_DATA, 645 /*! const string property, memory is NOT duplicated when setting the property, stays user-managed*/ 646 GF_PROP_NAME, 647 /*! data property, memory is NOT duplicated when setting the property but is then managed (and free) internally. 648 Only used when setting a property, the type then defaults to GF_PROP_DATA*/ 649 GF_PROP_DATA_NO_COPY, 650 /*! const data property, memory is NOT duplicated when setting the property, stays user-managed*/ 651 GF_PROP_CONST_DATA, 652 /*! user-managed pointer*/ 653 GF_PROP_POINTER, 654 /*! string list, memory is NOT duplicated when setting the property, the GF_List * of 655 the passed property is directly assigned to the new property and will be and managed internally (freed by the filter session)*/ 656 GF_PROP_STRING_LIST, 657 /*! unsigned 32 bit integer list, memory is ALWAYS duplicated when setting the property*/ 658 GF_PROP_UINT_LIST, 659 660 /*! not allowed*/ 661 GF_PROP_LAST_DEFINED, 662 } GF_PropType; 663 664 /*! Data property*/ 665 typedef struct 666 { 667 /*! data pointer */ 668 u8 *ptr; 669 /*! data size */ 670 u32 size; 671 } GF_PropData; 672 673 /*! List of unsigned int property*/ 674 typedef struct 675 { 676 /*! array of unsigned integers */ 677 u32 *vals; 678 /*! number of items in array */ 679 u32 nb_items; 680 } GF_PropUIntList; 681 682 /*! 2D signed integer vector property*/ 683 typedef struct 684 { 685 /*! x coord */ 686 s32 x; 687 /*! y coord */ 688 s32 y; 689 } GF_PropVec2i; 690 691 /*! 2D double number vector property*/ 692 typedef struct 693 { 694 /*! x coord */ 695 Double x; 696 /*! y coord */ 697 Double y; 698 } GF_PropVec2; 699 700 /*! 3D signed integer vector property*/ 701 typedef struct 702 { 703 /*! x coord */ 704 s32 x; 705 /*! y coord */ 706 s32 y; 707 /*! z coord */ 708 s32 z; 709 } GF_PropVec3i; 710 711 /*! 3D double number vector property*/ 712 typedef struct 713 { 714 /*! x coord */ 715 Double x; 716 /*! y coord */ 717 Double y; 718 /*! z coord */ 719 Double z; 720 } GF_PropVec3; 721 722 /*! 4D signed integer vector property*/ 723 typedef struct 724 { 725 /*! x coord */ 726 s32 x; 727 /*! y coord */ 728 s32 y; 729 /*! z coord */ 730 s32 z; 731 /*! w coord */ 732 s32 w; 733 } GF_PropVec4i; 734 735 /*! 4D double number vector property*/ 736 typedef struct 737 { 738 /*! x coord */ 739 Double x; 740 /*! y coord */ 741 Double y; 742 /*! z coord */ 743 Double z; 744 /*! w coord */ 745 Double w; 746 } GF_PropVec4; 747 748 /*! Property value used by PIDs and packets*/ 749 struct __gf_prop_val 750 { 751 /*! type of the property */ 752 GF_PropType type; 753 /*! union of all possible property data types */ 754 union { 755 /*! 64 bit unsigned integer value of property */ 756 u64 longuint; 757 /*! 64 bit signed integer value of property */ 758 s64 longsint; 759 /*! 32 bit signed integer value of property */ 760 s32 sint; 761 /*! 32 bit unsigned integer value of property */ 762 u32 uint; 763 /*! boolean value of property */ 764 Bool boolean; 765 /*! fraction (32/32 bits) value of property */ 766 GF_Fraction frac; 767 /*! fraction (64/64 bits) value of property */ 768 GF_Fraction64 lfrac; 769 /*! fixed number (float or 32 bit depending on compilation settings) value of property */ 770 Fixed fnumber; 771 /*! double value of property */ 772 Double number; 773 /*! 2D signed integer vector value of property */ 774 GF_PropVec2i vec2i; 775 /*! 2D double vector value of property */ 776 GF_PropVec2 vec2; 777 /*! 3D signed integer vector value of property */ 778 GF_PropVec3i vec3i; 779 /*! 3D double vector value of property */ 780 GF_PropVec3 vec3; 781 /*! 4D signed integer vector value of property */ 782 GF_PropVec4i vec4i; 783 /*! 4D double vector value of property */ 784 GF_PropVec4 vec4; 785 /*! data value of property. For non const data type, the memory is freed by filter session. 786 Otherwise caller is responsible to free it at end of filter/session*/ 787 GF_PropData data; 788 /*! string value of property. For non const string / names, the memory is freed by filter session, otherwise handled as const char *. */ 789 char *string; 790 /*! pointer value of property */ 791 void *ptr; 792 /*! string list value of property - memory is handled by filter session (always copy)*/ 793 GF_List *string_list; 794 /*! unsigned integer list value of property - memory is handled by filter session (always copy)*/ 795 GF_PropUIntList uint_list; 796 } value; 797 }; 798 799 /*! Playback mode type supported on PID*/ 800 typedef enum 801 { 802 /*! simplest playback mode, can play from 0 at speed=1 only*/ 803 GF_PLAYBACK_MODE_NONE=0, 804 /*! seek playback mode, can play from any position at speed=1 only*/ 805 GF_PLAYBACK_MODE_SEEK, 806 /*! fast forward playback mode, can play from any position at speed=N only, with N>=0*/ 807 GF_PLAYBACK_MODE_FASTFORWARD, 808 /*! rewind playback mode, can play from any position at speed=N, N positive or negative*/ 809 GF_PLAYBACK_MODE_REWIND 810 } GF_FilterPidPlaybackMode; 811 812 /*! Built-in property types 813 See gpac help (gpac -h props) for codes, types, formats and and meaning 814 \hideinitializer 815 */ 816 enum 817 { 818 GF_PROP_PID_ID = GF_4CC('P','I','D','I'), 819 GF_PROP_PID_ESID = GF_4CC('E','S','I','D'), 820 GF_PROP_PID_ITEM_ID = GF_4CC('I','T','I','D'), 821 GF_PROP_PID_SERVICE_ID = GF_4CC('P','S','I','D'), 822 GF_PROP_PID_CLOCK_ID = GF_4CC('C','K','I','D'), 823 GF_PROP_PID_DEPENDENCY_ID = GF_4CC('D','P','I','D'), 824 GF_PROP_PID_SUBLAYER = GF_4CC('D','P','S','L'), 825 GF_PROP_PID_PLAYBACK_MODE = GF_4CC('P','B','K','M'), 826 GF_PROP_PID_SCALABLE = GF_4CC('S','C','A','L'), 827 GF_PROP_PID_TILE_BASE = GF_4CC('S','A','B','T'), 828 GF_PROP_PID_LANGUAGE = GF_4CC('L','A','N','G'), 829 GF_PROP_PID_SERVICE_NAME = GF_4CC('S','N','A','M'), 830 GF_PROP_PID_SERVICE_PROVIDER = GF_4CC('S','P','R','O'), 831 GF_PROP_PID_STREAM_TYPE = GF_4CC('P','M','S','T'), 832 GF_PROP_PID_SUBTYPE = GF_4CC('P','S','S','T'), 833 GF_PROP_PID_ISOM_SUBTYPE = GF_4CC('P','I','S','T'), 834 GF_PROP_PID_ORIG_STREAM_TYPE = GF_4CC('P','O','S','T'), 835 GF_PROP_PID_CODECID = GF_4CC('P','O','T','I'), 836 GF_PROP_PID_IN_IOD = GF_4CC('P','I','O','D'), 837 GF_PROP_PID_UNFRAMED = GF_4CC('P','F','R','M'), 838 GF_PROP_PID_UNFRAMED_FULL_AU = GF_4CC('P','F','R','F'), 839 GF_PROP_PID_DURATION = GF_4CC('P','D','U','R'), 840 GF_PROP_PID_NB_FRAMES = GF_4CC('N','F','R','M'), 841 GF_PROP_PID_FRAME_SIZE = GF_4CC('C','F','R','S'), 842 GF_PROP_PID_TIMESHIFT_DEPTH = GF_4CC('P','T','S','D'), 843 GF_PROP_PID_TIMESHIFT_TIME = GF_4CC('P','T','S','T'), 844 GF_PROP_PID_TIMESHIFT_STATE = GF_4CC('P','T','S','S'), 845 GF_PROP_PID_TIMESCALE = GF_4CC('T','I','M','S'), 846 GF_PROP_PID_PROFILE_LEVEL = GF_4CC('P','R','P','L'), 847 GF_PROP_PID_DECODER_CONFIG = GF_4CC('D','C','F','G'), 848 GF_PROP_PID_DECODER_CONFIG_ENHANCEMENT = GF_4CC('E','C','F','G'), 849 GF_PROP_PID_CONFIG_IDX = GF_4CC('I','C','F','G'), 850 GF_PROP_PID_SAMPLE_RATE = GF_4CC('A','U','S','R'), 851 GF_PROP_PID_SAMPLES_PER_FRAME = GF_4CC('F','R','M','S'), 852 GF_PROP_PID_NUM_CHANNELS = GF_4CC('C','H','N','B'), 853 GF_PROP_PID_AUDIO_BPS = GF_4CC('A','B','P','S'), 854 GF_PROP_PID_CHANNEL_LAYOUT = GF_4CC('C','H','L','O'), 855 GF_PROP_PID_AUDIO_FORMAT = GF_4CC('A','F','M','T'), 856 GF_PROP_PID_AUDIO_SPEED = GF_4CC('A','S','P','D'), 857 GF_PROP_PID_UNFRAMED_LATM = GF_4CC('L','A','T','M'), 858 GF_PROP_PID_DELAY = GF_4CC('M','D','L','Y'), 859 GF_PROP_PID_CTS_SHIFT = GF_4CC('M','D','T','S'), 860 GF_PROP_PID_WIDTH = GF_4CC('W','I','D','T'), 861 GF_PROP_PID_HEIGHT = GF_4CC('H','E','I','G'), 862 GF_PROP_PID_PIXFMT = GF_4CC('P','F','M','T'), 863 GF_PROP_PID_PIXFMT_WRAPPED = GF_4CC('P','F','M','W'), 864 GF_PROP_PID_STRIDE = GF_4CC('V','S','T','Y'), 865 GF_PROP_PID_STRIDE_UV = GF_4CC('V','S','T','C'), 866 GF_PROP_PID_BIT_DEPTH_Y = GF_4CC('Y','B','P','S'), 867 GF_PROP_PID_BIT_DEPTH_UV = GF_4CC('C','B','P','S'), 868 GF_PROP_PID_FPS = GF_4CC('V','F','P','F'), 869 GF_PROP_PID_INTERLACED = GF_4CC('V','I','L','C'), 870 GF_PROP_PID_SAR = GF_4CC('P','S','A','R'), 871 GF_PROP_PID_PAR = GF_4CC('V','P','A','R'), 872 GF_PROP_PID_WIDTH_MAX = GF_4CC('M', 'W','I','D'), 873 GF_PROP_PID_HEIGHT_MAX = GF_4CC('M', 'H','E','I'), 874 GF_PROP_PID_ZORDER = GF_4CC('V', 'Z','I','X'), 875 GF_PROP_PID_TRANS_X = GF_4CC('V','T','R','X'), 876 GF_PROP_PID_TRANS_Y = GF_4CC('V','T','R','Y'), 877 GF_PROP_PID_HIDDEN = GF_4CC('H','I','D','E'), 878 GF_PROP_PID_CROP_POS = GF_4CC('V','C','X','Y'), 879 GF_PROP_PID_ORIG_SIZE = GF_4CC('V','O','W','H'), 880 GF_PROP_PID_SRD = GF_4CC('S','R','D',' '), 881 GF_PROP_PID_SRD_REF = GF_4CC('S','R','D','R'), 882 GF_PROP_PID_SRD_MAP = GF_4CC('S','R','D','M'), 883 GF_PROP_PID_ALPHA = GF_4CC('V','A','L','P'), 884 GF_PROP_PID_DOLBY_VISION = GF_4CC('D','O','V','I'), 885 GF_PROP_PID_BITRATE = GF_4CC('R','A','T','E'), 886 GF_PROP_PID_MAXRATE = GF_4CC('M','R','A','T'), 887 GF_PROP_PID_DBSIZE = GF_4CC('D','B','S','Z'), 888 GF_PROP_PID_MEDIA_DATA_SIZE = GF_4CC('M','D','S','Z'), 889 GF_PROP_PID_CAN_DATAREF = GF_4CC('D','R','E','F'), 890 GF_PROP_PID_URL = GF_4CC('F','U','R','L'), 891 GF_PROP_PID_REMOTE_URL = GF_4CC('R','U','R','L'), 892 GF_PROP_PID_REDIRECT_URL = GF_4CC('R','E','L','O'), 893 GF_PROP_PID_FILEPATH = GF_4CC('F','S','R','C'), 894 GF_PROP_PID_MIME = GF_4CC('M','I','M','E'), 895 GF_PROP_PID_FILE_EXT = GF_4CC('F','E','X','T'), 896 GF_PROP_PID_OUTPATH = GF_4CC('F','D','S','T'), 897 GF_PROP_PID_FILE_CACHED = GF_4CC('C','A','C','H'), 898 GF_PROP_PID_DOWN_RATE = GF_4CC('D','L','B','W'), 899 GF_PROP_PID_DOWN_SIZE = GF_4CC('D','L','S','Z'), 900 GF_PROP_PID_DOWN_BYTES = GF_4CC('D','L','B','D'), 901 GF_PROP_PID_FILE_RANGE = GF_4CC('F','B','R','A'), 902 GF_PROP_PID_DISABLE_PROGRESSIVE = GF_4CC('N','P','R','G'), 903 GF_PROP_PID_ISOM_BRANDS = GF_4CC('A','B','R','D'), 904 GF_PROP_PID_ISOM_MBRAND = GF_4CC('M','B','R','D'), 905 GF_PROP_PID_ISOM_MOVIE_TIME = GF_4CC('M','H','T','S'), 906 GF_PROP_PID_HAS_SYNC = GF_4CC('P','S','Y','N'), 907 GF_PROP_SERVICE_WIDTH = GF_4CC('D','W','D','T'), 908 GF_PROP_SERVICE_HEIGHT = GF_4CC('D','H','G','T'), 909 GF_PROP_PID_CAROUSEL_RATE = GF_4CC('C','A','R','A'), 910 GF_PROP_PID_UTC_TIME = GF_4CC('U','T','C','D'), 911 GF_PROP_PID_UTC_TIMESTAMP = GF_4CC('U','T','C','T'), 912 GF_PROP_PID_AUDIO_VOLUME = GF_4CC('A','V','O','L'), 913 GF_PROP_PID_AUDIO_PAN = GF_4CC('A','P','A','N'), 914 GF_PROP_PID_AUDIO_PRIORITY = GF_4CC('A','P','R','I'), 915 GF_PROP_PID_PROTECTION_SCHEME_TYPE = GF_4CC('S','C','H','T'), 916 GF_PROP_PID_PROTECTION_SCHEME_VERSION = GF_4CC('S','C','H','V'), 917 GF_PROP_PID_PROTECTION_SCHEME_URI = GF_4CC('S','C','H','U'), 918 GF_PROP_PID_PROTECTION_KMS_URI = GF_4CC('K','M','S','U'), 919 GF_PROP_PID_ISMA_SELECTIVE_ENC = GF_4CC('I','S','S','E'), 920 GF_PROP_PID_ISMA_IV_LENGTH = GF_4CC('I','S','I','V'), 921 GF_PROP_PID_ISMA_KI_LENGTH = GF_4CC('I','S','K','I'), 922 GF_PROP_PID_ISMA_KI = GF_4CC('I','K','E','Y'), 923 GF_PROP_PID_OMA_CRYPT_TYPE = GF_4CC('O','M','C','T'), 924 GF_PROP_PID_OMA_CID = GF_4CC('O','M','I','D'), 925 GF_PROP_PID_OMA_TXT_HDR = GF_4CC('O','M','T','H'), 926 GF_PROP_PID_OMA_CLEAR_LEN = GF_4CC('O','M','P','T'), 927 GF_PROP_PID_CRYPT_INFO = GF_4CC('E','C','R','I'), 928 GF_PROP_PID_DECRYPT_INFO = GF_4CC('E','D','R','I'), 929 GF_PROP_PCK_SENDER_NTP = GF_4CC('N','T','P','S'), 930 GF_PROP_PCK_RECEIVER_NTP = GF_4CC('N','T','P','R'), 931 GF_PROP_PID_ADOBE_CRYPT_META = GF_4CC('A','M','E','T'), 932 GF_PROP_PID_ENCRYPTED = GF_4CC('E','P','C','K'), 933 GF_PROP_PID_OMA_PREVIEW_RANGE = GF_4CC('O','D','P','R'), 934 GF_PROP_PID_CENC_PSSH = GF_4CC('P','S','S','H'), 935 GF_PROP_PCK_CENC_SAI = GF_4CC('S','A','I','S'), 936 GF_PROP_PID_KID = GF_4CC('S','K','I','D'), 937 GF_PROP_PID_CENC_IV_SIZE = GF_4CC('S','A','I','V'), 938 GF_PROP_PID_CENC_IV_CONST = GF_4CC('C','B','I','V'), 939 GF_PROP_PID_CENC_PATTERN = GF_4CC('C','P','T','R'), 940 GF_PROP_PID_CENC_STORE = GF_4CC('C','S','T','R'), 941 GF_PROP_PID_CENC_STSD_MODE = GF_4CC('C','S','T','M'), 942 GF_PROP_PID_AMR_MODE_SET = GF_4CC('A','M','S','T'), 943 GF_PROP_PCK_SUBS = GF_4CC('S','U','B','S'), 944 GF_PROP_PID_MAX_NALU_SIZE = GF_4CC('N','A','L','S'), 945 GF_PROP_PCK_FILENUM = GF_4CC('F','N','U','M'), 946 GF_PROP_PCK_FILENAME = GF_4CC('F','N','A','M'), 947 GF_PROP_PCK_IDXFILENAME = GF_4CC('I','N','A','M'), 948 GF_PROP_PCK_FILESUF = GF_4CC('F','S','U','F'), 949 GF_PROP_PCK_EODS = GF_4CC('E','O','D','S'), 950 GF_PROP_PID_MAX_FRAME_SIZE = GF_4CC('M','F','R','S'), 951 GF_PROP_PID_AVG_FRAME_SIZE = GF_4CC('A','F','R','S'), 952 GF_PROP_PID_MAX_TS_DELTA = GF_4CC('M','T','S','D'), 953 GF_PROP_PID_MAX_CTS_OFFSET = GF_4CC('M','C','T','O'), 954 GF_PROP_PID_CONSTANT_DURATION = GF_4CC('S','C','T','D'), 955 GF_PROP_PID_ISOM_TRACK_TEMPLATE = GF_4CC('I','T','K','T'), 956 GF_PROP_PID_ISOM_TREX_TEMPLATE = GF_4CC('I','T','X','T'), 957 GF_PROP_PID_ISOM_STSD_TEMPLATE = GF_4CC('I','S','T','D'), 958 GF_PROP_PID_ISOM_UDTA = GF_4CC('I','M','U','D'), 959 GF_PROP_PID_ISOM_HANDLER = GF_4CC('I','H','D','L'), 960 GF_PROP_PID_ISOM_TRACK_FLAGS = GF_4CC('I','T','K','F'), 961 GF_PROP_PID_ISOM_TRACK_MATRIX = GF_4CC('I','T','K','M'), 962 GF_PROP_PID_PERIOD_ID = GF_4CC('P','E','I','D'), 963 GF_PROP_PID_PERIOD_START = GF_4CC('P','E','S','T'), 964 GF_PROP_PID_PERIOD_DUR = GF_4CC('P','E','D','U'), 965 GF_PROP_PID_REP_ID = GF_4CC('D','R','I','D'), 966 GF_PROP_PID_AS_ID = GF_4CC('D','A','I','D'), 967 GF_PROP_PID_MUX_SRC = GF_4CC('M','S','R','C'), 968 GF_PROP_PID_DASH_MODE = GF_4CC('D','M','O','D'), 969 GF_PROP_PID_DASH_DUR = GF_4CC('D','D','U','R'), 970 GF_PROP_PID_DASH_MULTI_PID = GF_4CC('D','M','S','D'), 971 GF_PROP_PID_DASH_MULTI_PID_IDX = GF_4CC('D','M','S','I'), 972 GF_PROP_PID_DASH_MULTI_TRACK = GF_4CC('D','M','T','K'), 973 GF_PROP_PID_ROLE = GF_4CC('R','O','L','E'), 974 GF_PROP_PID_PERIOD_DESC = GF_4CC('P','D','E','S'), 975 GF_PROP_PID_AS_COND_DESC = GF_4CC('A','C','D','S'), 976 GF_PROP_PID_AS_ANY_DESC = GF_4CC('A','A','D','S'), 977 GF_PROP_PID_REP_DESC = GF_4CC('R','D','E','S'), 978 GF_PROP_PID_BASE_URL = GF_4CC('B','U','R','L'), 979 GF_PROP_PID_TEMPLATE = GF_4CC('D','T','P','L'), 980 GF_PROP_PID_START_NUMBER = GF_4CC('D','R','S','N'), 981 GF_PROP_PID_XLINK = GF_4CC('X','L','N','K'), 982 GF_PROP_PID_CLAMP_DUR = GF_4CC('D','C','M','D'), 983 GF_PROP_PID_HLS_PLAYLIST = GF_4CC('H','L','V','P'), 984 GF_PROP_PID_DASH_CUE = GF_4CC('D','C','U','E'), 985 GF_PROP_PID_DASH_SEGMENTS = GF_4CC('D','C','N','S'), 986 GF_PROP_PID_SINGLE_SCALE = GF_4CC('D','S','T','S'), 987 GF_PROP_PID_UDP = GF_4CC('P','U','D','P'), 988 989 GF_PROP_PID_PRIMARY_ITEM = GF_4CC('P','I','T','M'), 990 991 GF_PROP_PID_COLR_PRIMARIES = GF_4CC('C','P','R','M'), 992 GF_PROP_PID_COLR_TRANSFER = GF_4CC('C','T','R','C'), 993 GF_PROP_PID_COLR_MX = GF_4CC('C','M','X','C'), 994 GF_PROP_PID_COLR_RANGE = GF_4CC('C','F','R','A'), 995 GF_PROP_PID_COLR_CHROMALOC = GF_4CC('C','L','O','C'), 996 GF_PROP_PID_COLR_SPACE = GF_4CC('C','S','P','C'), 997 GF_PROP_PID_SRC_MAGIC = GF_4CC('P','S','M','G'), 998 GF_PROP_PID_TRACK_INDEX = GF_4CC('T','I','D','X'), 999 GF_PROP_NO_TS_LOOP = GF_4CC('N','T','S','L'), 1000 GF_PROP_PCK_FRAG_START = GF_4CC('P','F','R','B'), 1001 GF_PROP_PCK_FRAG_RANGE = GF_4CC('P','F','R','R'), 1002 GF_PROP_PCK_SIDX_RANGE = GF_4CC('P','F','S','R'), 1003 GF_PROP_PCK_MOOF_TEMPLATE = GF_4CC('M','F','T','P'), 1004 GF_PROP_PID_RAWGRAB = GF_4CC('P','G','R','B'), 1005 GF_PROP_PID_KEEP_AFTER_EOS = GF_4CC('P','K','A','E'), 1006 GF_PROP_PID_COVER_ART = GF_4CC('P','C','O','V'), 1007 //internal property indicating pointer to associated GF_DownloadSession 1008 GF_PROP_PID_DOWNLOAD_SESSION = GF_4CC('G','H','T','T') 1009 }; 1010 1011 /*! Block patching requirements for FILE pids, as signaled by GF_PROP_PID_DISABLE_PROGRESSIVE 1012 \hideinitializer 1013 */ 1014 enum 1015 { 1016 GF_PID_FILE_PATCH_NONE = 0, 1017 GF_PID_FILE_PATCH_REPLACE = 1, 1018 GF_PID_FILE_PATCH_INSERT = 2, 1019 }; 1020 1021 /*! Gets readable name of built-in property 1022 \param prop_4cc property built-in 4cc 1023 \return readable name 1024 */ 1025 const char *gf_props_4cc_get_name(u32 prop_4cc); 1026 1027 /*! Gets property type of built-in property 1028 \param prop_4cc property built-in 4cc 1029 \return property name 1030 */ 1031 u32 gf_props_4cc_get_type(u32 prop_4cc); 1032 1033 /*! Checks if two properties are equal 1034 \param p1 first property to compare 1035 \param p2 second property to compare 1036 \return GF_TRUE if properties are equal, GF_FALSE otherwise 1037 */ 1038 Bool gf_props_equal(const GF_PropertyValue *p1, const GF_PropertyValue *p2); 1039 1040 /*! Gets the readable name for a property type 1041 \param type property type 1042 \return readable name 1043 */ 1044 const char *gf_props_get_type_name(GF_PropType type); 1045 1046 /*! Gets the description for a property type 1047 \param type property type 1048 \return description 1049 */ 1050 const char *gf_props_get_type_desc(GF_PropType type); 1051 1052 /*! Gets the description type for a given property type name 1053 \param name property type name 1054 \return property type or GF_PROP_FORBIDEN 1055 */ 1056 GF_PropType gf_props_parse_type(const char *name); 1057 1058 1059 /*! Parses a property value from string 1060 \param type property type to parse 1061 \param name property name to parse (for logs) 1062 \param value string containing the value to parse 1063 \param enum_values string containig enum_values, or NULL. enum_values are used for unsigned int properties, take the form "a|b|c" and resolve to 0|1|2. 1064 \param list_sep_char value of the list seperator character to use 1065 \return the parsed property value 1066 */ 1067 GF_PropertyValue gf_props_parse_value(u32 type, const char *name, const char *value, const char *enum_values, char list_sep_char); 1068 1069 /*! Maximum string size to use when dumping a property*/ 1070 #define GF_PROP_DUMP_ARG_SIZE 100 1071 1072 /*! Dumps a property value to string 1073 \param att property value 1074 \param dump buffer holding the resulting value for types requiring string conversions (integers, ...) 1075 \param dump_data if set data will be dumped in hexadecimal. Otherwise, data buffer is not dumped 1076 \param min_max_enum optional, gives the min/max or enum string when the property is a filter argument 1077 \return string 1078 */ 1079 const char *gf_props_dump_val(const GF_PropertyValue *att, char dump[GF_PROP_DUMP_ARG_SIZE], Bool dump_data, const char *min_max_enum); 1080 1081 /*! Dumps a property value to string, resolving any built-in types (pix formats, codec id, ...) 1082 \param p4cc property 4CC 1083 \param att property value 1084 \param dump buffer holding the resulting value for types requiring string conversions (integers, ...) 1085 \param dump_data if set data will be dumped in hexadecimal. Otherwise, data buffer is not dumped 1086 \return string 1087 */ 1088 const char *gf_props_dump(u32 p4cc, const GF_PropertyValue *att, char dump[GF_PROP_DUMP_ARG_SIZE], Bool dump_data); 1089 1090 /*! Resets a property value, freeing allocated data or strings depending on the property type 1091 \param prop property 4CC 1092 */ 1093 void gf_props_reset_single(GF_PropertyValue *prop); 1094 1095 /*! Property aplies only to packets */ 1096 #define GF_PROP_FLAG_PCK 1 1097 /*! Property is optional for GPAC GSF serialization (not transmitted over network when property removal is enabled) */ 1098 #define GF_PROP_FLAG_GSF_REM 1<<1 1099 1100 /*! Structure describing a built-in property in GPAC*/ 1101 typedef struct { 1102 /*! identifier (4CC) */ 1103 u32 type; 1104 /*! name */ 1105 const char *name; 1106 /*! description */ 1107 const char *description; 1108 /*! data type (uint, float, etc ..) */ 1109 u8 data_type; 1110 /*! flags for the property */ 1111 u8 flags; 1112 } GF_BuiltInProperty; 1113 1114 /*! Gets property description 1115 \param prop_idx built-in property index, starting from 0 1116 \return associated property description or NULL if property was not found 1117 */ 1118 const GF_BuiltInProperty *gf_props_get_description(u32 prop_idx); 1119 1120 /*! Gets built-in property 4CC from name 1121 \param name built-in property name 1122 \return built-in property 4CC or 0 if not found 1123 */ 1124 u32 gf_props_get_id(const char *name); 1125 1126 /*! Gets flags of built-in property 1127 \param prop_4cc built-in property 4CC 1128 \return built-in property flags, 0 if not found 1129 */ 1130 u8 gf_props_4cc_get_flags(u32 prop_4cc); 1131 1132 /*! Helper macro to set signed int property */ 1133 #define PROP_SINT(_val) (GF_PropertyValue){.type=GF_PROP_SINT, .value.sint = _val} 1134 /*! Helper macro to set unsigned int property */ 1135 #define PROP_UINT(_val) (GF_PropertyValue){.type=GF_PROP_UINT, .value.uint = _val} 1136 /*! Helper macro to set long signed int property */ 1137 #define PROP_LONGSINT(_val) (GF_PropertyValue){.type=GF_PROP_LSINT, .value.longsint = _val} 1138 /*! Helper macro to set long unsigned int property */ 1139 #define PROP_LONGUINT(_val) (GF_PropertyValue){.type=GF_PROP_LUINT, .value.longuint = _val} 1140 /*! Helper macro to set boolean property */ 1141 #define PROP_BOOL(_val) (GF_PropertyValue){.type=GF_PROP_BOOL, .value.boolean = _val} 1142 /*! Helper macro to set fixed-point number property */ 1143 #define PROP_FIXED(_val) (GF_PropertyValue){.type=GF_PROP_FLOAT, .value.fnumber = _val} 1144 /*! Helper macro to set float property */ 1145 #define PROP_FLOAT(_val) (GF_PropertyValue){.type=GF_PROP_FLOAT, .value.fnumber = FLT2FIX(_val)} 1146 /*! Helper macro to set 32-bit fraction property from integers*/ 1147 #define PROP_FRAC_INT(_num, _den) (GF_PropertyValue){.type=GF_PROP_FRACTION, .value.frac.num = _num, .value.frac.den = _den} 1148 /*! Helper macro to set 32-bit fraction property*/ 1149 #define PROP_FRAC(_val) (GF_PropertyValue){.type=GF_PROP_FRACTION, .value.frac = _val } 1150 /*! Helper macro to set 64-bit fraction property from integers*/ 1151 #define PROP_FRAC64(_val) (GF_PropertyValue){.type=GF_PROP_FRACTION64, .value.lfrac = _val} 1152 /*! Helper macro to set 64-bit fraction property*/ 1153 #define PROP_FRAC64_INT(_num, _den) (GF_PropertyValue){.type=GF_PROP_FRACTION64, .value.lfrac.num = _num, .value.lfrac.den = _den} 1154 /*! Helper macro to set double property */ 1155 #define PROP_DOUBLE(_val) (GF_PropertyValue){.type=GF_PROP_DOUBLE, .value.number = _val} 1156 /*! Helper macro to set string property */ 1157 #define PROP_STRING(_val) (GF_PropertyValue){.type=GF_PROP_STRING, .value.string = (char *) _val} 1158 /*! Helper macro to set string property without string copy (string memory is owned by filter) */ 1159 #define PROP_STRING_NO_COPY(_val) (GF_PropertyValue){.type=GF_PROP_STRING_NO_COPY, .value.string = _val} 1160 /*! Helper macro to set name property */ 1161 #define PROP_NAME(_val) (GF_PropertyValue){.type=GF_PROP_NAME, .value.string = _val} 1162 /*! Helper macro to set data property */ 1163 #define PROP_DATA(_val, _len) (GF_PropertyValue){.type=GF_PROP_DATA, .value.data.ptr = _val, .value.data.size=_len} 1164 /*! Helper macro to set data property without data copy ( memory is owned by filter) */ 1165 #define PROP_DATA_NO_COPY(_val, _len) (GF_PropertyValue){.type=GF_PROP_DATA_NO_COPY, .value.data.ptr = _val, .value.data.size =_len} 1166 /*! Helper macro to set const data property */ 1167 #define PROP_CONST_DATA(_val, _len) (GF_PropertyValue){.type=GF_PROP_CONST_DATA, .value.data.ptr = _val, .value.data.size = _len} 1168 /*! Helper macro to set 2D float vector property */ 1169 #define PROP_VEC2(_val) (GF_PropertyValue){.type=GF_PROP_VEC2, .value.vec2 = _val} 1170 /*! Helper macro to set 2D integer vector property */ 1171 #define PROP_VEC2I(_val) (GF_PropertyValue){.type=GF_PROP_VEC2I, .value.vec2i = _val} 1172 /*! Helper macro to set 2D integer vector property from intergers*/ 1173 #define PROP_VEC2I_INT(_x, _y) (GF_PropertyValue){.type=GF_PROP_VEC2I, .value.vec2i.x = _x, .value.vec2i.y = _y} 1174 /*! Helper macro to set 3D float vector property */ 1175 #define PROP_VEC3(_val) (GF_PropertyValue){.type=GF_PROP_VEC3, .value.vec3 = _val} 1176 /*! Helper macro to set 3D integer vector property */ 1177 #define PROP_VEC3I(_val) (GF_PropertyValue){.type=GF_PROP_VEC3I, .value.vec3i = _val} 1178 /*! Helper macro to set 4D float vector property */ 1179 #define PROP_VEC4(_val) (GF_PropertyValue){.type=GF_PROP_VEC4, .value.vec4 = _val} 1180 /*! Helper macro to set 4D integer vector property */ 1181 #define PROP_VEC4I(_val) (GF_PropertyValue){.type=GF_PROP_VEC4I, .value.vec4i = _val} 1182 /*! Helper macro to set 4D integer vector property from integers */ 1183 #define PROP_VEC4I_INT(_x, _y, _z, _w) (GF_PropertyValue){.type=GF_PROP_VEC4I, .value.vec4i.x = _x, .value.vec4i.y = _y, .value.vec4i.z = _z, .value.vec4i.w = _w} 1184 /*! Helper macro to set pointer property */ 1185 #define PROP_POINTER(_val) (GF_PropertyValue){.type=GF_PROP_POINTER, .value.ptr = (void*)_val} 1186 1187 1188 /*! @} */ 1189 1190 1191 1192 1193 /*! 1194 \addtogroup fs_evt Filter Events 1195 \ingroup filters_grp 1196 \brief Filter Events 1197 1198 PIDs may receive commands and may emit messages using this system. 1199 1200 Events may flow downwards (towards the source), in which case they are commands, or upwards (towards the sink), in which case they are informative event. 1201 1202 A filter not implementing a process_event will result in the event being forwarded down to all input PIDs or up to all output PIDs. 1203 1204 A filter may decide to cancel an event, in which case the event is no longer forwarded down/up the chain. 1205 1206 GF_FEVT_PLAY, GF_FEVT_STOP and GF_FEVT_SOURCE_SEEK events will trigger a reset of PID buffers. 1207 1208 A GF_FEVT_PLAY event on a PID already playing is discarded. 1209 1210 A GF_FEVT_STOP event on a PID already stopped is discarded. 1211 1212 GF_FEVT_PLAY and GF_FEVT_SET_SPEED events will trigger larger (abs(speed)>1) or smaller (abs(speed)<1) PID buffer limit in blocking mode. 1213 1214 GF_FEVT_STOP and GF_FEVT_SOURCE_SEEK events are filtered to reset the PID buffers. 1215 1216 @{ 1217 */ 1218 1219 /*! Filter event types */ 1220 typedef enum 1221 { 1222 /*! PID control, usually triggered by sink - see \ref GF_FilterPidPlaybackMode*/ 1223 GF_FEVT_PLAY = 1, 1224 /*! PID speed control, usually triggered by sink - see \ref GF_FilterPidPlaybackMode*/ 1225 GF_FEVT_SET_SPEED, 1226 /*! PID control, usually triggered by sink - see \ref GF_FilterPidPlaybackMode*/ 1227 GF_FEVT_STOP, 1228 /*! PID pause, usually triggered by sink - see \ref GF_FilterPidPlaybackMode*/ 1229 GF_FEVT_PAUSE, 1230 /*! PID resume, usually triggered by sink - see \ref GF_FilterPidPlaybackMode*/ 1231 GF_FEVT_RESUME, 1232 /*! PID source seek, allows seeking in bytes the source*/ 1233 GF_FEVT_SOURCE_SEEK, 1234 /*! PID source switch, allows a source filter to switch its source URL for the same protocol*/ 1235 GF_FEVT_SOURCE_SWITCH, 1236 /*! DASH segment size info, sent down from muxers to manifest generators*/ 1237 GF_FEVT_SEGMENT_SIZE, 1238 /*! Scene attach event, sent down from compositor to filters (BIFS/OD/timedtext/any scene-related) to share the scene (resources and node graph)*/ 1239 GF_FEVT_ATTACH_SCENE, 1240 /*! Scene reset event, sent down from compositor to filters (BIFS/OD/timedtext/any scene-related) to indicate scene reset (resources and node graph). This is a direct filter call, only sent processed by filters running on the main thread*/ 1241 GF_FEVT_RESET_SCENE, 1242 /*! quality switching request event, helps filters decide how to adapt their processing*/ 1243 GF_FEVT_QUALITY_SWITCH, 1244 /*! visibility hint event, helps filters decide how to adapt their processing*/ 1245 GF_FEVT_VISIBILITY_HINT, 1246 /*! special event type sent to a filter whenever the PID info properties have been modified. No cancel because no forward - cf \ref gf_filter_pid_set_info. A filter returning GF_TRUE on this event will prevent info update notification on the destination filters*/ 1247 GF_FEVT_INFO_UPDATE, 1248 /*! buffer requirement event. This event is NOT sent to filters, it is internaly processed by the filter session. Filters may however send this 1249 event to indicate their buffereing preference (real-time sinks mostly)*/ 1250 GF_FEVT_BUFFER_REQ, 1251 /*! filter session capability change, sent whenever global capabilities (max width, max heoght, ... ) are changed*/ 1252 GF_FEVT_CAPS_CHANGE, 1253 /*! inidicates the PID could not be connected - the PID passed is an output PID of the filter, no specific event structure is associated*/ 1254 GF_FEVT_CONNECT_FAIL, 1255 /*! user event, sent from compositor/vout down to filters*/ 1256 GF_FEVT_USER, 1257 /*! PLAY hint event, used to signal if block dispatch is needed or not for the source*/ 1258 GF_FEVT_PLAY_HINT, 1259 /*! file delete event, sent upstream by dahser to notify file deletion*/ 1260 GF_FEVT_FILE_DELETE, 1261 } GF_FEventType; 1262 1263 /*! type: the type of the event*/ 1264 /*! on_pid: PID to which the event is targeted. If NULL the event is targeted at the whole filter */ 1265 #define FILTER_EVENT_BASE \ 1266 GF_FEventType type; \ 1267 GF_FilterPid *on_pid; \ 1268 \ 1269 1270 1271 /*! Macro helper for event structure initializing*/ 1272 #define GF_FEVT_INIT(_a, _type, _on_pid) { memset(&_a, 0, sizeof(GF_FilterEvent)); _a.base.type = _type; _a.base.on_pid = _on_pid; } 1273 1274 /*! Base type of events. All events start with the fields defined in \ref FILTER_EVENT_BASE*/ 1275 typedef struct 1276 { 1277 FILTER_EVENT_BASE 1278 } GF_FEVT_Base; 1279 1280 /*! Event structure for GF_FEVT_PLAY, GF_FEVT_SET_SPEED*/ 1281 typedef struct 1282 { 1283 FILTER_EVENT_BASE 1284 1285 /*! params for : ranges in sec - if range is <0, it means end of file (eg [2, -1] with speed>0 means 2 +oo) */ 1286 Double start_range, end_range; 1287 /*! params for GF_NET_CHAN_PLAY and GF_NET_CHAN_SPEED*/ 1288 Double speed; 1289 1290 /*! indicates playback should start from given packet number - used by dasher when reloading sources*/ 1291 u32 from_pck; 1292 1293 /*! set when PLAY event is sent upstream to audio out, indicates HW buffer reset*/ 1294 u8 hw_buffer_reset; 1295 /*! params for GF_FEVT_PLAY only: indicates this is the first PLAY on an element inserted from bcast*/ 1296 u8 initial_broadcast_play; 1297 /*! params for GF_NET_CHAN_PLAY only 1298 0: range is in media time 1299 1: range is in timesatmps 1300 2: range is in media time but timestamps should not be shifted (hybrid dash only for now) 1301 */ 1302 u8 timestamp_based; 1303 /*! indicates the consumer only cares for the full file, not packets*/ 1304 u8 full_file_only; 1305 /*! indicates any current download should be aborted*/ 1306 u8 forced_dash_segment_switch; 1307 /*! indicates non ref frames should be drawn for faster processing*/ 1308 u8 drop_non_ref; 1309 /*! indicates that a demuxer must not forward this event as a source seek because seek has already been done 1310 (typically this play request is a segment play and byte range access within the file has already been performed by DASH client)*/ 1311 u8 no_byterange_forward; 1312 } GF_FEVT_Play; 1313 1314 /*! Event structure for GF_FEVT_SOURCE_SEEK and GF_FEVT_SOURCE_SWITCH*/ 1315 typedef struct 1316 { 1317 FILTER_EVENT_BASE 1318 1319 /*! start offset in source*/ 1320 u64 start_offset; 1321 /*! end offset in source*/ 1322 u64 end_offset; 1323 /*! new path to switch to*/ 1324 const char *source_switch; 1325 /*! indicates previous source was a DASH init segment and should be kept in memory cache*/ 1326 u8 previous_is_init_segment; 1327 /*! ignore cache expiration directive for HTTP*/ 1328 u8 skip_cache_expiration; 1329 /*! hint block size for source, might not be respected*/ 1330 u32 hint_block_size; 1331 } GF_FEVT_SourceSeek; 1332 1333 /*! Event structure for GF_FEVT_SEGMENT_SIZE*/ 1334 typedef struct 1335 { 1336 FILTER_EVENT_BASE 1337 /*! URL of segment this info is for, or NULL if single file*/ 1338 const char *seg_url; 1339 /*! global sidx is signaled using is_init=1 and range in idx range*/ 1340 Bool is_init; 1341 /*! media start range in segment file*/ 1342 u64 media_range_start; 1343 /*! media end range in segment file*/ 1344 u64 media_range_end; 1345 /*! index start range in segment file*/ 1346 u64 idx_range_start; 1347 /*! index end range in segment file*/ 1348 u64 idx_range_end; 1349 } GF_FEVT_SegmentSize; 1350 1351 /*! Event structure for GF_FEVT_ATTACH_SCENE and GF_FEVT_RESET_SCENE 1352 For GF_FEVT_RESET_SCENE, THIS IS A DIRECT FILTER CALL NOT THREADSAFE, filters processing this event SHALL run on the main thread*/ 1353 typedef struct 1354 { 1355 FILTER_EVENT_BASE 1356 /*! Pointer to a GF_ObjectManager structure for this PID*/ 1357 void *object_manager; 1358 } GF_FEVT_AttachScene; 1359 1360 /*! Event structure for GF_FEVT_QUALITY_SWITCH*/ 1361 typedef struct 1362 { 1363 FILTER_EVENT_BASE 1364 1365 /*! switch quality up or down */ 1366 Bool up; 1367 /*! 0: current group, otherwise index of the depending_on group */ 1368 u32 dependent_group_index; 1369 /*! index of the quality to switch, as indicated in "has:qualities" property. If < 0, sets to automatic quality switching*/ 1370 s32 q_idx; 1371 /*! 1+tile mode adaptation (does not change other selections) */ 1372 u32 set_tile_mode_plus_one; 1373 /*! quality degradation hint, between 0 (full quality) and 100 (lowest quality, stream not currently rendered)*/ 1374 u32 quality_degradation; 1375 } GF_FEVT_QualitySwitch; 1376 1377 /*! Event structure for GF_FEVT_USER*/ 1378 typedef struct 1379 { 1380 FILTER_EVENT_BASE 1381 /*! GF_Event structure*/ 1382 GF_Event event; 1383 } GF_FEVT_Event; 1384 1385 /*! Event structure for GF_FEVT_FILE_DELETE*/ 1386 typedef struct 1387 { 1388 FILTER_EVENT_BASE 1389 /*! URL to delete*/ 1390 const char *url; 1391 } GF_FEVT_FileDelete; 1392 1393 /*! Event structure for GF_FEVT_VISIBILITY_HINT*/ 1394 typedef struct 1395 { 1396 FILTER_EVENT_BASE 1397 /*! gives minimun and maximum coordinates of the visible rectangle associated with channels. min_x may be greater than max_x in case of 360 videos */ 1398 u32 min_x, max_x, min_y, max_y; 1399 /*! if set, only min_x, min_y are used and indicate the gaze direction in pixels in the visual with/height frame (0,0) being top-left*/ 1400 Bool is_gaze; 1401 } GF_FEVT_VisibililityHint; 1402 1403 1404 /*! Event structure for GF_FEVT_BUFFER_REQ*/ 1405 typedef struct 1406 { 1407 FILTER_EVENT_BASE 1408 /*! indicates the max buffer to set on PID - the buffer is only activated on PIDs connected to decoders*/ 1409 u32 max_buffer_us; 1410 /*! indicates the max playout buffer to set on PID (buffer level triggering playback) 1411 Note: this is not used internally by the blocking mechanisms, but may be needed by other filters to take decisions 1412 */ 1413 u32 max_playout_us; 1414 /*! indicates the min playout buffer to set on PID (buffer level triggering rebuffering) 1415 Note: this is not used internally by the blocking mechanisms, but may be needed by other filters to take decisions 1416 */ 1417 u32 min_playout_us; 1418 /*! if set, only the PID target of the event will have the buffer req set; otherwise, the buffer requirement event is passed down the chain until a raw media PID is found or a decoder is found. Used for muxers*/ 1419 Bool pid_only; 1420 } GF_FEVT_BufferRequirement; 1421 1422 /*! Event object*/ 1423 union __gf_filter_event 1424 { 1425 GF_FEVT_Base base; 1426 GF_FEVT_Play play; 1427 GF_FEVT_SourceSeek seek; 1428 GF_FEVT_AttachScene attach_scene; 1429 GF_FEVT_Event user_event; 1430 GF_FEVT_QualitySwitch quality_switch; 1431 GF_FEVT_VisibililityHint visibility_hint; 1432 GF_FEVT_BufferRequirement buffer_req; 1433 GF_FEVT_SegmentSize seg_size; 1434 GF_FEVT_FileDelete file_del; 1435 }; 1436 1437 /*! Gets readable name for event type 1438 \param type type of the event 1439 \return readable name of the event 1440 */ 1441 const char *gf_filter_event_name(GF_FEventType type); 1442 1443 /*! @} */ 1444 1445 1446 /*! 1447 \addtogroup fs_filter Filter 1448 \ingroup filters_grp 1449 \brief Filter 1450 1451 1452 The API for filters documents declaration of filters, their creation and functions available to interact with the filter session. 1453 The gf_filter_* functions shall only be called from within a given filter, this filter being the target of the function. This is not checked at runtime. 1454 1455 Calling these functions on other filters will result in unpredictable behaviour, very likely crashes in multi-threading conditions. 1456 1457 A filter is instanciated through a filter register. The register holds entry points to a filter, arguments of a filter (basically property values) and capabilities. 1458 1459 Capabilities are used to check if a filter can be connected to a given input PID, or if two filters can be directly connected (capability match). 1460 1461 Capabilities are organized in so-called bundles, gathering the caps that shall be present or not present in the PID / connecting filter. Typically a capability bundle 1462 will contain a stream type for input a stream type for output, a codec id for input and a codec id for output. 1463 1464 Several capability bundles can be used if needed. A good example is the writegen filter in GPAC, which simply transforms a sequence of media frames into a raw file, hence converts 1465 stream_type/codecID to file extension and MIME type - cf gpac/src/filters/write_generic.c 1466 1467 When resolving a chain, PID properties are checked against these capabilities. If a property of the same type exists in the PID than in the capability, 1468 it must match the capability requirement (equal, excluded). If no property exists for a given non-optional capability type, 1469 the bundle is marked as not matching and the ext capability bundle in the filter is checked. 1470 A PID property not listed in any capability of the filter does not impact the matching. 1471 1472 The GF_PROP_PID_FILE_EXT and GF_PROP_PID_MIME are handled as alternate to each other, this allows matching a PID if either its MIME or extension map and avoids failing if the pid has no MIME or extension set. 1473 @{ 1474 */ 1475 1476 1477 /*! Structure holding arguments for a filter*/ 1478 typedef enum 1479 { 1480 /*! used for GUI config: regular argument type */ 1481 GF_FS_ARG_HINT_NORMAL = 0, 1482 /*! used for GUI config: advanced argument type */ 1483 GF_FS_ARG_HINT_ADVANCED = 1<<1, 1484 /*! used for GUI config: expert argument type */ 1485 GF_FS_ARG_HINT_EXPERT = 1<<2, 1486 /*! used for GUI config: hidden argument type */ 1487 GF_FS_ARG_HINT_HIDE = 1<<3, 1488 /*! if set indicates that the argument is updatable. If so, the value will be changed if offset_in_private is valid, and the update_args function will be called if not NULL*/ 1489 GF_FS_ARG_UPDATE = 1<<4, 1490 /*! used by meta filters (ffmpeg & co) to indicate the parsing is handled by the filter in which case the type is overloaded to string and passed to the update_args function*/ 1491 GF_FS_ARG_META = 1<<5, 1492 /*! internal flag used by meta filters (ffmpeg & co) to indicate the description of the argument is a dynamic allocated memory*/ 1493 GF_FS_ARG_META_ALLOC = 1<<6, 1494 } GF_FSArgumentFlags; 1495 1496 /*! Structure holding arguments for a filter*/ 1497 typedef struct 1498 { 1499 /*! argument name. Naming conventions: 1500 - only use lowercase 1501 - keep short and avoid '_' 1502 */ 1503 const char *arg_name; 1504 /*! offset of the argument in the structure, -1 means not exposed/stored in structure, in which case it is notified through the update_arg function. 1505 The offset is casted into the corresponding property value of the argument type*/ 1506 s32 offset_in_private; 1507 /*! description of argument. Format conventions: 1508 - first letter is lowercase except if it is an acronym (eg, 'IP'). 1509 - description does not end with a '.'; multiple sentences are however allowed with '.' separators. 1510 - description does not end with a new line CR or LF; multiple sentences are however allowed with '.' separators. 1511 - keep it short. If too long, use " - see filter help" and put description in filter help. 1512 - only use markdown '`' and '*', except for enumeration lists which shall use "- ". 1513 - do not use CR/LF in description except to start enum types description. 1514 - use infinitive (eg \"set foo to bar\" and not \"sets foo to bar\"). 1515 - Enumerations should be described as: 1516 sentence(s)'\n' (no '.' nor ':' at end) 1517 - name1: val'\n' (no '.' at end) 1518 - nameN: val (no '.' nor '\n' at end of last value description) 1519 and enum value description order shall match enum order 1520 - links are allowed, see GF_FilterRegister doc 1521 */ 1522 const char *arg_desc; 1523 /*! type of argument - this is a property type*/ 1524 GF_PropType arg_type; 1525 /*! default value of argument, can be NULL (for number types, value 0 for each dimension of the type is assumed)*/ 1526 const char *arg_default_val; 1527 /*! string describing an enum (unsigned integer type) or a min/max value. 1528 For min/max, the syntax is "min,max", with -I = -infinity and +I = +infinity 1529 For enum, the syntax is "a|b|...", resoling in a=0, b=1,... To skip a value insert '|' eg "|a|b" resolves to a=1, b=2, "a||b" resolves to a=0, b=2 1530 1531 Naming conventions for enumeration: 1532 - use single word 1533 - use lowercase escept for single/double characters name (eg 'A', 'V'). 1534 */ 1535 const char *min_max_enum; 1536 /*! set of argument flags*/ 1537 GF_FSArgumentFlags flags; 1538 } GF_FilterArgs; 1539 1540 /*! Shortcut macro to assign singed integer capability type*/ 1541 #define CAP_SINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_SINT, .value.sint = _b}, .flags=(_f) } 1542 /*! Shortcut macro to assign unsigned integer capability type*/ 1543 #define CAP_UINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f) } 1544 /*! Shortcut macro to assign signed long integer capability type*/ 1545 #define CAP_LSINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_LSINT, .value.longsint = _b}, .flags=(_f) } 1546 /*! Shortcut macro to assign unsigned long integer capability type*/ 1547 #define CAP_LUINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_LUINT, .value.longuint = _b}, .flags=(_f) } 1548 /*! Shortcut macro to assign boolean capability type*/ 1549 #define CAP_BOOL(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_BOOL, .value.boolean = _b}, .flags=(_f) } 1550 /*! Shortcut macro to assign fixed-point number capability type*/ 1551 #define CAP_FIXED(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = _b}, .flags=(_f) } 1552 /*! Shortcut macro to assign float capability type*/ 1553 #define CAP_FLOAT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = FLT2FIX(_b)}, .flags=(_f) } 1554 /*! Shortcut macro to assign 32-bit fraction capability type*/ 1555 #define CAP_FRAC_INT(_f, _a, _b, _c) { .code=_a, .val={.type=GF_PROP_FRACTION, .value.frac.num = _b, .value.frac.den = _c}, .flags=(_f) } 1556 /*! Shortcut macro to assign 32-bit fraction capability type from integers*/ 1557 #define CAP_FRAC(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FRACTION, .value.frac = _b}, .flags=(_f) } 1558 /*! Shortcut macro to assign double capability type*/ 1559 #define CAP_DOUBLE(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_DOUBLE, .value.number = _b}, .flags=(_f) } 1560 /*! Shortcut macro to assign name (const string) capability type*/ 1561 #define CAP_NAME(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_NAME, .value.string = _b}, .flags=(_f) } 1562 /*! Shortcut macro to assign string capability type*/ 1563 #define CAP_STRING(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_STRING, .value.string = _b}, .flags=(_f) } 1564 /*! Shortcut macro to assign unsigned integer capability type with capability priority*/ 1565 #define CAP_UINT_PRIORITY(_f, _a, _b, _p) { .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f), .priority=_p} 1566 1567 /*! Flags for filter capabilities*/ 1568 enum 1569 { 1570 /*! when not set, indicates the start of a new set of capabilities. Set by default by the generic GF_CAPS_* */ 1571 GF_CAPFLAG_IN_BUNDLE = 1, 1572 /*! if set this is an input capability of the bundle*/ 1573 GF_CAPFLAG_INPUT = 1<<1, 1574 /*! if set this is an output capability of the bundle. A capability can be declared both as input and output. For example stream type is usually the same on both inputs and outputs*/ 1575 GF_CAPFLAG_OUTPUT = 1<<2, 1576 /*! when set, the capability is valid if the value does not match. If an excluded capability is not found in the destination PID, it is assumed to match*/ 1577 GF_CAPFLAG_EXCLUDED = 1<<3, 1578 /*! when set, the capability is validated only for filter loaded for this destination filter*/ 1579 GF_CAPFLAG_LOADED_FILTER = 1<<4, 1580 /*! Only used for output capabilities, indicates that this capability applies to all bundles. This avoids repeating capabilities common to all bundles by setting them only in the first*/ 1581 GF_CAPFLAG_STATIC = 1<<5, 1582 /*! Only used for input capabilities, indicates that this capability is optional in the input PID */ 1583 GF_CAPFLAG_OPTIONAL = 1<<6, 1584 }; 1585 1586 /*! Shortcut macro to set for input capability flags*/ 1587 #define GF_CAPS_INPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT) 1588 /*! Shortcut macro to set for optional input capability flags*/ 1589 #define GF_CAPS_INPUT_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OPTIONAL) 1590 /*! Shortcut macro to set for static input capability flags*/ 1591 #define GF_CAPS_INPUT_STATIC (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_STATIC) 1592 /*! Shortcut macro to set for static optional input capability flags*/ 1593 #define GF_CAPS_INPUT_STATIC_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_STATIC|GF_CAPFLAG_OPTIONAL) 1594 /*! Shortcut macro to set for excluded input capability flags*/ 1595 #define GF_CAPS_INPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_EXCLUDED) 1596 /*! Shortcut macro to set for input for loaded filter only capability flags*/ 1597 #define GF_CAPS_INPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_LOADED_FILTER) 1598 /*! Shortcut macro to set for output capability flags*/ 1599 #define GF_CAPS_OUTPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT) 1600 /*! Shortcut macro to set for output for loaded filter only capability flags*/ 1601 #define GF_CAPS_OUTPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_LOADED_FILTER) 1602 /*! Shortcut macro to set for excluded output capability flags*/ 1603 #define GF_CAPS_OUTPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_EXCLUDED) 1604 /*! Shortcut macro to set for static output capability flags*/ 1605 #define GF_CAPS_OUTPUT_STATIC (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_STATIC) 1606 /*! Shortcut macro to set for excluded static output capability flags*/ 1607 #define GF_CAPS_OUTPUT_STATIC_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_EXCLUDED|GF_CAPFLAG_STATIC) 1608 /*! Shortcut macro to set for input and output capability flags*/ 1609 #define GF_CAPS_INPUT_OUTPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OUTPUT) 1610 /*! Shortcut macro to set for optional input and output capability flags*/ 1611 #define GF_CAPS_INPUT_OUTPUT_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_OPTIONAL) 1612 1613 /*! Filter capability description*/ 1614 typedef struct 1615 { 1616 /*! 4cc of the capability listed. This shall be 0 or the type of a built-in property */ 1617 u32 code; 1618 /*! default type and value of the capability listed*/ 1619 GF_PropertyValue val; 1620 /*! name of the capability listed, NULL if code is set. The special value * is used to indicate that the capability is solved at runtime (the filter must be loaded)*/ 1621 const char *name; 1622 /*! Flags of the capability*/ 1623 u32 flags; 1624 /*! overrides the filter register priority for this capability. Usually 0*/ 1625 u8 priority; 1626 } GF_FilterCapability; 1627 1628 /*! Filter session capability structure*/ 1629 typedef struct 1630 { 1631 u32 max_screen_width; 1632 u32 max_screen_height; 1633 u32 max_screen_bpp; 1634 u32 max_screen_fps; 1635 u32 max_screen_nb_views; 1636 u32 max_audio_channels; 1637 u32 max_audio_sample_rate; 1638 u32 max_audio_bit_depth; 1639 } GF_FilterSessionCaps; 1640 1641 /*! Gets filter session capability 1642 \param filter source of the query - avoids fetching the filter session object 1643 \param caps pointer filled with caps 1644 */ 1645 void gf_filter_get_session_caps(GF_Filter *filter, GF_FilterSessionCaps *caps); 1646 1647 /*! Sets filter session capability 1648 \param filter source of the query - avoids fetching the filter session object 1649 \param caps session capability new values - completely replace the old ones 1650 */ 1651 void gf_filter_set_session_caps(GF_Filter *filter, GF_FilterSessionCaps *caps); 1652 1653 /*! Filter probe score, used when probing a URL/MIME or when probing formats from data*/ 1654 typedef enum 1655 { 1656 /*! (de)mux format is not supported*/ 1657 GF_FPROBE_NOT_SUPPORTED = 0, 1658 /*! (de)mux format is supported with potentially missing features*/ 1659 GF_FPROBE_MAYBE_SUPPORTED, 1660 /*! (de)mux format is supported*/ 1661 GF_FPROBE_SUPPORTED, 1662 /*! demux format should be handled by this filter*/ 1663 GF_FPROBE_FORCE, 1664 /*! used by demux formats not supporting data prober*/ 1665 GF_FPROBE_EXT_MATCH, 1666 } GF_FilterProbeScore; 1667 1668 /*! Quick macro for assigning the capability arrays to the register structure*/ 1669 #define SETCAPS( __struct ) .caps = __struct, .nb_caps=sizeof(__struct)/sizeof(GF_FilterCapability) 1670 1671 #ifndef GPAC_DISABLE_DOC 1672 /*! Macro for assigning filter register description*/ 1673 #define GF_FS_SET_DESCRIPTION(_desc) .description = _desc, 1674 /*! Macro for assigning filter register author*/ 1675 #define GF_FS_SET_AUTHOR(_author) .author = _author, 1676 /*! Macro for assigning filter register help*/ 1677 #define GF_FS_SET_HELP(_help) .help = _help, 1678 /*! Macro for assigning filter register argument types and description*/ 1679 #define GF_FS_DEF_ARG(_name, _offset, _desc, _type, _default, _enum, _flags) { _name, _offset, _desc, _type, _default, _enum, _flags } 1680 #else 1681 #define GF_FS_SET_DESCRIPTION(_desc) 1682 #define GF_FS_SET_AUTHOR(_author) 1683 #define GF_FS_SET_HELP(_help) 1684 #define GF_FS_SET_ARGHELP(_help) 1685 #define GF_FS_DEF_ARG(_name, _offset, _desc, _type, _default, _enum, _flags) {_name, _offset, _type, _default, _enum, _flags} 1686 #endif 1687 1688 /*! Filter register flags*/ 1689 typedef enum 1690 { 1691 /*! when set indicates all calls shall take place in the main thread (running GL output) - to be refined*/ 1692 GF_FS_REG_MAIN_THREAD = 1<<1, 1693 /*! when set indicates the initial call to configure_pid will happen in the main thread. This is typically called by decoders requiring 1694 a GL context (currently only in main thread) upon init, but not requiring it for the decode. Such decoders get their GL frames mapped 1695 (through get_gl_texture callback) in the main GL thread*/ 1696 GF_FS_REG_CONFIGURE_MAIN_THREAD = 1<<2, 1697 /*! when set indicates the filter does not take part of dynamic filter chain resolution and can only be used by explicitly loading the filter*/ 1698 GF_FS_REG_EXPLICIT_ONLY = 1<<3, 1699 /*! when set ignores the filter weight during link resolution - this is typically needed by decoders requiring a specific reframing so that the weight of the reframer+decoder is the same as the weight of other decoders*/ 1700 GF_FS_REG_HIDE_WEIGHT = 1<<4, 1701 /*! Usually set for filters acting as sources but without exposing an src argument. This prevents throwing warnings on arguments not handled by the filter*/ 1702 GF_FS_REG_ACT_AS_SOURCE = 1<<5, 1703 /*! Indicates the filter is likely to block for a long time (typically, network IO). 1704 In multithread mode, this prevents the filter to be scheduled on the main thread, blocking video or audio output. 1705 Ignored in single thread mode.*/ 1706 GF_FS_REG_BLOCKING = 1<<6, 1707 /*! Indicates the filter PIDs may be dynamically added during process (e.g.M2TS, GSF, etc). 1708 This will prevent deactivating a filter when none of its output PIDs are connected*/ 1709 GF_FS_REG_DYNAMIC_PIDS = 1<<7, 1710 /*! Indicates the filter is a script-based filter. The registry is not valid until the script is loaded*/ 1711 GF_FS_REG_SCRIPT = 1<<8, 1712 /*! Indicates the filter is a meta filter, wrapping various underlying filters (e.g., FFmpeg)*/ 1713 GF_FS_REG_META = 1<<9, 1714 /*! Indicates that this filter, when dynamically loaded, allows the link resolver to redirect PID connection to this filter rather than to its next explicetly loaded filter in the chain. 1715 This is typically used by mux filters 1716 */ 1717 GF_FS_REG_DYNAMIC_REDIRECT = 1<<10, 1718 /*! Indicates the filter requires graph resolver (typically because it creates new destinations/sinks at run time)*/ 1719 GF_FS_REG_REQUIRES_RESOLVER = 1<<11, 1720 1721 /*! flag dynamically set at runtime for registries loaded through shared libraries*/ 1722 GF_FS_REG_DYNLIB = 0x80000000 1723 } GF_FSRegisterFlags; 1724 1725 /*! The filter register. Registries are loaded once at the start of the session and shall never be modified after that. 1726 If capabilities need to be changed for a specific filter, use \ref gf_filter_override_caps*/ 1727 struct __gf_filter_register 1728 { 1729 /*! mandatory - name of the filter as used when setting up filters. Naming conventions: 1730 - shall not contain any space (breaks filter lookup) 1731 - should use lowercase 1732 - should not use '_' 1733 */ 1734 const char *name; 1735 /*! optional - size of private stack structure. The structure is allocated by the framework and arguments are setup before calling any of the filter functions*/ 1736 u32 private_size; 1737 /*! indicates the max number of additional input PIDs - muxers and scalable filters typically set this to (u32) -1. A value of 0 implies the filter can only handle one PID*/ 1738 u32 max_extra_pids; 1739 /*! set of register flags*/ 1740 GF_FSRegisterFlags flags; 1741 1742 /*! list of PID capabilities*/ 1743 const GF_FilterCapability *caps; 1744 /*! number of PID capabilities*/ 1745 u32 nb_caps; 1746 1747 /*! optional - filter arguments if any*/ 1748 const GF_FilterArgs *args; 1749 1750 /*! mandatory - callback for filter processing 1751 This function is called whenever packets are available on the input PID and buffer space is available on the output. 1752 The session will by default monitor a filter for errors, and throw en error if a filter is not consuming nor producing packets for a given amount of process calls. 1753 In some cases, it might be needed to not consume nor produce a packet for a given time (for example, waiting for a packet drop before reconfiguring a filter). 1754 A filter must signal this using \ref gf_filter_ask_rt_reschedule, possibly with no timeout. 1755 1756 A filter may return GF_EOS to indicate no more data is expected to be produced by this filter 1757 1758 A filter may return GF_PROFILE_NOT_SUPPORTED to indicate that the filter is not supported (when unable to detect this at configure) and trigger a relink of the filter graph unless disabled at session level. 1759 */ 1760 GF_Err (*process)(GF_Filter *filter); 1761 1762 /*! optional for sources, mandatory for filters and sinks - callback for PID update may be called several times 1763 on the same PID if PID config is changed. 1764 Since discontinuities may happen at any time, and a filter may fetch packets in burst, 1765 this function may be called while the filter is calling \ref gf_filter_pid_get_packet (this is the only reentrant call for filters) 1766 1767 \param filter the target filter 1768 \param PID the input PID to configure 1769 \param is_remove indicates the input PID is removed 1770 \return error if any. 1771 a return error of GF_REQUIRES_NEW_INSTANCE indicates the PID cannot be processed in this instance but could be in a clone of the filter. 1772 a return error of GF_FILTER_NOT_SUPPORTED indicates the PID cannot be processed and no alternate chain resolution would help 1773 a return error of GF_BAD_PARAM indicates the PID cannot be processed and no alternate chain resolution would help, and throws a log error message 1774 ano other return error will trigger a reconfigure of the chain to find another filter unless disabled at session level. 1775 */ 1776 GF_Err (*configure_pid)(GF_Filter *filter, GF_FilterPid *PID, Bool is_remove); 1777 1778 /*! optional - callback for filter initialization - private stack of filter is allocated by framework) 1779 \param filter the target filter 1780 \return error if any. A filter may return GF_EOS to indicate the filter session shall not be run, but that no error should be thrown (used by dasher in realtime regulation mode) 1781 */ 1782 GF_Err (*initialize)(GF_Filter *filter); 1783 1784 /*! optional - callback for filter desctruction - private stack of filter is freed by framework 1785 \param filter the target filter 1786 */ 1787 void (*finalize)(GF_Filter *filter); 1788 1789 /*! optional - callback for arguments update. If GF_OK is returned, the filter private stack is updated accordingly. 1790 If function is NULL, all updatable arguments will be changed in the filter private stack without the filter being notified. 1791 If argument is a meta argument, it is the filter responsability to handle the update, as meta arguments do not live on the filter provate stack. 1792 If the filter is a meta filter and argument is not declared in the argument list, the function is always called. 1793 1794 \param filter the target filter 1795 \param arg_name the name of the argument being set 1796 \param new_val the value of the argument being set 1797 \return error if any, GF_NOT_FOUND to silently disable argument value change. 1798 */ 1799 GF_Err (*update_arg)(GF_Filter *filter, const char *arg_name, const GF_PropertyValue *new_val); 1800 1801 /*! optional - process a given event. Retruns TRUE if the event has to be canceled, FALSE otherwise 1802 If a downstream (towards source) event is not canceled, it will be forwarded to each input PID of the filter. 1803 If you need to forward the event only to one input pid, send a copy of the event to the desired input and cancel the event. 1804 \param filter the target filter 1805 \param evt the event to process 1806 \return GF_TRUE if the event should be canceled, GF_FALSE otherwise 1807 */ 1808 Bool (*process_event)(GF_Filter *filter, const GF_FilterEvent *evt); 1809 1810 /*! optional - Called whenever an output PID needs format renegotiaition. If not set, a filter chain will be loaded to solve the negotiation 1811 1812 \param filter the target filter 1813 \param PID the filter output PID being reconfigured 1814 \return error code if any 1815 */ 1816 GF_Err (*reconfigure_output)(GF_Filter *filter, GF_FilterPid *PID); 1817 1818 /*! optional, mostly used for source filters and destination filters - probe the given URL, returning a score. 1819 This function is called before opening the source (no data received yet) 1820 1821 \param url the url of the source to probe, never NULL. 1822 \param mime the MIME type of the source to probe. Can be NULL if mime not available at probe type 1823 \return probe score 1824 */ 1825 GF_FilterProbeScore (*probe_url)(const char *url, const char *mime); 1826 1827 /*! optional, usually set by demuxers. This function probes the mime type of a data chunk, usually located at the start of the file. 1828 This function is called once the source is open, but is never called on an instanciated filter. The returned mime type (if any) is then used instead of the file extension 1829 for solving filter graph. 1830 Note: demux filters should always exposed 2 input caps bundle, one for specifiying input cap by file extension and one for specifying input cap by mime type. 1831 \param data data to probe 1832 \param size size of the data to probe 1833 \param score set to the probe score. Initially set to \ref GF_FPROBE_NOT_SUPPORTED before calling the function. If you are certain of the data type, use \ref GF_FPROBE_SUPPORTED, if unsure use \ref GF_FPROBE_MAYBE_SUPPORTED. If the format cannot be probed (bad design), set it to \ref GF_FPROBE_EXT_MATCH 1834 \return mime type of content, list of known extensions for the format if score is set to GF_FPROBE_EXT_MATCH, or NULL if not detected. 1835 */ 1836 const char * (*probe_data)(const u8 *data, u32 size, GF_FilterProbeScore *score); 1837 1838 /*! for filters having the same match of input capabilities for a PID, the filter with priority at the lowest value will be used 1839 scalable decoders should use high values, so that they are only selected when enhancement layers are present*/ 1840 u8 priority; 1841 1842 /*! optional for dynamic filter registries. Dynamic registries may declare any number of registries. The register_free function will be called to cleanup any allocated memory 1843 1844 \param session the filter session 1845 \param freg the filter register to destroy 1846 */ 1847 void (*register_free)(GF_FilterSession *session, struct __gf_filter_register *freg); 1848 /*! user data of register loader, not inspected/modified by filter session*/ 1849 void *udta; 1850 1851 /*! optional. Used by sink filters offering multiple sink support 1852 GPAC instantiates filter chains based on filter capabilities and arguments of source and destination. When a sink/destination filter can handle 1853 multiple file inputs of various formats/types, temporary filters called alias are needed to instantiate the proper chain. 1854 If the return value is true, an alias filter of the same type as this filter will be created with the proper arguments and initialized (in order to modify the 1855 alias filter capabilities if needed), and finalized when no longer needed. All other callbacks will however be made on the main filter, not the alias. 1856 1857 A good example is HTTP output of a DASH session: 1858 - the first PID will be a FILE stream for the manifest (MPD, M3U8), and the http output capabilities will be set to accept the manifest file extension.mime 1859 - the other PIDs will be media PIDs (mp4, ts, mkv ...) and won't match the filter instance, creating a new instance which we don't want 1860 1861 By creating filter alias, a temprary HTTP output (alias) will be created, holding the arguments for the chain (including destination type). Overloading the alias filter capabilities 1862 with the desired file extension or MIME will trigger the proper chain resolution. The alias will be switched to the final filter upon connecting the PIDs 1863 1864 To access original arguments of the chain, see \ref gf_filter_pid_get_alias_udta 1865 To check if an initialize callback targets the main filter or the temporary one, see \ref gf_filter_is_alias 1866 \param filter the target filter 1867 \param url the url of the target destination, never NULL. 1868 \param mime the MIME type of the target destination. Can be NULL if mime not available 1869 \return GF_TRUE if this filter instance should be used to handle the given URL, in which case an alias filter will be created 1870 */ 1871 Bool (*use_alias)(GF_Filter *filter, const char *url, const char *mime); 1872 1873 1874 /*! version of the filter, usually only for external libs 1875 Note: If this strings starts with "! " it indicates an error message at load time of the registry. This should only be set when \code gf_opts_get_bool("temp", "gendoc"); \endcode returns true, indicating the filter session is only loaded for documentation purposes (man/md generation and command line help). 1876 */ 1877 const char *version; 1878 #ifndef GPAC_DISABLE_DOC 1879 /*! short description of the filter. Conventions: 1880 - should be small (used to generate UI / documentation) 1881 - Should be Capitalized 1882 - shall not use markdown 1883 - shall be single line 1884 */ 1885 const char *description; 1886 /*! author of the filter. Conventions: 1887 - shall not use markdown 1888 - first line if present is author name and should be normally capitalized 1889 - second line if present is comma-separated list of contact info (eg http://foo.bar,mailto:foo@bar.com) 1890 */ 1891 const char *author; 1892 /*! help of the filter. Conventions: 1893 - describe any non-obvious behaviour of the filter here 1894 - markdown is allowed. Use '`' for code, "__" for italic, "**" for bold and "~~" for strikethrough. 1895 - mardown top-level sections shall use '#', second level '##', and so on 1896 - mardown bullet lists shall use "- ", " - " etc... 1897 - notes shall be identifed as a line starting with "Note: " 1898 - warnings shall be identifed as a line starting with "Warning: " 1899 - the sequence "[-" is reserved for option links. It is formated as: 1900 - "[-OPT]()": link to self page for option OPT 1901 - "[-OPT](LINK)": link to other page for option OPT. 1902 LINK can be: 1903 - GPAC: resolves to general GPAC help 1904 - CORE: resolves to general CORE help 1905 - LOG: resolves to general LOG help 1906 - ANY: resolves to filter with register name 'ANY' 1907 1908 Note that [text](ANY) with ANY a filter register name will link to that filter help page 1909 */ 1910 const char *help; 1911 #endif 1912 }; 1913 1914 1915 /*! Gets filter private stack - the stack is allocated and freed by the filter session, as are any arguments. The rest is up to the filter to delete it 1916 \param filter target filter 1917 \return filter private stack if any, NULL otherwise 1918 */ 1919 void *gf_filter_get_udta(GF_Filter *filter); 1920 1921 /*! Sets filter name - mostly used for logging purposes 1922 \param filter target filter 1923 \param name new name to assign. If NULL, name is reset to register name 1924 */ 1925 void gf_filter_set_name(GF_Filter *filter, const char *name); 1926 1927 /*! Gets filter name 1928 \param filter target filter 1929 \return name of the filter 1930 */ 1931 const char *gf_filter_get_name(GF_Filter *filter); 1932 1933 /*! Makes the filter sticky. A sticky filter is not removed when all its input PIDs are disconnected. Typically used by the player 1934 \param filter target filter 1935 */ 1936 void gf_filter_make_sticky(GF_Filter *filter); 1937 1938 /*! Return the number of queued events on the filter. Events are not aggregated, some filter may want to wait until all events are processed before taking actions. The function recursively goes up the filter chain and count queued events. 1939 \param filter target filter 1940 \return number of queued events 1941 */ 1942 u32 gf_filter_get_num_events_queued(GF_Filter *filter); 1943 1944 /*! Returns the single instance of GPAC download manager. DO NOT DESTROY IT!! 1945 \param filter target filter 1946 \return the GPAC download manager 1947 */ 1948 GF_DownloadManager *gf_filter_get_download_manager(GF_Filter *filter); 1949 1950 /*! Returns the single instance of GPAC font manager. DO NOT DESTROY IT!! 1951 \param filter target filter 1952 \return the GPAC font manager 1953 */ 1954 struct _gf_ft_mgr *gf_filter_get_font_manager(GF_Filter *filter); 1955 1956 /*! Asks task reschedule for a given delay. There is no guarantee that the task will be recalled at exactly the desired delay 1957 \param filter target filter 1958 \param us_until_next number of microseconds to wait before recalling this task 1959 */ 1960 void gf_filter_ask_rt_reschedule(GF_Filter *filter, u32 us_until_next); 1961 1962 /*! Posts a filter process task to the parent session. This is needed for some filters not having any input packets to process but still needing to work 1963 such as decoder flushes, servers, etc... The filter session will ignore this call if the filter is already scheduled for processing 1964 \param filter target filter 1965 */ 1966 void gf_filter_post_process_task(GF_Filter *filter); 1967 1968 /*! Posts a task to the session scheduler. This task is not a process task but the filter will still be called by a single thread at any time (ie, might delay process) 1969 \param filter target filter 1970 \param task_execute the callback function for the task. The callback can return GF_TRUE to reschedule the task, in which case the task will be rescheduled 1971 immediately or after reschedule_ms. 1972 \param udta user data passed back to the task function 1973 \param task_name name of the task for logging purposes 1974 \return error code if failure 1975 */ 1976 GF_Err gf_filter_post_task(GF_Filter *filter, Bool (*task_execute) (GF_Filter *filter, void *callback, u32 *reschedule_ms), void *udta, const char *task_name); 1977 1978 1979 /*! Sets callback function on source filter setup failure 1980 \param filter target filter 1981 \param source_filter the source filter to monitor 1982 \param on_setup_error callback function to call upon source setup error 1983 \param udta user data passed back to the task function 1984 */ 1985 void gf_filter_set_setup_failure_callback(GF_Filter *filter, GF_Filter *source_filter, void (*on_setup_error)(GF_Filter *f, void *on_setup_error_udta, GF_Err e), void *udta); 1986 1987 /*! Notify a filter setup error. This is typically called when a source filter or a filter having accepted input PIDs detects an issue. 1988 For a source filter (no input PID), the failure callback will be called if any, and the filter will be removed. 1989 For a connected filter, all input PIDs od the filter will be disconnected and the filter removed. 1990 \param filter target filter 1991 \param reason the failure reason code 1992 */ 1993 void gf_filter_setup_failure(GF_Filter *filter, GF_Err reason); 1994 1995 /*! Notify a filter fatal error but not a connection error. Typically, a 404 in HTTP. 1996 \param filter target filter 1997 \param reason the failure reason code 1998 \param force_disconnect indicates if the filter chain should be disconnected or not 1999 */ 2000 void gf_filter_notification_failure(GF_Filter *filter, GF_Err reason, Bool force_disconnect); 2001 2002 /*! Disconnects a source filter chain between two filters 2003 \param filter the calling filter. This filter is NOT disconnected 2004 \param src_filter the source filter point of the chain to disconnect. 2005 */ 2006 void gf_filter_remove_src(GF_Filter *filter, GF_Filter *src_filter); 2007 2008 /*! Disconnects a filter from fthe chain 2009 \param filter the filter to remove 2010 */ 2011 void gf_filter_remove(GF_Filter *filter); 2012 2013 /*! Sets the number of additional input PID a filter can accept. This overrides the default value of the filter register 2014 \param filter the target filter 2015 \param max_extra_pids the number of additional PIDs this filter can accept 2016 */ 2017 void gf_filter_set_max_extra_input_pids(GF_Filter *filter, u32 max_extra_pids); 2018 2019 /*! Gets the number of additional input PID a filter can accept. This overrides the default value of the filter register 2020 \param filter the target filter 2021 \return max_extra_pids the number of additional PIDs this filter can accept 2022 */ 2023 u32 gf_filter_get_max_extra_input_pids(GF_Filter *filter); 2024 2025 2026 /*! Queries if blocking mode is enabled for the filter 2027 \param filter the target filter 2028 \return GF_TRUE if blocking mode is enabled, GF_FALSE otherwise 2029 */ 2030 Bool gf_filter_block_enabled(GF_Filter *filter); 2031 2032 /*! Indicates the EOS status on input PIDs of this filter shall not be checked when probing for end of stream in the chain 2033 \param filter the target filter 2034 \param do_block if GF_TRUE, prevents EOS checking on input stream, otherwise enables it (default is FALSE upon creation) 2035 */ 2036 void gf_filter_block_eos(GF_Filter *filter, Bool do_block); 2037 2038 2039 /*! Connects a source to this filter. 2040 Note: 2041 Any filter loaded between the source and the calling filter will not use argument inheritance from the caller. 2042 2043 \param filter the target filter 2044 \param url url of source to connect to, with optional arguments. 2045 \param parent_url url of parent if any 2046 \param err return code - can be NULL 2047 \return the new source filter instance or NULL if error 2048 */ 2049 GF_Filter *gf_filter_connect_source(GF_Filter *filter, const char *url, const char *parent_url, GF_Err *err); 2050 2051 /*! Connects a destination to this filter 2052 \param filter the target filter 2053 \param url url of destination to connect to, with optional arguments. 2054 \param err return code - can be NULL 2055 \return the new destination filter instance or NULL if error 2056 */ 2057 GF_Filter *gf_filter_connect_destination(GF_Filter *filter, const char *url, GF_Err *err); 2058 2059 2060 /*! Loads a new filter in the session - see \ref gf_fs_load_filter 2061 \param filter the target filter 2062 \param name name and arguments of the filter register to instantiate. 2063 \param err_code error code if any 2064 \return created filter or NULL if filter register cannot be found 2065 */ 2066 GF_Filter *gf_filter_load_filter(GF_Filter *filter, const char *name, GF_Err *err_code); 2067 2068 /*! Checks if a source filter can handle the given URL. The source filter is not loaded. 2069 2070 \param filter the target filter 2071 \param url url of source to connect to, with optional arguments. 2072 \param parent_url url of parent if any 2073 \return GF_TRUE if a source filter can be found for this URL, GF_FALSE otherwise 2074 */ 2075 Bool gf_filter_is_supported_source(GF_Filter *filter, const char *url, const char *parent_url); 2076 2077 /*! Gets the number of input PIDs connected to a filter 2078 \param filter the target filter 2079 \return number of input PIDs 2080 */ 2081 u32 gf_filter_get_ipid_count(GF_Filter *filter); 2082 2083 /*! Gets an input PIDs connected to a filter 2084 \param filter the target filter 2085 \param idx index of the input PID to retrieve, between 0 and \ref gf_filter_get_ipid_count 2086 \return the input PID, or NULL if not found 2087 */ 2088 GF_FilterPid *gf_filter_get_ipid(GF_Filter *filter, u32 idx); 2089 2090 /*! Gets the number of output PIDs connected to a filter 2091 \param filter the target filter 2092 \return number of output PIDs 2093 */ 2094 u32 gf_filter_get_opid_count(GF_Filter *filter); 2095 2096 /*! Gets an output PIDs connected to a filter 2097 \param filter the target filter 2098 \param idx index of the output PID to retrieve, between 0 and \ref gf_filter_get_opid_count 2099 \return the output PID, or NULL if not found 2100 */ 2101 GF_FilterPid *gf_filter_get_opid(GF_Filter *filter, u32 idx); 2102 2103 /*! Queries buffer max limits on a filter. This is the max of buffer limits on all its connected outputs 2104 \param filter the target filter 2105 \param max_buf will be set to the maximum buffer duration in microseconds - may be NULL 2106 \param max_playout_buf will be set to the maximum playout buffer (the one triggering play) duration in microseconds - may be NULL 2107 */ 2108 void gf_filter_get_output_buffer_max(GF_Filter *filter, u32 *max_buf, u32 *max_playout_buf); 2109 2110 /*! Sets a clock state at session level indicating the time / timestamp of the last rendered frame. This is used by basic audio output 2111 \param filter the target filter 2112 \param time_in_us the system time in us, see \ref gf_sys_clock_high_res 2113 \param media_timestamp the media timestamp associated with this time. 2114 */ 2115 void gf_filter_hint_single_clock(GF_Filter *filter, u64 time_in_us, GF_Fraction64 media_timestamp); 2116 2117 /*! Retrieves the clock state at session level, as set by \ref gf_filter_hint_single_clock 2118 \param filter the target filter 2119 \param time_in_us will be set to the system time in us, see \ref gf_sys_clock_high_res - may be NULL 2120 \param media_timestamp will be set to the media timestamp associated with this time - may be NULL. 2121 */ 2122 void gf_filter_get_clock_hint(GF_Filter *filter, u64 *time_in_us, GF_Fraction64 *media_timestamp); 2123 2124 /*! Explicitly assigns a source ID to a filter. This shall be called before connecting the link_from filter 2125 If no ID is assigned to the linked filter, a dynamic one in the form of _%08X_ (using the filter mem address) will be used 2126 \param filter the target filter 2127 \param link_from the filter to link from 2128 \param link_ext any link extensions allowed in link syntax: 2129 \c \#PIDNAME: accepts only PID(s) with name PIDNAME 2130 \c \#TYPE: accepts only PIDs of matching media type. TYPE can be 'audio' 'video' 'scene' 'text' 'font' 2131 \c \#TYPEN: accepts only Nth PID of matching type from source 2132 \c \#P4CC=VAL: accepts only PIDs with property matching VAL. 2133 \c \#PName=VAL: same as above, using the built-in name corresponding to the property. 2134 \c \#P4CC-VAL: accepts only PIDs with property strictly less than VAL (only for 1-dimension number properties). 2135 \c \#P4CC+VAL: accepts only PIDs with property strictly greater than VAL (only for 1-dimension number properties). 2136 \return error code if any 2137 */ 2138 GF_Err gf_filter_set_source(GF_Filter *filter, GF_Filter *link_from, const char *link_ext); 2139 2140 /*! Explicitly reset sourceID of a filter. This shall be called before connecting the filter (eg creating PIDs). 2141 2142 This is mostly used to reset a source ID of a filter created from a destination (e.g., dasher creating muxers from the MPD URL) where the destination arguments could have sourceIDs specified/ 2143 2144 \param filter the target filter 2145 */ 2146 void gf_filter_reset_source(GF_Filter *filter); 2147 2148 /*! Explicitly assigns an ID to a filter. This shall be called before running the session, and cannot be called on a filter with ID assign 2149 \param filter the target filter 2150 \param filter_id the ID to assign. If NULL, a dynmic ID is generated 2151 \return error code if any 2152 */ 2153 GF_Err gf_filter_assign_id(GF_Filter *filter, const char *filter_id); 2154 2155 /*! Gets the ID of a filter 2156 \param filter the target filter 2157 \return ID of the filter, NULL if not defined 2158 */ 2159 const char *gf_filter_get_id(GF_Filter *filter); 2160 2161 2162 /*! Overrides the filter register caps with new caps for this instance. Typically used when an option of the filter changes the capabilities 2163 \param filter the target filter 2164 \param caps the new set of capabilities to use for the filter. These are NOT copied and shall be valid for the lifetime of the filter 2165 \param nb_caps number of capabilities set 2166 \return error code if any 2167 */ 2168 GF_Err gf_filter_override_caps(GF_Filter *filter, const GF_FilterCapability *caps, u32 nb_caps ); 2169 2170 /*! Filter session separator set query*/ 2171 typedef enum 2172 { 2173 /*! queries the character code used to separate between filter arguments*/ 2174 GF_FS_SEP_ARGS=0, 2175 /*! queries the character code used to separate between argument name and value*/ 2176 GF_FS_SEP_NAME, 2177 /*! queries the character code used to indicate fragment identifiers (source PIDs, PID properties)*/ 2178 GF_FS_SEP_FRAG, 2179 /*! queries the character code used to separate items in a list*/ 2180 GF_FS_SEP_LIST, 2181 /*! queries the character code used to negate values*/ 2182 GF_FS_SEP_NEG, 2183 } GF_FilterSessionSepType; 2184 2185 /*! Queries the character code used as a given separator type in argument names. Used for formating arguments when loading sources and destinations from inside a filter 2186 \param filter the target filter 2187 \param sep_type the separator type to query 2188 \return character code of the separator 2189 */ 2190 u8 gf_filter_get_sep(GF_Filter *filter, GF_FilterSessionSepType sep_type); 2191 2192 /*! Queries the arguments of the destination arguments. The first output PID connected to a filter with non NULL args will be used (this is a recursive check until end of chain) 2193 \param filter the target filter 2194 \return the argument string of the destination args 2195 */ 2196 const char *gf_filter_get_dst_args(GF_Filter *filter); 2197 2198 /*! Queries the destination name. The first output PID connected to a filter with non NULL args will be used (this is a recursive check until end of chain) 2199 \param filter the target filter 2200 \return the argument string of the destination (SHALL be freed by caller), NULL if none found 2201 */ 2202 char *gf_filter_get_dst_name(GF_Filter *filter); 2203 2204 /*! Sends an event on all input PIDs (downstream) or on all output PIDs (upstream) 2205 \param filter the target filter 2206 \param evt the event to send 2207 \param upstream send the even upstream 2208 */ 2209 void gf_filter_send_event(GF_Filter *filter, GF_FilterEvent *evt, Bool upstream); 2210 2211 /*! Trigger reconnection of output PIDs of a filter. This is needed when inserting a filter in the chain while the session is running 2212 \param filter the target filter 2213 \return error if any 2214 */ 2215 GF_Err gf_filter_reconnect_output(GF_Filter *filter); 2216 2217 /*! Looks for a built-in property value marked as informative on a filter on all PIDs (inputs and output) 2218 This is a recursive call on both input and ouput chain. 2219 There is no guarantee that a queried property will still be valid at the setter side upon returning the call, the setter could have 2220 already reassigned it to NULL. To avoids random behaviour, the property returned is reference counted so that it is not 2221 destroyed by the setter while the caller uses it. 2222 2223 Properties retrieved shall be released using \ref gf_filter_release_property. Failure to do so will cause memory leaks in the program. 2224 2225 If the propentry pointer references a non-null value, this value will be released using \ref gf_filter_release_property, 2226 so make sure to initialize the pointer to a NULL value on the first call. 2227 This avoid calling \ref gf_filter_release_property after each get_info in the calling code: 2228 2229 \code{.c} 2230 GF_PropertyEntry *pe=NULL; 2231 const GF_PropertyValue *p; 2232 p = gf_filter_get_info(filter, FOO, &pe); 2233 if (p) { } 2234 p = gf_filter_get_info_str(filter, "BAR", &pe); 2235 if (p) { } 2236 p = gf_filter_pid_get_info(PID, ABCD, &pe); 2237 if (p) { } 2238 p = gf_filter_pid_get_info_str(PID, "MyProp", &pe); 2239 if (p) { } 2240 gf_filter_release_property(pe); 2241 \endcode 2242 2243 2244 2245 \param filter the target filter 2246 \param prop_4cc the code of the built-in property to fetch 2247 \param propentry the property reference object for later release. SHALL not be NULL 2248 \return the property if found NULL otherwise. 2249 */ 2250 const GF_PropertyValue *gf_filter_get_info(GF_Filter *filter, u32 prop_4cc, GF_PropertyEntry **propentry); 2251 2252 /*! Looks for a property value on a filter on all PIDs (inputs and output). 2253 This is a recursive call on both input and ouput chain 2254 Properties retrieved shall be released using \ref gf_filter_release_property. See \ref gf_filter_pid_get_info for more details. 2255 \param filter the target filter 2256 \param prop_name the name of the property to fetch 2257 \param propentry the property reference object for later release. See \ref gf_filter_pid_get_info for more details. 2258 \return the property if found NULL otherwise 2259 */ 2260 const GF_PropertyValue *gf_filter_get_info_str(GF_Filter *filter, const char *prop_name, GF_PropertyEntry **propentry); 2261 2262 /*! Release a property previously queried, only used for []_get_info_[] functions. 2263 This is a recursive call on both input and ouput chain 2264 \param propentry the property reference object to be released 2265 */ 2266 void gf_filter_release_property(GF_PropertyEntry *propentry); 2267 2268 /*! Sends a filter argument update 2269 \param filter the target filter 2270 \param target_filter_id if set, the target filter will be changed to the filter with this id if any. otherwise the target filter is the one specified 2271 \param arg_name argument name 2272 \param arg_val argument value 2273 \param propagate_mask propagation flags - 0 means no propagation 2274 */ 2275 void gf_filter_send_update(GF_Filter *filter, const char *target_filter_id, const char *arg_name, const char *arg_val, GF_EventPropagateType propagate_mask); 2276 2277 2278 2279 /*! Filters may request listening on global events.\n 2280 \warning This is not thread safe, the callback will be called directly upon event firing, your filter has to take care of this 2281 2282 API of event filter is likely to change any time soon - used for backward compatibility with some old modules 2283 */ 2284 typedef struct 2285 { 2286 /*! user data of the listener */ 2287 void *udta; 2288 /*! callback called when an event should be filtered. 2289 \param udta user data of the listener 2290 \param evt the event to be processed 2291 \param consumed_by_compositor indicates the event was already used by the compositor 2292 \return GF_TRUE if the event is to be cancelled, GF_FALSE otherwise 2293 */ 2294 Bool (*on_event)(void *udta, GF_Event *evt, Bool consumed_by_compositor); 2295 } GF_FSEventListener; 2296 2297 /*! Adds an event listener to the session 2298 \param filter filter object 2299 \param el the event listener to add 2300 \return the error code if any 2301 */ 2302 GF_Err gf_filter_add_event_listener(GF_Filter *filter, GF_FSEventListener *el); 2303 2304 /*! Removes an event listener from the session 2305 \param filter filter object 2306 \param el the event listener to add 2307 \return the error code if any 2308 */ 2309 GF_Err gf_filter_remove_event_listener(GF_Filter *filter, GF_FSEventListener *el); 2310 2311 /*! Forwards an event to the filter session 2312 \param filter filter object 2313 \param evt the event forwarded 2314 \param consumed if set, indicates the event was already consummed/processed before forwarding 2315 \param skip_user if set, indicates the event should only be dispatched to event listeners. 2316 Otherwise, if a user is assigned to the session, the event is forwarded to the user 2317 \return the error code if any 2318 */ 2319 Bool gf_filter_forward_gf_event(GF_Filter *filter, GF_Event *evt, Bool consumed, Bool skip_user); 2320 2321 /*! Forwards an event to the filter session. This is a shortcut for gf_filter_forward_gf_event(session, evt, GF_FALSE, GF_FALSE); 2322 \param filter filter object 2323 \param evt the event forwarded 2324 \return the error code if any 2325 */ 2326 Bool gf_filter_send_gf_event(GF_Filter *filter, GF_Event *evt); 2327 2328 /*! Checks if all sink filters in the session have seen end of stream. 2329 \param filter filter object 2330 \return GF_TRUE if all sinks are in end of stream, GF_FALSE otherwise 2331 */ 2332 Bool gf_filter_all_sinks_done(GF_Filter *filter); 2333 2334 /*! Gets a filter argument value as string for a given argument name.. 2335 \param filter filter object 2336 \param arg_name name of the filter argument 2337 \param dump buffer in which any formating of argument value will take place 2338 \return the string value of the argument, or NULL if argument is not found or is invalid 2339 */ 2340 const char *gf_filter_get_arg_str(GF_Filter *filter, const char *arg_name, char dump[GF_PROP_DUMP_ARG_SIZE]); 2341 2342 /*! Gets a filter argument value for a given argument name.. 2343 \param filter filter object 2344 \param arg_name name of the filter argument 2345 \param prop filled with the arguments value, do NOT modify 2346 \return GF_TURE if success, GF_FALSE otherwise (argument is not found or is invalid) 2347 */ 2348 Bool gf_filter_get_arg(GF_Filter *filter, const char *arg_name, GF_PropertyValue *prop); 2349 2350 2351 /*! Checks if a given mime type is supported as input in the parent session 2352 \param filter querying filter 2353 \param mime mime type to query 2354 \return GF_TRUE if mime is supported 2355 */ 2356 Bool gf_filter_is_supported_mime(GF_Filter *filter, const char *mime); 2357 2358 2359 /*! Sends UI event from video output into the session. For now only direct callback to global event handler is used, event is not forwarded down the chain 2360 \param filter triggering filter 2361 \param uievt event to send 2362 \return GF_TRUE if event has been cancelled, FALSE otherwise 2363 */ 2364 Bool gf_filter_ui_event(GF_Filter *filter, GF_Event *uievt); 2365 2366 2367 /*! Registers filter as an openGL provider. This is only used by sink filters creating a openGL context, to avoid creating another context. Filters registered as OpenGL providers will run on the main thread. 2368 \param filter filter providing OpenGL context 2369 \param do_register if TRUE the filter carries a valid gl context, if FALSE the filter no longer carries a valid GL context 2370 */ 2371 void gf_filter_register_opengl_provider(GF_Filter *filter, Bool do_register); 2372 2373 /*! Requests openGL support for this filter. If no OpenGL providers exist, a default provider will be created (GL context creation on hidden window). Filters requiring OpenGL will run on the main thread. 2374 2375 \note Filters using openGL should not assume any persistent GL state among calls. Other filters using openGL might change the openGL context state (depth test, viewport, alpha blending, culling, etc...). 2376 2377 \param filter filter providing OpenGL context 2378 \return error code if any 2379 */ 2380 GF_Err gf_filter_request_opengl(GF_Filter *filter); 2381 2382 /*! Sets openGL context active for this filter. 2383 \note There may be several openGL context created in the filter session, depending on activated filters. A filter using openGL must call this function before issuing any openGL calls 2384 2385 \param filter filter asking for OpenGL context activation 2386 \return error code if any 2387 */ 2388 GF_Err gf_filter_set_active_opengl_context(GF_Filter *filter); 2389 2390 2391 /*! Count the number of source filters for the given filter matching the given protocol type. 2392 \param filter filter to inspect 2393 \param protocol_scheme scheme of the protocol to test, without ://, eg "http", "rtp", "https" 2394 \param expand_proto if set to GF_TRUE, any source protocol with a name begining like protocol_scheme will be matched. For example, use this with "http" to match all http and https schemes. 2395 \param enum_pids user function to enumerate PIDs against which the source should be checked . If not set, all source filters will be checked. 2396 \param udta user data for the callback function 2397 \return the number of source filters matched by protocols 2398 */ 2399 u32 gf_filter_count_source_by_protocol(GF_Filter *filter, const char *protocol_scheme, Bool expand_proto, GF_FilterPid * (*enum_pids)(void *udta, u32 *idx), void *udta); 2400 2401 /*! Disables data probing on the given filter. Typically used by filters loading source filters. 2402 \param filter target filter 2403 */ 2404 void gf_filter_disable_probe(GF_Filter *filter); 2405 2406 /*! Disables input connection on the filter. This is used by filters acting both as true sources or demux/processing filters depending on their options. 2407 \param filter target filter 2408 */ 2409 void gf_filter_disable_inputs(GF_Filter *filter); 2410 2411 /*! Checks if some PIDs are still not connected in the graph originating at filter. This is typically used by filters dynamically loading source filters to make sure all PIDs from the source are connected. 2412 2413 NOTE: this does not guarantee that no other PID remove or configure will happen later on, this depends on the source type and is unknown by GPAC's filter architecture. 2414 \param filter target filter 2415 \param stop_at_filter check connections until this filter. If NULL, connections are checked until upper (sink) end of graph 2416 \return GF_TRUE if any filter in the path has pending PID connections 2417 */ 2418 Bool gf_filter_has_pid_connection_pending(GF_Filter *filter, GF_Filter *stop_at_filter); 2419 2420 /*! checks if the some PID connection tasks are still pending at the session level 2421 2422 This can be needed by some filters needing to make sure all their inputs are known before starting producing packets. 2423 2424 \param filter target filter 2425 \return GF_TRUE if some connection tasks are pending, GF_FALSE otherwise 2426 */ 2427 Bool gf_filter_connections_pending(GF_Filter *filter); 2428 2429 /*! Disables blocking check for a given filter 2430 2431 This can be needed by some filters internally managing their blocking state because one of their output is not managed by the filter session. 2432 2433 \param filter target filter 2434 \param prevent_blocking_enabled if GF_TRUE, filter will still be called even if one of its output is in blocking mode 2435 \return error if any 2436 */ 2437 GF_Err gf_filter_prevent_blocking(GF_Filter *filter, Bool prevent_blocking_enabled); 2438 2439 /*! Checks if filter was loaded as part of a link resolution or explicitly loaded by application 2440 \param filter target filter 2441 \return GF_TRUE if filter was loaded for link resolution, GF_FALSE if filter was explicitly loaded by the application 2442 */ 2443 Bool gf_filter_is_dynamic(GF_Filter *filter); 2444 2445 /*! Checks if reporting is turned on at session level. 2446 \param filter target filter 2447 \return GF_TRUE if reporting is enabled, GF_FALSE otherwise 2448 */ 2449 Bool gf_filter_reporting_enabled(GF_Filter *filter); 2450 2451 /*! Updates filter status string and progress. Should not be called if reporting is turned off at session level. 2452 This allows gathering stats from filter in realtime. The status string can be anything but shall not contain '\n' and 2453 should not contain any source or destination URL except for sources and sinks. 2454 \param filter target filter 2455 \param percent percentage (from 0 to 10000) of operation status. If more than 10000 ignored 2456 \param szStatus string giving a status of the filter 2457 \return error code if any 2458 */ 2459 GF_Err gf_filter_update_status(GF_Filter *filter, u32 percent, char *szStatus); 2460 2461 /*! check if session has been scheduled for destruction 2462 \param filter target filter 2463 \return GF_TRUE if session is about to be destroyed 2464 */ 2465 Bool gf_filter_end_of_session(GF_Filter *filter); 2466 2467 /*! used by meta-filters (ffmpeg and co) to report an option was set but not used by the filter. This is needed since these filters might not 2468 know the set of available options at initialize() time. 2469 \param filter target filter 2470 \param arg name of the argument not used/found 2471 */ 2472 void gf_filter_report_unused_meta_option(GF_Filter *filter, const char *arg); 2473 2474 /*! used by script to set a per-instance description 2475 \param filter target filter 2476 \param new_desc the new description to set 2477 \return error if any 2478 */ 2479 GF_Err gf_filter_set_description(GF_Filter *filter, const char *new_desc); 2480 2481 /*! get a per-instance description 2482 \param filter target filter 2483 \return the filter instance description, NULL otherwise 2484 */ 2485 const char *gf_filter_get_description(GF_Filter *filter); 2486 2487 /*! used by script to set a per-instance version 2488 \param filter target filter 2489 \param new_version the new version to set 2490 \return error if any 2491 */ 2492 GF_Err gf_filter_set_version(GF_Filter *filter, const char *new_version); 2493 2494 /*! get a per-instance version 2495 \param filter target filter 2496 \return the filter instance version, NULL otherwise 2497 */ 2498 const char *gf_filter_get_version(GF_Filter *filter); 2499 2500 /*! used by script to set a per-instance author 2501 \param filter target filter 2502 \param new_author the new author to set 2503 \return error if any 2504 */ 2505 GF_Err gf_filter_set_author(GF_Filter *filter, const char *new_author); 2506 2507 /*! get a per-instance author 2508 \param filter target filter 2509 \return the filter instance author, NULL otherwise 2510 */ 2511 const char *gf_filter_get_author(GF_Filter *filter); 2512 2513 /*! used by script to set a per-instance help 2514 \param filter target filter 2515 \param new_help the new help to set 2516 \return error if any 2517 */ 2518 GF_Err gf_filter_set_help(GF_Filter *filter, const char *new_help); 2519 2520 /*! get a per-instance help 2521 \param filter target filter 2522 \return the filter instance help, NULL otherwise 2523 */ 2524 const char *gf_filter_get_help(GF_Filter *filter); 2525 2526 2527 /*! used by script to set a per-instance arguments. The passed array shall have a 0 argument at the end and shall be valid 2528 for the lifetime of the filter (not locally copied) 2529 \param filter target filter 2530 \param new_args the new args to set 2531 \return error if any 2532 */ 2533 GF_Err gf_filter_define_args(GF_Filter *filter, GF_FilterArgs *new_args); 2534 2535 /*! get per-instance args 2536 \param filter target filter 2537 \return the filter instance args if any, NULL otherwise 2538 */ 2539 GF_FilterArgs *gf_filter_get_args(GF_Filter *filter); 2540 2541 2542 /*! probes mime type of a given block of data (should be begining of file ) 2543 \param filter target filter 2544 \param data buffer to probe 2545 \param size size of buffer 2546 \return the mime type probed, or NULL if not recognized 2547 */ 2548 const char *gf_filter_probe_data(GF_Filter *filter, u8 *data, u32 size); 2549 2550 /*! checks if the given filter is an alias filter created by a multiple sink filter 2551 \param filter target filter 2552 \return GF_TRUE if this is an alias filter created by a multiple sink filter, GF_FALSE otherwise 2553 */ 2554 Bool gf_filter_is_alias(GF_Filter *filter); 2555 2556 /*! @} */ 2557 2558 2559 /*! 2560 \addtogroup fs_pid Filter PID 2561 \ingroup filters_grp 2562 \brief Filter Interconnection 2563 2564 2565 A PID is a connection between two filters, holding packets to process. Internally, a PID created by a filter (output PID) is different from an input PID to a filter (configure_pid) 2566 but the API has been designed to hide this, so that most PID functions can be called regardless of the input/output nature of the PID. 2567 2568 All setters functions (gf_filter_pid_set*) will fail on an input PID. 2569 2570 The generic design of the architecture is that each filter is free to decide how it handle PIDs and their packets. This implies that the filter session has no clue how 2571 an output PID relates to an input PID (same goes for packets). 2572 Developpers must therefore manually copy PID properties that seem relevant, or more practically copy all properties from input PID to output PID and 2573 reassign output PID properties changed by the filter. 2574 2575 PIDs can be reconfigured multiple times, even potentially changing caps on the fly. The current architecture does not check for capability matching during reconfigure, it is up to 2576 the filter to do so. 2577 2578 It is also up to filters to decide how to handle a an input PID removal: remove the output PID immediately, keep it open to flush internal data or keep generating data on the output. 2579 The usual practice is to remove the output as soon as the input is removed. 2580 2581 Once an input PID has been notified to be removed, it shall no longer be used by the filter, as it may be discarded/freed (PID are NOT reference counted). 2582 2583 @{ 2584 */ 2585 2586 2587 2588 /*! Creates a new output PID for the filter. If the filter has a single input PID already connected, the PID properties are copied by default 2589 \param filter the target filter 2590 \return the new output PID 2591 */ 2592 GF_FilterPid *gf_filter_pid_new(GF_Filter *filter); 2593 2594 /*! Removes an output PID from the filter. This will trigger removal of the PID upward in the chain 2595 \param PID the target filter PID to remove 2596 */ 2597 void gf_filter_pid_remove(GF_FilterPid *PID); 2598 2599 /*! Creates an output PID for a raw input filter (file, sockets, pipe, etc). This will assign file name, local name, mime and extension properties to the created PID 2600 \param filter the target filter 2601 \param url URL of the source, SHALL be set 2602 \param local_file path on local host, can be NULL 2603 \param mime_type mime type of the content. If none provided and propbe_data is not null, the data will be probed for mime type resolution 2604 \param fext file extension of the content. If NULL, will be extracted from URL 2605 \param probe_data data of the stream to probe in order to solve its mime type 2606 \param probe_size size of the probe data 2607 \param trust_mime if set and mime_type is set, disables data probing 2608 \param out_pid the output PID to create or update. If no referer PID, a new PID will be created otherwise the PID will be updated 2609 \return error code if any 2610 */ 2611 GF_Err gf_filter_pid_raw_new(GF_Filter *filter, const char *url, const char *local_file, const char *mime_type, const char *fext, u8 *probe_data, u32 probe_size, Bool trust_mime, GF_FilterPid **out_pid); 2612 2613 /*! Sets a new property on an output PID for built-in property names. 2614 Previous properties (ones set before last packet dispatch) will still be valid. Property with same type/name will be reassigned 2615 You need to remove them one by one using \ref gf_filter_pid_set_property with NULL property, or reset the properties with \ref gf_filter_pid_reset_properties. 2616 Setting a new property will trigger a PID reconfigure at the consumption point of the next dispatched packet. 2617 2618 Warning: changing a property before the final end of stream (i.e. if no more packets are sent) will have no effect. You must use \ref gf_filter_pid_set_info and \ref gf_filter_pid_get_info for this. 2619 2620 \param PID the target filter PID 2621 \param prop_4cc the built-in property code to modify 2622 \param value the new value to assign, or NULL if the property is to be removed 2623 \return error code if any 2624 */ 2625 GF_Err gf_filter_pid_set_property(GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value); 2626 2627 /*! Sets a new property on an output PID - see \ref gf_filter_pid_set_property. 2628 \param PID the target filter PID 2629 \param name the name of the property to modify 2630 \param value the new value to assign, or NULL if the property is to be removed 2631 \return error code if any 2632 */ 2633 GF_Err gf_filter_pid_set_property_str(GF_FilterPid *PID, const char *name, const GF_PropertyValue *value); 2634 2635 /*! Sets a new property on an output PID - see \ref gf_filter_pid_set_property. 2636 \param PID the target filter PID 2637 \param name the name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session 2638 \param value the new value to assign, or NULL if the property is to be removed 2639 \return error code if any 2640 */ 2641 GF_Err gf_filter_pid_set_property_dyn(GF_FilterPid *PID, char *name, const GF_PropertyValue *value); 2642 2643 /*! Sets a new info property on an output PID for built-in property names. 2644 Similar to \ref gf_filter_pid_set_property, but infos are not copied up the chain and to not trigger PID reconfiguration. 2645 First packet dispatched after calling this function will be marked, and its fetching by the consuming filter will trigger a process_event notification. 2646 If the consumming filter copies properties from source packet to output packet, the flag will be passed to such new output packet. 2647 Note: any property type can be used for info, except \ref GF_PROP_POINTER. 2648 2649 \param PID the target filter PID 2650 \param prop_4cc the built-in property code to modify 2651 \param value the new value to assign, or NULL if the property is to be removed 2652 \return error code if any 2653 */ 2654 GF_Err gf_filter_pid_set_info(GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value); 2655 2656 /*! Sets a new info property on an output PID - see \ref gf_filter_pid_set_info 2657 See \ref gf_filter_pid_set_info 2658 \param PID the target filter PID 2659 \param name the name of the property to modify 2660 \param value the new value to assign, or NULL if the property is to be removed 2661 \return error code if any 2662 */ 2663 GF_Err gf_filter_pid_set_info_str(GF_FilterPid *PID, const char *name, const GF_PropertyValue *value); 2664 2665 /*! Sets a new property on an output PID. 2666 See \ref gf_filter_pid_set_info 2667 \param PID the target filter PID 2668 \param name the name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session 2669 \param value the new value to assign, or NULL if the property is to be removed 2670 \return error code if any 2671 */ 2672 GF_Err gf_filter_pid_set_info_dyn(GF_FilterPid *PID, char *name, const GF_PropertyValue *value); 2673 2674 /*! Sets user data pointer for a PID - see \ref gf_filter_pid_set_info 2675 \param PID the target filter PID 2676 \param udta user data pointer 2677 */ 2678 void gf_filter_pid_set_udta(GF_FilterPid *PID, void *udta); 2679 2680 /*! Gets user data pointer for a PID 2681 \param PID the target filter PID 2682 \return udta user data pointer 2683 */ 2684 void *gf_filter_pid_get_udta(GF_FilterPid *PID); 2685 2686 /*! Gets PID name. Mostly used for logging purposes 2687 \param PID the target filter PID 2688 \param name the new PID name. function ignored if NULL. 2689 */ 2690 void gf_filter_pid_set_name(GF_FilterPid *PID, const char *name); 2691 2692 /*! Gets PID name 2693 \param PID the target filter PID 2694 \return PID name 2695 */ 2696 const char *gf_filter_pid_get_name(GF_FilterPid *PID); 2697 2698 /*! Gets filter name of input PID 2699 \param PID the target filter PID 2700 \return name of the filter owning this input PID 2701 */ 2702 const char *gf_filter_pid_get_filter_name(GF_FilterPid *PID); 2703 2704 /*! Gets the source arguments of the PID, walking down the chain until the source filter 2705 \param PID the target filter PID 2706 \return argument of the source filter 2707 */ 2708 const char *gf_filter_pid_orig_src_args(GF_FilterPid *PID); 2709 2710 /*! Gets the source filter name or class name for the PID, walking down the chain until the source filter (ony the first input PID of each filter is used). 2711 \param PID the target filter PID 2712 \return argument of the source filter 2713 */ 2714 const char *gf_filter_pid_get_source_filter_name(GF_FilterPid *PID); 2715 2716 /*! Gets the arguments for the filter 2717 \param PID the target filter PID 2718 \return arguments of the source filter 2719 */ 2720 const char *gf_filter_pid_get_args(GF_FilterPid *PID); 2721 2722 /*! Sets max buffer requirement of an output PID. Typically used by audio to make sure several packets can be dispatched on a PID 2723 that would otherwise block after one packet 2724 \param PID the target filter PID 2725 \param total_duration_us buffer max occupancy in us 2726 */ 2727 void gf_filter_pid_set_max_buffer(GF_FilterPid *PID, u32 total_duration_us); 2728 2729 /*! Returns max buffer requirement of a PID. 2730 \param PID the target filter PID 2731 \return buffer max in us 2732 */ 2733 u32 gf_filter_pid_get_max_buffer(GF_FilterPid *PID); 2734 2735 /*! Checks if a given filter is in the PID parent chain. This is used to identify sources (rather than checking URL/...) 2736 \param PID the target filter PID 2737 \param filter the source filter to check 2738 \return GF_TRUE if filter is a source for that PID, GF_FALSE otherwise 2739 */ 2740 Bool gf_filter_pid_is_filter_in_parents(GF_FilterPid *PID, GF_Filter *filter); 2741 2742 /*! Gets current buffer levels of the PID 2743 \param PID the target filter PID 2744 \param max_units maximum number of packets allowed - can be 0 if buffer is measured in time 2745 \param nb_pck number of packets in PID 2746 \param max_duration maximum buffer duration allowed in us - can be 0 if buffer is measured in units 2747 \param duration buffer duration in us 2748 \return GF_TRUE if normal buffer query, GF_FALSE if final session flush, in which case buffer might never complete 2749 */ 2750 Bool gf_filter_pid_get_buffer_occupancy(GF_FilterPid *PID, u32 *max_units, u32 *nb_pck, u32 *max_duration, u32 *duration); 2751 2752 /*! Sets loose connect for a PID, avoiding to throw an error if connection of the PID fails. Used by the compositor filter which acts as both sink and filter. 2753 \param PID the target filter PID 2754 */ 2755 void gf_filter_pid_set_loose_connect(GF_FilterPid *PID); 2756 2757 2758 /*! Negotiate a given property on an input PID for built-in properties 2759 Filters may accept some PID connection but may need an adaptaion chain to be able to process packets, eg change pixel format or sample rate 2760 This function will trigger a reconfiguration of the filter chain to try to adapt this. If failing, the filter chain will disconnect 2761 This process is asynchronous, the filter asking for a PID negociation will see the notification through a pid_reconfigure if success. 2762 \param PID the target filter PID - this MUST be an input PID 2763 \param prop_4cc the built-in property code to negotiate 2764 \param value the new value to negotiate, SHALL NOT be NULL 2765 \return error code if any 2766 */ 2767 GF_Err gf_filter_pid_negociate_property(GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value); 2768 2769 /*! Negotiate a given property on an input PID for regular properties 2770 see \ref gf_filter_pid_negociate_property 2771 \param PID the target filter PID - this MUST be an input PID 2772 \param name name of the property to negotiate 2773 \param value the new value to negotiate, SHALL NOT be NULL 2774 \return error code if any 2775 */ 2776 GF_Err gf_filter_pid_negociate_property_str(GF_FilterPid *PID, const char *name, const GF_PropertyValue *value); 2777 2778 /*! Negotiate a given property on an input PID for regular properties 2779 see \ref gf_filter_pid_negociate_property 2780 \param PID the target filter PID - this MUST be an input PID 2781 \param name the name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session 2782 \param value the new value to negotiate, SHALL NOT be NULL 2783 \return error code if any 2784 */ 2785 GF_Err gf_filter_pid_negociate_property_dyn(GF_FilterPid *PID, char *name, const GF_PropertyValue *value); 2786 2787 /*! Queries a negotiated built-in capability on an output PID 2788 Filters may check if a property negotiation was done on an output PID, and check the property value. 2789 This can be done on an output PID in a filter->reconfigure_output if the filter accpets caps negotiation 2790 This can be done on an input PID in a generic reconfigure_pid 2791 2792 \param PID the target filter PID 2793 \param prop_4cc the built-in property code to negotiate 2794 \return the negociated property value 2795 */ 2796 const GF_PropertyValue *gf_filter_pid_caps_query(GF_FilterPid *PID, u32 prop_4cc); 2797 2798 /*! Queries a negotiated capability on an output PID - see \ref gf_filter_pid_caps_query 2799 \param PID the target filter PID 2800 \param prop_name the property name to negotiate 2801 \return the negociated property value 2802 */ 2803 const GF_PropertyValue *gf_filter_pid_caps_query_str(GF_FilterPid *PID, const char *prop_name); 2804 2805 /*! Statistics for PID*/ 2806 typedef struct 2807 { 2808 /*! if set, indicates the PID is disconnected and stats are not valid*/ 2809 u32 disconnected; 2810 /*! average process rate on that PID in bits per seconds*/ 2811 u32 average_process_rate; 2812 /*! max process rate on that PID in bits per seconds*/ 2813 u32 max_process_rate; 2814 /*! average bitrate for that PID*/ 2815 u32 avgerage_bitrate; 2816 /*! max bitrate for that PID*/ 2817 u32 max_bitrate; 2818 /*! number of packets processed on that PID*/ 2819 u32 nb_processed; 2820 /*! max packet process time of the filter in us*/ 2821 u32 max_process_time; 2822 /*! total process time of the filter in us*/ 2823 u64 total_process_time; 2824 /*! process time of first packet of the filter in us*/ 2825 u64 first_process_time; 2826 /*! process time of the last packet on that PID in us*/ 2827 u64 last_process_time; 2828 /*! minimum frame duration on that PID in us*/ 2829 u32 min_frame_dur; 2830 /*! number of saps 1/2/3 on that PID*/ 2831 u32 nb_saps; 2832 /*! max process time of SAP packets on that PID in us*/ 2833 u32 max_sap_process_time; 2834 /*! total process time of SAP packets on that PID in us*/ 2835 u64 total_sap_process_time; 2836 2837 /*! max buffer time in us - only set when querying decoder stats*/ 2838 u64 max_buffer_time; 2839 /*! max playout buffer time in us - only set when querying decoder stats*/ 2840 u64 max_playout_time; 2841 /*! min playout buffer time in us - only set when querying decoder stats*/ 2842 u64 min_playout_time; 2843 /*! current buffer time in us - only set when querying decoder stats*/ 2844 u64 buffer_time; 2845 /*! number of units in input buffer of the filter - only set when querying decoder stats*/ 2846 u32 nb_buffer_units; 2847 } GF_FilterPidStatistics; 2848 2849 /*! Direction for stats querying*/ 2850 typedef enum 2851 { 2852 /*! statistics are fetched on the current PID's parent filter. If the PID is an output PID, the statistics are fetched on all the destinations for that PID*/ 2853 GF_STATS_LOCAL = 0, 2854 /*! statistics are fetched on the current PID's parent filter. The statistics are fetched on all input of the parent filter*/ 2855 GF_STATS_LOCAL_INPUTS, 2856 /*! statistics are fetched on all inputs of the next decoder filter up the chain (towards the sink)*/ 2857 GF_STATS_DECODER_SINK, 2858 /*! statistics are fetched on all inputs of the previous decoder filter down the chain (towards the source)*/ 2859 GF_STATS_DECODER_SOURCE, 2860 /*! statistics are fetched on all inputs of the next encoder filter up the chain (towards the sink)*/ 2861 GF_STATS_ENCODER_SINK, 2862 /*! statistics are fetched on all inputs of the previous encoder filter down the chain (towards the source)*/ 2863 GF_STATS_ENCODER_SOURCE 2864 } GF_FilterPidStatsLocation; 2865 2866 /*! Gets statistics for the PID 2867 \param PID the target filter PID 2868 \param stats the retrieved statistics 2869 \param location indicates where to locate the filter to query stats on it. 2870 \return error code if any 2871 */ 2872 GF_Err gf_filter_pid_get_statistics(GF_FilterPid *PID, GF_FilterPidStatistics *stats, GF_FilterPidStatsLocation location); 2873 2874 /*! Resets current properties of the PID 2875 \param PID the target filter PID 2876 \return error code if any 2877 */ 2878 GF_Err gf_filter_pid_reset_properties(GF_FilterPid *PID); 2879 2880 2881 /*! Function protoype for filtering properties. 2882 \param cbk callback data 2883 \param prop_4cc the built-in property code 2884 \param prop_name property name 2885 \param src_prop the property value in the source packet 2886 \return GF_TRUE if the property shall be merged, GF_FALSE otherwise 2887 */ 2888 typedef Bool (*gf_filter_prop_filter)(void *cbk, u32 prop_4cc, const char *prop_name, const GF_PropertyValue *src_prop); 2889 2890 /*! Push a new set of properties on destination PID using all properties from source PID. Old properties in destination will be lost (i.e. reset properties is always performed during copy properties) 2891 \param dst_pid the destination filter PID 2892 \param src_pid the source filter PID 2893 \return error code if any 2894 */ 2895 GF_Err gf_filter_pid_copy_properties(GF_FilterPid *dst_pid, GF_FilterPid *src_pid); 2896 2897 /*! Push a new set of properties on destination PID, using all properties from source PID. 2898 Old properties of the destination are first copied to the new property set before copying the ones from the source PID, potentially filtering them. 2899 \param dst_pid the destination filter PID 2900 \param src_pid the source filter PID 2901 \param filter_prop callback filtering function 2902 \param cbk callback data passed to the callback function 2903 \return error code if any 2904 */ 2905 GF_Err gf_filter_pid_merge_properties(GF_FilterPid *dst_pid, GF_FilterPid *src_pid, gf_filter_prop_filter filter_prop, void *cbk ); 2906 2907 /*! Gets a built-in property of the PID 2908 Warning: properties are only valid until the next configure_pid is called. Attempting to use a property 2909 value (either the pointer or one of the value) queried before the current configure_pid will result in 2910 unpredictable behaviour, potentially crashes. 2911 \param PID the target filter PID 2912 \param prop_4cc the code of the built-in property to retrieve 2913 \return the property if found or NULL otherwise 2914 */ 2915 const GF_PropertyValue *gf_filter_pid_get_property(GF_FilterPid *PID, u32 prop_4cc); 2916 2917 /*! Gets a property of the PID - see \ref gf_filter_pid_get_property 2918 \param PID the target filter PID 2919 \param prop_name the name of the property to retrieve 2920 \return the property if found or NULL otherwise 2921 */ 2922 const GF_PropertyValue *gf_filter_pid_get_property_str(GF_FilterPid *PID, const char *prop_name); 2923 2924 /*! Enumerates properties of a PID - see \ref gf_filter_pid_get_property 2925 \param PID the target filter PID 2926 \param idx input/output index of the current property. 0 means first. Incremented by 1 upon success 2927 \param prop_4cc set to the built-in code of the property if built-in 2928 \param prop_name set to the name of the property if not built-in 2929 \return the property if found or NULL otherwise (end of enumeration) 2930 */ 2931 const GF_PropertyValue *gf_filter_pid_enum_properties(GF_FilterPid *PID, u32 *idx, u32 *prop_4cc, const char **prop_name); 2932 2933 /*! Enumerates info of a PID 2934 \param PID the target filter PID 2935 \param idx input/output index of the current info. 0 means first. Incremented by 1 upon success 2936 \param prop_4cc set to the built-in code of the info if built-in 2937 \param prop_name set to the name of the info if not built-in 2938 \return the property if found or NULL otherwise (end of enumeration) 2939 */ 2940 const GF_PropertyValue *gf_filter_pid_enum_info(GF_FilterPid *PID, u32 *idx, u32 *prop_4cc, const char **prop_name); 2941 2942 /*! Sets PID framing mode. filters can consume packets as they arrive, or may want to only process full frames/files 2943 \param PID the target filter PID 2944 \param requires_full_blocks if GF_TRUE, the packets on the PID will be reaggregated to form complete frame/files. 2945 \return error code if any 2946 */ 2947 GF_Err gf_filter_pid_set_framing_mode(GF_FilterPid *PID, Bool requires_full_blocks); 2948 2949 /*! Gets cumulated buffer duration of PID (recursive until source) 2950 \param PID the target filter PID 2951 \param check_pid_full if GF_TRUE, returns 0 if the PID buffer is not yet full 2952 \return the duration in us, or -1 if session is in final flush 2953 */ 2954 u64 gf_filter_pid_query_buffer_duration(GF_FilterPid *PID, Bool check_pid_full); 2955 2956 /*! Try to force a synchronous flush of the filter chain downwards this PID. If refetching a packet returns NULL, this failed. 2957 \param PID the target filter PID 2958 */ 2959 void gf_filter_pid_try_pull(GF_FilterPid *PID); 2960 2961 2962 /*! Looks for a built-in property value on a PIDs. This is a recursive call on input chain 2963 Info query is NOT threadsafe in gpac, you 2964 Properties retrieved shall be released using \ref gf_filter_release_property. See \ref gf_filter_pid_get_info for more details. 2965 \param PID the target filter PID to query 2966 \param prop_4cc the code of the built-in property to fetch 2967 \param propentry the property reference object for later release. See \ref gf_filter_pid_get_info for more details. 2968 \return the property if found NULL otherwise 2969 */ 2970 const GF_PropertyValue *gf_filter_pid_get_info(GF_FilterPid *PID, u32 prop_4cc, GF_PropertyEntry **propentry); 2971 2972 /*! Looks for a property value on a PIDs. This is a recursive call on both input and ouput chain 2973 Properties retrieved shall be released using \ref gf_filter_release_property. See \ref gf_filter_pid_get_info for more details. 2974 \param PID the target filter PID to query 2975 \param prop_name the name of the property to fetch 2976 \param propentry the property reference object for later release. See \ref gf_filter_pid_get_info for more details. 2977 \return the property if found NULL otherwise 2978 */ 2979 const GF_PropertyValue *gf_filter_pid_get_info_str(GF_FilterPid *PID, const char *prop_name, GF_PropertyEntry **propentry); 2980 2981 2982 /*! Signals end of stream on a PID. Each filter needs to call this when EOS is reached on a given stream since there is no explicit link between input PIDs and output PIDs 2983 \param PID the target filter PID 2984 */ 2985 void gf_filter_pid_set_eos(GF_FilterPid *PID); 2986 2987 /*! Checks for end of stream has been signaled a PID input chain. 2988 This is a recursive call on input chain. The function is typically used to abort buffering or synchronisation init in muxers. 2989 \param PID the target filter PID 2990 \return GF_TRUE if end of stream was signaled on the input chain 2991 */ 2992 Bool gf_filter_pid_has_seen_eos(GF_FilterPid *PID); 2993 2994 /*! Checks for end of stream signaling on a PID. 2995 \param PID the target filter PID 2996 \return GF_TRUE if end of stream was signaled on that PID 2997 */ 2998 Bool gf_filter_pid_is_eos(GF_FilterPid *PID); 2999 3000 /*! Checks if there is a packet ready on an input PID. 3001 \param PID the target filter PID 3002 \return GF_TRUE if no packet in buffers 3003 */ 3004 Bool gf_filter_pid_first_packet_is_empty(GF_FilterPid *PID); 3005 3006 /*! Gets the first packet in the input PID buffer. 3007 This may trigger a reconfigure signal on the filter. If reconfigure is not OK, returns NULL and the PID passed to the filter NO LONGER EXISTS (implicit remove) 3008 The packet is still present in the PID buffer until explicitly removed by \ref gf_filter_pid_drop_packet 3009 \param PID the target filter PID 3010 \return packet or NULL of empty or reconfigure error 3011 */ 3012 GF_FilterPacket * gf_filter_pid_get_packet(GF_FilterPid *PID); 3013 3014 /*! Fetches the CTS of the first packet in the input PID buffer. 3015 \param PID the target filter PID 3016 \param cts set to the composition time of the first packet, in PID timescale 3017 \return GF_TRUE if cts was fetched, GF_FALSE otherwise 3018 */ 3019 Bool gf_filter_pid_get_first_packet_cts(GF_FilterPid *PID, u64 *cts); 3020 3021 /*! Drops the first packet in the input PID buffer. 3022 \param PID the target filter PID 3023 */ 3024 void gf_filter_pid_drop_packet(GF_FilterPid *PID); 3025 3026 /*! Gets the number of packets in input PID buffer. 3027 \param PID the target filter PID 3028 \return the number of packets 3029 */ 3030 u32 gf_filter_pid_get_packet_count(GF_FilterPid *PID); 3031 3032 /*! Checks the capability of the input PID match its destination filter. 3033 \param PID the target filter PID 3034 \return GF_TRUE if match , GF_FALSE otherwise 3035 */ 3036 Bool gf_filter_pid_check_caps(GF_FilterPid *PID); 3037 3038 /*! Checks if the PID would enter a blocking state if a new packet is sent. 3039 This function should be called by eg demuxers to regulate the rate at which they send packets 3040 3041 Note: PIDs are never fully blocking in GPAC, a filter requesting an output packet should usually get one unless something goes wrong 3042 \param PID the target filter PID 3043 \return GF_TRUE if PID would enter blocking state , GF_FALSE otherwise 3044 */ 3045 Bool gf_filter_pid_would_block(GF_FilterPid *PID); 3046 3047 /*! Shortcut to access the timescale of the PID - faster than get property as the timescale is locally cached for buffer management 3048 \param PID the target filter PID 3049 \return the PID timescale 3050 */ 3051 u32 gf_filter_pid_get_timescale(GF_FilterPid *PID); 3052 3053 /*! Clears the end of stream flag on a PID. 3054 Note: the end of stream is automatically cleared when a new packet is dispatched; This function is used to clear it asap, before next packet dispacth (period switch in dash for example). 3055 \param PID the target filter PID 3056 \param all_pids if sets, clear end oof stream for all PIDs coming from the same filter as the target PID 3057 */ 3058 void gf_filter_pid_clear_eos(GF_FilterPid *PID, Bool all_pids); 3059 3060 /*! Indicates how clock references (PCR of MPEG-2) should be handled. 3061 By default these references are passed from input packets to output packets by the filter session (this assumes the filter doesn't modify composition timestamps). 3062 This default can be changed with this function. 3063 \param PID the target filter PID 3064 \param filter_in_charge if set to GF_TRUE, clock references are not forwarded by the filter session and the filter is in charge of handling them 3065 */ 3066 void gf_filter_pid_set_clock_mode(GF_FilterPid *PID, Bool filter_in_charge); 3067 3068 /*! Resolves file template using PID properties and file index. Templates follow the DASH mechanism: 3069 3070 - $KEYWORD$ or $KEYWORD%0nd$ are replaced in the template with the resolved value, 3071 3072 - $$ is an escape for $ 3073 3074 Supported KEYWORD (case insensitive): 3075 - num: replaced by file_number (usually matches GF_PROP_PCK_FILENUM, but this property is not used in the solving mechanism) 3076 - PID: ID of the source PID 3077 - URL: URL of source file 3078 - File: path on disk for source file 3079 - p4cc=ABCD: uses PID property with 4CC ABCD 3080 - pname=VAL: uses PID property with name VAL (either built-in prop name or other peroperty name) 3081 3082 \param PID the target filter PID 3083 \param szTemplate source template to solve 3084 \param szFinalName buffer for final name 3085 \param file_number number of file to use 3086 \param file_suffix if not null, will be appended after the value of the §File$ keyword if present 3087 \return error if any 3088 */ 3089 GF_Err gf_filter_pid_resolve_file_template(GF_FilterPid *PID, char szTemplate[GF_MAX_PATH], char szFinalName[GF_MAX_PATH], u32 file_number, const char *file_suffix); 3090 3091 3092 /*! Sets discard mode on or off on an input PID. When discard is on, all input packets for this PID are no longer dispatched. 3093 3094 This only affect the current PID, not the source filter(s) for that PID. 3095 3096 PID reconfigurations are still forwarded to the filter, so that a filter may decide to re-enable regular mode. 3097 3098 This is typically needed for filters that stop consuming data for a while (dash forced period duration for example) but may resume 3099 consumption later on (stream moving from period 1 to period 2 for example). 3100 3101 \param PID the target filter PID 3102 \param discard_on enables/disables discard 3103 \return error if any 3104 */ 3105 GF_Err gf_filter_pid_set_discard(GF_FilterPid *PID, Bool discard_on); 3106 3107 /*! Discard blocking mode for PID on end of stream. The filter is blocked when all output PIDs are in end of stream, this function unblocks the filter. 3108 This can be needed for playlist type filters dispatching end of stream at the end of each file but setting up next file in 3109 the following process() call. 3110 3111 \param PID the target filter PID 3112 */ 3113 void gf_filter_pid_discard_block(GF_FilterPid *PID); 3114 3115 /*! Gets URL argument of first destination of PID if any - memory shall be freed by caller. 3116 \param PID the target filter PID 3117 \return destination URL string or NULL if error 3118 */ 3119 char *gf_filter_pid_get_destination(GF_FilterPid *PID); 3120 3121 /*! Gets URL argument of first source of PID if any - memory shall be freed by caller. 3122 \param PID the target filter PID 3123 \return source URL string or NULL if error 3124 */ 3125 char *gf_filter_pid_get_source(GF_FilterPid *PID); 3126 3127 /*! Indicates that this output PID requires a sourceID on the destination filter to be present. This prevents trying to link to other filters with no source IDs but 3128 accepting the PID 3129 \param PID the target filter PID 3130 \return error code if any 3131 */ 3132 GF_Err gf_filter_pid_require_source_id(GF_FilterPid *PID); 3133 3134 /*! Enables decoding time reconstruction on PID for packets with DTS not set. If not enabled (default), dts not set implies dts = cts 3135 \param PID the target filter PID 3136 \param do_recompute if set, dts will be recomputed when not set 3137 */ 3138 void gf_filter_pid_recompute_dts(GF_FilterPid *PID, Bool do_recompute); 3139 3140 /*! Queries minimum packet duration as computed from DTS/CTS info on the PID 3141 \param PID the target filter PID 3142 \return minimum packet duration computed 3143 */ 3144 u32 gf_filter_pid_get_min_pck_duration(GF_FilterPid *PID); 3145 3146 3147 /*! Sends an event down the filter chain for input PID, or up the filter chain for output PIDs. 3148 \param PID the target filter PID 3149 \param evt the event to send 3150 */ 3151 void gf_filter_pid_send_event(GF_FilterPid *PID, GF_FilterEvent *evt); 3152 3153 3154 /*! Helper function to init play events, that checks the PID \ref GF_FilterPidPlaybackMode and adjust start/speed accordingly. This does not send the event. 3155 \param PID the target filter PID 3156 \param evt the event to initialize 3157 \param start playback start time of request 3158 \param speed playback speed time of request 3159 \param log_name name used for logs in case of capability mismatched 3160 */ 3161 void gf_filter_pid_init_play_event(GF_FilterPid *PID, GF_FilterEvent *evt, Double start, Double speed, const char *log_name); 3162 3163 /*! Check if the given PID is marked as playing or not. 3164 \param PID the target filter PID 3165 \return GF_TRUE if PID is currently playing, GF_FALSE otherwise 3166 */ 3167 Bool gf_filter_pid_is_playing(GF_FilterPid *PID); 3168 3169 /*! Enables direct dispatch of packets to connected filters. This mode is useful when a filter may send a very large number of packets 3170 in one process() call; this is for example the case of the isobmff muxer in interleave mode. Using this mode avoids overloading 3171 the PID buffer with packets. 3172 If the session is multi-threaded, this parameter has no effect. 3173 \param PID the target filter PID 3174 \return GF_TRUE if PID is currently playing, GF_FALSE otherwise 3175 */ 3176 GF_Err gf_filter_pid_allow_direct_dispatch(GF_FilterPid *PID); 3177 3178 /*! Gets the private stack of the alias filter associated with an input PID, if any 3179 3180 \note The filter type of the alias is always the type of the filter holding the input PID connection. 3181 \param PID the target filter PID 3182 \return the temporary alias filter private stack, NULL otherwise 3183 */ 3184 void *gf_filter_pid_get_alias_udta(GF_FilterPid *PID); 3185 3186 /*! @} */ 3187 3188 3189 /*! 3190 \addtogroup fs_pck Filter Packet 3191 \ingroup filters_grp 3192 \brief Filter data exchange 3193 3194 Packets consist in block of data or reference to such blocks, passed from the source to the sink only. 3195 Internally, a packet created by a filter (output packet) is different from an input packet to a filter (\ref gf_filter_pid_get_packet) 3196 but the API has been designed to hide this, so that most packet functions can be called regardless of the input/output nature of the PID. 3197 3198 Packets have native attributes (timing, sap state, ...) but may also have any number of properties associated to them. 3199 3200 The generic design of the architecture is that each filter is free to decide how it handle PIDs and their packets. This implies that the filter session has no clue how 3201 an output packet relates to an input packet. 3202 Developpers must therefore manually copy packet properties that seem relevant, or more practically copy all properties from input packet to output packet and 3203 reassign output packet properties changed by the filter. 3204 3205 In order to handle reordering of packets, it is possible to keep references to either packets (may block the filter chain), or packet properties. 3206 3207 Packets shall always be dispatched in their processing order (decode order). If reordering upon reception is needed, or AU interleaving is used, a filter SHALL do the reordering. 3208 However, packets do not have to be send in their creation order: a created packet is not assigned to PID buffers until it is send. 3209 3210 @{ 3211 */ 3212 3213 3214 /*! Keeps a reference to the given input packet. The packet shall be released at some point using \ref gf_filter_pck_unref 3215 \param pck the target input packet 3216 \return error if any 3217 */ 3218 GF_Err gf_filter_pck_ref(GF_FilterPacket **pck); 3219 3220 /*! Remove a reference to the given input packet. The packet might be destroyed after that call. 3221 \param pck the target input packet 3222 */ 3223 void gf_filter_pck_unref(GF_FilterPacket *pck); 3224 3225 /*! Creates a reference to the packet properties, but not to the data. 3226 This is mostly useful for encoders/decoders/filters with delay, where the input packet needs to be released before getting the corresponding output (frame reordering & co). 3227 This allows merging back packet properties after some delay without blocking the filter chain. 3228 \param pck the target input packet 3229 \return error if any 3230 */ 3231 GF_Err gf_filter_pck_ref_props(GF_FilterPacket **pck); 3232 3233 3234 /*! Allocates a new packet on the output PID with associated allocated data. 3235 The packet has by default no DTS, no CTS, no duration framing set to full frame (start=end=1) and all other flags set to 0 (including SAP type). 3236 \param PID the target output PID 3237 \param data_size the desired size of the packet - can be changed later 3238 \param data set to the writable buffer of the created packet 3239 \return new packet or NULL if error 3240 */ 3241 GF_FilterPacket *gf_filter_pck_new_alloc(GF_FilterPid *PID, u32 data_size, u8 **data); 3242 3243 3244 /*! Allocates a new packet on the output PID referencing internal data. 3245 The packet has by default no DTS, no CTS, no duration framing set to full frame (start=end=1) and all other flags set to 0 (including SAP type). 3246 \param PID the target output PID 3247 \param data the data block to dispatch 3248 \param data_size the size of the data block to dispatch 3249 \param destruct the callback function used to destroy the packet when no longer used - may be NULL 3250 \return new packet or NULL if error 3251 */ 3252 GF_FilterPacket *gf_filter_pck_new_shared(GF_FilterPid *PID, const u8 *data, u32 data_size, gf_fsess_packet_destructor destruct); 3253 3254 /*! Allocates a new packet on the output PID referencing data of some input packet. 3255 The packet has by default no DTS, no CTS, no duration framing set to full frame (start=end=1) and all other flags set to 0 (including SAP type). 3256 \param PID the target output PID 3257 \param data the data block to dispatch - if NULL, the entire data of the source packet is used 3258 \param data_size the size of the data block to dispatch - if 0, the entire data of the source packet is used 3259 \param source_packet the source packet this data belongs to (at least from the filter point of view). 3260 \return new packet or NULL if error 3261 */ 3262 GF_FilterPacket *gf_filter_pck_new_ref(GF_FilterPid *PID, const u8 *data, u32 data_size, GF_FilterPacket *source_packet); 3263 3264 /*! Allocates a new packet on the output PID with associated allocated data. 3265 The packet has by default no DTS, no CTS, no duration framing set to full frame (start=end=1) and all other flags set to 0 (including SAP type). 3266 \param PID the target output PID 3267 \param data_size the desired size of the packet - can be changed later 3268 \param data set to the writable buffer of the created packet 3269 \param destruct the callback function used to destroy the packet when no longer used - may be NULL 3270 \return new packet or NULL if error 3271 */ 3272 GF_FilterPacket *gf_filter_pck_new_alloc_destructor(GF_FilterPid *PID, u32 data_size, u8 **data, gf_fsess_packet_destructor destruct); 3273 3274 /*! Clones a new packet from a source packet and copy all source properties to output. 3275 If the source packet uses a frame interface object or has no associated data, returns a copy of the packet. 3276 If the source packet is referenced more than once (ie more than just the caller), a new packet on the output PID is allocated with source data copied. 3277 Otherwise, the source data is assigned to the output packet. 3278 This is typically called by filter wishing to perform in-place processing of input data. 3279 \param PID the target output PID 3280 \param pck_source the desired source packet to clone 3281 \param data set to the writable buffer of the created packet 3282 \return new packet or NULL if error 3283 */ 3284 GF_FilterPacket *gf_filter_pck_new_clone(GF_FilterPid *PID, GF_FilterPacket *pck_source, u8 **data); 3285 3286 /*! Copies a new packet from a source packet and copy all source properties to output. 3287 \param PID the target output PID 3288 \param pck_source the desired source packet to clone 3289 \param data set to the writable buffer of the created packet 3290 \return new packet or NULL if error 3291 */ 3292 GF_FilterPacket *gf_filter_pck_new_copy(GF_FilterPid *PID, GF_FilterPacket *pck_source, u8 **data); 3293 3294 /*! Marks memory of a shared packet as non-writable. By default \ref gf_filter_pck_new_shared and \ref gf_filter_pck_new_ref allow 3295 write access to internal memory in case the packet can be cloned (single reference used). If your filter relies on the content of the shared 3296 memory for its internal state, packet must be marked as read-only to avoid later state corruption. 3297 Note that packets created with \ref gf_filter_pck_new_frame_interface are always treated as read-only packets 3298 \param pck the target output packet to send 3299 \return error if any 3300 */ 3301 GF_Err gf_filter_pck_set_readonly(GF_FilterPacket *pck); 3302 3303 /*! Sends the packet on its output PID. Packets SHALL be sent in processing order (eg, decoding order for video). 3304 However, packets don't have to be sent in their allocation order. 3305 \param pck the target output packet to send 3306 \return error if any 3307 */ 3308 GF_Err gf_filter_pck_send(GF_FilterPacket *pck); 3309 3310 /*! Destructs a packet allocated but that cannot be sent. Shall not be used on packet references. 3311 \param pck the target output packet to send 3312 */ 3313 void gf_filter_pck_discard(GF_FilterPacket *pck); 3314 3315 /*! Destructs a packet allocated but that cannot be sent. Shall not be used on packet references. 3316 This is a shortcut to \ref gf_filter_pck_new_ref + \ref gf_filter_pck_merge_properties + \ref gf_filter_pck_send 3317 \param reference the input packet to forward 3318 \param PID the output PID to forward to 3319 \return error code if any 3320 */ 3321 GF_Err gf_filter_pck_forward(GF_FilterPacket *reference, GF_FilterPid *PID); 3322 3323 /*! Gets data associated with the packet. 3324 \param pck the target packet 3325 \param size set to the packet data size 3326 \return packet data if any, NULL if empty or if the packet uses a frame interface object. see \ref gf_filter_pck_get_frame_interface 3327 */ 3328 const u8 *gf_filter_pck_get_data(GF_FilterPacket *pck, u32 *size); 3329 3330 /*! Sets a built-in property of a packet 3331 \param pck the target packet 3332 \param prop_4cc the code of the built-in property to set 3333 \param value the property value to set 3334 \return error code if any 3335 */ 3336 GF_Err gf_filter_pck_set_property(GF_FilterPacket *pck, u32 prop_4cc, const GF_PropertyValue *value); 3337 3338 /*! Sets a property of a packet 3339 \param pck the target packet 3340 \param name the name of the property to set 3341 \param value the property value to set 3342 \return error code if any 3343 */ 3344 GF_Err gf_filter_pck_set_property_str(GF_FilterPacket *pck, const char *name, const GF_PropertyValue *value); 3345 3346 /*! Sets a property of a packet 3347 \param pck the target packet 3348 \param name the code of the property to set. The name will be copied to the property, and memory destruction performed by the filter session 3349 \param value the property value to set 3350 \return error code if any 3351 */ 3352 GF_Err gf_filter_pck_set_property_dyn(GF_FilterPacket *pck, char *name, const GF_PropertyValue *value); 3353 3354 /*! Merge properties of source packet into destination packet but does NOT reset destination packet properties 3355 \param pck_src source packet 3356 \param pck_dst destination packet 3357 \return error code if any 3358 */ 3359 GF_Err gf_filter_pck_merge_properties(GF_FilterPacket *pck_src, GF_FilterPacket *pck_dst); 3360 3361 /*! Same as \ref gf_filter_pck_merge_properties but uses a filter callback to select properties to merge 3362 \param pck_src source packet 3363 \param pck_dst destination packet 3364 \param filter_prop callback filtering function 3365 \param cbk callback data passed to the callback function 3366 \return error code if any 3367 */ 3368 GF_Err gf_filter_pck_merge_properties_filter(GF_FilterPacket *pck_src, GF_FilterPacket *pck_dst, gf_filter_prop_filter filter_prop, void *cbk); 3369 3370 /*! Gets built-in property of packet. 3371 \param pck target packet 3372 \param prop_4cc the code of the built-in property 3373 \return the property if found, NULL otherwise 3374 */ 3375 const GF_PropertyValue *gf_filter_pck_get_property(GF_FilterPacket *pck, u32 prop_4cc); 3376 3377 /*! Gets property of packet. 3378 \param pck target packet 3379 \param prop_name the name of the property 3380 \return the property if found, NULL otherwise 3381 */ 3382 const GF_PropertyValue *gf_filter_pck_get_property_str(GF_FilterPacket *pck, const char *prop_name); 3383 3384 /*! Enumerates properties on packets. 3385 \param pck target packet 3386 \param idx input/output index of the current property. 0 means first. Incremented by 1 upon success 3387 \param prop_4cc set to the code of the built-in property 3388 \param prop_name set to the name of the property 3389 \return the property if found, NULL otherwise 3390 */ 3391 const GF_PropertyValue *gf_filter_pck_enum_properties(GF_FilterPacket *pck, u32 *idx, u32 *prop_4cc, const char **prop_name); 3392 3393 3394 /*! Sets packet framing info. A full frame is a complete entity for the stream type, ie an access unit for media streams and a complete file for file streams 3395 \param pck target packet 3396 \param is_start packet is start of the frame 3397 \param is_end packet is end of the frame 3398 \return error code if any 3399 */ 3400 GF_Err gf_filter_pck_set_framing(GF_FilterPacket *pck, Bool is_start, Bool is_end); 3401 3402 /*! Gets packet framing info. A full frame is a complete entity for the stream type, ie an access unit for media streams and a complete file for file streams 3403 \param pck target packet 3404 \param is_start set to GF_TRUE if packet is start of the frame, to GF_FALSE otherwise 3405 \param is_end set to GF_TRUE if packet is end of the frame, to GF_FALSE otherwise 3406 \return error code if any 3407 */ 3408 GF_Err gf_filter_pck_get_framing(GF_FilterPacket *pck, Bool *is_start, Bool *is_end); 3409 3410 /*! Sets Decoding Timestamp (DTS) of the packet. Do not set if unknown - automatic packet duration is based on DTS diff if DTS is present, otherwise in CTS diff. 3411 \param pck target packet 3412 \param dts decoding timestamp of packet, in PID timescale units 3413 \return error code if any 3414 */ 3415 GF_Err gf_filter_pck_set_dts(GF_FilterPacket *pck, u64 dts); 3416 3417 /*! Gets Decoding Timestamp (DTS) of the packet. 3418 \param pck target packet 3419 \return dts decoding timestamp of packet, in PID timescale units 3420 */ 3421 u64 gf_filter_pck_get_dts(GF_FilterPacket *pck); 3422 3423 /*! Sets Composition Timestamp (CTS) of the packet. Do not set if unknown - automatic packet duration is based on DTS diff if DTS is present, otherwise in CTS diff. 3424 \param pck target packet 3425 \param cts composition timestamp of packet, in PID timescale units 3426 \return error code if any 3427 */ 3428 GF_Err gf_filter_pck_set_cts(GF_FilterPacket *pck, u64 cts); 3429 3430 /*! Gets Composition Timestamp (CTS) of the packet. 3431 \param pck target packet 3432 \return cts composition timestamp of packet, in PID timescale units 3433 */ 3434 u64 gf_filter_pck_get_cts(GF_FilterPacket *pck); 3435 3436 /*! Returns packet timescale (same as PID timescale) 3437 \param pck target packet 3438 \return packet timescale 3439 */ 3440 u32 gf_filter_pck_get_timescale(GF_FilterPacket *pck); 3441 3442 /*! Sets packet duration 3443 \param pck target packet 3444 \param duration duration of packet, in PID timescale units 3445 \return error code if any 3446 */ 3447 GF_Err gf_filter_pck_set_duration(GF_FilterPacket *pck, u32 duration); 3448 3449 /*! Gets packet duration 3450 \param pck target packet 3451 \return duration duration of packet, in PID timescale units 3452 */ 3453 u32 gf_filter_pck_get_duration(GF_FilterPacket *pck); 3454 3455 /*! reallocates packet not yet sent. Returns data start and new range of data. This will reset byte offset information to not available. 3456 \param pck target packet 3457 \param nb_bytes_to_add bytes to add to packet 3458 \param data_start realloc pointer of packet data start - may be NULL if new_range_start is set 3459 \param new_range_start pointer to new (apppended space) data - may be NULL if data_start is set 3460 \param new_size full size of allocated block. - may be be NULL 3461 \return error code if any 3462 */ 3463 GF_Err gf_filter_pck_expand(GF_FilterPacket *pck, u32 nb_bytes_to_add, u8 **data_start, u8 **new_range_start, u32 *new_size); 3464 3465 /*! Truncates packet not yet sent to given size 3466 \param pck target packet 3467 \param size new size to truncate to 3468 \return error code if any 3469 */ 3470 GF_Err gf_filter_pck_truncate(GF_FilterPacket *pck, u32 size); 3471 3472 /*! SAP types as defined in annex I of ISOBMFF */ 3473 typedef enum 3474 { 3475 /*! no SAP */ 3476 GF_FILTER_SAP_NONE = 0, 3477 /*! closed gop no leading */ 3478 GF_FILTER_SAP_1, 3479 /*! closed gop leading */ 3480 GF_FILTER_SAP_2, 3481 /*! open gop */ 3482 GF_FILTER_SAP_3, 3483 /*! GDR */ 3484 GF_FILTER_SAP_4, 3485 } GF_FilterSAPType; 3486 3487 /*! Sets packet SAP type 3488 \param pck target packet 3489 \param sap_type SAP type of the packet 3490 \return error code if any 3491 */ 3492 GF_Err gf_filter_pck_set_sap(GF_FilterPacket *pck, GF_FilterSAPType sap_type); 3493 3494 /*! Sets packet SAP type 3495 \param pck target packet 3496 \return sap_type SAP type of the packet 3497 */ 3498 GF_FilterSAPType gf_filter_pck_get_sap(GF_FilterPacket *pck); 3499 3500 3501 /*! Sets packet video interlacing flag 3502 \param pck target packet 3503 \param is_interlaced set to 0 if not interlaced, 1 for top field first/contains only top field, 2 for bottom field first/contains only bottom field. 3504 \return error code if any 3505 */ 3506 GF_Err gf_filter_pck_set_interlaced(GF_FilterPacket *pck, u32 is_interlaced); 3507 3508 /*! Gets packet video interlacing flag 3509 \param pck target packet 3510 \return interlaced flag, set to 0 if not interlaced, 1 for top field first, 2 otherwise. 3511 */ 3512 u32 gf_filter_pck_get_interlaced(GF_FilterPacket *pck); 3513 3514 /*! Sets packet corrupted data flag 3515 \param pck target packet 3516 \param is_corrupted indicates if data in packet is corrupted 3517 \return error code if any 3518 */ 3519 GF_Err gf_filter_pck_set_corrupted(GF_FilterPacket *pck, Bool is_corrupted); 3520 3521 /*! Gets packet corrupted data flag 3522 \param pck target packet 3523 \return GF_TRUE if data in packet is corrupted 3524 */ 3525 Bool gf_filter_pck_get_corrupted(GF_FilterPacket *pck); 3526 3527 /*! Sets seek flag of packet. 3528 For PIDs of stream type FILE with GF_PROP_PID_DISABLE_PROGRESSIVE set, the seek flag set to GF_TRUE indicates 3529 that the packet is a PATCH packet, replacing bytes located at gf_filter_pck_get_byte_offset in file if the interlaced flag of the packet is not set, or 3530 inserting bytes located at gf_filter_pck_get_byte_offset in file if the interlaced flag of the packet is set. 3531 If the corrupted flag is set, this indicates the data will be replaced later on. 3532 A seek packet is not meant to be displayed but is needed for decoding. 3533 \param pck target packet 3534 \param is_seek indicates packet is seek frame 3535 \return error code if any 3536 */ 3537 GF_Err gf_filter_pck_set_seek_flag(GF_FilterPacket *pck, Bool is_seek); 3538 3539 /*! Gets packet seek data flag 3540 \param pck target packet 3541 \return GF_TRUE if packet is a seek packet 3542 */ 3543 Bool gf_filter_pck_get_seek_flag(GF_FilterPacket *pck); 3544 3545 /*! Sets packet byte offset in source. 3546 byte offset should only be set if the data in the packet is exactly the same as the one at the given byte offset 3547 \param pck target packet 3548 \param byte_offset indicates the byte offset in the source. By default packets are created with no byte offset 3549 \return error code if any 3550 */ 3551 GF_Err gf_filter_pck_set_byte_offset(GF_FilterPacket *pck, u64 byte_offset); 3552 3553 /*! Sets packet byte offset in source 3554 \param pck target packet 3555 \return byte offset in the source 3556 */ 3557 u64 gf_filter_pck_get_byte_offset(GF_FilterPacket *pck); 3558 3559 /*! Sets packet roll info (number of packets to rewind/forward and decode to get a clean access point). 3560 \param pck target packet 3561 \param roll_count indicates the roll distance of this packet - only used for SAP 4 for now 3562 \return error code if any 3563 */ 3564 GF_Err gf_filter_pck_set_roll_info(GF_FilterPacket *pck, s16 roll_count); 3565 3566 /*! Gets packet roll info. 3567 \param pck target packet 3568 \return roll distance of this packet 3569 \return error code if any 3570 */ 3571 s16 gf_filter_pck_get_roll_info(GF_FilterPacket *pck); 3572 3573 /*! Crypt flags for packet */ 3574 #define GF_FILTER_PCK_CRYPT 1 3575 3576 /*! Sets packet crypt flags 3577 \param pck target packet 3578 \param crypt_flag packet crypt flag 3579 \return error code if any 3580 */ 3581 GF_Err gf_filter_pck_set_crypt_flags(GF_FilterPacket *pck, u8 crypt_flag); 3582 3583 /*! Gets packet crypt flags 3584 \param pck target packet 3585 \return packet crypt flag 3586 */ 3587 u8 gf_filter_pck_get_crypt_flags(GF_FilterPacket *pck); 3588 3589 /*! Packet clock reference types - used for MPEG-2 TS*/ 3590 typedef enum 3591 { 3592 /*! packet is not a clock reference */ 3593 GF_FILTER_CLOCK_NONE=0, 3594 /*! packet is a PCR clock reference, expressed in PID timescale */ 3595 GF_FILTER_CLOCK_PCR, 3596 /*! packet is a PCR clock discontinuity, expressed in PID timescale */ 3597 GF_FILTER_CLOCK_PCR_DISC, 3598 } GF_FilterClockType; 3599 3600 /*! Sets packet clock type 3601 \param pck target packet 3602 \param ctype packet clock flag 3603 \return error code if any 3604 */ 3605 GF_Err gf_filter_pck_set_clock_type(GF_FilterPacket *pck, GF_FilterClockType ctype); 3606 3607 /*! Gets last clock type and clock value on PID. Always returns 0 if the source filter manages clock references internally cd \ref gf_filter_pid_set_clock_mode. 3608 \param PID target PID to query for clock 3609 \param clock_val last clock reference found 3610 \param timescale last clock reference timescale 3611 \return ctype packet clock flag 3612 */ 3613 GF_FilterClockType gf_filter_pid_get_clock_info(GF_FilterPid *PID, u64 *clock_val, u32 *timescale); 3614 3615 /*! Gets clock type of packet. Always returns 0 if the source filter does NOT manages clock references internally cd \ref gf_filter_pid_set_clock_mode. 3616 \param pck target packet 3617 \return ctype packet clock flag 3618 */ 3619 GF_FilterClockType gf_filter_pck_get_clock_type(GF_FilterPacket *pck); 3620 3621 /*! Sets packet carrousel info 3622 \param pck target packet 3623 \param version_number carrousel version number associated with this data chunk 3624 \return error code if any 3625 */ 3626 GF_Err gf_filter_pck_set_carousel_version(GF_FilterPacket *pck, u8 version_number); 3627 3628 /*! Gets packet carrousel info 3629 \param pck target packet 3630 \return version_number carrousel version number associated with this data chunk 3631 */ 3632 u8 gf_filter_pck_get_carousel_version(GF_FilterPacket *pck); 3633 3634 /*! Sets packet sample dependency flags. 3635 3636 Sample dependency flags have the same semantics as ISOBMFF:\n 3637 bit(2)is_leading bit(2)sample_depends_on (2)sample_is_depended_on (2)sample_has_redundancy\n 3638 \n 3639 is_leading takes one of the following four values:\n 3640 0: the leading nature of this sample is unknown;\n 3641 1: this sample is a leading sample that has a dependency before the referenced I-picture (and is therefore not decodable);\n 3642 2: this sample is not a leading sample;\n 3643 3: this sample is a leading sample that has no dependency before the referenced I-picture (and is therefore decodable);\n 3644 sample_depends_on takes one of the following four values:\n 3645 0: the dependency of this sample is unknown;\n 3646 1: this sample does depend on others (not an I picture);\n 3647 2: this sample does not depend on others (I picture);\n 3648 3: reserved\n 3649 sample_is_depended_on takes one of the following four values:\n 3650 0: the dependency of other samples on this sample is unknown;\n 3651 1: other samples may depend on this one (not disposable);\n 3652 2: no other sample depends on this one (disposable);\n 3653 3: reserved\n 3654 sample_has_redundancy takes one of the following four values:\n 3655 0: it is unknown whether there is redundant coding in this sample;\n 3656 1: there is redundant coding in this sample;\n 3657 2: there is no redundant coding in this sample;\n 3658 3: reserved\n 3659 3660 \param pck target packet 3661 \param dep_flags sample dependency flags 3662 \return error code if any 3663 */ 3664 GF_Err gf_filter_pck_set_dependency_flags(GF_FilterPacket *pck, u8 dep_flags); 3665 3666 /*! Gets packet sample dependency flags. 3667 \param pck target packet 3668 \return dep_flags sample dependency flags - see \ref gf_filter_pck_set_dependency_flags for syntax. 3669 */ 3670 u8 gf_filter_pck_get_dependency_flags(GF_FilterPacket *pck); 3671 3672 3673 /*! Sets packet sequence number. Shall only be used when a filter handles a PLAY request based on packet sequence number 3674 \param pck target packet 3675 \param seq_num sequence number of packet 3676 \return error code if any 3677 */ 3678 GF_Err gf_filter_pck_set_seq_num(GF_FilterPacket *pck, u32 seq_num); 3679 3680 /*! Gets packet sequence number info 3681 \param pck target packet 3682 \return version_number carrousel version number associated with this data chunk 3683 */ 3684 u32 gf_filter_pck_get_seq_num(GF_FilterPacket *pck); 3685 3686 /*! Redefinition of GF_Matrix but without the maths.h include which breaks VideoToolBox on OSX/iOS */ 3687 typedef struct __matrix GF_Matrix_unexposed; 3688 3689 /*! frame interface flags*/ 3690 enum 3691 { 3692 /*! When set , indicates that the emitting filter will block until this frame is released. 3693 Consumers of such a packet shall drop the packet as soon as possible, since it blocks the emiting filter.*/ 3694 GF_FRAME_IFCE_BLOCKING = 1, 3695 /*! When set , indicates that the associated framebuffer is the main GL framebuffer.*/ 3696 GF_FRAME_IFCE_MAIN_GLFB = 1<<1 3697 }; 3698 3699 /*! Frame interface object 3700 3701 The frame interface object can be used to expose an interface between the packet generated by a filter and its consumers, when dispatching a regular data block is not possible. 3702 This is typically used by decoders exposing the output image planes or by OpenGL filters outputing textures. 3703 Currently only video frames use this interface object. 3704 */ 3705 typedef struct _gf_filter_frame_interface 3706 { 3707 /*! get video frame plane 3708 \param frame interface object for the video frame 3709 \param plane_idx plane index, 0: Y or full plane, 1: U or UV plane, 2: V plane 3710 \param outPlane address of target color plane 3711 \param outStride stride in bytes of target color plane 3712 \return error code if any 3713 */ 3714 GF_Err (*get_plane)(struct _gf_filter_frame_interface *frame, u32 plane_idx, const u8 **outPlane, u32 *outStride); 3715 3716 /*! get video frame plane texture 3717 \param frame interface object for the video frame 3718 \param plane_idx plane index, 0: Y or full plane, 1: U or UV plane, 2: V plane 3719 \param gl_tex_format GL texture format used 3720 \param gl_tex_id GL texture ID used 3721 \param texcoordmatrix texture transform to fill. The texture is expected to be layed out as an image (first pixel is top-first). If not the case, add a vertical flip (eg dispatching an OpenGL FBO). \return error code if any 3722 */ 3723 GF_Err (*get_gl_texture)(struct _gf_filter_frame_interface *frame, u32 plane_idx, u32 *gl_tex_format, u32 *gl_tex_id, GF_Matrix_unexposed * texcoordmatrix); 3724 3725 /*! Flags for this frame interface.*/ 3726 u32 flags; 3727 3728 /*! private space for the emitting filter, consumers shall not modify this*/ 3729 void *user_data; 3730 } GF_FilterFrameInterface; 3731 3732 3733 /*! Allocates a new packet holding a reference to a frame interface object. 3734 The packet has by default no DTS, no CTS, no duration framing set to full frame (start=end=1) and all other flags set to 0 (including SAP type). 3735 \param PID the target output PID 3736 \param frame_ifce the associated frame interface object 3737 \param destruct the destructor to be called upon packet release 3738 \return new packet 3739 */ 3740 GF_FilterPacket *gf_filter_pck_new_frame_interface(GF_FilterPid *PID, GF_FilterFrameInterface *frame_ifce, gf_fsess_packet_destructor destruct); 3741 3742 /*! Gets a frame interface associated with a packet if any. 3743 3744 Consummers will typically first check if the packet has associated data using \ref gf_filter_pck_get_data. 3745 3746 \param pck the target packet 3747 \return the associated frame interface object if any, or NULL otherwise 3748 */ 3749 GF_FilterFrameInterface *gf_filter_pck_get_frame_interface(GF_FilterPacket *pck); 3750 3751 3752 /*! Checks if the packet is a blocking reference, i.e. a parent filter in the chain is waiting for its destruction to emit a new packet. 3753 This is typically used by sink filters to decide if they can hold references to input packets without blocking the chain. 3754 \param pck the target packet 3755 \return GF_TRUE if the packet is blocking or is a reference to a blocking packet, GF_FALSE otherwise 3756 */ 3757 Bool gf_filter_pck_is_blocking_ref(GF_FilterPacket *pck); 3758 3759 /*! @} */ 3760 3761 #ifdef __cplusplus 3762 } 3763 #endif 3764 3765 #endif //_GF_FILTERS_H_ 3766 3767