4. 预览请求构建：CaptureRequest.Builder的配置，模板选择与参数设置

在Android相机预览流程中，CaptureRequest是连接应用层与相机HAL层的核心指令载体。每一个预览帧的采集、处理与输出，都依赖于一个正确配置的CaptureRequest。本章将深入剖析CaptureRequest.Builder的构建过程、模板选择策略以及关键参数的设置方法，帮助开发者精准控制预览数据通路。

4.1 CaptureRequest.Builder的创建与生命周期

CaptureRequest.Builder由CameraDevice.createCaptureRequest(int templateType)方法创建。该方法返回一个预填充了指定模板参数的Builder实例，开发者随后可在此基础上修改或添加参数。

// 典型构建流程
CameraDevice cameraDevice = ...;
CaptureRequest.Builder builder = cameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);

// 添加目标Surface（预览Surface + 拍照Surface等）
builder.addTarget(previewSurface);
builder.addTarget(imageReaderSurface);

// 设置参数
builder.set(CaptureRequest.CONTROL_AE_MODE, CaptureRequest.CONTROL_AE_MODE_ON);
builder.set(CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);

// 构建不可变请求
CaptureRequest request = builder.build();

4.2 模板选择：五种预设模板的适用场景

Android相机框架提供了五种标准模板，每种模板预置了不同的参数组合，以适应不同的使用场景。选择正确的模板可以减少大量手动参数配置工作，并确保底层HAL处于正确的运行模式。

4.3 关键参数设置：控制预览数据通路

在预览请求中，以下参数直接影响数据通路的效率与输出质量。开发者需要根据具体需求进行精细调整。

4.3.1 目标Surface绑定（addTarget）

addTarget(Surface)方法将输出Surface绑定到请求上。每个请求可以绑定多个Surface，但必须满足以下约束：

• 所有绑定的Surface必须来自同一个CameraDevice的会话（Session）。
• Surface的尺寸必须与配置的OutputConfiguration一致。
• 对于预览，通常绑定SurfaceView或TextureView的Surface；对于图像分析，绑定ImageReader的Surface。

4.3.2 3A参数（AE/AWB/AF）

自动曝光（AE）、自动白平衡（AWB）和自动对焦（AF）是预览画质的基础。模板已提供默认值，但开发者可根据场景覆盖：

// 强制锁定AE（适用于固定光照场景）
builder.set(CaptureRequest.CONTROL_AE_LOCK, true);

// 设置AE补偿（曝光补偿，范围由CameraCharacteristics控制）
builder.set(CaptureRequest.CONTROL_AE_EXPOSURE_COMPENSATION, 6);

// 选择AF模式
builder.set(CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_MODE_CONTINUOUS_PICTURE);

// 手动设置AWB模式
builder.set(CaptureRequest.CONTROL_AWB_MODE, CaptureRequest.CONTROL_AWB_MODE_DAYLIGHT);

4.3.3 帧率控制（FPS Range）

预览帧率通过CONTROL_AE_TARGET_FPS_RANGE控制。该参数是一个Range<Integer>，表示最小和最大帧率。

// 设置30fps固定帧率
builder.set(CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, new Range<>(30, 30));

// 设置可变帧率（15~30fps），允许在光照不足时降帧
builder.set(CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, new Range<>(15, 30));

4.3.4 传感器与处理管线控制

以下参数控制底层传感器输出与ISP处理：

4.4 预览请求构建流程SVG图

下图展示了从Builder创建到请求提交的完整流程，以及各阶段的关键操作：

4.5 常见配置错误与避坑指南

4.6 参数优先级与覆盖规则

当Builder上设置的参数与模板预置参数冲突时，遵循以下优先级规则：

1. 显式设置的参数（通过set()方法）优先级最高，会覆盖模板默认值。
2. 模板预置参数作为基础配置，仅在开发者未显式设置时生效。
3. HAL层最终决定权：部分参数（如AE状态）可能被HAL根据传感器能力调整，应用层设置仅作为建议。

// 示例：覆盖模板的AE模式
// TEMPLATE_PREVIEW默认AE为CONTROL_AE_MODE_ON
builder.set(CaptureRequest.CONTROL_AE_MODE, CaptureRequest.CONTROL_AE_MODE_OFF);
// 此时AE被强制关闭，需要手动设置曝光时间和ISO
builder.set(CaptureRequest.SENSOR_EXPOSURE_TIME, 10000000L); // 10ms
builder.set(CaptureRequest.SENSOR_SENSITIVITY, 400); // ISO 400

4.7 预览请求参数设置决策树SVG图

以下决策树帮助开发者在不同场景下快速选择正确的参数配置：

4.8 性能优化建议

• 减少参数设置次数： 在Builder上一次性设置所有参数，避免多次调用set()造成内部状态切换开销。
• 复用请求对象： 对于重复性预览（如setRepeatingRequest），构建一次CaptureRequest后持续使用，无需每帧重建。
• 避免不必要的参数： 只设置与当前预览相关的参数。例如，如果不需要手动控制曝光，就不要设置SENSOR_EXPOSURE_TIME，让AE自动处理。
• 使用FAST模式： 对于EDGE_MODE、NOISE_REDUCTION_MODE、TONEMAP_MODE等处理管线参数，优先选择FAST模式以降低延迟。