libgpac
Documentation of the core library of GPAC

Filter Interconnection. More...

+ Collaboration diagram for Filter PID:

Data Structures

struct  GF_FilterPidStatistics
 

Typedefs

typedef Bool(* gf_filter_prop_filter) (void *cbk, u32 prop_4cc, const char *prop_name, const GF_PropertyValue *src_prop)
 

Enumerations

enum  GF_FilterPidStatsLocation {
  GF_STATS_LOCAL = 0, GF_STATS_LOCAL_INPUTS, GF_STATS_DECODER_SINK, GF_STATS_DECODER_SOURCE,
  GF_STATS_ENCODER_SINK, GF_STATS_ENCODER_SOURCE
}
 

Functions

GF_FilterPidgf_filter_pid_new (GF_Filter *filter)
 
void gf_filter_pid_remove (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_raw_new (GF_Filter *filter, const char *url, const char *local_file, const char *mime_type, const char *fext, u8 *probe_data, u32 probe_size, Bool trust_mime, GF_FilterPid **out_pid)
 
GF_Err gf_filter_pid_set_property (GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_set_property_str (GF_FilterPid *PID, const char *name, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_set_property_dyn (GF_FilterPid *PID, char *name, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_set_info (GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_set_info_str (GF_FilterPid *PID, const char *name, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_set_info_dyn (GF_FilterPid *PID, char *name, const GF_PropertyValue *value)
 
void gf_filter_pid_set_udta (GF_FilterPid *PID, void *udta)
 
void * gf_filter_pid_get_udta (GF_FilterPid *PID)
 
u32 gf_filter_pid_get_udta_flags (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_set_udta_flags (GF_FilterPid *PID, u32 flags)
 
void gf_filter_pid_set_name (GF_FilterPid *PID, const char *name)
 
const char * gf_filter_pid_get_name (GF_FilterPid *PID)
 
const char * gf_filter_pid_get_filter_name (GF_FilterPid *PID)
 
const char * gf_filter_pid_orig_src_args (GF_FilterPid *PID, Bool for_unicity)
 
const char * gf_filter_pid_get_source_filter_name (GF_FilterPid *PID)
 
const char * gf_filter_pid_get_args (GF_FilterPid *PID)
 
void gf_filter_pid_set_max_buffer (GF_FilterPid *PID, u32 total_duration_us)
 
u32 gf_filter_pid_get_max_buffer (GF_FilterPid *PID)
 
Bool gf_filter_pid_is_filter_in_parents (GF_FilterPid *PID, GF_Filter *filter)
 
Bool gf_filter_pid_share_origin (GF_FilterPid *PID, GF_FilterPid *other_pid)
 
Bool gf_filter_pid_get_buffer_occupancy (GF_FilterPid *PID, u32 *max_units, u32 *nb_pck, u32 *max_duration, u32 *duration)
 
void gf_filter_pid_set_loose_connect (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_push_properties (GF_FilterPid *PID, char *args, Bool direct_merge, Bool use_default_seps)
 
GF_Err gf_filter_pid_negociate_property (GF_FilterPid *PID, u32 prop_4cc, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_negociate_property_str (GF_FilterPid *PID, const char *name, const GF_PropertyValue *value)
 
GF_Err gf_filter_pid_negociate_property_dyn (GF_FilterPid *PID, char *name, const GF_PropertyValue *value)
 
const GF_PropertyValue * gf_filter_pid_caps_query (GF_FilterPid *PID, u32 prop_4cc)
 
const GF_PropertyValue * gf_filter_pid_caps_query_str (GF_FilterPid *PID, const char *prop_name)
 
GF_Err gf_filter_pid_get_statistics (GF_FilterPid *PID, GF_FilterPidStatistics *stats, GF_FilterPidStatsLocation location)
 
GF_Err gf_filter_pid_reset_properties (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_copy_properties (GF_FilterPid *dst_pid, GF_FilterPid *src_pid)
 
GF_Err gf_filter_pid_merge_properties (GF_FilterPid *dst_pid, GF_FilterPid *src_pid, gf_filter_prop_filter filter_prop, void *cbk)
 
const GF_PropertyValue * gf_filter_pid_get_property (GF_FilterPid *PID, u32 prop_4cc)
 
const GF_PropertyValue * gf_filter_pid_get_property_str (GF_FilterPid *PID, const char *prop_name)
 
const GF_PropertyValue * gf_filter_pid_enum_properties (GF_FilterPid *PID, u32 *idx, u32 *prop_4cc, const char **prop_name)
 
const GF_PropertyValue * gf_filter_pid_enum_info (GF_FilterPid *PID, u32 *idx, u32 *prop_4cc, const char **prop_name)
 
GF_Err gf_filter_pid_set_framing_mode (GF_FilterPid *PID, Bool requires_full_blocks)
 
u64 gf_filter_pid_query_buffer_duration (GF_FilterPid *PID, Bool check_pid_full)
 
void gf_filter_pid_try_pull (GF_FilterPid *PID)
 
const GF_PropertyValue * gf_filter_pid_get_info (GF_FilterPid *PID, u32 prop_4cc, GF_PropertyEntry **propentry)
 
const GF_PropertyValue * gf_filter_pid_get_info_str (GF_FilterPid *PID, const char *prop_name, GF_PropertyEntry **propentry)
 
void gf_filter_pid_set_eos (GF_FilterPid *PID)
 
Bool gf_filter_pid_has_seen_eos (GF_FilterPid *PID)
 
Bool gf_filter_pid_eos_received (GF_FilterPid *PID)
 
Bool gf_filter_pid_is_eos (GF_FilterPid *PID)
 
Bool gf_filter_pid_first_packet_is_empty (GF_FilterPid *PID)
 
GF_FilterPacketgf_filter_pid_get_packet (GF_FilterPid *PID)
 
Bool gf_filter_pid_get_first_packet_cts (GF_FilterPid *PID, u64 *cts)
 
void gf_filter_pid_drop_packet (GF_FilterPid *PID)
 
u32 gf_filter_pid_get_packet_count (GF_FilterPid *PID)
 
Bool gf_filter_pid_check_caps (GF_FilterPid *PID)
 
Bool gf_filter_pid_would_block (GF_FilterPid *PID)
 
u32 gf_filter_pid_get_timescale (GF_FilterPid *PID)
 
void gf_filter_pid_clear_eos (GF_FilterPid *PID, Bool all_pids)
 
void gf_filter_pid_set_clock_mode (GF_FilterPid *PID, Bool filter_in_charge)
 
GF_Err gf_filter_pid_resolve_file_template (GF_FilterPid *PID, char szTemplate[GF_MAX_PATH], char szFinalName[GF_MAX_PATH], u32 file_number, const char *file_suffix)
 
GF_Err gf_filter_pid_resolve_file_template_ex (GF_FilterPid *PID, char szTemplate[GF_MAX_PATH], char szFinalName[GF_MAX_PATH], u32 file_number, const char *file_suffix, const char *file_name)
 
GF_Err gf_filter_pid_set_discard (GF_FilterPid *PID, Bool discard_on)
 
void gf_filter_pid_discard_block (GF_FilterPid *PID)
 
char * gf_filter_pid_get_destination (GF_FilterPid *PID)
 
char * gf_filter_pid_get_source (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_require_source_id (GF_FilterPid *PID)
 
void gf_filter_pid_recompute_dts (GF_FilterPid *PID, Bool do_recompute)
 
u32 gf_filter_pid_get_min_pck_duration (GF_FilterPid *PID)
 
void gf_filter_pid_send_event (GF_FilterPid *PID, GF_FilterEvent *evt)
 
void gf_filter_pid_init_play_event (GF_FilterPid *PID, GF_FilterEvent *evt, Double start, Double speed, const char *log_name)
 
Bool gf_filter_pid_is_playing (GF_FilterPid *PID)
 
GF_Err gf_filter_pid_allow_direct_dispatch (GF_FilterPid *PID)
 
void * gf_filter_pid_get_alias_udta (GF_FilterPid *PID)
 
GF_Filtergf_filter_pid_get_source_filter (GF_FilterPid *PID)
 
GF_Filtergf_filter_pid_enum_destinations (GF_FilterPid *PID, u32 idx)
 
GF_Err gf_filter_pid_ignore_blocking (GF_FilterPid *PID, Bool do_ignore)
 
u64 gf_filter_pid_get_next_ts (GF_FilterPid *PID)
 

Detailed Description

A PID is a connection between two filters, holding packets to process. Internally, a PID created by a filter (output PID) is different from an input PID to a filter (configure_pid) but the API has been designed to hide this, so that most PID functions can be called regardless of the input/output nature of the PID.

All setters functions (gf_filter_pid_set*) will fail on an input PID.

The generic design of the architecture is that each filter is free to decide how it handle PIDs and their packets. This implies that the filter session has no clue how an output PID relates to an input PID (same goes for packets). Developpers must therefore manually copy PID properties that seem relevant, or more practically copy all properties from input PID to output PID and reassign output PID properties changed by the filter.

PIDs can be reconfigured multiple times, even potentially changing caps on the fly. The current architecture does not check for capability matching during reconfigure, it is up to the filter to do so.

It is also up to filters to decide how to handle a an input PID removal: remove the output PID immediately, keep it open to flush internal data or keep generating data on the output. The usual practice is to remove the output as soon as the input is removed.

Once an input PID has been notified to be removed, it shall no longer be used by the filter, as it may be discarded/freed (PID are NOT reference counted).


Data Structure Documentation

◆ GF_FilterPidStatistics

struct GF_FilterPidStatistics

Statistics for PID

Data Fields
u32 disconnected

if set, indicates the PID is disconnected and stats are not valid

u32 average_process_rate

average process rate on that PID in bits per seconds

u32 max_process_rate

max process rate on that PID in bits per seconds

u32 avgerage_bitrate

average bitrate for that PID

u32 max_bitrate

max bitrate for that PID

u32 nb_processed

number of packets processed on that PID

u32 max_process_time

max packet process time of the filter in us

u64 total_process_time

total process time of the filter in us

u64 first_process_time

process time of first packet of the filter in us

u64 last_process_time

process time of the last packet on that PID in us

u32 min_frame_dur

minimum frame duration on that PID in us

u32 nb_saps

number of saps 1/2/3 on that PID

u32 max_sap_process_time

max process time of SAP packets on that PID in us

u64 total_sap_process_time

total process time of SAP packets on that PID in us

u64 max_buffer_time

max buffer time in us - only set when querying decoder stats

u64 max_playout_time

max playout buffer time in us - only set when querying decoder stats

u64 min_playout_time

min playout buffer time in us - only set when querying decoder stats

u64 buffer_time

current buffer time in us - only set when querying decoder stats

u32 nb_buffer_units

number of units in input buffer of the filter - only set when querying decoder stats

Typedef Documentation

◆ gf_filter_prop_filter

typedef Bool(* gf_filter_prop_filter) (void *cbk, u32 prop_4cc, const char *prop_name, const GF_PropertyValue *src_prop)

Function protoype for filtering properties.

Parameters
cbkcallback data
prop_4ccthe built-in property code
prop_nameproperty name
src_propthe property value in the source packet
Returns
GF_TRUE if the property shall be merged, GF_FALSE otherwise

Enumeration Type Documentation

◆ GF_FilterPidStatsLocation

Direction for stats querying

Enumerator
GF_STATS_LOCAL 

statistics are fetched on the current PID's parent filter. If the PID is an output PID, the statistics are fetched on all the destinations for that PID

GF_STATS_LOCAL_INPUTS 

statistics are fetched on the current PID's parent filter. The statistics are fetched on all input of the parent filter

GF_STATS_DECODER_SINK 

statistics are fetched on all inputs of the next decoder filter up the chain (towards the sink)

GF_STATS_DECODER_SOURCE 

statistics are fetched on all inputs of the previous decoder filter down the chain (towards the source)

GF_STATS_ENCODER_SINK 

statistics are fetched on all inputs of the next encoder filter up the chain (towards the sink)

GF_STATS_ENCODER_SOURCE 

statistics are fetched on all inputs of the previous encoder filter down the chain (towards the source)

Function Documentation

◆ gf_filter_pid_new()

GF_FilterPid* gf_filter_pid_new ( GF_Filter filter)

Creates a new output PID for the filter. If the filter has a single input PID already connected, the PID properties are copied by default

Parameters
filterthe target filter
Returns
the new output PID

◆ gf_filter_pid_remove()

void gf_filter_pid_remove ( GF_FilterPid PID)

Removes an output PID from the filter. This will trigger removal of the PID upward in the chain

Parameters
PIDthe target filter PID to remove

◆ gf_filter_pid_raw_new()

GF_Err gf_filter_pid_raw_new ( GF_Filter filter,
const char *  url,
const char *  local_file,
const char *  mime_type,
const char *  fext,
u8 probe_data,
u32  probe_size,
Bool  trust_mime,
GF_FilterPid **  out_pid 
)

Creates an output PID for a raw input filter (file, sockets, pipe, etc). This will assign file name, local name, mime and extension properties to the created PID

Parameters
filterthe target filter
urlURL of the source, SHALL be set
local_filepath on local host, can be NULL
mime_typemime type of the content. If none provided and propbe_data is not null, the data will be probed for mime type resolution
fextfile extension of the content. If NULL, will be extracted from URL
probe_datadata of the stream to probe in order to solve its mime type
probe_sizesize of the probe data
trust_mimeif set and mime_type is set, disables data probing
out_pidthe output PID to create or update. If no referer PID, a new PID will be created otherwise the PID will be updated
Returns
error code if any

◆ gf_filter_pid_set_property()

GF_Err gf_filter_pid_set_property ( GF_FilterPid PID,
u32  prop_4cc,
const GF_PropertyValue *  value 
)

Sets a new property on an output PID for built-in property names. Setting a new property will trigger a PID reconfigure at the consumption point of the next dispatched packet. Previous properties (ones set before last packet dispatch) will still be valid. You can remove any of them using gf_filter_pid_set_property with NULL property, or reset the properties with gf_filter_pid_reset_properties. There cannot be two instances of a property a given type/name:

  • If a property with same type/name exists and has the same value, assignment will be skipped: this avoids triggering PID reconfiguration when not needed. In that case, if the property contains memory to be passed to the filter session, this memory will be destroyed (eg GF_PROP_STRING_NO_COPY, GF_PROP_DATA_NO_COPY, GF_PROP_STRING_LIST).
  • If the values differ, the property will be reassigned. There cannot be tow instances of a proerty value with a given type/name.

Warning: changing a property at the final end of stream (i.e. if no more packets are sent) will have no effect. You must use gf_filter_pid_set_info and gf_filter_pid_get_info for this.

Parameters
PIDthe target filter PID
prop_4ccthe built-in property code to modify
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_property_str()

GF_Err gf_filter_pid_set_property_str ( GF_FilterPid PID,
const char *  name,
const GF_PropertyValue *  value 
)

Sets a new property on an output PID - see gf_filter_pid_set_property.

Parameters
PIDthe target filter PID
namethe name of the property to modify
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_property_dyn()

GF_Err gf_filter_pid_set_property_dyn ( GF_FilterPid PID,
char *  name,
const GF_PropertyValue *  value 
)

Sets a new property on an output PID - see gf_filter_pid_set_property.

Parameters
PIDthe target filter PID
namethe name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_info()

GF_Err gf_filter_pid_set_info ( GF_FilterPid PID,
u32  prop_4cc,
const GF_PropertyValue *  value 
)

Sets a new info property on an output PID for built-in property names. Similar to gf_filter_pid_set_property, but infos are not copied up the chain and to not trigger PID reconfiguration. First packet dispatched after calling this function will be marked, and its fetching by the consuming filter will trigger a process_event notification. If the consumming filter copies properties from source packet to output packet, the flag will be passed to such new output packet.

If an info property with same type/name exists and has the same value, assignment will be skipped. In that case, if the property contains memory to be passed to the filter session, this memory will be destroyed (eg GF_PROP_STRING_NO_COPY, GF_PROP_DATA_NO_COPY, GF_PROP_STRING_LIST).

Parameters
PIDthe target filter PID
prop_4ccthe built-in property code to modify
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_info_str()

GF_Err gf_filter_pid_set_info_str ( GF_FilterPid PID,
const char *  name,
const GF_PropertyValue *  value 
)

Sets a new info property on an output PID - see gf_filter_pid_set_info See gf_filter_pid_set_info

Parameters
PIDthe target filter PID
namethe name of the property to modify
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_info_dyn()

GF_Err gf_filter_pid_set_info_dyn ( GF_FilterPid PID,
char *  name,
const GF_PropertyValue *  value 
)

Sets a new property on an output PID. See gf_filter_pid_set_info

Parameters
PIDthe target filter PID
namethe name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session
valuethe new value to assign, or NULL if the property is to be removed
Returns
error code if any

◆ gf_filter_pid_set_udta()

void gf_filter_pid_set_udta ( GF_FilterPid PID,
void *  udta 
)

Sets user data pointer for a PID - see gf_filter_pid_set_info

Parameters
PIDthe target filter PID
udtauser data pointer

◆ gf_filter_pid_get_udta()

void* gf_filter_pid_get_udta ( GF_FilterPid PID)

Gets user data pointer for a PID

Parameters
PIDthe target filter PID
Returns
udta user data pointer

◆ gf_filter_pid_get_udta_flags()

u32 gf_filter_pid_get_udta_flags ( GF_FilterPid PID)

get user 32-bits flags

Parameters
PIDthe target filter PID
Returns
flags

◆ gf_filter_pid_set_udta_flags()

GF_Err gf_filter_pid_set_udta_flags ( GF_FilterPid PID,
u32  flags 
)

set user 32-bits flags

Parameters
PIDthe target filter PID
flagsthe flags (replaces the entire flags))
Returns
error if any

◆ gf_filter_pid_set_name()

void gf_filter_pid_set_name ( GF_FilterPid PID,
const char *  name 
)

Gets PID name. Mostly used for logging purposes

Parameters
PIDthe target filter PID
namethe new PID name. function ignored if NULL.

◆ gf_filter_pid_get_name()

const char* gf_filter_pid_get_name ( GF_FilterPid PID)

Gets PID name

Parameters
PIDthe target filter PID
Returns
PID name

◆ gf_filter_pid_get_filter_name()

const char* gf_filter_pid_get_filter_name ( GF_FilterPid PID)

Gets filter name of input PID

Parameters
PIDthe target filter PID
Returns
name of the filter owning this input PID

◆ gf_filter_pid_orig_src_args()

const char* gf_filter_pid_orig_src_args ( GF_FilterPid PID,
Bool  for_unicity 
)

Gets the source arguments of the PID, walking down the chain until the source filter

Parameters
PIDthe target filter PID
for_unicityif GF_TRUE, will return the arguments of the first filter responsible for a fan-out leading to this PID
Returns
argument of the source filter

◆ gf_filter_pid_get_source_filter_name()

const char* gf_filter_pid_get_source_filter_name ( GF_FilterPid PID)

Gets the source filter name or class name for the PID, walking down the chain until the source filter (ony the first input PID of each filter is used).

Parameters
PIDthe target filter PID
Returns
argument of the source filter

◆ gf_filter_pid_get_args()

const char* gf_filter_pid_get_args ( GF_FilterPid PID)

Gets the arguments for the filter

Parameters
PIDthe target filter PID
Returns
arguments of the source filter

◆ gf_filter_pid_set_max_buffer()

void gf_filter_pid_set_max_buffer ( GF_FilterPid PID,
u32  total_duration_us 
)

Sets max buffer requirement of an output PID. Typically used by audio to make sure several packets can be dispatched on a PID that would otherwise block after one packet

Parameters
PIDthe target filter PID
total_duration_usbuffer max occupancy in us

◆ gf_filter_pid_get_max_buffer()

u32 gf_filter_pid_get_max_buffer ( GF_FilterPid PID)

Returns max buffer requirement of a PID.

Parameters
PIDthe target filter PID
Returns
buffer max in us

◆ gf_filter_pid_is_filter_in_parents()

Bool gf_filter_pid_is_filter_in_parents ( GF_FilterPid PID,
GF_Filter filter 
)

Checks if a given filter is in the PID parent chain. This is used to identify sources (rather than checking URL/...)

Parameters
PIDthe target filter PID
filterthe source filter to check
Returns
GF_TRUE if filter is a source for that PID, GF_FALSE otherwise

◆ gf_filter_pid_share_origin()

Bool gf_filter_pid_share_origin ( GF_FilterPid PID,
GF_FilterPid other_pid 
)

Checks if a given PID has a common filter with another PID in the parent graph

Parameters
PIDthe target filter PID
other_pidthe other PID to check
Returns
GF_TRUE if a filter is found that is outputing these two PIDs, GF_FALSE otherwise

◆ gf_filter_pid_get_buffer_occupancy()

Bool gf_filter_pid_get_buffer_occupancy ( GF_FilterPid PID,
u32 max_units,
u32 nb_pck,
u32 max_duration,
u32 duration 
)

Gets current buffer levels of the PID

Parameters
PIDthe target filter PID
max_unitsmaximum number of packets allowed - can be 0 if buffer is measured in time
nb_pcknumber of packets in PID
max_durationmaximum buffer duration allowed in us - can be 0 if buffer is measured in units
durationbuffer duration in us
Returns
GF_TRUE if normal buffer query, GF_FALSE if final session flush, in which case buffer might never complete

◆ gf_filter_pid_set_loose_connect()

void gf_filter_pid_set_loose_connect ( GF_FilterPid PID)

Sets loose connect for a PID, avoiding to throw an error if connection of the PID fails. Used by the compositor filter which acts as both sink and filter.

Parameters
PIDthe target filter PID

◆ gf_filter_pid_push_properties()

GF_Err gf_filter_pid_push_properties ( GF_FilterPid PID,
char *  args,
Bool  direct_merge,
Bool  use_default_seps 
)

Adds PID properties from textual description - this does not reset the PID properties

Parameters
PIDthe target filter PID
argsone or more serialized properties to set, as documented in gpac -h doc
direct_mergeif true, next packet to be sent will not trigger a property change
use_default_sepsif GF_TRUE, the serialized properties are using the default separator set, otherwise they are using the current separator set of the session
Returns
Error if any

◆ gf_filter_pid_negociate_property()

GF_Err gf_filter_pid_negociate_property ( GF_FilterPid PID,
u32  prop_4cc,
const GF_PropertyValue *  value 
)

Negotiate a given property on an input PID for built-in properties Filters may accept some PID connection but may need an adaptaion chain to be able to process packets, eg change pixel format or sample rate This function will trigger a reconfiguration of the filter chain to try to adapt this. If failing, the filter chain will disconnect This process is asynchronous, the filter asking for a PID negociation will see the notification through a pid_reconfigure if success.

Parameters
PIDthe target filter PID - this MUST be an input PID
prop_4ccthe built-in property code to negotiate
valuethe new value to negotiate, SHALL NOT be NULL
Returns
error code if any

◆ gf_filter_pid_negociate_property_str()

GF_Err gf_filter_pid_negociate_property_str ( GF_FilterPid PID,
const char *  name,
const GF_PropertyValue *  value 
)

Negotiate a given property on an input PID for regular properties see gf_filter_pid_negociate_property

Parameters
PIDthe target filter PID - this MUST be an input PID
namename of the property to negotiate
valuethe new value to negotiate, SHALL NOT be NULL
Returns
error code if any

◆ gf_filter_pid_negociate_property_dyn()

GF_Err gf_filter_pid_negociate_property_dyn ( GF_FilterPid PID,
char *  name,
const GF_PropertyValue *  value 
)

Negotiate a given property on an input PID for regular properties see gf_filter_pid_negociate_property

Parameters
PIDthe target filter PID - this MUST be an input PID
namethe name of the property to modify. The name will be copied to the property, and memory destruction performed by the filter session
valuethe new value to negotiate, SHALL NOT be NULL
Returns
error code if any

◆ gf_filter_pid_caps_query()

const GF_PropertyValue* gf_filter_pid_caps_query ( GF_FilterPid PID,
u32  prop_4cc 
)

Queries a negotiated built-in capability on an output PID Filters may check if a property negotiation was done on an output PID, and check the property value. This can be done on an output PID in a filter->reconfigure_output if the filter accepts caps negotiation This can be done on an input PID in a generic reconfigure_pid

Parameters
PIDthe target filter PID
prop_4ccthe built-in property code to negotiate
Returns
the negociated property value

◆ gf_filter_pid_caps_query_str()

const GF_PropertyValue* gf_filter_pid_caps_query_str ( GF_FilterPid PID,
const char *  prop_name 
)

Queries a negotiated capability on an output PID - see gf_filter_pid_caps_query

Parameters
PIDthe target filter PID
prop_namethe property name to negotiate
Returns
the negociated property value

◆ gf_filter_pid_get_statistics()

GF_Err gf_filter_pid_get_statistics ( GF_FilterPid PID,
GF_FilterPidStatistics stats,
GF_FilterPidStatsLocation  location 
)

Gets statistics for the PID

Parameters
PIDthe target filter PID
statsthe retrieved statistics
locationindicates where to locate the filter to query stats on it.
Returns
error code if any

◆ gf_filter_pid_reset_properties()

GF_Err gf_filter_pid_reset_properties ( GF_FilterPid PID)

Resets current properties of the PID

Parameters
PIDthe target filter PID
Returns
error code if any

◆ gf_filter_pid_copy_properties()

GF_Err gf_filter_pid_copy_properties ( GF_FilterPid dst_pid,
GF_FilterPid src_pid 
)

Push a new set of properties on destination PID using all properties from source PID. Old properties in destination will be lost (i.e. reset properties is always performed during copy properties)

Parameters
dst_pidthe destination filter PID
src_pidthe source filter PID
Returns
error code if any

◆ gf_filter_pid_merge_properties()

GF_Err gf_filter_pid_merge_properties ( GF_FilterPid dst_pid,
GF_FilterPid src_pid,
gf_filter_prop_filter  filter_prop,
void *  cbk 
)

Push a new set of properties on destination PID, using all properties from source PID, potentially filtering them. Currently defined properties are not reseted.

Parameters
dst_pidthe destination filter PID
src_pidthe source filter PID
filter_propcallback filtering function
cbkcallback data passed to the callback function
Returns
error code if any

◆ gf_filter_pid_get_property()

const GF_PropertyValue* gf_filter_pid_get_property ( GF_FilterPid PID,
u32  prop_4cc 
)

Gets a built-in property of the PID Warning: properties are only valid until the next configure_pid is called. Attempting to use a property value (either the pointer or one of the value) queried before the current configure_pid will result in unpredictable behavior, potentially crashes.

Parameters
PIDthe target filter PID
prop_4ccthe code of the built-in property to retrieve
Returns
the property if found or NULL otherwise

◆ gf_filter_pid_get_property_str()

const GF_PropertyValue* gf_filter_pid_get_property_str ( GF_FilterPid PID,
const char *  prop_name 
)

Gets a property of the PID - see gf_filter_pid_get_property

Parameters
PIDthe target filter PID
prop_namethe name of the property to retrieve
Returns
the property if found or NULL otherwise

◆ gf_filter_pid_enum_properties()

const GF_PropertyValue* gf_filter_pid_enum_properties ( GF_FilterPid PID,
u32 idx,
u32 prop_4cc,
const char **  prop_name 
)

Enumerates properties of a PID - see gf_filter_pid_get_property

Parameters
PIDthe target filter PID
idxinput/output index of the current property. 0 means first. Incremented by 1 upon success
prop_4ccset to the built-in code of the property if built-in
prop_nameset to the name of the property if not built-in
Returns
the property if found or NULL otherwise (end of enumeration)

◆ gf_filter_pid_enum_info()

const GF_PropertyValue* gf_filter_pid_enum_info ( GF_FilterPid PID,
u32 idx,
u32 prop_4cc,
const char **  prop_name 
)

Enumerates info of a PID

Parameters
PIDthe target filter PID
idxinput/output index of the current info. 0 means first. Incremented by 1 upon success
prop_4ccset to the built-in code of the info if built-in
prop_nameset to the name of the info if not built-in
Returns
the property if found or NULL otherwise (end of enumeration)

◆ gf_filter_pid_set_framing_mode()

GF_Err gf_filter_pid_set_framing_mode ( GF_FilterPid PID,
Bool  requires_full_blocks 
)

Sets PID framing mode. filters can consume packets as they arrive, or may want to only process full frames/files

Parameters
PIDthe target filter PID
requires_full_blocksif GF_TRUE, the packets on the PID will be reaggregated to form complete frame/files.
Returns
error code if any

◆ gf_filter_pid_query_buffer_duration()

u64 gf_filter_pid_query_buffer_duration ( GF_FilterPid PID,
Bool  check_pid_full 
)

Gets cumulated buffer duration of PID (recursive until source)

Parameters
PIDthe target filter PID
check_pid_fullif GF_TRUE, returns 0 if the PID buffer is not yet full
Returns
the duration in us, or -1 if session is in final flush

◆ gf_filter_pid_try_pull()

void gf_filter_pid_try_pull ( GF_FilterPid PID)

Try to force a synchronous flush of the filter chain downwards this PID. If refetching a packet returns NULL, this failed.

Parameters
PIDthe target filter PID

◆ gf_filter_pid_get_info()

const GF_PropertyValue* gf_filter_pid_get_info ( GF_FilterPid PID,
u32  prop_4cc,
GF_PropertyEntry **  propentry 
)

Looks for a built-in property value on a PIDs. This is a recursive call on input chain Info query is NOT threadsafe in gpac, you Properties retrieved shall be released using gf_filter_release_property. See gf_filter_pid_get_info for more details.

Parameters
PIDthe target filter PID to query
prop_4ccthe code of the built-in 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_pid_get_info_str()

const GF_PropertyValue* gf_filter_pid_get_info_str ( GF_FilterPid PID,
const char *  prop_name,
GF_PropertyEntry **  propentry 
)

Looks for a property value on a PIDs. 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
PIDthe target filter PID to query
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_pid_set_eos()

void gf_filter_pid_set_eos ( GF_FilterPid PID)

Signals end of stream on a PID. Each filter needs to call this when EOS is reached on a given stream since there is no explicit link between input PIDs and output PIDs

Parameters
PIDthe target filter PID

◆ gf_filter_pid_has_seen_eos()

Bool gf_filter_pid_has_seen_eos ( GF_FilterPid PID)

Checks for end of stream has been signaled a PID input chain. This is a recursive call on input chain. The function is typically used to abort buffering or synchronisation init in muxers.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if end of stream was signaled on the input chain

◆ gf_filter_pid_eos_received()

Bool gf_filter_pid_eos_received ( GF_FilterPid PID)

Checks for end of stream has been signaled a PID. Contrary to gf_filter_pid_has_seen_eos this is not a recursive call and only checks the given pid.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if end of stream was signaled for that pid (there may be pending packets in queue)

◆ gf_filter_pid_is_eos()

Bool gf_filter_pid_is_eos ( GF_FilterPid PID)

Checks for end of stream signaling on a PID.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if end of stream is set on that PID (no more packet in queue)

◆ gf_filter_pid_first_packet_is_empty()

Bool gf_filter_pid_first_packet_is_empty ( GF_FilterPid PID)

Checks if there is a packet ready on an input PID.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if no packet in buffers

◆ gf_filter_pid_get_packet()

GF_FilterPacket* gf_filter_pid_get_packet ( GF_FilterPid PID)

Gets the first packet in the input PID buffer. This may trigger a reconfigure signal on the filter. If reconfigure is not OK, returns NULL and the PID passed to the filter NO LONGER EXISTS (implicit remove) The packet is still present in the PID buffer until explicitly removed by gf_filter_pid_drop_packet

Parameters
PIDthe target filter PID
Returns
packet or NULL of empty or reconfigure error

◆ gf_filter_pid_get_first_packet_cts()

Bool gf_filter_pid_get_first_packet_cts ( GF_FilterPid PID,
u64 cts 
)

Fetches the CTS of the first packet in the input PID buffer.

Parameters
PIDthe target filter PID
ctsset to the composition time of the first packet, in PID timescale
Returns
GF_TRUE if cts was fetched, GF_FALSE otherwise

◆ gf_filter_pid_drop_packet()

void gf_filter_pid_drop_packet ( GF_FilterPid PID)

Drops the first packet in the input PID buffer.

Parameters
PIDthe target filter PID

◆ gf_filter_pid_get_packet_count()

u32 gf_filter_pid_get_packet_count ( GF_FilterPid PID)

Gets the number of packets in input PID buffer.

Parameters
PIDthe target filter PID
Returns
the number of packets

◆ gf_filter_pid_check_caps()

Bool gf_filter_pid_check_caps ( GF_FilterPid PID)

Checks the capability of the input PID match its destination filter.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if match , GF_FALSE otherwise

◆ gf_filter_pid_would_block()

Bool gf_filter_pid_would_block ( GF_FilterPid PID)

Checks if the PID would enter a blocking state if a new packet is sent. This function should be called by eg demuxers to regulate the rate at which they send packets

Note
PIDs are never fully blocking in GPAC, a filter requesting an output packet should usually get one unless something goes wrong
Parameters
PIDthe target filter PID
Returns
GF_TRUE if PID would enter blocking state , GF_FALSE otherwise

◆ gf_filter_pid_get_timescale()

u32 gf_filter_pid_get_timescale ( GF_FilterPid PID)

Shortcut to access the timescale of the PID - faster than get property as the timescale is locally cached for buffer management

Parameters
PIDthe target filter PID
Returns
the PID timescale

◆ gf_filter_pid_clear_eos()

void gf_filter_pid_clear_eos ( GF_FilterPid PID,
Bool  all_pids 
)

Clears the end of stream flag on a PID.

Note
The end of stream is automatically cleared when a new packet is dispatched; This function is used to clear it asap, before next packet dispacth (period switch in dash for example).
Parameters
PIDthe target filter PID
all_pidsif sets, clear end oof stream for all PIDs coming from the same filter as the target PID

◆ gf_filter_pid_set_clock_mode()

void gf_filter_pid_set_clock_mode ( GF_FilterPid PID,
Bool  filter_in_charge 
)

Indicates how clock references (PCR of MPEG-2) should be handled. By default these references are passed from input packets to output packets by the filter session (this assumes the filter doesn't modify composition timestamps). This default can be changed with this function.

Parameters
PIDthe target filter PID
filter_in_chargeif set to GF_TRUE, clock references are not forwarded by the filter session and the filter is in charge of handling them

◆ gf_filter_pid_resolve_file_template()

GF_Err gf_filter_pid_resolve_file_template ( GF_FilterPid PID,
char  szTemplate[GF_MAX_PATH],
char  szFinalName[GF_MAX_PATH],
u32  file_number,
const char *  file_suffix 
)

Resolves file template using PID properties and file index. Templates follow the DASH mechanism:

  • $KEYWORD$ or $KEYWORD%0nd$ are replaced in the template with the resolved value,
  • $$ is an escape for $

Supported KEYWORD (case insensitive):

  • num: replaced by file_number (usually matches GF_PROP_PCK_FILENUM, but this property is not used in the solving mechanism)
  • PID: ID of the source PID
  • URL: URL of source file
  • File: path on disk for source file
  • p4cc=ABCD: uses PID property with 4CC ABCD
  • pname=VAL: uses PID property with name VAL (either built-in prop name or other peroperty name)
Parameters
PIDthe target filter PID
szTemplatesource template to solve
szFinalNamebuffer for final name
file_numbernumber of file to use
file_suffixif not null, will be appended after the value of the §File$ keyword if present
Returns
error if any

◆ gf_filter_pid_resolve_file_template_ex()

GF_Err gf_filter_pid_resolve_file_template_ex ( GF_FilterPid PID,
char  szTemplate[GF_MAX_PATH],
char  szFinalName[GF_MAX_PATH],
u32  file_number,
const char *  file_suffix,
const char *  file_name 
)

Same as gf_filter_pid_resolve_file_template but overrides file name with given name

Parameters
PIDthe target filter PID
szTemplatesource template to solve
szFinalNamebuffer for final name
file_numbernumber of file to use
file_suffixif not null, will be appended after the value of the §File$ keyword if present
file_nameif not null, will be used instead of PID URL or local path
Returns
error if any

◆ gf_filter_pid_set_discard()

GF_Err gf_filter_pid_set_discard ( GF_FilterPid PID,
Bool  discard_on 
)

Sets discard mode on or off on an input PID. When discard is on, all input packets for this PID are no longer dispatched.

This only affect the current PID, not the source filter(s) for that PID.

PID reconfigurations are still forwarded to the filter, so that a filter may decide to re-enable regular mode. Packets sent after a PID reconfiguration are kept until the PID is reconfigured, and discarded if the PID is still in discard mode.

This is typically needed for filters that stop consuming data for a while (dash forced period duration for example) but may resume consumption later on (stream moving from period 1 to period 2 for example).

Parameters
PIDthe target filter PID
discard_onenables/disables discard
Returns
error if any

◆ gf_filter_pid_discard_block()

void gf_filter_pid_discard_block ( GF_FilterPid PID)

Discard blocking mode for PID on end of stream. The filter is blocked when all output PIDs are in end of stream, this function unblocks the filter. This can be needed for playlist type filters dispatching end of stream at the end of each file but setting up next file in the following process() call.

Parameters
PIDthe target filter PID

◆ gf_filter_pid_get_destination()

char* gf_filter_pid_get_destination ( GF_FilterPid PID)

Gets URL argument of first destination of PID if any - memory shall be freed by caller.

Parameters
PIDthe target filter PID
Returns
destination URL string or NULL if error

◆ gf_filter_pid_get_source()

char* gf_filter_pid_get_source ( GF_FilterPid PID)

Gets URL argument of first source of PID if any - memory shall be freed by caller.

Parameters
PIDthe target filter PID
Returns
source URL string or NULL if error

◆ gf_filter_pid_require_source_id()

GF_Err gf_filter_pid_require_source_id ( GF_FilterPid PID)

Indicates that this output PID requires a sourceID on the destination filter to be present. This prevents trying to link to other filters with no source IDs but accepting the PID

Parameters
PIDthe target filter PID
Returns
error code if any

◆ gf_filter_pid_recompute_dts()

void gf_filter_pid_recompute_dts ( GF_FilterPid PID,
Bool  do_recompute 
)

Enables decoding time reconstruction on PID for packets with DTS not set. If not enabled (default), dts not set implies dts = cts

Parameters
PIDthe target filter PID
do_recomputeif set, dts will be recomputed when not set

◆ gf_filter_pid_get_min_pck_duration()

u32 gf_filter_pid_get_min_pck_duration ( GF_FilterPid PID)

Queries minimum packet duration as computed from DTS/CTS info on the PID

Parameters
PIDthe target filter PID
Returns
minimum packet duration computed

◆ gf_filter_pid_send_event()

void gf_filter_pid_send_event ( GF_FilterPid PID,
GF_FilterEvent *  evt 
)

Sends an event down the filter chain for input PID, or up the filter chain for output PIDs.

Parameters
PIDthe target filter PID
evtthe event to send

◆ gf_filter_pid_init_play_event()

void gf_filter_pid_init_play_event ( GF_FilterPid PID,
GF_FilterEvent *  evt,
Double  start,
Double  speed,
const char *  log_name 
)

Helper function to init play events, that checks the PID GF_FilterPidPlaybackMode and adjust start/speed accordingly. This does not send the event.

Parameters
PIDthe target filter PID
evtthe event to initialize
startplayback start time of request
speedplayback speed time of request
log_namename used for logs in case of capability mismatched

◆ gf_filter_pid_is_playing()

Bool gf_filter_pid_is_playing ( GF_FilterPid PID)

Check if the given PID is marked as playing or not.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if PID is currently playing, GF_FALSE otherwise

◆ gf_filter_pid_allow_direct_dispatch()

GF_Err gf_filter_pid_allow_direct_dispatch ( GF_FilterPid PID)

Enables direct dispatch of packets to connected filters. This mode is useful when a filter may send a very large number of packets in one process() call; this is for example the case of the isobmff muxer in interleave mode. Using this mode avoids overloading the PID buffer with packets. If the session is multi-threaded, this parameter has no effect.

Parameters
PIDthe target filter PID
Returns
GF_TRUE if PID is currently playing, GF_FALSE otherwise

◆ gf_filter_pid_get_alias_udta()

void* gf_filter_pid_get_alias_udta ( GF_FilterPid PID)

Gets the private stack of the alias filter associated with an input PID, if any

Note
The filter type of the alias is always the type of the filter holding the input PID connection.
Parameters
PIDthe target filter PID
Returns
the temporary alias filter private stack, NULL otherwise

◆ gf_filter_pid_get_source_filter()

GF_Filter* gf_filter_pid_get_source_filter ( GF_FilterPid PID)

Gets the filter owning the input PID

Parameters
PIDthe target filter PID
Returns
the filter owning the PID or NULL if error

◆ gf_filter_pid_enum_destinations()

GF_Filter* gf_filter_pid_enum_destinations ( GF_FilterPid PID,
u32  idx 
)

Enumerates the destination filters of an output PID

Parameters
PIDthe target filter PID
idxthe target destination index
Returns
the destination filter for the given index, or NULL if error

◆ gf_filter_pid_ignore_blocking()

GF_Err gf_filter_pid_ignore_blocking ( GF_FilterPid PID,
Bool  do_ignore 
)

Ignore this PID in blocking mode estimations.

This is typically used when a filter consumes N pids, with some at very low frequency for which an empty queue should not imply unblocking the filter to refill the queue.

Parameters
PIDthe target filter PID
do_ignoreif GF_TRUE, the PID will not be considered when trying to unblock the filter
Returns
error if any

◆ gf_filter_pid_get_next_ts()

u64 gf_filter_pid_get_next_ts ( GF_FilterPid PID)

Gets next estimated time on this PID, ie last_pck(DTS+dur) or last_pck(CTS+dur)

Parameters
PIDthe target filter PID
Returns
GF_FILTER_NO_TS or estimated time