Collaboration diagram for Filter:

Data Structures
struct	GF_FilterArgs

struct	GF_FilterCapability

struct	GF_FilterSessionCaps

struct	GF_FilterRegister

struct	GF_FSEventListener

Macros
#define	CAP_SINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_SINT, .value.sint = _b}, .flags=(_f) }

#define	CAP_UINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f) }

#define	CAP_4CC(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_4CC, .value.uint = _b}, .flags=(_f) }

#define	CAP_LSINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_LSINT, .value.longsint = _b}, .flags=(_f) }

#define	CAP_LUINT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_LUINT, .value.longuint = _b}, .flags=(_f) }

#define	CAP_BOOL(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_BOOL, .value.boolean = _b}, .flags=(_f) }

#define	CAP_FIXED(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = _b}, .flags=(_f) }

#define	CAP_FLOAT(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = FLT2FIX(_b)}, .flags=(_f) }

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

#define	CAP_FRAC(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_FRACTION, .value.frac = _b}, .flags=(_f) }

#define	CAP_DOUBLE(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_DOUBLE, .value.number = _b}, .flags=(_f) }

#define	CAP_NAME(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_NAME, .value.string = _b}, .flags=(_f) }

#define	CAP_STRING(_f, _a, _b) { .code=_a, .val={.type=GF_PROP_STRING, .value.string = _b}, .flags=(_f) }

#define	CAP_UINT_PRIORITY(_f, _a, _b, _p) { .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f), .priority=_p}

#define	GF_CAPS_INPUT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT)

#define	GF_CAPS_INPUT_OPT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_OPTIONAL)

#define	GF_CAPS_INPUT_STATIC (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_STATIC)

#define	GF_CAPS_INPUT_STATIC_OPT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_STATIC\|GF_CAPFLAG_OPTIONAL)

#define	GF_CAPS_INPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_EXCLUDED)

#define	GF_CAPS_INPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_LOADED_FILTER)

#define	GF_CAPS_OUTPUT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_OUTPUT)

#define	GF_CAPS_OUTPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_LOADED_FILTER)

#define	GF_CAPS_OUTPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_EXCLUDED)

#define	GF_CAPS_OUTPUT_STATIC (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_STATIC)

#define	GF_CAPS_OUTPUT_STATIC_EXCLUDED (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_EXCLUDED\|GF_CAPFLAG_STATIC)

#define	GF_CAPS_INPUT_OUTPUT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_OUTPUT)

#define	GF_CAPS_INPUT_OUTPUT_OPT (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_OPTIONAL)

#define	GF_CAPS_IN_OUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE\|GF_CAPFLAG_INPUT\|GF_CAPFLAG_OUTPUT\|GF_CAPFLAG_EXCLUDED)

#define	SETCAPS(__struct) .caps = __struct, .nb_caps=sizeof(__struct)/sizeof(GF_FilterCapability)

#define	GF_FS_SET_DESCRIPTION(_desc) .description = _desc,

#define	GF_FS_SET_AUTHOR(_author) .author = _author,

#define	GF_FS_SET_HELP(_help) .help = _help,

#define	GF_FS_DEF_ARG(_name, _offset, _desc, _type, _default, _enum, _flags) { _name, _offset, _desc, _type, _default, _enum, _flags }

Enumerations
enum	GF_FSArgumentFlags { GF_FS_ARG_HINT_NORMAL = 0, GF_FS_ARG_HINT_ADVANCED = 1<<1, GF_FS_ARG_HINT_EXPERT = 1<<2, GF_FS_ARG_HINT_HIDE = 1<<3, GF_FS_ARG_UPDATE = 1<<4, GF_FS_ARG_META = 1<<5, GF_FS_ARG_META_ALLOC = 1<<6, GF_FS_ARG_SINK_ALIAS = 1<<7, GF_FS_ARG_UPDATE_SYNC = 1<<8 }

enum	{ GF_CAPFLAG_IN_BUNDLE = 1, GF_CAPFLAG_INPUT = 1<<1, GF_CAPFLAG_OUTPUT = 1<<2, GF_CAPFLAG_EXCLUDED = 1<<3, GF_CAPFLAG_LOADED_FILTER = 1<<4, GF_CAPFLAG_STATIC = 1<<5, GF_CAPFLAG_OPTIONAL = 1<<6 }

enum	GF_FilterProbeScore { GF_FPROBE_NOT_SUPPORTED = 0, GF_FPROBE_MAYBE_NOT_SUPPORTED, GF_FPROBE_MAYBE_SUPPORTED, GF_FPROBE_SUPPORTED, GF_FPROBE_FORCE, GF_FPROBE_EXT_MATCH }

enum	GF_FSRegisterFlags { GF_FS_REG_MAIN_THREAD = 1<<1, GF_FS_REG_CONFIGURE_MAIN_THREAD = 1<<2, GF_FS_REG_EXPLICIT_ONLY = 1<<3, GF_FS_REG_HIDE_WEIGHT = 1<<4, GF_FS_REG_ACT_AS_SOURCE = 1<<5, GF_FS_REG_ALLOW_CYCLIC = 1<<6, GF_FS_REG_DYNAMIC_PIDS = 1<<7, GF_FS_REG_SCRIPT = 1<<8, GF_FS_REG_META = 1<<9, GF_FS_REG_DYNAMIC_REDIRECT = 1<<10, GF_FS_REG_REQUIRES_RESOLVER = 1<<11, GF_FS_REG_CUSTOM = 0x40000000 }

enum	GF_FilterSessionSepType { GF_FS_SEP_ARGS =0, GF_FS_SEP_NAME, GF_FS_SEP_FRAG, GF_FS_SEP_LIST, GF_FS_SEP_NEG }

Functions
void	gf_filter_get_session_caps (GF_Filter filter, GF_FilterSessionCaps caps)

void	gf_filter_set_session_caps (GF_Filter filter, GF_FilterSessionCaps caps)

Bool	gf_filter_is_instance_of (GF_Filter filter, const GF_FilterRegister freg)

void	gf_filter_abort (GF_Filter *filter)

void	gf_filter_lock (GF_Filter *filter, Bool do_lock)

void	gf_filter_lock_all (GF_Filter *filter, Bool do_lock)

void	gf_filter_require_source_id (GF_Filter *filter)

void *	gf_filter_get_udta (GF_Filter *filter)

void	gf_filter_set_name (GF_Filter filter, const char name)

const char *	gf_filter_get_name (GF_Filter *filter)

void	gf_filter_make_sticky (GF_Filter *filter)

u32	gf_filter_get_num_events_queued (GF_Filter *filter)

GF_DownloadManager *	gf_filter_get_download_manager (GF_Filter *filter)

struct _gf_ft_mgr *	gf_filter_get_font_manager (GF_Filter *filter)

void	gf_filter_ask_rt_reschedule (GF_Filter *filter, u32 us_until_next)

void	gf_filter_post_process_task (GF_Filter *filter)

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)

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)

void	gf_filter_setup_failure (GF_Filter *filter, GF_Err reason)

void	gf_filter_notification_failure (GF_Filter *filter, GF_Err reason, Bool force_disconnect)

void	gf_filter_remove_src (GF_Filter filter, GF_Filter src_filter)

void	gf_filter_remove (GF_Filter *filter)

void	gf_filter_set_max_extra_input_pids (GF_Filter *filter, u32 max_extra_pids)

u32	gf_filter_get_max_extra_input_pids (GF_Filter *filter)

Bool	gf_filter_block_enabled (GF_Filter *filter)

void	gf_filter_block_eos (GF_Filter *filter, Bool do_block)

GF_Filter *	gf_filter_connect_source (GF_Filter filter, const char url, const char parent_url, Bool inherit_args, GF_Err err)

GF_Filter *	gf_filter_connect_destination (GF_Filter filter, const char url, GF_Err *err)

GF_Filter *	gf_filter_load_filter (GF_Filter filter, const char name, GF_Err *err_code)

Bool	gf_filter_is_supported_source (GF_Filter filter, const char url, const char *parent_url)

