libgpac
Documentation of the core library of GPAC

Filter. More...

+ 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 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_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_BLOCKING = 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,
  GF_FS_REG_DYNLIB = 0x80000000
}
 
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_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_DownloadManagergf_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_Filtergf_filter_connect_source (GF_Filter *filter, const char *url, const char *parent_url, Bool inherit_args, GF_Err *err)
 
GF_Filtergf_filter_connect_destination (GF_Filter *filter, const char *url, GF_Err *err)
 
GF_Filtergf_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_FilterPidgf_filter_get_ipid (GF_Filter *filter, u32 idx)
 
u32 gf_filter_get_opid_count (GF_Filter *filter)
 
GF_FilterPidgf_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)
 
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)
 
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_unused_meta_option (GF_Filter *filter, const char *arg)
 
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_FilterArgsgf_filter_get_args (GF_Filter *filter)
 
const GF_FilterCapabilitygf_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_FilterArgsgf_filter_enumerate_args (GF_Filter *filter, u32 idx)
 

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 behaviour, 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

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

Shortcut macro to set for optional input and output 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

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

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_SUPPORTED 

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

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_BLOCKING 

Indicates the filter is 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. Ignored in single thread mode.

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_FS_REG_DYNLIB 

flag dynamically set at runtime for registries loaded through shared libraries

◆ 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
filtersource of the query - avoids fetching the filter session object
capspointer 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
filtersource of the query - avoids fetching the filter session object
capssession 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
filterfilter to test
fregfilter 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 stoping all input PIDs and sending EOS on all output PIDs

Parameters
filterfilter 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
filterfilter to lock
do_lockif GF_TRUE, locks the filter global mutex, otherwise unlocks it

◆ 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
filtertarget 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
filtertarget filter
namenew 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
filtertarget 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
filtertarget 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
filtertarget 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
filtertarget 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
filtertarget 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

Parameters
filtertarget filter
us_until_nextnumber 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
filtertarget 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
filtertarget filter
task_executethe 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.
udtauser data passed back to the task function
task_namename 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
filtertarget filter
source_filterthe source filter to monitor
on_setup_errorcallback function to call upon source setup error
udtauser 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
filtertarget filter
reasonthe 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
filtertarget filter
reasonthe failure reason code
force_disconnectindicates 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
filterthe calling filter. This filter is NOT disconnected
src_filterthe 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
filterthe 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
filterthe target filter
max_extra_pidsthe 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
filterthe 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
filterthe 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
filterthe target filter
do_blockif 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
filterthe target filter
urlurl of source to connect to, with optional arguments.
parent_urlurl of parent if any
inherit_argsif GF_TRUE, the source to connect will inherit arguments of the target filter's destination
errreturn 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
filterthe target filter
urlurl of destination to connect to, with optional arguments.
errreturn 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
filterthe target filter
namename and arguments of the filter register to instantiate.
err_codeerror 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
filterthe target filter
urlurl of source to connect to, with optional arguments.
parent_urlurl 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
filterthe 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
filterthe target filter
idxindex 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
filterthe 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
filterthe target filter
idxindex 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
filterthe target filter
max_bufwill be set to the maximum buffer duration in microseconds - may be NULL
max_playout_bufwill 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
filterthe target filter
time_in_usthe system time in us, see gf_sys_clock_high_res
media_timestampthe 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
filterthe target filter
time_in_uswill be set to the system time in us, see gf_sys_clock_high_res - may be NULL
media_timestampwill 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

Parameters
filterthe target filter
link_fromthe filter to link from
link_extany 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
filterthe target filter
link_fromthe filter to link from
link_extany 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
filterthe 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
filterthe target filter
filter_idthe 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
filterthe target filter
Returns
ID of the filter, NULL if not defined

◆ gf_filter_override_caps()

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

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

