Added in API level 31

MultiResolutionImageReader


open class MultiResolutionImageReader : AutoCloseable
kotlin.Any
   ↳ android.hardware.camera2.MultiResolutionImageReader

The MultiResolutionImageReader class wraps a group of ImageReaders with the same format and different sizes, source camera Id, or camera sensor modes.

The main use case of this class is for a multi-camera or an ultra high resolution sensor camera to output variable-size images. For a logical multi-camera which implements optical zoom, different physical cameras may have different maximum resolutions. As a result, when the camera device switches between physical cameras depending on zoom ratio, the maximum resolution for a particular format may change. For an ultra high resolution sensor camera, the camera device may deem it better or worse to run in maximum resolution mode / default mode depending on lighting conditions. So the application may choose to let the camera device decide on its behalf.

MultiResolutionImageReader should be used for a camera device only if the camera device supports multi-resolution output stream by advertising the specified output format in android.hardware.camera2.CameraCharacteristics#SCALER_MULTI_RESOLUTION_STREAM_CONFIGURATION_MAP.

To acquire images from the MultiResolutionImageReader, the application must use the ImageReader object passed by ImageReader.OnImageAvailableListener#onImageAvailable callback to call ImageReader#acquireNextImage or ImageReader#acquireLatestImage. The application must not use the ImageReader passed by an android.media.ImageReader.OnImageAvailableListener#onImageAvailable callback to acquire future images because future images may originate from a different ImageReader contained within the MultiResolutionImageReader.

Summary

Public constructors

Create a new multi-resolution reader based on a group of camera stream properties returned by a camera device.

Public methods
open Unit

open Unit

Flush pending images from all internal ImageReaders

open MultiResolutionStreamInfo

Get the MultiResolutionStreamInfo describing the ImageReader an image originates from

open Surface

Get the surface that is used as a target for CaptureRequest

open Unit

Set onImageAvailableListener callback.

Protected methods
open Unit

Public constructors

MultiResolutionImageReader

Added in API level 31
MultiResolutionImageReader(
    streams: MutableCollection<MultiResolutionStreamInfo!>,
    format: Int,
    maxImages: Int)

Create a new multi-resolution reader based on a group of camera stream properties returned by a camera device.

The valid size and formats depend on the camera characteristics. MultiResolutionImageReader for an image format is supported by the camera device if the format is in the supported multi-resolution output stream formats returned by android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputFormats. If the image format is supported, the MultiResolutionImageReader object can be created with the streams objects returned by android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputInfo.

The maxImages parameter determines the maximum number of Image objects that can be acquired from each of the ImageReader within the MultiResolutionImageReader. However, requesting more buffers will use up more memory, so it is important to use only the minimum number necessary. The application is strongly recommended to acquire no more than maxImages images from all of the internal ImageReader objects combined. By keeping track of the number of acquired images for the MultiResolutionImageReader, the application doesn't need to do the bookkeeping for each internal ImageReader returned from onImageAvailable callback.

Unlike the normal ImageReader, the MultiResolutionImageReader has a more complex configuration sequence. Instead of passing the same surface to OutputConfiguration and CaptureRequest, the android.hardware.camera2.params.OutputConfiguration#createInstancesForMultiResolutionOutput call needs to be used to create the OutputConfigurations for session creation, and then getSurface is used to get CaptureRequest.

