/*
 * 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<CaptureRequest> requests,
            vec<BufferCache> 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<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.
     *
     * @return queue the queue that implementation writes result metadata to.
     */
    getCaptureResultMetadataQueue() generates (fmq_sync<uint8_t> 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();
};