u32	gf_filter_get_ipid_count (GF_Filter *filter)

GF_FilterPid *	gf_filter_get_ipid (GF_Filter *filter, u32 idx)

u32	gf_filter_get_opid_count (GF_Filter *filter)

GF_FilterPid *	gf_filter_get_opid (GF_Filter *filter, u32 idx)

void	gf_filter_get_output_buffer_max (GF_Filter filter, u32 max_buf, u32 *max_playout_buf)

void	gf_filter_hint_single_clock (GF_Filter *filter, u64 time_in_us, GF_Fraction64 media_timestamp)

void	gf_filter_get_clock_hint (GF_Filter filter, u64 time_in_us, GF_Fraction64 *media_timestamp)

GF_Err	gf_filter_set_source (GF_Filter filter, GF_Filter link_from, const char *link_ext)

GF_Err	gf_filter_set_source_restricted (GF_Filter filter, GF_Filter link_from, const char *link_ext)

void	gf_filter_reset_source (GF_Filter *filter)

GF_Err	gf_filter_assign_id (GF_Filter filter, const char filter_id)

const char *	gf_filter_get_id (GF_Filter *filter)

void	gf_filter_set_blocking (GF_Filter *filter, Bool is_blocking)

GF_Err	gf_filter_override_caps (GF_Filter filter, const GF_FilterCapability caps, u32 nb_caps)

GF_Err	gf_filter_act_as_sink (GF_Filter *filter)

u8	gf_filter_get_sep (GF_Filter *filter, GF_FilterSessionSepType sep_type)

const char *	gf_filter_get_dst_args (GF_Filter *filter)

char *	gf_filter_get_dst_name (GF_Filter *filter)

const char *	gf_filter_get_src_args (GF_Filter *filter)

void	gf_filter_send_event (GF_Filter filter, GF_FilterEvent evt, Bool upstream)

GF_Err	gf_filter_reconnect_output (GF_Filter *filter)

GF_Err	gf_filter_set_event_target (GF_Filter *filter, Bool enable_events)

const GF_PropertyValue *	gf_filter_get_info (GF_Filter filter, u32 prop_4cc, GF_PropertyEntry *propentry)

const GF_PropertyValue *	gf_filter_get_info_str (GF_Filter filter, const char prop_name, GF_PropertyEntry **propentry)

void	gf_filter_release_property (GF_PropertyEntry *propentry)

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)

GF_Err	gf_filter_add_event_listener (GF_Filter filter, GF_FSEventListener el)

GF_Err	gf_filter_remove_event_listener (GF_Filter filter, GF_FSEventListener el)

Bool	gf_filter_forward_gf_event (GF_Filter filter, GF_Event evt, Bool consumed, Bool skip_user)

Bool	gf_filter_send_gf_event (GF_Filter filter, GF_Event evt)

Bool	gf_filter_all_sinks_done (GF_Filter *filter)

const char *	gf_filter_get_arg_str (GF_Filter filter, const char arg_name, char dump[GF_PROP_DUMP_ARG_SIZE])

Bool	gf_filter_get_arg (GF_Filter filter, const char arg_name, GF_PropertyValue *prop)

Bool	gf_filter_is_supported_mime (GF_Filter filter, const char mime)

Bool	gf_filter_ui_event (GF_Filter filter, GF_Event uievt)

void	gf_filter_register_opengl_provider (GF_Filter *filter, Bool do_register)

GF_Err	gf_filter_request_opengl (GF_Filter *filter)

GF_Err	gf_filter_set_active_opengl_context (GF_Filter *filter)

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)

void	gf_filter_disable_probe (GF_Filter *filter)

void	gf_filter_disable_inputs (GF_Filter *filter)

Bool	gf_filter_has_pid_connection_pending (GF_Filter filter, GF_Filter stop_at_filter)

Bool	gf_filter_connections_pending (GF_Filter *filter)

GF_Err	gf_filter_prevent_blocking (GF_Filter *filter, Bool prevent_blocking_enabled)

Bool	gf_filter_is_dynamic (GF_Filter *filter)

Bool	gf_filter_reporting_enabled (GF_Filter *filter)

GF_Err	gf_filter_update_status (GF_Filter filter, u32 percent, char szStatus)

Bool	gf_filter_end_of_session (GF_Filter *filter)

void	gf_filter_report_meta_option (GF_Filter filter, const char arg, Bool was_found)

GF_Err	gf_filter_set_description (GF_Filter filter, const char new_desc)

const char *	gf_filter_get_description (GF_Filter *filter)

GF_Err	gf_filter_set_version (GF_Filter filter, const char new_version)

const char *	gf_filter_get_version (GF_Filter *filter)

GF_Err	gf_filter_set_author (GF_Filter filter, const char new_author)

const char *	gf_filter_get_author (GF_Filter *filter)

GF_Err	gf_filter_set_help (GF_Filter filter, const char new_help)

const char *	gf_filter_get_help (GF_Filter *filter)

GF_Err	gf_filter_define_args (GF_Filter filter, GF_FilterArgs new_args)

GF_FilterArgs *	gf_filter_get_args (GF_Filter *filter)

const GF_FilterCapability *	gf_filter_get_caps (GF_Filter filter, u32 nb_caps)

const char *	gf_filter_probe_data (GF_Filter filter, u8 data, u32 size)

Bool	gf_filter_is_alias (GF_Filter *filter)

Bool	gf_filter_in_parent_chain (GF_Filter parent, GF_Filter filter)

GF_Err	gf_filter_get_stats (GF_Filter filter, GF_FilterStats stats)

const GF_FilterArgs *	gf_filter_enumerate_args (GF_Filter *filter, u32 idx)

Bool	gf_filter_relocate_url (GF_Filter filter, const char service_url, const char parent_url, char out_relocated_url, char *out_localized_url)

Detailed Description

The API for filters documents declaration of filters, their creation and functions available to interact with the filter session. 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.

Calling these functions on other filters will result in unpredictable behavior, very likely crashes in multi-threading conditions.

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.

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

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 will contain a stream type for input a stream type for output, a codec id for input and a codec id for output.

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 stream_type/codecID to file extension and MIME type - cf gpac/src/filters/write_generic.c

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, it must match the capability requirement (equal, excluded). If no property exists for a given non-optional capability type, the bundle is marked as not matching and the ext capability bundle in the filter is checked. A PID property not listed in any capability of the filter does not impact the matching.

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.

Data Structure Documentation

◆ GF_FilterArgs

struct GF_FilterArgs

Structure holding arguments for a filter

Data Fields
const char *	arg_name	argument name. Naming conventions: only use lowercase keep short and avoid '_'
s32	offset_in_private	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. The offset is casted into the corresponding property value of the argument type
const char *	arg_desc	description of argument. Format conventions: first letter is lowercase except if it is an acronym (eg, 'IP'). description does not end with a '.'; multiple sentences are however allowed with '.' separators. description does not end with a new line CR or LF; multiple sentences are however allowed with '.' separators. keep it short. If too long, use " - see filter help" and put description in filter help. only use markdown '‘’ and '*', except for enumeration lists which shall use "- ". do not use CR/LF in description except to start enum types description. use infinitive (eg "set foo to bar" and not "sets foo to bar"). Enumerations should be described as: sentence(s)' ' (no '.' nor ':' at end) name1: val' ' (no '.' at end) nameN: val (no '.' nor ' ' at end of last value description) and enum value description order shall match enum order links are allowed, see GF_FilterRegister doc
GF_PropType	arg_type	type of argument - this is a property type
const char *	arg_default_val	default value of argument, can be NULL (for number types, value 0 for each dimension of the type is assumed)
const char *	min_max_enum	string describing an enum (unsigned integer type) or a min/max value. For min/max, the syntax is "min,max", with -I = -infinity and +I = +infinity 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 Naming conventions for enumeration: use single word use lowercase escept for single/double characters name (eg 'A', 'V').
GF_FSArgumentFlags	flags	set of argument flags

◆ GF_FilterCapability

