1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.camera.device@3.2; 18 19import android.hardware.camera.common@1.0::types; 20 21/** 22 * 23 * Callback methods for the HAL to call into the framework. 24 * 25 * These methods are used to return metadata and image buffers for a completed 26 * or failed captures, and to notify the framework of asynchronous events such 27 * as errors. 28 * 29 * The framework must not call back into the HAL from within these callbacks, 30 * and these calls must not block for extended periods. 31 * 32 */ 33interface ICameraDeviceCallback { 34 35 /** 36 * processCaptureResult: 37 * 38 * Send results from one or more completed or partially completed captures 39 * to the framework. 40 * processCaptureResult() may be invoked multiple times by the HAL in 41 * response to a single capture request. This allows, for example, the 42 * metadata and low-resolution buffers to be returned in one call, and 43 * post-processed JPEG buffers in a later call, once it is available. Each 44 * call must include the frame number of the request it is returning 45 * metadata or buffers for. Only one call to processCaptureResult 46 * may be made at a time by the HAL although the calls may come from 47 * different threads in the HAL. 48 * 49 * A component (buffer or metadata) of the complete result may only be 50 * included in one process_capture_result call. A buffer for each stream, 51 * and the result metadata, must be returned by the HAL for each request in 52 * one of the processCaptureResult calls, even in case of errors producing 53 * some of the output. A call to processCaptureResult() with neither 54 * output buffers or result metadata is not allowed. 55 * 56 * The order of returning metadata and buffers for a single result does not 57 * matter, but buffers for a given stream must be returned in FIFO order. So 58 * the buffer for request 5 for stream A must always be returned before the 59 * buffer for request 6 for stream A. This also applies to the result 60 * metadata; the metadata for request 5 must be returned before the metadata 61 * for request 6. 62 * 63 * However, different streams are independent of each other, so it is 64 * acceptable and expected that the buffer for request 5 for stream A may be 65 * returned after the buffer for request 6 for stream B is. And it is 66 * acceptable that the result metadata for request 6 for stream B is 67 * returned before the buffer for request 5 for stream A is. If multiple 68 * capture results are included in a single call, camera framework must 69 * process results sequentially from lower index to higher index, as if 70 * these results were sent to camera framework one by one, from lower index 71 * to higher index. 72 * 73 * The HAL retains ownership of result structure, which only needs to be 74 * valid to access during this call. 75 * 76 * The output buffers do not need to be filled yet; the framework must wait 77 * on the stream buffer release sync fence before reading the buffer 78 * data. Therefore, this method should be called by the HAL as soon as 79 * possible, even if some or all of the output buffers are still in 80 * being filled. The HAL must include valid release sync fences into each 81 * output_buffers stream buffer entry, or -1 if that stream buffer is 82 * already filled. 83 * 84 * If the result buffer cannot be constructed for a request, the HAL must 85 * return an empty metadata buffer, but still provide the output buffers and 86 * their sync fences. In addition, notify() must be called with an 87 * ERROR_RESULT message. 88 * 89 * If an output buffer cannot be filled, its status field must be set to 90 * STATUS_ERROR. In addition, notify() must be called with a ERROR_BUFFER 91 * message. 92 * 93 * If the entire capture has failed, then this method still needs to be 94 * called to return the output buffers to the framework. All the buffer 95 * statuses must be STATUS_ERROR, and the result metadata must be an 96 * empty buffer. In addition, notify() must be called with a ERROR_REQUEST 97 * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages 98 * must not be sent. 99 * 100 * Performance requirements: 101 * 102 * This is a non-blocking call. The framework must handle each CaptureResult 103 * within 5ms. 104 * 105 * The pipeline latency (see S7 for definition) should be less than or equal to 106 * 4 frame intervals, and must be less than or equal to 8 frame intervals. 107 * 108 */ 109 processCaptureResult(vec<CaptureResult> results); 110 111 /** 112 * notify: 113 * 114 * Asynchronous notification callback from the HAL, fired for various 115 * reasons. Only for information independent of frame capture, or that 116 * require specific timing. Multiple messages may be sent in one call; a 117 * message with a higher index must be considered to have occurred after a 118 * message with a lower index. 119 * 120 * Multiple threads may call notify() simultaneously. 121 * 122 * Buffers delivered to the framework must not be dispatched to the 123 * application layer until a start of exposure timestamp (or input image's 124 * start of exposure timestamp for a reprocess request) has been received 125 * via a SHUTTER notify() call. It is highly recommended to dispatch this 126 * call as early as possible. 127 * 128 * The SHUTTER notify calls for requests with android.control.enableZsl 129 * set to TRUE and ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be 130 * out-of-order compared to SHUTTER notify for other kinds of requests 131 * (including regular, reprocess, or zero-shutter-lag requests with 132 * different capture intents). 133 * 134 * As a result, the capture results of zero-shutter-lag requests with 135 * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be out-of-order 136 * compared to capture results for other kinds of requests. 137 * 138 * Different SHUTTER notify calls for zero-shutter-lag requests with 139 * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE must be in order between 140 * them, as is for other kinds of requests. SHUTTER notify calls for 141 * zero-shutter-lag requests with non STILL_CAPTURE intent must be in order 142 * with SHUTTER notify calls for regular requests. 143 * ------------------------------------------------------------------------ 144 * Performance requirements: 145 * 146 * This is a non-blocking call. The framework must handle each message in 5ms. 147 */ 148 notify(vec<NotifyMsg> msgs); 149 150}; 151