Package: android.hardware.camera.device@3.2

ICameraDeviceSession

interface ICameraDeviceSession

Camera device active session interface.

Obtained via ICameraDevice::open(), this interface contains the methods to configure and request captures from an active camera device.

Methods

constructDefaultRequestSettings

constructDefaultRequestSettings (RequestTemplate type)
generates (Status status, CameraMetadata requestTemplate)

constructDefaultRequestSettings:

Create capture settings for standard camera use cases.

The device must return a settings buffer that is configured to meet the requested use case, which must be one of the CAMERA3_TEMPLATE_* enums.All request control fields must be included.

Performance requirements:

This must be a non-blocking call.The HAL should return from this call in 1ms, and must return from this call in 5ms.

Return values :

Details
Parameters
type
Generates
status
Status code for the operation, one of:OK:On a successful construction of default settings.INTERNAL_ERROR:An unexpected internal error occurred, and the default settings are not available.ILLEGAL_ARGUMENT:The camera HAL does not support the input template type CAMERA_DISCONNECTED:An external camera device has been disconnected, and is no longer available.This camera device interface is now stale, and a new instance must be acquired if the device is reconnected.All subsequent calls on this interface must return CAMERA_DISCONNECTED.
requestTemplate

configureStreams

configureStreams (StreamConfiguration requestedConfiguration)
generates (Status status, HalStreamConfiguration halConfiguration)

configureStreams:

Reset the HAL camera device processing pipeline and set up new input and output streams.This call replaces any existing stream configuration with the streams defined in the streamList.This method must be called at least once before a request is submitted with processCaptureRequest().

The streamList must contain at least one output-capable stream, and may not contain more than one input-capable stream.

The streamList may contain streams that are also in the currently-active set of streams(from the previous call to configureStreams()). These streams must already have valid values for usage, maxBuffers, and the private pointer.

If the HAL needs to change the stream configuration for an existing stream due to the new configuration, it may rewrite the values of usage and/or maxBuffers during the configure call.

The framework must detect such a change, and may then reallocate the stream buffers before using buffers from that stream in a request.

If a currently-active stream is not included in streamList, the HAL may safely remove any references to that stream.It must not be reused in a later configureStreams() call by the framework, and all the gralloc buffers for it must be freed after the configureStreams() call returns.

If the stream is new, the maxBuffer field of the stream structure must be set to 0.The usage must be set to the consumer usage flags.The HAL device must set these fields in the configureStreams() return values.These fields are then used by the framework and the platform gralloc module to allocate the gralloc buffers for each stream.

Newly allocated buffers may be included in a capture request at any time by the framework.Once a gralloc buffer is returned to the framework with processCaptureResult(and its respective releaseFence has been signaled)the framework may free or reuse it at any time.

------------------------------------------------------------------------

Preconditions:

The framework must only call this method when no captures are being processed.That is, all results have been returned to the framework, and all in-flight input and output buffers have been returned and their release sync fences have been signaled by the HAL.The framework must not submit new requests for capture while the configureStreams() call is underway.

Postconditions:

The HAL device must configure itself to provide maximum possible output frame rate given the sizes and formats of the output streams, as documented in the camera device's static metadata.

Performance requirements:

This call is expected to be heavyweight and possibly take several hundred milliseconds to complete, since it may require resetting and reconfiguring the image sensor and the camera processing pipeline.Nevertheless, the HAL device should attempt to minimize the reconfiguration delay to minimize the user-visible pauses during application operational mode changes(such as switching from still capture to video recording).

The HAL should return from this call in 500ms, and must return from this call in 1000ms.

Details
Parameters
requestedConfiguration
Generates
status
halConfiguration

processCaptureRequest

processCaptureRequest (vec<CaptureRequest> requests, vec<BufferCache> cachesToRemove)
generates (Status status, uint32_t numRequestProcessed)

processCaptureRequest:

Send a list of capture requests to the HAL.The HAL must not return from this call until it is ready to accept the next set of requests to process.Only one call to processCaptureRequest() must be made at a time by the framework, and the calls must all be from the same thread.The next call to processCaptureRequest() must be made as soon as a new request and its associated buffers are available.In a normal preview scenario, this means the function is generally called again by the framework almost instantly.If more than one request is provided by the client, the HAL must process the requests in order of lowest index to highest index.

