1 /* 2 * Copyright (C) 2011 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 17 #ifndef SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_H 18 #define SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 #include <cutils/native_handle.h> 24 #include <hardware/hardware.h> 25 #include <hardware/gralloc.h> 26 27 __BEGIN_DECLS 28 29 /** 30 * A set of bit masks for specifying how the received preview frames are 31 * handled before the previewCallback() call. 32 * 33 * The least significant 3 bits of an "int" value are used for this purpose: 34 * 35 * ..... 0 0 0 36 * ^ ^ ^ 37 * | | |---------> determine whether the callback is enabled or not 38 * | |-----------> determine whether the callback is one-shot or not 39 * |-------------> determine whether the frame is copied out or not 40 * 41 * WARNING: When a frame is sent directly without copying, it is the frame 42 * receiver's responsiblity to make sure that the frame data won't get 43 * corrupted by subsequent preview frames filled by the camera. This flag is 44 * recommended only when copying out data brings significant performance price 45 * and the handling/processing of the received frame data is always faster than 46 * the preview frame rate so that data corruption won't occur. 47 * 48 * For instance, 49 * 1. 0x00 disables the callback. In this case, copy out and one shot bits 50 * are ignored. 51 * 2. 0x01 enables a callback without copying out the received frames. A 52 * typical use case is the Camcorder application to avoid making costly 53 * frame copies. 54 * 3. 0x05 is enabling a callback with frame copied out repeatedly. A typical 55 * use case is the Camera application. 56 * 4. 0x07 is enabling a callback with frame copied out only once. A typical 57 * use case is the Barcode scanner application. 58 */ 59 60 enum { 61 CAMERA_FRAME_CALLBACK_FLAG_ENABLE_MASK = 0x01, 62 CAMERA_FRAME_CALLBACK_FLAG_ONE_SHOT_MASK = 0x02, 63 CAMERA_FRAME_CALLBACK_FLAG_COPY_OUT_MASK = 0x04, 64 /** Typical use cases */ 65 CAMERA_FRAME_CALLBACK_FLAG_NOOP = 0x00, 66 CAMERA_FRAME_CALLBACK_FLAG_CAMCORDER = 0x01, 67 CAMERA_FRAME_CALLBACK_FLAG_CAMERA = 0x05, 68 CAMERA_FRAME_CALLBACK_FLAG_BARCODE_SCANNER = 0x07 69 }; 70 71 /** msgType in notifyCallback and dataCallback functions */ 72 enum { 73 CAMERA_MSG_ERROR = 0x0001, // notifyCallback 74 CAMERA_MSG_SHUTTER = 0x0002, // notifyCallback 75 CAMERA_MSG_FOCUS = 0x0004, // notifyCallback 76 CAMERA_MSG_ZOOM = 0x0008, // notifyCallback 77 CAMERA_MSG_PREVIEW_FRAME = 0x0010, // dataCallback 78 CAMERA_MSG_VIDEO_FRAME = 0x0020, // data_timestamp_callback 79 CAMERA_MSG_POSTVIEW_FRAME = 0x0040, // dataCallback 80 CAMERA_MSG_RAW_IMAGE = 0x0080, // dataCallback 81 CAMERA_MSG_COMPRESSED_IMAGE = 0x0100, // dataCallback 82 CAMERA_MSG_RAW_IMAGE_NOTIFY = 0x0200, // dataCallback 83 // Preview frame metadata. This can be combined with 84 // CAMERA_MSG_PREVIEW_FRAME in dataCallback. For example, the apps can 85 // request FRAME and METADATA. Or the apps can request only FRAME or only 86 // METADATA. 87 CAMERA_MSG_PREVIEW_METADATA = 0x0400, // dataCallback 88 // Notify on autofocus start and stop. This is useful in continuous 89 // autofocus - FOCUS_MODE_CONTINUOUS_VIDEO and FOCUS_MODE_CONTINUOUS_PICTURE. 90 CAMERA_MSG_FOCUS_MOVE = 0x0800, // notifyCallback 91 CAMERA_MSG_ALL_MSGS = 0xFFFF 92 }; 93 94 /** cmdType in sendCommand functions */ 95 enum { 96 CAMERA_CMD_START_SMOOTH_ZOOM = 1, 97 CAMERA_CMD_STOP_SMOOTH_ZOOM = 2, 98 99 /** 100 * Set the clockwise rotation of preview display (setPreviewDisplay) in 101 * degrees. This affects the preview frames and the picture displayed after 102 * snapshot. This method is useful for portrait mode applications. Note 103 * that preview display of front-facing cameras is flipped horizontally 104 * before the rotation, that is, the image is reflected along the central 105 * vertical axis of the camera sensor. So the users can see themselves as 106 * looking into a mirror. 107 * 108 * This does not affect the order of byte array of 109 * CAMERA_MSG_PREVIEW_FRAME, CAMERA_MSG_VIDEO_FRAME, 110 * CAMERA_MSG_POSTVIEW_FRAME, CAMERA_MSG_RAW_IMAGE, or 111 * CAMERA_MSG_COMPRESSED_IMAGE. This is allowed to be set during preview 112 * since API level 14. 113 */ 114 CAMERA_CMD_SET_DISPLAY_ORIENTATION = 3, 115 116 /** 117 * cmdType to disable/enable shutter sound. In sendCommand passing arg1 = 118 * 0 will disable, while passing arg1 = 1 will enable the shutter sound. 119 */ 120 CAMERA_CMD_ENABLE_SHUTTER_SOUND = 4, 121 122 /* cmdType to play recording sound */ 123 CAMERA_CMD_PLAY_RECORDING_SOUND = 5, 124 125 /** 126 * Start the face detection. This should be called after preview is started. 127 * The camera will notify the listener of CAMERA_MSG_FACE and the detected 128 * faces in the preview frame. The detected faces may be the same as the 129 * previous ones. Apps should call CAMERA_CMD_STOP_FACE_DETECTION to stop 130 * the face detection. This method is supported if CameraParameters 131 * KEY_MAX_NUM_HW_DETECTED_FACES or KEY_MAX_NUM_SW_DETECTED_FACES is 132 * bigger than 0. Hardware and software face detection should not be running 133 * at the same time. If the face detection has started, apps should not send 134 * this again. 135 * 136 * In hardware face detection mode, CameraParameters KEY_WHITE_BALANCE, 137 * KEY_FOCUS_AREAS and KEY_METERING_AREAS have no effect. 138 * 139 * arg1 is the face detection type. It can be CAMERA_FACE_DETECTION_HW or 140 * CAMERA_FACE_DETECTION_SW. If the type of face detection requested is not 141 * supported, the HAL must return BAD_VALUE. 142 */ 143 CAMERA_CMD_START_FACE_DETECTION = 6, 144 145 /** 146 * Stop the face detection. 147 */ 148 CAMERA_CMD_STOP_FACE_DETECTION = 7, 149 150 /** 151 * Enable/disable focus move callback (CAMERA_MSG_FOCUS_MOVE). Passing 152 * arg1 = 0 will disable, while passing arg1 = 1 will enable the callback. 153 */ 154 CAMERA_CMD_ENABLE_FOCUS_MOVE_MSG = 8, 155 156 /** 157 * Ping camera service to see if camera hardware is released. 158 * 159 * When any camera method returns error, the client can use ping command 160 * to see if the camera has been taken away by other clients. If the result 161 * is OK, it means the camera hardware is not released. If the result 162 * is not OK, the camera has been released and the existing client 163 * can silently finish itself or show a dialog. 164 */ 165 CAMERA_CMD_PING = 9, 166 167 /** 168 * Configure the number of video buffers used for recording. The intended 169 * video buffer count for recording is passed as arg1, which must be 170 * greater than 0. This command must be sent before recording is started. 171 * This command returns INVALID_OPERATION error if it is sent after video 172 * recording is started, or the command is not supported at all. This 173 * command also returns a BAD_VALUE error if the intended video buffer 174 * count is non-positive or too big to be realized. 175 */ 176 CAMERA_CMD_SET_VIDEO_BUFFER_COUNT = 10, 177 178 /** 179 * Configure an explicit format to use for video recording metadata mode. 180 * This can be used to switch the format from the 181 * default IMPLEMENTATION_DEFINED gralloc format to some other 182 * device-supported format, and the default dataspace from the BT_709 color 183 * space to some other device-supported dataspace. arg1 is the HAL pixel 184 * format, and arg2 is the HAL dataSpace. This command returns 185 * INVALID_OPERATION error if it is sent after video recording is started, 186 * or the command is not supported at all. 187 * 188 * If the gralloc format is set to a format other than 189 * IMPLEMENTATION_DEFINED, then HALv3 devices will use gralloc usage flags 190 * of SW_READ_OFTEN. 191 */ 192 CAMERA_CMD_SET_VIDEO_FORMAT = 11 193 }; 194 195 /** camera fatal errors */ 196 enum { 197 CAMERA_ERROR_UNKNOWN = 1, 198 /** 199 * Camera was released because another client has connected to the camera. 200 * The original client should call Camera::disconnect immediately after 201 * getting this notification. Otherwise, the camera will be released by 202 * camera service in a short time. The client should not call any method 203 * (except disconnect and sending CAMERA_CMD_PING) after getting this. 204 */ 205 CAMERA_ERROR_RELEASED = 2, 206 207 /** 208 * Camera was released because device policy change or the client application 209 * is going to background. The client should call Camera::disconnect 210 * immediately after getting this notification. Otherwise, the camera will be 211 * released by camera service in a short time. The client should not call any 212 * method (except disconnect and sending CAMERA_CMD_PING) after getting this. 213 */ 214 CAMERA_ERROR_DISABLED = 3, 215 CAMERA_ERROR_SERVER_DIED = 100 216 }; 217 218 enum { 219 /** The facing of the camera is opposite to that of the screen. */ 220 CAMERA_FACING_BACK = 0, 221 /** The facing of the camera is the same as that of the screen. */ 222 CAMERA_FACING_FRONT = 1, 223 /** 224 * The facing of the camera is not fixed relative to the screen. 225 * The cameras with this facing are external cameras, e.g. USB cameras. 226 */ 227 CAMERA_FACING_EXTERNAL = 2 228 }; 229 230 enum { 231 /** Hardware face detection. It does not use much CPU. */ 232 CAMERA_FACE_DETECTION_HW = 0, 233 /** 234 * Software face detection. It uses some CPU. Applications must use 235 * Camera.setPreviewTexture for preview in this mode. 236 */ 237 CAMERA_FACE_DETECTION_SW = 1 238 }; 239 240 /** 241 * The information of a face from camera face detection. 242 */ 243 typedef struct camera_face { 244 /** 245 * Bounds of the face [left, top, right, bottom]. (-1000, -1000) represents 246 * the top-left of the camera field of view, and (1000, 1000) represents the 247 * bottom-right of the field of view. The width and height cannot be 0 or 248 * negative. This is supported by both hardware and software face detection. 249 * 250 * The direction is relative to the sensor orientation, that is, what the 251 * sensor sees. The direction is not affected by the rotation or mirroring 252 * of CAMERA_CMD_SET_DISPLAY_ORIENTATION. 253 */ 254 int32_t rect[4]; 255 256 /** 257 * The confidence level of the face. The range is 1 to 100. 100 is the 258 * highest confidence. This is supported by both hardware and software 259 * face detection. 260 */ 261 int32_t score; 262 263 /** 264 * An unique id per face while the face is visible to the tracker. If 265 * the face leaves the field-of-view and comes back, it will get a new 266 * id. If the value is 0, id is not supported. 267 */ 268 int32_t id; 269 270 /** 271 * The coordinates of the center of the left eye. The range is -1000 to 272 * 1000. -2000, -2000 if this is not supported. 273 */ 274 int32_t left_eye[2]; 275 276 /** 277 * The coordinates of the center of the right eye. The range is -1000 to 278 * 1000. -2000, -2000 if this is not supported. 279 */ 280 int32_t right_eye[2]; 281 282 /** 283 * The coordinates of the center of the mouth. The range is -1000 to 1000. 284 * -2000, -2000 if this is not supported. 285 */ 286 int32_t mouth[2]; 287 288 } camera_face_t; 289 290 /** 291 * The metadata of the frame data. 292 */ 293 typedef struct camera_frame_metadata { 294 /** 295 * The number of detected faces in the frame. 296 */ 297 int32_t number_of_faces; 298 299 /** 300 * An array of the detected faces. The length is number_of_faces. 301 */ 302 camera_face_t *faces; 303 } camera_frame_metadata_t; 304 305 __END_DECLS 306 307 #endif /* SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_H */ 308