struct GF_FilterCapability

Filter capability description

Data Fields
u32	code	4cc of the capability listed. This shall be 0 or the type of a built-in property
GF_PropertyValue	val	default type and value of the capability listed
const char *	name	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)
u32	flags	Flags of the capability
u8	priority	overrides the filter register priority for this capability. Usually 0

◆ GF_FilterSessionCaps

struct GF_FilterSessionCaps

Filter session capability structure

Data Fields
u32	max_screen_width
u32	max_screen_height
u32	max_screen_bpp
u32	max_screen_fps
u32	max_screen_nb_views
u32	max_audio_channels
u32	max_audio_sample_rate
u32	max_audio_bit_depth

Macro Definition Documentation

◆ CAP_SINT

#define CAP_SINT	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_SINT, .value.sint = _b}, .flags=(_f) }

Shortcut macro to assign singed integer capability type

◆ CAP_UINT

#define CAP_UINT	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f) }

Shortcut macro to assign unsigned integer capability type

◆ CAP_4CC

#define CAP_4CC	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_4CC, .value.uint = _b}, .flags=(_f) }

Shortcut macro to assign unsigned integer capability type

◆ CAP_LSINT

#define CAP_LSINT	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_LSINT, .value.longsint = _b}, .flags=(_f) }

Shortcut macro to assign signed long integer capability type

◆ CAP_LUINT

#define CAP_LUINT	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_LUINT, .value.longuint = _b}, .flags=(_f) }

Shortcut macro to assign unsigned long integer capability type

◆ CAP_BOOL

#define CAP_BOOL	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_BOOL, .value.boolean = _b}, .flags=(_f) }

Shortcut macro to assign boolean capability type

◆ CAP_FIXED

#define CAP_FIXED	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = _b}, .flags=(_f) }

Shortcut macro to assign fixed-point number capability type

◆ CAP_FLOAT

#define CAP_FLOAT	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_FLOAT, .value.fnumber = FLT2FIX(_b)}, .flags=(_f) }

Shortcut macro to assign float capability type

◆ CAP_FRAC_INT

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

Shortcut macro to assign 32-bit fraction capability type

◆ CAP_FRAC

#define CAP_FRAC	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_FRACTION, .value.frac = _b}, .flags=(_f) }

Shortcut macro to assign 32-bit fraction capability type from integers

◆ CAP_DOUBLE

#define CAP_DOUBLE	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_DOUBLE, .value.number = _b}, .flags=(_f) }

Shortcut macro to assign double capability type

◆ CAP_NAME

#define CAP_NAME	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_NAME, .value.string = _b}, .flags=(_f) }

Shortcut macro to assign name (const string) capability type

◆ CAP_STRING

#define CAP_STRING	(	_f,
		_a,
		_b
	)	{ .code=_a, .val={.type=GF_PROP_STRING, .value.string = _b}, .flags=(_f) }

Shortcut macro to assign string capability type

◆ CAP_UINT_PRIORITY

#define CAP_UINT_PRIORITY	(	_f,
		_a,
		_b,
		_p
	)	{ .code=_a, .val={.type=GF_PROP_UINT, .value.uint = _b}, .flags=(_f), .priority=_p}

Shortcut macro to assign unsigned integer capability type with capability priority

◆ GF_CAPS_INPUT

#define GF_CAPS_INPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT)

Shortcut macro to set for input capability flags

◆ GF_CAPS_INPUT_OPT

#define GF_CAPS_INPUT_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OPTIONAL)

Shortcut macro to set for optional input capability flags

◆ GF_CAPS_INPUT_STATIC

#define GF_CAPS_INPUT_STATIC (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_STATIC)

Shortcut macro to set for static input capability flags

◆ GF_CAPS_INPUT_STATIC_OPT

#define GF_CAPS_INPUT_STATIC_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_STATIC|GF_CAPFLAG_OPTIONAL)

Shortcut macro to set for static optional input capability flags

◆ GF_CAPS_INPUT_EXCLUDED

#define GF_CAPS_INPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_EXCLUDED)

Shortcut macro to set for excluded input capability flags

◆ GF_CAPS_INPUT_LOADED_FILTER

#define GF_CAPS_INPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_LOADED_FILTER)

Shortcut macro to set for input for loaded filter only capability flags

◆ GF_CAPS_OUTPUT

#define GF_CAPS_OUTPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT)

Shortcut macro to set for output capability flags

◆ GF_CAPS_OUTPUT_LOADED_FILTER

#define GF_CAPS_OUTPUT_LOADED_FILTER (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_LOADED_FILTER)

Shortcut macro to set for output for loaded filter only capability flags

◆ GF_CAPS_OUTPUT_EXCLUDED

#define GF_CAPS_OUTPUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_EXCLUDED)

Shortcut macro to set for excluded output capability flags

◆ GF_CAPS_OUTPUT_STATIC

#define GF_CAPS_OUTPUT_STATIC (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_STATIC)

Shortcut macro to set for static output capability flags

◆ GF_CAPS_OUTPUT_STATIC_EXCLUDED

#define GF_CAPS_OUTPUT_STATIC_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_EXCLUDED|GF_CAPFLAG_STATIC)

Shortcut macro to set for excluded static output capability flags

◆ GF_CAPS_INPUT_OUTPUT

#define GF_CAPS_INPUT_OUTPUT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OUTPUT)

Shortcut macro to set for input and output capability flags

◆ GF_CAPS_INPUT_OUTPUT_OPT

#define GF_CAPS_INPUT_OUTPUT_OPT (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_OPTIONAL)

Shortcut macro to set for optional input and output capability flags

◆ GF_CAPS_IN_OUT_EXCLUDED

#define GF_CAPS_IN_OUT_EXCLUDED (GF_CAPFLAG_IN_BUNDLE|GF_CAPFLAG_INPUT|GF_CAPFLAG_OUTPUT|GF_CAPFLAG_EXCLUDED)

Shortcut macro to set for excluded input capability flags

◆ SETCAPS

#define SETCAPS ( __struct ) .caps = __struct, .nb_caps=sizeof(__struct)/sizeof(GF_FilterCapability)

Quick macro for assigning the capability arrays to the register structure

◆ GF_FS_SET_DESCRIPTION

#define GF_FS_SET_DESCRIPTION ( _desc ) .description = _desc,

Macro for assigning filter register description

◆ GF_FS_SET_AUTHOR

#define GF_FS_SET_AUTHOR ( _author ) .author = _author,

Macro for assigning filter register author

◆ GF_FS_SET_HELP

#define GF_FS_SET_HELP ( _help ) .help = _help,

Macro for assigning filter register help

◆ GF_FS_DEF_ARG

#define GF_FS_DEF_ARG	(	_name,
		_offset,
		_desc,
		_type,
		_default,
		_enum,
		_flags
	)	{ _name, _offset, _desc, _type, _default, _enum, _flags }

Macro for assigning filter register argument types and description

Enumeration Type Documentation

◆ GF_FSArgumentFlags

enum GF_FSArgumentFlags

Structure holding arguments for a filter

Enumerator
GF_FS_ARG_HINT_NORMAL	used for GUI config: regular argument type
GF_FS_ARG_HINT_ADVANCED	used for GUI config: advanced argument type
GF_FS_ARG_HINT_EXPERT	used for GUI config: expert argument type
GF_FS_ARG_HINT_HIDE	used for GUI config: hidden argument type
GF_FS_ARG_UPDATE	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
GF_FS_ARG_META	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
GF_FS_ARG_META_ALLOC	internal flag used by meta filters (ffmpeg & co) to indicate the description of the argument is a dynamic allocated memory
GF_FS_ARG_SINK_ALIAS	internal flag used by filters acting as sinks (gsfmx in file mode) to allow retrieving dst url but avoid being used as direct sinks
GF_FS_ARG_UPDATE_SYNC	if set indicates that the argument is updatable only as a direct synchronous call (typically used for shared data). If so, the value will only be updated if the update directly targets the filter, and the global filter mutex will be locked before calling update_arg. It is however recommended for the calling app to lock the target filter whenever shared data is modified (see vout filter overlay argument for example) The filter should lock itself whenever appropriate using gf_filter_lock

