libgpac
Documentation of the core library of GPAC
MediaObject

Interface between compositor and decoding engine for media data access. More...

+ Collaboration diagram for MediaObject:

Data Structures

struct  GF_MediaObjectVRInfo
 

Enumerations

enum  GF_MOFetchMode { GF_MO_FETCH = 0 , GF_MO_FETCH_RESYNC , GF_MO_FETCH_PAUSED }
 
enum  GF_MOUserFlags { GF_MO_DISPLAY_REMOVE = (1<<1) , GF_MO_IN_RESYNC = (1<<2) }
 

Functions

GF_MediaObject * gf_mo_register (GF_Node *node, MFURL *url, Bool lock_timelines, Bool force_new_res)
 
void gf_mo_unregister (GF_Node *node, GF_MediaObject *mo)
 
void gf_mo_play (GF_MediaObject *mo, Double clipBegin, Double clipEnd, Bool can_loop)
 
void gf_mo_stop (GF_MediaObject **mo)
 
void gf_mo_restart (GF_MediaObject *mo)
 
void gf_mo_pause (GF_MediaObject *mo)
 
void gf_mo_resume (GF_MediaObject *mo)
 
void gf_mo_set_speed (GF_MediaObject *mo, Fixed speed)
 
Fixed gf_mo_get_speed (GF_MediaObject *mo, Fixed in_speed)
 
Bool gf_mo_get_loop (GF_MediaObject *mo, Bool in_loop)
 
Double gf_mo_get_duration (GF_MediaObject *mo)
 
Bool gf_mo_should_deactivate (GF_MediaObject *mo)
 
Bool gf_mo_url_changed (GF_MediaObject *mo, MFURL *url)
 
u32 gf_mo_get_min_frame_dur (GF_MediaObject *mo)
 
u32 gf_mo_map_timestamp_to_sys_clock (GF_MediaObject *mo, u32 ts)
 
Bool gf_mo_is_buffering (GF_MediaObject *mo)
 
u8gf_mo_fetch_data (GF_MediaObject *mo, GF_MOFetchMode resync, u32 upload_time_ms, Bool *eos, u32 *timestamp, u32 *size, s32 *ms_until_pres, s32 *ms_until_next, GF_FilterFrameInterface **outFrame, u32 *planar_size)
 
void gf_mo_release_data (GF_MediaObject *mo, u32 nb_bytes, s32 drop_mode)
 
void gf_mo_get_object_time (GF_MediaObject *mo, u32 *obj_time)
 
Bool gf_mo_is_muted (GF_MediaObject *mo)
 
Bool gf_mo_is_done (GF_MediaObject *mo)
 
void gf_mo_adjust_clock (GF_MediaObject *mo, s32 ms_drift)
 
Bool gf_mo_is_started (GF_MediaObject *mo)
 
Bool gf_mo_get_visual_info (GF_MediaObject *mo, u32 *width, u32 *height, u32 *stride, u32 *pixel_ar, u32 *pixelFormat, Bool *is_flipped)
 
Bool gf_mo_get_visual_info_ex (GF_MediaObject *mo, u32 *width, u32 *height, u32 *stride, u32 *pixel_ar, u32 *pixelFormat, Bool *is_flipped, Bool for_texture)
 
void gf_mo_get_nb_views (GF_MediaObject *mo, u32 *nb_views)
 
Bool gf_mo_get_audio_info (GF_MediaObject *mo, u32 *sample_rate, u32 *afmt, u32 *num_channels, u64 *channel_config, Bool *forced_layout)
 
Fixed gf_mo_get_current_speed (GF_MediaObject *mo)
 
u32 gf_mo_has_audio (GF_MediaObject *mo)
 
void gf_mo_set_flag (GF_MediaObject *mo, GF_MOUserFlags flag, Bool set_on)
 
GF_MediaObject * gf_mo_load_xlink_resource (GF_Node *node, Bool primary_resource, Double clipBegin, Double clipEnd)
 
void gf_mo_unload_xlink_resource (GF_Node *node, GF_MediaObject *mo)
 
GF_SceneGraph * gf_mo_get_scenegraph (GF_MediaObject *mo)
 
Bool gf_mo_get_srd_info (GF_MediaObject *mo, GF_MediaObjectVRInfo *vr_info)
 
void gf_mo_hint_quality_degradation (GF_MediaObject *mo, u32 quality_degradation)
 
