libgpac
Documentation of the core library of GPAC
Filter Events

Filter Events. More...

+ Collaboration diagram for Filter Events:

Data Structures

struct  GF_FEVT_Base
 
struct  GF_FEVT_Play
 
struct  GF_FEVT_SourceSeek
 
struct  GF_FEVT_SegmentSize
 
struct  GF_FEVT_FragmentSize
 
struct  GF_FEVT_AttachScene
 
struct  GF_FEVT_QualitySwitch
 
struct  GF_FEVT_Event
 
struct  GF_FEVT_FileDelete
 
struct  GF_FEVT_VisibilityHint
 
struct  GF_FEVT_BufferRequirement
 
struct  GF_FEVT_EncodeHints
 
struct  GF_FEVT_NTPRef
 
union  GF_FilterEvent
 

Macros

#define FILTER_EVENT_BASE
 
#define GF_FEVT_INIT(_a, _type, _on_pid)   { memset(&_a, 0, sizeof(GF_FilterEvent)); _a.base.type = _type; _a.base.on_pid = _on_pid; }
 

Enumerations

enum  GF_FEventType {
  GF_FEVT_PLAY = 1 , GF_FEVT_SET_SPEED , GF_FEVT_STOP , GF_FEVT_PAUSE ,
  GF_FEVT_RESUME , GF_FEVT_SOURCE_SEEK , GF_FEVT_SOURCE_SWITCH , GF_FEVT_SEGMENT_SIZE ,
  GF_FEVT_ATTACH_SCENE , GF_FEVT_RESET_SCENE , GF_FEVT_QUALITY_SWITCH , GF_FEVT_VISIBILITY_HINT ,
  GF_FEVT_INFO_UPDATE , GF_FEVT_BUFFER_REQ , GF_FEVT_CAPS_CHANGE , GF_FEVT_CONNECT_FAIL ,
  GF_FEVT_USER , GF_FEVT_PLAY_HINT , GF_FEVT_FILE_DELETE , GF_FEVT_FRAGMENT_SIZE ,
  GF_FEVT_ENCODE_HINTS , GF_FEVT_NTP_REF
}
 

Functions

const char * gf_filter_event_name (GF_FEventType type)
 

Detailed Description

PIDs may receive commands and may emit messages using an event system.

Events may flow downwards (towards the source), in which case they are commands, or upwards (towards the sink), in which case they are informative event.

A filter not implementing a process_event will result in the event being forwarded down to all input PIDs or up to all output PIDs.

A filter may decide to cancel an event, in which case the event is no longer forwarded down/up the chain.

GF_FEVT_PLAY, GF_FEVT_STOP and GF_FEVT_SOURCE_SEEK events will trigger a reset of PID buffers.

A GF_FEVT_PLAY event on a PID already playing is discarded.

A GF_FEVT_STOP event on a PID already stopped is discarded.

GF_FEVT_PLAY and GF_FEVT_SET_SPEED events will trigger larger (abs(speed)>1) or smaller (abs(speed)<1) PID buffer limit in blocking mode.

GF_FEVT_STOP and GF_FEVT_SOURCE_SEEK events are filtered to reset the PID buffers.

The following events may be used globally on a filter, e.g. without a PID associated to the event:

GF_FEVT_FILE_DELETE: used for source and sinks, indicata a file deletion

GF_FEVT_SOURCE_SWITCH: used for source filters only, indicate URL switching

GF_FEVT_QUALITY_SWITCH: globally change quality of of the filters for all pids (typically used in scalable contexts)

GF_FEVT_USER:

The filter session does not maintain a notion of paused or resume streams, it is up to the consummer to stop processing the data wgile paused. The GF_FEVT_PAUSE and GF_FEVT_RESUME events are only used to trigger pause and resume on interactive channels such as an RTSP session, i.e. to tell the remote peer to stop and resume.


Data Structure Documentation

◆ GF_FEVT_Base

struct GF_FEVT_Base

Base type of events. All events start with the fields defined in FILTER_EVENT_BASE

◆ GF_FEVT_Play

struct GF_FEVT_Play

Event structure for GF_FEVT_PLAY, GF_FEVT_SET_SPEED, GF_FEVT_PLAY_HINT, GF_FEVT_STOP

Data Fields
FILTER_EVENT_BASE Double start_range

