public class CameraConstrainedHighSpeedCaptureSessionImpl extends CameraConstrainedHighSpeedCaptureSession implements CameraCaptureSessionCore
Mostly just forwards calls to an instance of CameraCaptureSessionImpl, but implements the few necessary behavior changes and additional methods required for the constrained high speed speed mode.
CameraCaptureSession.CaptureCallback, CameraCaptureSession.CaptureListener, CameraCaptureSession.StateCallback, CameraCaptureSession.StateListener
SESSION_ID_NONE
Modifier and Type | Method and Description |
---|---|
void |
abortCaptures()
Discard all captures currently pending and in-progress as fast as possible.
|
int |
capture(CaptureRequest request,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Submit a request for an image to be captured by the camera device.
|
int |
captureBurst(List<CaptureRequest> requests,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Submit a list of requests to be captured in sequence as a burst.
|
void |
close()
Close this capture session asynchronously.
|
List<CaptureRequest> |
createHighSpeedRequestList(CaptureRequest request)
Create a unmodifiable list of requests that is suitable for constrained high speed capture
session streaming.
|
void |
finishDeferredConfiguration(List<OutputConfiguration> deferredOutputConfigs)
Finish the deferred output configurations where the output Surface was not configured before.
|
CameraDevice |
getDevice()
Get the camera device that this session is created for.
|
CameraDeviceImpl.StateCallbackKK |
getDeviceStateCallback()
Create an internal state callback, to be invoked on the mDeviceHandler
It has a few behaviors:
Convert device state changes into session state changes.
|
Surface |
getInputSurface()
Get the input Surface associated with a reprocessable capture session.
|
boolean |
isAborting()
Whether currently in mid-abort.
|
boolean |
isReprocessable()
Return if the application can submit reprocess capture requests with this camera capture
session.
|
void |
prepare(int maxCount,
Surface surface)
Pre-allocate at most maxCount buffers for an output Surface.
|
void |
prepare(Surface surface)
Pre-allocate all buffers for an output Surface.
|
void |
replaceSessionClose()
Replace this session with another session.
|
int |
setRepeatingBurst(List<CaptureRequest> requests,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Request endlessly repeating capture of a sequence of images by this
capture session.
|
int |
setRepeatingRequest(CaptureRequest request,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Request endlessly repeating capture of images by this capture session.
|
void |
stopRepeating()
Cancel any ongoing repeating capture set by either
setRepeatingRequest or
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) . |
void |
tearDown(Surface surface)
Free all buffers allocated for an output Surface.
|
public List<CaptureRequest> createHighSpeedRequestList(CaptureRequest request) throws CameraAccessException
CameraConstrainedHighSpeedCaptureSession
Create a unmodifiable list of requests that is suitable for constrained high speed capture session streaming.
High speed video streaming creates significant performance pressure on the camera device,
so to achieve efficient high speed streaming, the camera device may have to aggregate
multiple frames together. This means requests must be sent in batched groups, with all
requests sharing the same settings. This method takes the list of output target
Surfaces (subject to the output Surface requirements specified by the constrained high speed
session) and a request
, and generates a request list that has the same
controls for each request. The input request
must contain the target
output Surfaces and target high speed FPS range that is one of the
StreamConfigurationMap.getHighSpeedVideoFpsRangesFor(android.util.Size)
for the Surface size.
If both preview and recording Surfaces are specified in the request
, the
target FPS range
in the input
request
must be a fixed frame rate FPS range, where the
minimal FPS
==
maximum FPS
. The created request list will contain
a interleaved request pattern such that the preview output FPS is at least 30fps, the
recording output FPS is maximum FPS
of the requested
FPS range. The application can submit this request list directly to an active high speed
capture session to achieve high speed video recording. When only preview or recording
Surface is specified, this method will return a list of request that have the same controls
and output targets for all requests.
Submitting a request list created by this method to a normal capture session will result
in an IllegalArgumentException
if the high speed
FPS range
is not supported by
CameraCharacteristics.CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES
.
createHighSpeedRequestList
in class CameraConstrainedHighSpeedCaptureSession
request
- The high speed capture request that will be used to generate the high speed
request list.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraDevice.createConstrainedHighSpeedCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
,
CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE
,
StreamConfigurationMap.getHighSpeedVideoSizes()
,
StreamConfigurationMap.getHighSpeedVideoFpsRangesFor(android.util.Size)
,
CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES
,
CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO
public CameraDevice getDevice()
CameraCaptureSession
getDevice
in class CameraCaptureSession
public void prepare(Surface surface) throws CameraAccessException
CameraCaptureSession
Pre-allocate all buffers for an output Surface.
Normally, the image buffers for a given output Surface are allocated on-demand, to minimize startup latency and memory overhead.
However, in some cases, it may be desirable for the buffers to be allocated before any requests targeting the Surface are actually submitted to the device. Large buffers may take some time to allocate, which can result in delays in submitting requests until sufficient buffers are allocated to reach steady-state behavior. Such delays can cause bursts to take longer than desired, or cause skips or stutters in preview output.
The prepare() method can be used to perform this preallocation. It may only be called for a given output Surface before that Surface is used as a target for a request. The number of buffers allocated is the sum of the count needed by the consumer providing the output Surface, and the maximum number needed by the camera device to fill its pipeline. Since this may be a larger number than what is actually required for steady-state operation, using prepare may result in higher memory consumption than the normal on-demand behavior results in. Prepare() will also delay the time to first output to a given Surface, in exchange for smoother frame rate once the allocation is complete.
For example, an application that creates an
ImageReader
with a maxImages argument of 10,
but only uses 3 simultaneous Images at once would normally only cause those 3 images to be
allocated (plus what is needed by the camera device for smooth operation). But using
prepare() on the ImageReader Surface will result in all 10 Images being allocated. So
applications using this method should take care to request only the number of buffers
actually necessary for their application.
If the same output Surface is used in consecutive sessions (without closing the first session explicitly), then its already-allocated buffers are carried over, and if it was used as a target of a capture request in the first session, prepare cannot be called on it in the second session.
Once allocation is complete, CameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
will be invoked with
the Surface provided to this method. Between the prepare call and the onSurfacePrepared call,
the Surface provided to prepare must not be used as a target of a CaptureRequest submitted
to this session.
LEGACY
devices cannot pre-allocate output buffers; for those devices,
CameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
will be immediately called, and no preallocation is
done.
prepare
in class CameraCaptureSession
surface
- the output Surface for which buffers should be pre-allocated. Must be one of
the output Surfaces used to create this session.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
public void prepare(int maxCount, Surface surface) throws CameraAccessException
CameraCaptureSession
Pre-allocate at most maxCount buffers for an output Surface.
Like the CameraCaptureSession.prepare(Surface)
method, this method can be used to allocate output
buffers for a given Surface. However, while the CameraCaptureSession.prepare(Surface)
method allocates
the maximum possible buffer count, this method allocates at most maxCount buffers.
If maxCount is greater than the possible maximum count (which is the sum of the buffer
count requested by the creator of the Surface and the count requested by the camera device),
only the possible maximum count is allocated, in which case the function acts exactly like
CameraCaptureSession.prepare(Surface)
.
The restrictions on when this method can be called are the same as for
CameraCaptureSession.prepare(Surface)
.
Repeated calls to this method are allowed, and a mix of CameraCaptureSession.prepare(Surface)
and
this method is also allowed. Note that after the first call to CameraCaptureSession.prepare(Surface)
,
subsequent calls to either prepare method are effectively no-ops. In addition, this method
is not additive in terms of buffer count. This means calling it twice with maxCount = 2
will only allocate 2 buffers, not 4 (assuming the possible maximum is at least 2); to
allocate two buffers on the first call and two on the second, the application needs to call
prepare with prepare(surface, 2) and prepare(surface, 4).
prepare
in class CameraCaptureSession
maxCount
- the buffer count to try to allocate. If this is greater than the possible
maximum for this output, the possible maximum is allocated instead. If
maxCount buffers are already allocated, then prepare will do nothing.surface
- the output Surface for which buffers should be pre-allocated.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal error.public void tearDown(Surface surface) throws CameraAccessException
CameraCaptureSession
Free all buffers allocated for an output Surface.
Normally, once allocated, the image buffers for a given output Surface remain allocated for the lifetime of the capture session, to minimize latency of captures and to reduce memory allocation overhead.
However, in some cases, it may be desirable for allocated buffers to be freed to reduce the application's memory consumption, if the particular output Surface will not be used by the application for some time.
The tearDown() method can be used to perform this operation. After the call finishes, all unfilled image buffers will have been freed. Any future use of the target Surface may require allocation of additional buffers, as if the session had just been created. Buffers being held by the application (either explicitly as Image objects from ImageReader, or implicitly as the current texture in a SurfaceTexture or the current contents of a RS Allocation, will remain valid and allocated even when tearDown is invoked.
A Surface that has had tearDown() called on it is eligible to have prepare() invoked on it again even if it was used as a request target before the tearDown() call, as long as it doesn't get used as a target of a request between the tearDown() and prepare() calls.
tearDown
in class CameraCaptureSession
surface
- the output Surface for which buffers should be freed. Must be one of the
the output Surfaces used to create this session.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal error.public int capture(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
CameraCaptureSession
Submit a request for an image to be captured by the camera device.
The request defines all the parameters for capturing the single image, including sensor, lens, flash, and post-processing settings.
Each request will produce one CaptureResult
and produce new frames for one or more
target Surfaces, set with the CaptureRequest builder's
CaptureRequest.Builder.addTarget(android.view.Surface)
method. The target surfaces (set with
CaptureRequest.Builder.addTarget(android.view.Surface)
) must be a subset of the surfaces provided when this
capture session was created.
Multiple regular and reprocess requests can be in progress at once. If there are only regular requests or reprocess requests in progress, they are processed in first-in, first-out order. If there are both regular and reprocess requests in progress, regular requests are processed in first-in, first-out order and reprocess requests are processed in first-in, first-out order, respectively. However, the processing order of a regular request and a reprocess request in progress is not specified. In other words, a regular request will always be processed before regular requets that are submitted later. A reprocess request will always be processed before reprocess requests that are submitted later. However, a regular request may not be processed before reprocess requests that are submitted later.
Requests submitted through this method have higher priority than
those submitted through CameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, and will be processed as soon as the current
repeat/repeatBurst processing completes.
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
.
capture
in class CameraCaptureSession
request
- the settings for this capturelistener
- The callback object to notify once this request has been
processed. If null, no metadata will be produced for this capture,
although image data will still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.abortCaptures()
,
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public int captureBurst(List<CaptureRequest> requests, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
CameraCaptureSession
Regular and reprocess requests can be mixed together in a single burst. Regular requests
will be captured in order and reprocess requests will be processed in order, respectively.
However, the processing order between a regular request and a reprocess request is not
specified. Each capture produces one CaptureResult
and image buffers for one or more
target surfaces
. The target surfaces (set with
CaptureRequest.Builder.addTarget(android.view.Surface)
) must be a subset of the surfaces provided when
this capture session was created.
The main difference between this method and simply calling
CameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
repeatedly is that this method guarantees that no
other requests will be interspersed with the burst.
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
.
captureBurst
in class CameraCaptureSession
requests
- the list of settings for this burst capturelistener
- The callback object to notify each time one of the
requests in the burst has been processed. If null, no metadata will be
produced for any requests in this burst, although image data will still
be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.abortCaptures()
public int setRepeatingRequest(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
CameraCaptureSession
With this method, the camera device will continually capture images
using the settings in the provided CaptureRequest
, at the maximum
rate possible.
Repeating requests are a simple way for an application to maintain a
preview or other continuous stream of frames, without having to
continually submit identical requests through CameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
.
Repeat requests have lower priority than those submitted
through CameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or CameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, so if
CameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
is called when a repeating request is active, the
capture request will be processed before any further repeating
requests are processed.
To stop the repeating capture, call CameraCaptureSession.stopRepeating()
. Calling
CameraCaptureSession.abortCaptures()
will also clear the request.
Calling this method will replace any earlier repeating request or
burst set up by this method or CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, although any
in-progress burst will be completed before the new repeat request will be
used.
This method does not support reprocess capture requests because each reprocess
CaptureRequest
must be created from the TotalCaptureResult
that matches
the input image to be reprocessed. This is either the TotalCaptureResult
of capture
that is sent for reprocessing, or one of the TotalCaptureResults
of a set of captures, when data from the whole set is combined by the application into a
single reprocess input image. The request must be capturing images from the camera. If a
reprocess capture request is submitted, this method will throw IllegalArgumentException.
setRepeatingRequest
in class CameraCaptureSession
request
- the request to repeat indefinitelylistener
- The callback object to notify every time the
request finishes processing. If null, no metadata will be
produced for this stream of requests, although image data will
still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.stopRepeating()
,
CameraCaptureSession.abortCaptures()
public int setRepeatingBurst(List<CaptureRequest> requests, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
CameraCaptureSession
Request endlessly repeating capture of a sequence of images by this capture session.
With this method, the camera device will continually capture images,
cycling through the settings in the provided list of
CaptureRequests
, at the maximum rate possible.
If a request is submitted through CameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or
CameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, the current repetition of the request list will be
completed before the higher-priority request is handled. This guarantees
that the application always receives a complete repeat burst captured in
minimal time, instead of bursts interleaved with higher-priority
captures, or incomplete captures.
Repeating burst requests are a simple way for an application to
maintain a preview or other continuous stream of frames where each
request is different in a predicatable way, without having to continually
submit requests through CameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
.
To stop the repeating capture, call CameraCaptureSession.stopRepeating()
. Any
ongoing burst will still be completed, however. Calling
CameraCaptureSession.abortCaptures()
will also clear the request.
Calling this method will replace a previously-set repeating request or
burst set up by this method or CameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, although any
in-progress burst will be completed before the new repeat burst will be
used.
This method does not support reprocess capture requests because each reprocess
CaptureRequest
must be created from the TotalCaptureResult
that matches
the input image to be reprocessed. This is either the TotalCaptureResult
of capture
that is sent for reprocessing, or one of the TotalCaptureResults
of a set of captures, when data from the whole set is combined by the application into a
single reprocess input image. The request must be capturing images from the camera. If a
reprocess capture request is submitted, this method will throw IllegalArgumentException.
setRepeatingBurst
in class CameraCaptureSession
requests
- the list of requests to cycle through indefinitelylistener
- The callback object to notify each time one of the
requests in the repeating bursts has finished processing. If null, no
metadata will be produced for this stream of requests, although image
data will still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.stopRepeating()
,
CameraCaptureSession.abortCaptures()
public void stopRepeating() throws CameraAccessException
CameraCaptureSession
Cancel any ongoing repeating capture set by either
setRepeatingRequest
or
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
. Has no effect on requests submitted through
capture
or captureBurst
.
Any currently in-flight captures will still complete, as will any burst that is
mid-capture. To ensure that the device has finished processing all of its capture requests
and is in ready state, wait for the CameraCaptureSession.StateCallback.onReady(android.hardware.camera2.CameraCaptureSession)
callback after
calling this method.
stopRepeating
in class CameraCaptureSession
CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
StateCallback#onIdle
public void abortCaptures() throws CameraAccessException
CameraCaptureSession
The camera device will discard all of its current work as fast as possible. Some in-flight
captures may complete successfully and call CameraCaptureSession.CaptureCallback.onCaptureCompleted(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.TotalCaptureResult)
, while
others will trigger their CameraCaptureSession.CaptureCallback.onCaptureFailed(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureFailure)
callbacks. If a repeating
request or a repeating burst is set, it will be cleared.
This method is the fastest way to switch the camera device to a new session with
CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
or
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
, at the cost of discarding in-progress
work. It must be called before the new session is created. Once all pending requests are
either completed or thrown away, the CameraCaptureSession.StateCallback.onReady(android.hardware.camera2.CameraCaptureSession)
callback will be called,
if the session has not been closed. Otherwise, the CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
callback will be fired when a new session is created by the camera device.
Cancelling will introduce at least a brief pause in the stream of data from the camera device, since once the camera device is emptied, the first new request has to make it through the entire camera pipeline before new output buffers are produced.
This means that using abortCaptures()
to simply remove pending requests is not
recommended; it's best used for quickly switching output configurations, or for cancelling
long in-progress requests (such as a multi-second capture).
abortCaptures
in class CameraCaptureSession
CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorCameraCaptureSession.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraCaptureSession.setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
,
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public Surface getInputSurface()
CameraCaptureSession
Each reprocessable capture session has an input Surface
where the reprocess
capture requests get the input images from, rather than the camera device. The application
can create a ImageWriter
with this input Surface
and use it to provide input images for reprocess capture requests. When the reprocessable
capture session is closed, the input Surface
is abandoned and becomes invalid.
getInputSurface
in class CameraCaptureSession
Surface
where reprocessing capture requests get the input images from. If
this is not a reprocess capture session, null
will be returned.CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
,
ImageWriter
,
ImageReader
public void close()
CameraCaptureSession
Closing a session frees up the target output Surfaces of the session for reuse with either a new session, or to other APIs that can draw to Surfaces.
Note that creating a new capture session with CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
will close any existing capture session automatically, and call the older session listener's
CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
callback. Using CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
directly without closing is the recommended approach for quickly switching to a new session,
since unchanged target outputs can be reused more efficiently.
Once a session is closed, all methods on it will throw an IllegalStateException, and any
repeating requests or bursts are stopped (as if CameraCaptureSession.stopRepeating()
was called).
However, any in-progress capture requests submitted to the session will be completed as
normal; once all captures have completed and the session has been torn down,
CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
will be called.
Closing a session is idempotent; closing more than once has no effect.
close
in interface AutoCloseable
close
in class CameraCaptureSession
public boolean isReprocessable()
CameraCaptureSession
isReprocessable
in class CameraCaptureSession
true
if the application can submit reprocess capture requests with this
camera capture session. false
otherwise.CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public void replaceSessionClose()
CameraCaptureSessionCore
This is an optimization to avoid unconfiguring and then immediately having to reconfigure again.
The semantics are identical to #close
, except that unconfiguring will be skipped.
After this call completes, the session will not call any further methods on the camera device.
replaceSessionClose
in interface CameraCaptureSessionCore
CameraCaptureSession#close
public CameraDeviceImpl.StateCallbackKK getDeviceStateCallback()
CameraCaptureSessionCore
It has a few behaviors:
getDeviceStateCallback
in interface CameraCaptureSessionCore
public boolean isAborting()
CameraCaptureSessionCore
This is used by the implementation to set the capture failure reason, in lieu of more accurate error codes from the camera service. Unsynchronized to avoid deadlocks between simultaneous session->device, device->session calls.
isAborting
in interface CameraCaptureSessionCore
public void finishDeferredConfiguration(List<OutputConfiguration> deferredOutputConfigs) throws CameraAccessException
CameraCaptureSession
Finish the deferred output configurations where the output Surface was not configured before.
For camera use cases where a preview and other output configurations need to be configured,
it can take some time for the preview Surface to be ready (e.g., if the preview Surface is
obtained from SurfaceView
, the SurfaceView is ready after the UI layout
is done, then it takes some time to get the preview Surface).
To speed up camera startup time, the application can configure the
CameraCaptureSession
with the desired preview size, and defer the preview output
configuration until the Surface is ready. After the CameraCaptureSession
is created
successfully with this deferred configuration and other normal configurations, the
application can submit requests that don't include deferred output Surfaces. Once the
deferred Surface is ready, the application can set the Surface to the same deferred output
configuration with the OutputConfiguration.setDeferredSurface(android.view.Surface)
method, and then finish
the deferred output configuration via this method, before it can submit requests with this
output target.
The output Surfaces included by this list of deferred OutputConfigurations
can be used as CaptureRequest
targets as soon as this call
returns;
This method is not supported by Legacy devices.
finishDeferredConfiguration
in class CameraCaptureSession
deferredOutputConfigs
- a list of OutputConfigurations
that
have had setDeferredSurface
invoked
with a valid output Surface.CameraAccessException
- if the camera device is no longer connected or has encountered
a fatal error.