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_BY_SIZE_CHANGE = 4,
  56     UNTHROTTLE_METHOD_NUM_ITEMS
  57   };
  58
  59   class Observer {
  60    public:
  61     // Guaranteed to be called before the throttle is engaged.
  62     virtual void OnKeyframeExtracted(const SkBitmap* bitmap) {}
  63
  64     virtual void OnThrottleStateChange() {}
  65
  66     virtual void OnPeripheralStateChange() {}
  67
  68     // Called when the plugin should be hidden due to a placeholder.
  69     virtual void OnHiddenForPlaceholder(bool hidden) {}
  70
  71     virtual void OnThrottlerDestroyed() {}
  72   };
  73
  74   static scoped_ptr<PluginInstanceThrottler> Create();
  75
  76   static void RecordUnthrottleMethodMetric(PowerSaverUnthrottleMethod method);
  77
  78   // Returns true if content is considered "large", and thus essential.
  79   // |width| and |height| are zoom and device scale independent logical pixels.
  80   static bool IsLargeContent(int width, int height);
  81
  82   virtual ~PluginInstanceThrottler() {}
  83
  84   virtual void AddObserver(Observer* observer) = 0;
  85   virtual void RemoveObserver(Observer* observer) = 0;
  86
  87   virtual bool IsThrottled() const = 0;
  88   virtual bool IsHiddenForPlaceholder() const = 0;
  89
  90   // Marks the plugin as essential. Unthrottles the plugin if already throttled.
  91   virtual void MarkPluginEssential(PowerSaverUnthrottleMethod method) = 0;
  92
  93   // Called by the placeholder when the plugin should temporarily be hidden.
  94   virtual void SetHiddenForPlaceholder(bool hidden) = 0;
  95
  96   virtual blink::WebPlugin* GetWebPlugin() const = 0;
  97
  98   // Gets the throttler's best estimate of the plugin's visible dimensions.
  99   virtual const gfx::Size& GetSize() const = 0;
 100
 101   // Throttler needs to know when the plugin audio is throttled, as this may
 102   // prevent the plugin from generating new frames.
 103   virtual void NotifyAudioThrottled() = 0;
 104
 105  protected:
 106   PluginInstanceThrottler() {}
 107
 108  private:
 109   DISALLOW_COPY_AND_ASSIGN(PluginInstanceThrottler);
 110 };
 111 }
 112
 113 #endif  // CONTENT_PUBLIC_RENDERER_PLUGIN_INSTANCE_THROTTLER_H_