◆ anonymous enum

anonymous enum

Flags for filter capabilities

Enumerator
GF_CAPFLAG_IN_BUNDLE	when not set, indicates the start of a new set of capabilities. Set by default by the generic GF_CAPS_*
GF_CAPFLAG_INPUT	if set this is an input capability of the bundle
GF_CAPFLAG_OUTPUT	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
GF_CAPFLAG_EXCLUDED	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
GF_CAPFLAG_LOADED_FILTER	when set, the capability is validated only for filter loaded for this destination filter
GF_CAPFLAG_STATIC	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
GF_CAPFLAG_OPTIONAL	Only used for input capabilities, indicates that this capability is optional in the input PID

◆ GF_FilterProbeScore

enum GF_FilterProbeScore

Filter probe score, used when probing a URL/MIME or when probing formats from data

Enumerator
GF_FPROBE_NOT_SUPPORTED	(de)mux format is not supported
GF_FPROBE_MAYBE_NOT_SUPPORTED	For demux only: format is maybe a match but garbage data was found at the start
GF_FPROBE_MAYBE_SUPPORTED	for demux: format is maybe a match and can maybe be demuxed for mux: format is supported with potentially missing features
GF_FPROBE_SUPPORTED	(de)mux format is supported
GF_FPROBE_FORCE	demux format should be handled by this filter
GF_FPROBE_EXT_MATCH	used by demux formats not supporting data prober

◆ GF_FSRegisterFlags

enum GF_FSRegisterFlags

Filter register flags

Enumerator
GF_FS_REG_MAIN_THREAD	when set indicates all calls shall take place in the main thread (running GL output) - to be refined
GF_FS_REG_CONFIGURE_MAIN_THREAD	when set indicates the initial call to configure_pid will happen in the main thread. This is typically called by decoders requiring a GL context (currently only in main thread) upon init, but not requiring it for the decode. Such decoders get their GL frames mapped (through get_gl_texture callback) in the main GL thread
GF_FS_REG_EXPLICIT_ONLY	when set indicates the filter does not take part of dynamic filter chain resolution and can only be used by explicitly loading the filter
GF_FS_REG_HIDE_WEIGHT	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
GF_FS_REG_ACT_AS_SOURCE	Usually set for filters acting as sources but without exposing an src argument. This prevents throwing warnings on arguments not handled by the filter
GF_FS_REG_ALLOW_CYCLIC	Indicates the filter can connect to another instance of the same class (avoids cyclic detection in linker graph) Filters of the same class can only connect directly to each other if the destination filter is explictly loaded
GF_FS_REG_DYNAMIC_PIDS	Indicates the filter PIDs may be dynamically added during process (e.g.M2TS, GSF, etc). This will prevent deactivating a filter when none of its output PIDs are connected
GF_FS_REG_SCRIPT	Indicates the filter is a script-based filter. The registry is not valid until the script is loaded
GF_FS_REG_META	Indicates the filter is a meta filter, wrapping various underlying filters (e.g., FFmpeg)
GF_FS_REG_DYNAMIC_REDIRECT	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. This is typically used by mux filters
GF_FS_REG_REQUIRES_RESOLVER	Indicates the filter requires graph resolver (typically because it creates new destinations/sinks at run time)
GF_FS_REG_CUSTOM	flag dynamically set at runtime for custom filters

◆ GF_FilterSessionSepType

enum GF_FilterSessionSepType

Filter session separator set query

Enumerator
GF_FS_SEP_ARGS	queries the character code used to separate between filter arguments
GF_FS_SEP_NAME	queries the character code used to separate between argument name and value
GF_FS_SEP_FRAG	queries the character code used to indicate fragment identifiers (source PIDs, PID properties)
GF_FS_SEP_LIST	queries the character code used to separate items in a list
GF_FS_SEP_NEG	queries the character code used to negate values

Function Documentation

◆ gf_filter_get_session_caps()

void gf_filter_get_session_caps	(	GF_Filter *	filter,
		GF_FilterSessionCaps *	caps
	)

Gets filter session capability

Parameters

filter	source of the query - avoids fetching the filter session object
caps	pointer filled with caps

◆ gf_filter_set_session_caps()

void gf_filter_set_session_caps	(	GF_Filter *	filter,
		GF_FilterSessionCaps *	caps
	)

Sets filter session capability

Parameters

filter	source of the query - avoids fetching the filter session object
caps	session capability new values - completely replace the old ones

◆ gf_filter_is_instance_of()

Bool gf_filter_is_instance_of	(	GF_Filter *	filter,
		const GF_FilterRegister *	freg
	)

Check if the filter is an instance of a filter register

Parameters

filter	filter to test
freg	filter register to test

Returns: GF_TRUE if filter is an instance of this register, GF_FALSE otehrwise

◆ gf_filter_abort()

void gf_filter_abort ( GF_Filter * filter )

Aborts a filter, discarding and stopping all input PIDs and sending EOS on all output PIDs

Parameters

filter filter to abort

◆ gf_filter_lock()

void gf_filter_lock	(	GF_Filter *	filter,
		Bool	do_lock
	)

Locks a filter. A filter should only lock itself when using updatable arguments of type GF_FS_ARG_UPDATE_SYNC

Parameters

filter	filter to lock
do_lock	if GF_TRUE, locks the filter global mutex, otherwise unlocks it

◆ gf_filter_lock_all()

void gf_filter_lock_all	(	GF_Filter *	filter,
		Bool	do_lock
	)

Lock global filter session. This is needed when assigning source IDs after a connect source or destination to the loaded source to connect in an async way

Parameters

filter	target filter
do_lock	if GF_TRUE, locks the filter session global mutex, otherwise unlocks it

◆ gf_filter_require_source_id()

void gf_filter_require_source_id ( GF_Filter * filter )

Force all output pids created for this filter to require a source ID for linking.

This is used by filters loading subchains to enforce that filters from these subchain only connect to each other or the target filter but not other filters outside this chain. Filters using this function must setup source IDs on filters of the sunchain(s) they load.

Parameters

filter target filter

◆ gf_filter_get_udta()

void* gf_filter_get_udta ( GF_Filter * filter )

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

Parameters

filter target filter

Returns: filter private stack if any, NULL otherwise

◆ gf_filter_set_name()

void gf_filter_set_name	(	GF_Filter *	filter,
		const char *	name
	)

Sets filter name - mostly used for logging purposes

Parameters

filter	target filter
name	new name to assign. If NULL, name is reset to register name

◆ gf_filter_get_name()

const char* gf_filter_get_name ( GF_Filter * filter )

Gets filter name

Parameters

filter target filter

Returns: name of the filter

◆ gf_filter_make_sticky()

void gf_filter_make_sticky ( GF_Filter * filter )

Makes the filter sticky. A sticky filter is not removed when all its input PIDs are disconnected. Typically used by the player

Parameters

filter target filter

◆ gf_filter_get_num_events_queued()

u32 gf_filter_get_num_events_queued ( GF_Filter * filter )

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.

Parameters

filter target filter

Returns: number of queued events

◆ gf_filter_get_download_manager()

GF_DownloadManager* gf_filter_get_download_manager ( GF_Filter * filter )

Returns the single instance of GPAC download manager. DO NOT DESTROY IT!!

Parameters

filter target filter

Returns: the GPAC download manager

◆ gf_filter_get_font_manager()

struct _gf_ft_mgr* gf_filter_get_font_manager ( GF_Filter * filter )

Returns the single instance of GPAC font manager. DO NOT DESTROY IT!!

Parameters

filter target filter

Returns: the GPAC font manager

◆ gf_filter_ask_rt_reschedule()

void gf_filter_ask_rt_reschedule	(	GF_Filter *	filter,
		u32	us_until_next
	)

Asks task reschedule for a given delay. There is no guarantee that the task will be recalled at exactly the desired delay

