Refactor TimestampAligner for more general use.

This only changes the comments and rename variables.

Bug: chromium:1054403
Change-Id: Ie7419ca23e482361e9f90405587b8c8f839b26d2
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/169101
Commit-Queue: Minyue Li <minyue@webrtc.org>
Reviewed-by: Karl Wiberg <kwiberg@webrtc.org>
Reviewed-by: Niels Moller <nisse@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#30710}

rtc_base/timestamp_aligner.cc

@@ -27,25 +27,25 @@ TimestampAligner::TimestampAligner()
 
 TimestampAligner::~TimestampAligner() {}
 
-int64_t TimestampAligner::TranslateTimestamp(int64_t camera_time_us,
+int64_t TimestampAligner::TranslateTimestamp(int64_t capturer_time_us,
                                              int64_t system_time_us) {
   return ClipTimestamp(
-      camera_time_us + UpdateOffset(camera_time_us, system_time_us),
+      capturer_time_us + UpdateOffset(capturer_time_us, system_time_us),
       system_time_us);
 }
 
-int64_t TimestampAligner::UpdateOffset(int64_t camera_time_us,
+int64_t TimestampAligner::UpdateOffset(int64_t capturer_time_us,
                                        int64_t system_time_us) {
-  // Estimate the offset between system monotonic time and the capture
+  // Estimate the offset between system monotonic time and the capturer's
-  // time from the camera. The camera is assumed to provide more
+  // time. The capturer is assumed to provide more
   // accurate timestamps than we get from the system time. But the
-  // camera may use its own free-running clock with a large offset and
+  // capturer may use its own free-running clock with a large offset and
   // a small drift compared to the system clock. So the model is
   // basically
   //
   //   y_k = c_0 + c_1 * x_k + v_k
   //
-  // where x_k is the camera timestamp, believed to be accurate in its
+  // where x_k is the capturer's timestamp, believed to be accurate in its
   // own scale. y_k is our reading of the system clock. v_k is the
   // measurement noise, i.e., the delay from frame capture until the
   // system clock was read.
@@ -73,18 +73,18 @@ int64_t TimestampAligner::UpdateOffset(int64_t camera_time_us,
   // exponential averaging.
 
   // The input for averaging, y_k - x_k in the above notation.
-  int64_t diff_us = system_time_us - camera_time_us;
+  int64_t diff_us = system_time_us - capturer_time_us;
   // The deviation from the current average.
   int64_t error_us = diff_us - offset_us_;
 
   // If the current difference is far from the currently estimated
   // offset, the filter is reset. This could happen, e.g., if the
-  // camera clock is reset, or cameras are plugged in and out, or if
+  // capturer's clock is reset, cameras are plugged in and out, or
   // the application process is temporarily suspended. Expected to
   // happen for the very first timestamp (|frames_seen_| = 0). The
   // threshold of 300 ms should make this unlikely in normal
   // operation, and at the same time, converging gradually rather than
-  // resetting the filter should be tolerable for jumps in camera time
+  // resetting the filter should be tolerable for jumps in capturer's time
   // below this threshold.
   static const int64_t kResetThresholdUs = 300000;
   if (std::abs(error_us) > kResetThresholdUs) {

rtc_base/timestamp_aligner.h

@@ -18,14 +18,15 @@
 
 namespace rtc {
 
-// The TimestampAligner class helps translating camera timestamps into
+// The TimestampAligner class helps translating timestamps of a capture system
-// the same timescale as is used by rtc::TimeMicros(). Some cameras
+// into the same timescale as is used by rtc::TimeMicros(). Some capture systems
-// have built in timestamping which is more accurate than reading the
+// provide timestamps, which comes from the capturing hardware (camera or sound
-// system clock, but using a different epoch and unknown clock drift.
+// card) or stamped close to the capturing hardware. Such timestamps are more
-// Frame timestamps in webrtc should use rtc::TimeMicros (system monotonic
+// accurate (less jittery) than reading the system clock, but may have a
-// time), and this class provides a filter which lets us use the
+// different epoch and unknown clock drift. Frame timestamps in webrtc should
-// rtc::TimeMicros timescale, and at the same time take advantage of
+// use rtc::TimeMicros (system monotonic time), and this class provides a filter
-// higher accuracy of the camera clock.
+// which lets us use the rtc::TimeMicros timescale, and at the same time take
+// advantage of higher accuracy of the capturer's clock.
 
 // This class is not thread safe, so all calls to it must be synchronized
 // externally.
@@ -35,18 +36,19 @@ class RTC_EXPORT TimestampAligner {
   ~TimestampAligner();
 
  public:
-  // Translates camera timestamps to the same timescale as is used by
+  // Translates timestamps of a capture system to the same timescale as is used
-  // rtc::TimeMicros(). |camera_time_us| is assumed to be accurate, but
+  // by rtc::TimeMicros(). |capturer_time_us| is assumed to be accurate, but
   // with an unknown epoch and clock drift. |system_time_us| is
   // time according to rtc::TimeMicros(), preferably read as soon as
   // possible when the frame is captured. It may have poor accuracy
   // due to poor resolution or scheduling delays. Returns the
   // translated timestamp.
-  int64_t TranslateTimestamp(int64_t camera_time_us, int64_t system_time_us);
+  int64_t TranslateTimestamp(int64_t capturer_time_us, int64_t system_time_us);
 
  protected:
-  // Update the estimated offset between camera time and system monotonic time.
+  // Update the estimated offset between capturer's time and system monotonic
-  int64_t UpdateOffset(int64_t camera_time_us, int64_t system_time_us);
+  // time.
+  int64_t UpdateOffset(int64_t capturer_time_us, int64_t system_time_us);
 
   // Clip timestamp, return value is always
   //    <= |system_time_us|, and
@@ -57,11 +59,11 @@ class RTC_EXPORT TimestampAligner {
  private:
   // State for the timestamp translation.
   int frames_seen_;
-  // Estimated offset between camera time and system monotonic time.
+  // Estimated offset between capturer's time and system monotonic time.
   int64_t offset_us_;
 
   // State for the ClipTimestamp method, applied after the filter.
-  // A large negative camera clock drift tends to push translated
+  // A large negative clock drift of the capturer tends to push translated
   // timestamps into the future. |clip_bias_us_| is subtracted from the
   // translated timestamps, to get them back from the future.
   int64_t clip_bias_us_;