libgpac
Documentation of the core library of GPAC
Data Fields
GF_FilterRegister Struct Reference
Filter Management » Filter

#include <filters.h>

+ Collaboration diagram for GF_FilterRegister:

Data Fields

const char * name
 
u32 private_size
 
u32 max_extra_pids
 
GF_FSRegisterFlags flags
 
const GF_FilterCapability * caps
 
u32 nb_caps
 
const GF_FilterArgs * args
 
GF_Err(* process )(GF_Filter *filter)
 
GF_Err(* configure_pid )(GF_Filter *filter, GF_FilterPid *PID, Bool is_remove)
 
GF_Err(* initialize )(GF_Filter *filter)
 
void(* finalize )(GF_Filter *filter)
 
GF_Err(* update_arg )(GF_Filter *filter, const char *arg_name, const GF_PropertyValue *new_val)
 
Bool(* process_event )(GF_Filter *filter, const GF_FilterEvent *evt)
 
GF_Err(* reconfigure_output )(GF_Filter *filter, GF_FilterPid *PID)
 
GF_FilterProbeScore(* probe_url )(const char *url, const char *mime)
 
const char *(* probe_data )(const u8 *data, u32 size, GF_FilterProbeScore *score)
 
u8 priority
 
void(* register_free )(GF_FilterSession *session, struct __gf_filter_register *freg)
 
void * udta
 
Bool(* use_alias )(GF_Filter *filter, const char *url, const char *mime)
 
const char * version
 
const char * description
 
const char * author
 
const char * help
 

Detailed Description

The filter register. Registries are loaded once at the start of the session and shall never be modified after that. If capabilities need to be changed for a specific filter, use gf_filter_override_caps

Filter Register object

Field Documentation

◆ name

const char* GF_FilterRegister::name

mandatory - name of the filter as used when setting up filters. Naming conventions:

  • shall not contain any space (breaks filter lookup)
  • should use lowercase
  • should not use '_'

◆ private_size

u32 GF_FilterRegister::private_size

optional - size of private stack structure. The structure is allocated by the framework and arguments are setup before calling any of the filter functions

◆ max_extra_pids

u32 GF_FilterRegister::max_extra_pids

indicates the max number of additional input PIDs - muxers and scalable filters typically set this to (u32) -1. A value of 0 implies the filter can only handle one PID

◆ flags

GF_FSRegisterFlags GF_FilterRegister::flags

set of register flags

◆ caps

const GF_FilterCapability* GF_FilterRegister::caps

list of PID capabilities

◆ nb_caps

u32 GF_FilterRegister::nb_caps

number of PID capabilities

◆ args

const GF_FilterArgs* GF_FilterRegister::args

optional - filter arguments if any

◆ process

GF_Err(* GF_FilterRegister::process) (GF_Filter *filter)

mandatory - callback for filter processing

This function is called whenever packets are available on the input PID and buffer space is available on the output. The session will by default monitor a filter for errors, and throw en error if a filter is not consuming nor producing packets for a given amount of process calls. In some cases, it might be needed to not consume nor produce a packet for a given time (for example, waiting for a packet drop before reconfiguring a filter). A filter must signal this using gf_filter_ask_rt_reschedule, possibly with no timeout.

A filter may return GF_EOS to indicate no more data is expected to be produced by this filter

A filter may return GF_PROFILE_NOT_SUPPORTED to indicate that the filter is not supported (when unable to detect this at configure) and trigger a relink of the filter graph unless disabled at session level.

◆ configure_pid

GF_Err(* GF_FilterRegister::configure_pid) (GF_Filter *filter, GF_FilterPid *PID, Bool is_remove)

optional for sources, mandatory for filters and sinks (any filter with an input cap set) - callback for PID update may be called several times on the same PID if PID config is changed. Since discontinuities may happen at any time, and a filter may fetch packets in burst, this function may be called while the filter is calling gf_filter_pid_get_packet (this is the only reentrant call for filters). If an error is returned, the PID object shall no longer be used by the filter.

