Filter Session. More...

Collaboration diagram for Filter Session:

Data Structures
struct	GF_FilterStats

Macros
#define	GF_FS_FLAG_LOAD_META 1<<1

#define	GF_FS_FLAG_NON_BLOCKING 1<<2

#define	GF_FS_FLAG_NO_GRAPH_CACHE 1<<3

#define	GF_FS_FLAG_NO_REGULATION 1<<4

#define	GF_FS_FLAG_NO_PROBE (1<<5)

#define	GF_FS_FLAG_NO_REASSIGN (1<<6)

#define	GF_FS_FLAG_PRINT_CONNECTIONS (1<<7)

#define	GF_FS_FLAG_NO_ARG_CHECK (1<<8)

#define	GF_FS_FLAG_NO_RESERVOIR (1<<9)

#define	GF_FS_FLAG_FULL_LINK (1<<10)

#define	GF_FS_FLAG_NO_IMPLICIT (1<<11)

#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)

Enumerations
enum	GF_FilterSchedulerType { GF_FS_SCHEDULER_LOCK_FREE =0 , GF_FS_SCHEDULER_LOCK , GF_FS_SCHEDULER_LOCK_FREE_X , GF_FS_SCHEDULER_LOCK_FORCE , GF_FS_SCHEDULER_DIRECT }

enum	GF_FSFlushType { GF_FS_FLUSH_NONE =0 , GF_FS_FLUSH_ALL , GF_FS_FLUSH_FAST }

enum	GF_FSFilterType { GF_FS_STATS_FILTER_GENERIC , GF_FS_STATS_FILTER_RAWIN , GF_FS_STATS_FILTER_DEMUX , GF_FS_STATS_FILTER_DECODE , GF_FS_STATS_FILTER_ENCODE , GF_FS_STATS_FILTER_MUX , GF_FS_STATS_FILTER_RAWOUT , GF_FS_STATS_FILTER_MEDIA_SINK , GF_FS_STATS_FILTER_MEDIA_SOURCE }

enum	GF_EventPropagateType { GF_FILTER_UPDATE_DOWNSTREAM = 1 , GF_FILTER_UPDATE_UPSTREAM = 1<<1 }

enum	GF_SessionDebugFlag { GF_FS_DEBUG_GRAPH = 1 , GF_FS_DEBUG_STATS = 1<<1 , GF_FS_DEBUG_TASKS = 1<<2 , GF_FS_DEBUG_FILTERS = 1<<3 , GF_FS_DEBUG_ALL = 0x00FFFFFF , GF_FS_DEBUG_CONTINUOUS = 0x80000000 }

Functions
GF_FilterSession *	gf_fs_new (s32 nb_threads, GF_FilterSchedulerType type, u32 flags, const char *blacklist)

GF_FilterSession *	gf_fs_new_defaults (u32 flags)

void	gf_fs_del (GF_FilterSession *session)

GF_Filter *	gf_fs_load_filter (GF_FilterSession session, const char name, GF_Err *err_code)

Bool	gf_fs_filter_exists (GF_FilterSession session, const char name)

GF_Err	gf_fs_run (GF_FilterSession *session)

GF_Err	gf_fs_set_separators (GF_FilterSession session, const char separator_set)

GF_Err	gf_fs_set_max_resolution_chain_length (GF_FilterSession *session, u32 max_chain_length)

GF_Err	gf_fs_set_max_sleep_time (GF_FilterSession *session, u32 max_sleep)

u32	gf_fs_get_max_resolution_chain_length (GF_FilterSession *session)

GF_Err	gf_fs_stop (GF_FilterSession *session)

u32	gf_fs_filters_registers_count (GF_FilterSession *session)

const GF_FilterRegister *	gf_fs_get_filter_register (GF_FilterSession *session, u32 idx)

void	gf_fs_register_test_filters (GF_FilterSession *session)

GF_Filter *	gf_fs_load_source (GF_FilterSession session, const char url, const char args, const char parent_url, GF_Err *err)

GF_Filter *	gf_fs_load_destination (GF_FilterSession session, const char url, const char args, const char parent_url, GF_Err *err)

GF_Err	gf_fs_get_last_connect_error (GF_FilterSession *session)

GF_Err	gf_fs_get_last_process_error (GF_FilterSession *session)

void	gf_fs_add_filter_register (GF_FilterSession session, const GF_FilterRegister freg)

void	gf_fs_remove_filter_register (GF_FilterSession session, GF_FilterRegister freg)

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)

