include/hardware/camera_common.h

   1 /*
   2  * Copyright (C) 2012 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_COMMON_H
  20 #define ANDROID_INCLUDE_CAMERA_COMMON_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 <system/camera_vendor_tags.h>
  28 #include <hardware/hardware.h>
  29 #include <hardware/gralloc.h>
  30
  31 __BEGIN_DECLS
  32
  33 /**
  34  * The id of this module
  35  */
  36 #define CAMERA_HARDWARE_MODULE_ID "camera"
  37
  38 /**
  39  * Module versioning information for the Camera hardware module, based on
  40  * camera_module_t.common.module_api_version. The two most significant hex
  41  * digits represent the major version, and the two least significant represent
  42  * the minor version.
  43  *
  44  *******************************************************************************
  45  * Versions: 0.X - 1.X [CAMERA_MODULE_API_VERSION_1_0]
  46  *
  47  *   Camera modules that report these version numbers implement the initial
  48  *   camera module HAL interface. All camera devices openable through this
  49  *   module support only version 1 of the camera device HAL. The device_version
  50  *   and static_camera_characteristics fields of camera_info are not valid. Only
  51  *   the android.hardware.Camera API can be supported by this module and its
  52  *   devices.
  53  *
  54  *******************************************************************************
  55  * Version: 2.0 [CAMERA_MODULE_API_VERSION_2_0]
  56  *
  57  *   Camera modules that report this version number implement the second version
  58  *   of the camera module HAL interface. Camera devices openable through this
  59  *   module may support either version 1.0 or version 2.0 of the camera device
  60  *   HAL interface. The device_version field of camera_info is always valid; the
  61  *   static_camera_characteristics field of camera_info is valid if the
  62  *   device_version field is 2.0 or higher.
  63  *
  64  *******************************************************************************
  65  * Version: 2.1 [CAMERA_MODULE_API_VERSION_2_1]
  66  *
  67  *   This camera module version adds support for asynchronous callbacks to the
  68  *   framework from the camera HAL module, which is used to notify the framework
  69  *   about changes to the camera module state. Modules that provide a valid
  70  *   set_callbacks() method must report at least this version number.
  71  *
  72  *******************************************************************************
  73  * Version: 2.2 [CAMERA_MODULE_API_VERSION_2_2]
  74  *
  75  *   This camera module version adds vendor tag support from the module, and
  76  *   deprecates the old vendor_tag_query_ops that were previously only
  77  *   accessible with a device open.
  78  *
  79  *******************************************************************************
  80  * Version: 2.3 [CAMERA_MODULE_API_VERSION_2_3]
  81  *
  82  *   This camera module version adds open legacy camera HAL device support.
  83  *   Framework can use it to open the camera device as lower device HAL version
  84  *   HAL device if the same device can support multiple device API versions.
  85  *   The standard hardware module open call (common.methods->open) continues
  86  *   to open the camera device with the latest supported version, which is
  87  *   also the version listed in camera_info_t.device_version.
  88  */
  89
  90 /**
  91  * Predefined macros for currently-defined version numbers
  92  */
  93
  94 /**
  95  * All module versions <= HARDWARE_MODULE_API_VERSION(1, 0xFF) must be treated
  96  * as CAMERA_MODULE_API_VERSION_1_0
  97  */
  98 #define CAMERA_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
  99 #define CAMERA_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0)
 100 #define CAMERA_MODULE_API_VERSION_2_1 HARDWARE_MODULE_API_VERSION(2, 1)
 101 #define CAMERA_MODULE_API_VERSION_2_2 HARDWARE_MODULE_API_VERSION(2, 2)
 102 #define CAMERA_MODULE_API_VERSION_2_3 HARDWARE_MODULE_API_VERSION(2, 3)
 103
 104 #define CAMERA_MODULE_API_VERSION_CURRENT CAMERA_MODULE_API_VERSION_2_3
 105
 106 /**
 107  * All device versions <= HARDWARE_DEVICE_API_VERSION(1, 0xFF) must be treated
 108  * as CAMERA_DEVICE_API_VERSION_1_0
 109  */
 110 #define CAMERA_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
 111 #define CAMERA_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
 112 #define CAMERA_DEVICE_API_VERSION_2_1 HARDWARE_DEVICE_API_VERSION(2, 1)
 113 #define CAMERA_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
 114 #define CAMERA_DEVICE_API_VERSION_3_1 HARDWARE_DEVICE_API_VERSION(3, 1)
 115 #define CAMERA_DEVICE_API_VERSION_3_2 HARDWARE_DEVICE_API_VERSION(3, 2)
 116
 117 // Device version 3.2 is current, older HAL camera device versions are not
 118 // recommended for new devices.
 119 #define CAMERA_DEVICE_API_VERSION_CURRENT CAMERA_DEVICE_API_VERSION_3_2
 120
 121 /**
 122  * Defined in /system/media/camera/include/system/camera_metadata.h
 123  */
 124 typedef struct camera_metadata camera_metadata_t;
 125
 126 typedef struct camera_info {
 127     /**
 128      * The direction that the camera faces to. It should be CAMERA_FACING_BACK
 129      * or CAMERA_FACING_FRONT.
 130      *
 131      * Version information:
 132      *   Valid in all camera_module versions
 133      */
 134     int facing;
 135
 136     /**
 137      * The orientation of the camera image. The value is the angle that the
 138      * camera image needs to be rotated clockwise so it shows correctly on the
 139      * display in its natural orientation. It should be 0, 90, 180, or 270.
 140      *
 141      * For example, suppose a device has a naturally tall screen. The
 142      * back-facing camera sensor is mounted in landscape. You are looking at the
 143      * screen. If the top side of the camera sensor is aligned with the right
 144      * edge of the screen in natural orientation, the value should be 90. If the
 145      * top side of a front-facing camera sensor is aligned with the right of the
 146      * screen, the value should be 270.
 147      *
 148      * Version information:
 149      *   Valid in all camera_module versions
 150      */
 151     int orientation;
 152
 153     /**
 154      * The value of camera_device_t.common.version.
 155      *
 156      * Version information (based on camera_module_t.common.module_api_version):
 157      *
 158      *  CAMERA_MODULE_API_VERSION_1_0:
 159      *
 160      *    Not valid. Can be assumed to be CAMERA_DEVICE_API_VERSION_1_0. Do
 161      *    not read this field.
 162      *
 163      *  CAMERA_MODULE_API_VERSION_2_0 or higher:
 164      *
 165      *    Always valid
 166      *
 167      */
 168     uint32_t device_version;
 169
 170     /**
 171      * The camera's fixed characteristics, which include all camera metadata in
 172      * the android.*.info.* sections. This should be a sorted metadata buffer,
 173      * and may not be modified or freed by the caller. The pointer should remain
 174      * valid for the lifetime of the camera module, and values in it may not
 175      * change after it is returned by get_camera_info().
 176      *
 177      * Version information (based on camera_module_t.common.module_api_version):
 178      *
 179      *  CAMERA_MODULE_API_VERSION_1_0:
 180      *
 181      *    Not valid. Extra characteristics are not available. Do not read this
 182      *    field.
 183      *
 184      *  CAMERA_MODULE_API_VERSION_2_0 or higher:
 185      *
 186      *    Valid if device_version >= CAMERA_DEVICE_API_VERSION_2_0. Do not read
 187      *    otherwise.
 188      *
 189      */
 190     const camera_metadata_t *static_camera_characteristics;
 191 } camera_info_t;
 192
 193 /**
 194  * camera_device_status_t:
 195  *
 196  * The current status of the camera device, as provided by the HAL through the
 197  * camera_module_callbacks.camera_device_status_change() call.
 198  *
 199  * At module load time, the framework will assume all camera devices are in the
 200  * CAMERA_DEVICE_STATUS_PRESENT state. The HAL should invoke
 201  * camera_module_callbacks::camera_device_status_change to inform the framework
 202  * of any initially NOT_PRESENT devices.
 203  *
 204  * Allowed transitions:
 205  *      PRESENT            -> NOT_PRESENT
 206  *      NOT_PRESENT        -> ENUMERATING
 207  *      NOT_PRESENT        -> PRESENT
 208  *      ENUMERATING        -> PRESENT
 209  *      ENUMERATING        -> NOT_PRESENT
 210  */
 211 typedef enum camera_device_status {
 212     /**
 213      * The camera device is not currently connected, and opening it will return
 214      * failure. Calls to get_camera_info must still succeed, and provide the
 215      * same information it would if the camera were connected
 216      */
 217     CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
 218
 219     /**
 220      * The camera device is connected, and opening it will succeed. The
 221      * information returned by get_camera_info cannot change due to this status
 222      * change. By default, the framework will assume all devices are in this
 223      * state.
 224      */
 225     CAMERA_DEVICE_STATUS_PRESENT = 1,
 226
 227     /**
 228      * The camera device is connected, but it is undergoing an enumeration and
 229      * so opening the device will return -EBUSY. Calls to get_camera_info
 230      * must still succeed, as if the camera was in the PRESENT status.
 231      */
 232     CAMERA_DEVICE_STATUS_ENUMERATING = 2,
 233
 234 } camera_device_status_t;
 235
 236 /**
 237  * Callback functions for the camera HAL module to use to inform the framework
 238  * of changes to the camera subsystem. These are called only by HAL modules
 239  * implementing version CAMERA_MODULE_API_VERSION_2_1 or higher of the HAL
 240  * module API interface.
 241  */
 242 typedef struct camera_module_callbacks {
 243
 244     /**
 245      * camera_device_status_change:
 246      *
 247      * Callback to the framework to indicate that the state of a specific camera
 248      * device has changed. At module load time, the framework will assume all
 249      * camera devices are in the CAMERA_DEVICE_STATUS_PRESENT state. The HAL
 250      * must call this method to inform the framework of any initially
 251      * NOT_PRESENT devices.
 252      *
 253      * camera_module_callbacks: The instance of camera_module_callbacks_t passed
 254      *   to the module with set_callbacks.
 255      *
 256      * camera_id: The ID of the camera device that has a new status.
 257      *
 258      * new_status: The new status code, one of the camera_device_status_t enums,
 259      *   or a platform-specific status.
 260      *
 261      */
 262     void (*camera_device_status_change)(const struct camera_module_callbacks*,
 263             int camera_id,
 264             int new_status);
 265
 266 } camera_module_callbacks_t;
 267
 268 typedef struct camera_module {
 269     /**
 270      * Common methods of the camera module.  This *must* be the first member of
 271      * camera_module as users of this structure will cast a hw_module_t to
 272      * camera_module pointer in contexts where it's known the hw_module_t
 273      * references a camera_module.
 274      *
 275      * The return values for common.methods->open for camera_module are:
 276      *
 277      * 0:           On a successful open of the camera device.
 278      *
 279      * -ENODEV:     The camera device cannot be opened due to an internal
 280      *              error.
 281      *
 282      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
 283      *              and/or the module is invalid.
 284      *
 285      * -EBUSY:      The camera device was already opened for this camera id
 286      *              (by using this method or open_legacy),
 287      *              regardless of the device HAL version it was opened as.
 288      *
 289      * -EUSERS:     The maximal number of camera devices that can be
 290      *              opened concurrently were opened already, either by
 291      *              this method or the open_legacy method.
 292      *
 293      * All other return values from common.methods->open will be treated as
 294      * -ENODEV.
 295      */
 296     hw_module_t common;
 297
 298     /**
 299      * get_number_of_cameras:
 300      *
 301      * Returns the number of camera devices accessible through the camera
 302      * module.  The camera devices are numbered 0 through N-1, where N is the
 303      * value returned by this call. The name of the camera device for open() is
 304      * simply the number converted to a string. That is, "0" for camera ID 0,
 305      * "1" for camera ID 1.
 306      *
 307      * The value here must be static, and cannot change after the first call to
 308      * this method
 309      */
 310     int (*get_number_of_cameras)(void);
 311
 312     /**
 313      * get_camera_info:
 314      *
 315      * Return the static camera information for a given camera device. This
 316      * information may not change for a camera device.
 317      *
 318      * Return values:
 319      *
 320      * 0:           On a successful operation
 321      *
 322      * -ENODEV:     The information cannot be provided due to an internal
 323      *              error.
 324      *
 325      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
 326      *              and/or the module is invalid.
 327      */
 328     int (*get_camera_info)(int camera_id, struct camera_info *info);
 329
 330     /**
 331      * set_callbacks:
 332      *
 333      * Provide callback function pointers to the HAL module to inform framework
 334      * of asynchronous camera module events. The framework will call this
 335      * function once after initial camera HAL module load, after the
 336      * get_number_of_cameras() method is called for the first time, and before
 337      * any other calls to the module.
 338      *
 339      * Version information (based on camera_module_t.common.module_api_version):
 340      *
 341      *  CAMERA_MODULE_API_VERSION_1_0, CAMERA_MODULE_API_VERSION_2_0:
 342      *
 343      *    Not provided by HAL module. Framework may not call this function.
 344      *
 345      *  CAMERA_MODULE_API_VERSION_2_1:
 346      *
 347      *    Valid to be called by the framework.
 348      *
 349      * Return values:
 350      *
 351      * 0:           On a successful operation
 352      *
 353      * -ENODEV:     The operation cannot be completed due to an internal
 354      *              error.
 355      *
 356      * -EINVAL:     The input arguments are invalid, i.e. the callbacks are
 357      *              null
 358      */
 359     int (*set_callbacks)(const camera_module_callbacks_t *callbacks);
 360
 361     /**
 362      * get_vendor_tag_ops:
 363      *
 364      * Get methods to query for vendor extension metadata tag information. The
 365      * HAL should fill in all the vendor tag operation methods, or leave ops
 366      * unchanged if no vendor tags are defined.
 367      *
 368      * The vendor_tag_ops structure used here is defined in:
 369      * system/media/camera/include/system/vendor_tags.h
 370      *
 371      * Version information (based on camera_module_t.common.module_api_version):
 372      *
 373      *  CAMERA_MODULE_API_VERSION_1_x/2_0/2_1:
 374      *    Not provided by HAL module. Framework may not call this function.
 375      *
 376      *  CAMERA_MODULE_API_VERSION_2_2:
 377      *    Valid to be called by the framework.
 378      */
 379     void (*get_vendor_tag_ops)(vendor_tag_ops_t* ops);
 380
 381     /**
 382      * open_legacy:
 383      *
 384      * Open a specific legacy camera HAL device if multiple device HAL API
 385      * versions are supported by this camera HAL module. For example, if the
 386      * camera module supports both CAMERA_DEVICE_API_VERSION_1_0 and
 387      * CAMERA_DEVICE_API_VERSION_3_2 device API for the same camera id,
 388      * framework can call this function to open the camera device as
 389      * CAMERA_DEVICE_API_VERSION_1_0 device.
 390      *
 391      * This is an optional method. A Camera HAL module does not need to support
 392      * more than one device HAL version per device, and such modules may return
 393      * -ENOSYS for all calls to this method. For all older HAL device API
 394      * versions that are not supported, it may return -EOPNOTSUPP. When above
 395      * cases occur, The normal open() method (common.methods->open) will be
 396      * used by the framework instead.
 397      *
 398      * Version information (based on camera_module_t.common.module_api_version):
 399      *
 400      *  CAMERA_MODULE_API_VERSION_1_x/2_0/2_1/2_2:
 401      *    Not provided by HAL module. Framework will not call this function.
 402      *
 403      *  CAMERA_MODULE_API_VERSION_2_3:
 404      *    Valid to be called by the framework.
 405      *
 406      * Return values:
 407      *
 408      * 0:           On a successful open of the camera device.
 409      *
 410      * -ENOSYS      This method is not supported.
 411      *
 412      * -EOPNOTSUPP: The requested HAL version is not supported by this method.
 413      *
 414      * -EINVAL:     The input arguments are invalid, i.e. the id is invalid,
 415      *              and/or the module is invalid.
 416      *
 417      * -EBUSY:      The camera device was already opened for this camera id
 418      *              (by using this method or common.methods->open method),
 419      *              regardless of the device HAL version it was opened as.
 420      *
 421      * -EUSERS:     The maximal number of camera devices that can be
 422      *              opened concurrently were opened already, either by
 423      *              this method or common.methods->open method.
 424      */
 425     int (*open_legacy)(const struct hw_module_t* module, const char* id,
 426             uint32_t halVersion, struct hw_device_t** device);
 427
 428     /* reserved for future use */
 429     void* reserved[7];
 430 } camera_module_t;
 431
 432 __END_DECLS
 433
 434 #endif /* ANDROID_INCLUDE_CAMERA_COMMON_H */