CameraCaptureSession

CameraCaptureSession

CameraCaptureSession ()

abortCaptures

void abortCaptures ()

尽可能快地放弃当前待处理和正在进行的所有捕获。

相机设备将尽可能快地放弃其当前的所有工作。 某些在飞行中的捕捉可能会成功完成并调用onCaptureCompleted(CameraCaptureSession, CaptureRequest, TotalCaptureResult) ，而其他飞行捕捉可能会触发它们的onCaptureFailed(CameraCaptureSession, CaptureRequest, CaptureFailure)回调。 如果设置了重复请求或重复突发，它将被清除。

此方法是将摄像机设备切换到createCaptureSession(List , CameraCaptureSession.StateCallback, Handler) 或createReprocessableCaptureSession(InputConfiguration, List , CameraCaptureSession.StateCallback, Handler) 的最新方法的最快方式，但会以丢弃正在进行的工作为代价。 必须在创建新会话之前调用它。 一旦所有待处理的请求完成或被抛弃，如果会话尚未关闭，则将调用onReady(CameraCaptureSession)回调。 否则， onClosed(CameraCaptureSession)回调将在相机设备创建新会话时触发。

取消将至少在相机设备的数据流中引入暂停，因为一旦相机设备被清空，第一个新的请求必须在产生新的输出缓冲区之前通过整个相机管线。

这意味着不建议使用abortCaptures()简单地删除挂起的请求; 它最适用于快速切换输出配置，或用于取消长时间的正在进行的请求（例如多秒捕获）。

capture

int capture (CaptureRequest request, 
                CameraCaptureSession.CaptureCallback listener, 
                Handler handler)

提交要由相机设备拍摄的图像的请求。

该请求定义了捕获单个图像的所有参数，包括传感器，镜头，闪光灯和后期处理设置。

每个请求将生成一个CaptureResult并为一个或多个目标曲面生成新帧，使用CaptureRequest构建器的addTarget(Surface)方法进行设置。 目标曲面（使用addTarget(Surface)设置）必须是创建此捕捉会话时提供的曲面的子集。

多次定期和重新处理请求可以一次进行。 如果只有正在进行的请求或重新处理请求，则会按先进先出的顺序进行处理。 如果正在进行正常请求和重新处理请求，则按先进先出顺序处理常规请求，并按先进先出顺序分别处理重新处理请求。 但是，未指定正在进行的正常请求和重新处理请求的处理顺序。 换句话说，在稍后提交的常规请求之前，将始终处理常规请求。 重新处理请求将始终在稍后提交的重新处理请求之前处理。 但是，在稍后提交的重新处理请求之前，可能不会处理常规请求。

通过此方法提交的请求比通过 setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)或 setRepeatingBurst(List , CameraCaptureSession.CaptureCallback, Handler) 提交的请求具有更高的优先级，并且将在当前重复/重复爆发处理完成后立即处理。

所有捕捉会话都可以用于捕捉来自相机的图像，但只捕捉由createReprocessableCaptureSession创建的createReprocessableCaptureSession可以提交重新处理捕捉请求。 向定期捕获会话提交重新处理请求将导致IllegalArgumentException 。

captureBurst

int captureBurst (List<CaptureRequest> requests, 
                CameraCaptureSession.CaptureCallback listener, 
                Handler handler)

提交一个请求列表，按顺序将其作为一个突发。 突发将在尽可能短的时间内捕获，并且不会与其他捕获或重复呼叫提交的请求交织在一起。

定期和重新处理请求可以在一次突发中混合在一起。 定期的请求将被按顺序捕获，并且再处理请求将分别按顺序处理。 但是，没有指定正常请求和重新处理请求之间的处理顺序。 每个捕获产生一个CaptureResult和一个或多个目标surfaces图像缓冲区。 目标曲面（使用addTarget(Surface)设置）必须是创建此捕捉会话时提供的曲面的子集。