The function can be called several times while in process, the smallest reschedule time will be kept.

Parameters

filter	target filter
us_until_next	number of microseconds to wait before recalling this task

◆ gf_filter_post_process_task()

void gf_filter_post_process_task ( GF_Filter * filter )

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 such as decoder flushes, servers, etc... The filter session will ignore this call if the filter is already scheduled for processing

Parameters

filter target filter

◆ gf_filter_post_task()

GF_Err gf_filter_post_task	(	GF_Filter *	filter,
		Bool()(GF_Filter filter, void callback, u32 reschedule_ms)	task_execute,
		void *	udta,
		const char *	task_name
	)

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)

Parameters

filter	target filter
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 immediately or after reschedule_ms.
udta	user data passed back to the task function
task_name	name of the task for logging purposes

Returns: error code if failure

◆ gf_filter_set_setup_failure_callback()

void gf_filter_set_setup_failure_callback	(	GF_Filter *	filter,
		GF_Filter *	source_filter,
		void()(GF_Filter f, void *on_setup_error_udta, GF_Err e)	on_setup_error,
		void *	udta
	)

Sets callback function on source filter setup failure

Parameters

filter	target filter
source_filter	the source filter to monitor
on_setup_error	callback function to call upon source setup error
udta	user data passed back to the task function

◆ gf_filter_setup_failure()

void gf_filter_setup_failure	(	GF_Filter *	filter,
		GF_Err	reason
	)

Notify a filter setup error. This is typically called when a source filter or a filter having accepted input PIDs detects an issue. For a source filter (no input PID), the failure callback will be called if any, and the filter will be removed. For a connected filter, all input PIDs od the filter will be disconnected and the filter removed.

Parameters

filter	target filter
reason	the failure reason code

◆ gf_filter_notification_failure()

void gf_filter_notification_failure	(	GF_Filter *	filter,
		GF_Err	reason,
		Bool	force_disconnect
	)

Notify a filter fatal error but not a connection error. Typically, a 404 in HTTP.

Parameters

filter	target filter
reason	the failure reason code
force_disconnect	indicates if the filter chain should be disconnected or not

◆ gf_filter_remove_src()

void gf_filter_remove_src	(	GF_Filter *	filter,
		GF_Filter *	src_filter
	)

Disconnects a source filter chain between two filters

Parameters

filter	the calling filter. This filter is NOT disconnected
src_filter	the source filter point of the chain to disconnect.

◆ gf_filter_remove()

void gf_filter_remove ( GF_Filter * filter )

Disconnects a filter from fthe chain

Parameters

filter the filter to remove

◆ gf_filter_set_max_extra_input_pids()

void gf_filter_set_max_extra_input_pids	(	GF_Filter *	filter,
		u32	max_extra_pids
	)

Sets the number of additional input PID a filter can accept. This overrides the default value of the filter register

Parameters

filter	the target filter
max_extra_pids	the number of additional PIDs this filter can accept

◆ gf_filter_get_max_extra_input_pids()

u32 gf_filter_get_max_extra_input_pids ( GF_Filter * filter )

Gets the number of additional input PID a filter can accept. This overrides the default value of the filter register

Parameters

filter the target filter

Returns: max_extra_pids the number of additional PIDs this filter can accept

◆ gf_filter_block_enabled()

Bool gf_filter_block_enabled ( GF_Filter * filter )

Queries if blocking mode is enabled for the filter

Parameters

filter the target filter

Returns: GF_TRUE if blocking mode is enabled, GF_FALSE otherwise

◆ gf_filter_block_eos()

void gf_filter_block_eos	(	GF_Filter *	filter,
		Bool	do_block
	)

Indicates the EOS status on input PIDs of this filter shall not be checked when probing for end of stream in the chain

Parameters

filter	the target filter
do_block	if GF_TRUE, prevents EOS checking on input stream, otherwise enables it (default is FALSE upon creation)

◆ gf_filter_connect_source()

GF_Filter* gf_filter_connect_source	(	GF_Filter *	filter,
		const char *	url,
		const char *	parent_url,
		Bool	inherit_args,
		GF_Err *	err
	)

Connects a source to this filter.

Note: Any filter loaded between the source and the calling filter will not use argument inheritance from the caller.

Parameters

filter	the target filter
url	url of source to connect to, with optional arguments.
parent_url	url of parent if any
inherit_args	if GF_TRUE, the source to connect will inherit arguments of the target filter's destination
err	return code - can be NULL

Returns: the new source filter instance or NULL if error

◆ gf_filter_connect_destination()

GF_Filter* gf_filter_connect_destination	(	GF_Filter *	filter,
		const char *	url,
		GF_Err *	err
	)

Connects a destination to this filter

Parameters

filter	the target filter
url	url of destination to connect to, with optional arguments.
err	return code - can be NULL

Returns: the new destination filter instance or NULL if error

◆ gf_filter_load_filter()

GF_Filter* gf_filter_load_filter	(	GF_Filter *	filter,
		const char *	name,
		GF_Err *	err_code
	)

Loads a new filter in the session - see gf_fs_load_filter

Parameters

filter	the target filter
name	name and arguments of the filter register to instantiate.
err_code	error code if any

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

◆ gf_filter_is_supported_source()

Bool gf_filter_is_supported_source	(	GF_Filter *	filter,
		const char *	url,
		const char *	parent_url
	)

Checks if a source filter can handle the given URL. The source filter is not loaded.

Parameters

filter	the target filter
url	url of source to connect to, with optional arguments.
parent_url	url of parent if any

Returns: GF_TRUE if a source filter can be found for this URL, GF_FALSE otherwise

◆ gf_filter_get_ipid_count()

u32 gf_filter_get_ipid_count ( GF_Filter * filter )

Gets the number of input PIDs connected to a filter

Parameters

filter the target filter

Returns: number of input PIDs

◆ gf_filter_get_ipid()

GF_FilterPid* gf_filter_get_ipid	(	GF_Filter *	filter,
		u32	idx
	)

Gets an input PIDs connected to a filter

Parameters

filter	the target filter
idx	index of the input PID to retrieve, between 0 and gf_filter_get_ipid_count

Returns: the input PID, or NULL if not found

◆ gf_filter_get_opid_count()

u32 gf_filter_get_opid_count ( GF_Filter * filter )

Gets the number of output PIDs connected to a filter

Parameters

filter the target filter

Returns: number of output PIDs

◆ gf_filter_get_opid()

GF_FilterPid* gf_filter_get_opid	(	GF_Filter *	filter,
		u32	idx
	)

Gets an output PIDs connected to a filter

Parameters

filter	the target filter
idx	index of the output PID to retrieve, between 0 and gf_filter_get_opid_count

Returns: the output PID, or NULL if not found

◆ gf_filter_get_output_buffer_max()

void gf_filter_get_output_buffer_max	(	GF_Filter *	filter,
		u32 *	max_buf,
		u32 *	max_playout_buf
	)

Queries buffer max limits on a filter. This is the max of buffer limits on all its connected outputs

Parameters

filter	the target filter
max_buf	will be set to the maximum buffer duration in microseconds - may be NULL
max_playout_buf	will be set to the maximum playout buffer (the one triggering play) duration in microseconds - may be NULL

◆ gf_filter_hint_single_clock()

void gf_filter_hint_single_clock	(	GF_Filter *	filter,
		u64	time_in_us,
		GF_Fraction64	media_timestamp
	)

Sets a clock state at session level indicating the time / timestamp of the last rendered frame. This is used by basic audio output

Parameters

filter	the target filter
time_in_us	the system time in us, see gf_sys_clock_high_res
media_timestamp	the media timestamp associated with this time.

◆ gf_filter_get_clock_hint()

void gf_filter_get_clock_hint	(	GF_Filter *	filter,
		u64 *	time_in_us,
		GF_Fraction64 *	media_timestamp
	)

Retrieves the clock state at session level, as set by gf_filter_hint_single_clock

Parameters

