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 GURL;
  22 class SkBitmap;
  23
  24 namespace content {
  25
  26 // This class manages the metric collection, throttling, and unthrottling of a
  27 // single peripheral plugin instance. If the Power Saver feature is disabled,
  28 // the plugin instance will never actually be throttled, but still collects
  29 // user interaction metrics.
  30 //
  31 // The process for throttling a plugin is as follows:
  32 // 1) Attempt to find a representative keyframe to display as a placeholder for
  33 //    the plugin.
  34 // 2) a) If a representative keyframe is found, throttle the plugin at that
  35 //       keyframe.
  36 //    b) If a representative keyframe is not found, throttle the plugin after a
  37 //       certain period of time.
  38 //
  39 // The plugin will then be unthrottled by receiving a mouse click from the user.
  40 //
  41 // To choose a representative keyframe, we first wait for a certain number of
  42 // "interesting" frames to be displayed by the plugin. A frame is called
  43 // interesting if it meets some heuristic. After we have seen a certain number
  44 // of interesting frames, we throttle the plugin and use that frame as the
  45 // representative keyframe.
  46 class CONTENT_EXPORT PluginInstanceThrottler {
  47  public:
  48   // How the throttled power saver is unthrottled, if ever.
  49   // These numeric values are used in UMA logs; do not change them.
  50   enum PowerSaverUnthrottleMethod {
  51     UNTHROTTLE_METHOD_NEVER = 0,
  52     UNTHROTTLE_METHOD_BY_CLICK = 1,
  53     UNTHROTTLE_METHOD_BY_WHITELIST = 2,
  54     UNTHROTTLE_METHOD_BY_AUDIO = 3,
  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     // Called when the plugin should be hidden due to a placeholder.
  66     virtual void OnHiddenForPlaceholder(bool hidden) {}
  67
  68     virtual void OnThrottlerDestroyed() {}
  69   };
  70
  71   static scoped_ptr<PluginInstanceThrottler> Create();
  72
  73   static void RecordUnthrottleMethodMetric(PowerSaverUnthrottleMethod method);
  74
  75   virtual ~PluginInstanceThrottler() {}
  76
  77   virtual void AddObserver(Observer* observer) = 0;
  78   virtual void RemoveObserver(Observer* observer) = 0;
  79
  80   virtual bool IsThrottled() const = 0;
  81   virtual bool IsHiddenForPlaceholder() const = 0;
  82
  83   // Marks the plugin as essential. Unthrottles the plugin if already throttled.
  84   virtual void MarkPluginEssential(PowerSaverUnthrottleMethod method) = 0;
  85
  86   // Called by the placeholder when the plugin should temporarily be hidden.
  87   virtual void SetHiddenForPlaceholder(bool hidden) = 0;
  88
  89   virtual blink::WebPlugin* GetWebPlugin() const = 0;
  90
  91   // Gets the throttler's best estimate of the plugin's visible dimensions.
  92   virtual const gfx::Size& GetSize() const = 0;
  93
  94   // Throttler needs to know when the plugin audio is throttled, as this may
  95   // prevent the plugin from generating new frames.
  96   virtual void NotifyAudioThrottled() = 0;
  97
  98  protected:
  99   PluginInstanceThrottler() {}
 100
 101  private:
 102   DISALLOW_COPY_AND_ASSIGN(PluginInstanceThrottler);
 103 };
 104 }
 105
 106 #endif  // CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_