ImageReader.NewInstance Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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.ImageReaderParameters
- 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.ImageReaderParameters
- 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.