filter	the target filter
time_in_us	will be set to the system time in us, see gf_sys_clock_high_res - may be NULL
media_timestamp	will be set to the media timestamp associated with this time - may be NULL.

◆ gf_filter_set_source()

GF_Err gf_filter_set_source	(	GF_Filter *	filter,
		GF_Filter *	link_from,
		const char *	link_ext
	)

Explicitly assigns a source ID to a filter. This shall be called before connecting the link_from filter 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

Warning: In multithreaded sessions, the session must be locked before the filter creation step and unlocked after calling this function, otherwise graph resolution might happen before gf_filter_set_source is called

Parameters

filter	the target filter
link_from	the filter to link from
link_ext	any link extensions allowed in link syntax: `#PIDNAME:` accepts only PID(s) with name PIDNAME `#TYPE:` accepts only PIDs of matching media type. TYPE can be 'audio' 'video' 'scene' 'text' 'font' `#TYPEN:` accepts only Nth PID of matching type from source `#P4CC=VAL:` accepts only PIDs with property matching VAL. `#PName=VAL:` same as above, using the built-in name corresponding to the property. `#P4CC-VAL`: accepts only PIDs with property strictly less than VAL (only for 1-dimension number properties). `#P4CC+VAL`: accepts only PIDs with property strictly greater than VAL (only for 1-dimension number properties).

Returns: error code if any

◆ gf_filter_set_source_restricted()

GF_Err gf_filter_set_source_restricted	(	GF_Filter *	filter,
		GF_Filter *	link_from,
		const char *	link_ext
	)

Similar to gf_filter_set_source This should be used on source filters when the calling filter is expected to have more possible sources added in the future, thereby dynamically changing its source IDs. Typically the compositor running the GUI is one such filter. This variant will make sure the sourceID used in the adaptation chain is always the ID of the source and not the source ID of the calling filter

Parameters

filter	the target filter
link_from	the filter to link from
link_ext	any link extensions allowed in link syntax:

Returns: error code if any

◆ gf_filter_reset_source()

void gf_filter_reset_source ( GF_Filter * filter )

Explicitly reset sourceID of a filter. This shall be called before connecting the filter (eg creating PIDs).

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/

Parameters

filter the target filter

◆ gf_filter_assign_id()

GF_Err gf_filter_assign_id	(	GF_Filter *	filter,
		const char *	filter_id
	)

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

Parameters

filter	the target filter
filter_id	the ID to assign. If NULL, a dynmic ID is generated

Returns: error code if any

◆ gf_filter_get_id()

const char* gf_filter_get_id ( GF_Filter * filter )

Gets the ID of a filter

Parameters

filter the target filter

Returns: ID of the filter, NULL if not defined

◆ gf_filter_set_blocking()

void gf_filter_set_blocking	(	GF_Filter *	filter,
		Bool	is_blocking
	)

Indicates the filter is a likely to block for a long time (typically, network IO). In multithread mode, this prevents the filter to be scheduled on the main thread, blocking video or audio output. By default, all filters are created as non-blocking.

Parameters

filter	the target filter
is_blocking	if GF_TRUE, indicates the filter is likely to block

◆ gf_filter_override_caps()

GF_Err gf_filter_override_caps	(	GF_Filter *	filter,
		const GF_FilterCapability *	caps,
		u32	nb_caps
	)

Overrides the filter caps with new caps for this instance. Typically used when an option of the filter changes the capabilities

The new caps are only taken into account for future graph resolutions, any current link from/to the target filter will not be re-solved when calling this function.

Parameters

filter	the target filter
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
nb_caps	number of capabilities set

Returns: error code if any

◆ gf_filter_act_as_sink()

GF_Err gf_filter_act_as_sink ( GF_Filter * filter )

Indicates this filter acts as a sink and will be used as such in graph resolution. Such filters must provide a use_alias function in their registry.

Parameters

filter the target filter

Returns: error code if any

◆ gf_filter_get_sep()

u8 gf_filter_get_sep	(	GF_Filter *	filter,
		GF_FilterSessionSepType	sep_type
	)

Queries the character code used as a given separator type in argument names. Used for formatting arguments when loading sources and destinations from inside a filter

Parameters

filter	the target filter
sep_type	the separator type to query

Returns: character code of the separator

◆ gf_filter_get_dst_args()

const char* gf_filter_get_dst_args ( GF_Filter * filter )

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)

Parameters

filter the target filter

Returns: the argument string of the destination args

◆ gf_filter_get_dst_name()

char* gf_filter_get_dst_name ( GF_Filter * filter )

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)

Parameters

filter the target filter

Returns: the argument string of the destination (SHALL be freed by caller), NULL if none found

◆ gf_filter_get_src_args()

const char* gf_filter_get_src_args ( GF_Filter * filter )

Get the filter arguments.

Parameters

filter the target filter

Returns: the argument string of the filter

◆ gf_filter_send_event()

void gf_filter_send_event	(	GF_Filter *	filter,
		GF_FilterEvent *	evt,
		Bool	upstream
	)

Sends an event on all input PIDs (downstream) or on all output PIDs (upstream)

Parameters

filter	the target filter
evt	the event to send
upstream	send the even upstream

◆ gf_filter_reconnect_output()

GF_Err gf_filter_reconnect_output ( GF_Filter * filter )

Trigger reconnection of output PIDs of a filter. This is needed when inserting a filter in the chain while the session is running

Parameters

filter the target filter

Returns: error if any

◆ gf_filter_set_event_target()

GF_Err gf_filter_set_event_target	(	GF_Filter *	filter,
		Bool	enable_events
	)

Indicates that the filter accept and can process events coming from outside the filter chain, typically used by application firing events. The event is sent on the process_event function with no associated PID.

Parameters

filter	the target filter
enable_events	if GF_TRUE, the filter is considered an event target

Returns: error if any

◆ gf_filter_get_info()

const GF_PropertyValue* gf_filter_get_info	(	GF_Filter *	filter,
		u32	prop_4cc,
		GF_PropertyEntry **	propentry
	)

Looks for a built-in property value marked as informative on a filter on all PIDs (inputs and output) This is a recursive call on both input and ouput chain. There is no guarantee that a queried property will still be valid at the setter side upon returning the call, the setter could have already reassigned it to NULL. To avoids random behavior, the property returned is reference counted so that it is not destroyed by the setter while the caller uses it.

Properties retrieved shall be released using gf_filter_release_property. Failure to do so will cause memory leaks in the program.

If the propentry pointer references a non-null value, this value will be released using gf_filter_release_property, so make sure to initialize the pointer to a NULL value on the first call. This avoid calling gf_filter_release_property after each get_info in the calling code:

GF_PropertyEntry *pe=NULL;
const GF_PropertyValue *p;
p = gf_filter_get_info(filter, FOO, &pe);
if (p) { }
p = gf_filter_get_info_str(filter, "BAR", &pe);
if (p) { }
p = gf_filter_pid_get_info(PID, ABCD, &pe);
if (p) { }
p = gf_filter_pid_get_info_str(PID, "MyProp", &pe);
if (p) { }
gf_filter_release_property(pe);

Parameters

filter	the target filter
prop_4cc	the code of the built-in property to fetch
propentry	the property reference object for later release. SHALL not be NULL

Returns: the property if found NULL otherwise.

◆ gf_filter_get_info_str()

const GF_PropertyValue* gf_filter_get_info_str	(	GF_Filter *	filter,
		const char *	prop_name,
		GF_PropertyEntry **	propentry
	)

Looks for a property value on a filter on all PIDs (inputs and output). This is a recursive call on both input and ouput chain Properties retrieved shall be released using gf_filter_release_property. See gf_filter_pid_get_info for more details.

Parameters

filter	the target filter
prop_name	the name of the property to fetch
propentry	the property reference object for later release. See gf_filter_pid_get_info for more details.

Returns: the property if found NULL otherwise

◆ gf_filter_release_property()

void gf_filter_release_property ( GF_PropertyEntry * propentry )

Release a property previously queried, only used for []_get_info_[] functions. This is a recursive call on both input and ouput chain

Parameters

