GstClock

GstClock — Abstract class for global clocks

Synopsis


#include <gst/gst.h>


struct      GstClock;
typedef     GstClockTime;
typedef     GstClockTimeDiff;
typedef     GstClockID;
#define     GST_CLOCK_TIME_NONE
#define     GST_CLOCK_TIME_IS_VALID         (time)
#define     GST_SECOND
#define     GST_MSECOND
#define     GST_USECOND
#define     GST_NSECOND
#define     GST_CLOCK_DIFF                  (s, e)
#define     GST_TIMEVAL_TO_TIME             (tv)
#define     GST_TIME_TO_TIMEVAL             (t,tv)
#define     GST_CLOCK_ENTRY_TRACE_NAME
struct      GstClockEntry;
gboolean    (*GstClockCallback)             (GstClock *clock,
                                             GstClockTime time,
                                             GstClockID id,
                                             gpointer user_data);
enum        GstClockEntryType;
#define     GST_CLOCK_ENTRY                 (entry)
#define     GST_CLOCK_ENTRY_CLOCK           (entry)
#define     GST_CLOCK_ENTRY_TYPE            (entry)
#define     GST_CLOCK_ENTRY_TIME            (entry)
#define     GST_CLOCK_ENTRY_INTERVAL        (entry)
#define     GST_CLOCK_ENTRY_STATUS          (entry)
enum        GstClockReturn;
enum        GstClockFlags;
#define     GST_CLOCK_FLAGS                 (clock)
guint64     gst_clock_set_resolution        (GstClock *clock,
                                             guint64 resolution);
guint64     gst_clock_get_resolution        (GstClock *clock);
GstClockTime gst_clock_get_time             (GstClock *clock);
GstClockID  gst_clock_new_single_shot_id    (GstClock *clock,
                                             GstClockTime time);
GstClockID  gst_clock_new_periodic_id       (GstClock *clock,
                                             GstClockTime start_time,
                                             GstClockTime interval);
GstClockTime gst_clock_id_get_time          (GstClockID id);
GstClockReturn gst_clock_id_wait            (GstClockID id,
                                             GstClockTimeDiff *jitter);
GstClockReturn gst_clock_id_wait_async      (GstClockID id,
                                             GstClockCallback func,
                                             gpointer user_data);
void        gst_clock_id_unschedule         (GstClockID id);


Object Hierarchy


  GObject
   +----GstObject
         +----GstClock

Properties


  "stats"                gboolean             : Read / Write

Description

GStreamer uses a global clock to synchronise the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class.

The clock time is always measured in nanoseconds, with the clock being set to 0 when the pipeline goes to READY. Usually all renderers sync to the global clock so that the clock is always a good measure of the time in the pipeline.

Details

struct GstClock

struct GstClock {
  GstClockFlags	 flags;

};


GstClockTime

typedef guint64 	GstClockTime;

A datatype to hold a time, measured in nanoseconds.


GstClockTimeDiff

typedef gint64 		GstClockTimeDiff;

A datatype to hold a timedifference, measured in nanoseconds.


GstClockID

typedef gpointer 	GstClockID;

A detatype to hold the handle to an outstanding async clock callback


GST_CLOCK_TIME_NONE

#define GST_CLOCK_TIME_NONE  		((GstClockTime)-1)

Constant to define an undefined clock time


GST_CLOCK_TIME_IS_VALID()

#define GST_CLOCK_TIME_IS_VALID(time)	((time) != GST_CLOCK_TIME_NONE)

time :

GST_SECOND

#define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer second


GST_MSECOND

#define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))

Constant that defines one GStreamer millisecond


GST_USECOND

#define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))

Constant that defines one GStreamer microsecond


GST_NSECOND

#define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))

Constant that defines one GStreamer nanosecond


GST_CLOCK_DIFF()

#define GST_CLOCK_DIFF(s, e) 		(GstClockTimeDiff)((s) - (e))

Calculate a difference between to clock times.

s :the first time
e :the second time

GST_TIMEVAL_TO_TIME()

#define GST_TIMEVAL_TO_TIME(tv)		((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)

Convert a GTimeVal to a GstClockTime

tv :the timeval to convert

GST_TIME_TO_TIMEVAL()

#define     GST_TIME_TO_TIMEVAL(t,tv)

Convert a GstClockTime to a GTimeVal

t :The GstClockTime to convert
tv :The target timeval

GST_CLOCK_ENTRY_TRACE_NAME

#define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"

The name used for tracing clock entry allocations.


struct GstClockEntry

struct GstClockEntry {

  gint  		 refcount;
};

All pending timeouts or periodic notifies are converted into an entry.


GstClockCallback ()

gboolean    (*GstClockCallback)             (GstClock *clock,
                                             GstClockTime time,
                                             GstClockID id,
                                             gpointer user_data);

The function prototype of the callback.

clock :The clock that triggered the callback
time :The time it was triggered
id :The id that expired
user_data :user data passed in the async_wait call
Returns :TRUE or FALSE (currently unused)

enum GstClockEntryType

typedef enum {
  GST_CLOCK_ENTRY_SINGLE,
  GST_CLOCK_ENTRY_PERIODIC
} GstClockEntryType;

The type of the clock entry

GST_CLOCK_ENTRY_SINGLEa single shot timeout
GST_CLOCK_ENTRY_PERIODICa periodic timeout request

GST_CLOCK_ENTRY()

#define GST_CLOCK_ENTRY(entry)		((GstClockEntry *)(entry))

Cast to a clock entry

entry :the entry to cast

GST_CLOCK_ENTRY_CLOCK()