GF_Err	gf_fs_post_user_task_main (GF_FilterSession session, Bool(task_execute)(GF_FilterSession fsess, void callback, u32 reschedule_ms), void udta_callback, const char *log_name)

GF_Err	gf_fs_abort (GF_FilterSession *session, GF_FSFlushType flush_type)

Bool	gf_fs_is_last_task (GF_FilterSession *session)

Bool	gf_fs_in_final_flush (GF_FilterSession *session)

Bool	gf_fs_is_supported_mime (GF_FilterSession session, const char mime)

void	gf_fs_set_ui_callback (GF_FilterSession session, Bool(ui_event_proc)(void opaque, GF_Event event), void *cbk_udta)

void	gf_fs_print_stats (GF_FilterSession *session)

void	gf_fs_print_connections (GF_FilterSession *session)

void	gf_fs_print_non_connected (GF_FilterSession *session)

void	gf_fs_print_non_connected_ex (GF_FilterSession *session, Bool ignore_sinks)

void	gf_fs_print_unused_args (GF_FilterSession session, const char ignore_args)

void	gf_fs_print_all_connections (GF_FilterSession session, char filter_name, void(print_fn)(FILE output, GF_SysPrintArgFlags flags, const char *fmt,...))

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)

void	gf_fs_enable_reporting (GF_FilterSession *session, Bool reporting_on)

void	gf_fs_lock_filters (GF_FilterSession *session, Bool do_lock)

u32	gf_fs_get_filters_count (GF_FilterSession *session)

GF_Filter *	gf_fs_get_filter (GF_FilterSession *session, u32 idx)

GF_Err	gf_fs_get_filter_stats (GF_FilterSession session, u32 idx, GF_FilterStats stats)

Bool	gf_fs_enum_unmapped_options (GF_FilterSession session, u32 idx, const char *argname, u32 argtype, const char meta_name, const char meta_opt)

void	gf_fs_send_update (GF_FilterSession session, const char fid, GF_Filter filter, const char name, const char *val, GF_EventPropagateType propagate_mask)

GF_Err	gf_fs_load_script (GF_FilterSession session, const char jsfile)

u32	gf_fs_get_http_max_rate (GF_FilterSession *session)

GF_Err	gf_fs_set_http_max_rate (GF_FilterSession *session, u32 rate)

u32	gf_fs_get_http_rate (GF_FilterSession *session)

Bool	gf_fs_is_supported_source (GF_FilterSession session, const char url, const char *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)

void *	gf_fs_get_rt_udta (GF_FilterSession *session)

Bool	gf_fs_fire_event (GF_FilterSession session, GF_Filter filter, GF_FilterEvent *evt, Bool upstream)

GF_Err	gf_fs_set_external_gl_provider (GF_FilterSession session, gf_fs_gl_activate on_gl_activate, void udta)

void	gf_fs_print_debug_info (GF_FilterSession *session, GF_SessionDebugFlag dbg_flags)

Detailed Description

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.

Data Structure Documentation

◆ GF_FilterStats

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

Macro Definition Documentation

◆ GF_FS_FLAG_LOAD_META

#define GF_FS_FLAG_LOAD_META 1<<1

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

#define GF_FS_FLAG_NON_BLOCKING 1<<2

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

#define GF_FS_FLAG_NO_GRAPH_CACHE 1<<3

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

#define GF_FS_FLAG_NO_REGULATION 1<<4

Flag set to disable session regulation (no sleep)

◆ GF_FS_FLAG_NO_PROBE

#define GF_FS_FLAG_NO_PROBE (1<<5)

Flag set to disable data probe

◆ GF_FS_FLAG_NO_REASSIGN

#define GF_FS_FLAG_NO_REASSIGN (1<<6)

Flag set to disable source reassignment (e.g. switching from fin to ffdmx) in PID resolution

◆ GF_FS_FLAG_PRINT_CONNECTIONS

#define GF_FS_FLAG_PRINT_CONNECTIONS (1<<7)

Flag set to print enabled/disabled edges for debug of PID resolution

◆ GF_FS_FLAG_NO_ARG_CHECK

#define GF_FS_FLAG_NO_ARG_CHECK (1<<8)

Flag set to disable argument checking

◆ GF_FS_FLAG_NO_RESERVOIR

#define GF_FS_FLAG_NO_RESERVOIR (1<<9)

Disables reservoir for packets and properties, uses much less memory but much more alloc/free