propentry the property reference object to be released

◆ gf_filter_send_update()

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
	)

Sends a filter argument update

Parameters

filter	the target filter
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
arg_name	argument name
arg_val	argument value
propagate_mask	propagation flags - 0 means no propagation

◆ gf_filter_add_event_listener()

GF_Err gf_filter_add_event_listener	(	GF_Filter *	filter,
		GF_FSEventListener *	el
	)

Adds an event listener to the session

Parameters

filter	filter object
el	the event listener to add

Returns: the error code if any

◆ gf_filter_remove_event_listener()

GF_Err gf_filter_remove_event_listener	(	GF_Filter *	filter,
		GF_FSEventListener *	el
	)

Removes an event listener from the session

Parameters

filter	filter object
el	the event listener to add

Returns: the error code if any

◆ gf_filter_forward_gf_event()

Bool gf_filter_forward_gf_event	(	GF_Filter *	filter,
		GF_Event *	evt,
		Bool	consumed,
		Bool	skip_user
	)

Forwards an event to the filter session

Parameters

filter	filter object
evt	the event forwarded
consumed	if set, indicates the event was already consumed/processed before forwarding
skip_user	if set, indicates the event should only be dispatched to event listeners. Otherwise, if a user is assigned to the session, the event is forwarded to the user

Returns: the error code if any

◆ gf_filter_send_gf_event()

Bool gf_filter_send_gf_event	(	GF_Filter *	filter,
		GF_Event *	evt
	)

Forwards an event to the filter session. This is a shortcut for gf_filter_forward_gf_event(session, evt, GF_FALSE, GF_FALSE);

Parameters

filter	filter object
evt	the event forwarded

Returns: the error code if any

◆ gf_filter_all_sinks_done()

Bool gf_filter_all_sinks_done ( GF_Filter * filter )

Checks if all sink filters in the session have seen end of stream.

Parameters

filter filter object

Returns: GF_TRUE if all sinks are in end of stream, GF_FALSE otherwise

◆ gf_filter_get_arg_str()

const char* gf_filter_get_arg_str	(	GF_Filter *	filter,
		const char *	arg_name,
		char	dump[GF_PROP_DUMP_ARG_SIZE]
	)

Gets a filter argument value as string for a given argument name..

Parameters

filter	filter object
arg_name	name of the filter argument
dump	buffer in which any formatting of argument value will take place

Returns: the string value of the argument, or NULL if argument is not found or is invalid

◆ gf_filter_get_arg()

Bool gf_filter_get_arg	(	GF_Filter *	filter,
		const char *	arg_name,
		GF_PropertyValue *	prop
	)

Gets a filter argument value for a given argument name..

Parameters

filter	filter object
arg_name	name of the filter argument
prop	filled with the arguments value, do NOT modify

Returns: GF_TURE if success, GF_FALSE otherwise (argument is not found or is invalid)

◆ gf_filter_is_supported_mime()

Bool gf_filter_is_supported_mime	(	GF_Filter *	filter,
		const char *	mime
	)

Checks if a given mime type is supported as input in the parent session

Parameters

filter	querying filter
mime	mime type to query

Returns: GF_TRUE if mime is supported

◆ gf_filter_ui_event()

Bool gf_filter_ui_event	(	GF_Filter *	filter,
		GF_Event *	uievt
	)

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

Parameters

filter	triggering filter
uievt	event to send

Returns: GF_TRUE if event has been cancelled, FALSE otherwise

◆ gf_filter_register_opengl_provider()

void gf_filter_register_opengl_provider	(	GF_Filter *	filter,
		Bool	do_register
	)

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.

Parameters

filter	filter providing OpenGL context
do_register	if TRUE the filter carries a valid gl context, if FALSE the filter no longer carries a valid GL context

◆ gf_filter_request_opengl()

GF_Err gf_filter_request_opengl ( GF_Filter * filter )

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.

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

Parameters

filter filter providing OpenGL context

Returns: error code if any

◆ gf_filter_set_active_opengl_context()

GF_Err gf_filter_set_active_opengl_context ( GF_Filter * filter )

Sets openGL context active for this filter.

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

Parameters

filter filter asking for OpenGL context activation

Returns: error code if any

◆ gf_filter_count_source_by_protocol()

u32 gf_filter_count_source_by_protocol	(	GF_Filter *	filter,
		const char *	protocol_scheme,
		Bool	expand_proto,
		GF_FilterPid ()(void udta, u32 idx)	enum_pids,
		void *	udta
	)

Count the number of source filters for the given filter matching the given protocol type.

Parameters

filter	filter to inspect
protocol_scheme	scheme of the protocol to test, without ://, eg "http", "rtp", "https"
expand_proto	if set to GF_TRUE, any source protocol with a name beginning like protocol_scheme will be matched. For example, use this with "http" to match all http and https schemes.
enum_pids	user function to enumerate PIDs against which the source should be checked . If not set, all source filters will be checked.
udta	user data for the callback function

Returns: the number of source filters matched by protocols

◆ gf_filter_disable_probe()

void gf_filter_disable_probe ( GF_Filter * filter )

Disables data probing on the given filter. Typically used by filters loading source filters.

Parameters

filter target filter

◆ gf_filter_disable_inputs()

void gf_filter_disable_inputs ( GF_Filter * filter )

Disables input connection on the filter. This is used by filters acting both as true sources or demux/processing filters depending on their options.

Parameters

filter target filter

◆ gf_filter_has_pid_connection_pending()

Bool gf_filter_has_pid_connection_pending	(	GF_Filter *	filter,
		GF_Filter *	stop_at_filter
	)

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.

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.

Parameters

filter	target filter
stop_at_filter	check connections until this filter. If NULL, connections are checked until upper (sink) end of graph

Returns: GF_TRUE if any filter in the path has pending PID connections

◆ gf_filter_connections_pending()

Bool gf_filter_connections_pending ( GF_Filter * filter )

checks if the some PID connection tasks are still pending at the session level

This can be needed by some filters needing to make sure all their inputs are known before starting producing packets.

Parameters

filter target filter

Returns: GF_TRUE if some connection tasks are pending, GF_FALSE otherwise

◆ gf_filter_prevent_blocking()

GF_Err gf_filter_prevent_blocking	(	GF_Filter *	filter,
		Bool	prevent_blocking_enabled
	)

Disables blocking check for a given filter

This can be needed by some filters internally managing their blocking state because one of their output is not managed by the filter session.

Parameters

filter	target filter
prevent_blocking_enabled	if GF_TRUE, filter will still be called even if one of its output is in blocking mode

Returns: error if any

◆ gf_filter_is_dynamic()

Bool gf_filter_is_dynamic ( GF_Filter * filter )

Checks if filter was loaded as part of a link resolution or explicitly loaded by application

Parameters

filter target filter

Returns: GF_TRUE if filter was loaded for link resolution, GF_FALSE if filter was explicitly loaded by the application

◆ gf_filter_reporting_enabled()

Bool gf_filter_reporting_enabled ( GF_Filter * filter )

Checks if reporting is turned on at session level.

Parameters

filter target filter

Returns: GF_TRUE if reporting is enabled, GF_FALSE otherwise

◆ gf_filter_update_status()

GF_Err gf_filter_update_status	(	GF_Filter *	filter,
		u32	percent,
		char *	szStatus
	)

Updates filter status string and progress. Should not be called if reporting is turned off at session level. This allows gathering stats from filter in realtime. The status string can be anything but shall not contain '
' and should not contain any source or destination URL except for sources and sinks.

Parameters

filter	target filter
percent	percentage (from 0 to 10000) of operation status. If more than 10000 ignored
szStatus	string giving a status of the filter

Returns: error code if any

◆ gf_filter_end_of_session()

Bool gf_filter_end_of_session ( GF_Filter * filter )

check if session has been scheduled for destruction

Parameters

filter target filter

Returns: GF_TRUE if session is about to be destroyed

◆ gf_filter_report_meta_option()

