GF_FilterRegister Struct Reference

#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)
s16	priority
u8	hint_class_type
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

filter	the target filter
PID	the input PID to configure
is_remove	indicates 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

filter

the 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

filter

the 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

filter	the target filter
arg_name	the name of the argument being set
new_val	the 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

  filter	the target filter
  evt	the 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

filter	the target filter
PID	the 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

url	the url of the source to probe, never NULL.
mime	the 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

data	data to probe
size	size of the data to probe
score	set 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

s16 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

hint_class_type

u8 GF_FilterRegister::hint_class_type

hint class type for doc generation, one of GF_ClassTypeHint

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

session	the filter session
freg	the 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

filter	the target filter
url	the url of the target destination, never NULL.
mime	the 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"); 

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