1 page.title=Camera 2 @jd:body 3 4 <!-- 5 Copyright 2015 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 <img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_camera.png" alt="Android Camera HAL icon"/> 28 29 <p>Android's camera Hardware Abstraction Layer (HAL) connects the higher level 30 camera framework APIs in 31 <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> 32 to your underlying camera driver and hardware. The camera subsystem includes 33 implementations for camera pipeline components while the camera HAL provides 34 interfaces for use in implementing your version of these components.</p> 35 36 <p>For the most up-to-date information, refer to the following resources:</p> 37 <ul> 38 <li><a href="{@docRoot}devices/halref/camera_8h_source.html">camera.h</a> source 39 file</li> 40 <li><a href="{@docRoot}devices/halref/camera3_8h_source.html">camera3.h</a> 41 source file</li> 42 <li><a href="{@docRoot}devices/halref/camera__common_8h_source.html">camera_common.h</a> 43 source file</li> 44 <li><a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html">CameraMetadata</a> 45 developer reference</li> 46 </ul> 47 48 49 <h2 id="architecture">Architecture</h2> 50 <p>The following figure and list describe the HAL components:</p> 51 52 <img src="images/ape_fwk_camera.png" alt="Android camera architecture" id="figure1" /> 53 <p class="img-caption"><strong>Figure 1.</strong> Camera architecture</p> 54 55 <dl> 56 <dt>Application framework</dt> 57 <dd>At the application framework level is the app's code, which utilizes the 58 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 59 API to interact with the camera hardware. Internally, this code calls a 60 corresponding JNI glue class to access the native code that interacts with the 61 camera.</dd> 62 <dt>JNI</dt> 63 <dd>The JNI code associated with <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 64 is located in 65 <code>frameworks/base/core/jni/android_hardware_Camera.cpp</code>. This code 66 calls the lower level native code to obtain access to the physical camera 67 and returns data that is used to create the 68 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 69 object at the framework level.</dd> 70 <dt>Native framework<dt> 71 <dd>The native framework defined in <code>frameworks/av/camera/Camera.cpp</code> 72 provides a native equivalent to the 73 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 74 class. This class calls the IPC binder proxies to obtain access to the camera 75 service.</dd> 76 <dt>Binder IPC proxies</dt> 77 <dd>The IPC binder proxies facilitate communication over process boundaries. 78 There are three camera binder classes that are located in 79 <code>frameworks/av/camera</code> directory that calls into camera service. 80 ICameraService is the interface to the camera service, ICamera is the 81 interface to a specific opened camera device, and ICameraClient is the 82 device's interface back to the application framework.</dd> 83 <dt>Camera service</dt> 84 <dd>The camera service, located in 85 <code>frameworks/av/services/camera/libcameraservice/CameraService.cpp</code>, 86 is the actual code that interacts with the HAL.</dd> 87 <dt>HAL</dt> 88 <dd>The hardware abstraction layer defines the standard interface that the 89 camera service calls into and that you must implement to have your camera 90 hardware function correctly.</dd> 91 <dt>Kernel driver</dt> 92 <dd>The camera's driver interacts with the actual camera hardware and your 93 implementation of the HAL. The camera and driver must support YV12 and NV21 94 image formats to provide support for previewing the camera image on the 95 display and video recording.</dd> 96 </dl> 97 98 <h2 id="implementing">Implementing the HAL</h2> 99 <p>The HAL sits between the camera driver and the higher level Android framework 100 and defines an interface you must implement so apps can correctly operate the 101 camera hardware. The HAL interface is defined in the 102 <code>hardware/libhardware/include/hardware/camera.h</code> and 103 <code>hardware/libhardware/include/hardware/camera_common.h</code> header files. 104 </p> 105 106 <p><code>camera_common.h</code> defines <code>camera_module</code>, a standard 107 structure to obtain general information about the camera, such as the camera ID 108 and properties common to all cameras (i.e., whether it is a front- or 109 back-facing camera).</p> 110 111 <p> 112 <code>camera.h</code> contains code that corresponds to 113 <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>. This header file declares a 114 <code>camera_device</code> struct that in turn contains a 115 <code>camera_device_ops</code> struct with pointers to functions that implement 116 the HAL interface. For documentation on the camera parameters developers can 117 set, refer to <code>frameworks/av/include/camera/CameraParameters.h</code>. 118 These parameters are set with the function pointed to by <code>int 119 (*set_parameters)(struct camera_device *, const char *parms)</code> in the HAL. 120 </p> 121 122 <p>For an example of a HAL implementation, refer to the implementation for the 123 Galaxy Nexus HAL in <code>hardware/ti/omap4xxx/camera</code>.</p> 124 125 126 <h2 id="configuring">Configuring the shared library</h2> 127 <p>Set up the Android build system to correctly package the HAL implementation 128 into a shared library and copy it to the appropriate location by creating an 129 <code>Android.mk</code> file:</p> 130 131 <ol> 132 <li>Create a <code>device/<company_name>/<device_name>/camera</code> 133 directory to contain your library's source files.</li> 134 135 <li>Create an <code>Android.mk</code> file to build the shared library. Ensure 136 the Makefile contains the following lines: 137 <pre> 138 LOCAL_MODULE := camera.<device_name> 139 LOCAL_MODULE_RELATIVE_PATH := hw 140 </pre> 141 <p>Your library must be named <code>camera.<device_name></code> 142 (<code>.so</code> is appended automatically), so Android can correctly load the 143 library. For an example, see the Makefile for the Galaxy Nexus camera located in 144 <code>hardware/ti/omap4xxx/Android.mk</code>.</p></li> 145 146 <li>Specify your device has camera features by copying the necessary feature XML 147 files in the <code>frameworks/native/data/etc</code> directory with your 148 device's Makefile. For example, to specify your device has a camera flash and 149 can autofocus, add the following lines in your device's 150 <code><device>/<company_name>/<device_name>/device.mk</code> 151 Makefile: 152 <pre class="no-pretty-print"> 153 PRODUCT_COPY_FILES := \ ... 154 155 PRODUCT_COPY_FILES += \ 156 frameworks/native/data/etc/android.hardware.camera.flash-autofocus.xml:system/etc/permissions/android.hardware.camera.flash-autofocus.xml \ 157 </pre> 158 <p>For an example of a device Makefile, see 159 <code>device/samsung/tuna/device.mk</code>.</p></li> 160 161 <li>Declare your cameras media codec, format, and resolution capabilities in 162 <code>device/<company_name>/<device_name>/media_profiles.xml</code> 163 and <code>device/<company_name>/<device_name>/media_codecs.xml</code> 164 XML files. For details, see 165 <a href="{@docRoot}devices/media/index.html#expose">Exposing codecs to the 166 framework</a>.</li> 167 168 <li>Add the following lines in your device's 169 <code>device/<company_name>/<device_name>/device.mk</code> Makefile 170 to copy the <code>media_profiles.xml</code> and <code>media_codecs.xml</code> 171 files to the appropriate location: 172 <pre> 173 # media config xml file 174 PRODUCT_COPY_FILES += \ 175 <device>/<company>/<device>/media_profiles.xml:system/etc/media_profiles.xml 176 177 # media codec config xml file 178 PRODUCT_COPY_FILES += \ 179 <device>/<company>/<device>/media_codecs.xml:system/etc/media_codecs.xml 180 </pre></li> 181 182 <li>To include the Camera app in your device's system image, specify it in the 183 <code>PRODUCT_PACKAGES</code> variable in your device's 184 <code>device/<company>/<device>/device.mk</code> 185 Makefile: 186 <pre> 187 PRODUCT_PACKAGES := \ 188 Gallery2 \ 189 ... 190 </pre></li> 191 </ol> 192