void gf_mo_hint_visible_rect (GF_MediaObject *mo, u32 min_x, u32 max_x, u32 min_y, u32 max_y)
 
void gf_mo_hint_gaze (GF_MediaObject *mo, u32 gaze_x, u32 gaze_y)
 
void gf_mo_del (GF_MediaObject *mo)
 
GF_DOMEventTargetgf_mo_event_target_add_node (GF_MediaObject *mo, GF_Node *node)
 
GF_Err gf_mo_event_target_remove_by_node (GF_MediaObject *mo, GF_Node *node)
 
u32 gf_mo_event_target_count (GF_MediaObject *mo)
 
GF_Err gf_mo_event_target_remove_by_index (GF_MediaObject *mo, u32 index)
 
GF_DOMEventTargetgf_mo_event_target_get (GF_MediaObject *mo, u32 index)
 
void gf_mo_event_target_reset (GF_MediaObject *mo)
 
s32 gf_mo_event_target_find_by_node (GF_MediaObject *mo, GF_Node *node)
 
GF_Nodegf_mo_event_target_enum_node (GF_MediaObject *mo, u32 *i)
 
GF_Nodegf_event_target_get_node (GF_DOMEventTarget *target)
 

Detailed Description

This section documents the API between the compositor of GPAC and the decoding engine (filter pids)


Data Structure Documentation

◆ GF_MediaObjectVRInfo

struct GF_MediaObjectVRInfo

VR and SRD (Spatial Relationship Description) information of media object

Data Fields
u32 vr_type
s32 srd_x
s32 srd_y
s32 srd_w
s32 srd_h
s32 srd_min_x
s32 srd_min_y
s32 srd_max_x
s32 srd_max_y
u32 scene_width
u32 scene_height
Bool has_full_coverage
Bool is_tiled_srd

Enumeration Type Documentation

◆ GF_MOFetchMode

frame fetch mode for media object

Enumerator
GF_MO_FETCH 
GF_MO_FETCH_RESYNC 
GF_MO_FETCH_PAUSED 

◆ GF_MOUserFlags

media object user flags

Enumerator
GF_MO_DISPLAY_REMOVE 
GF_MO_IN_RESYNC 

Function Documentation

◆ gf_mo_register()

GF_MediaObject* gf_mo_register ( GF_Node node,
MFURL url,
Bool  lock_timelines,
Bool  force_new_res 
)

locates media object related to the given node - url designes the object to find - returns NULL if URL cannot be handled - note that until the mediaObject.isInit member is true, the media object is not valid (and could actually never be)

Parameters
nodenode querying the URL
urlthe URL to open
lock_timelinesif GF_TRUE, forces media timelines in remote URL to be locked to the node timeline
force_new_resif GF_TRUE, forces loading of a new resource
Returns
new media object or NULL of URL not valid
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_unregister()

void gf_mo_unregister ( GF_Node node,
GF_MediaObject *  mo 
)

unregisters the node from the media object

Parameters
nodenode querying the URL
mothe media object to unregister - can be destroyed during this function call
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_play()

void gf_mo_play ( GF_MediaObject *  mo,
Double  clipBegin,
Double  clipEnd,
Bool  can_loop 
)

opens media object

Parameters
mothe target media object
clipBeginthe playback start time in seconds
clipEndthe playback end time in seconds
can_loopif GF_TRUE, indicates the playback can be looped
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_stop()

void gf_mo_stop ( GF_MediaObject **  mo)

stops media object. Object is set to null if stop triggers a removal. If not removed, video memory is not reset, last frame is kept

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_restart()

void gf_mo_restart ( GF_MediaObject *  mo)

restarts media object - shall be used for all looping media instead of stop/play for mediaControl to restart appropriated objects

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_pause()

void gf_mo_pause ( GF_MediaObject *  mo)

pauses a media object

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_resume()

void gf_mo_resume ( GF_MediaObject *  mo)

resumes a media object

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_set_speed()

void gf_mo_set_speed ( GF_MediaObject *  mo,
Fixed  speed 
)
    Note on mediaControl: mediaControl is the media management app responsibility, therefore

is hidden from the rendering app. Since MediaControl overrides default settings of the node (speed and loop) you must use the gf_mo_get_speed and gf_mo_get_loop in order to know whether the related field applies or not

sets speed of media - speed is not always applied, depending on media control settings.

Note
audio pitching is the responsibility of the rendering app
Parameters
mothe target media object
speedthe playback speed to set
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_speed()

