Filter Management

Filter Management of GPAC. More...

Collaboration diagram for Filter Management:

Modules
	Filter Session
	Filter Session.
	Filter Properties
	PID and filter properties.
	Filter Events
	Filter Events.
	Filter
	Filter.
	Filter PID
	Filter Interconnection.
	Filter Packet
	Filter data exchange.
	Custom Filter
	Custom Filter.

Detailed Description

API Documentation of the filter managment system of GPAC.

The filter management in GPAC is built using the following core objects:

• GF_FilterSession in charge of:
  • loading filters from register, managing argument parsing and co
  • resolving filter graphs to handle PID connection(s)
  • tracking data packets and properties exchanged on PIDs
  • scheduling tasks between filters
  • ensuring thread-safe filter state: a filter may be called from any thread in the session (unless explicitly asked not to), but only by a single thread at any time.
• __gf_filter_register static structure describing possible entry points of the filter, possible arguments and input output PID capabilities. Each filter share the same API (register definition) regardless of its type: source/sink, mux/demux, encode/decode, raw media processing, encoded media processing, ...
• GF_Filter is an instance of the filter register. A filter implementation typical tasks are:
  • accepting new input PIDs (for non source filters)
  • defining new output PIDs (for non sink filters), applying any property change due to filter processing
  • consuming packets on the input PIDs
  • dispatching packets on the output PIDs
• GF_FilterPid handling the connections between two filters.
  • PID natively supports fan-out (one filter PID connecting to multiple destinations).
  • A PID is in charge of dispatching packets to possible destinations and storing PID properties in sync with dispatched packets.
  • Whenever PID properties change, the next packet sent on that PID is associated with the new state, and the destination filter(s) will be called upon fetching the new packet. This is the one of the two reentrant code of a filter, the other one being the GF_FEVT_INFO_UPDATE event.
  • When blocking mode is not disabled at the session filter, a PID is also in charge of managing its occupancy through either a number of packets or the cumulated duration of the packets it is holding.
  • Whenever a PID holds too much data, it enters a blocking state. A filter with ALL its output PIDs in a blocked state won't be scheduled for processing. This is a semi-blocking design, which imply that if a filter has one of its PIDs in a non blocking state, it will be scheduled for processing. If a PID has multiple destinations and one of the destination consumes faster than the other one, the filter is currently not blocking (this might change in the near future).
  • A PID is in charge of managing the packet references across filters, by performing memory management of allocated data packets (avoid alloc/free at each packet but rather recycle the memory) and tracking shared packets references.
• GF_FilterPacket holding data to dispatch from a filter on a given PID.
  • Packets are always associated to a single output PID, ie it is not possible for a filter to send one packet to multiple PIDs, the data has to be cloned.
  • Packets have default attributes such as timestamps, size, random access status, start/end frame, etc, as well as optional properties.
  • All packets are reference counted.
  • A packet can hold allocated block on the output PID, a pointer to some filter internal data, a data reference to a single input packet, or a frame interface object used for accessing data or OpenGL textures of the emitting filter. Packets holding data references rather than copy are notified back to their creators upon destruction.
• __gf_prop_val holding various properties for a PID or a packet
  • Properties can be copied/merged between input and output PIDs, or input and output packets. These properties are reference counted.
  • Two kinds of properties are defined, built-in ones which use a 32 bit identifier (usually a four character code), and user properties identified by a string.
  • PID properties are defined by the filter creating the PID. They can be overridden/added after being set by the filter by specifying fragment properties in the filter arguments. For example

    fin=src=myfile.foo:#FEXT=bar 

    will override the file extension property (FEXT) foo to bar AFTER the PID is being defined.
• __gf_filter_event used to pass various events (play/stop/buffer requirements/...) up and down the filter chain. This part of the API will likely change in the future, being merged with the global GF_Event of GPAC.

GPAC comes with a set of built-in filters in libgpac. It is also possible to define external filters in dynamic libraries. GPAC will look for such libraries in default module folder and folders listed in GPAC config file section core, key mod-dirs. The files SHALL be named gf_* and export a function called RegisterFilter with the following prototype:

Parameters

fsess

is set to NULL unless meta filters are listed, in which case the filter register should list all possible meta filters it supports

Returns

a GF_FilterRegister structure used for instantiating the filter.

const GF_FilterRegister *RegisterFilter(GF_FilterSession *fsess);