◆ GF_FS_FLAG_FULL_LINK

#define GF_FS_FLAG_FULL_LINK (1<<10)

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

#define GF_FS_FLAG_NO_IMPLICIT (1<<11)

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 successfull pid if destination is not a sink, or links only to sinks otherwise.

Note: This implies that the order in which filters are added to the session matters

◆ GF_FS_DEFAULT_SEPS

#define GF_FS_DEFAULT_SEPS ":=#,!@"

The default separator set used

Typedef Documentation

◆ gf_fs_on_filter_creation

typedef void(* gf_fs_on_filter_creation) (void *udta, GF_Filter *filter, Bool is_destroy)

callback functions for external monitoring of filter creation or destruction

Parameters

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

◆ gf_fs_gl_activate

typedef GF_Err(* gf_fs_gl_activate) (void *udta, Bool do_activate)

callback functions for external monitoring of filter creation or destruction

Parameters

udta	user data passed back to callback
do_activate	if true context must be activated for calling thread, otherwise context is no longer used

Returns: error if any

Enumeration Type Documentation

◆ GF_FilterSchedulerType

enum GF_FilterSchedulerType

Filter session scheduler type

Enumerator
GF_FS_SCHEDULER_LOCK_FREE	In this mode, the scheduler does not use locks for packet and property queues. Main task list is mutex-protected
GF_FS_SCHEDULER_LOCK	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
GF_FS_SCHEDULER_LOCK_FREE_X	In this mode, the scheduler does not use locks for packet and property queues, nor for the main task list
GF_FS_SCHEDULER_LOCK_FORCE	In this mode, the scheduler uses locks for packet and property queues even if single-threaded (test mode)
GF_FS_SCHEDULER_DIRECT	In this mode, the scheduler uses direct dispatch and no threads, trying to nest task calls within task calls

◆ GF_FSFlushType

enum GF_FSFlushType

Session flush types

Enumerator
GF_FS_FLUSH_NONE	Do not flush session: everything is discarded, potentially breaking output files
GF_FS_FLUSH_ALL	Flush all pending data before closing sessions: sources will be forced into end of stream and all emitted packets will be processed
GF_FS_FLUSH_FAST	Stop session (resetting buffers) and flush pipeline

◆ GF_FSFilterType

enum GF_FSFilterType

Type of filter

Enumerator
GF_FS_STATS_FILTER_GENERIC	Generic filter type accepting input(s) and producing output(s)
GF_FS_STATS_FILTER_RAWIN	raw input (file, socket, pipe) filter type
GF_FS_STATS_FILTER_DEMUX	demultiplexer filter type
GF_FS_STATS_FILTER_DECODE	decoder filter type
GF_FS_STATS_FILTER_ENCODE	encoder filter type
GF_FS_STATS_FILTER_MUX	multiplexer filter type
GF_FS_STATS_FILTER_RAWOUT	raw output (file, socket, pipe) filter type
GF_FS_STATS_FILTER_MEDIA_SINK	media sink (video out, audio out, ...) filter type
GF_FS_STATS_FILTER_MEDIA_SOURCE	media source (capture audio or video ...) filter type

◆ GF_EventPropagateType

enum GF_EventPropagateType

Flags for argument update event

Enumerator
GF_FILTER_UPDATE_DOWNSTREAM	the update event can be sent down the source chain
GF_FILTER_UPDATE_UPSTREAM	the update event can be sent up the filter chain

◆ GF_SessionDebugFlag

enum GF_SessionDebugFlag

Flags for debug info

Enumerator
GF_FS_DEBUG_GRAPH	print filter graph
GF_FS_DEBUG_STATS	print filter stats
GF_FS_DEBUG_TASKS	print tasks present in scheduler
GF_FS_DEBUG_FILTERS	print filter status and task scheduled on filter
GF_FS_DEBUG_ALL	print all info
GF_FS_DEBUG_CONTINUOUS	enable continuous reporting

Function Documentation

◆ gf_fs_new()

GF_FilterSession* gf_fs_new	(	s32	nb_threads,
		GF_FilterSchedulerType	type,
		u32	flags,
		const char *	blacklist
	)

Creates a new filter session. This will also load all available filter registers not blacklisted.

Parameters

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

Returns: the created filter session

◆ gf_fs_new_defaults()

GF_FilterSession* gf_fs_new_defaults ( u32 flags )

Creates a new filter session, loading parameters from gpac config. This will also load all available filter registers not blacklisted.

Parameters

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

