From 37e388ad2dee184b94fb6afdb4bd11eeaf302120 Mon Sep 17 00:00:00 2001 From: Minyue Li Date: Thu, 5 Mar 2020 11:16:19 +0100 Subject: [PATCH] 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 Reviewed-by: Karl Wiberg Reviewed-by: Niels Moller Cr-Commit-Position: refs/heads/master@{#30710} --- rtc_base/timestamp_aligner.cc | 20 ++++++++++---------- rtc_base/timestamp_aligner.h | 32 +++++++++++++++++--------------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/rtc_base/timestamp_aligner.cc b/rtc_base/timestamp_aligner.cc index b797420f01..8bbcdb5a6d 100644 --- a/rtc_base/timestamp_aligner.cc +++ b/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 - // time from the camera. The camera is assumed to provide more + // Estimate the offset between system monotonic time and the capturer's + // 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) { diff --git a/rtc_base/timestamp_aligner.h b/rtc_base/timestamp_aligner.h index 151bcdccb1..48023ab44d 100644 --- a/rtc_base/timestamp_aligner.h +++ b/rtc_base/timestamp_aligner.h @@ -18,14 +18,15 @@ namespace rtc { -// The TimestampAligner class helps translating camera timestamps into -// the same timescale as is used by rtc::TimeMicros(). Some cameras -// have built in timestamping which is more accurate than reading the -// system clock, but using a different epoch and unknown clock drift. -// Frame timestamps in webrtc should use rtc::TimeMicros (system monotonic -// time), and this class provides a filter which lets us use the -// rtc::TimeMicros timescale, and at the same time take advantage of -// higher accuracy of the camera clock. +// The TimestampAligner class helps translating timestamps of a capture system +// into the same timescale as is used by rtc::TimeMicros(). Some capture systems +// provide timestamps, which comes from the capturing hardware (camera or sound +// card) or stamped close to the capturing hardware. Such timestamps are more +// accurate (less jittery) than reading the system clock, but may have a +// different epoch and unknown clock drift. Frame timestamps in webrtc should +// use rtc::TimeMicros (system monotonic time), and this class provides a filter +// 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 - // rtc::TimeMicros(). |camera_time_us| is assumed to be accurate, but + // Translates timestamps of a capture system to the same timescale as is used + // 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. - int64_t UpdateOffset(int64_t camera_time_us, int64_t system_time_us); + // Update the estimated offset between capturer's time and system monotonic + // 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_;