GF_FEVT_PLAY only, play range in sec - if range is <0, it means end of file (eg [2, -1] with speed>0 means 2 +oo)

Double end_range

GF_FEVT_PLAY only, send range in sec - if range is less than start, ignored

Double speed

params for GF_FEVT_PLAY and GF_FEVT_SET_SPEED

u32 from_pck

GF_FEVT_PLAY only, indicates playback should start from given packet number - used by dasher and GHI when reloading sources

u8 hw_buffer_reset

GF_FEVT_PLAY only, set when PLAY event is sent upstream to audio out, indicates HW buffer reset

u8 initial_broadcast_play

1: indicates this is the first PLAY on an element inserted from broadcast/live (GF_FEVT_PLAY only) 2: indicates this is a PLAY preceeding a STOP or a STOP for a PID being disconnected (GF_FEVT_PLAY and GF_FEVT_STOP)

u8 timestamp_based

params for GF_FEVT_PLAY only 0: range is in media time 1: range is in timesatmps 2: range is in media time but timestamps should not be shifted (hybrid dash only for now)

u8 full_file_only

GF_FEVT_PLAY only, indicates the consumer only cares for the full file, not packets

u8 forced_dash_segment_switch

for GF_FEVT_PLAY: indicates any current download should be aborted for GF_FEVT_PLAY_HINT if upstream event: indicates a HAS segment switch has occured (used by tileagg to flush reassembly buffers) for GF_FEVT_STOP: indicates the source filter has already received stop/play events and cancel event just before source

u8 drop_non_ref

GF_FEVT_PLAY only, indicates non ref frames should be drawn for faster processing

u8 no_byterange_forward

GF_FEVT_PLAY only, indicates that a demuxer must not forward this event as a source seek because seek has already been done (typically this play request is a segment play and byte range access within the file has already been performed by DASH client)

u32 to_pck

GF_FEVT_PLAY only, indicates playback should stop from given packet number - used by GHI when loading sources

u32 orig_delay

GF_FEVT_PLAY only, indicates orginal delay applied to dts - used by GHI when loading sources

u64 hint_first_dts

GF_FEVT_PLAY only, hint DTS of first sample at ot just after start offset, in media timescale

u64 hint_start_offset

GF_FEVT_PLAY only, start offset in source - used by GHI when loading sources

u64 hint_end_offset

GF_FEVT_PLAY only, end offset in source - used by GHI when loading sources

◆ GF_FEVT_SourceSeek

struct GF_FEVT_SourceSeek

Event structure for GF_FEVT_SOURCE_SEEK and GF_FEVT_SOURCE_SWITCH

Data Fields
FILTER_EVENT_BASE u64 start_offset

start offset in source

u64 end_offset

end offset in source

const char * source_switch

GF_FEVT_SOURCE_SWITCH only, new path to switch to

u8 is_init_segment

GF_FEVT_SOURCE_SWITCH only, indicates source is a DASH init segment and should be kept in memory cache

u8 skip_cache_expiration

GF_FEVT_SOURCE_SWITCH only, ignore cache expiration directive for HTTP

u32 hint_block_size

GF_FEVT_SOURCE_SEEK only, hint block size for source, might not be respected

◆ GF_FEVT_SegmentSize

struct GF_FEVT_SegmentSize

Event structure for GF_FEVT_SEGMENT_SIZE

Data Fields
FILTER_EVENT_BASE const char * seg_url

URL of segment this info is for, or NULL if single file

u64 media_range_start

media start range in segment file

u64 media_range_end

media end range in segment file

u64 idx_range_start

index start range in segment file

u64 idx_range_end

index end range in segment file

u8 is_init

global sidx is signaled using is_init=1 and range in idx range

u8 is_shift

if global sidx, indicates if this is is an insertion and that byte range previously received should be shifted

◆ GF_FEVT_FragmentSize

struct GF_FEVT_FragmentSize

Event structure for GF_FEVT_FRAGMENT_SIZE

+ Collaboration diagram for GF_FEVT_FragmentSize:
Data Fields
FILTER_EVENT_BASE Bool is_last

set to TRUE if last fragment in segment

u64 offset

media start range in segment file

u64 size

media end range in segment file

GF_Fraction64 duration

media duration of fragment

Bool independent

fragment contains an IDR