这种方法与简单地重复调用 capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)的主要区别在于，该方法保证不会有其他请求与该突发散布。

All capture sessions can be used for capturing images from the camera but only capture sessions created by createReprocessableCaptureSession can submit reprocess capture requests. Submitting a reprocess request to a regular capture session will result in an IllegalArgumentException.

close

void close ()

异步关闭此捕获会话。

关闭会话可释放目标输出会话的表面，以便与新会话或可以绘制到曲面的其他API一起使用。

请注意，使用createCaptureSession(List , CameraCaptureSession.StateCallback, Handler) 创建新捕获会话将自动关闭任何现有捕获会话，并调用旧会话侦听器的onClosed(CameraCaptureSession)回onClosed(CameraCaptureSession) 。 直接使用createCaptureSession(List , CameraCaptureSession.StateCallback, Handler) 而不关闭是快速切换到新会话的推荐方法，因为不变的目标输出可以更有效地重新使用。

一旦会话关闭，其上的所有方法都将抛出IllegalStateException，并且停止任何重复请求或突发（就像调用了stopRepeating() ）。 但是，提交给会议的任何正在进行的捕获请求将如常完成; 一旦所有捕获完成并且会话被拆除， onClosed(CameraCaptureSession)将被调用。

闭幕会议是幂等的; 关闭不止一次没有效果。

getDevice

CameraDevice getDevice ()

获取为此会话创建的相机设备。

getInputSurface

Surface getInputSurface ()

获取与可重新处理捕获会话相关联的输入Surface。

每个可重新处理捕获会话都有一个输入Surface ，其中重新处理捕获请求从中获取输入图像，而不是相机设备。 应用程序可以使用此输入Surface创建ImageWriter ，并使用它为重新处理捕获请求提供输入图像。 当可重新处理捕获会话关闭时，输入Surface被放弃并变为无效。

isReprocessable

boolean isReprocessable ()

如果应用程序可以使用此相机捕获会话提交重新处理捕获请求，则返回。

prepare

void prepare (Surface surface)

预先分配输出Surface的所有缓冲区。

通常情况下，给定输出表面的图像缓冲区按需分配，以最小化启动延迟和内存开销。

但是，在某些情况下，可能需要在针对Surface的任何请求实际提交给设备之前分配缓冲区。 大型缓冲区可能需要一些时间进行分配，这可能导致延迟提交请求，直到分配足够的缓冲区以达到稳态行为。 这种延迟可能会导致突发时间超过预期时间，或导致预览输出中出现跳跃或断链。

prepare（）方法可用于执行此预分配。 它只能在Surface被用作请求的目标之前调用给定的输出Surface。 分配的缓冲区数量是消费者提供输出Surface所需的计数和摄像设备填充其管线所需的最大数量的总和。 由于这可能比稳态操作实际需要的数量更大，因此使用prepare可能会导致比正常的按需行为更大的内存消耗。Prepare（）也会延迟首次输出给定的时间表面，一旦分配完成，换取平滑的帧速率。

例如，创建一个ImageReader的应用程序，该参数的maxImages参数为10，但一次只能同时使用3个图像，通常只会导致分配3个图像（以及摄像机设备需要的平滑操作）。 但是在ImageReader Surface上使用prepare（）会导致所有10个图像被分配。 因此使用这种方法的应用程序应该小心只请求其应用程序实际所需的缓冲区数量。

如果在连续会话中使用相同的输出表面（不显式关闭第一个会话），则其已分配的缓冲区将被转移，并且如果它在第一个会话中用作捕获请求的目标，则不能调用prepare在第二届会议上。

一旦分配完成， onSurfacePrepared(CameraCaptureSession, Surface)将被提供给此方法的Surface调用。 在准备调用和onSurfacePrepared调用之间，提供准备的Surface不能用作提交给此会话的CaptureRequest的目标。

