Earth Guardian

You are not LATE!You are not EARLY!

0%

Android Camera API2 介绍

发表于 更新于 分类于

Android Camera 开发相机应用相关 API2 介绍，以及使用示例。

基础

camera 各个版本

  • Camera API1
    Android 4.4 或更低版本设备上的应用级相机框架，通过 android.hardware.Camera 类提供。
  • Camera API2
    Android 5.0 及更高版本设备上的应用级相机框架，通过 android.hardware.camera2 包提供。
  • Camera HAL
    由 SoC 供应商实现的相机模块层。该应用级公共框架基于 Camera HAL 构建而成。
  • Camera HAL3.1
    随 Android 4.4 发布的相机设备 HAL 版本。
  • Camera HAL3.2
    随 Android 5.0 发布的相机设备 HAL 版本。

Camera API1

Android 5.0 已弃用 Camera API1，而且随着新平台开发的重点放在 Camera API2 上，Camera API1 会逐渐被淘汰。但是淘汰期限将会很长，而且在一段时间内新 Android 版本会继续支持 Camera API1 应用。具体来说，将继续为以下内容提供支持：

  • 供应用使用的 Camera API1 接口；在 Camera API1 之上构建的相机应用应该像在运行早期 Android 版本的设备上一样工作
  • Camera HAL 版本，包括对 Camera HAL1.0 的支持

Camera API2

Camera API2 框架为应用提供更接近底层的相机控件，包括高效的零复制连拍/视频流以及曝光、增益、白平衡增益、颜色转换、去噪、锐化等方面的每帧控件。
Android 5.0 及更高版本提供 Camera API2；但是运行 Android 5.0 及更高版本的设备可能并不支持所有 Camera API2 功能。应用可通过 Camera API2 接口查询 android.info.supportedHardwareLevel 属性。该属性会报告以下支持级别之一：

  • INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY 旧版
    这些设备通过 Camera API2 接口为应用提供功能，而且这些功能与通过 Camera API1 接口提供给应用的功能大致相同。旧版框架代码在概念上将 Camera API2 调用转换为 Camera API1 调用；旧版设备不支持 Camera API2 功能，例如每帧控件。
  • INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 有限
    这些设备支持部分（但不是全部）Camera API2 功能，并且必须使用 Camera HAL 3.2 或更高版本。
  • INFO_SUPPORTED_HARDWARE_LEVEL_FULL 全面
    这些设备支持 Camera API2 的所有主要功能，并且必须使用 Camera HAL 3.2 或更高版本以及 Android 5.0 或更高版本。
  • INFO_SUPPORTED_HARDWARE_LEVEL_3 级别 3
    这些设备支持 YUV 重新处理和 RAW 图片捕获，以及其他输出流配置。
  • INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL 外部
    这些设备类似于 LIMITED 设备，但有一些例外情况；例如某些传感器或镜头信息可能未被报告或具有较不稳定的帧速率。此级别用于外部相机（如 USB 网络摄像头）。

各个模式支持的功能级别 LEGACY < LIMITED < FULL < LEVEL_3 ；各项功能通过 Camera API2 接口中的 android.request.availableCapabilities 属性提供。FULL 设备需要具备 MANUAL_SENSOR 和 MANUAL_POST_PROCESSING 等功能。但即使是 FULL 设备，也并非必须实现 RAW 功能。 LIMITED 设备可以提供这些功能的任何子集，甚至可以不提供其中任何功能。但是必须始终定义 BACKWARD_COMPATIBLE 功能。

设备支持的硬件级别及其支持的特定 Camera API2 功能采用以下功能标记的形式指明，APP 在使用时，在 AndroidManifest.xml 中通过 uses-feature 来声明使用的功能： 

1
2
3
4
android.hardware.camera.hardware_level.full
android.hardware.camera.capability.raw
android.hardware.camera.capability.manual_sensor
android.hardware.camera.capability.manual_post_processing

HAL 新旧版本架构图

从 Android 8.0 开始，相机 HAL 实现了 HIDL 接口；而旧版本架构和新版本主要体现在 HIDL 上。

基于 HIDL 的架构图
0109-android-camera-3-api-ape-fwk-camera2-hidl.png

旧版架构图
0109-android-camera-3-api-ape-fwk-camera-old.png

Camera 各版本介绍详细参考：Android Camera 架构 ， Android Camera 版本支持

Camera2 类图结构

0109-android-camera-3-api-caemra2-class.png

各个类功能简介

  • CameraManager
    相机设备管理员，用于检测相机设备，开启相机设备，获取相机设备支持的特性等等。
  • CameraDevice
    表示物理或逻辑摄像头，类似老版本中的 Camera 类，是对传感器相关功能的封装。
  • CameraCaptureSession
    Camera 应用程序和 CameraDevice 硬件之间建立的一个会话类，用于从相机捕获图像或重新处理先前在同一会话中从相机捕获的图像，捕获到的图像输出到目标 Surface 中。为应用程序主要提供预览 setRepeatingRequest 和拍照 capture 功能。
  • CameraMetadata
    是一个数据结构，包含了 CameraDevice 控制命令和相关信息。CameraMetadata 用于查询 CameraDevice 属性、捕获结果、设置请求参数的基本键/值映射。CameraMetadata 的所有实例都是不可变的。
  • CaptureRequest
    表示从 CameraDevice 获取捕获数据的请求，包含对 CameraDevice 的参数设置，算法控制，输出缓冲区等等。
  • CaptureResult
    表示从 CameraDevice 获取到数据的结果子集；包含捕获硬件（传感器，镜头，闪存），控制算法和输出缓冲区的最终配置等的子集；CaptureResult 对象实例是不可变的。
  • CameraCharacteristics
    用来描述 CameraDevice 设备的属性，这些属性是不可修改的，设备出厂时提供的；可以通过 CameraManager.getCameraCharacteristics(String cameraID) 来查询当前设备支持哪些属性。

基本结构

0109-android-camera-3-api-pipeline.png

在 Camera2 的架构中，APP 和 CameraDevice 之间通过 Pipeline 管道来连接。

  • CameraCaptureSession 充当管道的功能
  • APP 向 CameraDevice 发送 CaptureRequest
  • CameraDevices 收到请求后返回对应数据到对应的 Surface ：通常 TextureView 用来预览，ImageReader 用来拍照保存

简化使用流程图

0109-android-camera-3-api-camera2-simple-usecase.png

CameraManager

CameraManager 相机设备管理员，用于检测相机设备，开启相机设备，获取相机设备支持的特性等等。

API 方法

CameraManager 提供的 API 非常简单，围绕着类的主要功能： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
public final class CameraManager {
    private static final int USE_CALLING_UID = -1;

    @SuppressWarnings("unused")
    private static final int API_VERSION_1 = 1;
    private static final int API_VERSION_2 = 2;

    private static final int CAMERA_TYPE_BACKWARD_COMPATIBLE = 0;
    private static final int CAMERA_TYPE_ALL = 1;

    private ArrayList<String> mDeviceIdList;

    private final Context mContext;
    private final Object mLock = new Object();

    public CameraManager(Context context) {
        synchronized(mLock) {
            mContext = context;
        }
    }
    
    // 获取指定设备的属性
    public CameraCharacteristics getCameraCharacteristics (
        String cameraId){...}
    // 获取当前系统中的设备 ID 数组
    public String[] getCameraIdList() throws CameraAccessException {
        return CameraManagerGlobal.get().getCameraIdList();
    }
    // 开启指定 ID 的相机设备
    public void openCamera(@NonNull String cameraId,
        @NonNull final CameraDevice.StateCallback callback, 
        @Nullable Handler handler) throws CameraAccessException {
        openCameraForUid(cameraId, callback, handler, USE_CALLING_UID);
    }
    // 使用并发器开启相机设备
    public void openCamera (String cameraId,  Executor executor, 
        CameraDevice.StateCallback callback){...}
    // 注册 AvailabilityCallback
    public void registerAvailabilityCallback (Executor executor, 
        CameraManager.AvailabilityCallback callback)
    public void registerAvailabilityCallback (
        CameraManager.AvailabilityCallback callback, Handler handler){...}
    // 取消 AvailabilityCallback
    public void unregisterAvailabilityCallback (
        CameraManager.AvailabilityCallback callback){...}
    // 注册 TorchCallback
    public void registerTorchCallback (
        CameraManager.TorchCallback callback, Handler handler){...}
    public void registerTorchCallback (Executor executor, 
        CameraManager.TorchCallback callback){...}
    // 取消 TorchCallback
    public void unregisterTorchCallback (
        CameraManager.TorchCallback callback){...}
    // 指定 ID 相机设备，设置手电筒模式
    public void setTorchMode(@NonNull String cameraId, boolean enabled)
            throws CameraAccessException {
        if (CameraManagerGlobal.sCameraServiceDisabled) {
            throw new IllegalArgumentException("...");
        }
        CameraManagerGlobal.get().setTorchMode(cameraId, enabled);
    }
}

AvailabilityCallback 回调

CameraManager.AvailabilityCallback 表示相机设备开启后状态，变为有效或无效状态。 

1
2
3
4
public static abstract class AvailabilityCallback {
    public void onCameraAvailable(@NonNull String cameraId) {}
    public void onCameraUnavailable(@NonNull String cameraId) {}
}

TorchCallback 回调

CameraManager.TorchCallback 闪光灯用作手电筒的回调接口，表示闪光灯处于开启手电筒、关闭、或者无效状态。 

1
2
3
4
5
public static abstract class TorchCallback {
    public void onTorchModeUnavailable(@NonNull String cameraId) {}
    public void onTorchModeChanged(@NonNull String cameraId, 
        boolean enabled) {}
}

CameraDevice

CameraDevice 表示物理或逻辑摄像头，类似老版本中的 Camera 类，是对传感器相关功能的封装。使用前需要注意：

  • 权限
    CameraDevice 使用前需要申请权限 <uses-permission android:name="android.permission.CAMERA" /> 。
  • 支持功能的级别
    通过 CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL 查看当前手机平台支持的功能级别。如果支持 LEGACY 级别，则摄像机设备以向后兼容模式运行，并且支持最小的 Camera2 API ；如果支持 LIMITED 级别，则 Camera2 API 是和旧版 Camera API 大致相同的功能集，但界面更清晰效率更高；如果支持 EXTERNAL 级别，则该设备是可移动摄像头，提供与 LIMITED 级别相似但略少的功能；如果支持 FULL, LEVEL3 级别，API 将提供显着改进的功能。如果开发的 Camera 应用程序需要一个完整级别的设备才能正常运行，需要请在清单中声明 android.hardware.camera.level.full 功能。

常量

CameraDevice 中控制模板常量：

  • TEMPLATE_MANUAL
    手动控制模板，禁用所有的自动控制 3A 算法。
  • TEMPLATE_PREVIEW
    创建适合相机预览的窗口，高帧率优于高质量的后期处理。
  • TEMPLATE_RECORD
    创建适合录像的请求，使用稳定的帧率。
  • TEMPLATE_STILL_CAPTURE
    创建适合拍照的请求，优先考虑帧速率的图像质量。
  • TEMPLATE_VIDEO_SNAPSHOT
    创建录像时快照的请求，在不中断录像的前提下最大化图像质量。
  • TEMPLATE_ZERO_SHUTTER_LAG
    创建 ZSL 零延时拍照请求，在不影响帧率的前提下最大化图像质量，并开启 3A 算法。

API 方法

CameraDevice 中 API 简介： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
public abstract class CameraDevice implements AutoCloseable {
    // 关闭设备
    public abstract void close ();
    // 使用指定模板创建请求
    public abstract CaptureRequest.Builder createCaptureRequest(
        @RequestTemplate int templateType) throws CameraAccessException;
    // 使用指定模板创建请求，同时指定物理摄像头 ID 集
    public CaptureRequest.Builder createCaptureRequest (int templateType, 
        Set<String> physicalCameraIdSet){...}
    // 根据指定会话配置文件，创建会话
    public void createCaptureSession (SessionConfiguration config){...}
    // 给定输出列表，创建会话；API 文档中有非常详细的匹配图
    public abstract void createCaptureSession (List<Surface> outputs, 
        CameraCaptureSession.StateCallback callback,  Handler handler);
    // 根据给定输出配置文件列表，创建会话
    public abstract void createCaptureSessionByOutputConfigurations(
        List<OutputConfiguration> outputConfigurations, 
        CameraCaptureSession.StateCallback callback, Handler handler)；
    // 给定输出列表，创建高速会话
    public abstract void createConstrainedHighSpeedCaptureSession(
        List<Surface> outputs, 
        CameraCaptureSession.StateCallback callback, Handler handler);
    // 创建重新处理请求
    public abstract CaptureRequest.Builder createReprocessCaptureRequest(
        TotalCaptureResult inputResult);
    // 创建重复处理会话；API 文档中有详细匹配图
    public abstract void createReprocessableCaptureSession (
        InputConfiguration inputConfig, List<Surface> outputs, 
        CameraCaptureSession.StateCallback callback, Handler handler);
    // 根据配置文件创建重复处理会话
    public abstract void createReprocessableCaptureSessionByConfigurations(
        InputConfiguration inputConfig, List<OutputConfiguration> outputs, 
        CameraCaptureSession.StateCallback callback, Handler handler);
    // 获取设备的 ID
    public abstract String getId();
}

