Expand suspension of idle media players to all platforms.

media/blink/webmediaplayer_delegate.h

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef MEDIA_BLINK_WEBMEDIAPLAYER_DELEGATE_H_
 #define MEDIA_BLINK_WEBMEDIAPLAYER_DELEGATE_H_
 
 namespace blink {
 class WebMediaPlayer;
 }
 namespace media {
 
 // An interface to allow a WebMediaPlayer to communicate changes of state to
 // objects that need to know.
 class WebMediaPlayerDelegate {
  public:
   class Observer {
    public:
-    // Called when the WebMediaPlayer is no longer in the foreground.  Audio may
-    // continue in the background unless |must_suspend| is true.
-    virtual void OnHidden(bool must_suspend) = 0;
+    // Called when the WebMediaPlayer enters the background or foreground
+    // respectively.
+    virtual void OnHidden() = 0;
+    virtual void OnShown() = 0;
 
-    virtual void OnShown() = 0;
+    // Called when a WebMediaPlayer instance is asked to release any held
+    // resources.  If |must_suspend| is false, the player may continue to play
+    // background audio.  If |must_suspend| is true, after releasing resources,
+    // players must call WebMediaPlayerDelegate::PlayerGone().

[xhwang, 2016/03/07 19:13:58]

It seems PlayerGone() may also be called in OnHidden() or OnSuspend(false). We
should make this more clear.

[DaleCurtis, 2016/03/09 02:56:13]

Done.

+    virtual void OnSuspend(bool must_suspend) = 0;

[xhwang, 2016/03/07 19:13:58]

It seems there's some overlap between OnHidden() and OnSuspend(). For example,
when a player enters background and we want to suspend video but keep playing
background audio, should we call OnHidden(), or OnSuspend(false)?

[DaleCurtis, 2016/03/07 19:23:07]

With this change OnHidden() should only ever be called for transitions into the
background. Likewise, OnSuspend() will be called only in cases where we're
requesting suspend for release of idle resources or requiring suspend for a
pending undoable tab closure.

sandersd@ suggested some time ago that instead of having a bool we have an enum
like

SuspendReason { OPTIONAL_FOR_IDLE_RESOURCES, MANDATORY_FOR_PENDING_DESTRUCTION }

I couldn't come up with good names so I kept the bool instead, but I'm open to
suggestions :)

+
     virtual void OnPlay() = 0;
     virtual void OnPause() = 0;
 
     // Playout volume should be set to current_volume * multiplier.  The range
     // is [0, 1] and is typically 1.
     virtual void OnVolumeMultiplierUpdate(double multiplier) = 0;
   };
 
   WebMediaPlayerDelegate() {}
 
@@ skipping 20 matching lines @@
   // Returns whether the render frame is currently hidden.
   virtual bool IsHidden() = 0;
 
  protected:
   virtual ~WebMediaPlayerDelegate() {}
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BLINK_WEBMEDIAPLAYER_DELEGATE_H_