Introduce Renderer.reset

- It's a no-op for now
- Renderers that want to support retaining resources will move
  some functionality from their disable() implementations into
  reset()
- ExoPlayerImplInternal will be updated to not always call reset()
  immediately after disable(), which is what will enable resources
  to actually be retained.

Issue: #2826

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=215729783

library/core/src/main/java/com/google/android/exoplayer2/BaseRenderer.java

@@ -153,6 +153,12 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
     onDisabled();
     onDisabled();
   }
   }
 
 
+  @Override
+  public final void reset() {
+    Assertions.checkState(state == STATE_DISABLED);
+    onReset();
+  }
+
   // RendererCapabilities implementation.
   // RendererCapabilities implementation.
 
 
   @Override
   @Override
@@ -247,6 +253,15 @@ public abstract class BaseRenderer implements Renderer, RendererCapabilities {
     // Do nothing.
     // Do nothing.
   }
   }
 
 
+  /**
+   * Called when the renderer is reset.
+   *
+   * <p>The default implementation is a no-op.
+   */
+  protected void onReset() {
+    // Do nothing.
+  }
+
   // Methods to be called by subclasses.
   // Methods to be called by subclasses.
 
 
   /** Returns the formats of the currently enabled stream. */
   /** Returns the formats of the currently enabled stream. */

library/core/src/main/java/com/google/android/exoplayer2/ExoPlayerImplInternal.java

@@ -989,6 +989,7 @@ import java.util.Collections;
     mediaClock.onRendererDisabled(renderer);
     mediaClock.onRendererDisabled(renderer);
     ensureStopped(renderer);
     ensureStopped(renderer);
     renderer.disable();
     renderer.disable();
+    renderer.reset();
   }
   }
 
 
   private void reselectTracksInternal() throws ExoPlaybackException {
   private void reselectTracksInternal() throws ExoPlaybackException {

library/core/src/main/java/com/google/android/exoplayer2/NoSampleRenderer.java

@@ -159,6 +159,12 @@ public abstract class NoSampleRenderer implements Renderer, RendererCapabilities
   }
   }
 
 
   @Override
   @Override
+  public final void reset() {
+    Assertions.checkState(state == STATE_DISABLED);
+    onReset();
+  }
+
+  @Override
   public boolean isReady() {
   public boolean isReady() {
     return true;
     return true;
   }
   }
@@ -260,6 +266,15 @@ public abstract class NoSampleRenderer implements Renderer, RendererCapabilities
     // Do nothing.
     // Do nothing.
   }
   }
 
 
+  /**
+   * Called when the renderer is reset.
+   *
+   * <p>The default implementation is a no-op.
+   */
+  protected void onReset() {
+    // Do nothing.
+  }
+
   // Methods to be called by subclasses.
   // Methods to be called by subclasses.
 
 
   /**
   /**

library/core/src/main/java/com/google/android/exoplayer2/Renderer.java

@@ -44,12 +44,16 @@ public interface Renderer extends PlayerMessage.Target {
   @IntDef({STATE_DISABLED, STATE_ENABLED, STATE_STARTED})
   @IntDef({STATE_DISABLED, STATE_ENABLED, STATE_STARTED})
   @interface State {}
   @interface State {}
   /**
   /**
-   * The renderer is disabled.
+   * The renderer is disabled. A renderer in this state may hold resources that it requires for
+   * rendering (e.g. media decoders), for use if it's subsequently enabled. {@link #reset()} can be
+   * called to force the renderer to release these resources.
    */
    */
   int STATE_DISABLED = 0;
   int STATE_DISABLED = 0;
   /**
   /**
-   * The renderer is enabled but not started. A renderer in this state is not actively rendering
-   * media, but will typically hold resources that it requires for rendering (e.g. media decoders).
+   * The renderer is enabled but not started. A renderer in this state may render media at the
+   * current position (e.g. an initial video frame), but the position will not advance. A renderer
+   * in this state will typically hold resources that it requires for rendering (e.g. media
+   * decoders).
    */
    */
   int STATE_ENABLED = 1;
   int STATE_ENABLED = 1;
   /**
   /**
@@ -279,4 +283,12 @@ public interface Renderer extends PlayerMessage.Target {
    */
    */
   void disable();
   void disable();
 
 
+  /**
+   * Forces the renderer to give up any resources (e.g. media decoders) that it may be holding. If
+   * the renderer is not holding any resources, the call is a no-op.
+   *
+   * <p>This method may be called when the renderer is in the following states: {@link
+   * #STATE_DISABLED}.
+   */
+  void reset();
 }
 }

library/core/src/main/java/com/google/android/exoplayer2/video/spherical/CameraMotionRenderer.java

@@ -72,12 +72,12 @@ public class CameraMotionRenderer extends BaseRenderer {
 
 
   @Override
   @Override
   protected void onPositionReset(long positionUs, boolean joining) throws ExoPlaybackException {
   protected void onPositionReset(long positionUs, boolean joining) throws ExoPlaybackException {
-    reset();
+    resetListener();
   }
   }
 
 
   @Override
   @Override
   protected void onDisabled() {
   protected void onDisabled() {
-    reset();
+    resetListener();
   }
   }
 
 
   @Override
   @Override
@@ -124,7 +124,7 @@ public class CameraMotionRenderer extends BaseRenderer {
     return result;
     return result;
   }
   }
 
 
-  private void reset() {
+  private void resetListener() {
     lastTimestampUs = 0;
     lastTimestampUs = 0;
     if (listener != null) {
     if (listener != null) {
       listener.onCameraMotionReset();
       listener.onCameraMotionReset();

library/core/src/test/java/com/google/android/exoplayer2/audio/SimpleDecoderAudioRendererTest.java

@@ -103,6 +103,7 @@ public class SimpleDecoderAudioRendererTest {
     }
     }
     verify(mockAudioSink, times(1)).playToEndOfStream();
     verify(mockAudioSink, times(1)).playToEndOfStream();
     audioRenderer.disable();
     audioRenderer.disable();
+    audioRenderer.reset();
     verify(mockAudioSink, times(1)).release();
     verify(mockAudioSink, times(1)).release();
   }
   }