Returns: the created filter session

◆ gf_fs_del()

void gf_fs_del ( GF_FilterSession * session )

Destructs the filter session

Parameters

session the filter session to destruct

◆ gf_fs_load_filter()

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.

Parameters

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.

Returns: created filter or NULL if filter register cannot be found

◆ gf_fs_filter_exists()

Bool gf_fs_filter_exists	(	GF_FilterSession *	session,
		const char *	name
	)

Checks if a filter register exists by name.

Parameters

session	filter session
name	name of the filter register to check.

Returns: GF_TRUE if a filter register exists with the given name, GF_FALSE otherwise

◆ gf_fs_run()

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.

Parameters

session filter session

Returns: error if any, or GF_EOS. The last errors can be retrieved using gf_fs_get_last_connect_error and gf_fs_get_last_process_error

◆ gf_fs_set_separators()

GF_Err gf_fs_set_separators	(	GF_FilterSession *	session,
		const char *	separator_set
	)

Sets the set of separators to use when parsing args

Parameters

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 '@'

Returns: error if any

◆ gf_fs_set_max_resolution_chain_length()

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

Parameters

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

Returns: error if any

◆ gf_fs_set_max_sleep_time()

GF_Err gf_fs_set_max_sleep_time	(	GF_FilterSession *	session,
		u32	max_sleep
	)

Sets the maximum sleep time when postponing tasks.

Parameters

session	filter session
max_sleep	maximum sleep time in milliseconds. 0 means yield only.

Returns: error if any

◆ gf_fs_get_max_resolution_chain_length()

u32 gf_fs_get_max_resolution_chain_length ( GF_FilterSession * session )

gets the maximum filter chain lengtG

Parameters

session filter session

Returns: maximum chain length when resolving filter links.

◆ gf_fs_stop()

GF_Err gf_fs_stop ( GF_FilterSession * session )

Stops the session, waiting for all additional threads to complete

Parameters

session filter session

Returns: error if any

◆ gf_fs_filters_registers_count()

u32 gf_fs_filters_registers_count ( GF_FilterSession * session )

Gets the number of available filter registries (not blacklisted)

Parameters

session filter session

Returns: number of filter registries

◆ gf_fs_get_filter_register()

const GF_FilterRegister* gf_fs_get_filter_register	(	GF_FilterSession *	session,
		u32	idx
	)

Returns the register at the given index

Parameters

session	filter session
idx	index of register, from 0 to gf_fs_filters_registers_count

Returns: the register object, or NULL if index is out of bounds

◆ gf_fs_register_test_filters()

void gf_fs_register_test_filters ( GF_FilterSession * session )

Registers the test filters used for unit tests

Parameters

session filter session

◆ gf_fs_load_source()

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

Parameters

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
parent_url	parent URL of the source, or NULL if none
err	if not NULL, is set to error code if any

Returns: the filter loaded or NULL if error

◆ gf_fs_load_destination()

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

Parameters

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
parent_url	parent URL of the source, or NULL if none
err	if not NULL, is set to error code if any

Returns: the filter loaded or NULL if error

◆ gf_fs_get_last_connect_error()

GF_Err gf_fs_get_last_connect_error ( GF_FilterSession * session )

Returns the last error which happened during a PID connection

Parameters

session filter session

Returns: the error code if any

◆ gf_fs_get_last_process_error()

GF_Err gf_fs_get_last_process_error ( GF_FilterSession * session )

Returns the last error which happened during a filter process

Parameters

session filter session

Returns: the error code if any

◆ gf_fs_add_filter_register()

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

Parameters

session	filter session
freg	filter register to add

◆ gf_fs_remove_filter_register()

void gf_fs_remove_filter_register	(	GF_FilterSession *	session,
		GF_FilterRegister *	freg
	)

Removes a user-defined register from the session

Parameters

session	filter session
freg	filter register to remove

◆ gf_fs_post_user_task()

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

Parameters

session	filter session
task_execute	the callback function for the task. The callback can return: GF_FALSE to cancel the task GF_TRUE to reschedule the task, in which case the task will be rescheduled immediately or after reschedule_ms.
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"

Returns: the error code if any

◆ gf_fs_post_user_task_main()

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

Parameters

session	filter session
task_execute	the callback function for the task. The callback can return: GF_FALSE to cancel the task GF_TRUE to reschedule the task, in which case the task will be rescheduled immediately or after reschedule_ms.
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"

Returns: the error code if any

◆ gf_fs_abort()

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

