Android Camera API作用及使用指南_Android

一 streamconfigurationmap

1. streamconfigurationmap 的作用

streamconfigurationmap 是 android camera2 api 中的一个核心类，用于描述相机设备支持的输出流配置，包含以下信息：

支持的格式与分辨率：例如 yuv_420_888、jpeg、raw 等格式及其对应的分辨率列表。
输入/输出流组合规则：例如哪些格式可以同时用于预览、拍照或录像。
硬件能力限制：例如是否支持硬件级图像处理（如 yuv 重处理）、动态范围模式（hdr）等。
帧率与时长限制：如某些分辨率下支持的最小/最大帧率，或视频录制的最大时长。

应用通过 cameracharacteristics 获取 streamconfigurationmap，并基于此配置合理的 capturesession（例如选择预览和拍照的兼容分辨率）。

2. 与 cameraprovider 交互关系

(1) 数据来源

cameraprovider 提供原始数据：

camera hal 实现（如 android.hardware.camera.provider@2.4）通过 getcameracharacteristics() 方法向框架上报硬件能力，包括支持的流配置（格式、分辨率、动态范围等）。

框架封装为 streamconfigurationmap：

框架层（如 cameraservice）解析 hal 返回的元数据，将其转换为应用可直接使用的 streamconfigurationmap。

(2) 配置流程示例

应用请求相机能力：
- 应用调用 cameramanager.getcameracharacteristics(cameraid)。
框架查询 hal：
- cameraservice 通过 cameraprovider 的 hal 接口获取该相机的元数据。
hal 返回底层配置：
- cameraprovider 从硬件或板级配置文件（如 cam_board.xml）中读取支持的流配置，传递给框架。
构建 streamconfigurationmap：
- 框架将原始数据（如 scaler_available_stream_configurations）封装为 streamconfigurationmap 对象。
应用使用配置：
- 应用根据 streamconfigurationmap 选择兼容的流组合（例如同时支持 1080p@30fps 预览和 12mp 拍照）。

(3) 关键数据结构对应

hal 元数据字段（如 `android.scaler`）	streamconfigurationmap 方法	作用
`scaler_available_stream_configurations`	`getoutputsizes(int format)`	获取某格式支持的分辨率列表
`scaler_available_min_frame_durations`	`getoutputminframeduration(int format)`	获取某分辨率下最小帧间隔（决定最大帧率）
`request_available_capabilities`	`isoutputsupportedfor(int usecase)`	检查是否支持特定用例（如 zsl）

3. 实际示例

假设一个相机设备支持以下配置（通过 cameraprovider 上报）：

yuv_420_888: 1920x1080@30fps, 1280x720@60fps
jpeg: 4000x3000@10fps

则 streamconfigurationmap 会生成如下信息：

// 获取 yuv 格式支持的分辨率
size[] yuvsizes = streamconfigmap.getoutputsizes(imageformat.yuv_420_888);
// 结果: [1920x1080, 1280x720]
// 检查是否支持硬件级 yuv 重处理
boolean isreprocesssupported = streamconfigmap.isoutputsupportedfor(
    camerametadata.request_available_capabilities_yuv_reprocessing);

streamconfigurationmap 是应用层获取相机输出能力的接口，而 cameraprovider 是底层硬件能力的提供者。前者依赖后者上报的元数据，二者共同实现 硬件能力到应用接口的透明映射，是 android camera 系统分层架构的核心设计之一。

在 android 相机系统（camera2 api）中，outputconfiguration 和 streamconfigurationmap 是与相机输出流配置相关的两个关键类，它们在相机工作流程中扮演不同角色。以下是它们的详细介绍及关系分析：

二. outputconfiguration

1 作用

作用：

outputconfiguration 是 android 5.0（api 21）引入的类，用于定义单个相机输出流的配置。它的核心功能包括：

封装输出目标（如 surface 或 surfaceview）。
配置物理相机（在多摄像头设备中指定物理传感器）。
管理共享输出流（允许多个 surface 共享同一输出流）。
使用场景：
当创建 cameracapturesession 时，需传入一组 outputconfiguration 对象，描述所有输出流。
关键方法：
- addsurface(surface surface)：添加共享的 surface。
- setphysicalcameraid(string id)：指定物理相机（用于双摄/多摄设备）。
- getsurfaces()：获取关联的 surface 列表。
示例：

