From e5133033fa7ff2c61f05f9256b4571237e8f3a02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= <sebastian@centricular.com>
Date: Thu, 5 Sep 2024 12:49:11 +0300
Subject: [PATCH] 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>
---
girs/Gst-1.0.gir | 28 ++++++++---------
subprojects/gstreamer/gst/gstclock.c | 47 ++++++++++++++--------------
subprojects/gstreamer/gst/gstclock.h | 20 +++++++-----
3 files changed, 50 insertions(+), 45 deletions(-)
diff --git a/girs/Gst-1.0.gir b/girs/Gst-1.0.gir
index 743ef5d9b4..030d3e71d5 100644
--- a/girs/Gst-1.0.gir
+++ b/girs/Gst-1.0.gir
@@ -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">
diff --git a/subprojects/gstreamer/gst/gstclock.c b/subprojects/gstreamer/gst/gstclock.c
index f26adc7ba8..d9ea717083 100644
--- a/subprojects/gstreamer/gst/gstclock.c
+++ b/subprojects/gstreamer/gst/gstclock.c
@@ -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)) {
diff --git a/subprojects/gstreamer/gst/gstclock.h b/subprojects/gstreamer/gst/gstclock.h
index 0649f1420e..1457cde173 100644
--- a/subprojects/gstreamer/gst/gstclock.h
+++ b/subprojects/gstreamer/gst/gstclock.h
@@ -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 */