1 <html devsite> 2 <head> 3 <title>Camera Version Support</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 <p>This page details version differences in Camera HALs, APIs, and associated 27 Android Compatibility Test Suite (CTS) tests. It also covers several 28 architectural changes made to harden and secure the camera framework in Android 29 7.0 and the updates vendors must make to support these changes in their camera 30 implementations.</p> 31 32 <h2 id=glossary>Terminology</h2> 33 34 <p>The following terms are used on this page:</p> 35 36 <dl> 37 38 <dt>Camera API1</dt> 39 <dd>The app-level camera framework on Android 4.4 and earlier devices, exposed 40 through the <code>android.hardware.Camera</code> class.</dd> 41 42 <dt>Camera API2</dt> 43 <dd>The app-level camera framework on Android 5.0 and later devices, exposed 44 through the<code> android.hardware.camera2</code> package.</dd> 45 46 <dt>Camera HAL</dt> 47 <dd>The camera module layer implemented by SoC vendors. The app-level public 48 frameworks are built on top of the camera HAL.</dd> 49 50 <dt>Camera HAL3.1</dt> 51 <dd>Version of the camera device HAL released with Android 4.4.</dd> 52 53 <dt>Camera HAL3.2</dt> 54 <dd>Version of the camera device HAL released with Android 5.0.</dd> 55 56 <dt>Camera API1 CTS</dt> 57 <dd>Set of camera Compatibility Test Suite (CTS) tests that run on top of Camera 58 API1.</dd> 59 60 <dt>Camera API2 CTS</dt> 61 <dd>Additional set of camera CTS tests that run on top of Camera API2.</dd> 62 63 </dl> 64 65 66 <h2 id=camera_apis>Camera APIs</h2> 67 <p>Android includes the following camera APIs.</p> 68 69 <h3 id=camera_api1>Camera API1</h3> 70 71 <p>Android 5.0 deprecated Camera API1, which continues to be phased out as new 72 platform development focuses on Camera API2. However, the phase-out period will 73 be lengthy, and Android releases will continue to support Camera API1 apps for 74 some time. Specifically, support continues for:</p> 75 76 <ul> 77 <li><em>Camera API1 interfaces for apps</em>. Camera apps built on top of Camera 78 API1 should work as they do on devices running earlier Android release versions. 79 </li> 80 <li><em>Camera HAL versions</em>. Includes support for Camera HAL1.0.</li> 81 </ul> 82 83 <h3 id=camera_api2>Camera API2</h3> 84 85 <p>The Camera API2 framework exposes lower-level camera control to the app, 86 including efficient zero-copy burst/streaming flows and per-frame controls of 87 exposure, gain, white balance gains, color conversion, denoising, sharpening, 88 and more. For details, watch the 89 <a href="https://www.youtube.com/watch?v=92fgcUNCHic&feature=youtu.be&t=29m50s">Google 90 I/O video overview</a>.</p> 91 92 <p>Android 5.0 and later includes Camera API2; however, devices running Android 93 5.0 and later may not support all Camera API2 features. The 94 <code>android.info.supportedHardwareLevel</code> property that apps can query 95 through the Camera API2 interfaces reports one of the following support 96 levels:</p> 97 98 <ul> 99 <li><code>LEGACY</code>. These devices expose capabilities to apps through the 100 Camera API2 interfaces that are approximately the same capabilities as those 101 exposed to apps through the Camera API1 interfaces. The legacy frameworks code 102 conceptually translates Camera API2 calls into Camera API1 calls; legacy devices 103 do not support Camera API2 features such as per-frame controls.</li> 104 <li><code>FULL</code>. These devices support all of major capabilities of Camera 105 API2 and must use Camera HAL 3.2 or later and Android 5.0 or later.</li> 106 <li><code>LIMITED</code>. These devices support some Camera API2 capabilities 107 (but not all) and must use Camera HAL 3.2 or later.</li> 108 </ul> 109 110 <p>Individual capabilities are exposed via the 111 <code>android.request.availableCapabilities</code> property in the Camera API2 112 interfaces. <code>FULL</code> devices require the <code>MANUAL_SENSOR</code> and 113 <code>MANUAL_POST_PROCESSING</code> capabilities, among others. The 114 <code>RAW</code> capability is optional even for <code>FULL</code> devices. 115 <code>LIMITED</code> devices can advertise any subset of these capabilities, 116 including none of them. However, the <code>BACKWARD_COMPATIBLE</code> capability 117 must always be defined.</p> 118 119 <p>The supported hardware level of the device, as well as the specific Camera 120 API2 capabilities it supports, are available as the following feature flags to 121 allow Google Play filtering of Camera API2 camera apps.</p> 122 123 <ul> 124 <li><code>android.hardware.camera.hardware_level.full</code> 125 <li><code>android.hardware.camera.capability.raw</code> 126 <li><code>android.hardware.camera.capability.manual_sensor</code> 127 <li><code>android.hardware.camera.capability.manual_post_processing</code> 128 </ul> 129 130 <h2 id=cts_requirements>CTS requirements</h2> 131 132 <p>Devices running Android 5.0 and later must pass the Camera API1 CTS, Camera 133 API2 CTS, and CTS Verifier camera tests.</p> 134 135 <p>Devices that do not feature a Camera HAL3.2 implementation and are not 136 capable of supporting the full Camera API2 interfaces must still pass the Camera 137 API2 CTS tests. However, the device will be running in Camera API2 138 <code>LEGACY</code> mode (in which the Camera API2 calls are conceptually mapped 139 to Camera API1 calls) so any Camera API2 CTS tests related to features or 140 capabilities beyond Camera API1 will be automatically skipped.</p> 141 142 <p>On legacy devices, Camera API2 CTS tests that are not skipped use the 143 existing public Camera API1 interfaces and capabilities with no new 144 requirements. Bugs that are exposed (and which cause a Camera API2 CTS failure) 145 are bugs already present in the devices existing Camera HAL, and thus would 146 be found by existing Camera API1 apps. We do not expect many bugs of this nature 147 (however, any such bugs must be fixed to pass the Camera API2 CTS tests).</p> 148 149 <h2 id=hardening>Camera framework hardening</h2> 150 151 <p>To harden media and camera framework security, Android 7.0 moves camera 152 service out of mediaserver. Vendors may need to make changes in the camera HAL 153 depending on the API and HAL versions in use. The following sections detail 154 architectural changes in AP1 and AP2 for HAL1 and HAL3, as well as general 155 requirements.</p> 156 157 <h3 id=hardening_api1>Architectural changes for API1</h3> 158 <p>API1 video recording may assume camera and video encoder live in the same 159 process. When using API1 on:</p> 160 161 <ul> 162 <li>HAL3, where camera service uses BufferQueue to pass buffers between 163 processes, <strong>no vendor update</strong> is necessary. 164 <p><img src="images/ape_camera_n_api1_hal3.png" alt="Android 7.0 camera and media 165 stack in API1 on HAL3" id="figure1" /></p> 166 <p class="img-caption"><strong>Figure 1. </strong>Android 7.0 camera and media 167 stack in API1 on HAL3.</p> 168 </li> 169 <li>HAL1, which supports passing metadata in video buffers, <strong>vendors must 170 update the HAL to use kMetadataBufferTypeNativeHandleSource</strong>. 171 (<code>kMetadataBufferTypeCameraSource</code> is no longer supported in Android 172 7.0.) 173 <p><img src="images/ape_camera_n_api1_hal1.png" alt="Android 7.0 camera and media 174 stack in API1 on HAL1" id="figure1" /></p> 175 <p class="img-caption"><strong>Figure 2. </strong>Android 7.0 camera and media 176 stack in API1 on HAL1.</p> 177 </li> 178 </ul> 179 180 <h3 id=hardening_api2>Architectural changes for API2</h3> 181 <p>For API2 on HAL1 or HAL3, BufferQueue passes buffers so those paths continue 182 to work. The Android 7.0 architecture for API2 on:</p> 183 184 <ul> 185 <li>HAL1 is not affected by the cameraservice move, and <strong>no vendor 186 update</strong> is necessary.</li> 187 <li>HAL3 <em>is</em> affected, but <strong>no vendor update</strong> is 188 necessary: 189 <p><img src="images/ape_camera_n_api2_hal3.png" alt="Android 7.0 camera and 190 media stack in API2 on HAL2" id="figure1" /></p> 191 <p class="img-caption"><strong>Figure 3. </strong>Android 7.0 camera and media 192 stack in API2 on HAL3.</p> 193 </li> 194 </ul> 195 196 <h3 id=hardening_general>Additional requirements</h3> 197 <p>The architectural changes made for hardening media and camera framework 198 security include the following additional device requirements.</p> 199 200 <ul> 201 <li><strong>General</strong>. Devices require additional bandwidth due to IPC, 202 which may affect time-sensitive camera use cases such as high-speed video 203 recording. Vendors can measure actual impact by running 204 <code>android.hardware.camera2.cts.PerformanceTest</code> and the Google Camera 205 App for 120/240 FPS high speed video recording. Devices also require a small 206 amount of additional RAM to create the new process.</li> 207 <li><strong>Pass metadata in video buffers</strong>(<em>HAL1 only</em>). If HAL1 208 stores metadata instead of real YUV frame data in video buffers, the HAL must 209 use <code>kMetadataBufferTypeNativeHandleSource</code> as the metadata buffer 210 type and pass <code>VideoNativeHandleMetadata</code> in video buffers. 211 (<code>kMetadataBufferTypeCameraSource</code> is no longer supported on Android 212 7.0.) With <code>VideoNativeHandleMetadata</code>, camera and media frameworks 213 are able to pass the video buffers between processes by serializing and 214 deserializing the native handles properly.</li> 215 <li><strong>Buffer handle address does not always store the same buffer</strong> 216 (<em>HAL3 only</em>). For each capture request, HAL3 gets addresses of buffer 217 handles. HAL cannot use the addresses to identify buffers because the addresses 218 may store another buffer handle after HAL returns the buffer. You must update 219 the HAL to use buffer handles to identify the buffers. For example: HAL receives 220 a buffer handle address A, which stores buffer handle A. After HAL returns 221 buffer handle A, buffer handle address A may store buffer handle B next time the 222 HAL receives it.</li> 223 <li><strong>Update SELinux policies for cameraserver</strong>. If 224 device-specific SELinux policies give mediaserver permissions to run the camera, 225 you must update the SELinux policies to give cameraserver proper permissions. We 226 do not encourage replicating the mediaserver's SELinux policies for cameraserver 227 (as mediaserver and cameraserver generally require different resources in the 228 system). Cameraserver should have only the permissions needed to perform camera 229 functionalities and any unnecessary camera-related permissions in mediaserver 230 should be removed.</p> 231 232 <h3 id=hardening_validation>Validation</h3> 233 <p>For all devices that include a camera and run Android 7.0, verify the 234 implementation by running Android 7.0 CTS. Although Android 7.0 does not include 235 new CTS tests that verify camera service changes, existing CTS tests will fail 236 if you have not made the updates indicated above.</p> 237 238 <h2 id="version-history">Camera HAL version history</h2> 239 <p>For a list of tests available for evaluating the Android Camera HAL, see the 240 <a href="/compatibility/cts/camera-hal.html">Camera HAL Testing 241 Checklist</a>.</p> 242 243 <h3 id="34">3.4</h3> 244 245 <p>Minor additions to supported metadata and changes to data_space support:</p> 246 247 <ul> 248 <li>Add <code>ANDROID_SENSOR_OPAQUE_RAW_SIZE</code> static metadata as mandatory 249 if <code>RAW_OPAQUE</code> format is supported.</li> 250 <li>Add <code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE</code> static 251 metadata as mandatory if any RAW format is supported.</li> 252 <li>Switch <code>camera3_stream_t data_space</code> field to a more flexible 253 definition, using the version 0 definition of dataspace encoding.</li> 254 <li>General metadata additions which are available to use for HALv3.2 or newer: 255 <ul> 256 <li> 257 <a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html#INFO_SUPPORTED_HARDWARE_LEVEL_3"><code>ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3</code> 258 </a></li> 259 <li><code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST</code></li> 260 <li><code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE</code></li> 261 <li><code>ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL</code></li> 262 <li><code>ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL</code></li> 263 <li><code>ANDROID_SENSOR_OPAQUE_RAW_SIZE</code></li> 264 <li><code>ANDROID_SENSOR_OPTICAL_BLACK_REGIONS</code></li> 265 </ul> 266 <li> 267 </ul> 268 269 <h3 id="33">3.3</h3> 270 271 <p>Minor revision of expanded-capability HAL:</p> 272 273 <ul> 274 <li>OPAQUE and YUV reprocessing API updates.</li> 275 <li>Basic support for depth output buffers.</li> 276 <li>Addition of <code>data_space</code> field to 277 <code>camera3_stream_t</code>.</li> 278 <li>Addition of rotation field to <code>camera3_stream_t</code>.</li> 279 <li>Addition of camera3 stream configuration operation mode to 280 <code>camera3_stream_configuration_t</code>.</li> 281 </ul> 282 283 <h3 id="32">3.2</h3> 284 285 <p>Minor revision of expanded-capability HAL:</p> 286 287 <ul> 288 <li>Deprecates <code>get_metadata_vendor_tag_ops</code>. Use 289 <code>get_vendor_tag_ops</code> in <code>camera_common.h</code> instead.</li> 290 <li>Deprecates <code>register_stream_buffers</code>. All gralloc buffers 291 provided by framework to HAL in <code>process_capture_request</code> may be new 292 at any time.</li> 293 <li>Add partial result support. <code>process_capture_result</code> may be 294 called multiple times with a subset of the available results before the full 295 result is available.</li> 296 <li>Add manual template to <code>camera3_request_template</code>. Applications 297 may use this template to control the capture settings directly.</li> 298 <li>Rework the bidirectional and input stream specifications.</li> 299 <li>Change the input buffer return path. The buffer is returned in 300 <code>process_capture_result</code> instead of 301 <code>process_capture_request</code>.</li> 302 </ul> 303 304 <h3 id="31">3.1</h3> 305 306 <p>Minor revision of expanded-capability HAL:</p> 307 308 <ul> 309 <li><code>configure_streams</code> passes consumer usage flags to the HAL.</li> 310 <li>flush call to drop all in-flight requests/buffers as fast as possible.</li> 311 </ul> 312 313 <h3 id="30">3.0</h3> 314 315 <p>First revision of expanded-capability HAL:</p> 316 317 <ul> 318 <li>Major version change since the ABI is completely different. No change to the 319 required hardware capabilities or operational model from 2.0.</li> 320 <li>Reworked input request and stream queue interfaces: Framework calls into HAL 321 with next request and stream buffers already dequeued. Sync framework support 322 is included, necessary for efficient implementations.</li> 323 <li>Moved triggers into requests, most notifications into results.</li> 324 <li>Consolidated all callbacks into framework into one structure, and all setup 325 methods into a single <code>initialize()</code> call.</li> 326 <li>Made stream configuration into a single call to simplify stream management. 327 Bidirectional streams replace STREAM_FROM_STREAM construct.</li> 328 <li>Limited mode semantics for older/limited hardware devices.</li> 329 </ul> 330 331 <h3 id="20">2.0</h3> 332 333 <p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p> 334 335 <ul> 336 <li>Sufficient for implementing existing <code>android.hardware.Camera</code> 337 API.</li> 338 <li>Allows for ZSL queue in camera service layer.</li> 339 <li>Not tested for any new features such as manual capture control, Bayer RAW 340 capture, reprocessing of RAW data, etc.</li> 341 </ul> 342 343 <h3 id="10">1.0</strong></h3> 344 345 <p>Initial Android camera HAL (Android 4.0) [camera.h]:</p> 346 347 <ul> 348 <li>Converted from C++ CameraHardwareInterface abstraction layer.</li> 349 <li>Supports <code>android.hardware.Camera</code> API.</li> 350 </ul> 351 352 <h2 id=module_version>Camera module version history</h2> 353 354 <p>This section contains module versioning information for the Camera hardware 355 module, based on <code>camera_module_t.common.module_api_version</code>. The two 356 most significant hex digits represent the major version, and the two least 357 significant represent the minor version.</p> 358 359 <h3 id="24">2_4</h3> 360 361 <p>This camera module version adds the following API changes:</p> 362 363 <ol> 364 <li><em>Torch mode support</em>. The framework can turn on torch mode for any 365 camera device that has a flash unit, without opening a camera device. The 366 camera device has a higher priority accessing the flash unit than the camera 367 module; opening a camera device will turn off the torch if it had been enabled 368 through the module interface. When there are any resource conflicts, such as 369 <code>open()</code> is called to open a camera device, the camera HAL module 370 must notify the framework through the torch mode status callback that the torch 371 mode has been turned off.</li> 372 373 <li><em>External camera (e.g. USB hot-plug camera) support</em>. The API 374 updates specify the camera static info is available only when camera is 375 connected and ready to use for external hot-plug cameras. Calls to get static 376 info will be invalid calls when camera status is not 377 <code>CAMERA_DEVICE_STATUS_PRESENT</code>. The framework counts solely on 378 device status change callbacks to manage the available external camera list. 379 </li> 380 381 <li><em>Camera arbitration hints</em>. Adds support for explicitly indicating 382 the number of camera devices that can be simultaneously opened and used. To 383 specify valid combinations of devices, the <code>resource_cost</code> and 384 <code>conflicting_devices</code> fields should always be set in the 385 <code>camera_info</code> structure returned by the <code>get_camera_info</code> 386 call.</li> 387 388 <li><em>Module initialization method</em>. Called by the camera service 389 after the HAL module is loaded to allow for one-time initialization of the HAL. 390 It is called before any other module methods are invoked.</li> 391 </ol> 392 393 <h3 id="23">2_3</h3> 394 395 <p>This camera module version adds open legacy camera HAL device support. 396 The framework can use it to open the camera device as lower device HAL version 397 HAL device if the same device can support multiple device API versions. 398 The standard hardware module open call (common.methods->open) continues 399 to open the camera device with the latest supported version, which is 400 also the version listed in <code>camera_info_t.device_version</code>.</p> 401 402 <h3 id="22">2_2</h3> 403 404 <p>This camera module version adds vendor tag support from the module, and 405 deprecates the old <code>vendor_tag_query_ops</code> that were previously only 406 accessible with a device open.</p> 407 408 <h3 id="21">2_1</h3> 409 410 <p>This camera module version adds support for asynchronous callbacks to the 411 framework from the camera HAL module, which is used to notify the framework 412 about changes to the camera module state. Modules that provide a valid 413 <code>set_callbacks()</code> method must report at least this version number.</p> 414 415 <h3 id="20">2_0</h3> 416 417 <p>Camera modules that report this version number implement the second version 418 of the camera module HAL interface. Camera devices openable through this 419 module may support either version 1.0 or version 2.0 of the camera device 420 HAL interface. The <code>device_version</code> field of camera_info is always 421 valid; the <code>static_camera_characteristics</code> field of 422 <code>camera_info</code> is valid if the <code>device_version</code> field is 423 2.0 or higher.</p> 424 425 <h3 id="10">1_0</h3> 426 427 <p>Camera modules that report these version numbers implement the initial 428 camera module HAL interface. All camera devices openable through this 429 module support only version 1 of the camera device HAL. The 430 <code>device_version</code> and <code>static_camera_characteristics</code> 431 fields of <code>camera_info</code> are not valid. Only the 432 <code>android.hardware.Camera</code> API can be supported by this module and its 433 devices.</p> 434 435 </body> 436 </html> 437
