From 594d0ed1190671afa13e0b065bb7ba437844b920 Mon Sep 17 00:00:00 2001 From: Clay Murphy Date: Tue, 21 Oct 2014 11:04:30 -0700 Subject: Docs: Adding camera versioning information. Bug: 17660062 Change-Id: I2127e8bb666f13c5dfa8c8da41666aa6d18bd2ec --- src/devices/camera/camera3.jd | 13 ++-- src/devices/camera/versioning.jd | 132 +++++++++++++++++++++++++++++++++++++++ src/devices/devices_toc.cs | 1 + 3 files changed, 140 insertions(+), 6 deletions(-) create mode 100644 src/devices/camera/versioning.jd (limited to 'src/devices') diff --git a/src/devices/camera/camera3.jd b/src/devices/camera/camera3.jd index 6fe97701..4d4d3a1c 100644 --- a/src/devices/camera/camera3.jd +++ b/src/devices/camera/camera3.jd @@ -39,18 +39,19 @@ Android, be aware that there are significant changes in the camera pipeline.

capable front-facing camera with version 1 of the HAL and a more advanced back-facing camera with version 3 of the HAL. Version 2 was a stepping stone to version 3 and is not supported.

+

There is only one camera HAL module (with its own version number, currently 1, 2, or 2.1), which lists multiple independent camera devices that each have their own version. Camera module v2 or newer is required to support devices v2 or newer, and such camera modules can have a mix of camera device versions. This is what we mean -when we say we Android supports implementing both HALs. +when we say Android supports implementing both HALs.

-

Note: The new camera HAL is in active development and can change at any - time. This document describes at a high level the design of the camera subsystem - and omits many details. Stay tuned for more updates to the PDK repository and - look out for updates to the Camera HAL and reference implementation for more - information.

+ +

Note: The new camera HAL is in active +development and can change at any time. This document describes at a high level +the design of the camera subsystem and omits many details. See Camera version support for our plans.

Overview

diff --git a/src/devices/camera/versioning.jd b/src/devices/camera/versioning.jd new file mode 100644 index 00000000..9f97ce34 --- /dev/null +++ b/src/devices/camera/versioning.jd @@ -0,0 +1,132 @@ +page.title=Camera version support +@jd:body + + +
+
+

In this document

+
    +
+
+
+ +

The Android 5.0 (Lollipop) platform release adds a new app-level camera framework. This +document outlines some logistical details that OEMs and SoC vendors need to +know.

+ +

Terms

+ +

The following terms are used in this document:

+ + + +

Camera API2 overview

+ +

The new camera frameworks expose lower-level camera control to the app, +including efficient zero-copy burst/streaming flows and per-frame controls of +exposure, gain, white balance gains, color conversion, denoising, sharpening, +and more. See this brief +video overview from the Google I/O 2014 conference for additional details. +

+ +

Camera API1 availability and deprecation in Android 5.0

+ +

The Camera API1 interfaces are still available for apps to use on Android +5.0 and later devices, and camera apps built on top of Camera API1 should work +as before. Camera API1 is being marked as deprecated in Lollipop, indicating that it +will be phased out over time and new platform development will focus on Camera +API2. However, we expect this phase-out period to be lengthy, and Camera API1 +apps will continue to be supported in Android for some time to come.

+ +

All earlier camera HAL versions, including Camera HAL1.0, will also continue to +be supported.

+ +

Camera API2 capabilities and support levels

+ +

Android 5.0 and later devices feature Camera API2, however they may not fully support all of +the new features of Camera API2. The +android.info.supportedHardwareLevel property that apps can query +through the Camera API2 interfaces report one of three support levels: +LEGACY, FULL, and LIMITED.

+ +

Legacy devices expose a level of capabilities through the Camera API2 interfaces that +are approximately the same as is exposed to apps through the Camera API1 +interfaces; the legacy frameworks code conceptually translates Camera API2 +calls into Camera API1 calls under the hood. Legacy devices do not support +the new Camera API2 features including per-frame controls.

+ +

Full devices support all of the major capabilities of Camera API2. Full devices by +necessity must have a Camera HAL version of 3.2 (shipping with Android 5.0) or later.

+ +

Limited devices are in between: They support some of the new Camera API2 capabilities, +but not all of them, and must also comprise a Camera HAL version of 3.2 or later.

+ +

Individual capabilities are exposed via the +android.request.availableCapabilities property in the Camera API2 +interfaces. Full devices require both the MANUAL_SENSOR and +MANUAL_POST_PROCESSING capabilities, among others. There is also a +RAW capability that is optional even for full devices. Limited +devices can advertise any subset of these capabilities, including none of them. However, +the BACKWARD_COMPATIBLE capability must always be defined.

+ +

The supported hardware level of the device, as well as the specific Camera API2 +capabilities it supports, are available as the following feature flags to allow +Play Store filtering of Camera API2 camera apps; a device must define the +feature flag if any of its attached camera devices supports the feature.

+ + + +

CTS requirements

+ +

Android 5.0 and later devices must pass both Camera API1 CTS and Camera API2 +CTS. And as always, devices are required to pass the CTS Verifier camera +tests.

+ +

To add some context: For devices that don’t feature a Camera HAL3.2 +implementation and are not capable of supporting the full Camera API2 +interfaces, the Camera API2 CTS tests must still be passed. However, in this +case the device will be running in Camera API2 legacy mode (in which +the Camera API2 calls are conceptually just mapped to Camera +API1 calls); and any Camera API2 CTS tests that relate to features or +capabilities beyond Camera API1 have logic that will skip them in the case of +old (legacy) devices.

+ +

On a legacy device, the Camera API2 CTS tests that are not skipped are purely +using the existing public Camera API1 interfaces and capabilities (with no new +requirements), and any bugs that are exposed (which will in turn cause a Camera +API2 CTS failure) are bugs that were already present in the device’s existing +Camera HAL and would also be a bug that could be easily hit by existing Camera +API1 apps. The expectation is that there should be very few bugs of this +nature. Nevertheless, any such bugs will need to be fixed.

diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs index 5f9a0190..b18dc756 100644 --- a/src/devices/devices_toc.cs +++ b/src/devices/devices_toc.cs @@ -67,6 +67,7 @@
  • Output and Cropping
  • Errors and Streams
  • Request Creation
    • +
  • Version Support
    • -- cgit v1.2.3