AndroidCamera 4 CaptureRequest和CaptureResult

CaptureRequest

捕获请求，可以为不同的场景(预览 拍照)创建不同的请求，配置不同的属性，如：预览分辨率、预览目标、对焦模式、曝光模式等。

• 包含捕获硬件（sensor、镜头、闪光灯等）、管道、控制算法、输出buffer，发送图像到的目标的配置。

• 通过 CameraDevice 对象的 createCaptureRequest() 方法得到一个 CaptureRequest.Builder 对象，基本配置都是通过该构造者来配置；最后通过 CaptureRequest.Builder 对象的 build() 方法便可得到CaptureRequest 实例。

• CaptureRequest 通过CameraCaptureSession的capture 或setRepeatingRequest方法，发送给camera device 捕获图像。

• CaptureRequest 继承了Parcelable 接口，支持序列化。

内部类

CaptureRequest.Builder

典型的建造者模式，是 CaptureRequest 的构建者。

使用CameraDevice.createCaptureRequest(int)方法获取一个 CaptureRequest.Builder对象。其中的 int 取值为：(定义在CameraDevice中)

• TEMPLATE_PREVIEW ： 用于创建一个相机预览请求。相机会优先保证高帧率而不是高画质。适用于所有相机设备。
• TEMPLATE_STILL_CAPTURE ： 用于创建一个拍照请求。相机会优先保证高画质而不是高帧率。适用于所有相机设备。
• TEMPLATE_RECORD ： 用于创建一个录像请求。相机会使用标准帧率，并设置录像级别的画质。适用于所有相机设备。
• TEMPLATE_VIDEO_SNAPSHOT ： 用于创建一个录像时拍照的请求。相机会尽可能的保证照片质量的同时不破坏正在录制的视频质量。适用于硬件支持级别高于 LEGACY 的相机设备。
• EMPLATE_ZERO_SHUTTER_LAG ： 用于创建一个零延迟拍照的请求。相机会尽可能的保证照片质量的同时不损失预览图像的帧率，3A（自动曝光、自动聚焦、自动白平衡）都为 auto 模式。只适用于支持PRIVATE_REPROCESSING 和 YUV_REPROCESSING 的相机设备。
• TEMPLATE_MANUAL ： 用于创建一个手动控制相机参数的请求。相机所有自动控制将被禁用，后期处理参数为预览质量，手动控制参数被设置为合适的默认值，需要用户自己根据需求来调整各参数。适用于支持MANUAL_SENSOR 的相机设备。

支持的方法

1、addTarget

添加一个请求的输出surface，注意这个surface必须包含在 CameraDevice.createCaptureSession() 方法设置的输出surface集合中

2、removeTarget

移除指定的输出surface

3、CaptureRequest build()

使用当前配置构建一个CaptureRequest对象

4、T get(Key key)

CaptureRequest.Builder 的属性字段查询。这些字段定义了相机的具体配置。

5、set(Key key, T value)

设置指定key的值

6、void setTag(Object tag)

为该请求设置一个标签

支持的方法

1、T get(Key key)

和 CaptureRequest.Builder 中的 get 方法效果是一样的。

2、List<Key<?>> getKeys()

返回映射中包含的所有 Key 的列表。

3、Object getTag()

检索此请求的标签，如果有的话。对应 CaptureRequest.Builder 中的 setTag() 方法。

4、boolean isReprocess()

判断这是否是一个再处理的请求。

实例代码

private void captureStillPicture() {
    try {
        final Activity activity = getActivity();
        if (null == activity || null == mCameraDevice) {
            return;
        }
        // 1. 先拿到一个 CaptureRequest.Builder 对象
        final CaptureRequest.Builder captureBuilder =
                mCameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_STILL_CAPTURE);
        captureBuilder.addTarget(mImageReader.getSurface());
        // 2. 通过 CaptureRequest.Builder 对象设置一些捕捉请求的配置
        captureBuilder.set(CaptureRequest.CONTROL_AF_MODE,
                CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);
        setAutoFlash(captureBuilder);
        int rotation = activity.getWindowManager().getDefaultDisplay().getRotation();
        captureBuilder.set(CaptureRequest.JPEG_ORIENTATION, getOrientation(rotation));
        CameraCaptureSession.CaptureCallback CaptureCallback
                = new CameraCaptureSession.CaptureCallback() {

            @Override
            public void onCaptureCompleted(@NonNull CameraCaptureSession session,
                                           @NonNull CaptureRequest request,
                                           @NonNull TotalCaptureResult result) {
                // start preview
            }
        };
        mCaptureSession.stopRepeating();
        mCaptureSession.abortCaptures();
        // 3. 通过 CaptureRequest.Builder 对象的 `build()` 方法构建一个 CaptureRequest 对象
        mCaptureSession.capture(captureBuilder.build(), CaptureCallback, null);
    } catch (CameraAccessException e) {
        e.printStackTrace();
    }
}

CaptureResult

CaptureResult 表示捕捉的结果，是从图像传感器捕获单个图像的结果的子集。包含捕获硬件(传感器、镜头、闪光灯)、处理管道、控制算法和输出缓冲区的最终配置的子集。

捕获结果由camera在对CaptureRequest进行处理后产生。还可以对捕获结果查询为捕获请求列出的所有属性，以确定捕获使用的最终值。结果还包括捕获过程中相机设备状态的附加元数据。
CaptureResult 对象也是不可变的。常使用的子类是 TotalCaptureResult。

内部类

只有一个 CaptureResult.Key<T> 的内部类，用于 CaptureResult 类的字段查找。

类比于 CameraCharacteristics.Key 和 CaptureRequest.Key。

支持的方法

1、T get(Key key)

获取 CaptureResult 中指定 key 的值，key 为 CaptureResult 类中的那些静态常量。

2、long getFrameNumber()

获取该结果申请的帧的id。

3、List<Key<?>> getKeys()

返回映射中包含的所有 Key 的列表。

4、CaptureRequest getRequest()

返回这个结果对应的 CaptureRequest 对象。

5、int getSequenceId()

获取发生故障时的序列ID。

扩展阅读

源码中system/media/camera/docs 存放了上文 提到的camera device key值及对应属性的解释相关文档。