animated_content_sampler.h 6.6 KB

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