public class ImageWriter
extends Object implements AutoCloseable
| java.lang.Object | |
| ↳ | android.media.ImageWriter |
ImageWriter类允许应用程序将图像数据生成为 Surface ，并让其被另一个组件（如 CameraDevice 。
几个Android API类可以为ImageWriter提供输入 Surface对象以生成数据，其中包括 MediaCodec （编码器）， CameraCaptureSession （再处理输入）， ImageReader等。
输入图像数据封装在Image对象中。 要将图像数据生成到目标Surface ，应用程序可以通过dequeueInputImage()获取输入图像，然后将图像数据写入其中。 多个这样的Image对象可以同时出队，并以任何顺序排队，最多可达maxImages构造函数参数指定的数量。
如果应用程序已经有ImageReader的图像，应用程序可以直接将此图像排队到ImageWriter（通过queueInputImage(Image) ），可能没有零缓冲区副本。 对于PRIVATE张产生格式图片ImageReader ，这是图像数据发送到ImageWriter的，作为图像数据是不能被应用程序访问的唯一途径。
Android开发手册ImageReader or
CameraDevice) to consume the Images. If the downstream components cannot consume the Images at least as fast as the ImageWriter production rate, the
dequeueInputImage() call will eventually block and the application will have to drop input frames.
如果所提供的输入的消费者组件 Surface放弃 Surface ， queueing或 dequeueing一个 Image将抛出 IllegalStateException 。
Nested classes |
|
|---|---|
interface |
ImageWriter.OnImageReleasedListener ImageWriter回调接口，用于异步通知各种ImageWriter事件的应用程序。 |
Public methods |
|
|---|---|
void |
close() 释放与此ImageWriter相关的所有资源。 |
Image |
dequeueInputImage() 为应用程序生成下一个可用的输入图像以生成数据。 |
int |
getFormat() 获取ImageWriter格式。 |
int |
getMaxImages() 可以同时从ImageWriter出列的图像的最大数量（例如，使用 |
static ImageWriter |
newInstance(Surface surface, int maxImages) 创建一个新的ImageWriter。 |
void |
queueInputImage(Image image) 将输入 |
void |
setOnImageReleasedListener(ImageWriter.OnImageReleasedListener listener, Handler handler) 当输入Image返回到ImageWriter时，注册一个侦听器以供调用。 |
Protected methods |
|
|---|---|
void |
finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 |
Inherited methods |
|
|---|---|
 From class java.lang.Object