◆ GF_FEVT_AttachScene

struct GF_FEVT_AttachScene

Event structure for GF_FEVT_ATTACH_SCENE and GF_FEVT_RESET_SCENE For GF_FEVT_RESET_SCENE, THIS IS A DIRECT FILTER CALL NOT THREADSAFE, filters processing this event SHALL run on the main thread

Data Fields
FILTER_EVENT_BASE void * object_manager

Pointer to a GF_ObjectManager structure for this PID

void * node

Pointer to a GF_Node structure for this PID if node decoder pid

◆ GF_FEVT_QualitySwitch

struct GF_FEVT_QualitySwitch

Event structure for GF_FEVT_QUALITY_SWITCH

Data Fields
FILTER_EVENT_BASE Bool up

switch quality up or down

u32 dependent_group_index

0: current group, otherwise index of the depending_on group

s32 q_idx

index of the quality to switch, as indicated in "has:qualities" property. If < 0, sets to automatic quality switching

u32 set_tile_mode_plus_one

1+tile mode adaptation (does not change other selections)

u32 quality_degradation

quality degradation hint, between 0 (full quality) and 100 (lowest quality, stream not currently rendered)

◆ GF_FEVT_Event

struct GF_FEVT_Event

Event structure for GF_FEVT_USER

+ Collaboration diagram for GF_FEVT_Event:
Data Fields
FILTER_EVENT_BASE GF_Event event

GF_Event structure

◆ GF_FEVT_FileDelete

struct GF_FEVT_FileDelete

Event structure for GF_FEVT_FILE_DELETE

Data Fields
FILTER_EVENT_BASE const char * url

URL to delete, or "__gpac_self__" when asking source filter to delete file

◆ GF_FEVT_VisibilityHint

struct GF_FEVT_VisibilityHint

Event structure for GF_FEVT_VISIBILITY_HINT

Data Fields
FILTER_EVENT_BASE u32 min_x

gives minimun and maximum coordinates of the visible rectangle associated with channels. min_x may be greater than max_x in case of 360 videos

FILTER_EVENT_BASE u32 max_x
FILTER_EVENT_BASE u32 min_y
FILTER_EVENT_BASE u32 max_y
Bool is_gaze

if set, only min_x, min_y are used and indicate the gaze direction in pixels in the visual with/height frame (0,0) being top-left

◆ GF_FEVT_BufferRequirement

struct GF_FEVT_BufferRequirement

Event structure for GF_FEVT_BUFFER_REQ

Data Fields
FILTER_EVENT_BASE u32 max_buffer_us

indicates the max buffer to set on PID - the buffer is only activated on PIDs connected to decoders

u32 max_playout_us

indicates the max playout buffer to set on PID (buffer level triggering playback)

Note
This is not used internally by the blocking mechanisms, but may be needed by other filters to take decisions
u32 min_playout_us

indicates the min playout buffer to set on PID (buffer level triggering rebuffering)

Note
This is not used internally by the blocking mechanisms, but may be needed by other filters to take decisions
Bool pid_only

if set, only the PID target of the event will have the buffer req set; otherwise, the buffer requirement event is passed down the chain until a raw media PID is found or a decoder is found. Used for muxers

◆ GF_FEVT_EncodeHints

struct GF_FEVT_EncodeHints

Event structure for GF_FEVT_ENCODE_HINT

+ Collaboration diagram for GF_FEVT_EncodeHints:
Data Fields
FILTER_EVENT_BASE GF_Fraction intra_period

duration of intra (IDR, closed GOP) as expected by the dasher

Bool gen_dsi_only

if TRUE codec should only generate DSI (possibly no input frame, and all output packets will be discarded)

◆ GF_FEVT_NTPRef

struct GF_FEVT_NTPRef

Event structure for GF_FEVT_NTP_REF

Data Fields
FILTER_EVENT_BASE u64 ntp

64 bit NTP timestamp

◆ __gf_filter_event

union __gf_filter_event

Filter Event object