StateCallback 回调

CameraDevice.StateCallback 状态回调接口，在 CameraManager.open 打开摄像头时，必须提供该回调接口；表示当前 CameraDevice 的状态。
CameraDevice.StateCallback 中设备错误常量，在 onError() 方法中返回：

  • ERROR_CAMERA_DEVICE ：开启设备时遇到致命错误
  • ERROR_CAMERA_DISABLED ：由于设备策略，无法开启摄像头
  • ERROR_CAMERA_IN_USE ：当前开启设备正在被使用
  • ERROR_CAMERA_SERVICE ：CameraService 致命错误
  • ERROR_MAX_CAMERAS_IN_USE ：开启的设备已经达到最大数量 
1
2
3
4
5
6
7
8
9
10
11
public static abstract class StateCallback {
    // 当 CameraDevice.close() 调用时会触发；如果设备已经关闭，
    // 后续再次调用 CameraDevice 相关方法会抛出异常 IllegalStateException
    public void onClosed (CameraDevice camera){...}
    // 表示设备不能再被使用；再次访问会抛出 CameraAccessException
    public abstract void onDisconnected (CameraDevice camera){...}
    // 开启设备失败；再次访问抛出 CameraAccessException，并给出 error
    public abstract void onError (CameraDevice camera, int error);
    // 设备被正常打开
    public abstract void onOpened (CameraDevice camera);
}

CameraCaptureSession

抽象类；Camera 应用程序和 CameraDevice 硬件之间建立的一个会话类，用于从相机捕获图像或重新处理先前在同一会话中从相机捕获的图像，捕获到的图像输出到目标 Surface 中。为应用程序主要提供预览 setRepeatingRequest 和拍照 capture 功能。

CameraCaptureSession 创建非常耗时，可能需要几百毫秒，因为它需要配置摄像机设备的内部管道并分配内存缓冲区以将图像发送到所需目标，因此需要异步去完成。在 CameraDevice 中有两种方式创建：

  • createCaptureSession
  • createReprocessableCaptureSession ：可以重新处理先前在同一会话中从摄像机捕获的图像

API 方法

CameraCaptureSession 中 API 简介： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
public abstract class CameraCaptureSession implements AutoCloseable {
    // 取消所有的数据捕获
    abstract void abortCaptures();
    // 拍照：向 CameraDevice 发出拍照请求；返回序列号  
    abstract int capture(CaptureRequest request, 
        CameraCaptureSession.CaptureCallback listener, Handler handler);
    // 提交一个顺序捕获的列表
    abstract int captureBurst(List<CaptureRequest> requests, 
        CameraCaptureSession.CaptureCallback listener, Handler handler);
    // 提交顺序捕获列表，给定并发器
    int captureBurstRequests(List<CaptureRequest> requests, 
        Executor executor, CameraCaptureSession.CaptureCallback listener)
        {...}
    // 给定并发器，提交一个数据捕获请求
    int captureSingleRequest(CaptureRequest request, Executor executor, 
        CameraCaptureSession.CaptureCallback listener){...}
    // 关闭 CameraCaptureSession
    abstract void close();
    // 最终确定的输出配置
    abstract void finalizeOutputConfigurations(
        List<OutputConfiguration> outputConfigs);
    // 获取 CameraDevice
    abstract CameraDevice getDevice();
    // 获取输入 Surface
    abstract Surface getInputSurface();
    // 是否可以从新处理先前获取的图像
    abstract boolean isReprocessable();
    // 为输出 Surface 分配缓冲区
    abstract void prepare(Surface surface);
    // 预览：设置预览请求列表
    abstract int setRepeatingBurst(List<CaptureRequest> requests,
        CameraCaptureSession.CaptureCallback listener, Handler handler);
    // 预览：使用指定并发器设置预览请求列表
    int setRepeatingBurstRequests(List<CaptureRequest> requests, 
        Executor executor, CameraCaptureSession.CaptureCallback listener)
        {...}
    // 预览：设置一个预览请求
    abstract int setRepeatingRequest(CaptureRequest request, 
        CameraCaptureSession.CaptureCallback listener, Handler handler);
    // 预览：使用指定并发器设置预览请求
    int setSingleRepeatingRequest(CaptureRequest request, 
        Executor executor, CameraCaptureSession.CaptureCallback listener)
        {...}
    // 停止预览
    abstract void stopRepeating();
    // 更新输出配置
    void updateOutputConfiguration(OutputConfiguration config);
}

StateCallback 回调

CameraCaptureSession.StateCallback 状态回调接口，表示会话创建成功后或者会话有内容变化时会触发回调。CameraCaptureSession 创建成功后处于活动状态，直到摄像机设备创建新会话或关闭摄像机设备。创建成功后会触发 onConfigured 回调；如果无法完成配置，则会触发 onConfigureFailed，并且会话不会变为活动状态。新会话创建成功，则会关闭先前的会话，并会触发其 onClosed 回调。如果在会话关闭后调用，则所有会话方法都将抛出 IllegalStateException。
回调接口有如下几个方法，其中 onConfigured, onConfigureFailed 是抽象类，需要在子类中实现： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public static abstract class StateCallback {
    // 开始处理捕获请求时触发  
    void onActive(CameraCaptureSession session);
    // 当 CameraDevice 输入捕获队列为空并准备接受下一个请求时触发
    void onCaptureQueueEmpty(CameraCaptureSession session);
    // 当 CameraCaptureSession 关闭时触发；
    //如果还有方法被调用将会抛出 IllegalStateException
    void onClosed(CameraCaptureSession session);
    // 抽象方法，当请求失败时触发；之后 CameraCaptureSession 会被认为是关闭的
    abstract void onConfigureFailed(CameraCaptureSession session);
    // 当摄像机设备完成自身配置时触发，CameraCaptureSession 可以开始处理捕获请求
    abstract void onConfigured(CameraCaptureSession session);
    // 每次不再有要处理的捕获请求时触发  
    void onReady(CameraCaptureSession session);
    // 当输出 Surface 的缓冲区预分配完成时触发
    void onSurfacePrepared(CameraCaptureSession session, Surface surface);
}

CaptureCallback 回调

CameraCaptureSession.CaptureCallback 捕获回调接口，表示 CameraDevice 在接收到数据更新时的回调： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public static abstract class CaptureCallback {
    // 当单个捕获到的 Buffer 数据无法发送到 Surface 时触发  
    void onCaptureBufferLost(CameraCaptureSession session, 
        CaptureRequest request, Surface target, long frameNumber);
    // 图像捕获完成并且所有数据可用时触发  
    void onCaptureCompleted(CameraCaptureSession session, 
        CaptureRequest request, TotalCaptureResult result);
    // 当 CameraDevice 无法为请求生成 CaptureResult 时触发  
    void onCaptureFailed(CameraCaptureSession session, 
        CaptureRequest request, CaptureFailure failure);
    // 这里的结果是完整结果的一部分，每次捕获可能会多次触发
    // 每个结果只可能出现在某一次中，而最终整体的结果在 onCaptureCompleted 中
    void onCaptureProgressed(CameraCaptureSession session, 
        CaptureRequest request, CaptureResult partialResult);
    // 中止捕获时触发  
    void onCaptureSequenceAborted(CameraCaptureSession session,
        int sequenceId);
    // 捕获序列已经完成，并且结果已经返回时触发  
    void onCaptureSequenceCompleted(CameraCaptureSession session, 
        int sequenceId, long frameNumber);
    // 当 CameraDevice 开始捕获图像时触发  
    void onCaptureStarted(CameraCaptureSession session, 
        CaptureRequest request, long timestamp, long frameNumber);
}

CameraConstrainedHighSpeedCaptureSession

抽象类，继承 CameraCaptureSession ，表示高速捕获会话，支持大于等于 120 帧/秒的录像。只有一个公共并且是抽象的方法 createHighSpeedRequestList ，表示创建高速请求列表。 

1
2
3
4
5
public abstract class CameraConstrainedHighSpeedCaptureSession 
        extends CameraCaptureSession {
    public abstract List<CaptureRequest> createHighSpeedRequestList(
            @NonNull CaptureRequest request) throws CameraAccessException;
}

CaptureFailure

CaptureFailure 类表示拍照失败，包含了失败的具体信息；在 CameraCaptureSession.CaptureCallback 回调接口的 onCaptureFailed 中返回该类。

常量

CaptureFailure 中包含两个表示失败原因的常量：

  • REASON_ERROR ：framework 中出现的错误，导致当前帧丢弃了 CaptureResult
  • REASON_FLUSHED ：因为调用了 CameraCaptureSession.abortCaptures() 导致的捕获失败

API 方法

CaptureFailure 中 API 简介： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
public class CaptureFailure {
    public static final int REASON_ERROR = 0;
    public static final int REASON_FLUSHED = 1;

    private final CaptureRequest mRequest;
    private final int mReason;
    private final boolean mDropped;
    private final int mSequenceId;
    private final long mFrameNumber;

    public CaptureFailure(CaptureRequest request, int reason,
            boolean dropped, int sequenceId, long frameNumber) {
        mRequest = request;
        mReason = reason;
        mDropped = dropped;
        mSequenceId = sequenceId;
        mFrameNumber = frameNumber;
    }
   
    public CaptureRequest getRequest() {
        return mRequest;
    }
    // 获取帧编号
    public long getFrameNumber() {
        return mFrameNumber;
    }
    public int getReason() {
        return mReason;
    }
    // 确定图像是否从相机捕获；如果是，则可以使用图像缓冲区
    public boolean wasImageCaptured() {
        return !mDropped;
    }
    // 获取序列号；该序列号为 CameraCaptureSession.capture 的返回值
    public int getSequenceId() {
        return mSequenceId;
    }
}

CameraMetadata

抽象类，是一个数据结构，包含了 CameraDevice 控制命令和相关信息。CameraMetadata 用于查询 CameraDevice 属性、捕获结果、设置请求参数的基本键/值映射。
CameraMetadata 的所有实例都是不可变的，整个抽象类只提供一个公共方法： 

1
2
3
4
5
6
public List<TKey> getKeys() {
    Class<CameraMetadata<TKey>> thisClass = 
        (Class<CameraMetadata<TKey>>) getClass();
    return Collections.unmodifiableList(
            getKeys(thisClass, getKeyClass(), this, /*filterTags*/null));
}

从实现中可以看出 getKeys() 方法返回的键列表是永远不会更改的，任何键在整个对象生命周期内返回的值也不会更改。

CameraMetadata 中定义的常量非常多，详细含义需要参考 API 中的详解。

常量

