Add artwork display mode to PlayerView

This change deprecates `PlayerView.setUseArtwork(boolean)` and
introduces `setArtworkDisplayMode(mode)` and
`artworkDisplayMode="off|fit|fill"` instead.

- off: no artwork is displayed (like deprecated useArtwork=false)
- fit: letterbox like media (like deprecated useArtwork=true)
- fill: scales the artwork to fill the entire width/weight of the player view

#minor-release

PiperOrigin-RevId: 534167226
(cherry picked from commit 7f3f2fe0758e083cc5baf8781b1f1be20d32f052)

library/ui/src/main/java/com/google/android/exoplayer2/ui/StyledPlayerView.java

@@ -90,10 +90,11 @@ import org.checkerframework.checker.nullness.qual.RequiresNonNull;
  * The following attributes can be set on a StyledPlayerView when used in a layout XML file:
  *
  * <ul>
- *   <li><b>{@code use_artwork}</b> - Whether artwork is used if available in audio streams.
+ *   <li><b>{@code artwork_display_mode}</b> - Whether artwork is used if available in audio streams
+ *       and {@link ArtworkDisplayMode how it is displayed}.
  *       <ul>
- *         <li>Corresponding method: {@link #setUseArtwork(boolean)}
- *         <li>Default: {@code true}
+ *         <li>Corresponding method: {@link #setArtworkDisplayMode(int)}
+ *         <li>Default: {@link #ARTWORK_DISPLAY_MODE_FIT}
  *       </ul>
  *   <li><b>{@code default_artwork}</b> - Default artwork to use if no artwork available in audio
  *       streams.
@@ -199,6 +200,26 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
   }
 
   /**
+   * Determines the artwork display mode. One of {@link #ARTWORK_DISPLAY_MODE_OFF}, {@link
+   * #ARTWORK_DISPLAY_MODE_FIT} or {@link #ARTWORK_DISPLAY_MODE_FILL}.
+   */
+  @Documented
+  @Retention(RetentionPolicy.SOURCE)
+  @Target(TYPE_USE)
+  @IntDef({ARTWORK_DISPLAY_MODE_OFF, ARTWORK_DISPLAY_MODE_FIT, ARTWORK_DISPLAY_MODE_FILL})
+  public @interface ArtworkDisplayMode {}
+
+  /** No artwork is shown. */
+  public static final int ARTWORK_DISPLAY_MODE_OFF = 0;
+  /** The artwork is fit into the player view and centered creating a letterbox style. */
+  public static final int ARTWORK_DISPLAY_MODE_FIT = 1;
+  /**
+   * The artwork covers the entire space of the player view. If the aspect ratio of the image is
+   * different than the player view some areas of the image are cropped.
+   */
+  public static final int ARTWORK_DISPLAY_MODE_FILL = 2;
+
+  /**
    * Determines when the buffering view is shown. One of {@link #SHOW_BUFFERING_NEVER}, {@link
    * #SHOW_BUFFERING_WHEN_PLAYING} or {@link #SHOW_BUFFERING_ALWAYS}.
    */
@@ -251,7 +272,8 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
 
   @Nullable private FullscreenButtonClickListener fullscreenButtonClickListener;
 
-  private boolean useArtwork;
+  private @ArtworkDisplayMode int artworkDisplayMode;
+
   @Nullable private Drawable defaultArtwork;
   private @ShowBuffering int showBuffering;
   private boolean keepContentOnPlayerReset;
@@ -304,6 +326,7 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
     int shutterColor = 0;
     int playerLayoutId = R.layout.exo_styled_player_view;
     boolean useArtwork = true;
+    int artworkDisplayMode = ARTWORK_DISPLAY_MODE_FIT;
     int defaultArtworkId = 0;
     boolean useController = true;
     int surfaceType = SURFACE_TYPE_SURFACE_VIEW;
@@ -326,6 +349,8 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
         playerLayoutId =
             a.getResourceId(R.styleable.StyledPlayerView_player_layout_id, playerLayoutId);
         useArtwork = a.getBoolean(R.styleable.StyledPlayerView_use_artwork, useArtwork);
+        artworkDisplayMode =
+            a.getInt(R.styleable.StyledPlayerView_artwork_display_mode, artworkDisplayMode);
         defaultArtworkId =
             a.getResourceId(R.styleable.StyledPlayerView_default_artwork, defaultArtworkId);
         useController = a.getBoolean(R.styleable.StyledPlayerView_use_controller, useController);
@@ -420,7 +445,9 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
 
     // Artwork view.
     artworkView = findViewById(R.id.exo_artwork);
-    this.useArtwork = useArtwork && artworkView != null;
+    boolean isArtworkEnabled =
+        useArtwork && artworkDisplayMode != ARTWORK_DISPLAY_MODE_OFF && artworkView != null;
+    this.artworkDisplayMode = isArtworkEnabled ? artworkDisplayMode : ARTWORK_DISPLAY_MODE_OFF;
     if (defaultArtworkId != 0) {
       defaultArtwork = ContextCompat.getDrawable(getContext(), defaultArtworkId);
     }
@@ -558,8 +585,11 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
         } else if (surfaceView instanceof SurfaceView) {
           player.setVideoSurfaceView((SurfaceView) surfaceView);
         }
+        if (player.getCurrentTracks().isTypeSupported(C.TRACK_TYPE_VIDEO)) {
+          // If the player already is or was playing a video, onVideoSizeChanged isn't called.
           updateAspectRatio();
         }
+      }
       if (subtitleView != null && player.isCommandAvailable(COMMAND_GET_TEXT)) {
         subtitleView.setCues(player.getCurrentCues().cues);
       }