// 创建 imagereader 并获取 surface
imagereader imagereader = imagereader.newinstance(width, height, format, maximages);
surface imagesurface = imagereader.getsurface();
// 创建 outputconfiguration
outputconfiguration outputconfig = new outputconfiguration(imagesurface);
// 可选：配置共享 surface 或物理相机
// outputconfig.addsurface(anothersurface);
// outputconfig.setphysicalcameraid("2");
// 创建 cameracapturesession
list<outputconfiguration> outputconfigs = new arraylist<>();
outputconfigs.add(outputconfig);
cameradevice.createcapturesessionbyoutputconfigurations(outputconfigs, callback, handler);

2. 与 streamconfigurationmap 关系

协作流程：

step 1：通过 streamconfigurationmap 查询设备支持的输出参数（格式、分辨率等）。
step 2：根据合法参数创建输出目标（如 imagereader 或 surfaceview）。
step 3：将输出目标封装到 outputconfiguration，用于创建 cameracapturesession。

依赖关系：

outputconfiguration 的参数（如格式、分辨率）必须符合 streamconfigurationmap 的约束，否则会话创建会失败。
streamconfigurationmap 提供理论支持，outputconfiguration 负责实际配置。

扩展功能：

outputconfiguration 支持高级功能（如多摄像头共享输出流），而 streamconfigurationmap 仅描述硬件能力。
在 android 10（api 29）后，outputconfiguration 新增对动态分辨率、物理摄像头绑定的支持。

3. 常见问题