CameraMetadata 支持的常量及对应含义：

  • 色差校准模式 COLOR_CORRECTION_ABERRATION
    COLOR_CORRECTION_ABERRATION_MODE_FAST ：色差校准时不会减慢传感器的捕获速率
    COLOR_CORRECTION_ABERRATION_MODE_HIGH_QUALITY ：色差校准时提高图像质量，但是传感器捕获率会降低
    COLOR_CORRECTION_ABERRATION_MODE_OFF ：关闭色差校准模式
  • 颜色校准模式 COLOR_CORRECTION
    COLOR_CORRECTION_MODE_FAST ：颜色校准不会减慢传感器的捕获速率
    COLOR_CORRECTION_MODE_HIGH_QUALITY ：颜色校准时提高图片质量，但是传感器捕获率会被降低；可以用来做高级白平衡调整
    COLOR_CORRECTION_MODE_TRANSFORM_MATRIX ：使用矩阵转换，但是必须要禁用高级白平衡
  • 避免灯源工频干扰模式 ANTIBANDING
    CONTROL_AE_ANTIBANDING_MODE_50HZ ：CameraDevice 调整曝光持续时间以避免 50Hz 照明光源干扰产生的明暗条纹问题
    CONTROL_AE_ANTIBANDING_MODE_60HZ ：避免 60Hz 照明光源的明暗条纹问题
    CONTROL_AE_ANTIBANDING_MODE_AUTO ：默认模式，自动适配照明光源的频率，来避免明暗条纹问题
    CONTROL_AE_ANTIBANDING_MODE_OFF ：不会调整曝光持续时间以避免出现明暗条纹问题
  • 自动曝光模式 AE
    CONTROL_AE_MODE_OFF ：自动曝光关闭
    CONTROL_AE_MODE_ON ：自动曝光打开
    CONTROL_AE_MODE_ON_ALWAYS_FLASH ：自动曝光打开并总是闪光
    CONTROL_AE_MODE_ON_AUTO_FLASH ：自动曝光打开并自动闪光
    CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ：自动曝光打开，自动闪光并消除红眼
    CONTROL_AE_MODE_ON_EXTERNAL_FLASH ：自动曝光，并打开外接闪光灯
  • 测光序列 PRECAPTURE
    CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL ：自动曝光前的测光序列，取消
    CONTROL_AE_PRECAPTURE_TRIGGER_IDLE ：测光序列空闲
    CONTROL_AE_PRECAPTURE_TRIGGER_START ：开启测光序列
  • 自动曝光状态 AE_STATE
    CONTROL_AE_STATE_CONVERGED ：自动曝光状态良好
    CONTROL_AE_STATE_FLASH_REQUIRED ：自动曝光状态良好，但是需要打开闪光灯
    CONTROL_AE_STATE_INACTIVE ：自动曝光关闭，或者被重置
    CONTROL_AE_STATE_LOCKED ：自动曝光锁定
    CONTROL_AE_STATE_PRECAPTURE ：自动曝光需要发送测光序列
    CONTROL_AE_STATE_SEARCHING ：这是瞬间状态，表示自动曝光还没设置好，正在搜索
  • 自动对焦 AF
    CONTROL_AF_MODE_AUTO ：基本自动对焦模式
    CONTROL_AF_MODE_CONTINUOUS_PICTURE ：自动对焦连续的修改镜头位置以提供恒定对焦的图像流
    CONTROL_AF_MODE_CONTINUOUS_VIDEO ：录像中的自动对焦
    CONTROL_AF_MODE_EDOF ：扩展景深模式 Extended depth of field
    CONTROL_AF_MODE_MACRO ：特写聚焦模式
    CONTROL_AF_MODE_OFF ：自动对焦模式关闭
  • 自动对焦场景 AF_SCENE
    CONTROL_AF_SCENE_CHANGE_DETECTED ：自动对焦区域内检测到场景变化
    CONTROL_AF_SCENE_CHANGE_NOT_DETECTED ：自动对焦区域场景变化不检测
  • 自动对焦状态 AF_STATE
    CONTROL_AF_STATE_ACTIVE_SCAN ：自动对焦扫描
    CONTROL_AF_STATE_FOCUSED_LOCKED ：自动对焦，焦点锁定
    CONTROL_AF_STATE_INACTIVE ：自动对焦被关闭或者没有扫描过
    CONTROL_AF_STATE_NOT_FOCUSED_LOCKED ：自动对焦焦点锁定失败
    CONTROL_AF_STATE_PASSIVE_FOCUSED ：瞬态，自动对焦找到焦点，但是随时可能从新扫描
    CONTROL_AF_STATE_PASSIVE_SCAN ：瞬态，自动对焦正在扫描
    CONTROL_AF_STATE_PASSIVE_UNFOCUSED ：瞬态，自动对焦扫描后没有找到焦点，随时可以从新扫描
  • 自动对焦触发器 AF_TRIGGER
    CONTROL_AF_TRIGGER_CANCEL ：取消自动对焦触发器
    CONTROL_AF_TRIGGER_IDLE ：触发器空闲
    CONTROL_AF_TRIGGER_START ：触发器触发自动对焦
  • 自动白平衡模式 AWE
    CONTROL_AWB_MODE_AUTO ：基本自动白平衡模式
    CONTROL_AWB_MODE_CLOUDY_DAYLIGHT ：自动白平衡关闭，使用阴天日光作为白平衡的假定场景照明
    CONTROL_AWB_MODE_DAYLIGHT ：自动白平衡关闭，日光作为场景照明
    CONTROL_AWB_MODE_FLUORESCENT ：自动白平衡关闭，荧光灯
    CONTROL_AWB_MODE_INCANDESCENT ：自动白平衡关闭，白炽灯
    CONTROL_AWB_MODE_OFF ：自动白平衡关闭
    CONTROL_AWB_MODE_SHADE ：自动白平衡关闭，阴影
    CONTROL_AWB_MODE_TWILIGHT ：自动白平衡关闭，暮光
    CONTROL_AWB_MODE_WARM_FLUORESCENT ：自动白平衡关闭，暖荧光灯
  • 自动白平衡状态 AWE_STATE
    CONTROL_AWB_STATE_CONVERGED ：自动白平衡状态良好
    CONTROL_AWB_STATE_INACTIVE ：自动白平衡还没有开启自动模式，或者还没有开始测量
    CONTROL_AWB_STATE_LOCKED ：自动白平衡锁定
    CONTROL_AWB_STATE_SEARCHING ：瞬态，自动白平衡还没有找到合适的值，处于搜索状态
  • 数据捕获请求 CAPTURE_INTENT
    CONTROL_CAPTURE_INTENT_CUSTOM ：CameraDevice 默认的数据捕获请求
    CONTROL_CAPTURE_INTENT_MANUAL ：手动设置参数
    CONTROL_CAPTURE_INTENT_MOTION_TRACKING ：运动跟踪
    CONTROL_CAPTURE_INTENT_PREVIEW ：请求预览
    CONTROL_CAPTURE_INTENT_STILL_CAPTURE ：请求拍照
    CONTROL_CAPTURE_INTENT_VIDEO_RECORD ：请求录像
    CONTROL_CAPTURE_INTENT_VIDEO_SNAPSHOT ：请求视频快照
    CONTROL_CAPTURE_INTENT_ZERO_SHUTTER_LAG ：ZSL 零延时拍照请求
  • 颜色效果模式 EFFECT_MODE
    CONTROL_EFFECT_MODE_AQUA ：蓝色色调 AQUA 模式
    CONTROL_EFFECT_MODE_BLACKBOARD ：黑板模式，黑色区域带有白色或灰色细节
    CONTROL_EFFECT_MODE_MONO ：MONO 单色调模式，将图像映射为单一颜色
    CONTROL_EFFECT_MODE_NEGATIVE ：NEGATIVE 负片模式，图像的颜色反转
    CONTROL_EFFECT_MODE_OFF ：颜色效果模式关闭
    CONTROL_EFFECT_MODE_POSTERIZE ：POSTERIZE 色调分离模式，图像使用离散的色调区域而不是连续的
    CONTROL_EFFECT_MODE_SEPIA ：SEPIA 棕褐色效果模式，图像被映射为暖灰色，红色和棕色色调
    CONTROL_EFFECT_MODE_SOLARIZE ：SOLARIZE 日晒效果模式，图像的色调完全或部分颠倒
    CONTROL_EFFECT_MODE_WHITEBOARD ：白板模式，图像通常显示为白色区域，具有黑色或灰色细节
  • 3A 模式
    CONTROL_MODE_AUTO ：3A: AE, AWE, AF 都设置为自动模式
    CONTROL_MODE_OFF ：关闭 3A，所有的效果都是手动控制
    CONTROL_MODE_OFF_KEEP_STATE ：和模式关闭相同，但是使用 3A 算法来更新统计信息
    CONTROL_MODE_USE_SCENE_MODE ：使用特殊场景模式
  • 场景模式 SCENE_MODE
    CONTROL_SCENE_MODE_ACTION ：对快速移动物体的优化
    CONTROL_SCENE_MODE_BARCODE ：用于准确捕获条形码照片的优化
    CONTROL_SCENE_MODE_BEACH ：海滩场景，适合户外、明亮的场景
    CONTROL_SCENE_MODE_CANDLELIGHT ：火焰场景，适合光源为火焰的昏暗场景
    CONTROL_SCENE_MODE_DISABLED ：关闭场景模式
    CONTROL_SCENE_MODE_FACE_PRIORITY ：人脸场景，如果支持人脸检测，使用 3A 优化数据
    CONTROL_SCENE_MODE_FIREWORKS ：烟火场景，为晚上的烟火优化图片
    CONTROL_SCENE_MODE_HDR ：HDR 高动态范围模式，需要更长的时间捕获单个图像
    CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO ：已经废弃，主要用于高速录像场景
    CONTROL_SCENE_MODE_LANDSCAPE ：风景场景，用于优化远距离拍摄图片
    CONTROL_SCENE_MODE_NIGHT ：夜间场景，用于优化低光场景下的图片
    CONTROL_SCENE_MODE_NIGHT_PORTRAIT ：夜间人像，用于优化低光场景下的人像拍摄
    CONTROL_SCENE_MODE_PARTY ：聚会场景，适合昏暗、室内、多个移动人像的场景
    CONTROL_SCENE_MODE_PORTRAIT ：人像场景
    CONTROL_SCENE_MODE_SNOW ：雪景，适合明亮、室外、包含雪的场景
    CONTROL_SCENE_MODE_SPORTS ：运动场景，适合快速移动的人物
    CONTROL_SCENE_MODE_STEADYPHOTO ：优化设备小幅移动导致的图像模糊，比如手抖
    CONTROL_SCENE_MODE_SUNSET ：日落场景
    CONTROL_SCENE_MODE_THEATRE ：剧场场景，适合昏暗、室内、闪光灯关闭的场景
  • 录像防抖模式 VIDEO_STABILIZATION
    CONTROL_VIDEO_STABILIZATION_MODE_OFF ：录像防抖模式关闭
    CONTROL_VIDEO_STABILIZATION_MODE_ON ：录像防抖模式开启
  • 失真校准模式 DISTORTION_CORRECTION
    DISTORTION_CORRECTION_MODE_FAST ：镜头失真校准，在不降低传感器帧率情况下使用镜头失真校准
    DISTORTION_CORRECTION_MODE_HIGH_QUALITY ：高质量失真校准，但是会降低传感器帧率
    DISTORTION_CORRECTION_MODE_OFF ：失真校准模式关闭
  • 边缘增强 EDGE_MODE
    EDGE_MODE_FAST ：边缘增强，不降低传感器帧率
    EDGE_MODE_HIGH_QUALITY ：高质量边缘增强，但是会降低传感器帧率
    EDGE_MODE_OFF ：边缘增强关闭
    EDGE_MODE_ZERO_SHUTTER_LAG ：ZSL 零延时边缘增强
  • 闪光模式 FLASH_MODE
    FLASH_MODE_OFF ：图片捕获时不使用闪光灯
    FLASH_MODE_SINGLE ：如果闪光灯有效并有电，则开启闪光灯
    FLASH_MODE_TORCH ：闪光灯手电筒模式
    FLASH_STATE_CHARGING ：闪光灯正在充电，不能使用
    FLASH_STATE_FIRED ：这次图片捕获时，使用闪光灯
    FLASH_STATE_PARTIAL ：闪光灯部分照亮这帧图片
  • 闪光灯状态 FLASH_STATE
    FLASH_STATE_READY ：闪光灯已经准备好闪光
    FLASH_STATE_UNAVAILABLE ：没有闪光灯
  • 热点校正 HOT_PIXEL
    HOT_PIXEL_MODE_FAST ：传感器的热噪声：热点 hot pixel ，是因为芯片温度过高产生的噪点。开启热点校正，但不降低传感器帧率
    HOT_PIXEL_MODE_HIGH_QUALITY ：高质量的热点校正，但会降低传感器帧率
    HOT_PIXEL_MODE_OFF ：热点校正关闭
  • 相机硬件设备可控级别 SUPPORTED_HARDWARE_LEVEL
    各个模式支持的功能级别 LEGACY < LIMITED < FULL < LEVEL_3
    INFO_SUPPORTED_HARDWARE_LEVEL_3 ：最高权限，全层可控，并且可以进行 YUV 的再处理和原始数据捕获
    INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL ：摄像头设备为外接设备
    INFO_SUPPORTED_HARDWARE_LEVEL_FULL ：支持对每一帧数据进行控制,还支持高速率的图片拍摄
    INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED ：受限模式，支持一些基本功能；还有部分额外功能（FULL 子集）
    INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY ：向后兼容模式
  • 镜头人头方向 LENS_FACING
    LENS_FACING_BACK ：摄像头镜头成像方向与屏幕预览的关系，镜头与屏幕预览方向相反
    LENS_FACING_EXTERNAL ：外置摄像头，镜头与屏幕方向没有关系
    LENS_FACING_FRONT ：镜头与屏幕预览方向相同
  • 镜头聚焦距离测量 LENS_INFO_FOCUS_DISTANCE_CALIBRATION
    LENS_INFO_FOCUS_DISTANCE_CALIBRATION_APPROXIMATE ：镜头焦距以屈光度测量
    LENS_INFO_FOCUS_DISTANCE_CALIBRATION_CALIBRATED ：镜头焦距以屈光度测量并校准
    LENS_INFO_FOCUS_DISTANCE_CALIBRATION_UNCALIBRATED ：镜头焦距不准确，没有校准过
  • 镜头光学防抖 OIS: LENS_OPTICAL_STABILIZATION
    LENS_OPTICAL_STABILIZATION_MODE_OFF ：镜头光学防抖关闭
    LENS_OPTICAL_STABILIZATION_MODE_ON ：镜头光学防抖开启
  • 镜头光学中心位置 LENS_POSE_REFERENCE
    LENS_POSE_REFERENCE_GYROSCOPE ：镜头光学中心位置优先使用陀螺仪
    LENS_POSE_REFERENCE_PRIMARY_CAMERA ：镜头光学中心位置与相机相同方向
  • 镜头状态
    LENS_STATE_MOVING ：一个或者几个镜头的参数正在改变
    LENS_STATE_STATIONARY ：镜头参数不会改变
  • 多图像传感器的同步 MULTI_CAMERA_SENSOR_SYNC
    LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE_APPROXIMATE ：软件同步，图像的时间戳来自于传感器开始曝光的近似值
    LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE_CALIBRATED ：硬件同步，时间戳为准确值
  • 降噪模式 NOISE_REDUCTION
    NOISE_REDUCTION_MODE_FAST ：开启降噪模式，不降低传感器帧率
    NOISE_REDUCTION_MODE_HIGH_QUALITY ：高质量降噪模式，但会降低传感器帧率
    NOISE_REDUCTION_MODE_MINIMAL ：在不降低传感器帧率情况下，将噪声降到最小
    NOISE_REDUCTION_MODE_OFF ：降噪模式关闭
    NOISE_REDUCTION_MODE_ZERO_SHUTTER_LAG ：ZSL 零延时降噪模式
  • 有效请求功能集 REQUEST_AVAILABLE_CAPABILITIES
    REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE ：向后兼容，每个摄像头设备支持的最小功能集
    REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE ：当后期处理设置为 FAST 模式时，CameraDevice 支持以大于等于 20帧/秒（至少未压缩的YUV格式）的速度捕获高分辨率图像；也可以大于等于 10帧/秒的速度捕获最大分辨率图像。高分辨率至少 800 万像素或设备的最大分辨率，以较小者为准
    REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO ：设备支持高速视频录制（帧率大于等于 120 帧/秒）
    REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT ：支持景深
    REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA ：支持两个或多个物理摄像头
    REQUEST_AVAILABLE_CAPABILITIES_MANUAL_POST_PROCESSING ：支持图像手动后期处理
    REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR ：支持传感器获取图像阶段的手动控制，比如 3A 算法控制
    REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME ：单色相机，U, V 的值都是 128
    REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING ：支持运动追踪
    REQUEST_AVAILABLE_CAPABILITIES_PRIVATE_REPROCESSING ：支持零延时 ZSL
    REQUEST_AVAILABLE_CAPABILITIES_RAW ：支持传感器的原始缓冲区数据
    REQUEST_AVAILABLE_CAPABILITIES_READ_SENSOR_SETTINGS ：3A 在运行时，支持读取传感器的设置
    REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING ：和 PRIVATE_REPROCESSING 类似，支持 YUV_420_888
  • 裁剪类型 CROPPING
    SCALER_CROPPING_TYPE_CENTER_ONLY ：仅支持中央裁剪区域
    SCALER_CROPPING_TYPE_FREEFORM ：支持任意选择裁剪区域
  • 颜色滤镜 COLOR_FILTER
    SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_BGGR ：颜色滤镜即传感器中 Bayer 格式图像的 RGB 滤色器，从左上角开始每个 2x2 的像素区域使用的颜色滤镜组合；当前为 BGGR
    SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GBRG ：2x2 区域为 GBRG
    SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_GRBG ：2x2 区域为 GRBG
    SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGB ：传感器输出不是 Bayer 格式的图像，输出的是每个像素 316 位值，而不是 116
    SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_RGGB ：2x2 区域为 RGGB
  • 时间戳 TIMESTAMP
    SENSOR_INFO_TIMESTAMP_SOURCE_REALTIME ：时间戳和系统时间相同
    SENSOR_INFO_TIMESTAMP_SOURCE_UNKNOWN ：时间戳以纳秒为单位，并不能和其他子系统对比
  • 光源色温 ILLUMINANT
    SENSOR_REFERENCE_ILLUMINANT1_CLOUDY_WEATHER ：指的是人造标准光源的类型，模拟环境光源。模拟多云天
    SENSOR_REFERENCE_ILLUMINANT1_COOL_WHITE_FLUORESCENT ：模拟白色荧光，W 3900 - 4500 K
    SENSOR_REFERENCE_ILLUMINANT1_D50 ：D50, 5000K 模拟太阳光色温
    SENSOR_REFERENCE_ILLUMINANT1_D55 ：D55
    SENSOR_REFERENCE_ILLUMINANT1_D65 ：D65 6500K 国际标准人工日光色温
    SENSOR_REFERENCE_ILLUMINANT1_D75 ：D75 75000K 模拟北方平均太阳光色温
    SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT ：模拟白天
    SENSOR_REFERENCE_ILLUMINANT1_DAYLIGHT_FLUORESCENT ：白天荧光 D 5700 - 7100K
    SENSOR_REFERENCE_ILLUMINANT1_DAY_WHITE_FLUORESCENT ：白天白色荧光 N 4600 - 5400K
    SENSOR_REFERENCE_ILLUMINANT1_FINE_WEATHER ：模拟好天气
    SENSOR_REFERENCE_ILLUMINANT1_FLASH ：闪光灯
    SENSOR_REFERENCE_ILLUMINANT1_FLUORESCENT ：荧光灯
    SENSOR_REFERENCE_ILLUMINANT1_ISO_STUDIO_TUNGSTEN ：标准钨丝灯
    SENSOR_REFERENCE_ILLUMINANT1_SHADE ：阴影
    SENSOR_REFERENCE_ILLUMINANT1_STANDARD_A ：美式橱窗射灯 2856K
    SENSOR_REFERENCE_ILLUMINANT1_STANDARD_B ：
    SENSOR_REFERENCE_ILLUMINANT1_STANDARD_C ：
    SENSOR_REFERENCE_ILLUMINANT1_TUNGSTEN ：白炽灯
    SENSOR_REFERENCE_ILLUMINANT1_WHITE_FLUORESCENT ：白色荧光灯 WW 3200 - 3700K
  • 测试图案 TEST_PATTERN
    SENSOR_TEST_PATTERN_MODE_COLOR_BARS ：使用 8 条彩色图案：白、黄、青、绿、品红、红、蓝、黑
    SENSOR_TEST_PATTERN_MODE_COLOR_BARS_FADE_TO_GRAY ：和 COLOR_BARS 类似，但是从顶部到底部淡化成灰色
    SENSOR_TEST_PATTERN_MODE_CUSTOM1 ：自定义模式，图片必须是静态的
    SENSOR_TEST_PATTERN_MODE_OFF ：默认值，没有使用测试图案，直接返回传感器捕获的数据
    SENSOR_TEST_PATTERN_MODE_PN9 ：所有像素数据由从 PN9 512 位序列生成的伪随机序列
    SENSOR_TEST_PATTERN_MODE_SOLID_COLOR ：所有像素由颜色通道代替
  • 镜头阴影校正 Lens SHADING
    SHADING_MODE_FAST ：镜头均匀性指画面中心的明亮度到四周的明亮度比值。阴影校正，不会降低传感器帧率
    SHADING_MODE_HIGH_QUALITY ：高质量的阴影校正，但会降低帧率
    SHADING_MODE_OFF ：没有校正
  • 人脸检测 FACE DETECT
    STATISTICS_FACE_DETECT_MODE_FULL ：返回人脸检测所有元数据：面部矩形，分数，ID 等
    STATISTICS_FACE_DETECT_MODE_OFF ：人脸检测统计数据关闭
    STATISTICS_FACE_DETECT_MODE_SIMPLE ：仅返回人脸矩形，置信度
  • 镜头均匀性阴影图 LENS SHADING MAP
    STATISTICS_LENS_SHADING_MAP_MODE_OFF ：传感器输出的数据中不包含镜头阴影图
    STATISTICS_LENS_SHADING_MAP_MODE_ON ：传感器输出的数据中包含镜头阴影图
  • 光学防抖数据 OIS DATA
    STATISTICS_OIS_DATA_MODE_OFF ：传感器输出数据不包含光学防抖位置信息
    STATISTICS_OIS_DATA_MODE_ON ：传感器输出数据包含光学防抖位置信息
  • 照明闪烁 FLICKER
    STATISTICS_SCENE_FLICKER_50HZ ：CameraDevice 检查当前场景照明闪烁 50HZ
    STATISTICS_SCENE_FLICKER_60HZ ：闪烁为 60HZ
    STATISTICS_SCENE_FLICKER_NONE ：不去检查
  • 最大延迟同步 LATENCY
    SYNC_MAX_LATENCY_PER_FRAME_CONTROL ：每帧都去检查最大延迟同步
    SYNC_MAX_LATENCY_UNKNOWN ：不确定延迟同步
  • 色调映射模式 TONEMAP MODE
    TONEMAP_MODE_CONTRAST_CURVE ：不会降低传感器帧率，使用指定色调映射曲线
    TONEMAP_MODE_FAST ：不会降低传感器帧率，使用高级伽马映射和颜色增强
    TONEMAP_MODE_GAMMA_VALUE ：不会降低帧率，使用伽马值进行颜色映射，禁用其他色调映射和颜色增强
    TONEMAP_MODE_HIGH_QUALITY ：高质量的伽马映射和颜色增强，会降低帧率
    TONEMAP_MODE_PRESET_CURVE ：不会降低帧率，使用预设的色调映射曲线来执行色调映射，禁用其他色调映射和颜色增强
  • 色调映射曲线预设值 TONEMAP PRESET CURVE
    TONEMAP_PRESET_CURVE_REC709 ：色调映射曲线预设 ITU-R BT.709
    TONEMAP_PRESET_CURVE_SRGB ：色调映射曲线预设 sRGB

