[Android] Add a way to request new Surfaces from SurfaceProducer and avoid SurfaceProducer returning invalid Surface (flutter#169899)

> [!NOTE]  
> For anyone reviewing this PR, see
flutter/packages#9360 for how I'd use the
`getSurface(boolean forceNewSurface)` method.

> [!NOTE]  
> For anyone coming across this PR post-landing, in the code review
process, I renamed `getSurface(boolean forceNewSurface)` to
`getForcedNewSurface()`.

### What this does
(1) Adds method `getSurface(boolean forceNewSurface)` to
`SurfaceProducer` that will force the creation of a new `Surface` when
`SurfaceProducer.getSurface()` is called.
(2) Fixes `SurfaceProducer` to avoid returning invalid `Surface`s when
`SurfaceProducer.getSurface()`/`getSurface(boolean forceNewSurface)` is
called.

### Why we should...

#### (1) Add `getSurface(boolean forceNewSurface)`

My motivation for adding this is directly tied to
flutter#155294. The
`camera_android_camerax` plugin supports a camera preview use case that
requires providing a `Surface` to in order to render the preview. It
does so via `SurfaceProducer`; we provide a `Surface` retrieved from
`SurfaceProducer.getSurface()` to the CameraX library to render a camera
preview, and when the camera preview is done, a callback that we provide
is called, reporting that `Surface` as used and that it now should be
released/invalidated (see
[`SurfaceRequest`](https://developer.android.com/reference/androidx/camera/core/SurfaceRequest),
[`SurfaceRequest.Result`](https://developer.android.com/reference/androidx/camera/core/SurfaceRequest#provideSurface(android.view.Surface,java.util.concurrent.Executor,androidx.core.util.Consumer%3Candroidx.camera.core.SurfaceRequest.Result%3E))).
However, the CameraX library [makes no
guarantees](https://developer.android.com/reference/androidx/camera/core/Preview.SurfaceProvider#onSurfaceRequested(androidx.camera.core.SurfaceRequest):~:text=The%20camera%20may%20repeatedly%20request%20surfaces%20throughout%20usage%20of%20a%20Preview%20use%20case%2C%20but%20only%20a%20single%20request%20will%20be%20active%20at%20a%20time.)
about when requests for new `Surface`s are made, so the following race
condition can happen:

1. CameraX requests a `Surface`
2. We provide `Surface` A from `SurfaceProducer.getSurface()`
3. The camera preview was paused; CameraX requests a new `Surface`
4. The camera preview is resumed
5. We provide `Surface` A from `SurfaceProducer.getSurface()` because it
is still technically valid
6. CameraX calls our callback and now `Surface` A is released/invalid

I believe `SurfaceProducer` currently has no way to handle the level of
complexity of `Surface` handling required for use cases like the
`camera_android_camerax` camera preview, where a `Surface` may be
invalidated between calls to `SurfaceProducer.getSurface()`. So,
`getSurface(boolean forceNewSurface)` can support these use cases.*

`getSurface(boolean forceNewSurface)` simply will force
`SurfaceProducer` to return a new `Surface` when
`SurfaceProducer.getSurface` is called versus potentially returning the
same `Surface` as the previous invocation.

For `camera_android_camerax`, see
flutter/packages#9360 for an example of how it
would be used.

*I'd like to note that I also played around with creating new
`SurfaceProducer`s to solve the camera problem, which _was_ successful
and probably could be generally for that use case, but I think it's
cleaner to support this functionality from within the same
`SurfaceProducer` since we can 🤷‍♀️ It also helps avoid the user from
needing to create/manage multiple Flutter `Texture`s, from my
understanding.

#### (2) Fix `SurfaceProducer.getSurface()`/`getSurface(boolean
forceNewSurface)` to never return an invalid `Surface`s

I noticed that `SurfaceProducer.getSurface()`/`getSurface(boolean
forceNewSurface)` does not check for `Surface` validity before returning
them while I was working on (1). Honestly, this just feels right? We
should ensure that a `Surface` is valid and can be used before returning
it and potentially confusing the user.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: camsim99

engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/renderer/FlutterRenderer.java

@@ -555,10 +555,10 @@ void close() {
       return (double) deltaNanos / 1000000.0;
     }
 
-    PerImageReader getOrCreatePerImageReader(ImageReader reader) {
+    private PerImageReader getOrCreatePerImageReader(ImageReader reader) {
       PerImageReader r = perImageReaders.get(reader);
       if (r == null) {
-        r = new PerImageReader(reader);
+        r = createPerImageReader(reader);
         perImageReaders.put(reader, r);
         imageReaderQueue.add(r);
         if (VERBOSE_LOGS) {
@@ -568,6 +568,11 @@ PerImageReader getOrCreatePerImageReader(ImageReader reader) {
       return r;
     }
 
+    @VisibleForTesting
+    public PerImageReader createPerImageReader(ImageReader reader) {
+      return new PerImageReader(reader);
+    }
+
     void pruneImageReaderQueue() {
       boolean change = false;
       // Prune nodes from the head of the ImageReader queue.
@@ -829,6 +834,12 @@ public Surface getSurface() {
       return pir.reader.getSurface();
     }
 
+    @Override
+    public Surface getForcedNewSurface() {
+      createNewReader = true;
+      return getSurface();
+    }
+
     @Override
     public void scheduleFrame() {
       if (VERBOSE_LOGS) {
@@ -855,17 +866,23 @@ public Image acquireLatestImage() {
 
     private PerImageReader getActiveReader() {
       synchronized (lock) {
-        if (createNewReader) {
-          createNewReader = false;
-          // Create a new ImageReader and add it to the queue.
-          ImageReader reader = createImageReader();
-          if (VERBOSE_LOGS) {
-            Log.i(
-                TAG, reader.hashCode() + " created w=" + requestedWidth + " h=" + requestedHeight);
+        if (!createNewReader) {
+          // Verify we don't need a new ImageReader anyway because its Surface has been invalidated.
+          PerImageReader lastPerImageReader = imageReaderQueue.peekLast();
+          Surface lastImageReaderSurface = lastPerImageReader.reader.getSurface();
+          boolean lastImageReaderHasValidSurface = lastImageReaderSurface.isValid();
+          if (lastImageReaderHasValidSurface) {
+            return lastPerImageReader;
           }
-          return getOrCreatePerImageReader(reader);
         }
-        return imageReaderQueue.peekLast();
+
+        createNewReader = false;
+        // Create a new ImageReader and add it to the queue.
+        ImageReader reader = createImageReader();
+        if (VERBOSE_LOGS) {
+          Log.i(TAG, reader.hashCode() + " created w=" + requestedWidth + " h=" + requestedHeight);
+        }
+        return getOrCreatePerImageReader(reader);
       }
     }
 
@@ -909,7 +926,8 @@ private ImageReader createImageReader29() {
           HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE);
     }
 
-    private ImageReader createImageReader() {
+    @VisibleForTesting
+    public ImageReader createImageReader() {
       if (Build.VERSION.SDK_INT >= API_LEVELS.API_33) {
         return createImageReader33();
       } else if (Build.VERSION.SDK_INT >= API_LEVELS.API_29) {

engine/src/flutter/shell/platform/android/io/flutter/embedding/engine/renderer/SurfaceTextureSurfaceProducer.java

@@ -5,6 +5,7 @@
 import android.view.Surface;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
+import androidx.annotation.VisibleForTesting;
 import io.flutter.embedding.engine.FlutterJNI;
 import io.flutter.view.TextureRegistry;
 
@@ -92,12 +93,23 @@ public int getHeight() {
 
   @Override
   public Surface getSurface() {
-    if (surface == null) {
-      surface = new Surface(texture.surfaceTexture());
+    if (surface == null || !surface.isValid()) {
+      surface = createSurface(texture.surfaceTexture());
     }
     return surface;
   }
 
+  @Override
+  public Surface getForcedNewSurface() {
+    surface = null;
+    return getSurface();
+  }
+
+  @VisibleForTesting
+  public Surface createSurface(SurfaceTexture surfaceTexture) {
+    return new Surface(surfaceTexture);
+  }
+
   @Override
   public void scheduleFrame() {
     flutterJNI.markTextureFrameAvailable(id);

engine/src/flutter/shell/platform/android/io/flutter/view/TextureRegistry.java

@@ -138,6 +138,24 @@ interface SurfaceProducer extends TextureEntry {
      */
     Surface getSurface();
 
+    /**
+     * Direct access to a surface, which will be newly created (and thus, different from any surface
+     * objects returned from previous calls to {@link #getSurface()} or {@link
+     * #getForcedNewSurface()}.
+     *
+     * <p>When using this API, you will usually need to implement {@link SurfaceProducer.Callback}
+     * and provide it to {@link #setCallback(Callback)} in order to be notified when an existing
+     * surface has been destroyed (such as when the application goes to the background) or a new
+     * surface has been created (such as when the application is resumed back to the foreground).
+     *
+     * <p>NOTE: You should not cache the returned surface but instead invoke {@code getSurface} each
+     * time you need to draw. The surface may change when the texture is resized or has its format
+     * changed.
+     *
+     * @return a Surface to use for a drawing target for various APIs.
+     */
+    Surface getForcedNewSurface();
+
     /**
      * Sets a callback that is notified when a previously created {@link Surface} returned by {@link
      * SurfaceProducer#getSurface()} is no longer valid due to being destroyed, or a new surface is

engine/src/flutter/shell/platform/android/test/io/flutter/embedding/engine/renderer/FlutterRendererTest.java

@@ -9,6 +9,7 @@
 import static org.junit.Assert.assertArrayEquals;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
@@ -21,12 +22,14 @@
 import static org.mockito.Mockito.spy;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
 import static org.robolectric.Shadows.shadowOf;
 
 import android.graphics.Canvas;
 import android.graphics.Rect;
 import android.graphics.SurfaceTexture;
 import android.media.Image;
+import android.media.ImageReader;
 import android.os.Looper;
 import android.view.Surface;
 import androidx.lifecycle.Lifecycle;
@@ -991,4 +994,72 @@ public void ImageReaderSurfaceProducerSchedulesFrameIfQueueNotEmpty() throws Exc
     // is now empty.
     verify(flutterRenderer, times(3)).scheduleEngineFrame();
   }
+
+  @Test
+  public void getSurface_doesNotReturnInvalidSurface() {
+    FlutterRenderer flutterRenderer = spy(engineRule.getFlutterEngine().getRenderer());
+    TextureRegistry.SurfaceProducer producer = flutterRenderer.createSurfaceProducer();
+    FlutterRenderer.ImageReaderSurfaceProducer spyImageReaderSurfaceProducer =
+        spy((FlutterRenderer.ImageReaderSurfaceProducer) producer);
+    ImageReader mockImageReader = mock(ImageReader.class);
+    ImageReader mockSecondImageReader = mock(ImageReader.class);
+    Surface firstMockSurface = mock(Surface.class);
+    Surface secondMockSurface = mock(Surface.class);
+
+    when(mockImageReader.getSurface()).thenReturn(firstMockSurface);
+    when(mockSecondImageReader.getSurface()).thenReturn(secondMockSurface);
+    when(firstMockSurface.isValid()).thenReturn(false);
+    when(spyImageReaderSurfaceProducer.createImageReader())
+        .thenReturn(mockImageReader)
+        .thenReturn(mockSecondImageReader);
+
+    Surface firstSurface = spyImageReaderSurfaceProducer.getSurface();
+    Surface secondSurface = spyImageReaderSurfaceProducer.getSurface();
+
+    assertNotEquals(firstSurface, secondSurface);
+    assertEquals(firstSurface, firstMockSurface);
+    assertEquals(secondSurface, secondMockSurface);
+  }
+
+  @Test
+  public void getSurface_consecutiveCallsReturnSameSurfaceIfStillValid() {
+    FlutterRenderer flutterRenderer = spy(engineRule.getFlutterEngine().getRenderer());
+    TextureRegistry.SurfaceProducer producer = flutterRenderer.createSurfaceProducer();
+    FlutterRenderer.ImageReaderSurfaceProducer spyImageReaderSurfaceProducer =
+        spy((FlutterRenderer.ImageReaderSurfaceProducer) producer);
+    ImageReader mockImageReader = mock(ImageReader.class);
+    Surface mockSurface = mock(Surface.class);
+
+    when(mockSurface.isValid()).thenReturn(true);
+    when(mockImageReader.getSurface()).thenReturn(mockSurface);
+    when(spyImageReaderSurfaceProducer.createImageReader()).thenReturn(mockImageReader);
+
+    Surface firstSurface = spyImageReaderSurfaceProducer.getSurface();
+    Surface secondSurface = spyImageReaderSurfaceProducer.getSurface();
+
+    assertEquals(firstSurface, secondSurface);
+    assertEquals(firstSurface, mockSurface);
+  }
+
+  @Test
+  public void getForcedNewSurface_returnsNewSurface() {
+    FlutterRenderer flutterRenderer = spy(engineRule.getFlutterEngine().getRenderer());
+    TextureRegistry.SurfaceProducer producer = flutterRenderer.createSurfaceProducer();
+
+    Surface firstSurface = producer.getSurface();
+    Surface secondSurface = producer.getForcedNewSurface();
+
+    assertNotEquals(firstSurface, secondSurface);
+  }
+
+  @Test
+  public void getSurface_doesNotReturnNewSurface() {
+    FlutterRenderer flutterRenderer = spy(engineRule.getFlutterEngine().getRenderer());
+    TextureRegistry.SurfaceProducer producer = flutterRenderer.createSurfaceProducer();
+
+    Surface firstSurface = producer.getSurface();
+    Surface secondSurface = producer.getSurface();
+
+    assertEquals(firstSurface, secondSurface);
+  }
 }

engine/src/flutter/shell/platform/android/test/io/flutter/embedding/engine/renderer/SurfaceTextureSurfaceProducerTest.java

@@ -7,8 +7,11 @@
 import static io.flutter.Build.API_LEVELS;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.when;
 import static org.robolectric.Shadows.shadowOf;
 
 import android.annotation.TargetApi;
@@ -19,6 +22,7 @@
 import android.view.Surface;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import io.flutter.embedding.engine.FlutterJNI;
+import io.flutter.view.TextureRegistry;
 import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -84,4 +88,77 @@ public void releaseWillReleaseSurface() {
     producer.release();
     assertFalse(surface.isValid());
   }
+
+  @Test
+  public void getSurface_doesNotReturnInvalidSurface() {
+    final FlutterRenderer flutterRenderer = new FlutterRenderer(fakeJNI);
+    final Handler handler = new Handler(Looper.getMainLooper());
+    final SurfaceTexture mockSurfaceTexture = mock(SurfaceTexture.class);
+    final TextureRegistry.SurfaceTextureEntry spyTexture =
+        spy(flutterRenderer.registerSurfaceTexture(mockSurfaceTexture));
+    final SurfaceTextureSurfaceProducer producerSpy =
+        spy(new SurfaceTextureSurfaceProducer(0, handler, fakeJNI, spyTexture));
+    final Surface firstMockSurface = mock(Surface.class);
+    final Surface secondMockSurface = mock(Surface.class);
+
+    when(spyTexture.surfaceTexture()).thenReturn(mockSurfaceTexture);
+    when(firstMockSurface.isValid()).thenReturn(false);
+    when(producerSpy.createSurface(mockSurfaceTexture))
+        .thenReturn(firstMockSurface)
+        .thenReturn(secondMockSurface);
+
+    final Surface firstSurface = producerSpy.getSurface();
+    final Surface secondSurface = producerSpy.getSurface();
+
+    assertNotEquals(firstSurface, secondSurface);
+  }
+
+  @Test
+  public void getSurface_consecutiveCallsReturnSameSurfaceIfStillValid() {
+    final FlutterRenderer flutterRenderer = new FlutterRenderer(fakeJNI);
+    final Handler handler = new Handler(Looper.getMainLooper());
+    final SurfaceTexture mockSurfaceTexture = mock(SurfaceTexture.class);
+    final TextureRegistry.SurfaceTextureEntry spyTexture =
+        spy(flutterRenderer.registerSurfaceTexture(mockSurfaceTexture));
+    final SurfaceTextureSurfaceProducer producerSpy =
+        spy(new SurfaceTextureSurfaceProducer(0, handler, fakeJNI, spyTexture));
+    final Surface mockSurface = mock(Surface.class);
+
+    when(spyTexture.surfaceTexture()).thenReturn(mockSurfaceTexture);
+    when(mockSurface.isValid()).thenReturn(true);
+    when(producerSpy.createSurface(mockSurfaceTexture)).thenReturn(mockSurface);
+
+    final Surface firstSurface = producerSpy.getSurface();
+    final Surface secondSurface = producerSpy.getSurface();
+
+    assertEquals(firstSurface, secondSurface);
+  }
+
+  @Test
+  public void getForcedNewSurface_returnsNewSurface() {
+    final FlutterRenderer flutterRenderer = new FlutterRenderer(fakeJNI);
+    final Handler handler = new Handler(Looper.getMainLooper());
+    final SurfaceTextureSurfaceProducer producer =
+        new SurfaceTextureSurfaceProducer(
+            0, handler, fakeJNI, flutterRenderer.registerSurfaceTexture(new SurfaceTexture(0)));
+
+    final Surface firstSurface = producer.getSurface();
+    final Surface secondSurface = producer.getForcedNewSurface();
+
+    assertNotEquals(firstSurface, secondSurface);
+  }
+
+  @Test
+  public void getSurface_doesNotReturnNewSurface() {
+    final FlutterRenderer flutterRenderer = new FlutterRenderer(fakeJNI);
+    final Handler handler = new Handler(Looper.getMainLooper());
+    final SurfaceTextureSurfaceProducer producer =
+        new SurfaceTextureSurfaceProducer(
+            0, handler, fakeJNI, flutterRenderer.registerSurfaceTexture(new SurfaceTexture(0)));
+
+    Surface firstSurface = producer.getSurface();
+    Surface secondSurface = producer.getSurface();
+
+    assertEquals(firstSurface, secondSurface);
+  }
 }

engine/src/flutter/shell/platform/android/test/io/flutter/plugin/platform/PlatformViewsControllerTest.java

@@ -1689,6 +1689,11 @@ public Surface getSurface() {
                 return null;
               }
 
+              @Override
+              public Surface getForcedNewSurface() {
+                return null;
+              }
+
               @Override
               public boolean handlesCropAndRotation() {
                 return false;