1page.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 30camera framework APIs in 31<a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> 32to your underlying camera driver and hardware. The camera subsystem includes 33implementations for camera pipeline components while the camera HAL provides 34interfaces 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 39file</li> 40<li><a href="{@docRoot}devices/halref/camera3_8h_source.html">camera3.h</a> 41source file</li> 42<li><a href="{@docRoot}devices/halref/camera__common_8h_source.html">camera_common.h</a> 43source file</li> 44<li><a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html">CameraMetadata</a> 45developer 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 100and defines an interface you must implement so apps can correctly operate the 101camera 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 107structure to obtain general information about the camera, such as the camera ID 108and properties common to all cameras (i.e., whether it is a front- or 109back-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 116the HAL interface. For documentation on the camera parameters developers can 117set, refer to <code>frameworks/av/include/camera/CameraParameters.h</code>. 118These 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 123Galaxy 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 128into 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> 133directory to contain your library's source files.</li> 134 135<li>Create an <code>Android.mk</code> file to build the shared library. Ensure 136the Makefile contains the following lines: 137<pre> 138LOCAL_MODULE := camera.<device_name> 139LOCAL_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 143library. 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 147files in the <code>frameworks/native/data/etc</code> directory with your 148device's Makefile. For example, to specify your device has a camera flash and 149can autofocus, add the following lines in your device's 150<code><device>/<company_name>/<device_name>/device.mk</code> 151Makefile: 152<pre class="no-pretty-print"> 153PRODUCT_COPY_FILES := \ ... 154 155PRODUCT_COPY_FILES += \ 156frameworks/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 camera’s media codec, format, and resolution capabilities in 162<code>device/<company_name>/<device_name>/media_profiles.xml</code> 163and <code>device/<company_name>/<device_name>/media_codecs.xml</code> 164XML files. For details, see 165<a href="{@docRoot}devices/media/index.html#expose">Exposing codecs to the 166framework</a>.</li> 167 168<li>Add the following lines in your device's 169<code>device/<company_name>/<device_name>/device.mk</code> Makefile 170to copy the <code>media_profiles.xml</code> and <code>media_codecs.xml</code> 171files to the appropriate location: 172<pre> 173# media config xml file 174PRODUCT_COPY_FILES += \ 175 <device>/<company>/<device>/media_profiles.xml:system/etc/media_profiles.xml 176 177# media codec config xml file 178PRODUCT_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> 185Makefile: 186<pre> 187PRODUCT_PACKAGES := \ 188Gallery2 \ 189... 190</pre></li> 191</ol> 192
