clock: Use external / internal as term for the two clock bases everywhere

It was confusing that some functions were using master for the external time and
slave for the internal time. This is not consistently using external / internal
when talking about concrete clock times.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/7456>
This commit is contained in:
Sebastian Dröge 2024-09-05 12:49:11 +03:00 committed by Tim-Philipp Müller
parent f463d4c3c1
commit e5133033fa
3 changed files with 50 additions and 45 deletions

View file

@ -8749,10 +8749,10 @@ unscheduled with gst_clock_id_unschedule().</doc>
</parameters>
</virtual-method>
<method name="add_observation" c:identifier="gst_clock_add_observation">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">The time @master of the master clock and the time @slave of the slave
clock are added to the list of observations. If enough observations
are available, a linear regression algorithm is run on the
observations and @clock is recalibrated.
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">The time @observation_external of the external or master clock and the time
@observation_internal of the internal or slave clock are added to the list of
observations. If enough observations are available, a linear regression
algorithm is run on the observations and @clock is recalibrated.
If this functions returns %TRUE, @r_squared will contain the
correlation coefficient of the interpolation. A value of 1.0
@ -8770,12 +8770,12 @@ regression algorithm.</doc>
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a #GstClock</doc>
<type name="Clock" c:type="GstClock*"/>
</instance-parameter>
<parameter name="slave" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the slave</doc>
<parameter name="observation_internal" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the internal clock</doc>
<type name="ClockTime" c:type="GstClockTime"/>
</parameter>
<parameter name="master" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the master</doc>
<parameter name="observation_external" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the external clock</doc>
<type name="ClockTime" c:type="GstClockTime"/>
</parameter>
<parameter name="r_squared" direction="out" caller-allocates="0" transfer-ownership="full">
@ -8786,8 +8786,8 @@ regression algorithm.</doc>
</method>
<method name="add_observation_unapplied" c:identifier="gst_clock_add_observation_unapplied" version="1.6">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">Add a clock observation to the internal slaving algorithm the same as
gst_clock_add_observation(), and return the result of the master clock
estimation, without updating the internal calibration.
gst_clock_add_observation(), and return the result of the external or master
clock estimation, without updating the internal calibration.
The caller can then take the results and call gst_clock_set_calibration()
with the values, or some modified version of them.</doc>
@ -8802,12 +8802,12 @@ regression algorithm.</doc>
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a #GstClock</doc>
<type name="Clock" c:type="GstClock*"/>
</instance-parameter>
<parameter name="slave" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the slave</doc>
<parameter name="observation_internal" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the internal clock</doc>
<type name="ClockTime" c:type="GstClockTime"/>
</parameter>
<parameter name="master" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the master</doc>
<parameter name="observation_external" transfer-ownership="none">
<doc xml:space="preserve" filename="../subprojects/gstreamer/gst/gstclock.c">a time on the external clock</doc>
<type name="ClockTime" c:type="GstClockTime"/>
</parameter>
<parameter name="r_squared" direction="out" caller-allocates="0" transfer-ownership="full">

View file