Parameters

session	filter session
flush_type	flush method to use

Returns: the error code if any

◆ gf_fs_is_last_task()

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

Parameters

session filter session

Returns: GF_TRUE if no more task, GF_FALSE otherwise

◆ gf_fs_in_final_flush()

Bool gf_fs_in_final_flush ( GF_FilterSession * session )

Checks if the session is in its final flush state (shutdown)

Parameters

session filter session

Returns: GF_TRUE if no session is aborting, GF_FALSE otherwise

◆ gf_fs_is_supported_mime()

Bool gf_fs_is_supported_mime	(	GF_FilterSession *	session,
		const char *	mime
	)

Checks if a given MIME type is supported as input

Parameters

session	filter session
mime	MIME type to query

Returns: GF_TRUE if MIME is supported

◆ gf_fs_set_ui_callback()

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

Parameters

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

◆ gf_fs_print_stats()

void gf_fs_print_stats ( GF_FilterSession * session )

Prints stats to logs using

LOG_APP@LOG_INFO

Parameters

session filter session

◆ gf_fs_print_connections()

void gf_fs_print_connections ( GF_FilterSession * session )

Prints connections between loaded filters in the session to logs using

LOG_APP@LOG_INFO

Parameters

session filter session

◆ gf_fs_print_non_connected()

void gf_fs_print_non_connected ( GF_FilterSession * session )

Prints the list of filters not connected using

LOG_APP@LOG_WARNING

Parameters

session filter session

◆ gf_fs_print_non_connected_ex()

void gf_fs_print_non_connected_ex	(	GF_FilterSession *	session,
		Bool	ignore_sinks
	)

Prints the list of filters not connected using

LOG_APP@LOG_WARNING

Parameters

session	filter session
ignore_sinks	if set, do not warn if some sinks are not connected (mostly used for playback cases)

◆ gf_fs_print_unused_args()

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

LOG_APP@LOG_WARNING

Note: This is simply a wrapper to gf_fs_enum_unmapped_options

Parameters

session	filter session
ignore_args	ignore unused arguments if present in this comma-separated list - may be NULL

◆ gf_fs_print_all_connections()

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

LOG_APP@LOG_INFO

Parameters

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

◆ gf_fs_check_filter_register_cap()

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.

Parameters

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

Returns: GF_TRUE if filter register has such a match, GF_FALSE otherwise

◆ gf_fs_enable_reporting()

void gf_fs_enable_reporting	(	GF_FilterSession *	session,
		Bool	reporting_on
	)

Enables or disables filter reporting

Parameters

session	filter session
reporting_on	if GF_TRUE, reporting will be enabled

◆ gf_fs_lock_filters()

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.

Parameters

session	filter session
do_lock	if GF_TRUE, session is locked, otherwise session is unlocked

◆ gf_fs_get_filters_count()

u32 gf_fs_get_filters_count ( GF_FilterSession * session )

Gets number of active filters in the session

Parameters

session filter session

Returns: number of active filters

◆ gf_fs_get_filter()

GF_Filter* gf_fs_get_filter	(	GF_FilterSession *	session,
		u32	idx
	)

Gets a filter by its current index in the session

Parameters

session	filter session
idx	index in the filter session

Returns: filter, or NULL if none found

◆ gf_fs_get_filter_stats()

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

Parameters

session	filter session
idx	index of filter to query
stats	statistics for filter

Returns: error code if any

◆ gf_fs_enum_unmapped_options()

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.

Parameters

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)

Returns: GF_TRUE if success, GF_FALSE if nothing more to enumerate

◆ gf_fs_send_update()

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

Parameters

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_fs_load_script()

GF_Err gf_fs_load_script	(	GF_FilterSession *	session,
		const char *	jsfile
	)

Loads JS script for filter session

Parameters

session	filter session
jsfile	path to local JS script file to use

Returns: error if any

◆ gf_fs_get_http_max_rate()

u32 gf_fs_get_http_max_rate ( GF_FilterSession * session )

get max download rate allowed by download manager

Parameters

session filter session

Returns: max rate in bps

◆ gf_fs_set_http_max_rate()

GF_Err gf_fs_set_http_max_rate	(	GF_FilterSession *	session,
		u32	rate
	)

set max download rate allowed by download manager

Parameters

session	filter session
rate	max rate in bps

Returns: error if any

◆ gf_fs_get_http_rate()

u32 gf_fs_get_http_rate ( GF_FilterSession * session )

