include/hardware/camera.h

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