The cachesToRemove argument contains a list of buffer caches(see StreamBuffer document for more information on buffer cache)to be removed by camera HAL.Camera HAL must remove these cache entries whether or not this method returns OK.

The actual request processing is asynchronous, with the results of capture being returned by the HAL through the processCaptureResult() call.This call requires the result metadata to be available, but output buffers may simply provide sync fences to wait on.Multiple requests are expected to be in flight at once, to maintain full output frame rate.

The framework retains ownership of the request structure.It is only guaranteed to be valid during this call.The HAL device must make copies of the information it needs to retain for the capture processing.The HAL is responsible for waiting on and closing the buffers' fences and returning the buffer handles to the framework.

The HAL must write the file descriptor for the input buffer's release sync fence into input_buffer->release_fence, if input_buffer is not valid.If the HAL returns -1 for the input buffer release sync fence, the framework is free to immediately reuse the input buffer.Otherwise, the framework must wait on the sync fence before refilling and reusing the input buffer.

The input/output buffers provided by the framework in each request may be brand new(having never before seen by the HAL).

------------------------------------------------------------------------ Performance considerations:

Handling a new buffer should be extremely lightweight and there must be no frame rate degradation or frame jitter introduced.

This call must return fast enough to ensure that the requested frame rate can be sustained, especially for streaming cases(post-processing quality settings set to FAST). The HAL should return this call in 1 frame interval, and must return from this call in 4 frame intervals.

Details
Parameters
requests
cachesToRemove
Generates
status
Status code for the operation, one of:OK:On a successful start to processing the capture request ILLEGAL_ARGUMENT:If the input is malformed(the settings are empty when not allowed, there are 0 output buffers, etc)and capture processing cannot start.Failures during request processing must be handled by calling ICameraDeviceCallback::notify().In case of this error, the framework retains responsibility for the stream buffers' fences and the buffer handles;the HAL must not close the fences or return these buffers with ICameraDeviceCallback::processCaptureResult().INTERNAL_ERROR:If the camera device has encountered a serious error.After this error is returned, only the close() method can be successfully called by the framework.
numRequestProcessed
Number of requests successfully processed by camera HAL.When status is OK, this must be equal to the size of requests.When the call fails, this number is the number of requests that HAL processed successfully before HAL runs into an error.

getCaptureRequestMetadataQueue

getCaptureRequestMetadataQueue ()
generates (fmq_sync<uint8_t> queue)

getCaptureRequestMetadataQueue:

Retrieves the queue used along with processCaptureRequest.If client decides to use fast message queue to pass request metadata, it must:- Call getCaptureRequestMetadataQueue to retrieve the fast message queue;- In each of the requests sent in processCaptureRequest, set fmqSettingsSize field of CaptureRequest to be the size to read from the fast message queue;leave settings field of CaptureRequest empty.

Details
Generates
queue
the queue that client writes request metadata to.

getCaptureResultMetadataQueue

getCaptureResultMetadataQueue ()
generates (fmq_sync<uint8_t> queue)

getCaptureResultMetadataQueue:

Retrieves the queue used along with ICameraDeviceCallback.processCaptureResult.

Clients to ICameraDeviceSession must:- Call getCaptureRequestMetadataQueue to retrieve the fast message queue;- In implementation of ICameraDeviceCallback, test whether.fmqResultSize field is zero.- If.fmqResultSize != 0, read result metadata from the fast message queue;- otherwise, read result metadata in CaptureResult.result.

Details
Generates
queue
the queue that implementation writes result metadata to.

flush

flush ()
generates (Status status)

flush:

Flush all currently in-process captures and all buffers in the pipeline on the given device.Generally, this method is used to dump all state as quickly as possible in order to prepare for a configure_streams() call.

No buffers are required to be successfully returned, so every buffer held at the time of flush()(whether successfully filled or not)may be returned with CAMERA3_BUFFER_STATUS_ERROR.Note the HAL is still allowed to return valid(CAMERA3_BUFFER_STATUS_OK)buffers during this call, provided they are successfully filled.

