third_party/libwebrtc/api/video/video_timing.h

   1 /*
   2  *  Copyright (c) 2017 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 API_VIDEO_VIDEO_TIMING_H_
  12 #define API_VIDEO_VIDEO_TIMING_H_
  13
  14 #include <stdint.h>
  15
  16 #include <limits>
  17 #include <string>
  18
  19 #include "api/units/time_delta.h"
  20
  21 namespace webrtc {
  22
  23 // Video timing timestamps in ms counted from capture_time_ms of a frame.
  24 // This structure represents data sent in video-timing RTP header extension.
  25 struct VideoSendTiming {
  26   enum TimingFrameFlags : uint8_t {
  27     kNotTriggered = 0,  // Timing info valid, but not to be transmitted.
  28                         // Used on send-side only.
  29     kTriggeredByTimer = 1 << 0,  // Frame marked for tracing by periodic timer.
  30     kTriggeredBySize = 1 << 1,   // Frame marked for tracing due to size.
  31     kInvalid = std::numeric_limits<uint8_t>::max()  // Invalid, ignore!
  32   };
  33
  34   // Returns |time_ms - base_ms| capped at max 16-bit value.
  35   // Used to fill this data structure as per
  36   // https://webrtc.org/experiments/rtp-hdrext/video-timing/ extension stores
  37   // 16-bit deltas of timestamps from packet capture time.
  38   static uint16_t GetDeltaCappedMs(int64_t base_ms, int64_t time_ms);
  39   static uint16_t GetDeltaCappedMs(TimeDelta delta);
  40
  41   uint16_t encode_start_delta_ms;
  42   uint16_t encode_finish_delta_ms;
  43   uint16_t packetization_finish_delta_ms;
  44   uint16_t pacer_exit_delta_ms;
  45   uint16_t network_timestamp_delta_ms;
  46   uint16_t network2_timestamp_delta_ms;
  47   uint8_t flags = TimingFrameFlags::kInvalid;
  48 };
  49
  50 // Used to report precise timings of a 'timing frames'. Contains all important
  51 // timestamps for a lifetime of that specific frame. Reported as a string via
  52 // GetStats(). Only frame which took the longest between two GetStats calls is
  53 // reported.
  54 struct TimingFrameInfo {
  55   TimingFrameInfo();
  56
  57   // Returns end-to-end delay of a frame, if sender and receiver timestamps are
  58   // synchronized, -1 otherwise.
  59   int64_t EndToEndDelay() const;
  60
  61   // Returns true if current frame took longer to process than `other` frame.
  62   // If other frame's clocks are not synchronized, current frame is always
  63   // preferred.
  64   bool IsLongerThan(const TimingFrameInfo& other) const;
  65
  66   // Returns true if flags are set to indicate this frame was marked for tracing
  67   // due to the size being outside some limit.
  68   bool IsOutlier() const;
  69
  70   // Returns true if flags are set to indicate this frame was marked fro tracing
  71   // due to cyclic timer.
  72   bool IsTimerTriggered() const;
  73
  74   // Returns true if the timing data is marked as invalid, in which case it
  75   // should be ignored.
  76   bool IsInvalid() const;
  77
  78   std::string ToString() const;
  79
  80   bool operator<(const TimingFrameInfo& other) const;
  81
  82   bool operator<=(const TimingFrameInfo& other) const;
  83
  84   uint32_t rtp_timestamp;  // Identifier of a frame.
  85   // All timestamps below are in local monotonous clock of a receiver.
  86   // If sender clock is not yet estimated, sender timestamps
  87   // (capture_time_ms ... pacer_exit_ms) are negative values, still
  88   // relatively correct.
  89   int64_t capture_time_ms;          // Captrue time of a frame.
  90   int64_t encode_start_ms;          // Encode start time.
  91   int64_t encode_finish_ms;         // Encode completion time.
  92   int64_t packetization_finish_ms;  // Time when frame was passed to pacer.
  93   int64_t pacer_exit_ms;  // Time when last packet was pushed out of pacer.
  94   // Two in-network RTP processor timestamps: meaning is application specific.
  95   int64_t network_timestamp_ms;
  96   int64_t network2_timestamp_ms;
  97   int64_t receive_start_ms;   // First received packet time.
  98   int64_t receive_finish_ms;  // Last received packet time.
  99   int64_t decode_start_ms;    // Decode start time.
 100   int64_t decode_finish_ms;   // Decode completion time.
 101   int64_t render_time_ms;     // Proposed render time to insure smooth playback.
 102
 103   uint8_t flags;  // Flags indicating validity and/or why tracing was triggered.
 104 };
 105
 106 // Minimum and maximum playout delay values from capture to render.
 107 // These are best effort values.
 108 //
 109 // A value < 0 indicates no change from previous valid value.
 110 //
 111 // min = max = 0 indicates that the receiver should try and render
 112 // frame as soon as possible.
 113 //
 114 // min = x, max = y indicates that the receiver is free to adapt
 115 // in the range (x, y) based on network jitter.
 116 struct VideoPlayoutDelay {
 117   VideoPlayoutDelay() = default;
 118   VideoPlayoutDelay(int min_ms, int max_ms) : min_ms(min_ms), max_ms(max_ms) {}
 119   int min_ms = -1;
 120   int max_ms = -1;
 121
 122   bool operator==(const VideoPlayoutDelay& rhs) const {
 123     return min_ms == rhs.min_ms && max_ms == rhs.max_ms;
 124   }
 125 };
 126
 127 // TODO(bugs.webrtc.org/7660): Old name, delete after downstream use is updated.
 128 using PlayoutDelay = VideoPlayoutDelay;
 129
 130 }  // namespace webrtc
 131
 132 #endif  // API_VIDEO_VIDEO_TIMING_H_