1page.title=Camera HAL v3 overview 2@jd:body 3 4<!-- 5 Copyright 2013 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> 28Android's camera Hardware Abstraction Layer (HAL) connects the higher level 29camera framework APIs in 30<a 31href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 32to your underlying camera driver and hardware. The latest version of Android 33introduces a new, underlying implementation of the camera stack. If you have 34previously developed a camera HAL module and driver for other versions of 35Android, be aware that there are significant changes in the camera pipeline.</p> 36<p>Version 1 of the camera HAL is still supported for future releases of Android 37 because many devices still rely on it. Implementing both HALs is also supported 38 by the Android camera service, which is useful when you want to support a less 39 capable front-facing camera with version 1 of the HAL and a more advanced 40 back-facing camera with version 3 of the HAL. Version 2 was a stepping stone to 41 version 3 and is not supported.</p> 42 43<p> 44There is only one camera HAL module (with its own version number, currently 1, 2, 45or 2.1), which lists multiple independent camera devices that each have 46their own version. Camera module v2 or newer is required to support devices v2 or newer, and such 47camera modules can have a mix of camera device versions. This is what we mean 48when we say Android supports implementing both HALs. 49</p> 50 51<p class="note"><strong>Note:</strong> The new camera HAL is in active 52development and can change at any time. This document describes at a high level 53the design of the camera subsystem and omits many details. See <a 54href="versioning.html">Camera version support</a> for our plans.</p> 55 56<h2 id="overview">Overview</h2> 57 58<p> 59Version 1 of the camera subsystem was designed as a black box with high-level 60controls. Roughly speaking, the old subsystem has three operating modes:</p> 61 62<ul> 63<li>Preview</li> 64<li>Video Record</li> 65<li>Still Capture</li> 66</ul> 67 68<p>Each mode has slightly different and overlapping capabilities. This made it hard 69to implement new types of features, such as burst mode, since it would fall 70between two of these modes.<br/> 71<img src="images/camera_block.png" alt="Camera block diagram"/><br/> 72<strong>Figure 1.</strong> Camera components</p> 73 74<h2 id="v3-enhance">Version 3 enhancements</h2> 75 76<p>The aim of the Android Camera API redesign is to substantially increase the 77ability of applications to control the camera subsystem on Android devices while 78reorganizing the API to make it more efficient and maintainable.</p> 79 80<p>The additional control makes it easier to build high-quality camera applications 81on Android devices that can operate reliably across multiple products while 82still using device-specific algorithms whenever possible to maximize quality and 83performance.</p> 84 85<p>Version 3 of the camera subsystem structures the operation modes into a single 86unified view, which can be used to implement any of the previous modes and 87several others, such as burst mode. This results in better user control for 88focus and exposure and more post-processing, such as noise reduction, contrast 89and sharpening. Further, this simplified view makes it easier for application 90developers to use the camera's various functions.<br/> 91The API models the camera subsystem as a pipeline that converts incoming 92requests for frame captures into frames, on a 1:1 basis. The requests 93encapsulate all configuration information about the capture and processing of a 94frame. This includes: resolution and pixel format; manual sensor, lens and flash 95control; 3A operating modes; RAW->YUV processing control; statistics generation; 96and so on.</p> 97 98<p>In simple terms, the application framework requests a frame from the camera 99subsystem, and the camera subsystem returns results to an output stream. In 100addition, metadata that contains information such as color spaces and lens 101shading is generated for each set of results. The following sections and 102diagrams give you more detail about each component.<br/> 103You can think of camera version 3 as a pipeline to camera version 1's one-way 104stream. It converts each capture request into one image captured by the sensor, 105which is processed into: </p> 106 107<ul> 108<li>A Result object with metadata about the capture.</li> 109<li>One to N buffers of image data, each into its own destination Surface.</li> 110</ul> 111 112<p>The set of possible output Surfaces is preconfigured:</p> 113 114<ul> 115<li>Each Surface is a destination for a stream of image buffers of a fixed 116resolution.</li> 117<li>Only a small number of Surfaces can be configured as outputs at once (~3).</li> 118</ul> 119 120<p>A request contains all desired capture settings and the list of output Surfaces 121to push image buffers into for this request (out of the total configured set). A 122request can be one-shot ( with capture() ), or it may be repeated indefinitely 123(with setRepeatingRequest() ). Captures have priority over repeating 124requests.</p> 125<img src="images/camera_simple_model.png" alt="Camera data model"/> 126<p><strong>Figure 2.</strong> Camera core operation model</p> 127 128<h2 id="supported-version">Supported version</h2> 129 130<p>Camera devices that support this version of the HAL must return 131CAMERA_DEVICE_API_VERSION_3_1 in camera_device_t.common.version and in 132camera_info_t.device_version (from camera_module_t.get_camera_info).<br/> 133Camera modules that may contain version 3.1 devices must implement at least 134version 2.0 of the camera module interface (as defined by 135camera_module_t.common.module_api_version).<br/> 136See camera_common.h for more versioning details.</p> 137 138<h2 id="version-history">Version history</h2> 139 140<h4><strong>1.0</strong></h4> 141 142<p>Initial Android camera HAL (Android 4.0) [camera.h]:</p> 143 144<ul> 145<li>Converted from C++ CameraHardwareInterface abstraction layer.</li> 146<li>Supports android.hardware.Camera API.</li> 147</ul> 148 149<h4><strong>2.0</strong></h4> 150 151<p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p> 152 153<ul> 154<li>Sufficient for implementing existing android.hardware.Camera API.</li> 155<li>Allows for ZSL queue in camera service layer</li> 156<li>Not tested for any new features such manual capture control, Bayer RAW 157capture, reprocessing of RAW data.</li> 158</ul> 159 160<h4><strong>3.0</strong></h4> 161 162<p>First revision of expanded-capability HAL:</p> 163 164<ul> 165<li>Major version change since the ABI is completely different. No change to the 166required hardware capabilities or operational model from 2.0.</li> 167<li>Reworked input request and stream queue interfaces: Framework calls into HAL 168with next request and stream buffers already dequeued. Sync framework support 169is included, necessary for efficient implementations.</li> 170<li>Moved triggers into requests, most notifications into results.</li> 171<li>Consolidated all callbacks into framework into one structure, and all setup 172methods into a single initialize() call.</li> 173<li>Made stream configuration into a single call to simplify stream management. 174Bidirectional streams replace STREAM_FROM_STREAM construct.</li> 175<li>Limited mode semantics for older/limited hardware devices.</li> 176</ul> 177 178<h4><strong>3.1</strong></h4> 179 180<p>Minor revision of expanded-capability HAL:</p> 181 182<ul> 183<li>configure_streams passes consumer usage flags to the HAL.</li> 184<li>flush call to drop all in-flight requests/buffers as fast as possible.</li> 185</ul> 186