Sdílet prostřednictvím


ImageReader.NewInstance Method

Definition

Overloads

NewInstance(Int32, Int32, ImageFormatType, Int32)

Create a new reader for images of the desired size and format.

NewInstance(Int32, Int32, ImageFormatType, Int32, Int64)

Create a new reader for images of the desired size, format and consumer usage flag.

NewInstance(Int32, Int32, ImageFormatType, Int32)

Create a new reader for images of the desired size and format.

[Android.Runtime.Register("newInstance", "(IIII)Landroid/media/ImageReader;", "")]
public static Android.Media.ImageReader NewInstance (int width, int height, Android.Graphics.ImageFormatType format, int maxImages);
[<Android.Runtime.Register("newInstance", "(IIII)Landroid/media/ImageReader;", "")>]
static member NewInstance : int * int * Android.Graphics.ImageFormatType * int -> Android.Media.ImageReader

Parameters

width
Int32

The default width in pixels of the Images that this reader will produce.

height
Int32

The default height in pixels of the Images that this reader will produce.

format
ImageFormatType

The format of the Image that this 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.

maxImages
Int32

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, one of them has to be released before a new Image will become available for access through #acquireLatestImage() or #acquireNextImage(). Must be greater than 0.

Returns

Attributes

Remarks

Create a new reader for images of the desired size and format.

The maxImages parameter determines the maximum number of Image objects that can be be acquired from the ImageReader simultaneously. Requesting more buffers will use up more memory, so it is important to use only the minimum number necessary for the use case.

The valid sizes and formats depend on the source of the image data.

If the format is ImageFormat#PRIVATE PRIVATE, the created ImageReader will produce images that are not directly accessible by the application. The application can still acquire images from this ImageReader, and send them to the android.hardware.camera2.CameraDevice camera for reprocessing via ImageWriter interface. However, the Image#getPlanes() getPlanes() will return an empty array for ImageFormat#PRIVATE PRIVATE format images. The application can check if an existing reader's format by calling #getImageFormat().

ImageFormat#PRIVATE PRIVATE format ImageReader ImageReaders are more efficient to use when application access to image data is not necessary, compared to ImageReaders using other format such as ImageFormat#YUV_420_888 YUV_420_888.

Java documentation for android.media.ImageReader.newInstance(int, int, int, int).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

See also

Applies to

NewInstance(Int32, Int32, ImageFormatType, Int32, Int64)

Create a new reader for images of the desired size, format and consumer usage flag.

[Android.Runtime.Register("newInstance", "(IIIIJ)Landroid/media/ImageReader;", "", ApiSince=29)]
public static Android.Media.ImageReader NewInstance (int width, int height, Android.Graphics.ImageFormatType format, int maxImages, long usage);
[<Android.Runtime.Register("newInstance", "(IIIIJ)Landroid/media/ImageReader;", "", ApiSince=29)>]
static member NewInstance : int * int * Android.Graphics.ImageFormatType * int * int64 -> Android.Media.ImageReader

Parameters

width
Int32

The default width in pixels of the Images that this reader will produce.

height
Int32

The default height in pixels of the Images that this reader will produce.

format
ImageFormatType

The format of the Image that this 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.

maxImages
Int32

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, one of them has to be released before a new Image will become available for access through #acquireLatestImage() or #acquireNextImage(). Must be greater than 0.

usage
Int64

The intended usage of the images produced by this ImageReader. See the usages on HardwareBuffer for a list of valid usage bits. See also HardwareBuffer#isSupported(int, int, int, int, long) for checking if a combination is supported. If it's not supported this will throw an IllegalArgumentException.

Returns

Attributes

Remarks

Create a new reader for images of the desired size, format and consumer usage flag.

The maxImages parameter determines the maximum number of Image objects that can be be acquired from the ImageReader simultaneously. Requesting more buffers will use up more memory, so it is important to use only the minimum number necessary for the use case.

The valid sizes and formats depend on the source of the image data.

The format and usage flag combination describes how the buffer will be used by consumer end-points. For example, if the application intends to send the images to android.media.MediaCodec or android.media.MediaRecorder for hardware video encoding, the format and usage flag combination needs to be ImageFormat#PRIVATE PRIVATE and HardwareBuffer#USAGE_VIDEO_ENCODE. When an ImageReader object is created with a valid size and such format/usage flag combination, the application can send the Image images to an ImageWriter that is created with the input android.view.Surface provided by the android.media.MediaCodec or android.media.MediaRecorder.

If the format is ImageFormat#PRIVATE PRIVATE, the created ImageReader will produce images that are not directly accessible by the application. The application can still acquire images from this ImageReader, and send them to the android.hardware.camera2.CameraDevice camera for reprocessing, or to the android.media.MediaCodec / android.media.MediaRecorder for hardware video encoding via ImageWriter interface. However, the Image#getPlanes() getPlanes() will return an empty array for ImageFormat#PRIVATE PRIVATE format images. The application can check if an existing reader's format by calling #getImageFormat().

ImageFormat#PRIVATE PRIVATE format ImageReader ImageReaders are more efficient to use when application access to image data is not necessary, compared to ImageReaders using other format such as ImageFormat#YUV_420_888 YUV_420_888.

Note that not all format and usage flag combinations are supported by the ImageReader. Below are the supported combinations by the ImageReader (assuming the consumer end-points support the such image consumption, e.g., hardware video encoding). <table> <tr> <th>Format</th> <th>Compatible usage flags</th> </tr> <tr> <td>non-android.graphics.ImageFormat#PRIVATE PRIVATE formats defined by android.graphics.ImageFormat ImageFormat or android.graphics.PixelFormat PixelFormat</td> <td>HardwareBuffer#USAGE_CPU_READ_RARELY or HardwareBuffer#USAGE_CPU_READ_OFTEN</td> </tr> <tr> <td>android.graphics.ImageFormat#PRIVATE</td> <td>HardwareBuffer#USAGE_VIDEO_ENCODE or HardwareBuffer#USAGE_GPU_SAMPLED_IMAGE, or combined</td> </tr> </table> Using other combinations may result in IllegalArgumentException. Additionally, specifying HardwareBuffer#USAGE_CPU_WRITE_RARELY or HardwareBuffer#USAGE_CPU_WRITE_OFTEN and writing to the ImageReader's buffers might break assumptions made by some producers, and should be used with caution.

If the ImageReader is used as an output target for a android.hardware.camera2.CameraDevice, and if the usage flag contains HardwareBuffer#USAGE_VIDEO_ENCODE, the timestamps of the Image images produced by the ImageReader won't be in the same timebase as android.os.SystemClock#elapsedRealtimeNanos, even if android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE is android.hardware.camera2.CameraCharacteristics#SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME. Instead, the timestamps will be roughly in the same timebase as in android.os.SystemClock#uptimeMillis, so that A/V synchronization could work for video recording. In this case, the timestamps from the ImageReader with HardwareBuffer#USAGE_VIDEO_ENCODE usage flag may not be directly comparable with timestamps of other streams or capture result metadata.

Java documentation for android.media.ImageReader.newInstance(int, int, int, int, long).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to