From fc9900c483c69c71af7566c7213f7a97851bbf8b Mon Sep 17 00:00:00 2001
From: andrewlewis <andrewlewis@google.com>
Date: Tue, 16 Jan 2024 04:48:57 -0800
Subject: [PATCH] Document `setVideoEffects` surface limitation

`Surface`s don't expose their size via Java APIs. Recommend apps pass a
`SurfaceView` (which is preferable to `TextureView` as it's more efficient)
or `SurfaceHolder` so they benefit from the player automatically passing the
size down to the video renderer via `MSG_SET_VIDEO_OUTPUT_RESOLUTION`.

PiperOrigin-RevId: 598804258
---
 .../main/java/androidx/media3/exoplayer/ExoPlayer.java   | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java
index 96b47c45f2..d17820a71f 100644
--- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java
+++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java
@@ -1565,14 +1565,19 @@ public interface ExoPlayer extends Player {
    * Sets a {@link List} of {@linkplain Effect video effects} that will be applied to each video
    * frame.
    *
+   * <p>If {@linkplain #setVideoSurface passing a surface to the player directly}, the output
+   * resolution needs to be signaled by passing a renderer message with type {@link
+   * Renderer#MSG_SET_VIDEO_OUTPUT_RESOLUTION} after calling this method. For {@link SurfaceView},
+   * {@link TextureView} and {@link SurfaceHolder} output this happens automatically.
+   *
    * <p>The following limitations exist for using {@linkplain Effect video effects}:
    *
    * <ul>
    *   <li>This feature works only with the default {@link MediaCodecVideoRenderer} and not custom
    *       or extension {@linkplain Renderer video renderers}.
    *   <li>This feature does not work with {@linkplain Effect effects} updating the timestamps.
-   *   <li>This feature does not work with DRM-protected contents.
-   *   <li>This method should be called before calling {@link #prepare}.
+   *   <li>This feature does not work with DRM-protected content.
+   *   <li>This method should be called before calling {@link #prepare()}.
    * </ul>
    *
    * @param videoEffects The {@link List} of {@linkplain Effect video effects} to apply.