LEGACY设备不能预先分配输出缓冲区; 对于这些设备，将立即调用onSurfacePrepared(CameraCaptureSession, Surface) ，并且不进行预分配。

setRepeatingBurst

int setRepeatingBurst (List<CaptureRequest> requests, 
                CameraCaptureSession.CaptureCallback listener, 
                Handler handler)

通过此捕获会话请求无休止地重复捕获一系列图像。

通过这种方法，相机设备将不断捕捉图像，并以最大可能的速率循环所提供的 CaptureRequests列表中的设置。

如果通过capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)或captureBurst(List , CameraCaptureSession.CaptureCallback, Handler) 提交请求，则请求列表的当前重复将在处理较高优先级请求之前完成。 这可以确保应用程序始终能够在最短的时间内收到一个完整的重复突发数据，而不是以更高优先级捕获交错的突发或不完整的捕获。

重复突发请求是应用程序维护预览或其他连续帧流的简单方法，其中每个请求以可预测的方式不同，而不必通过 captureBurst(List , CameraCaptureSession.CaptureCallback, Handler) 持续提交请求。

要停止重复捕捉，请致电stopRepeating() 。 但是，任何持续爆发仍将完成。 拨打abortCaptures()也会清除请求。

调用此方法将取代之前设置的重复请求或由此方法设置的突发或 setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) ，但在使用新的重复突发之前将完成任何正在进行的突发。

此方法不支持重新处理捕获请求，因为必须从匹配要重新处理的输入图像的TotalCaptureResult创建每个重新处理CaptureRequest 。 这是捕获的TotalCaptureResult被发送用于重新处理，或者是来自整个集合的数据被应用程序合并成单个重新处理输入图像时的一组捕获中的一个TotalCaptureResults 。 该请求必须从相机捕捉图像。 如果提交重新处理捕获请求，则此方法将抛出IllegalArgumentException。

setRepeatingRequest

int setRepeatingRequest (CaptureRequest request, 
                CameraCaptureSession.CaptureCallback listener, 
                Handler handler)

通过此捕获会话请求无休止地重复捕获图像。

使用此方法，相机设备将以最大可能的速率使用所提供的 CaptureRequest的设置连续捕捉图像。

重复请求是应用程序维护预览或其他连续帧流的简单方法，无需通过 capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)持续提交相同的请求。

重复请求具有比通过提交这些较低优先级 capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)或 captureBurst(List , CameraCaptureSession.CaptureCallback, Handler) ，因此，如果 capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler)时的重复请求是活性被调用时，被处理的任何进一步重复请求之前捕获请求将被处理。

要停止重复捕捉，请致电stopRepeating() 。 致电abortCaptures()也将清除请求。

调用此方法将替换此方法或 setRepeatingBurst(List , CameraCaptureSession.CaptureCallback, Handler) 设置的任何较早的重复请求或突发，但在使用新的重复请求之前将完成任何正在进行的突发。

此方法不支持重新处理捕获请求，因为每个重新处理CaptureRequest必须从匹配要重新处理的输入图像的TotalCaptureResult创建。 这是捕获的TotalCaptureResult被发送用于重新处理，或者是来自整个集合的数据被应用程序合并成单个重新处理输入图像时的一组捕获中的一个TotalCaptureResults 。 该请求必须从相机捕捉图像。 如果提交重新处理捕获请求，则此方法将抛出IllegalArgumentException。

stopRepeating

void stopRepeating ()

取消由setRepeatingRequest或setRepeatingBurst(List , CameraCaptureSession.CaptureCallback, Handler) 设置的任何正在进行的重复捕捉。 对通过capture或captureBurst提交的请求没有任何影响。

任何目前的飞行中捕捉仍然会完成，就像任何中间捕捉的爆发一样。 要确保设备已完成处理其所有捕获请求并处于就绪状态，请在调用此方法后等待onReady(CameraCaptureSession)回调。