media/capture/animated_content_sampler.h

   1 // Copyright (c) 2015 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_ANIMATED_CONTENT_SAMPLER_H_
   6 #define MEDIA_CAPTURE_ANIMATED_CONTENT_SAMPLER_H_
   7
   8 #include <deque>
   9
  10 #include "base/time/time.h"
  11 #include "media/base/media_export.h"
  12 #include "ui/gfx/geometry/rect.h"
  13
  14 namespace media {
  15
  16 // Analyzes a sequence of events to detect the presence of constant frame rate
  17 // animated content.  In the case where there are multiple regions of animated
  18 // content, AnimatedContentSampler will propose sampling the one having the
  19 // largest "smoothness" impact, according to human perception (e.g., a 24 FPS
  20 // video versus a 60 FPS busy spinner).
  21 //
  22 // In addition, AnimatedContentSampler will provide rewritten frame timestamps,
  23 // for downstream consumers, that are "truer" to the source content than to the
  24 // local presentation hardware.
  25 class MEDIA_EXPORT AnimatedContentSampler {
  26  public:
  27   explicit AnimatedContentSampler(base::TimeDelta min_capture_period);
  28   ~AnimatedContentSampler();
  29
  30   // Get/Set the target sampling period.  This is used to determine whether to
  31   // subsample the frames of animated content.
  32   base::TimeDelta target_sampling_period() const {
  33     return target_sampling_period_;
  34   }
  35   void SetTargetSamplingPeriod(base::TimeDelta period);
  36
  37   // Examines the given presentation event metadata, along with recent history,
  38   // to detect animated content, updating the state of this sampler.
  39   // |damage_rect| is the region of a frame about to be drawn, while
  40   // |event_time| refers to the frame's estimated presentation time.
  41   void ConsiderPresentationEvent(const gfx::Rect& damage_rect,
  42                                  base::TimeTicks event_time);
  43
  44   // Returns true if animated content has been detected and a decision has been
  45   // made about whether to sample the last event.
  46   bool HasProposal() const;
  47
  48   // Returns true if the last event considered should be sampled.
  49   bool ShouldSample() const;
  50
  51   // Returns a frame timestamp to provide to consumers of the sampled frame.
  52   // Only valid when ShouldSample() returns true.
  53   base::TimeTicks frame_timestamp() const { return frame_timestamp_; }
  54
  55   // Returns the current sampling period.  This can be treated as the estimated
  56   // duration of the frame to be sampled.  Only valid when HasProposal()
  57   // returns true.
  58   base::TimeDelta sampling_period() const { return sampling_period_; }
  59
  60   // Accessors to currently-detected animating region/period, for logging.
  61   const gfx::Rect& detected_region() const { return detected_region_; }
  62   base::TimeDelta detected_period() const { return detected_period_; }
  63
  64   // Records that a frame with the given |frame_timestamp| was sampled.  This
  65   // method should be called when *any* sampling is taken, even if it was not
  66   // proposed by AnimatedContentSampler.
  67   void RecordSample(base::TimeTicks frame_timestamp);
  68
  69  private:
  70   friend class AnimatedContentSamplerTest;
  71
  72   // Data structure for efficient online analysis of recent event history.
  73   struct Observation {
  74     gfx::Rect damage_rect;
  75     base::TimeTicks event_time;
  76
  77     Observation(const gfx::Rect& d, base::TimeTicks e)
  78         : damage_rect(d), event_time(e) {}
  79   };
  80   typedef std::deque<Observation> ObservationFifo;
  81
  82   // Adds an observation to |observations_|, and prunes-out the old ones.
  83   void AddObservation(const gfx::Rect& damage_rect, base::TimeTicks event_time);
  84
  85   // Returns the damage Rect that is responsible for the majority of the pixel
  86   // damage in recent event history, if there is such a Rect.  If there isn't,
  87   // this method could still return any Rect, so the caller must confirm the
  88   // returned Rect really is responsible for the majority of pixel damage.
  89   gfx::Rect ElectMajorityDamageRect() const;
  90
  91   // Analyzes the observations relative to the current |event_time| to detect
  92   // stable animating content.  If detected, returns true and sets the output
  93   // arguments to the region of the animating content and its mean frame
  94   // duration.
  95   bool AnalyzeObservations(base::TimeTicks event_time,
  96                            gfx::Rect* rect,
  97                            base::TimeDelta* period) const;
  98
  99   // Called by ConsiderPresentationEvent() when the current event is part of a
 100   // detected animation, to update |frame_timestamp_|.
 101   base::TimeTicks ComputeNextFrameTimestamp(base::TimeTicks event_time) const;
 102
 103   // When the animation frame rate is greater than the target sampling rate,
 104   // this function determines an integer division of the animation frame rate
 105   // that is closest to the target sampling rate.  Returns the inverse of that
 106   // result (the period).  If the animation frame rate is slower or the same as
 107   // the target sampling rate, this function just returns |animation_period|.
 108   static base::TimeDelta ComputeSamplingPeriod(
 109       base::TimeDelta animation_period,
 110       base::TimeDelta target_sampling_period,
 111       base::TimeDelta min_capture_period);
 112
 113   // The client expects frame timestamps to be at least this far apart.
 114   const base::TimeDelta min_capture_period_;
 115
 116   // A recent history of observations in chronological order, maintained by
 117   // AddObservation().
 118   ObservationFifo observations_;
 119
 120   // The region of currently-detected animated content.  If empty, that means
 121   // "not detected."
 122   gfx::Rect detected_region_;
 123
 124   // The mean frame duration of currently-detected animated content.  If zero,
 125   // that means "not detected."
 126   base::TimeDelta detected_period_;
 127
 128   // Target period between sampled frames.  This can be changed by the client at
 129   // any time (e.g., to sample high frame rate content at a lower rate).
 130   base::TimeDelta target_sampling_period_;
 131
 132   // The sampling period computed during the last call to
 133   // ConsiderPresentationEvent().
 134   base::TimeDelta sampling_period_;
 135
 136   // Indicates whether the last event caused animated content to be detected and
 137   // whether the current event should be sampled.
 138   enum {
 139     NOT_SAMPLING,
 140     START_SAMPLING,
 141     SHOULD_NOT_SAMPLE,
 142     SHOULD_SAMPLE
 143   } sampling_state_;
 144
 145   // A token bucket that is used to decide which subset of the frames containing
 146   // the animated content should be sampled.  Here, the smallest discrete unit
 147   // of time (one microsecond) equals one token; and, tokens are only taken from
 148   // the bucket when at least a full sampling period's worth are present.
 149   base::TimeDelta token_bucket_;
 150
 151   // The rewritten frame timestamp for the latest event.
 152   base::TimeTicks frame_timestamp_;
 153 };
 154
 155 }  // namespace media
 156
 157 #endif  // MEDIA_CAPTURE_ANIMATED_CONTENT_SAMPLER_H_