Android APIs
public static abstract class

CameraCaptureSession.CaptureListener

extends Object
java.lang.Object
   ↳ android.hardware.camera2.CameraCaptureSession.CaptureListener

Class Overview

A listener for tracking the progress of a CaptureRequest submitted to the camera device.

This listener is called when a request triggers a capture to start, and when the capture is complete. In case on an error capturing an image, the error method is triggered instead of the completion method.

Summary

Public Constructors
CameraCaptureSession.CaptureListener()
Public Methods
void onCaptureCompleted(CameraCaptureSession session, CaptureRequest request, TotalCaptureResult result)
This method is called when an image capture has fully completed and all the result metadata is available.
void onCaptureFailed(CameraCaptureSession session, CaptureRequest request, CaptureFailure failure)
This method is called instead of onCaptureCompleted(CameraCaptureSession, CaptureRequest, TotalCaptureResult) when the camera device failed to produce a CaptureResult for the request.
void onCaptureProgressed(CameraCaptureSession session, CaptureRequest request, CaptureResult partialResult)
This method is called when an image capture makes partial forward progress; some (but not all) results from an image capture are available.
void onCaptureSequenceAborted(CameraCaptureSession session, int sequenceId)
This method is called independently of the others in CaptureListener, when a capture sequence aborts before any CaptureResult or CaptureFailure for it have been returned via this listener.
void onCaptureSequenceCompleted(CameraCaptureSession session, int sequenceId, long frameNumber)
This method is called independently of the others in CaptureListener, when a capture sequence finishes and all CaptureResult or CaptureFailure for it have been returned via this listener.
void onCaptureStarted(CameraCaptureSession session, CaptureRequest request, long timestamp)
This method is called when the camera device has started capturing the output image for the request, at the beginning of image exposure.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public CameraCaptureSession.CaptureListener ()

Public Methods

public void onCaptureCompleted (CameraCaptureSession session, CaptureRequest request, TotalCaptureResult result)

This method is called when an image capture has fully completed and all the result metadata is available.

This callback will always fire after the last onCaptureProgressed(CameraCaptureSession, CaptureRequest, CaptureResult); in other words, no more partial results will be delivered once the completed result is available.

For performance-intensive use-cases where latency is a factor, consider using onCaptureProgressed(CameraCaptureSession, CaptureRequest, CaptureResult) instead.

The default implementation of this method does nothing.

Parameters
session the session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
request The request that was given to the CameraDevice
result The total output metadata from the capture, including the final capture parameters and the state of the camera system during capture.

public void onCaptureFailed (CameraCaptureSession session, CaptureRequest request, CaptureFailure failure)

This method is called instead of onCaptureCompleted(CameraCaptureSession, CaptureRequest, TotalCaptureResult) when the camera device failed to produce a CaptureResult for the request.

Other requests are unaffected, and some or all image buffers from the capture may have been pushed to their respective output streams.

The default implementation of this method does nothing.

Parameters
session The session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
request The request that was given to the CameraDevice
failure The output failure from the capture, including the failure reason and the frame number.

public void onCaptureProgressed (CameraCaptureSession session, CaptureRequest request, CaptureResult partialResult)

This method is called when an image capture makes partial forward progress; some (but not all) results from an image capture are available.

The result provided here will contain some subset of the fields of a full result. Multiple onCaptureProgressed(CameraCaptureSession, CaptureRequest, CaptureResult) calls may happen per capture; a given result field will only be present in one partial capture at most. The final onCaptureCompleted(CameraCaptureSession, CaptureRequest, TotalCaptureResult) call will always contain all the fields (in particular, the union of all the fields of all the partial results composing the total result).

For each request, some result data might be available earlier than others. The typical delay between each partial result (per request) is a single frame interval. For performance-oriented use-cases, applications should query the metadata they need to make forward progress from the partial results and avoid waiting for the completed result.

Each request will generate at least 1 partial results, and at most REQUEST_PARTIAL_RESULT_COUNT partial results.

Depending on the request settings, the number of partial results per request will vary, although typically the partial count could be the same as long as the camera device subsystems enabled stay the same.

The default implementation of this method does nothing.

Parameters
session the session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
request The request that was given to the CameraDevice
partialResult The partial output metadata from the capture, which includes a subset of the TotalCaptureResult fields.

public void onCaptureSequenceAborted (CameraCaptureSession session, int sequenceId)

This method is called independently of the others in CaptureListener, when a capture sequence aborts before any CaptureResult or CaptureFailure for it have been returned via this listener.

Due to the asynchronous nature of the camera device, not all submitted captures are immediately processed. It is possible to clear out the pending requests by a variety of operations such as stopRepeating() or flush(). When such an event happens, onCaptureSequenceCompleted(CameraCaptureSession, int, long) will not be called.

The default implementation does nothing.

Parameters
session The session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
sequenceId A sequence ID returned by the capture(CaptureRequest, CameraCaptureSession.CaptureListener, Handler) family of functions.

public void onCaptureSequenceCompleted (CameraCaptureSession session, int sequenceId, long frameNumber)

This method is called independently of the others in CaptureListener, when a capture sequence finishes and all CaptureResult or CaptureFailure for it have been returned via this listener.

In total, there will be at least one result/failure returned by this listener before this callback is invoked. If the capture sequence is aborted before any requests have been processed, onCaptureSequenceAborted(CameraCaptureSession, int) is invoked instead.

The default implementation does nothing.

Parameters
session The session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
sequenceId A sequence ID returned by the capture(CaptureRequest, CameraCaptureSession.CaptureListener, Handler) family of functions.
frameNumber The last frame number (returned by getFrameNumber() or getFrameNumber()) in the capture sequence.

public void onCaptureStarted (CameraCaptureSession session, CaptureRequest request, long timestamp)

This method is called when the camera device has started capturing the output image for the request, at the beginning of image exposure.

This callback is invoked right as the capture of a frame begins, so it is the most appropriate time for playing a shutter sound, or triggering UI indicators of capture.

The request that is being used for this capture is provided, along with the actual timestamp for the start of exposure. This timestamp matches the timestamp that will be included in the result timestamp field, and in the buffers sent to each output Surface. These buffer timestamps are accessible through, for example, Image.getTimestamp() or getTimestamp().

For the simplest way to play a shutter sound camera shutter or a video recording start/stop sound, see the MediaActionSound class.

The default implementation of this method does nothing.

Parameters
session the session returned by createCaptureSession(List, CameraCaptureSession.StateListener, Handler)
request the request for the capture that just begun
timestamp the timestamp at start of capture, in nanoseconds.
See Also