All requests currently in the HAL are expected to be returned as soon as possible.Not-in-process requests must return errors immediately.Any interruptible hardware blocks must be stopped, and any uninterruptible blocks must be waited on.

flush() may be called concurrently to processCaptureRequest(), with the expectation that processCaptureRequest returns quickly and the request submitted in that processCaptureRequest call is treated like all other in-flight requests.Due to concurrency issues, it is possible that from the HAL's point of view, a processCaptureRequest() call may be started after flush has been invoked but has not returned yet.If such a call happens before flush() returns, the HAL must treat the new capture request like other in-flight pending requests(see #4 below).

More specifically, the HAL must follow below requirements for various cases:

1.For captures that are too late for the HAL to cancel/stop, and must be completed normally by the HAL;i.e.the HAL can send shutter/notify and processCaptureResult and buffers as normal.

2.For pending requests that have not done any processing, the HAL must call notify CAMERA3_MSG_ERROR_REQUEST, and return all the output buffers with processCaptureResult in the error state(CAMERA3_BUFFER_STATUS_ERROR). The HAL must not place the release fence into an error state, instead, the release fences must be set to the acquire fences passed by the framework, or -1 if they have been waited on by the HAL already.This is also the path to follow for any captures for which the HAL already called notify() with CAMERA3_MSG_SHUTTER but won't be producing any metadata/valid buffers for.After CAMERA3_MSG_ERROR_REQUEST, for a given frame, only processCaptureResults with buffers in CAMERA3_BUFFER_STATUS_ERROR are allowed.No further notifys or processCaptureResult with non-empty metadata is allowed.

3.For partially completed pending requests that do not have all the output buffers or perhaps missing metadata, the HAL must follow below:

3.1.Call notify with CAMERA3_MSG_ERROR_RESULT if some of the expected result metadata(i.e.one or more partial metadata)won't be available for the capture.

3.2.Call notify with CAMERA3_MSG_ERROR_BUFFER for every buffer that won't be produced for the capture.

3.3.Call notify with CAMERA3_MSG_SHUTTER with the capture timestamp before any buffers/metadata are returned with processCaptureResult.

3.4.For captures that will produce some results, the HAL must not call CAMERA3_MSG_ERROR_REQUEST, since that indicates complete failure.

3.5.Valid buffers/metadata must be passed to the framework as normal.

3.6.Failed buffers must be returned to the framework as described for case 2.But failed buffers do not have to follow the strict ordering valid buffers do, and may be out-of-order with respect to valid buffers.For example, if buffers A, B, C, D, E are sent, D and E are failed, then A, E, B, D, C is an acceptable return order.

3.7.For fully-missing metadata, calling CAMERA3_MSG_ERROR_RESULT is sufficient, no need to call processCaptureResult with empty metadata or equivalent.

4.If a flush() is invoked while a processCaptureRequest() invocation is active, that process call must return as soon as possible.In addition, if a processCaptureRequest() call is made after flush() has been invoked but before flush() has returned, the capture request provided by the late processCaptureRequest call must be treated like a pending request in case #2 above.

flush() must only return when there are no more outstanding buffers or requests left in the HAL.The framework may call configure_streams(as the HAL state is now quiesced)or may issue new requests.

Note that it's sufficient to only support fully-succeeded and fully-failed result cases.However, it is highly desirable to support the partial failure cases as well, as it could help improve the flush call overall performance.

Performance requirements:

The HAL should return from this call in 100ms, and must return from this call in 1000ms.And this call must not be blocked longer than pipeline latency(see S7 for definition).

Details
Generates
status
Status code for the operation, one of:OK:On a successful flush of the camera HAL.INTERNAL_ERROR:If the camera device has encountered a serious error.After this error is returned, only the close() method can be successfully called by the framework.

close

close ()

close:

Shut down the camera device.

After this call, all calls to this session instance must return INTERNAL_ERROR.

This method must always succeed, even if the device has encountered a serious error.

Details