Fixed gf_mo_get_speed ( GF_MediaObject *  mo,
Fixed  in_speed 
)

gets current speed of media

Parameters
mothe target media object
in_speedis the speed of the media as set in the node (MovieTexture, AudioClip and AudioSource)
Returns
the real speed of the media as overloaded by mediaControl if any
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_loop()

Bool gf_mo_get_loop ( GF_MediaObject *  mo,
Bool  in_loop 
)

gets current looping flag of media

Parameters
mothe target media object
in_loopis the looping flag of the media as set in the node (MovieTexture, AudioClip)
Returns
the real loop flag of the media as overloaded by mediaControl if any
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_duration()

Double gf_mo_get_duration ( GF_MediaObject *  mo)

get media object duration

Parameters
mothe target media object
Returns
media object duration
+ Here is the caller graph for this function:

◆ gf_mo_should_deactivate()

Bool gf_mo_should_deactivate ( GF_MediaObject *  mo)

checks if object should be deactivated (stop) or not - this checks object status as well as mediaControl status

Parameters
mothe target media object
Returns
GF_TRUE if should be deactivated
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_url_changed()

Bool gf_mo_url_changed ( GF_MediaObject *  mo,
MFURL url 
)

checks whether the target object is changed - you MUST use this in order to detect url changes

Parameters
mothe target media object
urlURL to compare to object current URL
Returns
GF_TRUE if URL changed
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_min_frame_dur()

u32 gf_mo_get_min_frame_dur ( GF_MediaObject *  mo)

gets minimum frame duration for an object

Parameters
mothe target media object
Returns
min frame duration or 0 if unknown
+ Here is the caller graph for this function:

◆ gf_mo_map_timestamp_to_sys_clock()

u32 gf_mo_map_timestamp_to_sys_clock ( GF_MediaObject *  mo,
u32  ts 
)

map a timestamp to the object clock

Parameters
mothe target media object
tsa timestamp in media object clock base
Returns
the timestamp in system time base
+ Here is the caller graph for this function:

◆ gf_mo_is_buffering()

Bool gf_mo_is_buffering ( GF_MediaObject *  mo)

checks if object is buffering

Parameters
mothe target media object
Returns
GF_TRUE if object is buffering
+ Here is the caller graph for this function:

◆ gf_mo_fetch_data()

u8* gf_mo_fetch_data ( GF_MediaObject *  mo,
GF_MOFetchMode  resync,
u32  upload_time_ms,
Bool eos,
u32 timestamp,
u32 size,
s32 ms_until_pres,
s32 ms_until_next,
GF_FilterFrameInterface **  outFrame,
u32 planar_size 
)

fetches media data

Parameters
mothe target media object
resyncresync mode for fetch operation
upload_time_msaverage time needed to push frame on GPU
eosset to end of stream status of the media
timestampset to the frmae timestamp in object time
sizeset to the frame data size
ms_until_presset to the number of milliseconds until presentation is due
ms_until_nextset to the number of milliseconds until presentation of next frame is due
outFrameset to the associated frame interface object if any
planar_sizeset to the planar size of audio data, or 0
Returns
frame data
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_release_data()

void gf_mo_release_data ( GF_MediaObject *  mo,
u32  nb_bytes,
s32  drop_mode 
)

releases given amount of media data - nb_bytes is used for audio

Parameters
mothe target media object
nb_bytesnumber of audio bytes to remove (ignored for other media types)
drop_modecan take the following values: -1: do not drop 0: do not force drop: the unlocked frame it will be dropped based on object time (typically video) 1: force drop : the unlocked frame will be dropped if all bytes are consumed (typically audio) 2: the frame will be stated as a discraded frame
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_object_time()

void gf_mo_get_object_time ( GF_MediaObject *  mo,
u32 obj_time 
)

gets object clock

Parameters
mothe target media object
obj_timeset to the object current time in milliseconds in object time base
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_is_muted()

Bool gf_mo_is_muted ( GF_MediaObject *  mo)

checks if object is muted. Muted media shouldn't be displayed

Parameters
mothe target media object
Returns
GF_TRUE if muted
+ Here is the caller graph for this function:

◆ gf_mo_is_done()

Bool gf_mo_is_done ( GF_MediaObject *  mo)

checks if a media object is done

Parameters
mothe target media object
Returns
GF_TRUE if end of stream
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_adjust_clock()

