belongs to Maven artifact androidx.heifwriter:heifwriter:1.0.0-alpha1

HeifWriter

public final class HeifWriter
extends Object implements AutoCloseable

java.lang.Object
   ↳ androidx.heifwriter.HeifWriter


This class writes one or more still images (of the same dimensions) into a heif file. It currently supports three input modes: INPUT_MODE_BUFFER, INPUT_MODE_SURFACE, or INPUT_MODE_BITMAP. The general sequence (in pseudo-code) to write a heif file using this class is as follows: 1) Construct the writer: HeifWriter heifwriter = new HeifWriter(...); 2) If using surface input mode, obtain the input surface: Surface surface = heifwriter.getInputSurface(); 3) Call start: heifwriter.start(); 4) Depending on the chosen input mode, add one or more images using one of these methods: heifwriter.addYuvBuffer(...); Or heifwriter.addBitmap(...); Or render to the previously obtained surface 5) Call stop: heifwriter.stop(...); 6) Close the writer: heifwriter.close(); Please refer to the documentations on individual methods for the exact usage.

Summary

Nested classes

class HeifWriter.Builder

Builder class for constructing a HeifWriter object from specified parameters. 

Constants

int INPUT_MODE_BITMAP

The input mode where the client adds bitmaps.

int INPUT_MODE_BUFFER

The input mode where the client adds input buffers with YUV data.

int INPUT_MODE_SURFACE

The input mode where the client renders the images to an input Surface created by the writer.

Public methods

void addBitmap(Bitmap bitmap)

Add one bitmap to the heif file.

void addYuvBuffer(int format, byte[] data)

Add one YUV buffer to the heif file.

void close()
Surface getInputSurface()

Retrieves the input surface for encoding.

void setInputEndOfStreamTimestamp(long timestampNs)

Set the timestamp (in nano seconds) of the last input frame to encode.

void start()

Start the heif writer.

void stop(long timeoutMs)

Stop the heif writer synchronously.

Inherited methods

Constants

INPUT_MODE_BITMAP

int INPUT_MODE_BITMAP

The input mode where the client adds bitmaps.

See also:

Constant Value: 2 (0x00000002)

INPUT_MODE_BUFFER

int INPUT_MODE_BUFFER

The input mode where the client adds input buffers with YUV data.

Constant Value: 0 (0x00000000)

INPUT_MODE_SURFACE

int INPUT_MODE_SURFACE

The input mode where the client renders the images to an input Surface created by the writer.

See also:

Constant Value: 1 (0x00000001)

Public methods

addBitmap

void addBitmap (Bitmap bitmap)

Add one bitmap to the heif file.

Parameters
bitmap Bitmap: the bitmap to be added to the file.

Throws
IllegalStateException if not started or not configured to use bitmap input.

addYuvBuffer

void addYuvBuffer (int format, 
                byte[] data)

Add one YUV buffer to the heif file.

Parameters
format int: The YUV format as defined in ImageFormat, currently only support YUV_420_888.

data byte: 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.

close

void close ()

getInputSurface

Surface getInputSurface ()

Retrieves the input surface for encoding.

Returns
Surface the input surface if configured to use surface input.

Throws
IllegalStateException if called after start or not configured to use surface input.

setInputEndOfStreamTimestamp

void setInputEndOfStreamTimestamp (long timestampNs)

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.

Parameters
timestampNs long: 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.

start

void start ()

Start the heif writer. Can only be called once.

Throws
IllegalStateException if called more than once.

stop

void stop (long timeoutMs)

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 setInputEndOfStreamTimestamp(long) will be written. In case where setInputEndOfStreamTimestamp(long) was never called, stop will block until maximum number of images are received.

Parameters
timeoutMs long: Maximum time (in microsec) to wait for the writer to complete, with zero indicating waiting indefinitely.

Throws
Exception if encountered error, in which case the output file may not be valid. In particular, TimeoutException is thrown when timed out, and MediaCodec.CodecException is thrown when encountered codec error.