+ Collaboration diagram for GF_FilterEvent:
Data Fields
GF_FEVT_Base base
GF_FEVT_Play play
GF_FEVT_SourceSeek seek
GF_FEVT_AttachScene attach_scene
GF_FEVT_Event user_event
GF_FEVT_QualitySwitch quality_switch
GF_FEVT_VisibilityHint visibility_hint
GF_FEVT_BufferRequirement buffer_req
GF_FEVT_SegmentSize seg_size
GF_FEVT_FragmentSize frag_size
GF_FEVT_FileDelete file_del
GF_FEVT_EncodeHints encode_hints
GF_FEVT_NTPRef ntp

Macro Definition Documentation

◆ FILTER_EVENT_BASE

#define FILTER_EVENT_BASE
Value:
GF_FEventType type; \
GF_FilterPid *on_pid; \
\
GF_FEventType
Definition: filters.h:1662

type: the type of the event

on_pid: PID to which the event is targeted. If NULL the event is targeted at the whole filter

◆ GF_FEVT_INIT

#define GF_FEVT_INIT (   _a,
  _type,
  _on_pid 
)    { memset(&_a, 0, sizeof(GF_FilterEvent)); _a.base.type = _type; _a.base.on_pid = _on_pid; }

Macro helper for event structure initializing

Enumeration Type Documentation

◆ GF_FEventType

Filter event types

Enumerator
GF_FEVT_PLAY 

PID control, usually triggered by sink - see GF_FilterPidPlaybackMode

GF_FEVT_SET_SPEED 

PID speed control, usually triggered by sink - see GF_FilterPidPlaybackMode

GF_FEVT_STOP 

PID control, usually triggered by sink - see GF_FilterPidPlaybackMode

GF_FEVT_PAUSE 

PID pause, usually triggered by sink - see GF_FilterPidPlaybackMode

GF_FEVT_RESUME 

PID resume, usually triggered by sink - see GF_FilterPidPlaybackMode

GF_FEVT_SOURCE_SEEK 

PID byte-seek of source, allows seeking in bytes the source - typically used by demuxer to convert time ranges to byte ranges

GF_FEVT_SOURCE_SWITCH 

PID source switch, allows a source filter to switch its source URL for the same protocol

GF_FEVT_SEGMENT_SIZE 

DASH segment size info, sent down from muxers to manifest generators

GF_FEVT_ATTACH_SCENE 

Scene attach event, sent down from compositor to filters (BIFS/OD/timedtext/any scene-related) to share the scene (resources and node graph)

GF_FEVT_RESET_SCENE 

Scene reset event, sent down from compositor to filters (BIFS/OD/timedtext/any scene-related) to indicate scene reset (resources and node graph). This is a direct filter call, only sent processed by filters running on the main thread

GF_FEVT_QUALITY_SWITCH 

quality switching request event, helps filters decide how to adapt their processing

GF_FEVT_VISIBILITY_HINT 

visibility hint event, helps filters decide how to adapt their processing

GF_FEVT_INFO_UPDATE 

special event type sent to a filter whenever the PID info properties have been modified. No cancel because no forward - cf gf_filter_pid_set_info. A filter returning GF_TRUE on this event will prevent info update notification on the destination filters

GF_FEVT_BUFFER_REQ 

buffer requirement event. This event is NOT sent to filters, it is internaly processed by the filter session. Filters may however send this event to indicate their buffereing preference (real-time sinks mostly)

GF_FEVT_CAPS_CHANGE 

filter session capability change, sent whenever global capabilities (max width, max height, ... ) are changed

GF_FEVT_CONNECT_FAIL 

inidicates the PID could not be connected - the PID passed is an output PID of the filter, no specific event structure is associated

GF_FEVT_USER 

user event, sent from compositor/vout down to filters

GF_FEVT_PLAY_HINT 

PLAY hint event, used to signal if block dispatch is needed or not for the source

GF_FEVT_FILE_DELETE 

file delete event, sent upstream by dasher to notify file deletion, downstream by flist to ask for file deletion. The associated file processing (reading, writing) MUST be done when firing this event

GF_FEVT_FRAGMENT_SIZE 

DASH fragment (cmaf chunk) size info, sent down from muxers to manifest generators

GF_FEVT_ENCODE_HINTS 

Encoder hints

GF_FEVT_NTP_REF 

NTP source clock send by other services (eg from TS to dash using TEMI)

Function Documentation

◆ gf_filter_event_name()

const char* gf_filter_event_name ( GF_FEventType  type)

Gets readable name for event type

Parameters
typetype of the event
Returns
readable name of the event