void gf_mo_adjust_clock ( GF_MediaObject *  mo,
s32  ms_drift 
)

adjusts clock sync (only audio objects are allowed to use this)

Parameters
mothe target media object
ms_driftdrift in milliseconds between object clock and actual rendering time
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_is_started()

Bool gf_mo_is_started ( GF_MediaObject *  mo)

checks if a media object is started

Parameters
mothe target media object
Returns
GF_TRUE if started
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_visual_info()

Bool gf_mo_get_visual_info ( GF_MediaObject *  mo,
u32 width,
u32 height,
u32 stride,
u32 pixel_ar,
u32 pixelFormat,
Bool is_flipped 
)

gets visual information of a media object

Parameters
mothe target media object
widthset to width in pixels
heightset to height in pixels
strideset to stride in bytes for visual objects with data frame, 0 if unknown
pixel_arset to the pixel aspect ratio as
(PAR_NUM<<16)|PAR_DEN
pixelFormatset to the pixel format of the video
is_flippedset to GF_TRUE if the pixels are vertically flipped (happens when reading back OpenGL textures)
Returns
GF_TRUE if success
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_visual_info_ex()

Bool gf_mo_get_visual_info_ex ( GF_MediaObject *  mo,
u32 width,
u32 height,
u32 stride,
u32 pixel_ar,
u32 pixelFormat,
Bool is_flipped,
Bool  for_texture 
)

gets visual information of a media object

Parameters
mothe target media object
widthset to width in pixels
heightset to height in pixels
strideset to stride in bytes for visual objects with data frame, 0 if unknown
pixel_arset to the pixel aspect ratio as
(PAR_NUM<<16)|PAR_DEN
pixelFormatset to the pixel format of the video
is_flippedset to GF_TRUE if the pixels are vertically flipped (happens when reading back OpenGL textures)
for_textureif true check for texture dimensions otherwise for SRD dimensions
Returns
GF_TRUE if success
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_nb_views()

void gf_mo_get_nb_views ( GF_MediaObject *  mo,
u32 nb_views 
)

gets number of views for 3D video object

Parameters
mothe target media object
nb_viewsset to the number of views in the object, vertically packed
+ Here is the caller graph for this function:

◆ gf_mo_get_audio_info()

Bool gf_mo_get_audio_info ( GF_MediaObject *  mo,
u32 sample_rate,
u32 afmt,
u32 num_channels,
u64 channel_config,
Bool forced_layout 
)

gets visual information of a media object

Parameters
mothe target media object
sample_rateset to the sampling frequency of the object
afmtset to the decoded PCM audio format
num_channelsset to the number of channels
channel_configset to the channel configuration
forced_layoutset to GF_TRUE if the channel layout is forced (prevents recomputing the layout for mono/stereo setups)
Returns
GF_TRUE if success
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_current_speed()

Fixed gf_mo_get_current_speed ( GF_MediaObject *  mo)

gets current playback speed of a media object

Parameters
mothe target media object
Returns
the playback speed
+ Here is the caller graph for this function:

◆ gf_mo_has_audio()

u32 gf_mo_has_audio ( GF_MediaObject *  mo)

checks if the service associated withthis object has an audio stream

Parameters
mothe target media object
Returns
0 if no audio is associated, 1 if there is an audio object associated, 2 if the service is not yet ready (not connected)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_set_flag()

void gf_mo_set_flag ( GF_MediaObject *  mo,
GF_MOUserFlags  flag,
Bool  set_on 
)

sets flags on a media object

Parameters
mothe target media object
flagthe flag(s) to adjust
set_onif GF_TRUE, set the flag(s), otherwise removes the flag(s)
+ Here is the caller graph for this function:

◆ gf_mo_load_xlink_resource()

GF_MediaObject* gf_mo_load_xlink_resource ( GF_Node node,
Bool  primary_resource,
Double  clipBegin,
Double  clipEnd 
)

loads a new resource as indicated in the xlink:href attribute of the node. If this points to a fragment of the current document, returns NULL. This will automatically trigger a play request on the resource

Parameters
nodenode with xlink:href attribute to a media resource
primary_resourceindicates if this is a primary resource (foreign object in SVG)
clipBeginthe playback start time in seconds
clipEndthe playback end time in seconds
Returns
the media object for this resource
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_unload_xlink_resource()

void gf_mo_unload_xlink_resource ( GF_Node node,
GF_MediaObject *  mo 
)

