libgpac
Documentation of the core library of GPAC
Terminal

GPAC media player APIs. More...

+ Collaboration diagram for Terminal:

Functions

GF_Terminalgf_term_new (GF_User *user)
 
GF_Err gf_term_del (GF_Terminal *term)
 
void gf_term_connect (GF_Terminal *term, const char *URL)
 
void gf_term_disconnect (GF_Terminal *term)
 
void gf_term_navigate_to (GF_Terminal *term, const char *toURL)
 
u32 gf_term_play_from_time (GF_Terminal *term, u64 from_time, u32 pause_at_first_frame)
 
void gf_term_connect_from_time (GF_Terminal *term, const char *URL, u64 time_in_ms, u32 pause_at_first_frame)
 
void gf_term_connect_with_path (GF_Terminal *term, const char *URL, const char *parent_URL)
 
Double gf_term_get_framerate (GF_Terminal *term, Bool absoluteFPS)
 
u32 gf_term_get_time_in_ms (GF_Terminal *term)
 
u32 gf_term_get_elapsed_time_in_ms (GF_Terminal *term)
 
const char * gf_term_get_url (GF_Terminal *term)
 
GF_Err gf_term_get_viewpoint (GF_Terminal *term, u32 viewpoint_idx, const char **outName, Bool *is_bound)
 
GF_Err gf_term_set_viewpoint (GF_Terminal *term, u32 viewpoint_idx, const char *viewpoint_name)
 
GF_Err gf_term_add_object (GF_Terminal *term, const char *url, Bool auto_play)
 
GF_Err gf_term_set_option (GF_Terminal *term, u32 opt_type, u32 opt_value)
 
u32 gf_term_get_option (GF_Terminal *term, u32 opt_type)
 
Bool gf_term_is_supported_url (GF_Terminal *term, const char *URL, Bool use_parent_url, Bool no_mime_check)
 
u32 gf_term_get_current_service_id (GF_Terminal *term)
 
Double gf_term_get_simulation_frame_rate (GF_Terminal *term, u32 *nb_frames_drawn)
 
GF_Err gf_term_get_visual_output_size (GF_Terminal *term, u32 *width, u32 *height)
 
GF_Err gf_term_set_speed (GF_Terminal *term, Fixed speed)
 
GF_Err gf_term_scene_update (GF_Terminal *term, char *type, char *com)
 
GF_Err gf_term_set_size (GF_Terminal *term, u32 NewWidth, u32 NewHeight)
 
const char * gf_term_get_text_selection (GF_Terminal *term, Bool probe_only)
 
GF_Err gf_term_paste_text (GF_Terminal *term, const char *txt, Bool probe_only)
 
Bool gf_term_process_step (GF_Terminal *term)
 
Bool gf_term_user_event (GF_Terminal *term, GF_Event *event)
 
Bool gf_term_send_event (GF_Terminal *term, GF_Event *evt)
 
GF_Err gf_term_get_screen_buffer (GF_Terminal *term, GF_VideoSurface *framebuffer)
 
GF_Err gf_term_get_offscreen_buffer (GF_Terminal *term, GF_VideoSurface *framebuffer, u32 view_idx, GF_CompositorGrabMode depth_buffer_type)
 
GF_Err gf_term_release_screen_buffer (GF_Terminal *term, GF_VideoSurface *framebuffer)
 
void gf_term_switch_quality (GF_Terminal *term, Bool up)
 
Bool gf_term_is_type_supported (GF_Terminal *term, const char *mime)
 

Detailed Description

This section documents the user-level API of the GPAC media player.

Function Documentation

◆ gf_term_new()

GF_Terminal* gf_term_new ( GF_User *  user)

creates a new terminal for a userApp callback

Parameters
usera user description
Returns
a new terminal

◆ gf_term_del()

GF_Err gf_term_del ( GF_Terminal term)

deletes a terminal - stop is done automatically