#define GST_CLOCK_ENTRY_CLOCK(entry)	((entry)->clock)

Get the owner clock of the entry

entry :the entry to query

GST_CLOCK_ENTRY_TYPE()

#define GST_CLOCK_ENTRY_TYPE(entry)	((entry)->type)

Get the type of the clock entry

entry :the entry to query

GST_CLOCK_ENTRY_TIME()

#define GST_CLOCK_ENTRY_TIME(entry)	((entry)->time)

Get the requested time of this entry

entry :the entry to query

GST_CLOCK_ENTRY_INTERVAL()

#define GST_CLOCK_ENTRY_INTERVAL(entry)	((entry)->interval)

Get the interval of this periodic entry

entry :the entry to query

GST_CLOCK_ENTRY_STATUS()

#define GST_CLOCK_ENTRY_STATUS(entry)	((entry)->status)

The status of the entry

entry :the entry to query

enum GstClockReturn

typedef enum
{
  GST_CLOCK_OK		=  0,
  GST_CLOCK_EARLY 	=  1,
  GST_CLOCK_UNSCHEDULED	=  2,
  GST_CLOCK_BUSY	=  3,
  GST_CLOCK_BADTIME 	=  4,
  GST_CLOCK_ERROR 	=  5,
  GST_CLOCK_UNSUPPORTED	=  6,
} GstClockReturn;

The return value of a clock operation.

GST_CLOCK_OK
GST_CLOCK_EARLYThe operation was scheduled too late.
GST_CLOCK_UNSCHEDULED
GST_CLOCK_BUSY
GST_CLOCK_BADTIME
GST_CLOCK_ERRORAn error occured
GST_CLOCK_UNSUPPORTEDOperation is not supported

enum GstClockFlags

typedef enum
{
  GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (1 << 1),
  GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (1 << 2),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (1 << 3),
  GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (1 << 4),
  GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (1 << 5),
} GstClockFlags;

The capabilities of this clock

GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNCThis clock can do a single sync timeut request
GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNCThis clock can do a single async timeout request
GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNCThis clock can do sync periodic timeout requests
GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNCThis clock can do async periodic timeout callbacks
GST_CLOCK_FLAG_CAN_SET_RESOLUTIONThe resolution of this clock can be changed

GST_CLOCK_FLAGS()

#define GST_CLOCK_FLAGS(clock)  (GST_CLOCK(clock)->flags)

Get the clock flags

clock :the clock to query

gst_clock_set_resolution ()

guint64     gst_clock_set_resolution        (GstClock *clock,
                                             guint64 resolution);

Set the accuracy of the clock.

clock : The clock set the resolution on
resolution : The resolution to set
Returns : the new resolution of the clock.

gst_clock_get_resolution ()

guint64     gst_clock_get_resolution        (GstClock *clock);

Get the accuracy of the clock.

clock : The clock get the resolution of
Returns : the resolution of the clock in microseconds. MT safe.

gst_clock_get_time ()

GstClockTime gst_clock_get_time             (GstClock *clock);

Gets the current time of the given clock. The time is always monotonically increasing.

clock : a GstClock to query
Returns : the time of the clock. Or GST_CLOCK_TIME_NONE when giving wrong input. MT safe.

gst_clock_new_single_shot_id ()

GstClockID  gst_clock_new_single_shot_id    (GstClock *clock,
                                             GstClockTime time);

Get an ID from the given clock to trigger a single shot notification at the requested time. The single shot id should be unreffed after usage.

clock : The clockid to get a single shot notification from
time : the requested time
Returns : An id that can be used to request the time notification. MT safe.

gst_clock_new_periodic_id ()

GstClockID  gst_clock_new_periodic_id       (GstClock *clock,
                                             GstClockTime start_time,
                                             GstClockTime interval);

Get an ID from the given clock to trigger a periodic notification. The periodeic notifications will be start at time start_time and will then be fired with the given interval. The id should be unreffed after usage.

clock : The clockid to get a periodic notification id from
start_time : the requested start time
interval : the requested interval
Returns : An id that can be used to request the time notification. MT safe.

gst_clock_id_get_time ()

GstClockTime gst_clock_id_get_time          (GstClockID id);

Get the time of the clock ID

id : The clockid to query
Returns : the time of the given clock id. MT safe.

gst_clock_id_wait ()

GstClockReturn gst_clock_id_wait            (GstClockID id,
                                             GstClockTimeDiff *jitter);

Perform a blocking wait on the given ID. The jitter arg can be NULL.

id : The clockid to wait on
jitter : A pointer that will contain the jitter
Returns : the result of the blocking wait. MT safe.

gst_clock_id_wait_async ()

GstClockReturn gst_clock_id_wait_async      (GstClockID id,
                                             GstClockCallback func,
                                             gpointer user_data);

Register a callback on the given clockid with the given function and user_data. When passing an id with an invalid time to this function, the callback will be called immediatly with a time set to GST_CLOCK_TIME_NONE. The callback will be called when the time of the id has been reached.

id : a GstClockID to wait on
func : The callback function
user_data : User data passed in the calback
Returns : the result of the non blocking wait. MT safe.

gst_clock_id_unschedule ()

void        gst_clock_id_unschedule         (GstClockID id);

Cancel an outstanding request with the given ID. This can either be an outstanding async notification or a pending sync notification. After this call, the id cannot be used anymore to receive sync or async notifications, you need to create a new GstClockID.

MT safe.

id : The id to unschedule

Properties

"stats" (gboolean : Read / Write)

Boolean property to activate stat generation on the clock.

See Also

GstSystemClock