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 #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  * Supports the android.hardware.Camera API.
  26  *
  27  * Camera devices that support this version of the HAL must return a value in
  28  * the range HARDWARE_DEVICE_API_VERSION(0,0)-(1,FF) in
  29  * camera_device_t.common.version. CAMERA_DEVICE_API_VERSION_1_0 is the
  30  * recommended value.
  31  *
  32  * Camera modules that implement version 2.0 or higher of camera_module_t must
  33  * also return the value of camera_device_t.common.version in
  34  * camera_info_t.device_version.
  35  *
  36  * See camera_common.h for more details.
  37  */
  38
  39 __BEGIN_DECLS
  40
  41 struct camera_memory;
  42 typedef void (*camera_release_memory)(struct camera_memory *mem);
  43
  44 typedef struct camera_memory {
  45     void *data;
  46     size_t size;
  47     void *handle;
  48     camera_release_memory release;
  49 } camera_memory_t;
  50
  51 typedef camera_memory_t* (*camera_request_memory)(int fd, size_t buf_size, unsigned int num_bufs,
  52                                                   void *user);
  53
  54 typedef void (*camera_notify_callback)(int32_t msg_type,
  55         int32_t ext1,
  56         int32_t ext2,
  57         void *user);
  58
  59 typedef void (*camera_data_callback)(int32_t msg_type,
  60         const camera_memory_t *data, unsigned int index,
  61         camera_frame_metadata_t *metadata, void *user);
  62
  63 typedef void (*camera_data_timestamp_callback)(int64_t timestamp,
  64         int32_t msg_type,
  65         const camera_memory_t *data, unsigned int index,
  66         void *user);
  67
  68 #define HAL_CAMERA_PREVIEW_WINDOW_TAG 0xcafed00d
  69
  70 typedef struct preview_stream_ops {
  71     int (*dequeue_buffer)(struct preview_stream_ops* w,
  72                           buffer_handle_t** buffer, int *stride);
  73     int (*enqueue_buffer)(struct preview_stream_ops* w,
  74                 buffer_handle_t* buffer);
  75     int (*cancel_buffer)(struct preview_stream_ops* w,
  76                 buffer_handle_t* buffer);
  77     int (*set_buffer_count)(struct preview_stream_ops* w, int count);
  78 #ifdef HTC_3D_SUPPORT
  79     int (*set_3d_mode)(const struct preview_stream_ops *w, int r1, int r2, int r3);
  80 #endif
  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 */