CameraCharacteristics

继承 CameraMetadata ，用来描述 CameraDevice 设备的属性，这些属性是不可修改的，设备出厂时提供的；可以通过 CameraManager.getCameraCharacteristics(String cameraID) 来查询当前设备支持哪些属性。

Key 常量

CameraCharacteristics 支持的 Key 常量及对应含义，这些值都是从 system/media/camera/docs 中自动解析生成的： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
  // 相差矫正模式列表
  public static final Key<int[]> 
      COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES =
      new Key<int[]>("android.colorCorrection.availableAberrationModes",
      int[].class);
  // 自动曝光避免工频干扰列表
  public static final Key<int[]> 
      CONTROL_AE_AVAILABLE_ANTIBANDING_MODES =
      new Key<int[]>("android.control.aeAvailableAntibandingModes",
      int[].class);
  // 自动曝光模式列表  
  public static final Key<int[]> CONTROL_AE_AVAILABLE_MODES =
      new Key<int[]>("android.control.aeAvailableModes", int[].class);
  // 支持的帧率范围  
  public static final Key<android.util.Range<Integer>[]> 
      CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES =
      new Key<android.util.Range<Integer>[]>(
          "android.control.aeAvailableTargetFpsRanges", 
          new TypeReference<android.util.Range<Integer>[]>() {{ }});
  // 自动曝光补偿值范围  
  public static final Key<android.util.Range<Integer>> 
      CONTROL_AE_COMPENSATION_RANGE =
          new Key<android.util.Range<Integer>>(
          "android.control.aeCompensationRange", 
          new TypeReference<android.util.Range<Integer>>() {{ }});
  // 自动曝光补偿值最小步进  
  public static final Key<Rational> CONTROL_AE_COMPENSATION_STEP =
      new Key<Rational>("android.control.aeCompensationStep", 
      Rational.class);
  // 是否支持 AE 锁  
  public static final Key<Boolean> CONTROL_AE_LOCK_AVAILABLE =
      new Key<Boolean>("android.control.aeLockAvailable",boolean.class);
  // 自动对焦模式列表  
  public static final Key<int[]> CONTROL_AF_AVAILABLE_MODES =
      new Key<int[]>("android.control.afAvailableModes", int[].class);
  // 颜色效果列表  
  public static final Key<int[]> CONTROL_AVAILABLE_EFFECTS =
      new Key<int[]>("android.control.availableEffects", int[].class);
  // 控制模式列表  
  public static final Key<int[]> CONTROL_AVAILABLE_MODES =
      new Key<int[]>("android.control.availableModes", int[].class);
  // 场景模式列表  
  public static final Key<int[]> CONTROL_AVAILABLE_SCENE_MODES =
      new Key<int[]>("android.control.availableSceneModes",int[].class);
  // 视频防抖模式列表
  public static final Key<int[]> 
      CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES =
      new Key<int[]>("android.control.availableVideoStabilizationModes",
      int[].class);
  // 自动白平衡列表  
  public static final Key<int[]> CONTROL_AWB_AVAILABLE_MODES =
      new Key<int[]>("android.control.awbAvailableModes", int[].class);
  // 是否支持自动白平衡锁  
  public static final Key<Boolean> CONTROL_AWB_LOCK_AVAILABLE =
      new Key<Boolean>("android.control.awbLockAvailable",boolean.class);
  // 自动曝光，测量区域最大值  
  public static final Key<Integer> CONTROL_MAX_REGIONS_AE =
          new Key<Integer>("android.control.maxRegionsAe", int.class);
  // 自动对焦，测量区域最大值  
  public static final Key<Integer> CONTROL_MAX_REGIONS_AF =
          new Key<Integer>("android.control.maxRegionsAf", int.class);
  // 自动白平衡，测量区域最大值  
  public static final Key<Integer> CONTROL_MAX_REGIONS_AWB =
          new Key<Integer>("android.control.maxRegionsAwb", int.class);
  // 传感器灵敏度增强范围  
  public static final Key<android.util.Range<Integer>> 
      CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE =
      new Key<android.util.Range<Integer>>(
      "android.control.postRawSensitivityBoostRange", 
      new TypeReference<android.util.Range<Integer>>() {{ }});
  // 指示捕获目标能否同时输出 DEPTH16/DEPTH_POIN 
  // 或者正常模式 YUV_420_888, JPEG, RAW
  public static final Key<Boolean> DEPTH_DEPTH_IS_EXCLUSIVE =
      new Key<Boolean>("android.depth.depthIsExclusive", boolean.class);
  // 失真校准模式列表  
  public static final Key<int[]> DISTORTION_CORRECTION_AVAILABLE_MODES=.;
  // 边缘增强模式列表  
  public static final Key<int[]> EDGE_AVAILABLE_EDGE_MODES =
      new Key<int[]>("android.edge.availableEdgeModes", int[].class);
  // 是否有闪光灯  
  public static final Key<Boolean> FLASH_INFO_AVAILABLE =
      new Key<Boolean>("android.flash.info.available", boolean.class);
  // 热点矫正模式列表  
  public static final Key<int[]> HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES =
      new Key<int[]>("android.hotPixel.availableHotPixelModes", 
      int[].class);
  // 相机全功能支持级别  
  public static final Key<Integer> INFO_SUPPORTED_HARDWARE_LEVEL =
      new Key<Integer>("android.info.supportedHardwareLevel",int.class);
  // 相机设备制造商信息，如 ISP 硬件，传感器等等  
  public static final Key<String> INFO_VERSION=...;
  // JPEG 缩略图大小  
  public static final Key<android.util.Size[]> 
      JPEG_AVAILABLE_THUMBNAIL_SIZES =
      new Key<android.util.Size[]>("android.jpeg.availableThumbnailSizes",
      android.util.Size[].class);
  // 镜头失真校准系数  
  public static final Key<float[]> LENS_DISTORTION=...;
  // 相机相对屏幕的方向  
  public static final Key<Integer> LENS_FACING =
      new Key<Integer>("android.lens.facing", int.class);
  // 相机支持的光圈大小列表  
  public static final Key<float[]> LENS_INFO_AVAILABLE_APERTURES =
      new Key<float[]>("android.lens.info.availableApertures", 
      float[].class);
  // 中性密度滤镜值列表  
  public static final Key<float[]> LENS_INFO_AVAILABLE_FILTER_DENSITIES =
          new Key<float[]>("android.lens.info.availableFilterDensities", 
          float[].class);
  // 焦距长度列表  
  public static final Key<float[]> LENS_INFO_AVAILABLE_FOCAL_LENGTHS =
          new Key<float[]>("android.lens.info.availableFocalLengths", 
          float[].class);
  // 光学防抖模式列表  
  public static final Key<int[]> 
      LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION =
      new Key<int[]>("android.lens.info.availableOpticalStabilization",
      int[].class);
  // 镜头焦距校准质量  
  public static final Key<Integer> LENS_INFO_FOCUS_DISTANCE_CALIBRATION=
          new Key<Integer>("android.lens.info.focusDistanceCalibration",
          int.class);
  // 镜头超焦距  
  public static final Key<Float> LENS_INFO_HYPERFOCAL_DISTANCE =
          new Key<Float>("android.lens.info.hyperfocalDistance", 
          float.class);
  // 镜头进入清晰焦点的最短距离  
  public static final Key<Float> LENS_INFO_MINIMUM_FOCUS_DISTANCE =
          new Key<Float>("android.lens.info.minimumFocusDistance", 
          float.class);
  // 镜头固有的校准参数  
  public static final Key<float[]> LENS_INTRINSIC_CALIBRATION =
          new Key<float[]>("android.lens.intrinsicCalibration", 
          float[].class);
  // 不同的校准方法或校准用例，产生最好或最坏结果依赖于选取区域
  public static final Key<Integer> LENS_POSE_REFERENCE=...;
  // 镜头坐标体系的方向  
  public static final Key<float[]> LENS_POSE_ROTATION =
      new Key<float[]>("android.lens.poseRotation", float[].class);
  // 镜头光学中心位置  
  public static final Key<float[]> LENS_POSE_TRANSLATION =
      new Key<float[]>("android.lens.poseTranslation", float[].class);
  // 降级，使用 LENS_DISTORTION 替代  
  public static final Key<float[]> LENS_RADIAL_DISTORTION =
      new Key<float[]>("android.lens.radialDistortion", float[].class);
  // 多传感器时间戳同步类型  