Parameters
filterthe target filter
capsthe new set of capabilities to use for the filter. These are NOT copied and shall be valid for the lifetime of the filter
nb_capsnumber 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
filterthe 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
filterthe target filter
sep_typethe 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
filterthe 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
filterthe target filter
Returns
the argument string of the destination (SHALL be freed by caller), NULL if none found

◆ 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
filterthe target filter
evtthe event to send
upstreamsend 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
filterthe 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
filterthe target filter
enable_eventsif 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 behaviour, 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:

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) { }
Parameters
filterthe target filter
prop_4ccthe code of the built-in property to fetch
propentrythe 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
filterthe target filter
prop_namethe name of the property to fetch
propentrythe 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
propentrythe 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
filterthe target filter
target_filter_idif set, the target filter will be changed to the filter with this id if any. otherwise the target filter is the one specified
arg_nameargument name
arg_valargument value
propagate_maskpropagation 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
filterfilter object
elthe 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
filterfilter object
elthe 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
filterfilter object
evtthe event forwarded
consumedif set, indicates the event was already consummed/processed before forwarding
skip_userif 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
filterfilter object
evtthe 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
filterfilter 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
filterfilter object
arg_namename of the filter argument
dumpbuffer 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
filterfilter object
arg_namename of the filter argument
propfilled 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
filterquerying filter
mimemime 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
filtertriggering filter
uievtevent 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
filterfilter providing OpenGL context
do_registerif 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
filterfilter 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
filterfilter 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
filterfilter to inspect
protocol_schemescheme of the protocol to test, without ://, eg "http", "rtp", "https"
expand_protoif set to GF_TRUE, any source protocol with a name begining like protocol_scheme will be matched. For example, use this with "http" to match all http and https schemes.
enum_pidsuser function to enumerate PIDs against which the source should be checked . If not set, all source filters will be checked.
udtauser 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
filtertarget 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
filtertarget 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
filtertarget filter
stop_at_filtercheck 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
filtertarget 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
filtertarget filter
prevent_blocking_enabledif 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
filtertarget 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
filtertarget 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
filtertarget filter
percentpercentage (from 0 to 10000) of operation status. If more than 10000 ignored
szStatusstring 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
filtertarget filter
Returns
GF_TRUE if session is about to be destroyed

◆ gf_filter_report_unused_meta_option()

void gf_filter_report_unused_meta_option ( GF_Filter filter,
const char *  arg 
)

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

Parameters
filtertarget filter
argname of the argument not used/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
filtertarget filter
new_descthe 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
filtertarget 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
filtertarget filter
new_versionthe 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
filtertarget 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
filtertarget filter
new_authorthe 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
filtertarget 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
filtertarget filter
new_helpthe 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
filtertarget 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
filtertarget filter
new_argsthe 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
filtertarget 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
filtertarget filter
nb_capsset 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 begining of file )

Parameters
filtertarget filter
databuffer to probe
sizesize 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
filtertarget 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
parentend of filter chain to check
filtertarget 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
filterfilter session
statsstatistics 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
filterfilter session
idxthe 0-based index of the argument to query
Returns
the argument definition, or NULL if error
gf_filter_release_property
void gf_filter_release_property(GF_PropertyEntry *propentry)
filter
attribute JSFilter filter
Definition: jsf.idl:27
gf_filter_pid_get_info_str
const GF_PropertyValue * gf_filter_pid_get_info_str(GF_FilterPid *PID, const char *prop_name, GF_PropertyEntry **propentry)
gf_filter_pid_get_info
const GF_PropertyValue * gf_filter_pid_get_info(GF_FilterPid *PID, u32 prop_4cc, GF_PropertyEntry **propentry)
GF_PropertyEntry
struct __gf_prop_entry GF_PropertyEntry
Definition: filters.h:161
gf_filter_get_info
const GF_PropertyValue * gf_filter_get_info(GF_Filter *filter, u32 prop_4cc, GF_PropertyEntry **propentry)
gf_filter_get_info_str
const GF_PropertyValue * gf_filter_get_info_str(GF_Filter *filter, const char *prop_name, GF_PropertyEntry **propentry)