Wait for first frame when using placeholder surface

We currently pretend to be ready when using a placeholder
surface irrespective of whether the renderer is actually
ready to immediately render when a surface is attached.

This causes issues in two ways:
 - Apps don't know when a player without a surface can be
   connected to a surface and immediately start playing
 - A paused player without a surface will use the 1 second
   default doSomeWork loop, causing any pending decoding
   to be extremely slow (see Issue: #1973).

The fix is to let the placeholder surface case use the same
paths as the regular surface and with marking the first
frame as available as soon as the codec output buffer for it
is pending and ready for release.

PiperOrigin-RevId: 737942496
(cherry picked from commit eef678f)

Author: tonihei

RELEASENOTES.md

@@ -1,9 +1,5 @@
 # Release notes
 
-### Unreleased changes
-
-
-
 ## 1.6
 
 ### 1.6.0-rc02 (2025-03-18)
@@ -18,6 +14,10 @@ This release includes the following changes since
 *   Audio:
     *   Add support for float PCM to `ChannelMappingAudioProcessor`.
     *   Add support for float PCM to `TrimmingAudioProcessor`.
+*   Video:
+    *   Fix issue where a player without a surface was ready immediately and
+        very slow decoding any pending frames
+        ([#1973](https://github.com/androidx/media/issues/1973)).
 *   Session:
     *   Fix bug where a stale notification stays visible when the playlist is
         cleared ([#2211](https://github.com/androidx/media/issues/2211)).

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/video/DefaultVideoSink.java

@@ -129,7 +129,7 @@ public void flush(boolean resetPosition) {
 
   @Override
   public boolean isReady(boolean rendererOtherwiseReady) {
-    return outputSurface == null || videoFrameReleaseControl.isReady(rendererOtherwiseReady);
+    return videoFrameReleaseControl.isReady(rendererOtherwiseReady);
   }
 
   @Override

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/video/MediaCodecVideoRenderer.java

@@ -990,7 +990,7 @@ public boolean isReady() {
     if (videoSink != null) {
       return videoSink.isReady(rendererOtherwiseReady);
     }
-    if (rendererOtherwiseReady && (getCodec() == null || displaySurface == null || tunneling)) {
+    if (rendererOtherwiseReady && (getCodec() == null || tunneling)) {
       // Not releasing frames.
       return true;
     }
@@ -1157,24 +1157,24 @@ private void setOutput(@Nullable Object output) throws ExoPlaybackException {
       if (displaySurface != null) {
         // If we know the video size, report it again immediately.
         maybeRenotifyVideoSizeChanged();
-        if (state == STATE_STARTED) {
-          // We want to "join" playback to prevent an intermediate buffering state in the player
-          // before we rendered the new first frame. Since there is no reason to believe the next
-          // frame is delayed and the renderer needs to catch up, we still request to render the
-          // next frame as soon as possible.
-          if (videoSink != null) {
-            videoSink.join(/* renderNextFrameImmediately= */ true);
-          } else {
-            videoFrameReleaseControl.join(/* renderNextFrameImmediately= */ true);
-          }
-        }
       } else {
         // The display surface has been removed.
         reportedVideoSize = null;
         if (videoSink != null) {
           videoSink.clearOutputSurfaceInfo();
         }
       }
+      if (state == STATE_STARTED) {
+        // We want to "join" playback to prevent an intermediate buffering state in the player
+        // before we rendered the new first frame. Since there is no reason to believe the next
+        // frame is delayed and the renderer needs to catch up, we still request to render the
+        // next frame as soon as possible.
+        if (videoSink != null) {
+          videoSink.join(/* renderNextFrameImmediately= */ true);
+        } else {
+          videoFrameReleaseControl.join(/* renderNextFrameImmediately= */ true);
+        }
+      }
       maybeSetupTunnelingForFirstFrame();
     } else if (displaySurface != null) {
       // The display surface is set and unchanged. If we know the video size and/or have already

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/video/VideoFrameReleaseControl.java

@@ -181,6 +181,7 @@ boolean shouldIgnoreFrame(
   private float playbackSpeed;
   private Clock clock;
   private boolean hasOutputSurface;
+  private boolean frameReadyWithoutSurface;
 
   /**
    * Creates an instance.
@@ -242,6 +243,7 @@ public void onProcessedStreamChange() {
   /** Called when the display surface changed. */
   public void setOutputSurface(@Nullable Surface outputSurface) {
     hasOutputSurface = outputSurface != null;
+    frameReadyWithoutSurface = false;
     frameReleaseHelper.onSurfaceChanged(outputSurface);
     lowerFirstFrameState(C.FIRST_FRAME_NOT_RENDERED);
   }
@@ -288,7 +290,9 @@ public void allowReleaseFirstFrameBeforeStarted() {
    * @return Whether the release control is ready.
    */
   public boolean isReady(boolean rendererOtherwiseReady) {
-    if (rendererOtherwiseReady && firstFrameState == C.FIRST_FRAME_RENDERED) {
+    if (rendererOtherwiseReady
+        && (firstFrameState == C.FIRST_FRAME_RENDERED
+            || (!hasOutputSurface && frameReadyWithoutSurface))) {
       // Ready. If we were joining then we've now joined, so clear the joining deadline.
       joiningDeadlineMs = C.TIME_UNSET;
       return true;
@@ -364,6 +368,7 @@ public void join(boolean renderNextFrameImmediately) {
       return FRAME_RELEASE_SKIP;
     }
     if (!hasOutputSurface) {
+      frameReadyWithoutSurface = true;
       // Skip frames in sync with playback, so we'll be at the right frame if a surface is set.
       if (frameTimingEvaluator.shouldIgnoreFrame(
           frameReleaseInfo.earlyUs,

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/video/MediaCodecVideoRendererTest.java

@@ -26,6 +26,7 @@
 import static androidx.media3.test.utils.TestUtil.createByteArray;
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
@@ -416,6 +417,49 @@ public void render_earlyWithoutSurfaceAndNotStarted_doesNotSkipBuffer() throws E
     assertThat(argumentDecoderCounters.getValue().skippedOutputBufferCount).isEqualTo(0);
   }
 
+  @Test
+  public void render_withNewSurfaceAndAlreadyReadyWithPlaceholder_canRenderFirstFrameImmediately()
+      throws Exception {
+    FakeSampleStream fakeSampleStream =
+        new FakeSampleStream(
+            new DefaultAllocator(/* trimOnReset= */ true, /* individualAllocationSize= */ 1024),
+            /* mediaSourceEventDispatcher= */ null,
+            DrmSessionManager.DRM_UNSUPPORTED,
+            new DrmSessionEventListener.EventDispatcher(),
+            /* initialFormat= */ VIDEO_H264,
+            ImmutableList.of(
+                oneByteSample(/* timeUs= */ 0, C.BUFFER_FLAG_KEY_FRAME),
+                oneByteSample(/* timeUs= */ 10_000),
+                oneByteSample(/* timeUs= */ 20_000),
+                oneByteSample(/* timeUs= */ 30_000),
+                END_OF_STREAM_ITEM));
+    fakeSampleStream.writeData(/* startPositionUs= */ 0);
+    // Set placeholder surface.
+    mediaCodecVideoRenderer.handleMessage(Renderer.MSG_SET_VIDEO_OUTPUT, null);
+    // Enable at a non-zero start position to ensure the renderer isn't ready with one render call.
+    mediaCodecVideoRenderer.enable(
+        RendererConfiguration.DEFAULT,
+        new Format[] {VIDEO_H264},
+        fakeSampleStream,
+        /* positionUs= */ 0,
+        /* joining= */ false,
+        /* mayRenderStartOfStream= */ true,
+        /* startPositionUs= */ 20_000,
+        /* offsetUs= */ 0,
+        /* mediaPeriodId= */ new MediaSource.MediaPeriodId(new Object()));
+    while (!mediaCodecVideoRenderer.isReady()) {
+      mediaCodecVideoRenderer.render(/* positionUs= */ 0, SystemClock.elapsedRealtime() * 1000);
+    }
+    ShadowLooper.idleMainLooper(); // Ensure all pending events are delivered.
+    verify(eventListener, never()).onRenderedFirstFrame(any(), anyLong());
+
+    mediaCodecVideoRenderer.handleMessage(Renderer.MSG_SET_VIDEO_OUTPUT, surface);
+    mediaCodecVideoRenderer.render(/* positionUs= */ 0, SystemClock.elapsedRealtime() * 1000);
+    ShadowLooper.idleMainLooper(); // Ensure all pending events are delivered.
+
+    verify(eventListener).onRenderedFirstFrame(any(), anyLong());
+  }
+
   @Test
   public void render_withBufferLimitEqualToNumberOfSamples_rendersLastFrameAfterEndOfStream()
       throws Exception {

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/video/VideoFrameReleaseControlTest.java

@@ -60,6 +60,46 @@ public void isReady_afterReleasingFrame_returnsTrue() {
     assertThat(videoFrameReleaseControl.isReady(/* rendererOtherwiseReady= */ true)).isTrue();
   }
 
+  @Test
+  public void isReady_withoutSurfaceFirstFrameNotReady_returnsFalse() throws Exception {
+    VideoFrameReleaseControl.FrameReleaseInfo frameReleaseInfo =
+        new VideoFrameReleaseControl.FrameReleaseInfo();
+    VideoFrameReleaseControl videoFrameReleaseControl = createVideoFrameReleaseControl();
+    videoFrameReleaseControl.setOutputSurface(/* outputSurface= */ null);
+
+    // Process decode-only frame to ensure it doesn't make the release control ready.
+    videoFrameReleaseControl.getFrameReleaseAction(
+        /* presentationTimeUs= */ 0,
+        /* positionUs= */ 0,
+        /* elapsedRealtimeUs= */ 0,
+        /* outputStreamStartPositionUs= */ 0,
+        /* isDecodeOnlyFrame= */ true,
+        /* isLastFrame= */ false,
+        frameReleaseInfo);
+
+    assertThat(videoFrameReleaseControl.isReady(/* otherwiseReady= */ true)).isFalse();
+  }
+
+  @Test
+  public void isReady_withoutSurfaceFirstFrameReady_returnsFalse() throws Exception {
+    VideoFrameReleaseControl.FrameReleaseInfo frameReleaseInfo =
+        new VideoFrameReleaseControl.FrameReleaseInfo();
+    VideoFrameReleaseControl videoFrameReleaseControl = createVideoFrameReleaseControl();
+    videoFrameReleaseControl.setOutputSurface(/* outputSurface= */ null);
+
+    // Process first frame.
+    videoFrameReleaseControl.getFrameReleaseAction(
+        /* presentationTimeUs= */ 0,
+        /* positionUs= */ 0,
+        /* elapsedRealtimeUs= */ 0,
+        /* outputStreamStartPositionUs= */ 0,
+        /* isDecodeOnlyFrame= */ false,
+        /* isLastFrame= */ false,
+        frameReleaseInfo);
+
+    assertThat(videoFrameReleaseControl.isReady(/* otherwiseReady= */ true)).isTrue();
+  }
+
   @Test
   public void isReady_withinJoiningDeadlineWhenRenderingNextFrameImmediately_returnsTrue() {
     FakeClock clock = new FakeClock(/* isAutoAdvancing= */ false);