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 this case, notify() isn't required to be called with
91     * an ERROR_BUFFER message. The framework will simply treat the notify()
92     * call with ERROR_BUFFER as a no-op, and derive whether and when to notify
93     * the application of buffer loss based on the buffer status and whether or not
94     * the entire capture has failed.
95     *
96     * If the entire capture has failed, then this method still needs to be
97     * called to return the output buffers to the framework. All the buffer
98     * statuses must be STATUS_ERROR, and the result metadata must be an
99     * empty buffer. In addition, notify() must be called with a ERROR_REQUEST
100     * message. In this case, individual ERROR_RESULT/ERROR_BUFFER messages
101     * must not be sent. Note that valid partial results are still allowed
102     * as long as the final result metadata fails to be generated.
103     *
104     * Performance requirements:
105     *
106     * This is a non-blocking call. The framework must handle each CaptureResult
107     * within 5ms.
108     *
109     * The pipeline latency (see S7 for definition) should be less than or equal to
110     * 4 frame intervals, and must be less than or equal to 8 frame intervals.
111     *
112     */
113    processCaptureResult(vec<CaptureResult> results);
114
115    /**
116     * notify:
117     *
118     * Asynchronous notification callback from the HAL, fired for various
119     * reasons. Only for information independent of frame capture, or that
120     * require specific timing. Multiple messages may be sent in one call; a
121     * message with a higher index must be considered to have occurred after a
122     * message with a lower index.
123     *
124     * Multiple threads may call notify() simultaneously.
125     *
126     * Buffers delivered to the framework must not be dispatched to the
127     * application layer until a start of exposure timestamp (or input image's
128     * start of exposure timestamp for a reprocess request) has been received
129     * via a SHUTTER notify() call. It is highly recommended to dispatch this
130     * call as early as possible.
131     *
132     * The SHUTTER notify calls for requests with android.control.enableZsl
133     * set to TRUE and ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be
134     * out-of-order compared to SHUTTER notify for other kinds of requests
135     * (including regular, reprocess, or zero-shutter-lag requests with
136     * different capture intents).
137     *
138     * As a result, the capture results of zero-shutter-lag requests with
139     * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE may be out-of-order
140     * compared to capture results for other kinds of requests.
141     *
142     * Different SHUTTER notify calls for zero-shutter-lag requests with
143     * ANDROID_CONTROL_CAPTURE_INTENT == STILL_CAPTURE must be in order between
144     * them, as is for other kinds of requests. SHUTTER notify calls for
145     * zero-shutter-lag requests with non STILL_CAPTURE intent must be in order
146     * with SHUTTER notify calls for regular requests.
147     * ------------------------------------------------------------------------
148     * Performance requirements:
149     *
150     * This is a non-blocking call. The framework must handle each message in 5ms.
151     */
152    notify(vec<NotifyMsg> msgs);
153
154};
155