Parameters
filterthe target filter
PIDthe input PID to configure
is_removeindicates the input PID is removed
Returns
error if any.
  • a return error of GF_REQUIRES_NEW_INSTANCE indicates the PID cannot be processed in this instance but could be in a clone of the filter.
  • a return error of GF_FILTER_NOT_SUPPORTED indicates the PID cannot be processed and no alternate chain resolution would help
  • a return error of GF_EOS silently discard the input pid (same as GF_FILTER_NOT_SUPPORTED but does not throw error)
  • a return error of GF_BAD_PARAM, GF_SERVICE_ERROR or GF_REMOTE_SERVICE_ERROR indicates the PID cannot be processed and no alternate chain resolution would help, and throws a log error message
  • any other return error will trigger a reconfigure of the chain to find another filter unless disabled at session level.

If an error is returned when (re)configuring a pid, the function is called again with is_remove set to GF_TRUE

◆ initialize

GF_Err(* GF_FilterRegister::initialize) (GF_Filter *filter)

optional - callback for filter initialization - private stack of filter is allocated by framework)

Parameters
filterthe target filter
Returns
error if any. A filter may return GF_EOS to indicate the filter session shall not be run, but that no error should be thrown (used by dasher in realtime regulation mode)

◆ finalize

void(* GF_FilterRegister::finalize) (GF_Filter *filter)

optional - callback for filter destruction - private stack of filter is freed by framework

Parameters
filterthe target filter

◆ update_arg

GF_Err(* GF_FilterRegister::update_arg) (GF_Filter *filter, const char *arg_name, const GF_PropertyValue *new_val)

optional - callback for arguments update. If GF_OK is returned, the filter private stack is updated accordingly. If function is NULL, all updatable arguments will be changed in the filter private stack without the filter being notified. If argument is a meta argument, it is the filter responsibility to handle the update, as meta arguments do not live on the filter private stack. If the filter is a meta filter and argument is not declared in the argument list, the function is always called.

Parameters
filterthe target filter
arg_namethe name of the argument being set
new_valthe value of the argument being set
Returns
error if any, GF_NOT_FOUND to silently disable argument value change.

◆ process_event

Bool(* GF_FilterRegister::process_event) (GF_Filter *filter, const GF_FilterEvent *evt)

optional - process a given event. Returns TRUE if the event has to be canceled, FALSE otherwise

  • If a downstream (towards source) event is not canceled, it will be forwarded to each input PID of the filter.
  • If you need to forward the event only to one input pid, send a copy of the event to the desired input and cancel the event.
    Parameters
    filterthe target filter
    evtthe event to process
    Returns
    GF_TRUE if the event should be canceled, GF_FALSE otherwise

◆ reconfigure_output

GF_Err(* GF_FilterRegister::reconfigure_output) (GF_Filter *filter, GF_FilterPid *PID)

optional - Called whenever an output PID needs format renegotiation. If not set, a filter chain will be loaded to solve the negotiation

Parameters
filterthe target filter
PIDthe filter output PID being reconfigured
Returns
error code if any

◆ probe_url

GF_FilterProbeScore(* GF_FilterRegister::probe_url) (const char *url, const char *mime)

optional, mostly used for source filters and destination filters - probe the given URL, returning a score. This function is called before opening the source (no data received yet)

Parameters
urlthe url of the source to probe, never NULL.
mimethe MIME type of the source to probe. Can be NULL if mime not available at probe type
Returns
probe score

◆ probe_data

const char*(* GF_FilterRegister::probe_data) (const u8 *data, u32 size, GF_FilterProbeScore *score)

optional, usually set by demuxers. This function probes the mime type of a data chunk, usually located at the start of the file. This function is called once the source is open, but is never called on an instanciated filter. The returned mime type (if any) is then used instead of the file extension for solving filter graph.

Note
Demux filters should always exposed 2 input caps bundle, one for specifying input cap by file extension and one for specifying input cap by mime type.
Parameters
datadata to probe
sizesize of the data to probe
scoreset to the probe score. Initially set to GF_FPROBE_NOT_SUPPORTED before calling the function. If you are certain of the data type, use GF_FPROBE_SUPPORTED, if unsure use GF_FPROBE_MAYBE_SUPPORTED. If the format cannot be probed (bad design), set it to GF_FPROBE_EXT_MATCH
Returns
mime type of content, list of known extensions for the format if score is set to GF_FPROBE_EXT_MATCH, or NULL if not detected.

