 |
libgpac
Documentation of the core library of GPAC
|
|
libgpac
Documentation of the core library of GPAC
|
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 |
| struct | GF_FEVT_DASHQualitySelection |
| struct | GF_FEVT_NetworkHint |
| 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; } |
Functions | |
| const char * | gf_filter_event_name (GF_FEventType type) |
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 while 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.
| struct GF_FEVT_Base |
Base type of events. All events start with the fields defined in FILTER_EVENT_BASE
| 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 / GF_FEVT_PLAY_HINT, 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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)
|
| u32 | min_playout_us |
indicates the min playout buffer to set on PID (buffer level triggering rebuffering)
|
| 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 |
| 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) |
| struct GF_FEVT_NTPRef |
Event structure for GF_FEVT_NTP_REF
| Data Fields | ||
|---|---|---|
| FILTER_EVENT_BASE u64 | ntp |
64 bit NTP timestamp |
| struct GF_FEVT_DASHQualitySelection |
Event structure for GF_FEVT_DASH_QUALITY_SELECT
| Data Fields | ||
|---|---|---|
| FILTER_EVENT_BASE u32 | service_id |
service ID as advertised by the source PID carrying the manifest |
| const char * | period_id |
ID of period |
| s32 | as_id |
ID of adaptation set |
| const char * | rep_id |
ID of representation for DASH, URL of variant playlist for HLS |
| GF_QualtitySelectionState | select_type |
selection state |
| struct GF_FEVT_NetworkHint |
Event structure for GF_FEVT_NETWORK_HINT
| Data Fields | ||
|---|---|---|
| FILTER_EVENT_BASE u32 | mtu_size |
MTU size |
| 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 | |
| GF_FEVT_DASHQualitySelection | dash_select | |
| GF_FEVT_NetworkHint | net_hint | |
| #define FILTER_EVENT_BASE |
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
| #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
| enum 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 | indicates 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) |
| GF_FEVT_DASH_QUALITY_SELECT | Event sent by DASH/HLS demux to source to notify a quality change - used for ROUTE/MABR only |
| GF_FEVT_NETWORK_HINT | Hint for network transmission event |
| const char* gf_filter_event_name | ( | GF_FEventType | type | ) |
Gets readable name for event type
| type | type of the event |
1.9.1