Parameters
termthe target terminal
Returns
error if any (GF_IO_ERR if client couldn't be shutdown normally)

◆ gf_term_connect()

void gf_term_connect ( GF_Terminal term,
const char *  URL 
)

connects to a URL - connection OK or error is acknowledged via the user callback

Parameters
termthe target terminal
URLthe target URL

◆ gf_term_disconnect()

void gf_term_disconnect ( GF_Terminal term)

disconnects the current url

Parameters
termthe target terminal

◆ gf_term_navigate_to()

void gf_term_navigate_to ( GF_Terminal term,
const char *  toURL 
)

navigates to a given destination or shutdown/restart the current one if any. This is the only safe way of restarting/jumping a presentation from inside the EventProc where doing a disconnect/connect could deadlock if toURL is NULL, uses the current URL

Parameters
termthe target terminal
toURLthe new target URL

◆ gf_term_play_from_time()

u32 gf_term_play_from_time ( GF_Terminal term,
u64  from_time,
u32  pause_at_first_frame 
)

restarts url from given time (in ms).

Parameters
termthe target terminal
from_timerestart time in milliseconds
pause_at_first_frameif 1, pauses at the first frame. If 2, pauses at the first frame only if the terminal is in paused state.
Returns
0: service is not connected yet, 1: service has no seeking capabilities, 2: service has been seeked

◆ gf_term_connect_from_time()

void gf_term_connect_from_time ( GF_Terminal term,
const char *  URL,
u64  time_in_ms,
u32  pause_at_first_frame 
)

connects URL and seek right away - only needed when reloading the complete player (avoids waiting for connection and post a seek..)

Parameters
termthe target terminal
URLthe target URL
time_in_msconnect time in milliseconds
pause_at_first_frameif 1, pauses rendering and streaming when starting, if 2 pauses only rendering

◆ gf_term_connect_with_path()

void gf_term_connect_with_path ( GF_Terminal term,
const char *  URL,
const char *  parent_URL 
)

connects a URL but specify a parent path for this URL

Parameters
termthe target terminal
URLthe target URL
parent_URLthe parent URL of the connected service

◆ gf_term_get_framerate()

Double gf_term_get_framerate ( GF_Terminal term,
Bool  absoluteFPS 
)

gets framerate

Parameters
termthe target terminal
absoluteFPSif GF_TRUE, the return value is the absolute framerate, eg NbFrameCount/NbTimeSpent regardless of whether a frame has been drawn or not, which means the FPS returned can be much greater than the target rendering framerate. If GF_FALSE, the return value is the FPS taking into account not drawn frames (eg, less than or equal to compositor FPS)
Returns
current framerate

◆ gf_term_get_time_in_ms()

u32 gf_term_get_time_in_ms ( GF_Terminal term)

gets main scene current time

Parameters
termthe target terminal
Returns
time in milliseconds

◆ gf_term_get_elapsed_time_in_ms()

u32 gf_term_get_elapsed_time_in_ms ( GF_Terminal term)

gets elapsed time since loading of the scene - may be different from scene time when seeking or live content

Parameters
termthe target terminal
Returns
time elapsed in milliseconds

◆ gf_term_get_url()

const char* gf_term_get_url ( GF_Terminal term)

gets current URL

Parameters
termthe target terminal
Returns
the current URL

◆ gf_term_get_viewpoint()

GF_Err gf_term_get_viewpoint ( GF_Terminal term,
u32  viewpoint_idx,
const char **  outName,
Bool is_bound 
)

gets viewpoints/viewports for main scene

Parameters
termthe target terminal
viewpoint_idx1-based index of the viewport to query
outNameset to the name of the viewport
is_boundset to GF_TRUE of that viewport is bound
Returns
error if any, GF_EOS if index is greater than number of viewpoints

◆ gf_term_set_viewpoint()

GF_Err gf_term_set_viewpoint ( GF_Terminal term,
u32  viewpoint_idx,
const char *  viewpoint_name 
)

sets active viewpoints/viewports for main scene given its name

Note
if only one viewpoint is present in the scene
Parameters
termthe target terminal
viewpoint_idx1-based index of the viewport to set or 0 to set by viewpoint name
viewpoint_namename of the viewport
Returns
error if any, GF_EOS if index is greater than number of viewpoints

◆ gf_term_add_object()

GF_Err gf_term_add_object ( GF_Terminal term,
const char *  url,
Bool  auto_play 
)

adds an object to the scene - only possible if scene has selectable streams (cf GF_OPT_CAN_SELECT_STREAMS option)

Parameters
termthe target terminal
urlthe URL of the object to inject
auto_playselcts the object for playback when inserting it
Returns
error if any

◆ gf_term_set_option()

GF_Err gf_term_set_option ( GF_Terminal term,
u32  opt_type,
u32  opt_value 
)

sets option - most of the terminal cfg is done through options, please refer to options.h for details

Parameters
termthe target terminal
opt_typeoption to set
opt_valueoption value
Returns
error if any

◆ gf_term_get_option()

u32 gf_term_get_option ( GF_Terminal term,
u32  opt_type 
)

gets option - most of the terminal cfg is done through options, please refer to options.h for details

Parameters
termthe target terminal
opt_typeoption to set
Returns
option value

◆ gf_term_is_supported_url()

Bool gf_term_is_supported_url ( GF_Terminal term,
const char *  URL,
Bool  use_parent_url,
Bool  no_mime_check 
)

checks if given URL is understood by client.

Parameters
termthe target terminal
URLthe URL to check
use_parent_urlif GF_TRUE, relative URLs are solved against the current presentation URL
no_mime_checkif GF_TRUE, checks by file extension only
Returns
GF_TRUE if client should be able to handle the URL

◆ gf_term_get_current_service_id()

u32 gf_term_get_current_service_id ( GF_Terminal term)

get the current service ID for MPEG-2 TS mux

Parameters
termthe target terminal
Returns
service ID or 0 if no service ID is associated or not loaded yet

◆ gf_term_get_simulation_frame_rate()

Double gf_term_get_simulation_frame_rate ( GF_Terminal term,
u32 nb_frames_drawn 
)

gets simulation frame rate

Parameters
termthe target terminal
nb_frames_drawnset to the number of frames drawn
Returns
simulation frames per seconds

◆ gf_term_get_visual_output_size()

GF_Err gf_term_get_visual_output_size ( GF_Terminal term,
u32 width,
u32 height 
)

gets visual output size (current window/display size)

Parameters
termthe target terminal
widthset to the display width
heightset to the display height
Returns
error if any

◆ gf_term_set_speed()

GF_Err gf_term_set_speed ( GF_Terminal term,
Fixed  speed 
)

sets playback speed

Parameters
termthe target terminal
speedthe requested speed
Returns
error if any

◆ gf_term_scene_update()

GF_Err gf_term_scene_update ( GF_Terminal term,
char *  type,
char *  com 
)

sends a set of scene commands (BT, XMT, X3D, LASeR+XML) to the scene

Parameters
termthe target terminal
typeindicates the language used - accepted values are "model/x3d+xml" or "x3d": commands is an X3D+XML scene "model/x3d+vrml" or "xrdv": commands is an X3D+VRML scene "model/vrml" or "vrml": commands is an VRML scene "application/x-xmt" or "xmt": commands is an XMT-A scene or a list of XMT-A updates "application/x-bt" or "bt": commands is a BT scene or a list of BT updates "image/svg+xml" or "svg": commands is an SVG scene "application/x-laser+xml" or "laser": commands is an SVG/LASeR+XML scene or a list of LASeR+XML updates if not specified, the type will be guessed from the current root node if any
comthe textual update
Returns
error if any

◆ gf_term_set_size()

GF_Err gf_term_set_size ( GF_Terminal term,
u32  NewWidth,
u32  NewHeight 
)

sets visual output size change: NOT NEEDED WHEN THE TERMINAL IS HANDLING THE DISPLAY WINDOW (cf user.h) if the user app manages the output window it shall resize it before calling this

Parameters
termthe target terminal
NewWidththe output width in pixels
NewHeightthe output height in pixels
Returns
error if any

◆ gf_term_get_text_selection()

const char* gf_term_get_text_selection ( GF_Terminal term,
Bool  probe_only 
)

returns current text selection.

Parameters
termthe target terminal
probe_onlyif GF_TRUE, simply returns a non-NULL string ("") if some text is selected
Returns
text selection if any, or NULL otherwise.

◆ gf_term_paste_text()

GF_Err gf_term_paste_text ( GF_Terminal term,
const char *  txt,
Bool  probe_only 
)

pastes text into current selection if any.

Parameters
termthe target terminal
txtthe text to set
probe_onlyif GF_TRUE, only check if text is currently edited
Returns
error if any

◆ gf_term_process_step()

Bool gf_term_process_step ( GF_Terminal term)

processes pending tasks in the media session

Note
If filter session regulation is not disabled, the function will sleep for until next frame should be drawn before returning.
Parameters
termthe target terminal
Returns
GF_TRUE if a new frame was drawn, GF_FALSE otherwise

◆ gf_term_user_event()

Bool gf_term_user_event ( GF_Terminal term,
GF_Event event 
)

post user interaction to terminal

Parameters
termthe target terminal
eventthe event to post
Returns
GF_TRUE if event was directly consumed

◆ gf_term_send_event()

Bool gf_term_send_event ( GF_Terminal term,
GF_Event evt 
)

post event to terminal

Warning
NOT NEEDED WHEN THE TERMINAL IS HANDLING THE DISPLAY WINDOW (cf user.h)
Parameters
termthe target terminal
evtthe event to post
Returns
GF_TRUE if event was directly consumed

◆ gf_term_get_screen_buffer()

GF_Err gf_term_get_screen_buffer ( GF_Terminal term,
GF_VideoSurface framebuffer 
)

gets screen buffer

Note
the screen buffer is released by calling gf_term_release_screen_buffer
Parameters
termthe target terminal
framebufferset to the framebuffer information
Returns
error if any

◆ gf_term_get_offscreen_buffer()

GF_Err gf_term_get_offscreen_buffer ( GF_Terminal term,
GF_VideoSurface framebuffer,
u32  view_idx,
GF_CompositorGrabMode  depth_buffer_type 
)

gets view buffer - this locks the scene graph too until released is called

Note
the screen buffer is released by calling gf_term_release_screen_buffer
Parameters
termthe target terminal
framebufferset to the framebuffer information
view_idxindicates the view index, and ranges from 0 to GF_OPT_NUM_STEREO_VIEWS value
depth_buffer_typeindicates the depth buffer mode
Returns
error if any

◆ gf_term_release_screen_buffer()

GF_Err gf_term_release_screen_buffer ( GF_Terminal term,
GF_VideoSurface framebuffer 
)

releases screen buffer and unlocks graph

Parameters
termthe target terminal
framebufferthe pointer passed to gf_term_get_screen_buffer
Returns
error if any

◆ gf_term_switch_quality()

void gf_term_switch_quality ( GF_Terminal term,
Bool  up 
)

switches quality up or down - can be called several time in the same direction this will call all decoders to adjust their quality levels

Parameters
termthe target terminal
upif GF_TRUE, switches quality up,otherwise down

◆ gf_term_is_type_supported()

Bool gf_term_is_type_supported ( GF_Terminal term,
const char *  mime 
)

checks if a mime type is supported

Parameters
termthe target terminal
mimethe mime type to check
Returns
GF_TRUE if supported