q1: 为什么需要同时使用两者？
a: streamconfigurationmap是相机设备的“能力说明书”，告诉开发者硬件支持哪些输出配置。outputconfiguration是实际构建输出流的“施工图”，将合法的参数绑定到具体的surface`。

二者配合确保相机输出流的正确性和高效性

q2: 如何避免 invalidsurfaceexception？
a: 确保 outputconfiguration 的 surface 参数（格式、分辨率）在 streamconfigurationmap 的合法范围内。

q3: 多摄像头场景如何处理？
a: 使用 outputconfiguration.setphysicalcameraid() 指定物理摄像头，并通过 streamconfigurationmap 检查该摄像头是否支持目标参数。

总结 streamconfigurationmap 是相机设备的“能力说明书”，告诉开发者硬件支持哪些输出配置。outputconfiguration 是实际构建输出流的“施工图”，将合法的参数绑定到具体的 surface。二者配合确保相机输出流的正确性和高效性，是 camera2 api 中不可或缺的组件。

在 android camera2 api 中，cameracapturesession 是管理相机数据流和捕获请求的核心组件。它与 outputconfiguration 密切相关，共同决定了相机的输出目标（如预览、拍照、录像等）的配置和运行机制。以下是详细解释及其与 outputconfiguration 的关系：

三 cameracapturesession

1. 作用

cameracapturesession 是相机设备（cameradevice）与输出目标（surface）之间的桥梁，负责：

管理输出流：绑定多个 surface（如预览的 surfaceview、拍照的 imagereader），并确保数据正确传输到这些目标。

提交捕获请求：通过 capture() 或 setrepeatingrequest() 发送请求（capturerequest），控制相机的行为（如自动对焦、曝光、帧率等）。

处理异步事件：监听相机状态（如对焦完成、帧捕获完成）并回调给应用。

2 生命周期

创建：通过 cameradevice.createcapturesession() 或 createcapturesessionbyoutputconfigurations() 创建。
活动状态：可提交捕获请求，相机数据流向绑定的 surface。
关闭：调用 close() 释放资源，不可再发送请求。

3.创建 cameracapturesession

创建会话时，需要指定一组输出目标（surface 或 outputconfiguration）。两种方法：

传统方式（基于 surface 列表）：

cameradevice.createcapturesession(
    list<surface> outputs,   // 直接传递 surface 列表
    cameracapturesession.statecallback callback, 
    handler handler
);

适用于简单场景，但灵活性有限（例如不支持多摄像头或动态分辨率）。

基于 outputconfiguration 的方式（api 21+，扩展功能在后续版本增强）：

cameradevice.createcapturesessionbyoutputconfigurations(
    list<outputconfiguration> outputconfigurations,  // 封装了 surface 的高级配置
    cameracapturesession.statecallback callback,
    handler handler
);

支持更复杂的配置（如共享流、物理摄像头绑定、动态分辨率等）。

4. 与 outputconfiguration 的关系

(1) outputconfiguration 是会话的输入

功能：outputconfiguration 封装了一个或多个 surface 的配置信息，用于定义输出流的特性：
- 单个或共享的 surface：通过 addsurface() 添加多个 surface，共享同一数据流（例如预览和录像共享同一帧数据）。
- 物理摄像头绑定：在双摄/多摄设备中，通过 setphysicalcameraid() 指定输出流来自哪个物理摄像头。
- 动态分辨率（api 23+）：允许在会话运行时动态调整分辨率（需硬件支持）。
优势：相比直接传递 surface 列表，outputconfiguration 提供了更细粒度的控制能力。

(2) 创建会话的流程

查询设备支持：通过 streamconfigurationmap 确认相机支持的格式和分辨率。
创建输出目标：根据合法参数创建 surface（如 imagereader、surfaceview）。
封装为 outputconfiguration：将 surface 及其附加配置（如物理摄像头）封装到 outputconfiguration。
创建会话：调用 createcapturesessionbyoutputconfigurations()，传入 outputconfiguration 列表。

(3) 关键约束

不可变性：一旦 cameracapturesession 创建成功，其绑定的 outputconfiguration 不可修改（如新增或移除 surface）。若需更改，必须关闭当前会话并重新创建。
硬件限制：outputconfiguration 的配置（如分辨率、格式）必须符合 streamconfigurationmap 的支持范围。

5. 示例：使用 outputconfiguration 创建会话

// 创建两个输出目标：预览 surface 和拍照 imagereader
surfaceview surfaceview = ... // 预览的 surfaceview
imagereader imagereader = imagereader.newinstance(4032, 3024, imageformat.jpeg, 3);
// 封装为 outputconfiguration
outputconfiguration previewconfig = new outputconfiguration(surfaceview.getholder().getsurface());
outputconfiguration captureconfig = new outputconfiguration(imagereader.getsurface());
// 可选：配置共享流或物理摄像头
// previewconfig.addsurface(anothersurface); // 共享同一个流
// captureconfig.setphysicalcameraid("1");    // 指定物理摄像头
list<outputconfiguration> outputconfigs = new arraylist<>();
outputconfigs.add(previewconfig);
outputconfigs.add(captureconfig);
// 创建 cameracapturesession
cameradevice.createcapturesessionbyoutputconfigurations(outputconfigs, 
    new cameracapturesession.statecallback() {
        @override
        public void onconfigured(@nonnull cameracapturesession session) {
            // 会话就绪，可提交 capturerequest
        }
        @override
        public void onconfigurefailed(@nonnull cameracapturesession session) {
            // 配置失败（参数不合法或硬件问题）
        }
    }, 
    null // 可选 handler
);

6. 高级功能与兼容性

共享流（shared surfaces）：
- 多个 surface 共享同一输出流（例如预览和 ai 分析共享数据），减少内存和功耗。
- 实现方式：通过 outputconfiguration.addsurface() 添加多个 surface。
动态分辨率（dynamic resolution）（api 23+）：
- 允许在会话运行时动态调整输出分辨率（需设备支持）。
- 通过 outputconfiguration.setdynamicrangeprofile() 配置。
多摄像头支持（api 28+）：
- 在双摄设备中，通过 outputconfiguration.setphysicalcameraid() 指定输出流来源。

7. 常见问题与解决方案

问题1：createcapturesession 失败，错误为 illegalargumentexception。
原因：outputconfiguration 参数不合法（如分辨率超出支持范围）。
解决：检查 streamconfigurationmap 的合法参数。
问题2：无法在运行时修改输出流。
原因：cameracapturesession 的配置不可变。
解决：关闭当前会话，重新创建新的会话。
问题3：多摄像头场景下数据流混乱。
原因：未正确指定 setphysicalcameraid()。
解决：确保每个 outputconfiguration 绑定到正确的物理摄像头。

总结

cameracapturesession：是相机数据流的核心控制器，负责管理输出目标和捕获请求。
与 outputconfiguration 的关系：
- outputconfiguration 是会话的输入，定义了每个输出流的具体配置（如 surface、物理摄像头）。
- cameracapturesession 通过 outputconfiguration 的配置，确保数据流符合硬件能力（由 streamconfigurationmap 定义）。
- 使用 outputconfiguration 可以启用高级功能（如共享流、多摄像头），而传统 surface 列表方式功能受限。