*
* The pipeline uses the clock to calculate the running time. Usually all
* renderers synchronize to the global clock using the buffer timestamps, the
- * newsegment events and the element's base time, see #GstPipeline.
+ * #GST_EVENT_SEGMENT events and the element's base time, see #GstPipeline.
*
* A clock implementation can support periodic and single shot clock
* notifications both synchronous and asynchronous.
* notification using gst_clock_new_single_shot_id() or
* gst_clock_new_periodic_id().
*
- * To perform a blocking wait for the specific time of the #GstClockID use the
+ * To perform a blocking wait for the specific time of the #GstClockID use
* gst_clock_id_wait(). To receive a callback when the specific time is reached
* in the clock use gst_clock_id_wait_async(). Both these calls can be
* interrupted with the gst_clock_id_unschedule() call. If the blocking wait is
* unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned.
*
* Periodic callbacks scheduled async will be repeatedly called automatically
- * until it is unscheduled. To schedule a sync periodic callback,
+ * until they are unscheduled. To schedule a sync periodic callback,
* gst_clock_id_wait() should be called repeatedly.
*
* The async callbacks can happen from any thread, either provided by the core
* the clock is not PLAYING.
*
* When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
- * slaved to another #GstClock with the gst_clock_set_master(). The clock will
+ * slaved to another #GstClock with gst_clock_set_master(). The clock will
* then automatically be synchronized to this master clock by repeatedly
* sampling the master clock and the slave clock and recalibrating the slave
* clock with gst_clock_set_calibration(). This feature is mostly useful for
* gst_clock_id_ref:
* @id: The #GstClockID to ref
*
- * Increase the refcount of given @id.
+ * Increases the refcount of given @id.
*
* Returns: (transfer full): The same #GstClockID with increased refcount.
- *
- * MT safe.
*/
GstClockID
gst_clock_id_ref (GstClockID id)
* gst_clock_id_unref:
* @id: (transfer full): The #GstClockID to unref
*
- * Unref given @id. When the refcount reaches 0 the
+ * Unrefs given @id. When the refcount reaches 0 the
* #GstClockID will be freed.
- *
- * MT safe.
*/
void
gst_clock_id_unref (GstClockID id)
* @clock: The #GstClockID to get a single shot notification from
* @time: the requested time
*
- * Get a #GstClockID from @clock to trigger a single shot
- * notification at the requested time. The single shot id should be
- * unreffed after usage.
- *
- * Free-function: gst_clock_id_unref
+ * Gets a #GstClockID from @clock to trigger a single shot
+ * notification at the requested time.
*
* Returns: (transfer full): a #GstClockID that can be used to request the
* time notification.
- *
- * MT safe.
*/
GstClockID
gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
* @start_time: the requested start time
* @interval: the requested interval
*
- * Get an ID from @clock to trigger a periodic notification.
+ * Gets an ID from @clock to trigger a periodic notification.
* The periodic notifications will start at time @start_time and
- * will then be fired with the given @interval. @id should be unreffed
- * after usage.
- *
- * Free-function: gst_clock_id_unref
+ * will then be fired with the given @interval.
*
* Returns: (transfer full): a #GstClockID that can be used to request the
* time notification.
- *
- * MT safe.
*/
GstClockID
gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
* Compares the two #GstClockID instances. This function can be used
* as a GCompareFunc when sorting ids.
*
- * Returns: negative value if a < b; zero if a = b; positive value if a > b
- *
- * MT safe.
+ * Returns: negative value if `a < b`; zero if `a = b`; positive value if `a > b`
*/
gint
gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2)
* gst_clock_id_get_time:
* @id: The #GstClockID to query
*
- * Get the time of the clock ID
+ * Gets the time of the clock ID
*
* Returns: the time of the given clock id.
- *
- * MT safe.
*/
GstClockTime
gst_clock_id_get_time (GstClockID id)
* @jitter: (out) (allow-none): a pointer that will contain the jitter,
* can be %NULL.
*
- * Perform a blocking wait on @id.
+ * Performs a blocking wait on @id.
* @id should have been created with gst_clock_new_single_shot_id()
* or gst_clock_new_periodic_id() and should not have been unscheduled
* with a call to gst_clock_id_unschedule().
* if the current clock time is past the time of @id, #GST_CLOCK_OK if
* @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
* unscheduled with gst_clock_id_unschedule().
- *
- * MT safe.
*/
GstClockReturn
gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
* @user_data: User data passed in the callback
* @destroy_data: #GDestroyNotify for user_data
*
- * Register a callback on the given #GstClockID @id with the given
+ * Registers a callback on the given #GstClockID @id with the given
* function and user_data. When passing a #GstClockID with an invalid
* time to this function, the callback will be called immediately
- * with a time set to GST_CLOCK_TIME_NONE. The callback will
+ * with a time set to %GST_CLOCK_TIME_NONE. The callback will
* be called when the time of @id has been reached.
*
* The callback @func can be invoked from any thread, either provided by the
* core or from a streaming thread. The application should be prepared for this.
*
* Returns: the result of the non blocking wait.
- *
- * MT safe.
*/
GstClockReturn
gst_clock_id_wait_async (GstClockID id,
* gst_clock_id_unschedule:
* @id: The id to unschedule
*
- * Cancel an outstanding request with @id. This can either
+ * Cancels an outstanding request with @id. This can either
* be an outstanding async notification or a pending sync notification.
* After this call, @id cannot be used anymore to receive sync or
* async notifications, you need to create a new #GstClockID.
- *
- * MT safe.
*/
void
gst_clock_id_unschedule (GstClockID id)
/**
* GstClock::synced:
- * @clock: the clock
+ * @self: the clock
* @synced: if the clock is synced now
*
- * Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once
+ * Signaled on clocks with %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once
* the clock is synchronized, or when it completely lost synchronization.
* This signal will not be emitted on clocks without the flag.
*
* @clock: a #GstClock
* @resolution: The resolution to set
*
- * Set the accuracy of the clock. Some clocks have the possibility to operate
+ * Sets the accuracy of the clock. Some clocks have the possibility to operate
* with different accuracy at the expense of more resource usage. There is
* normally no need to change the default resolution of a clock. The resolution
* of a clock can only be changed if the clock has the
* gst_clock_get_resolution:
* @clock: a #GstClock
*
- * Get the accuracy of the clock. The accuracy of the clock is the granularity
+ * Gets the accuracy of the clock. The accuracy of the clock is the granularity
* of the values returned by gst_clock_get_time().
*
* Returns: the resolution of the clock in units of #GstClockTime.
- *
- * MT safe.
*/
GstClockTime
gst_clock_get_resolution (GstClock * clock)
* Gets the current internal time of the given clock. The time is returned
* unadjusted for the offset and the rate.
*
- * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when
+ * Returns: the internal time of the clock. Or %GST_CLOCK_TIME_NONE when
* given invalid input.
- *
- * MT safe.
*/
GstClockTime
gst_clock_get_internal_time (GstClock * clock)
* monotonically increasing and adjusted according to the current
* offset and rate.
*
- * Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when
+ * Returns: the time of the clock. Or %GST_CLOCK_TIME_NONE when
* given invalid input.
- *
- * MT safe.
*/
GstClockTime
gst_clock_get_time (GstClock * clock)
* Subsequent calls to gst_clock_get_time() will return clock times computed as
* follows:
*
- * |[
+ * ``` C
* time = (internal_time - internal) * rate_num / rate_denom + external
- * ]|
+ * ```
*
* This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
* tries to do the integer arithmetic as precisely as possible.
* Note that gst_clock_get_time() always returns increasing values so when you
* move the clock backwards, gst_clock_get_time() will report the previous value
* until the clock catches up.
- *
- * MT safe.
*/
void
gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
*
* @internal, @external, @rate_num, and @rate_denom can be left %NULL if the
* caller is not interested in the values.
- *
- * MT safe.
*/
void
gst_clock_get_calibration (GstClock * clock, GstClockTime * internal,
* @clock: a #GstClock
* @master: (allow-none): a master #GstClock
*
- * Set @master as the master clock for @clock. @clock will be automatically
+ * Sets @master as the master clock for @clock. @clock will be automatically
* calibrated so that gst_clock_get_time() reports the same time as the
* master clock.
*
* Returns: %TRUE if the clock is capable of being slaved to a master clock.
* Trying to set a master on a clock without the
* #GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE.
- *
- * MT safe.
*/
gboolean
gst_clock_set_master (GstClock * clock, GstClock * master)
* gst_clock_get_master:
* @clock: a #GstClock
*
- * Get the master clock that @clock is slaved to or %NULL when the clock is
+ * Gets the master clock that @clock is slaved to or %NULL when the clock is
* not slaved to any master clock.
*
* Returns: (transfer full) (nullable): a master #GstClock or %NULL
- * when this clock is not slaved to a master clock. Unref after
- * usage.
- *
- * MT safe.
+ * when this clock is not slaved to a master clock.
*/
GstClock *
gst_clock_get_master (GstClock * clock)
* This function returns the underlying clock.
*
* Returns: (transfer full) (nullable): a #GstClock or %NULL when the
- * underlying clock has been freed. Unref after usage.
- *
- * MT safe.
- *
+ * underlying clock has been freed.
* Since: 1.16
*/
GstClock *
* no longer usable and should be freed.
*
* Returns: whether the clock @id uses the same underlying #GstClock @clock.
- *
- * MT safe.
- *
* Since: 1.16
*/
gboolean
*
* Returns: %TRUE if enough observations were added to run the
* regression algorithm.
- *
- * MT safe.
*/
gboolean
gst_clock_add_observation (GstClock * clock, GstClockTime slave,
* The caller can then take the results and call gst_clock_set_calibration()
* with the values, or some modified version of them.
*
+ * Returns: %TRUE if enough observations were added to run the
+ * regression algorithm.
* Since: 1.6
*/
gboolean
* @clock: a #GstClock
* @timeout: a timeout
*
- * Set the amount of time, in nanoseconds, to sample master and slave
+ * Sets the amount of time, in nanoseconds, to sample master and slave
* clocks
*/
void
* gst_clock_get_timeout:
* @clock: a #GstClock
*
- * Get the amount of time that master and slave clocks are sampled.
+ * Gets the amount of time that master and slave clocks are sampled.
*
* Returns: the interval between samples.
*/
* is %GST_CLOCK_TIME_NONE it will wait forever, otherwise it will time out
* after @timeout nanoseconds.
*
- * For asynchronous waiting, the GstClock::synced signal can be used.
+ * For asynchronous waiting, the #GstClock::synced signal can be used.
*
- * This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
+ * This returns immediately with %TRUE if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
* is not set on the clock, or if the clock is already synced.
*
* Returns: %TRUE if waiting was successful, or %FALSE on timeout
* gst_clock_is_synced:
* @clock: a GstClock
*
- * Checks if the clock is currently synced.
- *
- * This returns if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is not set on the clock.
+ * Checks if the clock is currently synced, by looking at whether
+ * %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC is set.
*
* Returns: %TRUE if the clock is currently synced
*
* @clock: a GstClock
* @synced: if the clock is synced
*
- * Sets @clock to synced and emits the GstClock::synced signal, and wakes up any
+ * Sets @clock to synced and emits the #GstClock::synced signal, and wakes up any
* thread waiting in gst_clock_wait_for_sync().
*
- * This function must only be called if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
+ * This function must only be called if %GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
* is set on the clock, and is intended to be called by subclasses only.
*
* Since: 1.6
* GST_TIME_AS_SECONDS:
* @time: the time
*
- * Convert a #GstClockTime to seconds.
+ * Converts a #GstClockTime to seconds.
*/
#define GST_TIME_AS_SECONDS(time) ((time) / GST_SECOND)
/**
* GST_TIME_AS_MSECONDS:
* @time: the time
*
- * Convert a #GstClockTime to milliseconds (1/1000 of a second).
+ * Converts a #GstClockTime to milliseconds (1/1000 of a second).
*/
#define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
/**
* GST_TIME_AS_USECONDS:
* @time: the time
*
- * Convert a #GstClockTime to microseconds (1/1000000 of a second).
+ * Converts a #GstClockTime to microseconds (1/1000000 of a second).
*/
#define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
/**
* GST_TIME_AS_NSECONDS:
* @time: the time
*
- * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
+ * Converts a #GstClockTime to nanoseconds (1/1000000000 of a second).
*/
#define GST_TIME_AS_NSECONDS(time) (time)
* @s: the first time
* @e: the second time
*
- * Calculate a difference between two clock times as a #GstClockTimeDiff.
+ * Calculates a difference between two clock times as a #GstClockTimeDiff.
* The difference is calculated as @e - @s.
*/
#define GST_CLOCK_DIFF(s, e) (GstClockTimeDiff)((e) - (s))
* GST_TIMEVAL_TO_TIME:
* @tv: the timeval to convert
*
- * Convert a GTimeVal to a #GstClockTime.
+ * Converts a GTimeVal to a #GstClockTime.
*/
#define GST_TIMEVAL_TO_TIME(tv) (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
* @t: The #GstClockTime to convert
* @tv: The target timeval
*
- * Convert a #GstClockTime to a GTimeVal
+ * Converts a #GstClockTime to a GTimeVal
*
* > on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
* > which is about 68 years. Expect trouble if you want to schedule stuff
* GST_TIMESPEC_TO_TIME:
* @ts: the timespec to convert
*
- * Convert a struct timespec (see man pselect) to a #GstClockTime.
+ * Converts a struct timespec (see `man pselect`) to a #GstClockTime.
*/
#define GST_TIMESPEC_TO_TIME(ts) (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
/**
* @t: The #GstClockTime to convert
* @ts: The target timespec
*
- * Convert a #GstClockTime to a struct timespec (see man pselect)
+ * Converts a #GstClockTime to a struct timespec (see `man pselect`)
*/
#define GST_TIME_TO_TIMESPEC(t,ts) \
G_STMT_START { \
* GST_TIME_FORMAT: (skip):
*
* A string that can be used in printf-like format strings to display a
- * #GstClockTime value in h:m:s format. Use GST_TIME_ARGS() to construct
+ * #GstClockTime value in `h:m:s` format. Use GST_TIME_ARGS() to construct
* the matching arguments.
*
* Example:
- * |[<!-- language="C" -->
+ *
+ * ``` C
* printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
- * ]|
+ * ```
*/
#define GST_TIME_FORMAT "u:%02u:%02u.%09u"
/**
* GST_TIME_ARGS: (skip):
* @t: a #GstClockTime
*
- * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
+ * Formats @t for the #GST_TIME_FORMAT format string. Note: @t will be
* evaluated more than once.
*/
#define GST_TIME_ARGS(t) \
* GST_STIME_FORMAT: (skip):
*
* A string that can be used in printf-like format strings to display a signed
- * #GstClockTimeDiff or #gint64 value in h:m:s format. Use GST_TIME_ARGS() to
+ * #GstClockTimeDiff or #gint64 value in `h:m:s` format. Use GST_TIME_ARGS() to
* construct the matching arguments.
*
* Example:
- * |[
+ *
+ * ``` C
* printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts));
- * ]|
+ * ```
*
* Since: 1.6
*/
* GST_STIME_ARGS: (skip):
* @t: a #GstClockTimeDiff or #gint64
*
- * Format @t for the #GST_STIME_FORMAT format string. Note: @t will be
+ * Formats @t for the #GST_STIME_FORMAT format string. Note: @t will be
* evaluated more than once.
*
* Since: 1.6
* GST_CLOCK_ENTRY:
* @entry: the entry to cast
*
- * Cast to a clock entry
+ * Casts to a clock entry
*/
#define GST_CLOCK_ENTRY(entry) ((GstClockEntry *)(entry))
* GST_CLOCK_ENTRY_CLOCK:
* @entry: the entry to query
*
- * Get the owner clock of the entry
+ * Gets the owner clock of the entry
*
* Deprecated: Use gst_clock_id_get_clock() instead.
*/
* GST_CLOCK_ENTRY_TYPE:
* @entry: the entry to query
*
- * Get the type of the clock entry
+ * Gets the type of the clock entry
*/
#define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
/**
* GST_CLOCK_ENTRY_TIME:
* @entry: the entry to query
*
- * Get the requested time of this entry
+ * Gets the requested time of this entry
*/
#define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
/**
* GST_CLOCK_ENTRY_INTERVAL:
* @entry: the entry to query
*
- * Get the interval of this periodic entry
+ * Gets the interval of this periodic entry
*/
#define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
/**
*/
struct _GstClockEntry {
gint refcount;
- /*< protected >*/
+ /*< private >*/
#ifndef GST_REMOVE_DEPRECATED
#ifndef GST_DISABLE_DEPRECATED
GstClock *clock;
* @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
* @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
* @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
- * @GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC: clock needs to be synced before it can be used
- * (Since: 1.6)
* @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
*
* The capabilities of this clock
GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC = (GST_OBJECT_FLAG_LAST << 3),
GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (GST_OBJECT_FLAG_LAST << 4),
GST_CLOCK_FLAG_CAN_SET_MASTER = (GST_OBJECT_FLAG_LAST << 5),
+
+ /**
+ * GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC:
+ *
+ * clock needs to be synced before it can be used
+ *
+ * Since: 1.6
+ */
GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC = (GST_OBJECT_FLAG_LAST << 6),
/* padding */
GST_CLOCK_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 8)
/**
* GstClock:
+ * @object: the parent structure
*
- * #GstClock base structure. The values of this structure are
- * protected for subclasses, use the methods to use the #GstClock.
+ * #GstClock base structure.
*/
struct _GstClock {
GstObject object;
/**
* GstClockClass:
* @parent_class: the parent class structure
- * @change_resolution: change the resolution of the clock. Not all values might
- * be acceptable. The new resolution should be returned.
- * @get_resolution: get the resolution of the clock.
- * @get_internal_time: get the internal unadjusted time of the clock.
- * implement @wait_jitter instead.
- * @wait: perform a blocking wait on the given #GstClockEntry and return
- * the jitter.
- * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
- * @unschedule: unblock a blocking or async wait operation.
*
* GStreamer clock class. Override the vmethods to implement the clock
* functionality.
/*< public >*/
/* vtable */
+
+ /**
+ * GstClockClass::change_resolution:
+ * @clock: the #GstClock
+ * @old_resolution: the previous resolution
+ * @new_resolution: the new resolution
+ *
+ * Change the resolution of the clock. Not all values might
+ * be acceptable.
+ *
+ * Returns: the new resolution
+ */
GstClockTime (*change_resolution) (GstClock *clock,
GstClockTime old_resolution,
GstClockTime new_resolution);
+
+ /**
+ * GstClockClass::get_resolution:
+ * @clock: the #GstClock
+ *
+ * Get the resolution of the clock.
+ *
+ * Returns: the current resolution
+ */
GstClockTime (*get_resolution) (GstClock *clock);
+ /**
+ * GstClockClass::get_internal_time:
+ * @clock: the #GstClock
+ *
+ * Get the internal unadjusted time of the clock.
+ *
+ * Implement #GstClockClass::wait instead.
+ *
+ * Returns: the internal time
+ */
GstClockTime (*get_internal_time) (GstClock *clock);
/* waiting on an ID */
+
+ /**
+ * GstClockClass::wait:
+ * @clock: the #GstClock
+ * @entry: the entry to wait on
+ * @jitter: (out) (allow-none): a pointer that will contain the jitter
+ *
+ * Perform a blocking wait on the given #GstClockEntry and return
+ * the jitter.
+ *
+ * Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
+ * if the current clock time is past the time of @id, #GST_CLOCK_OK if
+ * @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
+ * unscheduled with gst_clock_id_unschedule().
+ */
GstClockReturn (*wait) (GstClock *clock, GstClockEntry *entry,
GstClockTimeDiff *jitter);
+
+ /**
+ * GstClockClass::wait_async:
+ * @clock: the #GstClock
+ * @entry: the entry to wait on
+ *
+ * Perform an asynchronous wait on the given #GstClockEntry.
+ *
+ * Returns: the result of the non blocking wait.
+ */
GstClockReturn (*wait_async) (GstClock *clock, GstClockEntry *entry);
+
+ /**
+ * GstClockClass::unschedule:
+ * @clock: the #GstClock
+ * @entry: the entry to unschedule
+ *
+ * Unblock a blocking or async wait operation.
+ */
void (*unschedule) (GstClock *clock, GstClockEntry *entry);
/*< private >*/