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@1.0;
18
19interface ICameraDeviceCallback {
20
21    /**
22     * Notify the camera service of a particular event occurring
23     * The meaning of each parameter is defined by the value of msgType, and
24     * documented in the definition of NotifyCallbackMsg.
25     *
26     * @param msgType The type of the event.
27     * @param ext1 The first parameter for the event, if needed.
28     * @param ext2 The second parameter for the event, if needed.
29     */
30    notifyCallback(NotifyCallbackMsg msgType, int32_t ext1, int32_t ext2);
31
32    /**
33     * Define a memory buffer from the provided handle and size, and return a
34     * unique identifier for the HAL to use to reference it with.
35     *
36     * @param descriptor A native handle that must have exactly one file
37     *     descriptor in it; the file descriptor must be memory mappable to
38     *     bufferSize * bufferCount bytes.
39     * @param bufferSize The number of bytes a single buffer consists of.
40     * @param bufferCount The number of contiguous buffers that the descriptor
41     *     contains.
42     *
43     * @return memId A positive integer identifier for this memory buffer, for
44     *     use with data callbacks and unregistering memory. 0 must be returned
45     *     in case of error, such as if the descriptor does not contain exactly
46     *     one FD.
47     */
48    registerMemory(handle descriptor, uint32_t bufferSize, uint32_t bufferCount)
49            generates (MemoryId memId);
50
51    /**
52     * Unregister a previously registered memory buffer
53     */
54    unregisterMemory(MemoryId memId);
55
56    /**
57     * Send a buffer of image data to the camera service
58     *
59     * @param msgType The kind of image buffer data this call represents.
60     * @param data A memory handle to the buffer containing the data.
61     * @param bufferIndex The offset into the memory handle where the buffer
62     *     starts.
63     *
64     */
65    dataCallback(DataCallbackMsg msgType, MemoryId data, uint32_t bufferIndex,
66            CameraFrameMetadata metadata);
67
68    /**
69     * Send a buffer of image data to the camera service, with a timestamp
70     *
71     * @param msgType The kind of image buffer data this call represents.
72     * @param data A memory handle to the buffer containing the data.
73     * @param bufferIndex The offset into the memory handle where the buffer
74     *     starts.
75     * @param timestamp The time this buffer was captured by the camera, in
76     *     nanoseconds.
77     *
78     */
79    dataCallbackTimestamp(DataCallbackMsg msgType, MemoryId data, uint32_t bufferIndex,
80            int64_t timestamp);
81
82    /**
83     * Send a buffer of image data to the camera service, with a timestamp
84     *
85     * @param msgType The kind of image buffer data this call represents.
86     * @param handle The handle of image buffer data this call represents.
87     * @param data A memory handle to the buffer containing the data.
88     * @param bufferIndex The offset into the memory handle where the buffer
89     *     starts.
90     * @param timestamp The time this buffer was captured by the camera, in
91     *     nanoseconds.
92     *
93     */
94    handleCallbackTimestamp(DataCallbackMsg msgType, handle frameData, MemoryId data,
95            uint32_t bufferIndex, int64_t timestamp);
96
97    /**
98     * Send a batch of image data buffer to the camera service, with timestamps
99     *
100     * This callback can be used to send multiple frames to camera framework in one callback, which
101     * reduce number of callbacks in performance intensive use cases, such as high speed video
102     * recording. The HAL must not mix use of this method with handleCallbackTimestamp in one
103     * recording session (between startRecording and stopRecording)
104     *
105     * @param msgType The kind of image buffer data this call represents.
106     * @param batch a vector messages. Each message contains a image buffer and a timestamp. The
107     *     messages must be ordered in time from lower index to higher index, so that timestamp of
108     *     i-th message is always smaller than i+1-th message.
109     *
110     */
111    handleCallbackTimestampBatch(DataCallbackMsg msgType, vec<HandleTimestampMessage> batch);
112
113};
114