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