Transformer GL: Document lack of support for non-square pixels.

This may one day change, but at least for now, we don't intend
to support non-square pixels.

PiperOrigin-RevId: 417983516

libraries/transformer/src/androidTest/java/androidx/media3/transformer/FrameEditorTest.java

@@ -60,6 +60,8 @@ public final class FrameEditorTest {
   private static final int DEQUEUE_TIMEOUT_US = 5_000_000;
   /** Time to wait for the frame editor's input to be populated by the decoder, in milliseconds. */
   private static final int SURFACE_WAIT_MS = 1000;
+  /** The ratio of width over height, for each pixel in a frame. */
+  private static final float PIXEL_WIDTH_HEIGHT_RATIO = 1;
 
   private @MonotonicNonNull FrameEditor frameEditor;
   private @MonotonicNonNull ImageReader frameEditorOutputImageReader;
@@ -91,6 +93,7 @@ public final class FrameEditorTest {
               getApplicationContext(),
               width,
               height,
+              PIXEL_WIDTH_HEIGHT_RATIO,
               identityMatrix,
               frameEditorOutputImageReader.getSurface(),
               Transformer.DebugViewProvider.NONE);

libraries/transformer/src/main/java/androidx/media3/transformer/FrameEditor.java

@@ -47,6 +47,7 @@ import java.util.concurrent.atomic.AtomicInteger;
    * @param context A {@link Context}.
    * @param outputWidth The output width in pixels.
    * @param outputHeight The output height in pixels.
+   * @param pixelWidthHeightRatio The ratio of width over height, for each pixel.
    * @param transformationMatrix The transformation matrix to apply to each frame.
    * @param outputSurface The {@link Surface}.
    * @param debugViewProvider Provider for optional debug views to show intermediate output.
@@ -56,9 +57,22 @@ import java.util.concurrent.atomic.AtomicInteger;
       Context context,
       int outputWidth,
       int outputHeight,
+      float pixelWidthHeightRatio,
       Matrix transformationMatrix,
       Surface outputSurface,
-      Transformer.DebugViewProvider debugViewProvider) {
+      Transformer.DebugViewProvider debugViewProvider)
+      throws TransformationException {
+    if (pixelWidthHeightRatio != 1.0f) {
+      // TODO(http://b/211782176): Consider implementing support for non-square pixels.
+      throw new TransformationException(
+          "FrameEditor Error",
+          new IllegalArgumentException(
+              "Transformer's frame editor currently does not support frame edits on non-square"
+                  + " pixels. The pixelWidthHeightRatio is: "
+                  + pixelWidthHeightRatio),
+          TransformationException.ERROR_CODE_GL_INIT_FAILED);
+    }
+
     EGLDisplay eglDisplay = GlUtil.createEglDisplay();
     EGLContext eglContext = GlUtil.createEglContext(eglDisplay);
     EGLSurface eglSurface = GlUtil.getEglSurface(eglDisplay, outputSurface);

libraries/transformer/src/main/java/androidx/media3/transformer/VideoSamplePipeline.java

@@ -104,6 +104,7 @@ import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
               context,
               outputWidth,
               outputHeight,
+              inputFormat.pixelWidthHeightRatio,
               transformationRequest.transformationMatrix,
               /* outputSurface= */ checkNotNull(encoder.getInputSurface()),
               debugViewProvider);