Clarify the thread requirements of a SurfaceView or SurfaceHolder

Issue: #9005
PiperOrigin-RevId: 382765045

library/common/src/main/java/com/google/android/exoplayer2/Player.java

@@ -2029,6 +2029,9 @@ public interface Player {
    * Sets the {@link SurfaceHolder} that holds the {@link Surface} onto which video will be
    * rendered. The player will track the lifecycle of the surface automatically.
    *
+   * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
+   * associated with {@link #getApplicationLooper()}.
+   *
    * @param surfaceHolder The surface holder.
    */
   void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
@@ -2045,6 +2048,9 @@ public interface Player {
    * Sets the {@link SurfaceView} onto which video will be rendered. The player will track the
    * lifecycle of the surface automatically.
    *
+   * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
+   * associated with {@link #getApplicationLooper()}.
+   *
    * @param surfaceView The surface view.
    */
   void setVideoSurfaceView(@Nullable SurfaceView surfaceView);
@@ -2061,6 +2067,9 @@ public interface Player {
    * Sets the {@link TextureView} onto which video will be rendered. The player will track the
    * lifecycle of the surface automatically.
    *
+   * <p>The thread that calls the {@link TextureView.SurfaceTextureListener} methods must be the
+   * thread associated with {@link #getApplicationLooper()}.
+   *
    * @param textureView The texture view.
    */
   void setVideoTextureView(@Nullable TextureView textureView);

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

@@ -334,6 +334,9 @@ public interface ExoPlayer extends Player {
      * Sets the {@link SurfaceHolder} that holds the {@link Surface} onto which video will be
      * rendered. The player will track the lifecycle of the surface automatically.
      *
+     * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
+     * associated with {@link #getApplicationLooper()}.
+     *
      * @param surfaceHolder The surface holder.
      */
     void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
@@ -350,6 +353,9 @@ public interface ExoPlayer extends Player {
      * Sets the {@link SurfaceView} onto which video will be rendered. The player will track the
      * lifecycle of the surface automatically.
      *
+     * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
+     * associated with {@link #getApplicationLooper()}.
+     *
      * @param surfaceView The surface view.
      */
     void setVideoSurfaceView(@Nullable SurfaceView surfaceView);
@@ -366,6 +372,9 @@ public interface ExoPlayer extends Player {
      * Sets the {@link TextureView} onto which video will be rendered. The player will track the
      * lifecycle of the surface automatically.
      *
+     * <p>The thread that calls the {@link TextureView.SurfaceTextureListener} methods must be the
+     * thread associated with {@link #getApplicationLooper()}.
+     *
      * @param textureView The texture view.
      */
     void setVideoTextureView(@Nullable TextureView textureView);