unloads a media object associated with a given node through xlink:href

Parameters
nodenode with xlink:href attribute to the media resource
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_get_scenegraph()

GF_SceneGraph* gf_mo_get_scenegraph ( GF_MediaObject *  mo)

gets the scene graph associated with a scene/document object

Parameters
mothe target media object
Returns
the scene graph, or NULL if wrong type or not loaded
+ Here is the caller graph for this function:

◆ gf_mo_get_srd_info()

Bool gf_mo_get_srd_info ( GF_MediaObject *  mo,
GF_MediaObjectVRInfo vr_info 
)

gets SRD and VR info for a media object. Returns FALSE if no VR and no SRD info

Parameters
mothe target media object
vr_infoset to the VR and SRD info of the media object
Returns
GF_TRUE if SRD info present
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_hint_quality_degradation()

void gf_mo_hint_quality_degradation ( GF_MediaObject *  mo,
u32  quality_degradation 
)

sets quality degradation hint for a media object

Parameters
mothe target media object
quality_degradationquality hint value between 0 (max quality) and 100 (worst quality)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_hint_visible_rect()

void gf_mo_hint_visible_rect ( GF_MediaObject *  mo,
u32  min_x,
u32  max_x,
u32  min_y,
u32  max_y 
)

sets visible rectangle for a media object, only used in 360 videos for now

Parameters
mothe target media object
min_xminimum horizontal coordinate of visible region, in pixel in the media frame (0 being left column)
max_xmaximum horizontal coordinate of visible region, in pixel in the media frame (width being right column)
min_yminimum vertical coordinate of visible region, in pixel in the media frame (0 being top row)
max_ymaximum vertical coordinate of visible region, in pixel in the media frame (height being bottom row)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_hint_gaze()

void gf_mo_hint_gaze ( GF_MediaObject *  mo,
u32  gaze_x,
u32  gaze_y 
)

sets gaze position in a media object, only used in 360 videos for now

Parameters
mothe target media object
gaze_xminimum horizontal coordinate of visible region, in pixel in the media frame (0 being left column, width being right column)
gaze_ymaximum horizontal coordinate of visible region, in pixel in the media frame (0 being top row, bottom row)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_del()

void gf_mo_del ( GF_MediaObject *  mo)

destroys a media object

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_add_node()

GF_DOMEventTarget* gf_mo_event_target_add_node ( GF_MediaObject *  mo,
GF_Node node 
)

adds event target node to a media object

Parameters
mothe target media object
nodethe event target node
Returns
a DOM event target interface object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_remove_by_node()

GF_Err gf_mo_event_target_remove_by_node ( GF_MediaObject *  mo,
GF_Node node 
)

removes event target node from a media object

Parameters
mothe target media object
nodethe event target node
Returns
error if any
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_count()

u32 gf_mo_event_target_count ( GF_MediaObject *  mo)

counts number of event targets associated with a media object

Parameters
mothe target media object
Returns
number of event targets
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_remove_by_index()

GF_Err gf_mo_event_target_remove_by_index ( GF_MediaObject *  mo,
u32  index 
)

removes event target node from a media object by index

Parameters
mothe target media object
index0-based index of the event target to remove
Returns
error if any
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_get()

GF_DOMEventTarget* gf_mo_event_target_get ( GF_MediaObject *  mo,
u32  index 
)

gets event target node of a media object by index

Parameters
mothe target media object
index0-based index of the event target to get
Returns
a DOM event target interface object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_reset()

void gf_mo_event_target_reset ( GF_MediaObject *  mo)

resets all event targets of a media object

Parameters
mothe target media object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_find_by_node()

s32 gf_mo_event_target_find_by_node ( GF_MediaObject *  mo,
GF_Node node 
)

finds an even target interface of a media object associated to a given node

Parameters
mothe target media object
nodethe node associated with the event target
Returns
the index of the event target interface object
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_mo_event_target_enum_node()

GF_Node* gf_mo_event_target_enum_node ( GF_MediaObject *  mo,
u32 i 
)

enumerates event target nodes associated with a media object

Parameters
mothe target media object
icurrent index to query, incremented upon function return
Returns
an event target node
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ gf_event_target_get_node()

GF_Node* gf_event_target_get_node ( GF_DOMEventTarget target)

gets the event target node of an event target interface

Parameters
targetthe target event target interface
Returns
the associated node, NULL if error
+ Here is the caller graph for this function: