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
|
addExifData(int imageIndex, byte[] exifData, int offset, int length)
Add Exif data for the specified image. |
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
public static final int INPUT_MODE_BITMAP
The input mode where the client adds bitmaps.
See also:
Constant Value: 2 (0x00000002)
INPUT_MODE_BUFFER
public static final int INPUT_MODE_BUFFER
The input mode where the client adds input buffers with YUV data.
See also:
Constant Value: 0 (0x00000000)
INPUT_MODE_SURFACE
public static final int INPUT_MODE_SURFACE
The input mode where the client renders the images to an input Surface created by the writer. The input surface operates in single buffer mode. As a result, for use case where camera directly outputs to the input surface, this mode will not work because camera framework requires multiple buffers to operate in a pipeline fashion.
See also:
Constant Value: 1 (0x00000001)
Public methods
addBitmap
public 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. |
addExifData
public void addExifData (int imageIndex, byte[] exifData, int offset, int length)
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.)
Parameters | |
---|---|
imageIndex |
int : index of the image, must be a valid index for the max number of image
specified by HeifWriter.Builder.setMaxImages(int) . |
exifData |
byte : byte buffer containing a Exif data block. |
offset |
int : offset of the Exif data block within exifData. |
length |
int : length of the Exif data block.
|
addYuvBuffer
public 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
public void close ()
getInputSurface
public 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
public 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
public void start ()
Start the heif writer. Can only be called once.
Throws | |
---|---|
IllegalStateException |
if called more than once. |
stop
public 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.
|
See also:
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.