1 /* 2 * Copyright (c) 2016 The WebRTC Project Authors. All rights reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef RTC_BASE_TIMESTAMP_ALIGNER_H_ 12 #define RTC_BASE_TIMESTAMP_ALIGNER_H_ 13 14 #include <stdint.h> 15 16 #include "rtc_base/system/rtc_export.h" 17 18 namespace rtc { 19 20 // The TimestampAligner class helps translating timestamps of a capture system 21 // into the same timescale as is used by rtc::TimeMicros(). Some capture systems 22 // provide timestamps, which comes from the capturing hardware (camera or sound 23 // card) or stamped close to the capturing hardware. Such timestamps are more 24 // accurate (less jittery) than reading the system clock, but may have a 25 // different epoch and unknown clock drift. Frame timestamps in webrtc should 26 // use rtc::TimeMicros (system monotonic time), and this class provides a filter 27 // which lets us use the rtc::TimeMicros timescale, and at the same time take 28 // advantage of higher accuracy of the capturer's clock. 29 30 // This class is not thread safe, so all calls to it must be synchronized 31 // externally. 32 class RTC_EXPORT TimestampAligner { 33 public: 34 TimestampAligner(); 35 ~TimestampAligner(); 36 37 TimestampAligner(const TimestampAligner&) = delete; 38 TimestampAligner& operator=(const TimestampAligner&) = delete; 39 40 public: 41 // Translates timestamps of a capture system to the same timescale as is used 42 // by rtc::TimeMicros(). `capturer_time_us` is assumed to be accurate, but 43 // with an unknown epoch and clock drift. `system_time_us` is 44 // time according to rtc::TimeMicros(), preferably read as soon as 45 // possible when the frame is captured. It may have poor accuracy 46 // due to poor resolution or scheduling delays. Returns the 47 // translated timestamp. 48 int64_t TranslateTimestamp(int64_t capturer_time_us, int64_t system_time_us); 49 50 // Returns the translated timestamp without updating the states. This is to 51 // allow TimestampAligner to translate capturer time into system clock based 52 // on earlier observations. It won't guarantee monotonicity. 53 int64_t TranslateTimestamp(int64_t capturer_time_us) const; 54 55 protected: 56 // Update the estimated offset between capturer's time and system monotonic 57 // time. 58 int64_t UpdateOffset(int64_t capturer_time_us, int64_t system_time_us); 59 60 // Clip timestamp, return value is always 61 // <= `system_time_us`, and 62 // >= min(`prev_translated_time_us_` + `kMinFrameIntervalUs`, 63 // `system_time_us`). 64 int64_t ClipTimestamp(int64_t filtered_time_us, int64_t system_time_us); 65 66 private: 67 // State for the timestamp translation. 68 int frames_seen_; 69 // Estimated offset between capturer's time and system monotonic time. 70 int64_t offset_us_; 71 72 // State for the ClipTimestamp method, applied after the filter. 73 // A large negative clock drift of the capturer tends to push translated 74 // timestamps into the future. `clip_bias_us_` is subtracted from the 75 // translated timestamps, to get them back from the future. 76 int64_t clip_bias_us_; 77 // Used to ensure that translated timestamps are monotonous. 78 int64_t prev_translated_time_us_; 79 // Offset between `prev_translated_time_us_` and the corresponding capturer 80 // time. 81 int64_t prev_time_offset_us_; 82 }; 83 84 } // namespace rtc 85 86 #endif // RTC_BASE_TIMESTAMP_ALIGNER_H_ 87