public static final Key<Integer> LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE=.;
  // 降噪模式列表  
  public static final Key<int[]> 
      NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES =
          new Key<int[]>(
          "android.noiseReduction.availableNoiseReductionModes",
          int[].class);
  // 最大的停顿时间  
  public static final Key<Integer> REPROCESS_MAX_CAPTURE_STALL =
      new Key<Integer>("android.reprocess.maxCaptureStall", int.class);
  // 相机支持的功能列表  
  public static final Key<int[]> REQUEST_AVAILABLE_CAPABILITIES =
      new Key<int[]>("android.request.availableCapabilities", 
      int[].class);
  // 最大输入流  
  public static final Key<Integer> REQUEST_MAX_NUM_INPUT_STREAMS =
          new Key<Integer>("android.request.maxNumInputStreams", 
          int.class);
  // 最大输出流（并发）  
  public static final Key<Integer> REQUEST_MAX_NUM_OUTPUT_PROC =
          new Key<Integer>("android.request.maxNumOutputProc", 
          int.class);
  // 最大输出流（同步）  
  public static final Key<Integer> 
      REQUEST_MAX_NUM_OUTPUT_PROC_STALLING =
          new Key<Integer>("android.request.maxNumOutputProcStalling",
          int.class);
  // RAW 格式最大输出流  
  public static final Key<Integer> REQUEST_MAX_NUM_OUTPUT_RAW =
      new Key<Integer>("android.request.maxNumOutputRaw", int.class);
  // 定义输出结果可以有多少个子结果  
  public static final Key<Integer> REQUEST_PARTIAL_RESULT_COUNT =
      new Key<Integer>("android.request.partialResultCount", int.class);
  // 最大管道深度  
  public static final Key<Byte> REQUEST_PIPELINE_MAX_DEPTH =
      new Key<Byte>("android.request.pipelineMaxDepth", byte.class);
  // 最大数字变焦比率  
  public static final Key<Float> SCALER_AVAILABLE_MAX_DIGITAL_ZOOM =
      new Key<Float>("android.scaler.availableMaxDigitalZoom", 
      float.class);
  // 支持的裁剪类型  
  public static final Key<Integer> SCALER_CROPPING_TYPE =
          new Key<Integer>("android.scaler.croppingType", int.class);
  // 图像格式对应的输出配置表  
  public static final Key<
      android.hardware.camera2.params.StreamConfigurationMap> 
      SCALER_STREAM_CONFIGURATION_MAP =
        new Key<android.hardware.camera2.params.StreamConfigurationMap>(
        "android.scaler.streamConfigurationMap", 
        android.hardware.camera2.params.StreamConfigurationMap.class);
  // 传感器测试图案列表  
  public static final Key<int[]> SENSOR_AVAILABLE_TEST_PATTERN_MODES =
      new Key<int[]>("android.sensor.availableTestPatternModes",
      int[].class);
  // 滤色器阵列马赛克通道的零光值（黑电平）  
  public static final Key<
      android.hardware.camera2.params.BlackLevelPattern> 
      SENSOR_BLACK_LEVEL_PATTERN =
          new Key<android.hardware.camera2.params.BlackLevelPattern>(
          "android.sensor.blackLevelPattern", 
          android.hardware.camera2.params.BlackLevelPattern.class);
  // 第一参考光源，校准变换矩阵  
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_CALIBRATION_TRANSFORM1 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.calibrationTransform1", 
          android.hardware.camera2.params.ColorSpaceTransform.class);
  // 第二参考光源，校准变换矩阵 
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_CALIBRATION_TRANSFORM2 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.calibrationTransform2", 
          android.hardware.camera2.params.ColorSpaceTransform.class);
  // 第一参考光源，颜色转换矩阵  
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_COLOR_TRANSFORM1 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.colorTransform1", 
          ndroid.hardware.camera2.params.ColorSpaceTransform.class);
  // 第二参考光源，颜色转换矩阵  
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_COLOR_TRANSFORM2 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.colorTransform2", 
          android.hardware.camera2.params.ColorSpaceTransform.class);
  // 第一参考光源，使用 D50 白点的颜色转换矩阵  
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_FORWARD_MATRIX1 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.forwardMatrix1", 
          android.hardware.camera2.params.ColorSpaceTransform.class);
  // 第二参考光源，使用 D50 白点的颜色转换矩阵
  public static final Key<
      android.hardware.camera2.params.ColorSpaceTransform> 
      SENSOR_FORWARD_MATRIX2 =
          new Key<android.hardware.camera2.params.ColorSpaceTransform>(
          "android.sensor.forwardMatrix2", 
          android.hardware.camera2.params.ColorSpaceTransform.class);    
  // 使用几何失真校准的矩形大小  
  public static final Key<android.graphics.Rect> 
      SENSOR_INFO_ACTIVE_ARRAY_SIZE =
          new Key<android.graphics.Rect>(
          "android.sensor.info.activeArraySize", 
          android.graphics.Rect.class);
  // 滤色镜排布  
  public static final Key<Integer> SENSOR_INFO_COLOR_FILTER_ARRANGEMENT =
          new Key<Integer>("android.sensor.info.colorFilterArrangement", 
          int.class);
  // 图像曝光时间范围
  public static final Key<android.util.Range<Long>> 
      SENSOR_INFO_EXPOSURE_TIME_RANGE =
          new Key<android.util.Range<Long>>(
          "android.sensor.info.exposureTimeRange", 
          new TypeReference<android.util.Range<Long>>() {{ }});
  // 摄像头原始图像输出是否受镜头阴影矫正  
  public static final Key<Boolean> SENSOR_INFO_LENS_SHADING_APPLIED =
          new Key<Boolean>("android.sensor.info.lensShadingApplied",
          boolean.class);
  // 最大帧间隔（最小帧率）  
  public static final Key<Long> SENSOR_INFO_MAX_FRAME_DURATION =
          new Key<Long>("android.sensor.info.maxFrameDuration", 
          long.class);
  // 全像素数组的物理尺寸  
  public static final Key<android.util.SizeF> SENSOR_INFO_PHYSICAL_SIZE =
          new Key<android.util.SizeF>("android.sensor.info.physicalSize",
          android.util.SizeF.class);
  // 全像素数组的维度，包括黑色校准像素  
  public static final Key<android.util.Size> SENSOR_INFO_PIXEL_ARRAY_SIZE=
      new Key<android.util.Size>("android.sensor.info.pixelArraySize",
      android.util.Size.class);
  // 几何失真校准的有效区域  
  public static final Key<android.graphics.Rect> 
      SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE =
          new Key<android.graphics.Rect>(
          "android.sensor.info.preCorrectionActiveArraySize",
          android.graphics.Rect.class);
  // ISO 感光度范围  
  public static final Key<android.util.Range<Integer>> 
      SENSOR_INFO_SENSITIVITY_RANGE =
          new Key<android.util.Range<Integer>>(
          "android.sensor.info.sensitivityRange", 
          new TypeReference<android.util.Range<Integer>>() {{ }});
  // 传感器开始捕获时间戳的时基源
  public static final Key<Integer> SENSOR_INFO_TIMESTAMP_SOURCE =
          new Key<Integer>("android.sensor.info.timestampSource", 
          int.class);
  // 传感器最大输出的原始数值
  public static final Key<Integer> SENSOR_INFO_WHITE_LEVEL =
          new Key<Integer>("android.sensor.info.whiteLevel", 
          int.class);
  // 通过模拟增益获得的最大灵敏度 
  public static final Key<Integer> SENSOR_MAX_ANALOG_SENSITIVITY =
          new Key<Integer>("android.sensor.maxAnalogSensitivity", 
          int.class);    
  // 传感器光学屏蔽的黑色像素不相交区域  
  public static final Key<android.graphics.Rect[]> 
      SENSOR_OPTICAL_BLACK_REGIONS =
          new Key<android.graphics.Rect[]>(
          "android.sensor.opticalBlackRegions", 
          android.graphics.Rect[].class);
  // 输出图像与屏幕垂直所需要的顺时针角度  
  public static final Key<Integer> SENSOR_ORIENTATION =
          new Key<Integer>("android.sensor.orientation", int.class);
  // 标准参考光源 1  
  public static final Key<Integer> SENSOR_REFERENCE_ILLUMINANT1 =
      new Key<Integer>("android.sensor.referenceIlluminant1", int.class);
  // 标准参考光源 2  
  public static final Key<Byte> SENSOR_REFERENCE_ILLUMINANT2 =
      new Key<Byte>("android.sensor.referenceIlluminant2", byte.class);
  // 镜头均匀性，阴影校准模式  
  public static final Key<int[]> SHADING_AVAILABLE_MODES =
          new Key<int[]>("android.shading.availableModes", int[].class);
  // 人脸识别模式模式  
  public static final Key<int[]> 
      STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES =
      new Key<int[]>("android.statistics.info.availableFaceDetectModes",
      int[].class);
  // 热点映射模式  
  public static final Key<boolean[]> 
      STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES =
          new Key<boolean[]>(
          "android.statistics.info.availableHotPixelMapModes", 
          boolean[].class);
  // 镜头阴影校准映表模式  
  public static final Key<int[]> 
      STATISTICS_INFO_AVAILABLE_LENS_SHADING_MAP_MODES =
          new Key<int[]>(
          "android.statistics.info.availableLensShadingMapModes",
          int[].class);
  // 光学防抖位置数据模式
