Merge "HeifWriter / AvifWriter: fix Java doc" into androidx-main

DichenZhang1 · Gerrit Code Review · commit e8ca1c724a7b · 2024-09-11T17:47:30.000Z
diff --git a/heifwriter/heifwriter/src/main/java/androidx/heifwriter/AvifWriter.java b/heifwriter/heifwriter/src/main/java/androidx/heifwriter/AvifWriter.java
@@ -291,6 +291,112 @@ private Builder(String path, FileDescriptor fd,
         }
     }
 
+    /**
+     * Start the avif writer. Can only be called once.
+     *
+     * @throws IllegalStateException if called more than once.
+     */
+    @Override
+    public void start() {
+        super.start();
+    }
+
+    /**
+     * Add one YUV buffer to the avif file.
+     *
+     * @param format The YUV format as defined in {@link android.graphics.ImageFormat}, currently
+     *               only support YUV_420_888.
+     *
+     * @param data byte array containing the YUV data. If the format has more than one planes,
+     *             they must be concatenated.
+     *
+     * @throws IllegalStateException if not started or not configured to use buffer input.
+     */
+    @Override
+    public void addYuvBuffer(int format, @NonNull byte[] data) {
+        super.addYuvBuffer(format, data);
+    }
+
+    /**
+     * Retrieves the input surface for encoding.
+     *
+     * @return the input surface if configured to use surface input.
+     *
+     * @throws IllegalStateException if called after start or not configured to use surface input.
+     */
+    @Override
+    public @NonNull Surface getInputSurface() {
+        return super.getInputSurface();
+    }
+
+    /**
+     * Set the timestamp (in nano seconds) of the last input frame to encode.
+     *
+     * This call is only valid for surface input. Client can use this to stop the avif writer
+     * earlier before the maximum number of images are written. If not called, the writer will
+     * only stop when the maximum number of images are written.
+     *
+     * @param timestampNs timestamp (in nano seconds) of the last frame that will be written to the
+     *                    avif file. Frames with timestamps larger than the specified value will not
+     *                    be written. However, if a frame already started encoding when this is set,
+     *                    all tiles within that frame will be encoded.
+     *
+     * @throws IllegalStateException if not started or not configured to use surface input.
+     */
+    @Override
+    public void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs) {
+        super.setInputEndOfStreamTimestamp(timestampNs);
+    }
+
+    /**
+     * Add one bitmap to the avif file.
+     *
+     * @param bitmap the bitmap to be added to the file.
+     * @throws IllegalStateException if not started or not configured to use bitmap input.
+     */
+    @Override
+    public void addBitmap(@NonNull Bitmap bitmap) {
+        super.addBitmap(bitmap);
+    }
+
+    /**
+     * Add Exif data for the specified image. The data must be a valid Exif data block,
+     * starting with "Exif\0\0" followed by the TIFF header (See JEITA CP-3451C Section 4.5.2.)
+     *
+     * @param imageIndex index of the image, must be a valid index for the max number of image
+     *                   specified by {@link Builder#setMaxImages(int)}.
+     * @param exifData byte buffer containing a Exif data block.
+     * @param offset offset of the Exif data block within exifData.
+     * @param length length of the Exif data block.
+     */
+    @Override
+    public void addExifData(int imageIndex, @NonNull byte[] exifData, int offset, int length) {
+        super.addExifData(imageIndex, exifData, offset, length);
+    }
+
+    /**
+     * Stop the avif writer synchronously. Throws exception if the writer didn't finish writing
+     * successfully. Upon a success return:
+     *
+     * - For buffer and bitmap inputs, all images sent before stop will be written.
+     *
+     * - For surface input, images with timestamp on or before that specified in
+     *   {@link #setInputEndOfStreamTimestamp(long)} will be written. In case where
+     *   {@link #setInputEndOfStreamTimestamp(long)} was never called, stop will block
+     *   until maximum number of images are received.
+     *
+     * @param timeoutMs Maximum time (in microsec) to wait for the writer to complete, with zero
+     *                  indicating waiting indefinitely.
+     * @see #setInputEndOfStreamTimestamp(long)
+     * @throws Exception if encountered error, in which case the output file may not be valid. In
+     *                   particular, {@link TimeoutException} is thrown when timed out, and {@link
+     *                   MediaCodec.CodecException} is thrown when encountered codec error.
+     */
+    @Override
+    public void stop(@IntRange(from = 0) long timeoutMs) throws Exception {
+        super.stop(timeoutMs);
+    }
+
     @SuppressLint("WrongConstant")
     @SuppressWarnings("WeakerAccess") /* synthetic access */
     AvifWriter(@NonNull String path,
diff --git a/heifwriter/heifwriter/src/main/java/androidx/heifwriter/HeifWriter.java b/heifwriter/heifwriter/src/main/java/androidx/heifwriter/HeifWriter.java
@@ -276,6 +276,112 @@ private Builder(String path, FileDescriptor fd,
         }
     }
 