get current download rate of download manager, all active resources together

Parameters

session filter session

Returns: current rate in bps

◆ gf_fs_is_supported_source()

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

Parameters

session	filter session
url	the URL to test
parent_url	the parent URL

Returns: GF_TRUE if a filter for such a source could be loaded

◆ gf_fs_set_filter_creation_callback()

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

Parameters

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

Returns: error if any

◆ gf_fs_get_rt_udta()

void* gf_fs_get_rt_udta ( GF_FilterSession * session )

returns RT user data passed in gf_fs_set_filter_creation_callback

Parameters

session filter session

Returns: udta user data, NULL if error or none

◆ gf_fs_fire_event()

Bool gf_fs_fire_event	(	GF_FilterSession *	session,
		GF_Filter *	filter,
		GF_FilterEvent *	evt,
		Bool	upstream
	)

Fires an event on filter

Parameters

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

Returns: GF_TRUE if event was sent, GF_FALSE otherwise

◆ gf_fs_set_external_gl_provider()

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

Parameters

session	filter session
on_gl_activate	openGL context activation callback, must not be NULL
udta	user data for callbacks, may be NULL

Returns: error if any

◆ gf_fs_print_debug_info()

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

Parameters

session	filter session
dbg_flags	set of flags indicating what to print

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ GF_FilterStats

Macro Definition Documentation

◆ GF_FS_FLAG_LOAD_META

◆ GF_FS_FLAG_NON_BLOCKING

◆ GF_FS_FLAG_NO_GRAPH_CACHE

◆ GF_FS_FLAG_NO_REGULATION

◆ GF_FS_FLAG_NO_PROBE

◆ GF_FS_FLAG_NO_REASSIGN

◆ GF_FS_FLAG_PRINT_CONNECTIONS

◆ GF_FS_FLAG_NO_ARG_CHECK

◆ GF_FS_FLAG_NO_RESERVOIR

◆ GF_FS_FLAG_FULL_LINK

◆ GF_FS_FLAG_NO_IMPLICIT

◆ GF_FS_DEFAULT_SEPS

Typedef Documentation

◆ gf_fs_on_filter_creation

◆ gf_fs_gl_activate

Enumeration Type Documentation

◆ GF_FilterSchedulerType

◆ GF_FSFlushType

◆ GF_FSFilterType

◆ GF_EventPropagateType

◆ GF_SessionDebugFlag

Function Documentation

◆ gf_fs_new()

◆ gf_fs_new_defaults()

◆ gf_fs_del()

◆ gf_fs_load_filter()

◆ gf_fs_filter_exists()

◆ gf_fs_run()

◆ gf_fs_set_separators()

◆ gf_fs_set_max_resolution_chain_length()

◆ gf_fs_set_max_sleep_time()

◆ gf_fs_get_max_resolution_chain_length()

◆ gf_fs_stop()

◆ gf_fs_filters_registers_count()

◆ gf_fs_get_filter_register()

◆ gf_fs_register_test_filters()

◆ gf_fs_load_source()

◆ gf_fs_load_destination()

◆ gf_fs_get_last_connect_error()

◆ gf_fs_get_last_process_error()

◆ gf_fs_add_filter_register()

◆ gf_fs_remove_filter_register()

◆ gf_fs_post_user_task()

◆ gf_fs_post_user_task_main()

◆ gf_fs_abort()

◆ gf_fs_is_last_task()

◆ gf_fs_in_final_flush()

◆ gf_fs_is_supported_mime()

◆ gf_fs_set_ui_callback()

◆ gf_fs_print_stats()

◆ gf_fs_print_connections()

◆ gf_fs_print_non_connected()

◆ gf_fs_print_non_connected_ex()

◆ gf_fs_print_unused_args()

◆ gf_fs_print_all_connections()

◆ gf_fs_check_filter_register_cap()

◆ gf_fs_enable_reporting()

◆ gf_fs_lock_filters()

◆ gf_fs_get_filters_count()

◆ gf_fs_get_filter()

◆ gf_fs_get_filter_stats()

◆ gf_fs_enum_unmapped_options()

◆ gf_fs_send_update()

◆ gf_fs_load_script()

◆ gf_fs_get_http_max_rate()

◆ gf_fs_set_http_max_rate()

◆ gf_fs_get_http_rate()

◆ gf_fs_is_supported_source()

◆ gf_fs_set_filter_creation_callback()

◆ gf_fs_get_rt_udta()

◆ gf_fs_fire_event()