public static final Key<int[]> STATISTICS_INFO_AVAILABLE_OIS_DATA_MODES=.;
  // 同时可检测的最大人脸数  
  public static final Key<Integer> STATISTICS_INFO_MAX_FACE_COUNT =
          new Key<Integer>("android.statistics.info.maxFaceCount", 
          int.class);
  // 最大同步延迟数  
  public static final Key<Integer> SYNC_MAX_LATENCY =
          new Key<Integer>("android.sync.maxLatency", int.class);
  // 色调映射模式  
  public static final Key<int[]> TONEMAP_AVAILABLE_TONE_MAP_MODES =
          new Key<int[]>("android.tonemap.availableToneMapModes", 
          int[].class);
  // 色调映射曲线支持的最大数量点  
  public static final Key<Integer> TONEMAP_MAX_CURVE_POINTS =
      new Key<Integer>("android.tonemap.maxCurvePoints", int.class);

API 方法

CameraCharacteristics 支持的方法： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
public final class CameraCharacteristics 
    extends CameraMetadata<CameraCharacteristics.Key<?>> {
    
    private final CameraMetadataNative mProperties;
    private List<CameraCharacteristics.Key<?>> mKeys;
    private List<CaptureRequest.Key<?>> mAvailableRequestKeys;
    private List<CaptureResult.Key<?>> mAvailableResultKeys;

    public <T> T get(Key<T> key) {
        return mProperties.get(key);
    }
    
    // 获取相机支持的请求列表  
    public List<CaptureRequest.Key<?>> getAvailableCaptureRequestKeys() {
        if (mAvailableRequestKeys == null) {
            Object crKey = CaptureRequest.Key.class;
            Class<CaptureRequest.Key<?>> crKeyTyped 
                = (Class<CaptureRequest.Key<?>>)crKey;

            int[] filterTags = get(REQUEST_AVAILABLE_REQUEST_KEYS);
            if (filterTags == null) {
                throw new AssertionError("...");
            }
            mAvailableRequestKeys = getAvailableKeyList(
                CaptureRequest.class, crKeyTyped, filterTags);
        }
        return mAvailableRequestKeys;
    }

    // 获取相机支持的结果列表  
    public List<CaptureResult.Key<?>> getAvailableCaptureResultKeys() {
        if (mAvailableResultKeys == null) {
            Object crKey = CaptureResult.Key.class;
            Class<CaptureResult.Key<?>> crKeyTyped 
                = (Class<CaptureResult.Key<?>>)crKey;

            int[] filterTags = get(REQUEST_AVAILABLE_RESULT_KEYS);
            if (filterTags == null) {
                throw new AssertionError("...");
            }
            mAvailableResultKeys = getAvailableKeyList(
                CaptureResult.class, crKeyTyped, filterTags);
        }
        return mAvailableResultKeys;
    }

    // getAvailableCaptureRequestKeys 的子集
    public List<CaptureRequest.Key<?>> 
        getAvailablePhysicalCameraRequestKeys(){...}
    
    //  getAvailableCaptureRequestKeys 的子集  
    public List<CaptureRequest.Key<?>> 
        getAvailableSessionKeys() {}
    
    public List<Key<?>> getKeys() {
        // List of keys is immutable; 
        // cache the results after we calculate them
        if (mKeys != null) {
            return mKeys;
        }

        int[] filterTags = get(REQUEST_AVAILABLE_CHARACTERISTICS_KEYS);
        if (filterTags == null) {
            throw new AssertionError("...");
        }

        mKeys = Collections.unmodifiableList(
                getKeys(getClass(), getKeyClass(), this, filterTags));
        return mKeys;
    }

    Set<String> getPhysicalCameraIds(){...}
    ...
}

CaptureRequest

CaptureRequest 继承了 CameraMetadata ；表示从 CameraDevice 获取捕获数据的请求，包含对 CameraDevice 的参数设置，算法控制，输出缓冲区等等。

  • 创建实例
    由 CameraDevice.createCaptureRequest 返回的 CaptureRequest.Builder 来创建实例。
  • 请求
    由 CameraCaptureSession.capture, CameraCaptureSession.setRepeatingRequest 向 CameraDevice 发出请求。

Key 常量

CaptureRequest 支持的 Key 常量及其含义，这些值都是 system/media/camera/docs 自动生成的： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
// 黑电平补偿是否锁定当前值；对于某些参数（曝光时间）的改变需要重置黑电平  
public static final Key<Boolean> BLACK_LEVEL_LOCK =
        new Key<Boolean>("android.blackLevel.lock", boolean.class);
// 色差校准算法的操作模式
public static final Key<Integer> COLOR_CORRECTION_ABERRATION_MODE =
        new Key<Integer>("android.colorCorrection.aberrationMode"
        , int.class);
// 适用于 Bayer 原色通道的白平衡增益
public static final 
    Key<android.hardware.camera2.params.RggbChannelVector> 
    COLOR_CORRECTION_GAINS =
        new Key<android.hardware.camera2.params.RggbChannelVector>
        ("android.colorCorrection.gains", 
        android.hardware.camera2.params.RggbChannelVector.class);
// 原始颜色转换为 sRGB 时的颜色校准模式；当 AWE 开启时，该值不会生效
public static final Key<Integer> COLOR_CORRECTION_MODE =
        new Key<Integer>("android.colorCorrection.mode", int.class);
// 颜色校准转换矩阵
public static final 
    Key<android.hardware.camera2.params.ColorSpaceTransform> 
    COLOR_CORRECTION_TRANSFORM =
        new Key<android.hardware.camera2.params.ColorSpaceTransform>(
        "android.colorCorrection.transform", 
        android.hardware.camera2.params.ColorSpaceTransform.class);
// 工频干扰模式，自动曝光时需要设置反馈补偿
public static final Key<Integer> CONTROL_AE_ANTIBANDING_MODE =
        new Key<Integer>("android.control.aeAntibandingMode", 
        int.class);
// 调整自动曝光图像亮度的补偿值
public static final Key<Integer> CONTROL_AE_EXPOSURE_COMPENSATION =
        new Key<Integer>("android.control.aeExposureCompensation", 
        int.class);
// 自动曝光当前是否锁定
public static final Key<Boolean> CONTROL_AE_LOCK =
        new Key<Boolean>("android.control.aeLock", boolean.class);
// 自动曝光的控制模式
public static final Key<Integer> CONTROL_AE_MODE =
        new Key<Integer>("android.control.aeMode", int.class);
// 自动曝光测光序列开关
public static final Key<Integer> CONTROL_AE_PRECAPTURE_TRIGGER =
        new Key<Integer>("android.control.aePrecaptureTrigger", 
        int.class);
// 自动曝光测光区域列表
public static final 
    Key<android.hardware.camera2.params.MeteringRectangle[]> 
    CONTROL_AE_REGIONS =
        new Key<android.hardware.camera2.params.MeteringRectangle[]>(
        "android.control.aeRegions", 
        android.hardware.camera2.params.MeteringRectangle[].class);
// 自动曝光调整帧率来保持良好的曝光范围
public static final Key<android.util.Range<Integer>> 
    CONTROL_AE_TARGET_FPS_RANGE =
        new Key<android.util.Range<Integer>>(
        "android.control.aeTargetFpsRange", 
        new TypeReference<android.util.Range<Integer>>() {{ }});
// 自动对焦模式
public static final Key<Integer> CONTROL_AF_MODE =
        new Key<Integer>("android.control.afMode", int.class);
// 自动对焦计量区域列表
public static final 
    Key<android.hardware.camera2.params.MeteringRectangle[]> 
    CONTROL_AF_REGIONS =
        new Key<android.hardware.camera2.params.MeteringRectangle[]>(
        "android.control.afRegions", 
        android.hardware.camera2.params.MeteringRectangle[].class);
// 自动对焦开关
public static final Key<Integer> CONTROL_AF_TRIGGER =
        new Key<Integer>("android.control.afTrigger", int.class);
// 自动白平衡是否锁定
public static final Key<Boolean> CONTROL_AWB_LOCK =
        new Key<Boolean>("android.control.awbLock", boolean.class);
// 自动白平衡的模式
public static final Key<Integer> CONTROL_AWB_MODE =
        new Key<Integer>("android.control.awbMode", int.class);
// 自动白平衡，光源估计的测量区域列表
public static final 
    Key<android.hardware.camera2.params.MeteringRectangle[]> 
    CONTROL_AWB_REGIONS =
        new Key<android.hardware.camera2.params.MeteringRectangle[]>(
        "android.control.awbRegions", 
        android.hardware.camera2.params.MeteringRectangle[].class);
// 设置捕获图像信息时的控制意图，比如 3A 算法等
public static final Key<Integer> CONTROL_CAPTURE_INTENT =
        new Key<Integer>("android.control.captureIntent", int.class);
// 设置颜色效果模式
public static final Key<Integer> CONTROL_EFFECT_MODE =
        new Key<Integer>("android.control.effectMode", int.class);
// 是否开启 ZSL
public static final Key<Boolean> CONTROL_ENABLE_ZSL =
        new Key<Boolean>("android.control.enableZsl", boolean.class);
// 设置控制模式，手动、自动等
public static final Key<Integer> CONTROL_MODE =
        new Key<Integer>("android.control.mode", int.class);
// 设置传感器捕获数据后，灵敏度增强
public static final Key<Integer> CONTROL_POST_RAW_SENSITIVITY_BOOST =
        new Key<Integer>("android.control.postRawSensitivityBoost", 
        int.class);
// 设置场景模式
public static final Key<Integer> CONTROL_SCENE_MODE =
        new Key<Integer>("android.control.sceneMode", int.class);
// 设置录像防抖模式
public static final Key<Integer> CONTROL_VIDEO_STABILIZATION_MODE =
        new Key<Integer>("android.control.videoStabilizationMode", 
        int.class);
// 设置失真校准模式
public static final Key<Integer> DISTORTION_CORRECTION_MODE = ...;
// 设置边缘增强模式
public static final Key<Integer> EDGE_MODE =
        new Key<Integer>("android.edge.mode", int.class);
// 设置闪光灯模式，手电筒等
public static final Key<Integer> FLASH_MODE =
        new Key<Integer>("android.flash.mode", int.class);
// 设置热点校正模式
public static final Key<Integer> HOT_PIXEL_MODE =
        new Key<Integer>("android.hotPixel.mode", int.class);
// 生成图像的 GPS 元数据时，使用位置信息
public static final Key<android.location.Location> JPEG_GPS_LOCATION =
        new Key<android.location.Location>("android.jpeg.gpsLocation", 
        android.location.Location.class);
// JPEG 图像的旋转方向
public static final Key<Integer> JPEG_ORIENTATION =
        new Key<Integer>("android.jpeg.orientation", int.class);
// JPEG 图像的质量，典型值为 85-95 
public static final Key<Byte> JPEG_QUALITY =
        new Key<Byte>("android.jpeg.quality", byte.class);
// JPEG 缩略图的质量 1-100
public static final Key<Byte> JPEG_THUMBNAIL_QUALITY =
        new Key<Byte>("android.jpeg.thumbnailQuality", byte.class);
// JPEG 缩略图分辨率
public static final Key<android.util.Size> JPEG_THUMBNAIL_SIZE =
        new Key<android.util.Size>("android.jpeg.thumbnailSize", 
        android.util.Size.class);
// 镜头光圈大小
public static final Key<Float> LENS_APERTURE =
        new Key<Float>("android.lens.aperture", float.class);
// 镜头滤光片密度
public static final Key<Float> LENS_FILTER_DENSITY =
        new Key<Float>("android.lens.filterDensity", float.class);
// 镜头光学变焦焦距
public static final Key<Float> LENS_FOCAL_LENGTH =
        new Key<Float>("android.lens.focalLength", float.class);
// 镜头到最清晰焦点的距离
public static final Key<Float> LENS_FOCUS_DISTANCE =
        new Key<Float>("android.lens.focusDistance", float.class);
// 设置镜头光学防抖模式
public static final Key<Integer> LENS_OPTICAL_STABILIZATION_MODE =
        new Key<Integer>("android.lens.opticalStabilizationMode", 
        int.class);
// 设置降噪模式
public static final Key<Integer> NOISE_REDUCTION_MODE =
        new Key<Integer>("android.noiseReduction.mode", int.class);
