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
19enum CameraFacing : uint32_t {
20    /** The facing of the camera is opposite to that of the screen. */
21    BACK = 0,
22    /** The facing of the camera is the same as that of the screen. */
23    FRONT = 1,
24    /**
25     * The facing of the camera is not fixed relative to the screen.
26     * The cameras with this facing are external cameras, e.g. USB cameras.
27     */
28    EXTERNAL = 2
29};
30
31/**
32 * Basic information about a camera device, always accessible via
33 * ICameraDevice::getCameraInfo().
34 */
35struct CameraInfo {
36    /**
37     * The direction that this device faces.
38     */
39    CameraFacing facing;
40
41    /**
42     * The orientation of the camera image. The value is the angle that the
43     * camera image needs to be rotated clockwise so it shows correctly on the
44     * display in its natural orientation. It must be 0, 90, 180, or 270.
45     *
46     * For example, suppose a device has a naturally tall screen. The
47     * back-facing camera sensor is mounted in landscape. You are looking at the
48     * screen. If the top side of the camera sensor is aligned with the right
49     * edge of the screen in natural orientation, the value must be 90. If the
50     * top side of a front-facing camera sensor is aligned with the right of the
51     * screen, the value must be 270.
52     *
53     * An external camera device must leave this set to 0.
54     *
55     */
56    uint32_t orientation;
57
58};
59
60/**
61 * Message types for ICameraDevice@1.0::enableMsgType()/disableMsgType()
62 *
63 * A set of bit masks for specifying how the received preview frames are
64 * handled before the previewCallback() call.
65 *
66 * The least significant 3 bits of an "int" value are used for this purpose:
67 *
68 * ..... 0 0 0
69 *       ^ ^ ^
70 *       | | |---------> determine whether the callback is enabled or not
71 *       | |-----------> determine whether the callback is one-shot or not
72 *       |-------------> determine whether the frame is copied out or not
73 *
74 * WARNING: When a frame is sent directly without copying, it is the frame
75 * receiver's responsiblity to make sure that the frame data won't get
76 * corrupted by subsequent preview frames filled by the camera. This flag is
77 * recommended only when copying out data brings significant performance price
78 * and the handling/processing of the received frame data is always faster than
79 * the preview frame rate so that data corruption won't occur.
80 *
81 * For instance,
82 * 1. 0x00 disables the callback. In this case, copy out and one shot bits
83 *    are ignored.
84 * 2. 0x01 enables a callback without copying out the received frames. A
85 *    typical use case is the Camcorder application to avoid making costly
86 *    frame copies.
87 * 3. 0x05 is enabling a callback with frame copied out repeatedly. A typical
88 *    use case is the Camera application.
89 * 4. 0x07 is enabling a callback with frame copied out only once. A typical
90 *    use case is the Barcode scanner application.
91 */
92enum FrameCallbackFlag : uint32_t {
93    ENABLE_MASK = 0x01,
94    ONE_SHOT_MASK = 0x02,
95    COPY_OUT_MASK = 0x04,
96    /** Typical use cases */
97    NOOP = 0x00,
98    CAMCORDER = 0x01,
99    CAMERA = 0x05,
100    BARCODE_SCANNER = 0x07
101};
102
103typedef bitfield<FrameCallbackFlag> FrameCallbackFlags;
104
105/**
106 * Subset of commands in /system/core/include/system/camera.h relevant for
107 * ICameraDevice@1.0::sendCommand()
108 */
109enum CommandType : uint32_t {
110    START_SMOOTH_ZOOM = 1,
111    STOP_SMOOTH_ZOOM = 2,
112
113    /**
114     * Start the face detection. This must be called only after preview is
115     * started.  The camera must notify the listener of CAMERA_MSG_FACE and the
116     * detected faces in the preview frame. The detected faces may be the same
117     * as the previous ones. Apps must call CAMERA_CMD_STOP_FACE_DETECTION to
118     * stop the face detection. This method is supported if CameraParameters
119     * KEY_MAX_NUM_HW_DETECTED_FACES or KEY_MAX_NUM_SW_DETECTED_FACES is bigger
120     * than 0. Hardware and software face detection must not be running at the
121     * same time. If the face detection has started, apps must not send this
122     * again.
123     *
124     * In hardware face detection mode, CameraParameters KEY_WHITE_BALANCE,
125     * KEY_FOCUS_AREAS and KEY_METERING_AREAS have no effect.
126     *
127     * arg1 is the face detection type. It can be CAMERA_FACE_DETECTION_HW or
128     * CAMERA_FACE_DETECTION_SW. If the type of face detection requested is not
129     * supported, the HAL must return BAD_VALUE.
130     */
131    START_FACE_DETECTION = 6,
132
133    /**
134     * Stop the face detection.
135     */
136    STOP_FACE_DETECTION = 7,
137
138    /**
139     * Enable/disable focus move callback (CAMERA_MSG_FOCUS_MOVE). Passing
140     * arg1 = 0 must disable, while passing arg1 = 1 must enable the callback.
141     */
142    ENABLE_FOCUS_MOVE_MSG = 8,
143
144    /**
145     * Configure an explicit format to use for video recording metadata mode.
146     * This can be used to switch the format from the
147     * default IMPLEMENTATION_DEFINED gralloc format to some other
148     * device-supported format, and the default dataspace from the BT_709 color
149     * space to some other device-supported dataspace. arg1 is the HAL pixel
150     * format, and arg2 is the HAL dataSpace. This command returns
151     * INVALID_OPERATION error if it is sent after video recording is started,
152     * or the command is not supported at all.
153     *
154     * If the gralloc format is set to a format other than
155     * IMPLEMENTATION_DEFINED, then HALv3 devices must use gralloc usage flags
156     * of SW_READ_OFTEN.
157     */
158    SET_VIDEO_FORMAT = 11
159};
160
161/**
162 * Message types for ICameraDevice1Callback::notifyCallback()
163 */
164enum NotifyCallbackMsg : uint32_t {
165    ERROR = 0x0001,
166    SHUTTER = 0x0002,
167    FOCUS = 0x0004,
168    ZOOM = 0x0008,
169    // Notify on autofocus start and stop. This is useful in continuous
170    // autofocus - FOCUS_MODE_CONTINUOUS_VIDEO and FOCUS_MODE_CONTINUOUS_PICTURE.
171    FOCUS_MOVE = 0x0800
172};
173
174/**
175 * Message types for ICameraDevice1Callback::dataCallback() and
176 * ICameraDevice1Callback::dataCallbackTimestamp()
177 */
178enum DataCallbackMsg : uint32_t {
179    PREVIEW_FRAME = 0x0010,
180    VIDEO_FRAME = 0x0020,
181    POSTVIEW_FRAME = 0x0040,
182    RAW_IMAGE = 0x0080,
183    COMPRESSED_IMAGE = 0x0100,
184    RAW_IMAGE_NOTIFY = 0x0200,
185    // Preview frame metadata. This can be combined with
186    // CAMERA_MSG_PREVIEW_FRAME in dataCallback. For example, the apps can
187    // request FRAME and METADATA. Or the apps can request only FRAME or only
188    // METADATA.
189    PREVIEW_METADATA = 0x0400
190};
191
192/**
193 * Information for a single detected face.
194 */
195 struct CameraFace {
196    /**
197     * Bounds of the face [left, top, right, bottom]. (-1000, -1000) represents
198     * the top-left of the camera field of view, and (1000, 1000) represents the
199     * bottom-right of the field of view. The width and height cannot be 0 or
200     * negative. This is supported by both hardware and software face detection.
201     *
202     * The direction is relative to the sensor orientation, that is, what the
203     * sensor sees. The direction is not affected by the rotation or mirroring
204     * of CAMERA_CMD_SET_DISPLAY_ORIENTATION.
205     */
206    int32_t[4] rect;
207
208    /**
209     * The confidence level of the face. The range is 1 to 100. 100 is the
210     * highest confidence. This is supported by both hardware and software
211     * face detection.
212     */
213    int32_t score;
214
215    /**
216     * An unique id per face while the face is visible to the tracker. If
217     * the face leaves the field-of-view and comes back, it will get a new
218     * id. If the value is 0, id is not supported.
219     */
220    int32_t id;
221
222    /**
223     * The coordinates of the center of the left eye. The range is -1000 to
224     * 1000. -2000, -2000 if this is not supported.
225     */
226    int32_t[2] leftEye;
227
228    /**
229     * The coordinates of the center of the right eye. The range is -1000 to
230     * 1000. -2000, -2000 if this is not supported.
231     */
232    int32_t[2] rightEye;
233
234    /**
235     * The coordinates of the center of the mouth. The range is -1000 to 1000.
236     * -2000, -2000 if this is not supported.
237     */
238    int32_t[2] mouth;
239
240};
241
242/**
243 * The metadata of the frame data, such as face detection result.
244 */
245struct CameraFrameMetadata {
246    /**
247     * A vector of the detected faces.
248     */
249    vec<CameraFace> faces;
250};
251
252/**
253 * A simple integer handle to use to reference a particular memory buffer
254 * between the HAL and the framework.
255 */
256typedef uint32_t MemoryId;
257
258/*
259 * Struct containing arguments of ICameraDeviceCallback::handleCallbackTimestamp.
260 * Used to send a batch of messages in ICameraDeviceCallback::handleCallbackTimestampBatch.
261 */
262struct HandleTimestampMessage {
263    // The handle of image buffer data.
264    handle frameData;
265
266    // A memory handle to the buffer containing the data
267    MemoryId data;
268
269    // The offset into the memory handle where the buffer starts.
270    uint32_t bufferIndex;
271
272    // The time this buffer was captured by the camera, in nanoseconds
273    int64_t timestamp;
274};
275
276/*
277 * Struct containing arguments of ICameraDevice::releaseRecordingFrameHandle.
278 * Used by camera framework to send a batch of recording frames back to camera HAL.
279 */
280struct VideoFrameMessage {
281    // The handle of image buffer data.
282    handle frameData;
283
284    // A memory handle to the buffer containing the data
285    MemoryId data;
286
287    // The offset into the memory handle where the buffer starts.
288    uint32_t bufferIndex;
289};
290