/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup Camera * @{ */ /** * @file NdkCameraCaptureSession.h */ /* * This file defines an NDK API. * Do not remove methods. * Do not change method signatures. * Do not change the value of constants. * Do not change the size of any of the classes defined in here. * Do not reference types that are not part of the NDK. * Do not #include files that aren't part of the NDK. */ #include #include "NdkCameraError.h" #include "NdkCameraMetadata.h" #ifndef _NDK_CAMERA_CAPTURE_SESSION_H #define _NDK_CAMERA_CAPTURE_SESSION_H #ifdef __cplusplus extern "C" { #endif /** * ACameraCaptureSession is an opaque type that manages frame captures of a camera device. * * A pointer can be obtained using {@link ACameraDevice_createCaptureSession} method. */ typedef struct ACameraCaptureSession ACameraCaptureSession; /** * The definition of camera capture session state callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_stateCallbacks}. * @param session The camera capture session whose state is changing. */ typedef void (*ACameraCaptureSession_stateCallback)(void* context, ACameraCaptureSession *session); typedef struct ACameraCaptureSession_stateCallbacks { /// optional application context. void* context; /** * This callback is called when the session is closed and deleted from memory. * *

A session is closed when {@link ACameraCaptureSession_close} is called, a new session * is created by the parent camera device, * or when the parent camera device is closed (either by the user closing the device, * or due to a camera device disconnection or fatal error).

* *

Once this callback is called, all access to this ACameraCaptureSession object will cause * a crash.

*/ ACameraCaptureSession_stateCallback onClosed; /** * This callback is called every time the session has no more capture requests to process. * *

This callback will be invoked any time the session finishes processing * all of its active capture requests, and no repeating request or burst is set up.

*/ ACameraCaptureSession_stateCallback onReady; /** * This callback is called when the session starts actively processing capture requests. * *

If the session runs out of capture requests to process and calls {@link onReady}, * then this callback will be invoked again once new requests are submitted for capture.

*/ ACameraCaptureSession_stateCallback onActive; } ACameraCaptureSession_stateCallbacks; /// Enum for describing error reason in {@link ACameraCaptureFailure} enum { /** * The capture session has dropped this frame due to an * {@link ACameraCaptureSession_abortCaptures} call. */ CAPTURE_FAILURE_REASON_FLUSHED = 0, /** * The capture session has dropped this frame due to an error in the framework. */ CAPTURE_FAILURE_REASON_ERROR }; /// Struct to describe a capture failure typedef struct ACameraCaptureFailure { /** * The frame number associated with this failed capture. * *

Whenever a request has been processed, regardless of failed capture or success, * it gets a unique frame number assigned to its future result/failed capture.

* *

This value monotonically increments, starting with 0, * for every new result or failure; and the scope is the lifetime of the * {@link ACameraDevice}.