// 重复处理前，原始帧的曝光因子
public static final Key<Float> REPROCESS_EFFECTIVE_EXPOSURE_FACTOR =
        new Key<Float>("android.reprocess.effectiveExposureFactor", 
        float.class);
// 设置裁剪区域，可用于数字变焦
public static final Key<android.graphics.Rect> SCALER_CROP_REGION =
        new Key<android.graphics.Rect>("android.scaler.cropRegion", 
        android.graphics.Rect.class);
// 传感器自动曝光时间
public static final Key<Long> SENSOR_EXPOSURE_TIME =
        new Key<Long>("android.sensor.exposureTime", long.class);
// 从帧曝光开始到下一帧曝光的间隔时间
public static final Key<Long> SENSOR_FRAME_DURATION =
        new Key<Long>("android.sensor.frameDuration", long.class);
// 传感器 ISO 感光度
public static final Key<Integer> SENSOR_SENSITIVITY =
        new Key<Integer>("android.sensor.sensitivity", int.class);
// 传感器测试模式序列数据 [R, G_even, G_odd, B]
public static final Key<int[]> SENSOR_TEST_PATTERN_DATA =
        new Key<int[]>("android.sensor.testPatternData", int[].class);
// 传感器测试模图案模式
public static final Key<Integer> SENSOR_TEST_PATTERN_MODE =
        new Key<Integer>("android.sensor.testPatternMode", int.class);
// 镜头阴影校正模式
public static final Key<Integer> SHADING_MODE =
        new Key<Integer>("android.shading.mode", int.class);
// 人脸检测模式
public static final Key<Integer> STATISTICS_FACE_DETECT_MODE =
        new Key<Integer>("android.statistics.faceDetectMode", 
        int.class);
// 热点映射模式开关
public static final Key<Boolean> STATISTICS_HOT_PIXEL_MAP_MODE =
        new Key<Boolean>("android.statistics.hotPixelMapMode", 
        boolean.class);
// 镜头阴影校正映射开关
public static final Key<Integer> STATISTICS_LENS_SHADING_MAP_MODE =
        new Key<Integer>("android.statistics.lensShadingMapMode", 
        int.class);
// 光学防抖数据模式
public static final Key<Integer> STATISTICS_OIS_DATA_MODE = ...;
// 色调映射曲线
public static final Key<android.hardware.camera2.params.TonemapCurve>
    TONEMAP_CURVE = 
    new Key<android.hardware.camera2.params.TonemapCurve>(
    "android.tonemap.curve", 
    android.hardware.camera2.params.TonemapCurve.class);
// 色调映射曲线伽马值
public static final Key<Float> TONEMAP_GAMMA =
        new Key<Float>("android.tonemap.gamma", float.class);
// 色调映射模式
public static final Key<Integer> TONEMAP_MODE =
        new Key<Integer>("android.tonemap.mode", int.class);
// 色调映射预设曲线
public static final Key<Integer> TONEMAP_PRESET_CURVE =
        new Key<Integer>("android.tonemap.presetCurve", int.class);

API 方法

CaptureRequest 中 API 简介： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
public final class CaptureRequest 
    extends CameraMetadata<CaptureRequest.Key<?>>
    implements Parcelable {

    private final HashSet<Surface> mSurfaceSet;
    private final CameraMetadataNative mSettings;
    private boolean mIsReprocess;
    private boolean mIsPartOfCHSRequestList = false;
    private int mReprocessableSessionId;
    private Object mUserTag;

    ...
    // 获取键对应的值
    public <T> T get(Key<T> key) {
        return mSettings.get(key);
    }
    // 获取所有的键值列表
    public List<Key<?>> getKeys() {
        return super.getKeys();
    }
    // 当前请求的 tag 信息
    public Object getTag() {
        return mUserTag;
    }
    // 是否是在重新处理请求
    public boolean isReprocess() {
        return mIsReprocess;
    }
    ...
}

Builder 内部类

CaptureRequest.Builder 内部类，建造者模式，用于创建 CaptureRequest 实例。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
public final static class Builder {

    private final CaptureRequest mRequest;
    public Builder(CameraMetadataNative template, boolean reprocess,
            int reprocessableSessionId) {
        mRequest = new CaptureRequest(template, reprocess, 
            reprocessableSessionId);
    }
    // 添加输出目标
    public void addTarget(@NonNull Surface outputTarget) {
        mRequest.mSurfaceSet.add(outputTarget);
    }
    public void removeTarget(@NonNull Surface outputTarget) {
        mRequest.mSurfaceSet.remove(outputTarget);
    }
    // 设置键值对
    public <T> void set(@NonNull Key<T> key, T value) {
        mRequest.mSettings.set(key, value);
    }
    public <T> T get(Key<T> key) {
        return mRequest.mSettings.get(key);
    }
    public void setTag(@Nullable Object tag) {
        mRequest.mUserTag = tag;
    }
    public CaptureRequest build() {
        return new CaptureRequest(mRequest);
    }
    public boolean isEmpty() {
        return mRequest.mSettings.isEmpty();
    }
    public T getPhysicalCameraKey (Key<T> key, 
                String physicalCameraId){...}
    public CaptureRequest.Builder setPhysicalCameraKey (Key<T> key, 
                T value,  String physicalCameraId){...}
    ...
}

Key 内部类

CaptureRequest.Key<T> 内部类，用于设置参数时的 Key 值。 

1
2
3
4
5
6
7
8
9
10
11
12
13
public final static class Key<T> {
    private final CameraMetadataNative.Key<T> mKey;

    public Key(String name, Class<T> type, long vendorId) {
        mKey = new CameraMetadataNative.Key<T>(name, type, vendorId);
    }
    ...
    // 获取键值名称
    public String getName() {
        return mKey.getName();
    }
    ...
}

CaptureResult

CaptureResult 继承了 CameraMetadata ；表示从 CameraDevice 获取到数据的结果子集；包含捕获硬件（传感器，镜头，闪存），控制算法和输出缓冲区的最终配置等的子集；CaptureResult 对象实例是不可变的。

Key 常量

通过对比代码 CaptureRequest, CaptureResult 两份代码大部分都相同，特别是 Key 常量的定义（都是在 system/media/camera/docs 中通过脚本生成），CaptureResult 仅仅是新增了几个常量： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
...
// 自动曝光算法当前状态：搜索，锁定，转换等等
public static final Key<Integer> CONTROL_AE_STATE =
        new Key<Integer>("android.control.aeState", int.class);
// 自动对焦算法当前状态：激活，扫描，锁定等等
public static final Key<Integer> CONTROL_AF_STATE =
        new Key<Integer>("android.control.afState", int.class);
// 白平衡算法当前状态：激活，搜索，转换，锁定等
public static final Key<Integer> CONTROL_AWB_STATE =
        new Key<Integer>("android.control.awbState", int.class);
// 闪光灯当前状态：充电、闪光、装备好等
public static final Key<Integer> FLASH_STATE =
        new Key<Integer>("android.flash.state", int.class);
// 景深距离范围
public static final Key<android.util.Pair<Float,Float>> 
    LENS_FOCUS_RANGE = new Key<android.util.Pair<Float,Float>>(
    "android.lens.focusRange", 
    new TypeReference<android.util.Pair<Float,Float>>() {{ }});
// 镜头当前状态：移动、平稳
public static final Key<Integer> LENS_STATE =
        new Key<Integer>("android.lens.state", int.class);
// 镜头坐标体系的方向
public static final Key<float[]> LENS_POSE_ROTATION =
        new Key<float[]>("android.lens.poseRotation", float[].class);
// 镜头光学中心位置
public static final Key<float[]> LENS_POSE_TRANSLATION =
    new Key<float[]>("android.lens.poseTranslation", float[].class);
// 镜头固有的校准参数
public static final Key<float[]> LENS_INTRINSIC_CALIBRATION =
        new Key<float[]>("android.lens.intrinsicCalibration", 
        float[].class);
// 降级，使用 LENS_DISTORTION 代替
public static final Key<float[]> LENS_RADIAL_DISTORTION =
    new Key<float[]>("android.lens.radialDistortion", float[].class);
// 请求的管道深度
public static final Key<Byte> REQUEST_PIPELINE_DEPTH =
        new Key<Byte>("android.request.pipelineDepth", byte.class);
// 返回传感器时间戳
public static final Key<Long> SENSOR_TIMESTAMP =
        new Key<Long>("android.sensor.timestamp", long.class);
// 传感器色彩空间中估计的中性色
public static final Key<Rational[]> SENSOR_NEUTRAL_COLOR_POINT =
        new Key<Rational[]>("android.sensor.neutralColorPoint", 
        Rational[].class);
// 每个 CFA 马赛克通道的噪声模型系数
public static final Key<android.util.Pair<Double,Double>[]> 
    SENSOR_NOISE_PROFILE = new Key<android.util.Pair<Double,Double>[]>(
    "android.sensor.noiseProfile", 
    new TypeReference<android.util.Pair<Double,Double>[]>() {{ }});
// Bayer 阵列中绿色通道最差分割的估计值
public static final Key<Float> SENSOR_GREEN_SPLIT =
        new Key<Float>("android.sensor.greenSplit", float.class);
// 第一行到最后一行曝光的时间偏差
public static final Key<Long> SENSOR_ROLLING_SHUTTER_SKEW =
        new Key<Long>("android.sensor.rollingShutterSkew", long.class);
// 每个滤色器排列 CFA 马赛克通道的每帧动态黑电平偏移
public static final Key<float[]> SENSOR_DYNAMIC_BLACK_LEVEL =
    new Key<float[]>("android.sensor.dynamicBlackLevel", float[].class);
// 每个滤色器排列 CFA 马赛克通道的每帧动态白电平偏移
public static final Key<Integer> SENSOR_DYNAMIC_WHITE_LEVEL =
        new Key<Integer>("android.sensor.dynamicWhiteLevel", int.class);
//
public static final Key<int[]> STATISTICS_FACE_IDS =
        new Key<int[]>("android.statistics.faceIds", int[].class);
// 检测到的人脸列表
public static final Key<android.hardware.camera2.params.Face[]> 
    STATISTICS_FACES = new Key<android.hardware.camera2.params.Face[]>(
    "android.statistics.faces", 
    android.hardware.camera2.params.Face[].class);
// 镜头阴影校正映射图
public static final Key<android.hardware.camera2.params.LensShadingMap> 
    STATISTICS_LENS_SHADING_CORRECTION_MAP =
        new Key<android.hardware.camera2.params.LensShadingMap>(
        "android.statistics.lensShadingCorrectionMap", 
        android.hardware.camera2.params.LensShadingMap.class);
// 传感器估计的灯源照明频率
public static final Key<Integer> STATISTICS_SCENE_FLICKER =
        new Key<Integer>("android.statistics.sceneFlicker", int.class);
// 热点映射区域
public static final Key<android.graphics.Point[]> 
    STATISTICS_HOT_PIXEL_MAP = new Key<android.graphics.Point[]>(
    "android.statistics.hotPixelMap", android.graphics.Point[].class);

API 方法

CaptureResult 中 API 简介： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {

    private final CameraMetadataNative mResults;
    private final CaptureRequest mRequest;
    private final int mSequenceId;
    private final long mFrameNumber;

    public CaptureResult(CameraMetadataNative results, 
        CaptureRequest parent, CaptureResultExtras extras) {
        ...
        mResults = CameraMetadataNative.move(results);
        if (mResults.isEmpty()) {
            throw new AssertionError("Results must not be empty");
        }
        setNativeInstance(mResults);
        mRequest = parent;
        mSequenceId = extras.getRequestId();
        mFrameNumber = extras.getFrameNumber();
    }

    // 获取键对应的值
    public <T> T get(Key<T> key) {
        T value = mResults.get(key);
        return value;
    }
    // 获取键列表
    public List<Key<?>> getKeys() {
        return super.getKeys();
    }
    // 获取当前结果的请求 CaptureRequest
    public CaptureRequest getRequest() {
        return mRequest;
    }
    // 获取当前结果的帧号
    public long getFrameNumber() {
        return mFrameNumber;
    }
    // 获取序列号；该序列号为 CameraCaptureSession.capture 的返回值
    public int getSequenceId() {
        return mSequenceId;
    }
    ...
}

CaptureResult.Key 和 CaptureRequest.Key 代码几乎一样，主要是提供一个 Key 封装。

TotalCaptureResult

TotalCaptureResult 继承了 CaptureResult ；表示传感器捕获的单个图像组成的结果集合。在 CaptureCallback.onCaptureCompleted 回调后，会返回 TotalCaptureResult 总的捕获结果集合。部分源码如下： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public final class TotalCaptureResult extends CaptureResult {

    private final List<CaptureResult> mPartialResults;
    private final int mSessionId;
    ...
    // 获取结果集
    public List<CaptureResult> getPartialResults() {
        return Collections.unmodifiableList(mPartialResults);
    }

    // 获取当前结果集的会话 ID
    public int getSessionId() {
        return mSessionId;
    }
}

