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
 

Typedefs

typedef struct _mediaobj GF_MediaObject
 

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_MediaObjectgf_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)
 
void gf_mo_get_nb_views (GF_MediaObject *mo, u32 *nb_views)
 
void gf_mo_get_nb_layers (GF_MediaObject *mo, u32 *nb_layers)
 
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_MediaObjectgf_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_SceneGraphgf_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_Node * gf_mo_event_target_enum_node (GF_MediaObject *mo, u32 *i)
 
GF_Node * gf_event_target_get_node (GF_DOMEventTarget *target)
 

Detailed Description

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


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

Typedef Documentation

◆ GF_MediaObject

typedef struct _mediaobj GF_MediaObject

Media Object

opaque handler for all natural media objects (audio, video, image) so that compositor and systems engine are not too tied up. NOTE: the media object location relies on the node parent graph (this is to deal with namespaces in OD framework) therefore it is the task of the media management app to setup clear links between the scene graph and its resources (but this is not mandatory, cf URLs in VRML )

Enumeration Type Documentation

◆ GF_MOFetchMode

frame fetch mode for media object

◆ GF_MOUserFlags

media object user flags

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

◆ 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

◆ 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

◆ 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

◆ 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

◆ gf_mo_pause()

void gf_mo_pause ( GF_MediaObject mo)

pauses a media object

Parameters
mothe target media object

◆ gf_mo_resume()

void gf_mo_resume ( GF_MediaObject mo)

resumes a media object

Parameters
mothe target media object

◆ gf_mo_set_speed()

void gf_mo_set_speed ( GF_MediaObject mo,
Fixed  speed 
)
    Note on mediaControl: mediaControl is the media management app responsability, 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 responsability of the rendering app

Parameters
mothe target media object
speedthe playback speed to set

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ gf_mo_get_nb_layers()

void gf_mo_get_nb_layers ( GF_MediaObject mo,
u32 nb_layers 
)

gets number of layers for 2D scalable video object

Parameters
mothe target media object
nb_layersset to the number of layers in the object

◆ 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

◆ 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

◆ 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)

◆ 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)

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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)

◆ 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)

◆ 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)

◆ gf_mo_del()

void gf_mo_del ( GF_MediaObject mo)

destroys a media object

Parameters
mothe target media object

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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