*/ int64_t frameNumber; /** * Determine why the request was dropped, whether due to an error or to a user * action. * * @see CAPTURE_FAILURE_REASON_ERROR * @see CAPTURE_FAILURE_REASON_FLUSHED */ int reason; /** * The sequence ID for this failed capture that was returned by the * {@link ACameraCaptureSession_capture} or {@link ACameraCaptureSession_setRepeatingRequest}. * *

The sequence ID is a unique monotonically increasing value starting from 0, * incremented every time a new group of requests is submitted to the ACameraDevice.

*/ int sequenceId; /** * Determine if the image was captured from the camera. * *

If the image was not captured, no image buffers will be available. * If the image was captured, then image buffers may be available.

* */ bool wasImageCaptured; } ACameraCaptureFailure; /** * The definition of camera capture start callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param request The capture request that is starting. Note that this pointer points to a copy of * capture request sent by application, so the address is different to what * application sent but the content will match. This request will be freed by * framework immediately after this callback returns. * @param timestamp The timestamp when the capture is started. This timestmap will match * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. */ typedef void (*ACameraCaptureSession_captureCallback_start)( void* context, ACameraCaptureSession* session, const ACaptureRequest* request, int64_t timestamp); /** * The definition of camera capture progress/result callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param request The capture request of interest. Note that this pointer points to a copy of * capture request sent by application, so the address is different to what * application sent but the content will match. This request will be freed by * framework immediately after this callback returns. * @param result The capture result metadata reported by camera device. The memory is managed by * camera framework. Do not access this pointer after this callback returns. */ typedef void (*ACameraCaptureSession_captureCallback_result)( void* context, ACameraCaptureSession* session, ACaptureRequest* request, const ACameraMetadata* result); /** * The definition of camera capture failure callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param request The capture request of interest. Note that this pointer points to a copy of * capture request sent by application, so the address is different to what * application sent but the content will match. This request will be freed by * framework immediately after this callback returns. * @param failure The {@link ACameraCaptureFailure} desribes the capture failure. The memory is * managed by camera framework. Do not access this pointer after this callback * returns. */ typedef void (*ACameraCaptureSession_captureCallback_failed)( void* context, ACameraCaptureSession* session, ACaptureRequest* request, ACameraCaptureFailure* failure); /** * The definition of camera sequence end callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param sequenceId The capture sequence ID of the finished sequence. * @param frameNumber The frame number of the last frame of this sequence. */ typedef void (*ACameraCaptureSession_captureCallback_sequenceEnd)( void* context, ACameraCaptureSession* session, int sequenceId, int64_t frameNumber); /** * The definition of camera sequence aborted callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param sequenceId The capture sequence ID of the aborted sequence. */ typedef void (*ACameraCaptureSession_captureCallback_sequenceAbort)( void* context, ACameraCaptureSession* session, int sequenceId); /** * The definition of camera buffer lost callback. * * @param context The optional application context provided by user in * {@link ACameraCaptureSession_captureCallbacks}. * @param session The camera capture session of interest. * @param request The capture request of interest. Note that this pointer points to a copy of * capture request sent by application, so the address is different to what * application sent but the content will match. This request will be freed by * framework immediately after this callback returns. * @param window The {@link ANativeWindow} that the lost buffer would have been sent to. * @param frameNumber The frame number of the lost buffer. */ typedef void (*ACameraCaptureSession_captureCallback_bufferLost)( void* context, ACameraCaptureSession* session, ACaptureRequest* request, ANativeWindow* window, int64_t frameNumber); typedef struct ACameraCaptureSession_captureCallbacks { /// optional application context. void* context; /** * This callback 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 timestamps that will be * included in {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in * {@link onCaptureCompleted} callback, * and in the buffers sent to each output ANativeWindow. These buffer * timestamps are accessible through, for example, * {@link AImage_getTimestamp} or * * android.graphics.SurfaceTexture#getTimestamp().

* *

Note that the ACaptureRequest pointer in the callback will not match what application has * submitted, but the contents the ACaptureRequest will match what application submitted.

* */ ACameraCaptureSession_captureCallback_start onCaptureStarted; /** * This callback 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 {@link onCaptureProgressed} calls may happen per * capture; a given result field will only be present in one partial * capture at most. The final {@link 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, {@link onCaptureProgressed} may happen before or after * {@link onCaptureStarted}.

* *

Each request will generate at least `1` partial results, and at most * {@link ACAMERA_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.

* *

Note that the ACaptureRequest pointer in the callback will not match what application has * submitted, but the contents the ACaptureRequest will match what application submitted.

*/ ACameraCaptureSession_captureCallback_result onCaptureProgressed; /** * This callback is called when an image capture has fully completed and all the * result metadata is available. * *

This callback will always fire after the last {@link 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 {@link onCaptureProgressed} instead.

* *

Note that the ACaptureRequest pointer in the callback will not match what application has * submitted, but the contents the ACaptureRequest will match what application submitted.

*/ ACameraCaptureSession_captureCallback_result onCaptureCompleted; /** * This callback is called instead of {@link onCaptureCompleted} when the * camera device failed to produce a capture result 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.

* *

Note that the ACaptureRequest pointer in the callback will not match what application has * submitted, but the contents the ACaptureRequest will match what application submitted.

* * @see ACameraCaptureFailure */ ACameraCaptureSession_captureCallback_failed onCaptureFailed; /** * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, * when a capture sequence finishes and all capture result * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. * *

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, {@link onCaptureSequenceAborted} is invoked instead.

*/ ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; /** * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, * when a capture sequence aborts before any capture result * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. * *

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 {@link ACameraCaptureSession_stopRepeating} or * {@link ACameraCaptureSession_abortCaptures}. When such an event happens, * {@link onCaptureSequenceCompleted} will not be called.

*/ ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; /** * This callback is called if a single buffer for a capture could not be sent to its * destination ANativeWindow. * *

If the whole capture failed, then {@link 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 {@link ACameraCaptureFailure#wasImageCaptured} * returning true, along with one or more calls to {@link onCaptureBufferLost} for the * failed outputs.

* *

Note that the ACaptureRequest pointer in the callback will not match what application has * submitted, but the contents the ACaptureRequest will match what application submitted. * The ANativeWindow pointer will always match what application submitted in * {@link ACameraDevice_createCaptureSession}

* */ ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; } ACameraCaptureSession_captureCallbacks; enum { CAPTURE_SEQUENCE_ID_NONE = -1 }; /** * Close this capture session. * *

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 {@link ACameraDevice_createCaptureSession} * will close any existing capture session automatically, and call the older session listener's * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback. Using * {@link ACameraDevice_createCaptureSession} directly without closing is the recommended approach * for quickly switching to a new session, since unchanged target outputs can be reused more * efficiently.

* *

After a session is closed and before {@link ACameraCaptureSession_stateCallbacks#onClosed} * is called, all methods invoked on the session will return {@link ACAMERA_ERROR_SESSION_CLOSED}, * and any repeating requests are stopped (as if {@link ACameraCaptureSession_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, * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback will be called and the seesion * will be removed from memory.

* *

Closing a session is idempotent; closing more than once has no effect.

* * @param session the capture session of interest */ void ACameraCaptureSession_close(ACameraCaptureSession* session); struct ACameraDevice; typedef struct ACameraDevice ACameraDevice; /** * Get the ACameraDevice pointer associated with this capture session in the device argument * if the method succeeds. * * @param session the capture session of interest * @param device the {@link ACameraDevice} associated with session. Will be set to NULL * if the session is closed or this method fails. * @return * */ camera_status_t ACameraCaptureSession_getDevice( ACameraCaptureSession* session, /*out*/ACameraDevice** device); /** * Submit an array of requests to be captured in sequence as a burst in the minimum of time possible. * *

The burst will be captured in the minimum amount of time possible, and will not be * interleaved with requests submitted by other capture or repeat calls.

* *

Each capture produces one {@link ACameraMetadata} as a capture result and image buffers for * one or more target {@link ANativeWindow}s. The target ANativeWindows (set with * {@link ACaptureRequest_addTarget}) must be a subset of the ANativeWindow provided when * this capture session was created.

* * @param session the capture session of interest * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated this capture * sequence. No capture callback will be fired if this is set to NULL. * @param numRequests number of requests in requests argument. Must be at least 1. * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least * numRequests. * @param captureSequenceId the capture sequence ID associated with this capture method invocation * will be stored here if this argument is not NULL and the method call succeeds. * When this argument is set to NULL, the capture sequence ID will not be returned. * * @return */ camera_status_t ACameraCaptureSession_capture( ACameraCaptureSession* session, /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, int numRequests, ACaptureRequest** requests, /*optional*/int* captureSequenceId); /** * 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 * {@link ACaptureRequest}, at the maximum rate possible.

* *

If a request is submitted through {@link ACameraCaptureSession_capture}, * 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 {@link ACameraCaptureSession_capture}.

* *

To stop the repeating capture, call {@link ACameraCaptureSession_stopRepeating}. Any * ongoing burst will still be completed, however. Calling * {@link ACameraCaptureSession_abortCaptures} will also clear the request.

* *

Calling this method will replace a previously-set repeating requests * set up by this method, although any in-progress burst will be completed before the new repeat * burst will be used.

* * @param session the capture session of interest * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated with this * capture sequence. No capture callback will be fired if callbacks is set to NULL. * @param numRequests number of requests in requests array. Must be at least 1. * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least * numRequests. * @param captureSequenceId the capture sequence ID associated with this capture method invocation * will be stored here if this argument is not NULL and the method call succeeds. * When this argument is set to NULL, the capture sequence ID will not be returned. * * @return */ camera_status_t ACameraCaptureSession_setRepeatingRequest( ACameraCaptureSession* session, /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, int numRequests, ACaptureRequest** requests, /*optional*/int* captureSequenceId); /** * Cancel any ongoing repeating capture set by {@link ACameraCaptureSession_setRepeatingRequest}. * Has no effect on requests submitted through {@link ACameraCaptureSession_capture}. * *

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 {@link ACameraCaptureSession_stateCallbacks#onReady} callback * after calling this method.

* * @param session the capture session of interest * * @return */ camera_status_t ACameraCaptureSession_stopRepeating(ACameraCaptureSession* session); /** * Discard all captures currently pending and in-progress as fast as possible. * *

The camera device will discard all of its current work as fast as possible. Some in-flight * captures may complete successfully and call * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted}, * while others will trigger their {@link ACameraCaptureSession_captureCallbacks#onCaptureFailed} * callbacks. If a repeating request list is set, it will be cleared.

* *

This method is the fastest way to switch the camera device to a new session with * {@link ACameraDevice_createCaptureSession}, 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 {@link ACameraCaptureSession_stateCallbacks#onReady} * callback will be called, if the session has not been closed. Otherwise, the * {@link ACameraCaptureSession_stateCallbacks#onClosed} * callback will be fired when a new session is created by the camera device and the previous * session is being removed from memory.

* *

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 ACameraCaptureSession_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).

* * @param session the capture session of interest * * @return */ camera_status_t ACameraCaptureSession_abortCaptures(ACameraCaptureSession* session); #ifdef __cplusplus } // extern "C" #endif #endif // _NDK_CAMERA_CAPTURE_SESSION_H /** @} */