FrameProcessor: Improve PresentationFrameProcessor javadocs.

PiperOrigin-RevId: 442835160

library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/PresentationFrameProcessorPixelTest.java

@@ -182,7 +182,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_scaleToFit_narrow";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(1f, PresentationFrameProcessor.SCALE_TO_FIT)
+            .setAspectRatio(1f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);
@@ -211,7 +211,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_scaleToFit_wide";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(2f, PresentationFrameProcessor.SCALE_TO_FIT)
+            .setAspectRatio(2f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);
@@ -240,7 +240,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_scaleToFitWithCrop_narrow";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(1f, PresentationFrameProcessor.SCALE_TO_FIT_WITH_CROP)
+            .setAspectRatio(1f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT_WITH_CROP)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);
@@ -269,7 +269,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_scaleToFitWithCrop_wide";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(2f, PresentationFrameProcessor.SCALE_TO_FIT_WITH_CROP)
+            .setAspectRatio(2f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT_WITH_CROP)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);
@@ -298,7 +298,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_stretchToFit_narrow";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(1f, PresentationFrameProcessor.STRETCH_TO_FIT)
+            .setAspectRatio(1f, PresentationFrameProcessor.LAYOUT_STRETCH_TO_FIT)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);
@@ -327,7 +327,7 @@ public final class PresentationFrameProcessorPixelTest {
     String testId = "drawFrame_changeAspectRatio_stretchToFit_wide";
     presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(2f, PresentationFrameProcessor.STRETCH_TO_FIT)
+            .setAspectRatio(2f, PresentationFrameProcessor.LAYOUT_STRETCH_TO_FIT)
             .build();
     presentationFrameProcessor.initialize(
         getApplicationContext(), inputTexId, inputWidth, inputHeight);

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/AdvancedFrameProcessor.java

@@ -27,11 +27,14 @@ import java.io.IOException;
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
 
 /**
- * Applies a transformation matrix in the vertex shader.
+ * Applies a transformation matrix in the vertex shader, and copies input pixels into an output
+ * frame based on their locations after applying this matrix.
  *
  * <p>Operations are done on normalized device coordinates (-1 to 1 on x and y axes). No automatic
  * adjustments (like done in {@link ScaleToFitFrameProcessor}) are applied on the transformation.
- * Width and height are not modified. The background color will default to black.
+ * Width and height are not modified.
+ *
+ * <p>The background color of the output frame will be black.
  */
 @SuppressWarnings("FunctionalInterfaceClash") // b/228192298
 public final class AdvancedFrameProcessor implements GlFrameProcessor {

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/GlFrameProcessor.java

@@ -20,7 +20,8 @@ import android.util.Size;
 import java.io.IOException;
 
 /**
- * Manages a GLSL shader program for processing a frame.
+ * Manages a GLSL shader program for processing a frame. Implementations generally copy input pixels
+ * into an output frame, with changes to pixels specific to the implementation.
  *
  * <p>Methods must be called in the following order:
  *

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/ScaleToFitFrameProcessor.java

@@ -30,9 +30,12 @@ import org.checkerframework.checker.nullness.qual.EnsuresNonNull;
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
 
 /**
- * Applies a simple rotation and/or scale in the vertex shader. All input frames' pixels will be
- * preserved, potentially changing the width and height of the frame by scaling dimensions to fit.
- * The background color will default to black.
+ * Applies a simple rotation and/or scale in the vertex shader.
+ *
+ * <p>All input frames' pixels will be preserved and copied into an output frame, potentially
+ * changing the width and height of the frame by scaling dimensions to fit.
+ *
+ * <p>The background color of the output frame will be black.
  */
 public final class ScaleToFitFrameProcessor implements GlFrameProcessor {
 

library/transformer/src/main/java/com/google/android/exoplayer2/transformer/TransformationRequest.java

@@ -100,7 +100,8 @@ public final class TransformationRequest {
      * Sets the x and y axis scaling factors to apply to each frame's width and height, stretching
      * the video along these axes appropriately.
      *
-     * <p>The values default to 1, which corresponds to not scaling along both axes.
+     * <p>The default value for {@code scaleX} and {@code scaleY}, 1, corresponds to not scaling
+     * along the x and y axes, respectively.
      *
      * @param scaleX The multiplier by which the frame will scale horizontally, along the x-axis.
      * @param scaleY The multiplier by which the frame will scale vertically, along the y-axis.
@@ -137,7 +138,7 @@ public final class TransformationRequest {
      *
      * <p>For example, a 1920x1440 video can be scaled to 640x480 by calling setResolution(480).
      *
-     * <p>The default value {@link C#LENGTH_UNSET} leaves the width and height unchanged unless
+     * <p>The default value, {@link C#LENGTH_UNSET}, leaves the width and height unchanged unless
      * {@linkplain #setScale(float,float) scaling} or @linkplain #setRotationDegrees(float)
      * rotation} are requested.
      *

library/transformer/src/test/java/com/google/android/exoplayer2/transformer/PresentationFrameProcessorTest.java

@@ -175,7 +175,7 @@ public final class PresentationFrameProcessorTest {
     float aspectRatio = 2f;
     PresentationFrameProcessor presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(aspectRatio, PresentationFrameProcessor.SCALE_TO_FIT)
+            .setAspectRatio(aspectRatio, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT)
             .build();
 
     presentationFrameProcessor.configureOutputSizeAndTransformationMatrix(inputWidth, inputHeight);
@@ -194,7 +194,7 @@ public final class PresentationFrameProcessorTest {
     int requestedHeight = 100;
     PresentationFrameProcessor presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(aspectRatio, PresentationFrameProcessor.SCALE_TO_FIT)
+            .setAspectRatio(aspectRatio, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT)
             .setResolution(requestedHeight)
             .build();
 
@@ -210,7 +210,7 @@ public final class PresentationFrameProcessorTest {
   public void getOutputSize_setAspectRatioAndCrop_throwsIllegalStateException() {
     PresentationFrameProcessor.Builder presentationFrameProcessor =
         new PresentationFrameProcessor.Builder()
-            .setAspectRatio(/* aspectRatio= */ 2f, PresentationFrameProcessor.SCALE_TO_FIT);
+            .setAspectRatio(/* aspectRatio= */ 2f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT);
 
     assertThrows(
         IllegalStateException.class,
@@ -229,7 +229,7 @@ public final class PresentationFrameProcessorTest {
         IllegalStateException.class,
         () ->
             presentationFrameProcessor.setAspectRatio(
-                /* aspectRatio= */ 2f, PresentationFrameProcessor.SCALE_TO_FIT));
+                /* aspectRatio= */ 2f, PresentationFrameProcessor.LAYOUT_SCALE_TO_FIT));
   }
 
   @Test