◆ priority

u8 GF_FilterRegister::priority

for filters having the same match of input capabilities for a PID, the filter with priority at the lowest value will be used

Note
Scalable decoders should use high values, so that they are only selected when enhancement layers are present

◆ register_free

void(* GF_FilterRegister::register_free) (GF_FilterSession *session, struct __gf_filter_register *freg)

optional for dynamic filter registries. Dynamic registries may declare any number of registries. The register_free function will be called to cleanup any allocated memory

Parameters
sessionthe filter session
fregthe filter register to destroy

◆ udta

void* GF_FilterRegister::udta

user data of register loader, not inspected/modified by filter session

◆ use_alias

Bool(* GF_FilterRegister::use_alias) (GF_Filter *filter, const char *url, const char *mime)

optional. Used by sink filters offering multiple sink support GPAC instantiates filter chains based on filter capabilities and arguments of source and destination. When a sink/destination filter can handle multiple file inputs of various formats/types, temporary filters called alias are needed to instantiate the proper chain. If the return value is true, an alias filter of the same type as this filter will be created with the proper arguments and initialized (in order to modify the alias filter capabilities if needed), and finalized when no longer needed. All other callbacks will however be made on the main filter, not the alias.

A good example is HTTP output of a DASH session:

  • the first PID will be a FILE stream for the manifest (MPD, M3U8), and the http output capabilities will be set to accept the manifest file extension.mime
  • the other PIDs will be media PIDs (mp4, ts, mkv ...) and won't match the filter instance, creating a new instance which we don't want

By creating filter alias, a temprary HTTP output (alias) will be created, holding the arguments for the chain (including destination type). Overloading the alias filter capabilities with the desired file extension or MIME will trigger the proper chain resolution. The alias will be switched to the final filter upon connecting the PIDs

To access original arguments of the chain, see gf_filter_pid_get_alias_udta To check if an initialize callback targets the main filter or the temporary one, see gf_filter_is_alias

Parameters
filterthe target filter
urlthe url of the target destination, never NULL.
mimethe MIME type of the target destination. Can be NULL if mime not available
Returns
GF_TRUE if this filter instance should be used to handle the given URL, in which case an alias filter will be created

◆ version

const char* GF_FilterRegister::version

version of the filter, usually only for external libs

Note
If this strings starts with "! " it indicates an error message at load time of the registry. This should only be set when
gf_opts_get_bool("temp", "gendoc");
gf_opts_get_bool
Bool gf_opts_get_bool(const char *secName, const char *keyName)
returns true, indicating the filter session is only loaded for documentation purposes (man/md generation and command line help).

◆ description

const char* GF_FilterRegister::description

short description of the filter. Conventions:

  • should be small (used to generate UI / documentation)
  • Should be Capitalized
  • shall not use markdown
  • shall be single line

◆ author

const char* GF_FilterRegister::author

author of the filter. Conventions:

  • shall not use markdown
  • first line if present is author name and should be normally capitalized
  • second line if present is comma-separated list of contact info (eg http://foo.bar,mailto:foo@bar.com)

If first character is a -, this field is interpreted as a configuration info (typically for meta filters such as ffmpeg).

◆ help

const char* GF_FilterRegister::help

help of the filter. Conventions:

  • describe any non-obvious behavior of the filter here
  • markdown is allowed. Use '‘’ for code, "__" for italic, "**" for bold and "~~" for strikethrough.
  • mardown top-level sections shall use '#', second level '##', and so on
  • mardown bullet lists shall use "- ", " - " etc...
  • notes shall be identifed as a line starting with "Note: "
  • warnings shall be identifed as a line starting with "Warning: "
  • examples shall be identifed as a line starting with "EX "

  • the sequence "[-" is reserved for option links. It is formatted as:

    • "[-OPT]()": link to self page for option OPT
    • "[-OPT](LINK)": link to other page for option OPT. LINK can be:
    • GPAC: resolves to general GPAC help
    • CORE: resolves to general CORE help
    • LOG: resolves to general LOG help
    • ANY: resolves to filter with register name 'ANY'

    Note that [text](ANY) with ANY a filter register name will link to that filter help page