Parameters
streams MutableCollection<MultiResolutionStreamInfo!>: The group of multi-resolution stream info, which is used to create a multi-resolution reader containing a number of ImageReader objects. Each ImageReader object represents a multi-resolution stream in the group. This value cannot be null.
format Int: The format of the Image that this multi-resolution reader will produce. This must be one of the android.graphics.ImageFormat or android.graphics.PixelFormat constants. Note that not all formats are supported, like ImageFormat.NV21. The supported multi-resolution reader format can be queried by android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputFormats. Value is android.graphics.ImageFormat#UNKNOWN, android.graphics.PixelFormat#RGBA_8888, android.graphics.PixelFormat#RGBX_8888, android.graphics.PixelFormat#RGB_888, android.graphics.ImageFormat#RGB_565, android.graphics.ImageFormat#YV12, android.graphics.ImageFormat#Y8, android.graphics.ImageFormat.Y16, android.graphics.ImageFormat#YCBCR_P010, android.graphics.ImageFormat#NV16, android.graphics.ImageFormat#NV21, android.graphics.ImageFormat#YUY2, android.graphics.ImageFormat#JPEG, android.graphics.ImageFormat#DEPTH_JPEG, android.graphics.ImageFormat#YUV_420_888, android.graphics.ImageFormat#YUV_422_888, android.graphics.ImageFormat#YUV_444_888, android.graphics.ImageFormat#FLEX_RGB_888, android.graphics.ImageFormat#FLEX_RGBA_8888, android.graphics.ImageFormat#RAW_SENSOR, android.graphics.ImageFormat#RAW_PRIVATE, android.graphics.ImageFormat#RAW10, android.graphics.ImageFormat#RAW12, android.graphics.ImageFormat#DEPTH16, android.graphics.ImageFormat#DEPTH_POINT_CLOUD, android.graphics.ImageFormat.RAW_DEPTH, android.graphics.ImageFormat.RAW_DEPTH10, android.graphics.ImageFormat#PRIVATE, android.graphics.ImageFormat#HEIC, or android.graphics.ImageFormat#JPEG_R
maxImages Int: The maximum number of images the user will want to access simultaneously. This should be as small as possible to limit memory use. Once maxImages images are obtained by the user from any given internal ImageReader, one of them has to be released before a new Image will become available for access through the ImageReader's ImageReader#acquireLatestImage() or ImageReader#acquireNextImage(). Must be greater than 0. Value is 1 or greater

Public methods

close

Added in API level 31
open fun close(): Unit
Exceptions
java.lang.Exception if this resource cannot be closed

flush

Added in API level 31
open fun flush(): Unit

Flush pending images from all internal ImageReaders

Acquire and close pending images from all internal ImageReaders. This has the same effect as calling acquireLatestImage() on all internal ImageReaders, and closing all latest images.

getStreamInfoForImageReader

Added in API level 31
open fun getStreamInfoForImageReader(reader: ImageReader): MultiResolutionStreamInfo

Get the MultiResolutionStreamInfo describing the ImageReader an image originates from

An image from a MultiResolutionImageReader is produced from one of the underlying ImageReaders. This function returns the MultiResolutionStreamInfo to describe the property for that ImageReader, such as width, height, and physical camera Id.

Parameters
reader ImageReader: An internal ImageReader within MultiResolutionImageReader. This value cannot be null.
Return
MultiResolutionStreamInfo The stream info describing the internal ImageReader. This value cannot be null.

getSurface

Added in API level 31
open fun getSurface(): Surface

Get the surface that is used as a target for CaptureRequest

The application must use the surface returned by this function as a target for CaptureRequest. The camera device makes the decision on which internal ImageReader will receive the output image.

Please note that holding on to the Surface objects returned by this method is not enough to keep their parent MultiResolutionImageReaders from being reclaimed. In that sense, a Surface acts like a weak reference to the MultiResolutionImageReader that provides it.

Return
Surface a Surface to use as the target for a capture request. This value cannot be null.

setOnImageAvailableListener

Added in API level 31
open fun setOnImageAvailableListener(
    listener: ImageReader.OnImageAvailableListener?,
    executor: Executor?
): Unit

Set onImageAvailableListener callback.

This function sets the onImageAvailableListener for all the internal ImageReader objects.

For a multi-resolution ImageReader, the timestamps of images acquired in onImageAvailable callback from different internal ImageReaders may become out-of-order due to the asynchronous callbacks between the different resolution image queues.

Parameters
listener ImageReader.OnImageAvailableListener?: The listener that will be run. This value may be null.
executor Executor?: The executor which will be used when invoking the callback. This value may be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

Protected methods

finalize

Added in API level 31
protected open fun finalize(): Unit
Exceptions
java.lang.Throwable the Exception raised by this method