void gf_filter_report_meta_option	(	GF_Filter *	filter,
		const char *	arg,
		Bool	was_found
	)

used by meta-filters (ffmpeg and co) to report used/unused options. This is needed since these filters might not know the set of available options at initialize() time.

Parameters

filter	target filter
arg	name of the argument not used/found
was_found	indicate that this option was found

◆ gf_filter_set_description()

GF_Err gf_filter_set_description	(	GF_Filter *	filter,
		const char *	new_desc
	)

used by script to set a per-instance description

Parameters

filter	target filter
new_desc	the new description to set

Returns: error if any

◆ gf_filter_get_description()

const char* gf_filter_get_description ( GF_Filter * filter )

get a per-instance description

Parameters

filter target filter

Returns: the filter instance description, NULL otherwise

◆ gf_filter_set_version()

GF_Err gf_filter_set_version	(	GF_Filter *	filter,
		const char *	new_version
	)

used by script to set a per-instance version

Parameters

filter	target filter
new_version	the new version to set

Returns: error if any

◆ gf_filter_get_version()

const char* gf_filter_get_version ( GF_Filter * filter )

get a per-instance version

Parameters

filter target filter

Returns: the filter instance version, NULL otherwise

◆ gf_filter_set_author()

GF_Err gf_filter_set_author	(	GF_Filter *	filter,
		const char *	new_author
	)

used by script to set a per-instance author

Parameters

filter	target filter
new_author	the new author to set

Returns: error if any

◆ gf_filter_get_author()

const char* gf_filter_get_author ( GF_Filter * filter )

get a per-instance author

Parameters

filter target filter

Returns: the filter instance author, NULL otherwise

◆ gf_filter_set_help()

GF_Err gf_filter_set_help	(	GF_Filter *	filter,
		const char *	new_help
	)

used by script to set a per-instance help

Parameters

filter	target filter
new_help	the new help to set

Returns: error if any

◆ gf_filter_get_help()

const char* gf_filter_get_help ( GF_Filter * filter )

get a per-instance help

Parameters

filter target filter

Returns: the filter instance help, NULL otherwise

◆ gf_filter_define_args()

GF_Err gf_filter_define_args	(	GF_Filter *	filter,
		GF_FilterArgs *	new_args
	)

used by script to set a per-instance arguments. The passed array shall have a 0 argument at the end and shall be valid for the lifetime of the filter (not locally copied)

Parameters

filter	target filter
new_args	the new args to set

Returns: error if any

◆ gf_filter_get_args()

GF_FilterArgs* gf_filter_get_args ( GF_Filter * filter )

get per-instance args

Parameters

filter target filter

Returns: the filter instance args if any, NULL otherwise

◆ gf_filter_get_caps()

const GF_FilterCapability* gf_filter_get_caps	(	GF_Filter *	filter,
		u32 *	nb_caps
	)

get per-instance caps

Parameters

filter	target filter
nb_caps	set to the number of caps

Returns: the filter instance caps if any, NULL otherwise

◆ gf_filter_probe_data()

const char* gf_filter_probe_data	(	GF_Filter *	filter,
		u8 *	data,
		u32	size
	)

probes mime type of a given block of data (should be beginning of file )

Parameters

filter	target filter
data	buffer to probe
size	size of buffer

Returns: the mime type probed, or NULL if not recognized

◆ gf_filter_is_alias()

Bool gf_filter_is_alias ( GF_Filter * filter )

checks if the given filter is an alias filter created by a multiple sink filter

Parameters

filter target filter

Returns: GF_TRUE if this is an alias filter created by a multiple sink filter, GF_FALSE otherwise

◆ gf_filter_in_parent_chain()

Bool gf_filter_in_parent_chain	(	GF_Filter *	parent,
		GF_Filter *	filter
	)

checks if the given filter is in the chain ending up at parent

Parameters

parent	end of filter chain to check
filter	target filter to check

Returns: GF_TRUE if filter is present in the parent chain, GF_FALSE otherwise

◆ gf_filter_get_stats()

GF_Err gf_filter_get_stats	(	GF_Filter *	filter,
		GF_FilterStats *	stats
	)

Gets statistics for filter

Parameters

filter	filter session
stats	statistics for filter

Returns: error code if any

◆ gf_filter_enumerate_args()

const GF_FilterArgs* gf_filter_enumerate_args	(	GF_Filter *	filter,
		u32	idx
	)

Enumerates default arguments of a filter

Parameters

filter	filter session
idx	the 0-based index of the argument to query

Returns: the argument definition, or NULL if error

◆ gf_filter_relocate_url()

Bool gf_filter_relocate_url	(	GF_Filter *	filter,
		const char *	service_url,
		const char *	parent_url,
		char *	out_relocated_url,
		char *	out_localized_url
	)

Reslves URL against locales settings

Parameters

filter	filter
service_url	URL of service to relocate
parent_url	parent URL of service
out_relocated_url	- must be GF_MAX_PATH size
out_localized_url	- must be GF_MAX_PATH size

Returns: GF_TRUE if success

Data Structures

Macros

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ GF_FilterArgs

◆ GF_FilterCapability

◆ GF_FilterSessionCaps

Macro Definition Documentation

◆ CAP_SINT

◆ CAP_UINT

◆ CAP_4CC

◆ CAP_LSINT

◆ CAP_LUINT

◆ CAP_BOOL

◆ CAP_FIXED

◆ CAP_FLOAT

◆ CAP_FRAC_INT

◆ CAP_FRAC

◆ CAP_DOUBLE

◆ CAP_NAME

◆ CAP_STRING

◆ CAP_UINT_PRIORITY

◆ GF_CAPS_INPUT

◆ GF_CAPS_INPUT_OPT

◆ GF_CAPS_INPUT_STATIC

◆ GF_CAPS_INPUT_STATIC_OPT

◆ GF_CAPS_INPUT_EXCLUDED

◆ GF_CAPS_INPUT_LOADED_FILTER

◆ GF_CAPS_OUTPUT

◆ GF_CAPS_OUTPUT_LOADED_FILTER

◆ GF_CAPS_OUTPUT_EXCLUDED

◆ GF_CAPS_OUTPUT_STATIC

◆ GF_CAPS_OUTPUT_STATIC_EXCLUDED

◆ GF_CAPS_INPUT_OUTPUT

◆ GF_CAPS_INPUT_OUTPUT_OPT

◆ GF_CAPS_IN_OUT_EXCLUDED

◆ SETCAPS

◆ GF_FS_SET_DESCRIPTION

◆ GF_FS_SET_AUTHOR

◆ GF_FS_SET_HELP

◆ GF_FS_DEF_ARG

Enumeration Type Documentation

◆ GF_FSArgumentFlags

◆ anonymous enum

◆ GF_FilterProbeScore

◆ GF_FSRegisterFlags

◆ GF_FilterSessionSepType

Function Documentation

◆ gf_filter_get_session_caps()

◆ gf_filter_set_session_caps()

◆ gf_filter_is_instance_of()

◆ gf_filter_abort()

◆ gf_filter_lock()

◆ gf_filter_lock_all()

◆ gf_filter_require_source_id()

◆ gf_filter_get_udta()

◆ gf_filter_set_name()

◆ gf_filter_get_name()

◆ gf_filter_make_sticky()

◆ gf_filter_get_num_events_queued()

◆ gf_filter_get_download_manager()

◆ gf_filter_get_font_manager()

◆ gf_filter_ask_rt_reschedule()

◆ gf_filter_post_process_task()

◆ gf_filter_post_task()

◆ gf_filter_set_setup_failure_callback()

◆ gf_filter_setup_failure()

◆ gf_filter_notification_failure()

◆ gf_filter_remove_src()

◆ gf_filter_remove()

◆ gf_filter_set_max_extra_input_pids()

◆ gf_filter_get_max_extra_input_pids()

◆ gf_filter_block_enabled()

◆ gf_filter_block_eos()

◆ gf_filter_connect_source()

◆ gf_filter_connect_destination()

◆ gf_filter_load_filter()

◆ gf_filter_is_supported_source()