@@ -595,24 +625,36 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
     return contentFrame.getResizeMode();
   }
 
-  /** Returns whether artwork is displayed if present in the media. */
+  /**
+   * @deprecated Use {@link #getArtworkDisplayMode()} instead.
+   */
+  @Deprecated
   public boolean getUseArtwork() {
-    return useArtwork;
+    return this.artworkDisplayMode != ARTWORK_DISPLAY_MODE_OFF;
   }
 
   /**
-   * Sets whether artwork is displayed if present in the media.
-   *
-   * @param useArtwork Whether artwork is displayed.
+   * @deprecated Use {@link #setArtworkDisplayMode(int)} instead.
    */
+  @Deprecated
   public void setUseArtwork(boolean useArtwork) {
-    Assertions.checkState(!useArtwork || artworkView != null);
-    if (this.useArtwork != useArtwork) {
-      this.useArtwork = useArtwork;
+    setArtworkDisplayMode(useArtwork ? ARTWORK_DISPLAY_MODE_OFF : ARTWORK_DISPLAY_MODE_FIT);
+  }
+
+  /** Sets whether and how artwork is displayed if present in the media. */
+  public void setArtworkDisplayMode(@ArtworkDisplayMode int artworkDisplayMode) {
+    Assertions.checkState(artworkDisplayMode == ARTWORK_DISPLAY_MODE_OFF || artworkView != null);
+    if (this.artworkDisplayMode != artworkDisplayMode) {
+      this.artworkDisplayMode = artworkDisplayMode;
       updateForCurrentTrackSelections(/* isNewPlayer= */ false);
     }
   }
 
+  /** Returns the {@link ArtworkDisplayMode artwork display mode}. */
+  public @ArtworkDisplayMode int getArtworkDisplayMode() {
+    return artworkDisplayMode;
+  }
+
   /** Returns the default artwork to display. */
   @Nullable
   public Drawable getDefaultArtwork() {
@@ -1208,7 +1250,7 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
 
   @EnsuresNonNullIf(expression = "artworkView", result = true)
   private boolean useArtwork() {
-    if (useArtwork) {
+    if (artworkDisplayMode != ARTWORK_DISPLAY_MODE_OFF) {
       Assertions.checkStateNotNull(artworkView);
       return true;
     }
@@ -1329,8 +1371,14 @@ public class StyledPlayerView extends FrameLayout implements AdViewProvider {
       int drawableWidth = drawable.getIntrinsicWidth();
       int drawableHeight = drawable.getIntrinsicHeight();
       if (drawableWidth > 0 && drawableHeight > 0) {
-        float artworkAspectRatio = (float) drawableWidth / drawableHeight;
-        onContentAspectRatioChanged(contentFrame, artworkAspectRatio);
+        float artworkLayoutAspectRatio = (float) drawableWidth / drawableHeight;
+        ImageView.ScaleType scaleStyle = ImageView.ScaleType.FIT_XY;
+        if (artworkDisplayMode == ARTWORK_DISPLAY_MODE_FILL) {
+          artworkLayoutAspectRatio = (float) getWidth() / getHeight();
+          scaleStyle = ImageView.ScaleType.CENTER_CROP;
+        }
+        onContentAspectRatioChanged(contentFrame, artworkLayoutAspectRatio);
+        artworkView.setScaleType(scaleStyle);
         artworkView.setImageDrawable(drawable);
         artworkView.setVisibility(VISIBLE);
         return true;

library/ui/src/main/res/values/attrs.xml

@@ -42,6 +42,11 @@
 
   <!-- PlayerView and StyledPlayerView attributes -->
   <attr name="use_artwork" format="boolean"/>
+  <attr name="artwork_display_mode" format="enum">
+    <enum name="off" value="0"/>
+    <enum name="fit" value="1"/>
+    <enum name="fill" value="2"/>
+  </attr>
   <attr name="shutter_background_color" format="color"/>
   <attr name="default_artwork" format="reference"/>
   <attr name="use_controller" format="boolean"/>
@@ -93,6 +98,7 @@
 
   <declare-styleable name="StyledPlayerView">
     <attr name="use_artwork"/>
+    <attr name="artwork_display_mode"/>
     <attr name="shutter_background_color"/>
     <attr name="default_artwork"/>
     <attr name="use_controller"/>