1 page.title=Camera Version 1 2 @jd:body 3 4 <!-- 5 Copyright 2010 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <p>Android's camera HAL connects the higher level 28 camera framework APIs in <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> to your underlying camera driver and hardware. 29 The following figure and list describe the components involved and where to find the source for each: 30 </p> 31 32 <p><img src="images/camera_hal.png"></p> 33 34 <dl> 35 36 <dt>Application framework</dt> 37 <dd>At the application framework level is the app's code, which utilizes the <a 38 href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 39 API to interact with the camera hardware. Internally, this code calls a corresponding JNI glue class 40 to access the native code that interacts with the camera.</dd> 41 42 <dt>JNI</dt> 43 <dd>The JNI code associated with <a 44 href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> is located in 45 <code>frameworks/base/core/jni/android_hardware_Camera.cpp</code>. This code calls the lower level 46 native code to obtain access to the physical camera and returns data that is used to create the 47 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> object at the framework level.</dd> 48 49 <dt>Native framework<dt> 50 <dd>The native framework defined in <code>frameworks/av/camera/Camera.cpp</code> provides a native equivalent 51 to the <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> class. 52 This class calls the IPC binder proxies to obtain access to the camera service.</dd> 53 54 <dt>Binder IPC proxies</dt> 55 <dd>The IPC binder proxies facilitate communication over process boundaries. There are three camera binder 56 classes that are located in the <code>frameworks/av/camera</code> directory that calls into 57 camera service. ICameraService is the interface to the camera service, ICamera is the interface 58 to a specific opened camera device, and ICameraClient is the device's interface back to the application framework.</dd> 59 60 <dt>Camera service</dt> 61 <dd>The camera service, located in <code>frameworks/av/services/camera/libcameraservice/CameraService.cpp</code>, is the actual code that interacts with the HAL.</p> 62 63 <dt>HAL</dt> 64 <dd>The hardware abstraction layer defines the standard interface that the camera service calls into and that 65 you must implement to have your camera hardware function correctly. 66 </dd> 67 68 <dt>Kernel driver</dt> 69 <dd>The camera's driver interacts with the actual camera hardware and your implementation of the HAL. The 70 camera and driver must support YV12 and NV21 image formats to provide support for 71 previewing the camera image on the display and video recording.</dd> 72 </dl> 73 74 75 <h2 id="implementing">Implementing the HAL</h2> 76 <p>The HAL sits between the camera driver and the higher level Android framework 77 and defines an interface that you must implement so that apps can 78 correctly operate the camera hardware. The HAL interface is defined in the 79 <code>hardware/libhardware/include/hardware/camera.h</code> and 80 <code>hardware/libhardware/include/hardware/camera_common.h</code> header files. 81 </p> 82 83 <p> 84 <code>camera_common.h</code> defines an important struct, <code>camera_module</code>, which defines a standard 85 structure to obtain general information about the camera, such as its ID and properties 86 that are common to all cameras such as whether or not it is a front or back-facing camera. 87 </p> 88 89 <p> 90 <code>camera.h</code> contains the code that corresponds mainly with 91 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>. This header file declares a <code>camera_device</code> 92 struct that contains a<code>camera_device_ops</code> struct with function pointers 93 that point to functions that implement the HAL interface. For documentation on the 94 different types of camera parameters that a developer can set, 95 see the <code>frameworks/av/include/camera/CameraParameters.h</code> file. 96 These parameters are set with the function pointed to by 97 <code>int (*set_parameters)(struct camera_device *, const char *parms)</code> in the HAL. 98 </p> 99 100 <p>For an example of a HAL implementation, see the implementation for the Galaxy Nexus HAL in 101 <code>hardware/ti/omap4xxx/camera</code>.</p> 102 103 104 <h2 id="configuring">Configuring the Shared Library</h2> 105 <p>You need to set up the Android build system to 106 correctly package the HAL implementation into a shared library and copy it to the 107 appropriate location by creating an <code>Android.mk</code> file: 108 109 <ol> 110 <li>Create a <code>device/<company_name>/<device_name>/camera</code> directory to contain your 111 library's source files.</li> 112 <li>Create an <code>Android.mk</code> file to build the shared library. Ensure that the Makefile contains the following lines: 113 <pre> 114 LOCAL_MODULE := camera.<device_name> 115 LOCAL_MODULE_PATH := $(TARGET_OUT_SHARED_LIBRARIES)/hw 116 </pre> 117 <p>Notice that your library must be named <code>camera.<device_name></code> (<code>.so</code> is appended automatically), 118 so that Android can correctly load the library. For an example, see the Makefile 119 for the Galaxy Nexus camera located in <code>hardware/ti/omap4xxx/Android.mk</code>.</p> 120 121 </li> 122 <li>Specify that your device has camera features by copying the necessary feature XML files in the 123 <code>frameworks/native/data/etc</code> directory with your 124 device's Makefile. For example, to specify that your device has a camera flash and can autofocus, 125 add the following lines in your device's 126 <code><device>/<company_name>/<device_name>/device.mk</code> Makefile: 127 128 <pre class="no-pretty-print"> 129 PRODUCT_COPY_FILES := \ ... 130 131 PRODUCT_COPY_FILES += \ 132 frameworks/native/data/etc/android.hardware.camera.flash-autofocus.xml:system/etc/permissions/android.hardware.camera.flash-autofocus.xml \ 133 </pre> 134 135 <p>For an example of a device Makefile, see <code>device/samsung/tuna/device.mk</code>.</p> 136 </li> 137 138 <li>Declare your cameras media codec, format, and resolution capabilities in 139 <code>device/<company_name>/<device_name>/media_profiles.xml</code> and 140 <code>device/<company_name>/<device_name>/media_codecs.xml</code> XML files. 141 For more information, see <a href="media.html#expose"> Exposing 142 Codecs and Profiles to the Framework</a> for information on how to do this. 143 </p></code> 144 145 </li> 146 147 <li>Add the following lines in your device's 148 <code>device/<company_name>/<device_name>/device.mk</code> 149 Makefile to copy the <code>media_profiles.xml</code> 150 and <code>media_codecs.xml</code> files to the appropriate location: 151 <pre> 152 # media config xml file 153 PRODUCT_COPY_FILES += \ 154 <device>/<company_name>/<device_name>/media_profiles.xml:system/etc/media_profiles.xml 155 156 # media codec config xml file 157 PRODUCT_COPY_FILES += \ 158 <device>/<company_name>/<device_name>/media_codecs.xml:system/etc/media_codecs.xml 159 </pre> 160 </li> 161 162 <li> 163 <p>Declare that you want to include the Camera app in your device's system image by 164 specifying it in the <code>PRODUCT_PACKAGES</code> variable in your device's 165 <code>device/<company_name>/<device_name>/device.mk</code> 166 Makefile:</p> 167 <pre> 168 PRODUCT_PACKAGES := \ 169 Gallery2 \ 170 ... 171 </pre> 172 </li> 173 174 </ol> 175