|
|
From interface java.lang.AutoCloseable
|
|
void close ()
释放与此ImageWriter相关的所有资源。
调用此方法后，此ImageWriter不能使用。 调用此ImageWriter的和先前提供的图像的任何方法dequeueInputImage()将导致IllegalStateException ，并试图写入ByteBuffers由先前的返回Plane#getBuffer电话将有不确定的行为。
Image dequeueInputImage ()
为应用程序生成下一个可用的输入图像以生成数据。
此方法请求来自ImageWriter的新输入图像。 此调用后，应用程序拥有此Image。 一旦应用程序填充了图像数据，它就会将此图像返回给ImageWriter以供下游消费者组件（例如CameraDevice ）使用。 Image可以通过queueInputImage(Image)或close()返回ImageWriter。
如果所有可用的输入图像已被应用程序排队并且下游消费者尚未消费，则此调用将被阻止。 当下游消费者使用图像并释放图像时，将触发onImageReleased(ImageWriter)回调，这表示存在一个可用的输入图像。 对于非PRIVATE格式（ getFormat() ！= PRIVATE ），建议在稳定状态下仅在此回调被触发后才能使下一个图像出列。
如果ImageWriter的格式为PRIVATE （ getFormat() == PRIVATE ），则应用程序无法访问图像缓冲区，调用此方法将导致IllegalStateException 。 相反，应用程序应该从某个其他组件（例如ImageReader ）获取图像，并通过queueInputImage()方法将它们直接排队到此ImageWriter。
| Returns | |
|---|---|
Image |
The next available input Image from this ImageWriter. |
| Throws | |
|---|---|
IllegalStateException |
if maxImages Images are currently dequeued, or the ImageWriter format is PRIVATE, or the input Surface has been abandoned by the consumer component that provided the Surface. |
也可以看看：
int getFormat ()
获取ImageWriter格式。
此格式可能与getFormat()返回的图像格式不同。 但是，如果ImageWriter格式为PRIVATE ，则调用dequeueInputImage()将导致IllegalStateException 。
| Returns | |
|---|---|
int |
The ImageWriter format. |
int getMaxImages ()
可同时从ImageWriter出列的图像的最大数量（例如， dequeueInputImage() ）。
Image从ImageWriter返回 dequeueInputImage()后，视为退出队列，直到Image通过 queueInputImage(Image)或 close()发送回ImageWriter。
试图同时出队超过 maxImages将导致 dequeueInputImage()函数抛出 IllegalStateException 。
| Returns | |
|---|---|
int |
Maximum number of Images that can be dequeued from this ImageWriter. |
ImageWriter newInstance (Surface surface, int maxImages)
创建一个新的ImageWriter。
所述maxImages参数确定的最大数量Image ，可以从被出队对象ImageWriter同时。 请求更多的缓冲区会占用更多的内存，因此仅使用必要的最小数量非常重要。
输入图像的大小和格式取决于下游客户终端提供的表面。
| Parameters | |
|---|---|
surface |
Surface: The destination Surface this writer produces Image data into. |
maxImages |
int: The maximum number of Images the user will want to access simultaneously for producing Image data. This should be as small as possible to limit memory use. Once maxImages Images are dequeued by the user, one of them has to be queued back before a new Image can be dequeued for access via dequeueInputImage(). |
| Returns | |
|---|---|
ImageWriter |
a new ImageWriter instance. |
void queueInputImage (Image image)
将输入 Image回到ImageWriter，供下游消费者访问。
输入Image可以来自ImageReader（通过acquireNextImage()或acquireLatestImage()获取）或来自ImageWriter（通过dequeueInputImage()获取）。 在前一种情况下，图像数据将被移至此ImageWriter。 请注意，图像属性（大小，格式，步幅等）必须与从此ImageWriter出列的图像的属性相同，否则此方法将抛出IllegalArgumentException 。 在后一种情况下，应用程序用输入图像填充数据。 此方法然后将填充的缓冲区传递给下游用户。 在这两种情况下，调用者都要确保正确设置图像时间戳（以纳秒为单位），因为下游组件可能希望使用它来指示图像数据捕获时间。
在此方法被调用并且下游消费者使用并释放图像后， onImageReleased(ImageWriter)回调将触发。 应用程序可以使用此回调来避免以稳定状态下的下游消费者处理速率发送图像。
从某个其他组件（例如ImageReader ） ImageReader图像时，需要将此ImageWriter的免费输入图像作为目标。 在这种情况下，如果没有可用的空闲图像，则此呼叫将被阻止，如dequeueInputImage() 。 为了避免阻塞，应用程序应该确保在调用此方法之前，此ImageWriter中至少有一个可用的图像可用。
在此调用之后，输入图像不再有效用于进一步访问，就像图像是closed 。 试图访问ByteBuffers由先前的返回Plane#getBuffer调用将导致IllegalStateException 。
| Parameters | |
|---|---|
image |
Image: The Image to be queued back to ImageWriter for future consumption. |
| Throws | |
|---|---|
IllegalStateException |
if the image was already queued previously, or the image was aborted previously, or the input Surface has been abandoned by the consumer component that provided the Surface. |
也可以看看：
void setOnImageReleasedListener (ImageWriter.OnImageReleasedListener listener, Handler handler)
当输入Image返回到ImageWriter时，注册一个侦听器以供调用。
| Parameters | |
|---|---|
listener |
ImageWriter.OnImageReleasedListener: The listener that will be run. |
handler |
Handler: The handler on which the listener should be invoked, or null if the listener should be invoked on the calling thread's looper. |
| Throws | |
|---|---|
IllegalArgumentException |
If no handler specified and the calling thread has no looper. |
void finalize ()
当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 子类会覆盖finalize方法以处置系统资源或执行其他清理。
的常规协定finalize是，它被调用，如果当在Java TM虚拟机已确定不再有由该目的可以通过还没有死亡，除了作为一个动作的结果的任何线程访问的任何手段取决于某些其他可以完成的对象或类别的最终定稿。 方法finalize可以采取任何行动，包括使该对象再次可用于其他线程; 然而， finalize的通常目的是在对象被不可撤销地丢弃之前执行清理操作。 例如，表示输入/输出连接的对象的finalize方法可能会执行显式I / O事务，以在永久丢弃该对象之前中断连接。
类Object的finalize方法Object执行特殊操作; 它只是正常返回。 Object子类可能会覆盖此定义。
Java编程语言不保证哪个线程将为任何给定对象调用finalize方法。 但是，保证调用finalize的线程在调用finalize时不会保留任何用户可见的同步锁。 如果finalize方法引发未捕获的异常，则忽略该异常，并终止该对象的终止。
在针对某个对象调用 finalize方法后，将不会采取进一步的操作，直到Java虚拟机再次确定不再有任何途径可以通过任何尚未死亡的线程访问此对象，包括可能的操作通过准备完成的其他对象或类别，此时该对象可能被丢弃。
对于任何给定的对象，Java虚拟机永远不会多次调用 finalize方法。
finalize方法抛出的任何异常 finalize导致终止此对象的终止，但会被忽略。
| Throws | |
|---|---|
Throwable |
|