+    /**
+     * Start the heif writer. Can only be called once.
+     *
+     * @throws IllegalStateException if called more than once.
+     */
+    @Override
+    public void start() {
+        super.start();
+    }
+
+    /**
+     * Add one YUV buffer to the heif file.
+     *
+     * @param format The YUV format as defined in {@link android.graphics.ImageFormat}, currently
+     *               only support YUV_420_888.
+     *
+     * @param data byte array containing the YUV data. If the format has more than one planes,
+     *             they must be concatenated.
+     *
+     * @throws IllegalStateException if not started or not configured to use buffer input.
+     */
+    @Override
+    public void addYuvBuffer(int format, @NonNull byte[] data) {
+        super.addYuvBuffer(format, data);
+    }
+
+    /**
+     * Retrieves the input surface for encoding.
+     *
+     * @return the input surface if configured to use surface input.
+     *
+     * @throws IllegalStateException if called after start or not configured to use surface input.
+     */
+    @Override
+    public @NonNull Surface getInputSurface() {
+        return super.getInputSurface();
+    }
+
+    /**
+     * Set the timestamp (in nano seconds) of the last input frame to encode.
+     *
+     * This call is only valid for surface input. Client can use this to stop the heif writer
+     * earlier before the maximum number of images are written. If not called, the writer will
+     * only stop when the maximum number of images are written.
+     *
+     * @param timestampNs timestamp (in nano seconds) of the last frame that will be written to the
+     *                    heif file. Frames with timestamps larger than the specified value will not
+     *                    be written. However, if a frame already started encoding when this is set,
+     *                    all tiles within that frame will be encoded.
+     *
+     * @throws IllegalStateException if not started or not configured to use surface input.
+     */
+    @Override
+    public void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs) {
+        super.setInputEndOfStreamTimestamp(timestampNs);
+    }
+
+    /**
+     * Add one bitmap to the heif file.
+     *
+     * @param bitmap the bitmap to be added to the file.
+     * @throws IllegalStateException if not started or not configured to use bitmap input.
+     */
+    @Override
+    public void addBitmap(@NonNull Bitmap bitmap) {
+        super.addBitmap(bitmap);
+    }
+
+    /**
+     * Add Exif data for the specified image. The data must be a valid Exif data block,
+     * starting with "Exif\0\0" followed by the TIFF header (See JEITA CP-3451C Section 4.5.2.)
+     *
+     * @param imageIndex index of the image, must be a valid index for the max number of image
+     *                   specified by {@link Builder#setMaxImages(int)}.
+     * @param exifData byte buffer containing a Exif data block.
+     * @param offset offset of the Exif data block within exifData.
+     * @param length length of the Exif data block.
+     */
+    @Override
+    public void addExifData(int imageIndex, @NonNull byte[] exifData, int offset, int length) {
+        super.addExifData(imageIndex, exifData, offset, length);
+    }
+
+    /**
+     * Stop the heif writer synchronously. Throws exception if the writer didn't finish writing
+     * successfully. Upon a success return:
+     *
+     * - For buffer and bitmap inputs, all images sent before stop will be written.
+     *
+     * - For surface input, images with timestamp on or before that specified in
+     *   {@link #setInputEndOfStreamTimestamp(long)} will be written. In case where
+     *   {@link #setInputEndOfStreamTimestamp(long)} was never called, stop will block
+     *   until maximum number of images are received.
+     *
+     * @param timeoutMs Maximum time (in microsec) to wait for the writer to complete, with zero
+     *                  indicating waiting indefinitely.
+     * @see #setInputEndOfStreamTimestamp(long)
+     * @throws Exception if encountered error, in which case the output file may not be valid. In
+     *                   particular, {@link TimeoutException} is thrown when timed out, and {@link
+     *                   MediaCodec.CodecException} is thrown when encountered codec error.
+     */
+    @Override
+    public void stop(@IntRange(from = 0) long timeoutMs) throws Exception {
+        super.stop(timeoutMs);
+    }
+
     @SuppressLint("WrongConstant")
     @SuppressWarnings("WeakerAccess") /* synthetic access */
     HeifWriter(@NonNull String path,
diff --git a/heifwriter/heifwriter/src/main/java/androidx/heifwriter/WriterBase.java b/heifwriter/heifwriter/src/main/java/androidx/heifwriter/WriterBase.java
@@ -159,7 +159,7 @@ protected WriterBase(int rotation,
      *
      * @throws IllegalStateException if called more than once.
      */
-    public void start() {
+    void start() {
         checkStarted(false);
         mStarted = true;
         mEncoder.start();
@@ -176,7 +176,7 @@ public void start() {
      *
      * @throws IllegalStateException if not started or not configured to use buffer input.
      */
-    public void addYuvBuffer(int format, @NonNull byte[] data) {
+    void addYuvBuffer(int format, @NonNull byte[] data) {
         checkStartedAndMode(INPUT_MODE_BUFFER);
         synchronized (this) {
             if (mEncoder != null) {
@@ -192,7 +192,7 @@ public void addYuvBuffer(int format, @NonNull byte[] data) {
      *
      * @throws IllegalStateException if called after start or not configured to use surface input.
      */
-    public @NonNull Surface getInputSurface() {
+    @NonNull Surface getInputSurface() {
         checkStarted(false);
         checkMode(INPUT_MODE_SURFACE);
         return mEncoder.getInputSurface();
@@ -212,7 +212,7 @@ public void addYuvBuffer(int format, @NonNull byte[] data) {
      *
      * @throws IllegalStateException if not started or not configured to use surface input.
      */
-    public void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs) {
+    void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs) {
         checkStartedAndMode(INPUT_MODE_SURFACE);
         synchronized (this) {
             if (mEncoder != null) {
@@ -227,7 +227,7 @@ public void setInputEndOfStreamTimestamp(@IntRange(from = 0) long timestampNs) {
      * @param bitmap the bitmap to be added to the file.
      * @throws IllegalStateException if not started or not configured to use bitmap input.
      */
-    public void addBitmap(@NonNull Bitmap bitmap) {
+    void addBitmap(@NonNull Bitmap bitmap) {
         checkStartedAndMode(INPUT_MODE_BITMAP);
         synchronized (this) {
             if (mEncoder != null) {
@@ -246,7 +246,7 @@ public void addBitmap(@NonNull Bitmap bitmap) {
      * @param offset offset of the Exif data block within exifData.
      * @param length length of the Exif data block.
      */
-    public void addExifData(int imageIndex, @NonNull byte[] exifData, int offset, int length) {
+    void addExifData(int imageIndex, @NonNull byte[] exifData, int offset, int length) {
         checkStarted(true);
 
         ByteBuffer buffer = ByteBuffer.allocateDirect(length);
@@ -298,7 +298,7 @@ void processExifData() {
      *                   particular, {@link TimeoutException} is thrown when timed out, and {@link
      *                   MediaCodec.CodecException} is thrown when encountered codec error.
      */
-    public void stop(@IntRange(from = 0) long timeoutMs) throws Exception {
+    void stop(@IntRange(from = 0) long timeoutMs) throws Exception {
         checkStarted(true);
         synchronized (this) {
             if (mEncoder != null) {
