/* * 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; /** * * Callback methods for the HAL to call into the framework. * * These methods are used to return metadata and image buffers for a completed * or failed captures, and to notify the framework of asynchronous events such * as errors. * * The framework must not call back into the HAL from within these callbacks, * and these calls must not block for extended periods. * */ interface ICameraDeviceCallback { /** * processCaptureResult: * * Send results from one or more completed or partially completed captures * to the framework. * processCaptureResult() may be invoked multiple times by the HAL in * response to a single capture request. This allows, for example, the * metadata and low-resolution buffers to be returned in one call, and * post-processed JPEG buffers in a later call, once it is available. Each * call must include the frame number of the request it is returning * metadata or buffers for. Only one call to processCaptureResult * may be made at a time by the HAL although the calls may come from * different threads in the HAL. * * A component (buffer or metadata) of the complete result may only be * included in one process_capture_result call. A buffer for each stream, * and the result metadata, must be returned by the HAL for each request in * one of the processCaptureResult calls, even in case of errors producing * some of the output. A call to processCaptureResult() with neither * output buffers or result metadata is not allowed. * * The order of returning metadata and buffers for a single result does not * matter, but buffers for a given stream must be returned in FIFO order. So * the buffer for request 5 for stream A must always be returned before the * buffer for request 6 for stream A. This also applies to the result * metadata; the metadata for request 5 must be returned before the metadata * for request 6. * * However, different streams are independent of each other, so it is * acceptable and expected that the buffer for request 5 for stream A may be * returned after the buffer for request 6 for stream B is. And it is * acceptable that the result metadata for request 6 for stream B is * returned before the buffer for request 5 for stream A is. If multiple * capture results are included in a single call, camera framework must * process results sequentially from lower index to higher index, as if * these results were sent to camera framework one by one, from lower index * to higher index. * * The HAL retains ownership of result structure, which only needs to be * valid to access during this call. * * The output buffers do not need to be filled yet; the framework must wait * on the stream buffer release sync fence before reading the buffer * data. Therefore, this method should be called by the HAL as soon as * possible, even if some or all of the output buffers are still in * being filled. The HAL must include valid release sync fences into each * output_buffers stream buffer entry, or -1 if that stream buffer is * already filled. * * If the result buffer cannot be constructed for a request, the HAL must * return an empty metadata buffer, but still provide the output buffers and * their sync fences. In addition, notify() must be called with an * ERROR_RESULT message. * * If an output buffer cannot be filled, its status field must be set to * STATUS_ERROR. In this case, notify() isn't required to be called with * an ERROR_BUFFER message. The framework will simply treat the notify() * call with ERROR_BUFFER as a no-op, and derive whether and when to notify * the application of buffer loss based on the buffer status and whether or not * the entire capture has failed. * * If the entire capture has failed, then this method still needs to be * called to return the output buffers to the framework. All the buffer * statuses must be STATUS_ERROR, and the result metadata must be an * empty buffer. In addition, notify() must be called with a ERROR_REQUEST * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages * must not be sent. Note that valid partial results are still allowed * as long as the final result metadata fails to be generated. * * Performance requirements: * * This is a non-blocking call. The framework must handle each CaptureResult * within 5ms. * * The pipeline latency (see S7 for definition) should be less than or equal to * 4 frame intervals, and must be less than or equal to 8 frame intervals. * */ processCaptureResult(vec results); /** * notify: * * Asynchronous notification callback from the HAL, fired for various * reasons. Only for information independent of frame capture, or that * require specific timing. Multiple messages may be sent in one call; a * message with a higher index must be considered to have occurred after a * message with a lower index. * * Multiple threads may call notify() simultaneously. * * Buffers delivered to the framework must not be dispatched to the * application layer until a start of exposure timestamp (or input image's * start of exposure timestamp for a reprocess request) has been received * via a SHUTTER notify() call. It is highly recommended to dispatch this * call as early as possible. * * The SHUTTER notify calls for requests with android.control.enableZsl * set to TRUE and ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be * out-of-order compared to SHUTTER notify for other kinds of requests * (including regular, reprocess, or zero-shutter-lag requests with * different capture intents). * * As a result, the capture results of zero-shutter-lag requests with * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be out-of-order * compared to capture results for other kinds of requests. * * Different SHUTTER notify calls for zero-shutter-lag requests with * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE must be in order between * them, as is for other kinds of requests. SHUTTER notify calls for * zero-shutter-lag requests with non STILL_CAPTURE intent must be in order * with SHUTTER notify calls for regular requests. * ------------------------------------------------------------------------ * Performance requirements: * * This is a non-blocking call. The framework must handle each message in 5ms. */ notify(vec msgs); };