From b8c1e223895ccdf04546a384496a7eda98e661cd Mon Sep 17 00:00:00 2001
From: andrewlewis <andrewlewis@google.com>
Date: Tue, 28 Nov 2023 05:27:45 -0800
Subject: [PATCH] Clarify threading-related comments in texture manager

In `ExternalTextureManager` fields are accessed from the GL thread and the class needs to be constructed on the GL thread.

Also visibly document threading requirement in the parent class.

PiperOrigin-RevId: 585941284
---
 .../media3/effect/ExternalTextureManager.java     | 15 ++-------------
 .../androidx/media3/effect/TextureManager.java    |  3 +--
 2 files changed, 3 insertions(+), 15 deletions(-)

diff --git a/libraries/effect/src/main/java/androidx/media3/effect/ExternalTextureManager.java b/libraries/effect/src/main/java/androidx/media3/effect/ExternalTextureManager.java
index 86c6e9ccbe..2625996f88 100644
--- a/libraries/effect/src/main/java/androidx/media3/effect/ExternalTextureManager.java
+++ b/libraries/effect/src/main/java/androidx/media3/effect/ExternalTextureManager.java
@@ -65,30 +65,21 @@ import java.util.concurrent.atomic.AtomicInteger;
   private final float[] textureTransformMatrix;
   private final Queue<FrameInfo> pendingFrames;
   private final ScheduledExecutorService forceEndOfStreamExecutorService;
-
-  // Created on any thread. Otherwise, read and written on the GL thread only.
   private final AtomicInteger externalShaderProgramInputCapacity;
+
   // Counts the frames that are registered before flush but are made available after flush.
-  // Read and written on the GL thread only.
   private int numberOfFramesToDropOnBecomingAvailable;
-
-  // Read and written on the GL thread only.
   private int availableFrameCount;
-
-  // Read and written on the GL thread only.
   private boolean currentInputStreamEnded;
 
   // The frame that is sent downstream and is not done processing yet.
-  // Read and written on the GL thread only.
   @Nullable private FrameInfo currentFrame;
 
   @Nullable private Future<?> forceSignalEndOfStreamFuture;
-
-  // Whether to reject frames from the SurfaceTexture. Accessed on the GL thread only.
   private boolean shouldRejectIncomingFrames;
 
   /**
-   * Creates a new instance.
+   * Creates a new instance. The caller's thread must have a current GL context.
    *
    * @param glObjectsProvider The {@link GlObjectsProvider} for using EGL and GLES.
    * @param externalShaderProgram The {@link ExternalShaderProgram} for which this {@code
@@ -227,8 +218,6 @@ import java.util.concurrent.atomic.AtomicInteger;
     forceEndOfStreamExecutorService.shutdownNow();
   }
 
-  // Methods that must be called on the GL thread.
-
   @Override
   protected void flush() {
     // A frame that is registered before flush may arrive after flush.
diff --git a/libraries/effect/src/main/java/androidx/media3/effect/TextureManager.java b/libraries/effect/src/main/java/androidx/media3/effect/TextureManager.java
index 5deb6489fc..f2a0c95152 100644
--- a/libraries/effect/src/main/java/androidx/media3/effect/TextureManager.java
+++ b/libraries/effect/src/main/java/androidx/media3/effect/TextureManager.java
@@ -152,8 +152,7 @@ import androidx.media3.common.util.TimestampIterator;
    */
   public abstract void release() throws VideoFrameProcessingException;
 
-  // Methods that must be called on the GL thread.
-
+  /** Clears any pending data. Must be called on the GL thread. */
   protected void flush() {
     synchronized (lock) {
       if (onFlushCompleteTask != null) {