 |
libgpac
Documentation of the core library of GPAC
|
|
libgpac
Documentation of the core library of GPAC
|
Filter Session. More...
Collaboration diagram for Filter Session:Data Structures | |
| struct | GF_FilterStats |
Macros | |
| #define | GF_FS_DEFAULT_SEPS ":=#,!@" |
Typedefs | |
| typedef void(* | gf_fs_on_filter_creation) (void *udta, GF_Filter *filter, Bool is_destroy) |
| typedef GF_Err(* | gf_fs_gl_activate) (void *udta, Bool do_activate) |
The GPAC filter session object allows building media pipelines using multiple sources and destinations and arbitrary filter chains.
Filters are described through a __gf_filter_register structure. A set of built-in filters are available, and user-defined filters can be added or removed at runtime.
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.
The number of GF_FilterCapability matched between registries defines the weight of the connection.
Paths from an instantiated filter are enabled/disabled based on the source PID capabilities.
Paths to destination are recomputed for each destination, based on the instantiated destination filter capabilities.
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.
The resulting weighted graph is then solved using Dijkstra's algorithm, using filter priority in case of weight equality.
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.
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.
| struct GF_FilterStats |
Filter statistics object
Collaboration diagram for GF_FilterStats:| Data Fields | ||
|---|---|---|
| const GF_Filter * | filter |
filter object |
| const GF_Filter * | filter_alias |
set if filter is only an alias, in which case all remaining fields of the structure are not set |
| u64 | nb_tasks_done |
number of tasks executed by this filter |
| u64 | nb_pck_processed |
number of packets processed by this filter |
| u64 | nb_bytes_processed |
number of bytes processed by this filter |
| u64 | nb_pck_sent |
number of packets sent by this filter |
| u64 | nb_hw_pck_sent |
number of hardware frames packets sent by this filter |
| u32 | nb_errors |
number of processing errors in the lifetime of the filter |
| u64 | nb_bytes_sent |
number of bytes sent by this filter |
| u64 | time_process |
number of microseconds this filter was active |
| s32 | percent |
percentage of data processed (between 0 and 100), otherwise unknown (-1) |
| const char * | status |
last status report from filter, null if session reporting is not enabled |
| Bool | report_updated |
set to GF_TRUE of status or percent changed since last query for this filter, GF_FALSE otherwise |
| const char * | name |
filter name |
| const char * | reg_name |
filter register name |
| const char * | filter_id |
filter register ID |
| Bool | done |
set to GF_TRUE if filter is done processing |
| u32 | nb_pid_in |
number of input PIDs |
| u64 | nb_in_pck |
number of input packets processed |
| u32 | nb_pid_out |
number of output PIDs |
| u64 | nb_out_pck |
number of output packets sent |
| Bool | in_eos |
set to GF_TRUE if filter has seen end of stream |
| GF_FSFilterType | type |
set to the filter class type |
| u32 | stream_type |
set to streamtype of output PID if single output, GF_STREAM_UNKNOWN otherwise |
| u32 | codecid |
set to codecid of output PID if single output, GF_CODECID_NONE otherwise |
| GF_Fraction64 | last_ts_sent |
timestamp and timescale of last packet emitted on output pids |
| GF_Fraction64 | last_ts_drop |
timestamp and timescale of last packet dropped on input pids |
| #define GF_FS_DEFAULT_SEPS ":=#,!@" |
The default separator set used
callback functions for external monitoring of filter creation or destruction
| udta | user data passed back to callback |
| filter | created or destroyed filter |
| is_destroy | if GF_TRUE, the filter is being destroyed, otherwise it is being created |
callback functions for external monitoring of filter creation or destruction
| udta | user data passed back to callback |
| do_activate | if true context must be activated for calling thread, otherwise context is no longer used |
Filter session scheduler type
Filter session flags
| Enumerator | |
|---|---|
| GF_FS_FLAG_LOAD_META | Flag set to indicate meta filters should be loaded. A meta filter is a filter providing various sub-filters. The sub-filters are usually not exposed as filters, only the parent one is. When set, all sub-filters are exposed. This should only be set when inspecting filters help |
| GF_FS_FLAG_NON_BLOCKING | Flag set to run session in non-blocking mode. Each call to gf_fs_run will return as soon as there are no more pending tasks on the main thread |
| GF_FS_FLAG_NO_GRAPH_CACHE | 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) |
| GF_FS_FLAG_NO_REGULATION | Flag set to disable session regulation (no sleep) |
| GF_FS_FLAG_NO_PROBE | Flag set to disable data probe |
| GF_FS_FLAG_NO_REASSIGN | Flag set to disable source reassignment (e.g. switching from fin to ffdmx) in PID resolution |
| GF_FS_FLAG_PRINT_CONNECTIONS | Flag set to print enabled/disabled edges for debug of PID resolution |
| GF_FS_FLAG_NO_ARG_CHECK | Flag set to disable argument checking |
| GF_FS_FLAG_NO_RESERVOIR | Disables reservoir for packets and properties, uses much less memory but much more alloc/free |
| GF_FS_FLAG_FULL_LINK | Throws an error if any PID in the filter graph cannot be linked. The default behavior is to run the session even when some PIDs are not connected |
| GF_FS_FLAG_NO_IMPLICIT | Flag set to disable implicit linking By default the session runs in implicit linking when no link directives are set on any filter: linking aborts after the first successful pid if destination is not a sink, or links only to sinks otherwise.
|
| GF_FS_FLAG_REQUIRE_SOURCE_ID | Flag set to force all filters to require a source ID (same as setting RSID option on all filters). This is typically used when the app sets links on all used filters while declaring more, unused filters. |
| GF_FS_FLAG_FORCE_DEFER_LINK | Flag set to force all explicitly added filters to be loaded in deferred link state - linking will only happen once gf_filter_reconnect_output is called on the filter. |
| GF_FS_FLAG_PREVENT_PLAY | Flag set to ignore all PLAY events from sinks - use gf_fs_send_deferred_play to start playback |
| enum GF_FSFlushType |
Session flush types
| enum GF_FSFilterType |
Type of filter
| enum GF_SessionDebugFlag |
Flags for debug info
| GF_FilterSession* gf_fs_new | ( | s32 | nb_threads, |
| GF_FilterSchedulerType | type, | ||
| GF_FilterSessionFlags | flags, | ||
| const char * | blacklist | ||
| ) |
Creates a new filter session. This will also load all available filter registers not blacklisted.
| nb_threads | number of extra threads to allocate. A negative value means all core used by session (eg nb_cores-1 extra threads) |
| type | scheduler type |
| flags | set of above flags for the session. Modes set by flags cannot be changed at runtime |
| blacklist | string containing comma-separated names of filters to disable. If first character is '-', this describes a whitelist, i.e. only filters listed in this string will be allowed |
| GF_FilterSession* gf_fs_new_defaults | ( | GF_FilterSessionFlags | flags | ) |
Creates a new filter session, loading parameters from gpac config. This will also load all available filter registers not blacklisted.
| flags | set of flags for the session. Only GF_FS_FLAG_LOAD_META, GF_FS_FLAG_NON_BLOCKING , GF_FS_FLAG_NO_GRAPH_CACHE and GF_FS_FLAG_PRINT_CONNECTIONS are used, other flags are set from config file or command line |
| void gf_fs_del | ( | GF_FilterSession * | session | ) |
Destructs the filter session
| session | the filter session to destruct |
| GF_Filter* gf_fs_load_filter | ( | GF_FilterSession * | session, |
| const char * | name, | ||
| GF_Err * | err_code | ||
| ) |
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. Value can be omitted for boolean, defaulting to true (eg :allt). Using '!' before the name negates the result (eg :!moof_first). 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.
Options are either options for the target filter class, options to be inherited between the new filter and its implicit source(s) or implici destination(s), or generic filter options.
Generic filter options are:
=pid), missing input packet property (=pck) or both (=all)| session | filter session |
| name | name and arguments of the filter register to instantiate. |
| err_code | set to error code if any - may be NULL. If initially set to GF_EOS, disables log messages. |
| Bool gf_fs_filter_exists | ( | GF_FilterSession * | session, |
| const char * | name | ||
| ) |
Checks if a filter register exists by name.
| session | filter session |
| name | name of the filter register to check. |
| GF_Err gf_fs_run | ( | GF_FilterSession * | session | ) |
Runs the session
If the session is non-blocking (created with GF_FS_FLAG_NON_BLOCKING), process all tasks of oldest scheduled filter, process any pending PID connections and returns. Otherwise (session is blocking), runs until session is over or aborted.
| session | filter session |
| GF_Err gf_fs_set_separators | ( | GF_FilterSession * | session, |
| const char * | separator_set | ||
| ) |
Sets the set of separators to use when parsing args
| session | filter session |
| separator_set | filter session. The first char is used to separate argument names - default is ':' The second char, if present, is used to separate names and values - default is '=' The third char, if present, is used to separate fragments for PID sources - default is '#' The fourth char, if present, is used for list separators (sourceIDs, gfreg, ...) - default is ',' The fifth char, if present, is used for boolean negation - default is '!' The sixth char, if present, is used for LINK directives - default is '@' |
| GF_Err gf_fs_set_max_resolution_chain_length | ( | GF_FilterSession * | session, |
| u32 | max_chain_length | ||
| ) |
Sets the maximum length of a filter chain dynamically loaded to solve connection between two filters
| session | filter session |
| max_chain_length | sets maximum chain length when resolving filter links. Default value is 6 ([ in -> ] demux -> reframe -> decode -> encode -> reframe -> mux [ -> out ]) (filter chains loaded for adaptation (eg pixel format change, audio resample) are loaded after the link resolution) Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually |
| GF_Err gf_fs_set_max_sleep_time | ( | GF_FilterSession * | session, |
| u32 | max_sleep | ||
| ) |
Sets the maximum sleep time when postponing tasks.
| session | filter session |
| max_sleep | maximum sleep time in milliseconds. 0 means yield only. |
| u32 gf_fs_get_max_resolution_chain_length | ( | GF_FilterSession * | session | ) |
gets the maximum filter chain lengtG
| session | filter session |
| GF_Err gf_fs_stop | ( | GF_FilterSession * | session | ) |
Stops the session, waiting for all additional threads to complete
| session | filter session |
| u32 gf_fs_filters_registers_count | ( | GF_FilterSession * | session | ) |
Gets the number of available filter registries (not blacklisted)
| session | filter session |
| const GF_FilterRegister* gf_fs_get_filter_register | ( | GF_FilterSession * | session, |
| u32 | idx | ||
| ) |
Returns the register at the given index
| session | filter session |
| idx | index of register, from 0 to gf_fs_filters_registers_count |
| void gf_fs_register_test_filters | ( | GF_FilterSession * | session | ) |
Registers the test filters used for unit tests
| session | filter session |
| GF_Filter* gf_fs_load_source | ( | GF_FilterSession * | session, |
| const char * | url, | ||
| const char * | args, | ||
| const char * | parent_url, | ||
| GF_Err * | err | ||
| ) |
Loads a source filter from a URL and arguments
| session | filter session |
| 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://) |
| args | arguments for the filter, see gf_fs_load_filter - the arguments can also be set in the url, typycally using :gpac: option delimiter |
| parent_url | parent URL of the source, or NULL if none |
| err | if not NULL, is set to error code if any |
| GF_Filter* gf_fs_load_destination | ( | GF_FilterSession * | session, |
| const char * | url, | ||
| const char * | args, | ||
| const char * | parent_url, | ||
| GF_Err * | err | ||
| ) |
Loads a destination filter from a URL and arguments
| session | filter session |
| 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://) |
| args | arguments for the filter, see gf_fs_load_filter - the arguments can also be set in the url, typycally using :gpac: option delimiter |
| parent_url | parent URL of the source, or NULL if none |
| err | if not NULL, is set to error code if any |
| GF_Err gf_fs_get_last_connect_error | ( | GF_FilterSession * | session | ) |
Returns the last error which happened during a PID connection
| session | filter session |
| GF_Err gf_fs_get_last_process_error | ( | GF_FilterSession * | session | ) |
Returns the last error which happened during a filter process
| session | filter session |
| void gf_fs_add_filter_register | ( | GF_FilterSession * | session, |
| const GF_FilterRegister * | freg | ||
| ) |
Adds a user-defined register to the session - the register is added regardless of the session blacklist
| session | filter session |
| freg | filter register to add |
| void gf_fs_remove_filter_register | ( | GF_FilterSession * | session, |
| GF_FilterRegister * | freg | ||
| ) |
Removes a user-defined register from the session
| session | filter session |
| freg | filter register to remove |
| void gf_fs_send_deferred_play | ( | GF_FilterSession * | session | ) |
Sends PLAY event on all sinks, ignored if GF_FS_FLAG_PREVENT_PLAY flag is not set
| session | filter session |
| GF_Err gf_fs_post_user_task | ( | GF_FilterSession * | session, |
| Bool(*)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms) | task_execute, | ||
| void * | udta_callback, | ||
| const char * | log_name | ||
| ) |
Posts a user task to the session
| session | filter session |
| task_execute | the callback function for the task. The callback can return:
|
| udta_callback | callback user data passed back to the task_execute function |
| log_name | log name of the task. If NULL, default is "user_task" |
| GF_Err gf_fs_post_user_task_main | ( | GF_FilterSession * | session, |
| Bool(*)(GF_FilterSession *fsess, void *callback, u32 *reschedule_ms) | task_execute, | ||
| void * | udta_callback, | ||
| const char * | log_name | ||
| ) |
Posts a user task to the session main thread only
| session | filter session |
| task_execute | the callback function for the task. The callback can return:
|
| udta_callback | callback user data passed back to the task_execute function |
| log_name | log name of the task. If NULL, default is "user_task" |
| GF_Err gf_fs_abort | ( | GF_FilterSession * | session, |
| GF_FSFlushType | flush_type | ||
| ) |
Aborts the session. This can be called within a callback task to stop the session. Do NOT use gf_fs_stop from within a user task callback, this will deadlock the session
| session | filter session |
| flush_type | flush method to use |
| Bool gf_fs_is_last_task | ( | GF_FilterSession * | session | ) |
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
| session | filter session |
| Bool gf_fs_in_final_flush | ( | GF_FilterSession * | session | ) |
Checks if the session is in its final flush state (shutdown)
| session | filter session |
| Bool gf_fs_is_supported_mime | ( | GF_FilterSession * | session, |
| const char * | mime | ||
| ) |
Checks if a given MIME type is supported as input
| session | filter session |
| mime | MIME type to query |
| void gf_fs_set_ui_callback | ( | GF_FilterSession * | session, |
| Bool(*)(void *opaque, GF_Event *event) | ui_event_proc, | ||
| void * | cbk_udta | ||
| ) |
Sets UI callback event
| session | filter session |
| ui_event_proc | the event proc callback function. Its return value depends on the event type, usually 0 |
| cbk_udta | pointer passed back to callback |
| void gf_fs_print_stats | ( | GF_FilterSession * | session | ) |
Prints stats to logs using
| session | filter session |
| void gf_fs_print_connections | ( | GF_FilterSession * | session | ) |
Prints connections between loaded filters in the session to logs using
| session | filter session |
| void gf_fs_print_non_connected | ( | GF_FilterSession * | session | ) |
Prints the list of filters not connected using
| session | filter session |
| void gf_fs_print_non_connected_ex | ( | GF_FilterSession * | session, |
| Bool | ignore_sinks | ||
| ) |
Prints the list of filters not connected using
| session | filter session |
| ignore_sinks | if set, do not warn if some sinks are not connected (mostly used for playback cases) |
| void gf_fs_print_unused_args | ( | GF_FilterSession * | session, |
| const char * | ignore_args | ||
| ) |
Prints the list of arguments specified but not used by the filter session using
| session | filter session |
| ignore_args | ignore unused arguments if present in this comma-separated list - may be NULL |
| void gf_fs_print_all_connections | ( | GF_FilterSession * | session, |
| char * | filter_name, | ||
| void(*)(FILE *output, GF_SysPrintArgFlags flags, const char *fmt,...) | print_fn | ||
| ) |
Prints all possible connections between filter registries to logs using
| session | filter session |
| filter_name | if not null, only prints input connection for this filter register |
| print_fn | optional callback function for print, otherwise print to stderr |
| 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 | ||
| ) |
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.
| filter_reg | filter register to check |
| in_cap_code | capability code (property type) of input capability to check |
| in_cap | capabiility value of input capability to check |
| out_cap_code | capability code (property type) of output capability to check |
| out_cap | capability value of output capability to check |
| exact_match_only | if true returns TRUE only if exact match (code and value), otherwise return TRUE if caps code are matched |
| void gf_fs_enable_reporting | ( | GF_FilterSession * | session, |
| Bool | reporting_on | ||
| ) |
Enables or disables filter reporting
| session | filter session |
| reporting_on | if GF_TRUE, reporting will be enabled |
| void gf_fs_lock_filters | ( | GF_FilterSession * | session, |
| Bool | do_lock | ||
| ) |
Locks global session mutex - mostly used to query filter reports and avoids concurrent destruction of a filter. When adding a filter in an already running session, the session must be locked if set_source is to be used.
| session | filter session |
| do_lock | if GF_TRUE, session is locked, otherwise session is unlocked |
| u32 gf_fs_get_filters_count | ( | GF_FilterSession * | session | ) |
Gets number of active filters in the session
| session | filter session |
| GF_Filter* gf_fs_get_filter | ( | GF_FilterSession * | session, |
| u32 | idx | ||
| ) |
Gets a filter by its current index in the session
| session | filter session |
| idx | index in the filter session |
| GF_Err gf_fs_get_filter_stats | ( | GF_FilterSession * | session, |
| u32 | idx, | ||
| GF_FilterStats * | stats | ||
| ) |
Gets statistics for a given filter index in the session
| session | filter session |
| idx | index of filter to query |
| stats | statistics for filter |
| Bool gf_fs_enum_unmapped_options | ( | GF_FilterSession * | session, |
| u32 * | idx, | ||
| const char ** | argname, | ||
| u32 * | argtype, | ||
| const char ** | meta_name, | ||
| const char ** | meta_opt | ||
| ) |
Enumerates filter and meta-filter arguments not matched in the session. All output parameters may be NULL.
| session | filter session |
| idx | index of argument to query, 0 being first argument; this value is automatically incremented |
| argname | set to argument name |
| 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) |
| meta_name | set to meta filter name if any (for local filter args only) |
| meta_opt | set to meta filter suboption name if any (for local filter args only) |
| void gf_fs_send_update | ( | GF_FilterSession * | session, |
| const char * | fid, | ||
| GF_Filter * | filter, | ||
| const char * | name, | ||
| const char * | val, | ||
| GF_EventPropagateType | propagate_mask | ||
| ) |
Enumerates filter and meta-filter arguments not matched in the session
| session | filter session |
| fid | ID of filter on which to send the update, NULL if filter is set |
| filter | filter on which to send the update, NULL if fid is set |
| name | name of filter option to update |
| val | value of filter option to update |
| propagate_mask | propagation flags - 0 means no propagation |
| GF_Err gf_fs_load_script | ( | GF_FilterSession * | session, |
| const char * | jsfile | ||
| ) |
Loads JS script for filter session
| session | filter session |
| jsfile | path to local JS script file to use |
| u32 gf_fs_get_http_max_rate | ( | GF_FilterSession * | session | ) |
get max download rate allowed by download manager
| session | filter session |
| GF_Err gf_fs_set_http_max_rate | ( | GF_FilterSession * | session, |
| u32 | rate | ||
| ) |
set max download rate allowed by download manager
| session | filter session |
| rate | max rate in bps |
| u32 gf_fs_get_http_rate | ( | GF_FilterSession * | session | ) |
get current download rate of download manager, all active resources together
| session | filter session |
| Bool gf_fs_is_supported_source | ( | GF_FilterSession * | session, |
| const char * | url, | ||
| const char * | parent_url | ||
| ) |
check if a URL is likely to be supported
| session | filter session |
| url | the URL to test |
| parent_url | the parent URL |
| GF_Err gf_fs_set_filter_creation_callback | ( | GF_FilterSession * | session, |
| gf_fs_on_filter_creation | on_create_destroy, | ||
| void * | udta, | ||
| Bool | force_sync | ||
| ) |
assign callbacks for filter creation and destruction monitoring
| session | filter session |
| on_create_destroy | filter creation/destruction callback, may be NULL |
| udta | user data for callbacks, may be NULL |
| force_sync | execute tasks involving filter creation/setup and user tasks on main thread |
| void* gf_fs_get_rt_udta | ( | GF_FilterSession * | session | ) |
returns RT user data passed in gf_fs_set_filter_creation_callback
| session | filter session |
| Bool gf_fs_fire_event | ( | GF_FilterSession * | session, |
| GF_Filter * | filter, | ||
| GF_FilterEvent * | evt, | ||
| Bool | upstream | ||
| ) |
Fires an event on filter
| session | filter session |
| filter | target filter - if NULL, event will be executed on all filters. Otherwise, the event will be executed directly if its type is GF_FEVT_USER, and fired otherwise |
| evt | event to fire |
| upstream | if true, send event toward sinks, otherwise towards sources |
| GF_Err gf_fs_set_external_gl_provider | ( | GF_FilterSession * | session, |
| gf_fs_gl_activate | on_gl_activate, | ||
| void * | udta | ||
| ) |
assign callbacks for filter creation and destruction monitoring
| session | filter session |
| on_gl_activate | openGL context activation callback, must not be NULL |
| udta | user data for callbacks, may be NULL |
| void gf_fs_print_debug_info | ( | GF_FilterSession * | session, |
| GF_SessionDebugFlag | dbg_flags | ||
| ) |
prints session debug info on stderr
To turn on (resp.off) continous reporting, set (resp. unset) the flag GF_FS_DEBUG_CONTINUOUS. Continuous reporting is done in the main thread using the last flags provided
| session | filter session |
| dbg_flags | set of flags indicating what to print |
1.9.1