Home | History | Annotate | Download | only in system
      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 NO_ERROR, it means the camera hardware is not released. If the result
    162      * is not NO_ERROR, 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     CAMERA_ERROR_SERVER_DIED = 100
    207 };
    208 
    209 enum {
    210     /** The facing of the camera is opposite to that of the screen. */
    211     CAMERA_FACING_BACK = 0,
    212     /** The facing of the camera is the same as that of the screen. */
    213     CAMERA_FACING_FRONT = 1,
    214     /**
    215      * The facing of the camera is not fixed relative to the screen.
    216      * The cameras with this facing are external cameras, e.g. USB cameras.
    217      */
    218     CAMERA_FACING_EXTERNAL = 2
    219 };
    220 
    221 enum {
    222     /** Hardware face detection. It does not use much CPU. */
    223     CAMERA_FACE_DETECTION_HW = 0,
    224     /**
    225      * Software face detection. It uses some CPU. Applications must use
    226      * Camera.setPreviewTexture for preview in this mode.
    227      */
    228     CAMERA_FACE_DETECTION_SW = 1
    229 };
    230 
    231 /**
    232  * The information of a face from camera face detection.
    233  */
    234 typedef struct camera_face {
    235     /**
    236      * Bounds of the face [left, top, right, bottom]. (-1000, -1000) represents
    237      * the top-left of the camera field of view, and (1000, 1000) represents the
    238      * bottom-right of the field of view. The width and height cannot be 0 or
    239      * negative. This is supported by both hardware and software face detection.
    240      *
    241      * The direction is relative to the sensor orientation, that is, what the
    242      * sensor sees. The direction is not affected by the rotation or mirroring
    243      * of CAMERA_CMD_SET_DISPLAY_ORIENTATION.
    244      */
    245     int32_t rect[4];
    246 
    247     /**
    248      * The confidence level of the face. The range is 1 to 100. 100 is the
    249      * highest confidence. This is supported by both hardware and software
    250      * face detection.
    251      */
    252     int32_t score;
    253 
    254     /**
    255      * An unique id per face while the face is visible to the tracker. If
    256      * the face leaves the field-of-view and comes back, it will get a new
    257      * id. If the value is 0, id is not supported.
    258      */
    259     int32_t id;
    260 
    261     /**
    262      * The coordinates of the center of the left eye. The range is -1000 to
    263      * 1000. -2000, -2000 if this is not supported.
    264      */
    265     int32_t left_eye[2];
    266 
    267     /**
    268      * The coordinates of the center of the right eye. The range is -1000 to
    269      * 1000. -2000, -2000 if this is not supported.
    270      */
    271     int32_t right_eye[2];
    272 
    273     /**
    274      * The coordinates of the center of the mouth. The range is -1000 to 1000.
    275      * -2000, -2000 if this is not supported.
    276      */
    277     int32_t mouth[2];
    278 
    279 } camera_face_t;
    280 
    281 /**
    282  * The metadata of the frame data.
    283  */
    284 typedef struct camera_frame_metadata {
    285     /**
    286      * The number of detected faces in the frame.
    287      */
    288     int32_t number_of_faces;
    289 
    290     /**
    291      * An array of the detected faces. The length is number_of_faces.
    292      */
    293     camera_face_t *faces;
    294 } camera_frame_metadata_t;
    295 
    296 __END_DECLS
    297 
    298 #endif /* SYSTEM_CORE_INCLUDE_ANDROID_CAMERA_H */
    299