1 /* 2 * Copyright (C) 2010-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 ANDROID_INCLUDE_CAMERA_H 18 #define ANDROID_INCLUDE_CAMERA_H 19 20 #include "camera_common.h" 21 22 /** 23 * Camera device HAL, initial version [ CAMERA_DEVICE_API_VERSION_1_0 ] 24 * 25 * DEPRECATED. New devices should use Camera HAL v3.2 or newer. 26 * 27 * Supports the android.hardware.Camera API, and the android.hardware.camera2 28 * API in legacy mode only. 29 * 30 * Camera devices that support this version of the HAL must return a value in 31 * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in 32 * camera_device_t.common.version. CAMERA_DEVICE_API_VERSION_1_0 is the 33 * recommended value. 34 * 35 * Camera modules that implement version 2.0 or higher of camera_module_t must 36 * also return the value of camera_device_t.common.version in 37 * camera_info_t.device_version. 38 * 39 * See camera_common.h for more details. 40 */ 41 42 __BEGIN_DECLS 43 44 struct camera_memory; 45 typedef void (*camera_release_memory)(struct camera_memory *mem); 46 47 typedef struct camera_memory { 48 void *data; 49 size_t size; 50 void *handle; 51 camera_release_memory release; 52 } camera_memory_t; 53 54 typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs, 55 void *user); 56 57 typedef void (*camera_notify_callback)(int32_t msg_type, 58 int32_t ext1, 59 int32_t ext2, 60 void *user); 61 62 typedef void (*camera_data_callback)(int32_t msg_type, 63 const camera_memory_t *data, unsigned int index, 64 camera_frame_metadata_t *metadata, void *user); 65 66 typedef void (*camera_data_timestamp_callback)(int64_t timestamp, 67 int32_t msg_type, 68 const camera_memory_t *data, unsigned int index, 69 void *user); 70 71 #define HAL_CAMERA_PREVIEW_WINDOW_TAG 0xcafed00d 72 73 typedef struct preview_stream_ops { 74 int (*dequeue_buffer)(struct preview_stream_ops* w, 75 buffer_handle_t** buffer, int *stride); 76 int (*enqueue_buffer)(struct preview_stream_ops* w, 77 buffer_handle_t* buffer); 78 int (*cancel_buffer)(struct preview_stream_ops* w, 79 buffer_handle_t* buffer); 80 int (*set_buffer_count)(struct preview_stream_ops* w, int count); 81 int (*set_buffers_geometry)(struct preview_stream_ops* pw, 82 int w, int h, int format); 83 int (*set_crop)(struct preview_stream_ops *w, 84 int left, int top, int right, int bottom); 85 int (*set_usage)(struct preview_stream_ops* w, int usage); 86 int (*set_swap_interval)(struct preview_stream_ops *w, int interval); 87 int (*get_min_undequeued_buffer_count)(const struct preview_stream_ops *w, 88 int *count); 89 int (*lock_buffer)(struct preview_stream_ops* w, 90 buffer_handle_t* buffer); 91 // Timestamps are measured in nanoseconds, and must be comparable 92 // and monotonically increasing between two frames in the same 93 // preview stream. They do not need to be comparable between 94 // consecutive or parallel preview streams, cameras, or app runs. 95 int (*set_timestamp)(struct preview_stream_ops *w, int64_t timestamp); 96 } preview_stream_ops_t; 97 98 struct camera_device; 99 typedef struct camera_device_ops { 100 /** Set the ANativeWindow to which preview frames are sent */ 101 int (*set_preview_window)(struct camera_device *, 102 struct preview_stream_ops *window); 103 104 /** Set the notification and data callbacks */ 105 void (*set_callbacks)(struct camera_device *, 106 camera_notify_callback notify_cb, 107 camera_data_callback data_cb, 108 camera_data_timestamp_callback data_cb_timestamp, 109 camera_request_memory get_memory, 110 void *user); 111 112 /** 113 * The following three functions all take a msg_type, which is a bitmask of 114 * the messages defined in include/ui/Camera.h 115 */ 116 117 /** 118 * Enable a message, or set of messages. 119 */ 120 void (*enable_msg_type)(struct camera_device *, int32_t msg_type); 121 122 /** 123 * Disable a message, or a set of messages. 124 * 125 * Once received a call to disableMsgType(CAMERA_MSG_VIDEO_FRAME), camera 126 * HAL should not rely on its client to call releaseRecordingFrame() to 127 * release video recording frames sent out by the cameral HAL before and 128 * after the disableMsgType(CAMERA_MSG_VIDEO_FRAME) call. Camera HAL 129 * clients must not modify/access any video recording frame after calling 130 * disableMsgType(CAMERA_MSG_VIDEO_FRAME). 131 */ 132 void (*disable_msg_type)(struct camera_device *, int32_t msg_type); 133 134 /** 135 * Query whether a message, or a set of messages, is enabled. Note that 136 * this is operates as an AND, if any of the messages queried are off, this 137 * will return false. 138 */ 139 int (*msg_type_enabled)(struct camera_device *, int32_t msg_type); 140 141 /** 142 * Start preview mode. 143 */ 144 int (*start_preview)(struct camera_device *); 145 146 /** 147 * Stop a previously started preview. 148 */ 149 void (*stop_preview)(struct camera_device *); 150 151 /** 152 * Returns true if preview is enabled. 153 */ 154 int (*preview_enabled)(struct camera_device *); 155 156 /** 157 * Request the camera HAL to store meta data or real YUV data in the video 158 * buffers sent out via CAMERA_MSG_VIDEO_FRAME for a recording session. If 159 * it is not called, the default camera HAL behavior is to store real YUV 160 * data in the video buffers. 161 * 162 * This method should be called before startRecording() in order to be 163 * effective. 164 * 165 * If meta data is stored in the video buffers, it is up to the receiver of 166 * the video buffers to interpret the contents and to find the actual frame 167 * data with the help of the meta data in the buffer. How this is done is 168 * outside of the scope of this method. 169 * 170 * Some camera HALs may not support storing meta data in the video buffers, 171 * but all camera HALs should support storing real YUV data in the video 172 * buffers. If the camera HAL does not support storing the meta data in the 173 * video buffers when it is requested to do do, INVALID_OPERATION must be 174 * returned. It is very useful for the camera HAL to pass meta data rather 175 * than the actual frame data directly to the video encoder, since the 176 * amount of the uncompressed frame data can be very large if video size is 177 * large. 178 * 179 * @param enable if true to instruct the camera HAL to store 180 * meta data in the video buffers; false to instruct 181 * the camera HAL to store real YUV data in the video 182 * buffers. 183 * 184 * @return OK on success. 185 */ 186 int (*store_meta_data_in_buffers)(struct camera_device *, int enable); 187 188 /** 189 * Start record mode. When a record image is available, a 190 * CAMERA_MSG_VIDEO_FRAME message is sent with the corresponding 191 * frame. Every record frame must be released by a camera HAL client via 192 * releaseRecordingFrame() before the client calls 193 * disableMsgType(CAMERA_MSG_VIDEO_FRAME). After the client calls 194 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 195 * responsibility to manage the life-cycle of the video recording frames, 196 * and the client must not modify/access any video recording frames. 197 */ 198 int (*start_recording)(struct camera_device *); 199 200 /** 201 * Stop a previously started recording. 202 */ 203 void (*stop_recording)(struct camera_device *); 204 205 /** 206 * Returns true if recording is enabled. 207 */ 208 int (*recording_enabled)(struct camera_device *); 209 210 /** 211 * Release a record frame previously returned by CAMERA_MSG_VIDEO_FRAME. 212 * 213 * It is camera HAL client's responsibility to release video recording 214 * frames sent out by the camera HAL before the camera HAL receives a call 215 * to disableMsgType(CAMERA_MSG_VIDEO_FRAME). After it receives the call to 216 * disableMsgType(CAMERA_MSG_VIDEO_FRAME), it is the camera HAL's 217 * responsibility to manage the life-cycle of the video recording frames. 218 */ 219 void (*release_recording_frame)(struct camera_device *, 220 const void *opaque); 221 222 /** 223 * Start auto focus, the notification callback routine is called with 224 * CAMERA_MSG_FOCUS once when focusing is complete. autoFocus() will be 225 * called again if another auto focus is needed. 226 */ 227 int (*auto_focus)(struct camera_device *); 228 229 /** 230 * Cancels auto-focus function. If the auto-focus is still in progress, 231 * this function will cancel it. Whether the auto-focus is in progress or 232 * not, this function will return the focus position to the default. If 233 * the camera does not support auto-focus, this is a no-op. 234 */ 235 int (*cancel_auto_focus)(struct camera_device *); 236 237 /** 238 * Take a picture. 239 */ 240 int (*take_picture)(struct camera_device *); 241 242 /** 243 * Cancel a picture that was started with takePicture. Calling this method 244 * when no picture is being taken is a no-op. 245 */ 246 int (*cancel_picture)(struct camera_device *); 247 248 /** 249 * Set the camera parameters. This returns BAD_VALUE if any parameter is 250 * invalid or not supported. 251 */ 252 int (*set_parameters)(struct camera_device *, const char *parms); 253 254 /** Retrieve the camera parameters. The buffer returned by the camera HAL 255 must be returned back to it with put_parameters, if put_parameters 256 is not NULL. 257 */ 258 char *(*get_parameters)(struct camera_device *); 259 260 /** The camera HAL uses its own memory to pass us the parameters when we 261 call get_parameters. Use this function to return the memory back to 262 the camera HAL, if put_parameters is not NULL. If put_parameters 263 is NULL, then you have to use free() to release the memory. 264 */ 265 void (*put_parameters)(struct camera_device *, char *); 266 267 /** 268 * Send command to camera driver. 269 */ 270 int (*send_command)(struct camera_device *, 271 int32_t cmd, int32_t arg1, int32_t arg2); 272 273 /** 274 * Release the hardware resources owned by this object. Note that this is 275 * *not* done in the destructor. 276 */ 277 void (*release)(struct camera_device *); 278 279 /** 280 * Dump state of the camera hardware 281 */ 282 int (*dump)(struct camera_device *, int fd); 283 } camera_device_ops_t; 284 285 typedef struct camera_device { 286 /** 287 * camera_device.common.version must be in the range 288 * HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF). CAMERA_DEVICE_API_VERSION_1_0 is 289 * recommended. 290 */ 291 hw_device_t common; 292 camera_device_ops_t *ops; 293 void *priv; 294 } camera_device_t; 295 296 __END_DECLS 297 298 #endif /* #ifdef ANDROID_INCLUDE_CAMERA_H */ 299