DngCreator

DngCreator 用于将传感器捕获到的原始图像数据转换为 DNG 格式图片，图片相关处理的方法都是 native 的。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public final class DngCreator implements AutoCloseable {
    // 缩略图最大尺寸
    public static final int MAX_THUMBNAIL_DIMENSION = 256;
    // 根据配置文件 CameraCharacteristics 和捕获结果 CaptureResult 
    // 生成 DNG 图片
    public DngCreator (CameraCharacteristics characteristics, 
                CaptureResult metadata){...}
                
    public void close(){...}
    // 设置图片描述
    public DngCreator setDescription(String description){...}
    // 设置位置信息
    public DngCreator setLocation(Location location){...}
    // 设置图片旋转方向
    public DngCreator setOrientation(int orientation){...}
    // 创建缩略图
    public DngCreator setThumbnail(Image pixels){...}
    public DngCreator setThumbnail(Bitmap pixels){...}
    // 将原始像素中元数据写入 DNG 图片
    public void writeByteBuffer (OutputStream dngOutput, 
        Size size, ByteBuffer pixels, long offset){...}
    public void writeImage (OutputStream dngOutput, Image pixels){...}
    public void writeInputStream (OutputStream dngOutput, 
        Size size, InputStream pixels, long offset){...}
}

示例

TextureView 输出显示

通过 TextureView 来显示捕获的数据；需要监听 TextureView.SurfaceTextureListener ，当输出 onSurfaceTextureAvailable 可用时，才能向 CameraDevice 请求数据输出。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
private TextureView mTextureView;
private Surface mTextureSurface;
protected void onResume() {
    super.onResume();
    if (mTextureView.isAvailable()){
        openCamera();
    } else {
        mTextureView.setSurfaceTextureListener(mSurfaceTextureListener);
    }
}

private TextureView.SurfaceTextureListener mSurfaceTextureListener = 
    new TextureView.SurfaceTextureListener() {
    @Override
    public void onSurfaceTextureAvailable(SurfaceTexture surface, 
        int width, int height) {
        openCamera();
    }

    @Override
    public void onSurfaceTextureSizeChanged(SurfaceTexture surface, 
        int width, int height) {}

    @Override
    public boolean onSurfaceTextureDestroyed(SurfaceTexture surface) {
        return true;
    }

    @Override
    public void onSurfaceTextureUpdated(SurfaceTexture surface) {}
};

获取 CameraManager

1
mCameraManager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);

获取后置摄像头 ID 及支持级别

通过 CameraCharacteristics 了解设备的属性。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
for (String cameraId : mCameraManager.getCameraIdList()) {
    CameraCharacteristics cameraCharacteristics = 
        mCameraManager.getCameraCharacteristics(cameraId);
    // support LEVEL
    Integer level = cameraCharacteristics.get(
        CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
    Log.d(TAG, "preview: cameraId = " + cameraId + ", level = " + level);
    Integer facing = cameraCharacteristics.get(
        CameraCharacteristics.LENS_FACING);
    // rear camera
    if (facing != null && facing==CameraCharacteristics.LENS_FACING_BACK){
        mCameraId = cameraId;
    }
}

打开 CameraDevice 并设置状态监听

打开 CameraDevice 时设置状态监听；在设备正确打开后，在 CameraDevice.StateCallback.onOpened 中创建 CameraCaptureSession 会话。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
CameraDevice.StateCallback mCameraDeviceStateCallback = 
    new CameraDevice.StateCallback() {
    @Override
    public void onOpened(@NonNull CameraDevice camera) {
        mCameraDevice = camera;
        // 创建会话
        createCameraCaptureSession();
    }

    @Override
    public void onDisconnected(@NonNull CameraDevice camera) {
        camera.close();
        mCameraDevice = null;
    }

    @Override
    public void onError(@NonNull CameraDevice camera, int error) {
        camera.close();
        mCameraDevice = null;
        Log.e(TAG, "onError: error = " + error);
    }
};

try {
    mCameraManager.openCamera(mCameraId, mCameraDeviceStateCallback, 
        mBackHandler);
} catch (CameraAccessException e) {
    e.printStackTrace();
}

初始化输出 Surface

本示例中有两个 Surface ：

  • TextureView 对应 Surface ：预览时用于实时输出
  • ImageReader 对应 Surface ：拍照时用于保存图片 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
SurfaceTexture texture = mTextureView.getSurfaceTexture();
texture.setDefaultBufferSize(WIDTH, HEIGHT);
mTextureSurface = new Surface(texture);

mImageReader = ImageReader.newInstance(WIDTH, HEIGHT, ImageFormat.JPEG, 2);
// 设置监听事件，当 ImageReader 中可以读取图片时保存文件
mImageReader.setOnImageAvailableListener(
    new ImageReader.OnImageAvailableListener() {
    @Override
    public void onImageAvailable(ImageReader reader) {
        File file = createImageFile();
        if (null != file) {
            mBackHandler.post(new ImageSaveRunnable(
                reader.acquireNextImage(), file));
        } else {
            Toast.makeText(CustomCamera2Activity.this, 
                "create File error!", Toast.LENGTH_SHORT).show();
        }
    }
}, mBackHandler);

创建会话 CameraCaptureSession

通过 mCameraDevice.createCaptureSession 创建会话成功后，在回调方法 CameraCaptureSession.StateCallback.onConfigured 中获取会话 mCameraCaptureSession ，后续所有的 CaptureRequest 都是通过该会话发起。
可以在创建会话成功时，同步开启预览请求 preview 。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
private void createCameraCaptureSession() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
        try {
            mCameraDevice.createCaptureSession(Arrays.asList(
                mTextureSurface, mImageReader.getSurface()),
                new CameraCaptureSession.StateCallback() {
                @Override
                public void onConfigured(
                    @NonNull CameraCaptureSession session) {
                    Log.d(TAG, "onConfigured: ");
                    mCameraCaptureSession = session;
                    // 开启预览请求
                    preview();
                }

                @Override
                public void onConfigureFailed(
                    @NonNull CameraCaptureSession session) {
                    Log.e(TAG, "onConfigureFailed: ");
                }
            }, null);
        } catch (CameraAccessException e) {
            e.printStackTrace();
        }
    }
}

发出预览请求 CaptureRequest

预览请求为 CameraDevice.TEMPLATE_PREVIEW ，设置输出为 mTextureSurface ，当捕获到预览数据时，会反复响应 CameraCaptureSession.CaptureCallback ： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
private void preview(){
    try {
        CaptureRequest.Builder previewRequestBuilder = 
          mCameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
        previewRequestBuilder.addTarget(mTextureSurface);
        CameraCaptureSession.CaptureCallback captureCallback = 
            new CameraCaptureSession.CaptureCallback() {
            @Override
            public void onCaptureCompleted(
                @NonNull CameraCaptureSession session, 
                @NonNull CaptureRequest request, 
                @NonNull TotalCaptureResult result) {
                //Log.d(TAG, "preview, onCaptureCompleted: ");
            }
        };
        mCameraCaptureSession.setRepeatingRequest(
            previewRequestBuilder.build(), captureCallback, mBackHandler);
    } catch (CameraAccessException e) {
        e.printStackTrace();
    }
}

发出拍照请求 CaptureRequest

拍照请求为 CameraDevice.TEMPLATE_STILL_CAPTURE ，设置输出为 mImageReader.getSurface() ，当存在有效数据时直接触发 ImageReader.OnImageAvailableListener 。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
private void takePicture(){
    //mPreviewRequestBuilder.set(CaptureRequest.CONTROL_AF_TRIGGER,
    //CameraMetadata.CONTROL_AF_TRIGGER_START);
    try {
        CaptureRequest.Builder captureRequestBuild = mCameraDevice
            .createCaptureRequest(CameraDevice.TEMPLATE_STILL_CAPTURE);
        captureRequestBuild.addTarget(mImageReader.getSurface());
        captureRequestBuild.set(CaptureRequest.CONTROL_AF_MODE, 
            CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);
        // 配置图片方向
        captureRequestBuild.set(CaptureRequest.JPEG_ORIENTATION, 
            mImageOrientation);
        CameraCaptureSession.CaptureCallback captureCallback = 
            new CameraCaptureSession.CaptureCallback() {
            @Override
            public void onCaptureCompleted(
                @NonNull CameraCaptureSession session, 
                @NonNull CaptureRequest request, 
                @NonNull TotalCaptureResult result) {
                Log.d(TAG, "takePicture, onCaptureCompleted: ");
                Toast.makeText(CustomCamera2Activity.this, 
                    "Take Picture, OK!", Toast.LENGTH_SHORT).show();
            }
        };
        mCameraCaptureSession.stopRepeating();
        mCameraCaptureSession.abortCaptures();
        mCameraCaptureSession.capture(captureRequestBuild.build(), 
            captureCallback, mBackHandler);
    } catch (CameraAccessException e) {
        e.printStackTrace();
    }
}

这里需要注意的是，拍照前需要根据传感器安装的方向和屏幕旋转角度来配置图片保存方向，否则可能会出现横竖混淆的照片：

0109-android-camera-3-api-camera-pic-ratation.png

  • 获取 Camera sensor 安装方向 
    1
    2
    mSensorOrientation = 
        characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION);
  • 获取当前屏幕的旋转角度 
    1
    2
    int displayRotation = activity.getWindowManager()
        .getDefaultDisplay().getRotation();

如果安装方向和旋转角度一致（比如都是 90° ），则不需要补偿；否则需要按照顺时针方向设置旋转（即屏幕顺时针朝着 sensor 方向旋转角度），参考 Camera.java 中 setDisplayOrientation 方法的代码注释，计算公式如下： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// 获取当前摄像头是前置还是后置
Integer facing = 
    cameraCharacteristics.get(CameraCharacteristics.LENS_FACING);

// 获取当前 sensor 安装方向
Integer mSensorOrientation = 
    characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION);

// 获取当前屏幕旋转
int rotation = activity.getWindowManager()
    .getDefaultDisplay().getRotation();
// 将旋转转换成角度
int degrees = 0;
switch (rotation) {
    case Surface.ROTATION_0: degrees = 0; break;
    case Surface.ROTATION_90: degrees = 90; break;
    case Surface.ROTATION_180: degrees = 180; break;
    case Surface.ROTATION_270: degrees = 270; break;
}

//int result;
// 前后摄计算公式不一样
if (facing == CameraCharacteristics.LENS_FACING_FRONT) {
    mImageOrientation = (mSensorOrientation + degrees) % 360;
    // compensate the mirror
    mImageOrientation = (360 - mImageOrientation) % 360;  
} else {  // back-facing
    mImageOrientation = (mSensorOrientation - degrees + 360) % 360;
}

我们以后摄为例，屏幕旋转方向和 Camera sensor 安装方向可能出现的如下几种组合：

0109-android-camera-3-api-camera-orientation.png

补偿角度的计算结果按照公式如下，先以 Sensor 方向不变： 

1
2
3
4
5
6
7
8
9
0:  (0  - 0   + 360) % 360  = 0     180: (180 - 0   + 360) % 360 = 180
0:  (0  - 90  + 360) % 360  = 270   180: (180 - 90  + 360) % 360 = 90
0:  (0  - 180 + 360) % 360  = 180   180: (180 - 180 + 360) % 360 = 0
0:  (0  - 270 + 360) % 360  = 90    180: (180 - 270 + 360) % 360 = 270
                              
90: (90 - 0   + 360) % 360 = 90     270: (270 - 0   + 360) % 360 = 270
90: (90 - 90  + 360) % 360 = 0      270: (270 - 90  + 360) % 360 = 180
90: (90 - 180 + 360) % 360 = 270    270: (270 - 180 + 360) % 360 = 90
90: (90 - 270 + 360) % 360 = 180    270: (270 - 270 + 360) % 360 = 0

当 Sensor 安装方向为 0 时，如果屏幕旋转角度也为 0 ，则两个是同方向的，不需要补偿（补偿为 0）；当 Sensor 安装方向为 180 时，如果屏幕旋转角度为 90 （向右横屏），则需要补偿 90 （即当前屏幕方向朝 Sensor 方向旋转 90 度）。

小结

  • 需要等待 TextureView 可用后，才能开启预览
  • 图片保存时，需要设置方向，否则可能会出现旋转角度

序列图

0109-android-camera-3-api-class-flow.png

小结

CameraMetadata 及其子类的 Key 值

CameraMetadata, CaptureRequest, CaptureResult, CameraCharacteristics 的几个常量都是 system/media/camera/docs 中脚本自动生成的，在 metadata_properties.xml 中定义，解析时的对应关系为：

1
2
3
4
5
6
7
8
## Static properties only
##${single_kind_keys('CameraCharacteristicsKeys', 'static')}
##
## Controls properties only
##${single_kind_keys('CaptureRequestKeys', 'controls')}
##
## Dynamic properties only
##${single_kind_keys('CaptureResultKeys', 'dynamic')}

CameraCaptureSession 的两个重要方法

  • setRepeatingRequest ：用于预览
  • capture ：用于拍照

参考文档