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

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)

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_DOMEventTarget *	gf_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_DOMEventTarget *	gf_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 (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

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

enum GF_MOFetchMode

frame fetch mode for media object

◆ GF_MOUserFlags

enum 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

node	node querying the URL
url	the URL to open
lock_timelines	if GF_TRUE, forces media timelines in remote URL to be locked to the node timeline
force_new_res	if 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

node	node querying the URL
mo	the 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

mo	the target media object
clipBegin	the playback start time in seconds
clipEnd	the playback end time in seconds
can_loop	if 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

mo	the 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

mo	the target media object

◆ gf_mo_pause()

void gf_mo_pause ( GF_MediaObject * mo )

pauses a media object

Parameters

mo	the target media object

◆ gf_mo_resume()

void gf_mo_resume ( GF_MediaObject * mo )

resumes a media object

Parameters

mo	the 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 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

mo	the target media object
speed	the 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

mo	the target media object
in_speed	is 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

mo	the target media object
in_loop	is 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

mo	the 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

mo	the 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

mo	the target media object
url	URL 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

mo	the 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

mo	the target media object
ts	a 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

mo	the 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

mo	the target media object
resync	resync mode for fetch operation
upload_time_ms	average time needed to push frame on GPU
eos	set to end of stream status of the media
timestamp	set to the frmae timestamp in object time
size	set to the frame data size
ms_until_pres	set to the number of milliseconds until presentation is due
ms_until_next	set to the number of milliseconds until presentation of next frame is due
outFrame	set to the associated frame interface object if any
planar_size	set 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

mo	the target media object
nb_bytes	number of audio bytes to remove (ignored for other media types)
drop_mode	can 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

mo	the target media object
obj_time	set 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

mo	the 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

mo	the 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

mo	the target media object
ms_drift	drift 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

mo	the 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

mo	the target media object
width	set to width in pixels
height	set to height in pixels
stride	set to stride in bytes for visual objects with data frame, 0 if unknown
pixel_ar	set to the pixel aspect ratio as (PAR_NUM<<16)\|PAR_DEN
pixelFormat	set to the pixel format of the video
is_flipped	set to GF_TRUE if the pixels are vertically flipped (happens when reading back OpenGL textures)

Returns: GF_TRUE if success

◆ 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

mo	the target media object
width	set to width in pixels
height	set to height in pixels
stride	set to stride in bytes for visual objects with data frame, 0 if unknown
pixel_ar	set to the pixel aspect ratio as (PAR_NUM<<16)\|PAR_DEN
pixelFormat	set to the pixel format of the video
is_flipped	set to GF_TRUE if the pixels are vertically flipped (happens when reading back OpenGL textures)
for_texture	if true check for texture dimensions otherwise for SRD dimensions

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

mo	the target media object
nb_views	set to the number of views in the object, vertically packed

◆ 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

mo	the target media object
sample_rate	set to the sampling frequency of the object
afmt	set to the decoded PCM audio format
num_channels	set to the number of channels
channel_config	set to the channel configuration
forced_layout	set 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

mo	the 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

mo	the 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

mo	the target media object
flag	the flag(s) to adjust
set_on	if 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

node	node with xlink:href attribute to a media resource
primary_resource	indicates if this is a primary resource (foreign object in SVG)
clipBegin	the playback start time in seconds
clipEnd	the 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

node	node with xlink:href attribute to the media resource
mo	the 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

mo	the 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

mo	the target media object
vr_info	set 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

mo	the target media object
quality_degradation	quality 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

mo	the target media object
min_x	minimum horizontal coordinate of visible region, in pixel in the media frame (0 being left column)
max_x	maximum horizontal coordinate of visible region, in pixel in the media frame (width being right column)
min_y	minimum vertical coordinate of visible region, in pixel in the media frame (0 being top row)
max_y	maximum 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

mo	the target media object
gaze_x	minimum horizontal coordinate of visible region, in pixel in the media frame (0 being left column, width being right column)
gaze_y	maximum 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

mo	the 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

mo	the target media object
node	the 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

mo	the target media object
node	the 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

mo	the 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

mo	the target media object
index	0-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

mo	the target media object
index	0-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

mo	the 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

mo	the target media object
node	the 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

mo	the target media object
i	current 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

target the target event target interface

Returns: the associated node, NULL if error

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ GF_MediaObjectVRInfo

Typedef Documentation

◆ GF_MediaObject

Enumeration Type Documentation

◆ GF_MOFetchMode

◆ GF_MOUserFlags

Function Documentation

◆ gf_mo_register()

◆ gf_mo_unregister()

◆ gf_mo_play()

◆ gf_mo_stop()

◆ gf_mo_restart()

◆ gf_mo_pause()

◆ gf_mo_resume()

◆ gf_mo_set_speed()

◆ gf_mo_get_speed()

◆ gf_mo_get_loop()

◆ gf_mo_get_duration()

◆ gf_mo_should_deactivate()

◆ gf_mo_url_changed()

◆ gf_mo_get_min_frame_dur()

◆ gf_mo_map_timestamp_to_sys_clock()

◆ gf_mo_is_buffering()

◆ gf_mo_fetch_data()

◆ gf_mo_release_data()

◆ gf_mo_get_object_time()

◆ gf_mo_is_muted()

◆ gf_mo_is_done()

◆ gf_mo_adjust_clock()

◆ gf_mo_is_started()

◆ gf_mo_get_visual_info()

◆ gf_mo_get_visual_info_ex()

◆ gf_mo_get_nb_views()

◆ gf_mo_get_audio_info()

◆ gf_mo_get_current_speed()

◆ gf_mo_has_audio()

◆ gf_mo_set_flag()

◆ gf_mo_load_xlink_resource()

◆ gf_mo_unload_xlink_resource()

◆ gf_mo_get_scenegraph()

◆ gf_mo_get_srd_info()

◆ gf_mo_hint_quality_degradation()

◆ gf_mo_hint_visible_rect()

◆ gf_mo_hint_gaze()

◆ gf_mo_del()

◆ gf_mo_event_target_add_node()

◆ gf_mo_event_target_remove_by_node()

◆ gf_mo_event_target_count()

◆ gf_mo_event_target_remove_by_index()

◆ gf_mo_event_target_get()

◆ gf_mo_event_target_reset()

◆ gf_mo_event_target_find_by_node()

◆ gf_mo_event_target_enum_node()

◆ gf_event_target_get_node()