content/public/renderer/plugin_instance_throttler.h

   1 // Copyright 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 CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_
   6 #define CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_
   7
   8 #include "base/macros.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "content/common/content_export.h"
  11
  12 namespace blink {
  13 class WebPlugin;
  14 struct WebPluginParams;
  15 }
  16
  17 namespace gfx {
  18 class Size;
  19 }
  20
  21 class SkBitmap;
  22
  23 namespace content {
  24
  25 // This class manages the metric collection, throttling, and unthrottling of a
  26 // single peripheral plugin instance. If the Power Saver feature is disabled,
  27 // the plugin instance will never actually be throttled, but still collects
  28 // user interaction metrics.
  29 //
  30 // The process for throttling a plugin is as follows:
  31 // 1) Attempt to find a representative keyframe to display as a placeholder for
  32 //    the plugin.
  33 // 2) a) If a representative keyframe is found, throttle the plugin at that
  34 //       keyframe.
  35 //    b) If a representative keyframe is not found, throttle the plugin after a
  36 //       certain period of time.
  37 //
  38 // The plugin will then be unthrottled by receiving a mouse click from the user.
  39 //
  40 // To choose a representative keyframe, we first wait for a certain number of
  41 // "interesting" frames to be displayed by the plugin. A frame is called
  42 // interesting if it meets some heuristic. After we have seen a certain number
  43 // of interesting frames, we throttle the plugin and use that frame as the
  44 // representative keyframe.
  45 class CONTENT_EXPORT PluginInstanceThrottler {
  46  public:
  47   // How the throttled power saver is unthrottled, if ever.
  48   // These numeric values are used in UMA logs; do not change them.
  49   enum PowerSaverUnthrottleMethod {
  50     UNTHROTTLE_METHOD_NEVER = 0,
  51     UNTHROTTLE_METHOD_BY_CLICK = 1,
  52     UNTHROTTLE_METHOD_BY_WHITELIST = 2,
  53     UNTHROTTLE_METHOD_BY_AUDIO = 3,
  54     UNTHROTTLE_METHOD_BY_SIZE_CHANGE = 4,
  55     UNTHROTTLE_METHOD_NUM_ITEMS
  56   };
  57
  58   class Observer {
  59    public:
  60     // Guaranteed to be called before the throttle is engaged.
  61     virtual void OnKeyframeExtracted(const SkBitmap* bitmap) {}
  62
  63     virtual void OnThrottleStateChange() {}
  64
  65     virtual void OnPeripheralStateChange() {}
  66
  67     // Called when the plugin should be hidden due to a placeholder.
  68     virtual void OnHiddenForPlaceholder(bool hidden) {}
  69
  70     virtual void OnThrottlerDestroyed() {}
  71   };
  72
  73   static scoped_ptr<PluginInstanceThrottler> Create();
  74
  75   static void RecordUnthrottleMethodMetric(PowerSaverUnthrottleMethod method);
  76
  77   // Returns true if content is considered "large", and thus essential.
  78   // |width| and |height| are zoom and device scale independent logical pixels.
  79   static bool IsLargeContent(int width, int height);
  80
  81   virtual ~PluginInstanceThrottler() {}
  82
  83   virtual void AddObserver(Observer* observer) = 0;
  84   virtual void RemoveObserver(Observer* observer) = 0;
  85
  86   virtual bool IsThrottled() const = 0;
  87   virtual bool IsHiddenForPlaceholder() const = 0;
  88
  89   // Marks the plugin as essential. Unthrottles the plugin if already throttled.
  90   virtual void MarkPluginEssential(PowerSaverUnthrottleMethod method) = 0;
  91
  92   // Called by the placeholder when the plugin should temporarily be hidden.
  93   virtual void SetHiddenForPlaceholder(bool hidden) = 0;
  94
  95   virtual blink::WebPlugin* GetWebPlugin() const = 0;
  96
  97   // Gets the throttler's best estimate of the plugin's visible dimensions.
  98   virtual const gfx::Size& GetSize() const = 0;
  99
 100   // Throttler needs to know when the plugin audio is throttled, as this may
 101   // prevent the plugin from generating new frames.
 102   virtual void NotifyAudioThrottled() = 0;
 103
 104  protected:
 105   PluginInstanceThrottler() {}
 106
 107  private:
 108   DISALLOW_COPY_AND_ASSIGN(PluginInstanceThrottler);
 109 };
 110 }
 111
 112 #endif  // CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_