@ -1432,14 +1432,14 @@ gst_clock_id_uses_clock (GstClockID id, GstClock * clock)
/**
* gst_clock_add_observation:
* @clock: a #GstClock
* @slave: a time on the slave
* @master: a time on the master
* @observation_internal: a time on the internal clock
* @observation_external: a time on the external clock
* @r_squared: (out): a pointer to hold the result
*
* The time @master of the master clock and the time @slave of the slave
* clock are added to the list of observations. If enough observations
* are available, a linear regression algorithm is run on the
* observations and @clock is recalibrated.
* The time @observation_external of the external or master clock and the time
* @observation_internal of the internal or slave clock are added to the list of
* observations. If enough observations are available, a linear regression
* algorithm is run on the observations and @clock is recalibrated.
*
* If this functions returns %TRUE, @r_squared will contain the
* correlation coefficient of the interpolation. A value of 1.0
@ -1451,13 +1451,13 @@ gst_clock_id_uses_clock (GstClockID id, GstClock * clock)
* regression algorithm.
*/
gboolean
gst_clock_add_observation (GstClock * clock, GstClockTime slave,
GstClockTime master, gdouble * r_squared)
gst_clock_add_observation (GstClock * clock, GstClockTime observation_internal,
GstClockTime observation_external, gdouble * r_squared)
{
GstClockTime m_num, m_denom, b, xbase;
if (!gst_clock_add_observation_unapplied (clock, slave, master, r_squared,
&xbase, &b, &m_num, &m_denom))
if (!gst_clock_add_observation_unapplied (clock, observation_internal,
observation_external, r_squared, &xbase, &b, &m_num, &m_denom))
return FALSE;
/* if we have a valid regression, adjust the clock */
@ -1469,8 +1469,8 @@ gst_clock_add_observation (GstClock * clock, GstClockTime slave,
/**
* gst_clock_add_observation_unapplied:
* @clock: a #GstClock
* @slave: a time on the slave
* @master: a time on the master
* @observation_internal: a time on the internal clock
* @observation_external: a time on the external clock
* @r_squared: (out): a pointer to hold the result
* @internal: (out) (optional): a location to store the internal time
* @external: (out) (optional): a location to store the external time
@ -1478,8 +1478,8 @@ gst_clock_add_observation (GstClock * clock, GstClockTime slave,
* @rate_denom: (out) (optional): a location to store the rate denominator
*
* Add a clock observation to the internal slaving algorithm the same as
* gst_clock_add_observation(), and return the result of the master clock
* estimation, without updating the internal calibration.
* gst_clock_add_observation(), and return the result of the external or master
* clock estimation, without updating the internal calibration.
*
* The caller can then take the results and call gst_clock_set_calibration()
* with the values, or some modified version of them.
@ -1489,9 +1489,9 @@ gst_clock_add_observation (GstClock * clock, GstClockTime slave,
* Since: 1.6
*/
gboolean
gst_clock_add_observation_unapplied (GstClock * clock, GstClockTime slave,
GstClockTime master, gdouble * r_squared,
GstClockTime * internal, GstClockTime * external,
gst_clock_add_observation_unapplied (GstClock * clock,
GstClockTime internal_observation, GstClockTime external_observation,
gdouble * r_squared, GstClockTime * internal, GstClockTime * external,
GstClockTime * rate_num, GstClockTime * rate_denom)
{
GstClockTime m_num, m_denom, b, xbase;
@ -1499,8 +1499,8 @@ gst_clock_add_observation_unapplied (GstClock * clock, GstClockTime slave,
guint n;
g_return_val_if_fail (GST_IS_CLOCK (clock), FALSE);
g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (slave), FALSE);
g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (master), FALSE);
g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (internal_observation), FALSE);
g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (external_observation), FALSE);
g_return_val_if_fail (r_squared != NULL, FALSE);
priv = clock->priv;
@ -1508,11 +1508,12 @@ gst_clock_add_observation_unapplied (GstClock * clock, GstClockTime slave,
GST_CLOCK_SLAVE_LOCK (clock);
GST_CAT_LOG_OBJECT (GST_CAT_CLOCK, clock,
"adding observation slave %" GST_TIME_FORMAT ", master %" GST_TIME_FORMAT,
GST_TIME_ARGS (slave), GST_TIME_ARGS (master));
"adding observation internal %" GST_TIME_FORMAT ", external %"
GST_TIME_FORMAT, GST_TIME_ARGS (internal_observation),
GST_TIME_ARGS (external_observation));
priv->times[(2 * priv->time_index)] = slave;
priv->times[(2 * priv->time_index) + 1] = master;
priv->times[(2 * priv->time_index)] = internal_observation;
priv->times[(2 * priv->time_index) + 1] = external_observation;
priv->time_index++;
if (G_UNLIKELY (priv->time_index == priv->window_size)) {

View file

@ -610,15 +610,19 @@ GST_API
GstClockTime gst_clock_get_timeout (GstClock *clock);
GST_API
gboolean gst_clock_add_observation (GstClock *clock, GstClockTime slave,
GstClockTime master, gdouble *r_squared);
gboolean gst_clock_add_observation (GstClock *clock,
GstClockTime observation_internal,
GstClockTime observation_external,
gdouble *r_squared);
GST_API
gboolean gst_clock_add_observation_unapplied (GstClock *clock, GstClockTime slave,
GstClockTime master, gdouble *r_squared,
GstClockTime *internal,
GstClockTime *external,
GstClockTime *rate_num,
GstClockTime *rate_denom);
gboolean gst_clock_add_observation_unapplied (GstClock *clock,
GstClockTime observation_internal,
GstClockTime observation_external,
gdouble *r_squared,
GstClockTime *internal,
GstClockTime *external,
GstClockTime *rate_num,
GstClockTime *rate_denom);
/* getting and adjusting internal/external time */