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 ANDROID_CAMERA_CAMERA_CAPTURE_H
18#define ANDROID_CAMERA_CAMERA_CAPTURE_H
19
20/*
21 * Contains declarations for video capturing API that is used by the camera
22 * emulator.
23 */
24
25#include "camera-common.h"
26
27/* Initializes camera device descriptor, and connects to the camera device.
28 * Param:
29 *  name - On Linux contains name of the device to be used to capture video.
30 *    On Windows contains name to assign to the capturing window. This parameter
31 *    can be NULL, in which case '/dev/video0' will be used as device name on
32 *    Linux, or 'AndroidEmulatorVC' on Windows.
33 *  inp_channel - On Linux defines input channel to use when communicating with
34 *    the camera driver. On Windows contains an index (up to 10) of the driver
35 *    to use to communicate with the camera device.
36 * Return:
37 *  Initialized camera device descriptor on success, or NULL on failure.
38 */
39extern CameraDevice* camera_device_open(const char* name, int inp_channel);
40
41/* Starts capturing frames from the camera device.
42 * Param:
43 *  cd - Camera descriptor representing a camera device opened in
44 *    camera_device_open routine.
45 *  pixel_format - Defines pixel format for the captured frames. Must be one of
46 *      the formats, supported by the camera device.
47 *  width, height - Frame dimensions for the captured video frame. Must match
48 *      dimensions supported by the camera for the pixel format defined by the
49 *      'pixel_format' parameter.
50 * Return:
51 *  0 on success, or non-zero value on failure.
52 */
53extern int camera_device_start_capturing(CameraDevice* cd,
54                                         uint32_t pixel_format,
55                                         int frame_width,
56                                         int frame_height);
57
58/* Stops capturing frames from the camera device.
59 * Param:
60 *  cd - Camera descriptor representing a camera device opened in
61 *    camera_device_open routine.
62 * Return:
63 *  0 on success, or non-zero value on failure.
64 */
65extern int camera_device_stop_capturing(CameraDevice* cd);
66
67/* Captures a frame from the camera device.
68 * Param:
69 *  cd - Camera descriptor representing a camera device opened in
70 *    camera_device_open routine.
71 *  framebuffers - Array of framebuffers where to read the frame. Size of this
72 *      array is defined by the 'fbs_num' parameter. Note that the caller must
73 *      make sure that buffers are large enough to contain entire frame captured
74 *      from the device.
75 *  fbs_num - Number of entries in the 'framebuffers' array.
76 *  r_scale, g_scale, b_scale - White balance scale.
77 *  exp_comp - Expsoure compensation.
78 * Return:
79 *  0 on success, or non-zero value on failure. There is a special vaule 1
80 *  returned from this routine which indicates that frames were not available in
81 *  the device. This value is returned on Linux implementation when frame ioctl
82 *  has returned EAGAIN error. The client should respond to this value by
83 *  repeating the read, rather than reporting an error.
84 */
85extern int camera_device_read_frame(CameraDevice* cd,
86                                    ClientFrameBuffer* framebuffers,
87                                    int fbs_num,
88                                    float r_scale,
89                                    float g_scale,
90                                    float b_scale,
91                                    float exp_comp);
92
93/* Closes camera device, opened in camera_device_open routine.
94 * Param:
95 *  cd - Camera descriptor representing a camera device opened in
96 *    camera_device_open routine.
97 */
98extern void camera_device_close(CameraDevice* cd);
99
100/* Enumerates camera devices connected to the host, and collects information
101 * about each device.
102 * Apparently, camera framework in the guest will only accept the the YV12
103 * (V4L2_PIX_FMT_YVU420) pixel format. So, we don't really need to report all the
104 * pixel formats, supported by the camera device back to the guest. We can simpy
105 * pick any format that is supported by the device, and collect frame dimensions
106 * available for it. The only thing we can do is to specifically check, if camera
107 * support YV12, and choose it, in order to spare some CPU cycles on the
108 * conversion.
109 * Param:
110 *  cis - An allocated array where to store informaion about found camera
111 *      devices. For each found camera device an entry will be initialized in the
112 *      array. It's responsibility of the caller to free the memory allocated for
113 *      the entries.
114 *  max - Maximum number of entries that can fit into the array.
115 * Return:
116 *  Number of entries added to the 'cis' array on success, or < 0 on failure.
117 */
118extern int enumerate_camera_devices(CameraInfo* cis, int max);
119
120#endif  /* ANDROID_CAMERA_CAMERA_CAPTURE_H */
121