1 page.title=Camera version support 2 @jd:body 3 4 <!-- 5 Copyright 2014 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>The Android 5.0 (Lollipop) platform release adds a new app-level camera framework. This 28 document outlines some logistical details that OEMs and SoC vendors need to 29 know.</p> 30 31 <h2 id=glossary>Terms</h2> 32 33 <p>The following terms are used in this document:</p> 34 35 <ul> 36 <li><em>Camera API1</em>: The app-level camera framework on KitKat and earlier devices, exposed 37 through the <code>android.hardware.Camera</code> class. 38 <li><em>Camera API2</em>: The app-level camera framework on 5.0 and later 39 devices, exposed through the<code> android.hardware.camera2</code> package. 40 <li><em>Camera HAL</em>: The camera module layer that SoC vendors implement. The app-level public 41 frameworks are built on top of the camera HAL. 42 <li><em>Camera HAL3.2</em>: The version of the camera device HAL that is 43 being released with Lollipop. KitKat launched with an earlier version (Camera HAL3.1). 44 <li><em>Camera API1 CTS</em>: The set of camera Compatibility Test Suite (CTS) tests that run on top of 45 Camera API1. 46 <li><em>Camera API2 CTS</em>: An additional set of camera CTS tests that run on top of Camera API2. 47 </ul> 48 49 <h2 id=camera_api2_overview>Camera API2 overview</h2> 50 51 <p>The new camera frameworks expose lower-level camera control to the app, 52 including efficient zero-copy burst/streaming flows and per-frame controls of 53 exposure, gain, white balance gains, color conversion, denoising, sharpening, 54 and more. See this <a 55 href="https://www.youtube.com/watch?v=92fgcUNCHic&feature=youtu.be&t=29m50s">brief 56 video overview from the Google I/O 2014 conference</a> for additional details. 57 </p> 58 59 <h2 id=camera_api1_availability_and_deprecation_in_l>Camera API1 availability and deprecation in Android 5.0</h2> 60 61 <p>The Camera API1 interfaces are still available for apps to use on Android 62 5.0 and later devices, and camera apps built on top of Camera API1 should work 63 as before. Camera API1 is being marked as deprecated in Lollipop, indicating that it 64 will be phased out over time and new platform development will focus on Camera 65 API2. However, we expect this phase-out period to be lengthy, and Camera API1 66 apps will continue to be supported in Android for some time to come.</p> 67 68 <p>All earlier camera HAL versions, including Camera HAL1.0, will also continue to 69 be supported.</p> 70 71 <h2 id=camera_api2_capabilities_and_support_levels>Camera API2 capabilities and support levels</h2> 72 73 <p>Android 5.0 and later devices feature Camera API2, however they may not fully support all of 74 the new features of Camera API2. The 75 <code>android.info.supportedHardwareLevel</code> property that apps can query 76 through the Camera API2 interfaces report one of three support levels: 77 <code>LEGACY</code>, <code>FULL</code>, and <code>LIMITED</code>.</p> 78 79 <p><em>Legacy</em> devices expose a level of capabilities through the Camera API2 interfaces that 80 are approximately the same as is exposed to apps through the Camera API1 81 interfaces; the legacy frameworks code conceptually translates Camera API2 82 calls into Camera API1 calls under the hood. Legacy devices do not support 83 the new Camera API2 features including per-frame controls.</p> 84 85 <p><em>Full</em> devices support all of the major capabilities of Camera API2. Full devices by 86 necessity must have a Camera HAL version of 3.2 (shipping with Android 5.0) or later.</p> 87 88 <p><em>Limited</em> devices are in between: They support some of the new Camera API2 capabilities, 89 but not all of them, and must also comprise a Camera HAL version of 3.2 or later.</p> 90 91 <p>Individual capabilities are exposed via the<code> 92 android.request.availableCapabilities</code> property in the Camera API2 93 interfaces. Full devices require both the <code>MANUAL_SENSOR</code> and 94 <code>MANUAL_POST_PROCESSING</code> capabilities, among others. There is also a 95 <code>RAW</code> capability that is optional even for full devices. Limited 96 devices can advertise any subset of these capabilities, including none of them. However, 97 the <code>BACKWARD_COMPATIBLE</code> capability must always be defined.</p> 98 99 <p>The supported hardware level of the device, as well as the specific Camera API2 100 capabilities it supports, are available as the following feature flags to allow 101 Play Store filtering of Camera API2 camera apps; a device must define the 102 feature flag if any of its attached camera devices supports the feature.</p> 103 104 <ul> 105 <li><code>android.hardware.camera.hardware_level.full</code> 106 <li><code>android.hardware.camera.capability.raw</code> 107 <li><code>android.hardware.camera.capability.manual_sensor</code> 108 <li><code>android.hardware.camera.capability.manual_post_processing</code> 109 </ul> 110 111 <h2 id=cts_requirements>CTS requirements</h2> 112 113 <p>Android 5.0 and later devices must pass both Camera API1 CTS and Camera API2 114 CTS. And as always, devices are required to pass the CTS Verifier camera 115 tests.</p> 116 117 <p>To add some context: For devices that dont feature a Camera HAL3.2 118 implementation and are not capable of supporting the full Camera API2 119 interfaces, the Camera API2 CTS tests must still be passed. However, in this 120 case the device will be running in Camera API2 <em>legacy</em> mode (in which 121 the Camera API2 calls are conceptually just mapped to Camera 122 API1 calls); and any Camera API2 CTS tests that relate to features or 123 capabilities beyond Camera API1 have logic that will skip them in the case of 124 old (legacy) devices.</p> 125 126 <p>On a legacy device, the Camera API2 CTS tests that are not skipped are purely 127 using the existing public Camera API1 interfaces and capabilities (with no new 128 requirements), and any bugs that are exposed (which will in turn cause a Camera 129 API2 CTS failure) are bugs that were already present in the devices existing 130 Camera HAL and would also be a bug that could be easily hit by existing Camera 131 API1 apps. The expectation is that there should be very few bugs of this 132 nature. Nevertheless, any such bugs will need to be fixed.</p> 133 134 <h2 id="version-history">Version history</h2> 135 136 <h3 id="32">3.2</h3> 137 138 <p>Second revision of expanded-capability HAL:</p> 139 140 <ul> 141 <li>Deprecates get_metadata_vendor_tag_ops. Please use get_vendor_tag_ops in 142 camera_common.h instead.</li> 143 <li>register_stream_buffers deprecated. All gralloc buffers provided by 144 framework to HAL in process_capture_request may be new at any time.</li> 145 <li>Add partial result support. process_capture_result may be called multiple 146 times with a subset of the available result before the full result is available.</li> 147 <li>Add manual template to camera3_request_template. The applications may use 148 this template to control the capture settings directly.</li> 149 <li>Rework the bidirectional and input stream specifications.</li> 150 <li>Change the input buffer return path. The buffer is returned in 151 process_capture_result instead of process_capture_request.</li> 152 </ul> 153 154 <h3 id="31">3.1</h3> 155 156 <p>Minor revision of expanded-capability HAL:</p> 157 158 <ul> 159 <li>configure_streams passes consumer usage flags to the HAL.</li> 160 <li>flush call to drop all in-flight requests/buffers as fast as possible.</li> 161 </ul> 162 163 <h3 id="30">3.0</h3> 164 165 <p>First revision of expanded-capability HAL:</p> 166 167 <ul> 168 <li>Major version change since the ABI is completely different. No change to the 169 required hardware capabilities or operational model from 2.0.</li> 170 <li>Reworked input request and stream queue interfaces: Framework calls into HAL 171 with next request and stream buffers already dequeued. Sync framework support 172 is included, necessary for efficient implementations.</li> 173 <li>Moved triggers into requests, most notifications into results.</li> 174 <li>Consolidated all callbacks into framework into one structure, and all setup 175 methods into a single initialize() call.</li> 176 <li>Made stream configuration into a single call to simplify stream management. 177 Bidirectional streams replace STREAM_FROM_STREAM construct.</li> 178 <li>Limited mode semantics for older/limited hardware devices.</li> 179 </ul> 180 181 <h3 id="20">2.0</h3> 182 183 <p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p> 184 185 <ul> 186 <li>Sufficient for implementing existing android.hardware.Camera API.</li> 187 <li>Allows for ZSL queue in camera service layer</li> 188 <li>Not tested for any new features such manual capture control, Bayer RAW 189 capture, reprocessing of RAW data.</li> 190 </ul> 191 192 <h3 id="10">1.0</strong></h3> 193 194 <p>Initial Android camera HAL (Android 4.0) [camera.h]:</p> 195 196 <ul> 197 <li>Converted from C++ CameraHardwareInterface abstraction layer.</li> 198 <li>Supports android.hardware.Camera API.</li> 199 </ul> 200
