media/capture/video_capture_oracle.h

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_CAPTURE_VIDEO_CAPTURE_ORACLE_H_
   6 #define MEDIA_CAPTURE_VIDEO_CAPTURE_ORACLE_H_
   7
   8 #include "base/callback_forward.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "base/time/time.h"
  11 #include "media/base/media_export.h"
  12 #include "media/capture/animated_content_sampler.h"
  13 #include "media/capture/smooth_event_sampler.h"
  14 #include "ui/gfx/geometry/rect.h"
  15
  16 namespace media {
  17
  18 // VideoCaptureOracle manages the producer-side throttling of captured frames
  19 // from a video capture device.  It is informed of every update by the device;
  20 // this empowers it to look into the future and decide if a particular frame
  21 // ought to be captured in order to achieve its target frame rate.
  22 class MEDIA_EXPORT VideoCaptureOracle {
  23  public:
  24   enum Event {
  25     kTimerPoll,
  26     kCompositorUpdate,
  27     kNumEvents,
  28   };
  29
  30   enum {
  31     // The recommended minimum amount of time between calls to
  32     // ObserveEventAndDecideCapture() for the kTimerPoll Event type.  Anything
  33     // lower than this isn't harmful, just wasteful.
  34     kMinTimerPollPeriodMillis = 125,  // 8 FPS
  35   };
  36
  37   explicit VideoCaptureOracle(base::TimeDelta min_capture_period);
  38   virtual ~VideoCaptureOracle();
  39
  40   // Record a event of type |event|, and decide whether the caller should do a
  41   // frame capture.  |damage_rect| is the region of a frame about to be drawn,
  42   // and may be an empty Rect, if this is not known.  If the caller accepts the
  43   // oracle's proposal, it should call RecordCapture() to indicate this.
  44   bool ObserveEventAndDecideCapture(Event event,
  45                                     const gfx::Rect& damage_rect,
  46                                     base::TimeTicks event_time);
  47
  48   // Record the start of a capture.  Returns a frame_number to be used with
  49   // CompleteCapture().
  50   int RecordCapture();
  51
  52   // Notify of the completion of a capture, and whether it was successful.
  53   // Returns true iff the captured frame should be delivered.  |frame_timestamp|
  54   // is set to the timestamp that should be provided to the consumer of the
  55   // frame.
  56   bool CompleteCapture(int frame_number,
  57                        bool capture_was_successful,
  58                        base::TimeTicks* frame_timestamp);
  59
  60   base::TimeDelta min_capture_period() const {
  61     return smoothing_sampler_.min_capture_period();
  62   }
  63
  64   // Returns the oracle's estimate of the duration of the next frame.  This
  65   // should be called just after ObserveEventAndDecideCapture(), and will only
  66   // be non-zero if the call returned true.
  67   base::TimeDelta estimated_frame_duration() const {
  68     return duration_of_next_frame_;
  69   }
  70
  71  private:
  72   // Retrieve/Assign a frame timestamp by capture |frame_number|.
  73   base::TimeTicks GetFrameTimestamp(int frame_number) const;
  74   void SetFrameTimestamp(int frame_number, base::TimeTicks timestamp);
  75
  76   // Incremented every time a paint or update event occurs.
  77   int next_frame_number_;
  78
  79   // Stores the last |event_time| from the last observation/decision.  Used to
  80   // sanity-check that event times are monotonically non-decreasing.
  81   base::TimeTicks last_event_time_[kNumEvents];
  82
  83   // Updated by the last call to ObserveEventAndDecideCapture() with the
  84   // estimated duration of the next frame to sample.  This is zero if the method
  85   // returned false.
  86   base::TimeDelta duration_of_next_frame_;
  87
  88   // Stores the frame number from the last successfully delivered frame.
  89   int last_successfully_delivered_frame_number_;
  90
  91   // Stores the number of pending frame captures.
  92   int num_frames_pending_;
  93
  94   // These track present/paint history and propose whether to sample each event
  95   // for capture.  |smoothing_sampler_| uses a "works for all" heuristic, while
  96   // |content_sampler_| specifically detects animated content (e.g., video
  97   // playback) and decides which events to sample to "lock into" that content.
  98   SmoothEventSampler smoothing_sampler_;
  99   AnimatedContentSampler content_sampler_;
 100
 101   // Recent history of frame timestamps proposed by VideoCaptureOracle.  This is
 102   // a ring-buffer, and should only be accessed by the Get/SetFrameTimestamp()
 103   // methods.
 104   enum { kMaxFrameTimestamps = 16 };
 105   base::TimeTicks frame_timestamps_[kMaxFrameTimestamps];
 106 };
 107
 108 }  // namespace media
 109
 110 #endif  // MEDIA_CAPTURE_VIDEO_CAPTURE_ORACLE_H_