/* * Copyright (C) 2016 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. */ package android.hardware.camera.device@3.2; import android.hardware.camera.common@1.0::types; /** * Camera device active session interface. * * Obtained via ICameraDevice::open(), this interface contains the methods to * configure and request captures from an active camera device. * */ interface ICameraDeviceSession { /** * 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: * @return 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. * @return template The default capture request settings for the requested * use case, or an empty metadata structure if status is not OK. * */ constructDefaultRequestSettings(RequestTemplate type) generates (Status status, CameraMetadata requestTemplate); /** * 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 client must set the consumer usage flags in * requestedConfiguration. Upon return, the HAL device must set producerUsage, * maxBuffers, and other 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. * * @return Status Status code for the operation, one of: * OK: * On successful stream configuration. * INTERNAL_ERROR: * If there has been a fatal error and the device is no longer * operational. Only close() can be called successfully by the * framework after this error is returned. * ILLEGAL_ARGUMENT: * If the requested stream configuration is invalid. Some examples * of invalid stream configurations include: * - Including more than 1 INPUT stream * - Not including any OUTPUT streams * - Including streams with unsupported formats, or an unsupported * size for that format. * - Including too many output streams of a certain format. * - Unsupported rotation configuration * - Stream sizes/formats don't satisfy the * StreamConfigurationMode requirements for non-NORMAL mode, or * the requested operation_mode is not supported by the HAL. * - Unsupported usage flag * The camera service cannot filter out all possible illegal stream * configurations, since some devices may support more simultaneous * streams or larger stream resolutions than the minimum required * for a given camera device hardware level. The HAL must return an * ILLEGAL_ARGUMENT for any unsupported stream set, and then be * ready to accept a future valid stream configuration in a later * configureStreams call. * @return finalConfiguration The stream parameters desired by the HAL for * each stream, including maximum buffers, the usage flags, and the * override format. * */ configureStreams(StreamConfiguration requestedConfiguration) generates (Status status, HalStreamConfiguration halConfiguration); /** * 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. * * @return 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. * @return 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. * */ processCaptureRequest(vec requests, vec cachesToRemove) generates (Status status, uint32_t numRequestProcessed); /** * 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. * * @return queue the queue that client writes request metadata to. */ getCaptureRequestMetadataQueue() generates (fmq_sync 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. * * @return queue the queue that implementation writes result metadata to. */ getCaptureResultMetadataQueue() generates (fmq_sync queue); /** * 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). * * @return 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. */ flush() generates (Status status); /** * 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. */ close(); };