Added in API level 21

CaptureCallback


abstract class CaptureCallback
kotlin.Any
   ↳ android.hardware.camera2.CameraCaptureSession.CaptureCallback

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

This callback is invoked 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

Public methods
open Unit
onCaptureBufferLost(session: CameraCaptureSession, request: CaptureRequest, target: Surface, frameNumber: Long)

This method is called if a single buffer for a capture could not be sent to its destination surface.

open Unit

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

open Unit

This method is called instead of onCaptureCompleted when the camera device failed to produce a CaptureResult for the request.

open Unit

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

open Unit

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

open Unit
onCaptureSequenceCompleted(session: CameraCaptureSession, sequenceId: Int, frameNumber: Long)

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

open Unit
onCaptureStarted(session: CameraCaptureSession, request: CaptureRequest, timestamp: Long, frameNumber: Long)

This method is called when the camera device has started capturing the output image for the request, at the beginning of image exposure, or when the camera device has started processing an input image for a reprocess request.

open Unit
onReadoutStarted(session: CameraCaptureSession, request: CaptureRequest, timestamp: Long, frameNumber: Long)

This method is called when the camera device has started reading out the output image for the request, at the beginning of the sensor image readout.

Public constructors

CaptureCallback

CaptureCallback()

Public methods

onCaptureBufferLost

Added in API level 24
open fun onCaptureBufferLost(
    session: CameraCaptureSession,
    request: CaptureRequest,
    target: Surface,
    frameNumber: Long
): Unit

This method is called if a single buffer for a capture could not be sent to its destination surface.

If the whole capture failed, then onCaptureFailed will be called instead. If some but not all buffers were captured but the result metadata will not be available, then onCaptureFailed will be invoked with CaptureFailure#wasImageCaptured returning true, along with one or more calls to onCaptureBufferLost for the failed outputs.

Parameters
session CameraCaptureSession: The session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: The request that was given to the CameraDevice This value cannot be null.
target Surface: The target Surface that the buffer will not be produced for This value cannot be null.
frameNumber Long: The frame number for the request

onCaptureCompleted

Added in API level 21
open fun onCaptureCompleted(
    session: CameraCaptureSession,
    request: CaptureRequest,
    result: TotalCaptureResult
): Unit

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; 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 instead.

The default implementation of this method does nothing.

Parameters
session CameraCaptureSession: the session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: The request that was given to the CameraDevice This value cannot be null.
result TotalCaptureResult: The total output metadata from the capture, including the final capture parameters and the state of the camera system during capture. This value cannot be null.

onCaptureFailed

Added in API level 21
open fun onCaptureFailed(
    session: CameraCaptureSession,
    request: CaptureRequest,
    failure: CaptureFailure
): Unit

This method is called instead of onCaptureCompleted 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.

If a logical multi-camera fails to generate capture result for one of its physical cameras, this method will be called with a CaptureFailure for that physical camera. In such cases, as long as the logical camera capture result is valid, onCaptureCompleted will still be called.

The default implementation of this method does nothing.

Parameters
session CameraCaptureSession: The session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: The request that was given to the CameraDevice This value cannot be null.
failure CaptureFailure: The output failure from the capture, including the failure reason and the frame number. This value cannot be null.

onCaptureProgressed

Added in API level 21
open fun onCaptureProgressed(
    session: CameraCaptureSession,
    request: CaptureRequest,
    partialResult: CaptureResult
): Unit

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 calls may happen per capture; a given result field will only be present in one partial capture at most. The final onCaptureCompleted 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.

For a particular request, onCaptureProgressed may happen before or after onCaptureStarted.

Each request will generate at least 1 partial results, and at most CameraCharacteristics#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 CameraCaptureSession: the session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: The request that was given to the CameraDevice This value cannot be null.
partialResult CaptureResult: The partial output metadata from the capture, which includes a subset of the TotalCaptureResult fields. This value cannot be null.

onCaptureSequenceAborted

Added in API level 21
open fun onCaptureSequenceAborted(
    session: CameraCaptureSession,
    sequenceId: Int
): Unit

This method is called independently of the others in CaptureCallback, 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 CameraCaptureSession#stopRepeating or CameraCaptureSession#abortCaptures. When such an event happens, onCaptureSequenceCompleted will not be called.

The default implementation does nothing.

Parameters
session CameraCaptureSession: The session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
sequenceId Int: A sequence ID returned by the capture family of functions.

onCaptureSequenceCompleted

Added in API level 21
open fun onCaptureSequenceCompleted(
    session: CameraCaptureSession,
    sequenceId: Int,
    frameNumber: Long
): Unit

This method is called independently of the others in CaptureCallback, 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 is invoked instead.

The default implementation does nothing.

Parameters
session CameraCaptureSession: The session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
sequenceId Int: A sequence ID returned by the capture family of functions.
frameNumber Long: The last frame number (returned by CaptureResult#getFrameNumber or CaptureFailure#getFrameNumber) in the capture sequence.

onCaptureStarted

Added in API level 21
open fun onCaptureStarted(
    session: CameraCaptureSession,
    request: CaptureRequest,
    timestamp: Long,
    frameNumber: Long
): Unit

This method is called when the camera device has started capturing the output image for the request, at the beginning of image exposure, or when the camera device has started processing an input image for a reprocess request.

For a regular capture request, 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. For a reprocess request, this timestamp will be the input image's start of exposure which matches the result timestamp field of the TotalCaptureResult that was used to create the reprocess request. This timestamp matches the timestamps 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 android.graphics.SurfaceTexture#getTimestamp(). The frame number included is equal to the frame number that will be included in CaptureResult#getFrameNumber.

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

The default implementation of this method does nothing.

Parameters
session CameraCaptureSession: the session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: the request for the capture that just begun This value cannot be null.
timestamp Long: the timestamp at start of capture for a regular request, or the timestamp at the input image's start of capture for a reprocess request, in nanoseconds.
frameNumber Long: the frame number for this capture

onReadoutStarted

Added in API level 34
open fun onReadoutStarted(
    session: CameraCaptureSession,
    request: CaptureRequest,
    timestamp: Long,
    frameNumber: Long
): Unit

This method is called when the camera device has started reading out the output image for the request, at the beginning of the sensor image readout.

For a capture request, this callback is invoked right after onCaptureStarted. Unlike onCaptureStarted, instead of passing a timestamp of start of exposure, this callback passes a timestamp of start of camera data readout. This is useful because for a camera running at fixed frame rate, the start of readout is at fixed interval, which is not necessarily true for the start of exposure, particularly when autoexposure is changing exposure duration between frames.

The timestamps match the timestamps of the output surfaces with readout timestamp enabled (via OutputConfiguration#setReadoutTimestampEnabled) if:

Otherwise, the timestamps won't match the timestamp of the output surfaces. See the possible parameters for OutputConfiguration#setTimestampBase for details.

This callback will be called only if android.hardware.camera2.CameraCharacteristics#SENSOR_READOUT_TIMESTAMP is CameraMetadata#SENSOR_READOUT_TIMESTAMP_HARDWARE, and it's called right after onCaptureStarted.

Parameters
session CameraCaptureSession: the session returned by android.hardware.camera2.CameraDevice#createCaptureSession This value cannot be null.
request CaptureRequest: the request for the readout that just began This value cannot be null.
timestamp Long: the timestamp at start of readout for a regular request, or the timestamp at the input image's start of readout for a reprocess request, in nanoseconds.
frameNumber Long: the frame number for this capture