106.StreamConfigurationMap 与输出格式匹配机制：构建高效图像流配置体系的工程实战解析

StreamConfigurationMap 与输出格式匹配机制：构建高效图像流配置体系的工程实战解析

关键词：
StreamConfigurationMap、输出分辨率、图像格式、YUV_420_888、JPEG、RAW_SENSOR、CameraCharacteristics、UseCase 匹配、图像配置优化

摘要：
在 Camera2 架构中， StreamConfigurationMap 是连接相机硬件能力与应用图像流配置的核心桥梁，决定了应用层能否正确创建 Surface ，并高效运行多种 UseCase（预览、拍照、分析等）。错误或不匹配的输出格式与分辨率配置，常常导致流创建失败、帧卡顿、内存溢出等问题。本文将从开发实战角度出发，深入讲解 StreamConfigurationMap 的构成与使用方法，覆盖输出格式支持查询、兼容性适配、分辨率匹配机制与多 UseCase 场景下的配置组合策略，助力开发者构建更稳定、高性能的图像输出链路。

目录

1. StreamConfigurationMap 在 Camera 架构中的作用定位
2. 获取与解析 CameraCharacteristics 输出能力
3. 输出格式（Format）支持策略与平台差异
4. 分辨率与帧率支持查询机制
5. 多 UseCase 场景下的组合配置方案
6. Surface 配置失败的常见原因与排查流程
7. 实战案例：构建自适应输出配置模型
8. 兼容性优化与跨平台配置建议

一、StreamConfigurationMap 在 Camera 架构中的作用定位

在 Android 的 Camera2 架构中， StreamConfigurationMap 是连接硬件能力（HAL 提供）与上层 UseCase 图像流配置之间的桥梁 ，其作用远不止于“支持的分辨率列表”那么简单。正确地理解与使用 StreamConfigurationMap ，是构建稳定、兼容性强且具备性能保证的 Camera 应用的第一步。

本章将围绕其在系统中的角色定位、功能范围与调用时机展开，结合平台实际行为、典型错误场景与系统数据流逻辑，明确其在整个 Camera 初始化与流配置中的核心地位。

1.1 Camera 架构中的配置关键点

在 Camera2 架构下，流配置发生在 CameraCaptureSession 创建之前，具体流程如下：

CameraDevice.open() 
   ↓
CameraDevice.createCaptureSession(List<Surface>) 
   ↓
根据 Surface 的格式、大小 → 查询是否支持 → 生成 StreamConfig
   ↓
内部通过 StreamConfigurationMap 校验与构造配置

此时 StreamConfigurationMap 的作用是： 在已知目标格式（如 YUV、JPEG、RAW）与尺寸（如 1920x1080）时，判断该组合是否被硬件支持 ，并决定是否可以成功建立 Camera 流通道。

1.2 定义与来源

CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId);
StreamConfigurationMap configMap = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);

• StreamConfigurationMap 是通过 CameraCharacteristics 获取的；
• 数据由底层 Camera HAL 提供，通常在设备开机或 Camera 初始化时由 HAL 查询并上报；
• 是设备静态能力的一部分 ，即它不会随 app 或场景变化动态变化。

1.3 核心功能范围

1.4 典型错误场景示例

1.5 实战中的定位与调用建议

• 初始化时提取一次缓存 ，避免反复读取；
• 与目标 UseCase 绑定前，先进行动态匹配判断；
• 建议构建 CameraConfigAdapter 工具类，封装 StreamConfigurationMap 的查询逻辑，实现对不同格式、不同尺寸的支持判定、降级选择。

小结

StreamConfigurationMap 并非只是一个静态能力列表，它是 Camera2 模型中图像流配置成功与否的核心判定依据。了解其作用、调用路径与返回数据结构，是开发高可靠性相机系统的基础。

二、获取与解析 CameraCharacteristics 输出能力

在 Android Camera2 架构中，所有关于相机设备硬件能力的查询，统一由 CameraCharacteristics 提供。其中，输出能力（包括图像格式、分辨率、帧率等）是 Camera 流配置是否成功的关键前提。而这些信息大多存储在其下属字段 SCALER_STREAM_CONFIGURATION_MAP 中，返回对象即为 StreamConfigurationMap 。

本章将从工程实践出发，详细讲解如何通过 CameraCharacteristics 获取相机输出能力、解析格式与分辨率支持情况，并构建适配逻辑以保证应用在多设备、多平台下的稳定性。

2.1 获取 CameraCharacteristics 的标准方式

开发者首先需要通过 CameraManager 获取目标 Camera ID 列表，然后逐一查询对应的 CameraCharacteristics ：

CameraManager cameraManager = (CameraManager) context.getSystemService(Context.CAMERA_SERVICE);
for (String cameraId : cameraManager.getCameraIdList()) {
    CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId);
    // 后续处理
}

该对象为一个 Key-Value 映射表，其中的 Key 是标准的静态常量，如：

• CameraCharacteristics.LENS_FACING
• CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP
• CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES

2.2 解析 StreamConfigurationMap 的核心能力字段

StreamConfigurationMap map = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);

该对象提供了以下常用能力查询方法：

例如：

int[] formats = map.getOutputFormats();
for (int format : formats) {
    Size[] sizes = map.getOutputSizes(format);
    Log.d("CameraFormat", "Format = " + format + ", Supported Sizes = " + Arrays.toString(sizes));
}

2.3 常见格式类型说明（基于 ImageFormat 定义）

2.4 判断是否支持特定格式与分辨率组合

实际工程中，开发者需要确保使用的格式和分辨率被当前设备支持：

public boolean isSupportedFormatSize(StreamConfigurationMap map, int format, Size targetSize) {
    Size[] supportedSizes = map.getOutputSizes(format);
    for (Size size : supportedSizes) {
        if (size.equals(targetSize)) {
            return true;
        }
    }
    return false;
}

可用于确保 ImageReader 、 PreviewView 、 MediaRecorder 等输出不会抛出 “不支持的 Surface” 错误。

2.5 多平台适配建议

• 高通平台（QTI） ：支持格式丰富，兼容性强，部分分辨率支持高帧率；
• MTK 平台 ：在特定分辨率（如 4K@30fps）下可能对格式有限制；
• 三星平台（Exynos） ：PRIVATE 格式使用较频繁，建议通过 Surface 创建而非 ImageReader 。

建议在项目初始化阶段预先收集主流设备输出能力，并构建白名单/黑名单机制用于平台级降级适配。

小结

通过 CameraCharacteristics 获取并解析输出能力，是构建兼容性强、稳定性高的相机应用的关键。开发者应在 UseCase 绑定前进行能力确认，避免不支持的流配置导致的闪退、黑屏或初始化失败。

三、输出格式（Format）支持策略与平台差异

在 Android Camera2 架构中， 输出图像格式（Format）直接决定了底层图像缓冲结构、HAL 数据流路径与上层 UseCase 的兼容性 。不同设备、不同 SoC 平台对格式支持的广度与稳定性差异显著，错误的格式选择往往会导致 createCaptureSession() 失败、Surface 初始化异常、甚至相机初始化崩溃。

本章将围绕主流输出格式的系统支持情况、适配策略与平台差异进行深入分析，帮助开发者在工程实践中做出正确的输出格式选型。

3.1 Camera2 支持的标准输出格式列表（基于 ImageFormat 常量）

3.2 各格式的实际使用场景

3.3 PRIVATE 格式的特别说明

PRIVATE 格式并不是指一个真实的图像格式，而是一种 “HAL 自行决定格式细节、上层不直接干涉”的封装方式 。当你将 SurfaceTexture 、 SurfaceView 作为预览目标绑定给 CaptureSession 时，系统会自动使用 PRIVATE 格式，并由 HAL 决定是否使用 NV21/YV12/RGB 等内部格式进行处理。

Surface surface = new Surface(textureView.getSurfaceTexture());
captureRequestBuilder.addTarget(surface); // 实际使用 PRIVATE 格式

⚠️ 不建议对 PRIVATE 格式使用 ImageReader 进行读取或格式转换操作。

3.4 不同 SoC 平台对输出格式的支持差异

3.5 工程实践中格式选择策略建议

3.6 常见错误与调试经验分享

• 错误一：使用 YUV + Preview 并发导致 createCaptureSession 失败

  • 部分 MTK 平台在 Preview + YUV 并发时超出最大输出流限制；
  • 建议降级为 JPEG 或仅保留一条分析流。

• 错误二：使用 JPEG 输出 Image 时解码失败

  • 可能是 ImageReader 未设置合适的最大图像数量，或未及时 image.close() 释放；
  • 调整为 ImageReader.newInstance(w, h, JPEG, 2) ，确保及时处理。

• 调试建议 ：

  • 使用 adb shell dumpsys media.camera 查看当前流配置与格式；
  • 打开 CameraService 日志（logcat tag：CameraService）获取详细错误码与 Surface 拒绝原因。

小结

输出格式选择不仅影响图像质量与处理效率，更直接决定了相机流配置能否成功。开发者在跨平台 Camera 架构设计中，应优先选择 YUV/JPEG/PRIVATE 等主流格式，并结合平台能力判断做出合理取舍，避免低兼容性的格式引发的稳定性问题。

四、分辨率与帧率支持查询机制

在 Android Camera2 架构中， 输出分辨率（Resolution）与帧率（Frame Rate）是 UseCase 成功运行的核心条件 。设备所支持的每种图像格式，其可选的输出尺寸和帧率范围均需通过系统查询获得，无法依靠固定写死。错误的尺寸或帧率配置常导致图像拉伸、帧丢失、流创建失败，甚至设备不兼容。

本章将系统化解析如何通过 StreamConfigurationMap 获取设备支持的输出分辨率与帧率组合，并结合多平台差异和实战经验提出配置优化建议。

4.1 使用 CameraCharacteristics 获取支持信息

要查询输出能力，第一步是通过 CameraManager 获取对应设备的 CameraCharacteristics ：

CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId);
StreamConfigurationMap configMap = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);

其中， SCALER_STREAM_CONFIGURATION_MAP 提供了如下关键接口：

Size[] getOutputSizes(int format);
Size[] getOutputSizes(Class<?> klass); // 如 SurfaceTexture.class

4.2 获取输出分辨率列表（按 Format）

Size[] yuvSizes = configMap.getOutputSizes(ImageFormat.YUV_420_888);
Size[] jpegSizes = configMap.getOutputSizes(ImageFormat.JPEG);
Size[] surfaceSizes = configMap.getOutputSizes(SurfaceTexture.class);

通常推荐：

• 预览流 使用 SurfaceTexture / SurfaceView + PRIVATE 格式；
• 分析流 使用 YUV_420_888 ；
• 拍照输出 使用 JPEG 。

4.3 查询帧率范围支持逻辑

帧率支持并不直接由 StreamConfigurationMap 提供，而是通过 CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES ：

Range<Integer>[] fpsRanges = characteristics.get(CameraCharacteristics.CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES);

你可以从中选出合适范围：

for (Range<Integer> range : fpsRanges) {
    Log.d("CameraFps", "Min: " + range.getLower() + ", Max: " + range.getUpper());
}

在构建 CaptureRequest 时，通过如下方式设置：

builder.set(CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, Range.create(30, 30));

⚠️ 不同设备可能只支持部分帧率组合，比如部分 MTK 平台仅支持 (15,30) 或 (30,30) 。

4.4 获取各尺寸下的帧率上限（高级查询）

部分平台扩展提供 getHighSpeedVideoFpsRangesFor(Size size) 接口：

Range<Integer>[] highSpeedRanges = configMap.getHighSpeedVideoFpsRangesFor(new Size(1920, 1080));

适用于慢动作视频、120fps 或 240fps 等场景，但前提是设备支持 CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO 。

4.5 判断 UseCase 支持合法性：配置前校验

开发中建议封装校验方法：

boolean isSupported(Size wantedSize, int format) {
    Size[] supported = configMap.getOutputSizes(format);
    return Arrays.asList(supported).contains(wantedSize);
}

当 CaptureSession 创建失败时，首要检查点是： Surface 的尺寸与格式是否在支持列表中 。

4.6 跨平台的输出支持差异分析

4.7 常见错误与调试经验

• 流配置失败 / createCaptureSession 报错
  → 通常是 Size + Format 组合非法，需重新查询配置项。

• 帧率无法稳定锁定
  → 当前设置的 FPS Range 并未包含在设备支持范围内。

• YUV 分辨率无法绑定 ImageReader
  → 缺失 ImageReader 内部 Surface 尺寸合法性校验，需打印其实际分配尺寸确认。

ImageReader reader = ImageReader.newInstance(w, h, ImageFormat.YUV_420_888, 3);
Log.d("YUVReader", "Allocated: " + reader.getWidth() + " x " + reader.getHeight());

4.8 实战建议：分辨率选型与动态策略

• 预览推荐尺寸 ：根据设备屏幕密度动态计算（如 1280×720、1920×1080）；
• 图像分析尺寸 ：兼顾算法精度与性能，常见为 640×480、1280×720；
• 拍照尺寸 ：优先选择 JPEG 最大尺寸，但需考虑内存压力与写盘速度；
• 帧率 ：拍照时锁 30fps；分析时视算法延迟而定（15fps ~ 60fps）。

小结

输出分辨率与帧率是相机配置中最容易出错、但又最关键的部分。通过 StreamConfigurationMap 与 CameraCharacteristics 精准获取支持能力，结合动态判断与封装策略，可极大提升系统稳定性与图像链路效率。

五、多 UseCase 场景下的组合配置方案

在 Camera2 框架中，多 UseCase 并发（如预览 + 拍照 + 图像分析）是典型高复杂度的使用场景。 每个 UseCase 对 Surface 的格式、尺寸、帧率有特定要求，而 CameraDevice 仅支持有限数量的输出流和组合能力 。如果配置错误，就会出现 createCaptureSession 失败、画面黑屏、延迟异常等问题。

本章将围绕实际项目开发需求，系统讲解如何合理组合多个 UseCase 的输出配置，结合平台差异化限制与调度约束，提供一套工程化的组合配置策略。

5.1 CameraDevice 的流组合限制（Stream Configuration Constraints）

Android 平台在系统层对每个 CameraDevice 的输出流数量、格式类型与组合模式有约束：

• 最多 3 个并发输出流（部分平台支持 4 个）
• 每种格式只能指定 1 个主输出流（如 JPEG）+ N 个低分辨率辅助流
• 使用不同分辨率、格式组合时会触发内部硬件路径切换

可通过以下字段查询设备组合能力：

int maxStreams = characteristics.get(CameraCharacteristics.REQUEST_MAX_NUM_OUTPUT_STREAMS);

此外，部分厂商（如 QTI）会在 HAL 层自定义组合约束，需在实战中详细验证。

5.2 常见 UseCase 配置组合类型

5.3 Surface 配置示例：构造 SessionConfiguration

List<OutputConfiguration> outputConfigs = new ArrayList<>();

// 预览 Surface
Surface previewSurface = surfaceView.getHolder().getSurface();
outputConfigs.add(new OutputConfiguration(previewSurface));

// 拍照 Surface
ImageReader jpegReader = ImageReader.newInstance(w, h, ImageFormat.JPEG, 2);
outputConfigs.add(new OutputConfiguration(jpegReader.getSurface()));

// 图像分析 Surface
ImageReader analysisReader = ImageReader.newInstance(640, 480, ImageFormat.YUV_420_888, 2);
outputConfigs.add(new OutputConfiguration(analysisReader.getSurface()));

SessionConfiguration sessionConfig = new SessionConfiguration(
    SessionConfiguration.SESSION_REGULAR,
    outputConfigs,
    executor,
    stateCallback
);

cameraDevice.createCaptureSession(sessionConfig);

⚠️ 需确保上述三种 Surface 的尺寸和格式组合被设备支持，否则 createCaptureSession 将直接失败并抛出 IllegalArgumentException 。

5.4 如何判断组合是否合法

系统提供了组合合法性判断入口：

StreamConfigurationMap.isOutputSupportedFor(format)

但这仅是单 Surface 级别判断。更推荐使用预先验证机制：

boolean isValidCombo = checkSurfaceCombo(previewSurface, jpegSurface, yuvSurface);

自行维护合法组合表是平台兼容的重要手段（如某些 MTK 设备只支持 2 路并发输出）。

5.5 流配置失败常见错误与排查路径

调试建议：

adb shell dumpsys media.camera
adb logcat | grep Camera

5.6 UseCase 分辨率匹配建议

• 预览流 推荐 1280×720，适配大多数设备；
• 图像分析流 控制在 640×480 或以下，降低计算压力；
• 拍照输出 使用 JPEG 最大支持尺寸，但谨慎使用超大图（如 8000x6000）以避免 OOM；
• 组合场景下 ，建议从小到大排序添加 Surface，减少高分辨率占用资源。

5.7 多 Surface 输出下的帧率协调策略

默认情况下，多个输出 Surface 会共享帧率上限（如 30fps）。如需控制帧率，必须统一设置：

builder.set(CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, Range.create(30, 30));

高帧率（如 60fps）只支持 PRIVATE + SurfaceTexture 输出，不能并发 JPEG。

5.8 实战封装建议：组合策略抽象模型

class SurfaceCombo {
    Surface previewSurface;
    Surface imageCaptureSurface;
    Surface analysisSurface;

    boolean isValid(StreamConfigurationMap map);
    SessionConfiguration buildConfig();
}

结合反射或设备配置白名单，构建跨平台的动态流组合配置方案，是高质量 Camera 应用的重要工程保障。

小结

在多 UseCase 场景下，Surface 组合配置既是 Camera 系统架构的重要基础，也是开发者调优和稳定运行的挑战核心。掌握合法配置策略、尺寸与格式匹配技巧，并建立动态组合管理机制，是保障 Camera 应用适配性与性能表现的关键路径。

六、Surface 配置失败的常见原因与排查流程

在基于 Camera2 架构进行多 UseCase（如 Preview + Capture + Analysis）并发开发时， createCaptureSession() 失败是开发者最常见的系统级问题之一。尤其是当 Surface 配置不合法、设备不支持当前格式组合或资源不足时，系统会直接抛出 IllegalArgumentException 或 Silent Failure，导致黑屏、闪退、拍照无反应等问题。

本章将从工程角度系统剖析 Surface 配置失败的典型原因，配套 logcat 分析方法与系统工具排查流程，提供开发者稳定构建图像管线的调试方法论。

6.1 常见失败现象归类

6.2 原因一：非法的 Surface 配置组合

• 多路 ImageReader 使用同种格式但分辨率不同
• YUV_420_888 + JPEG + Analysis 组合不被 HAL 支持
• Surface 尺寸未在 StreamConfigurationMap 支持表中注册

排查建议：

StreamConfigurationMap map = characteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
Size[] sizes = map.getOutputSizes(ImageFormat.YUV_420_888);

确保所配置的 Size 属于上述合法范围。

6.3 原因二：Surface 生命周期管理失控

常见于以下场景：

• ImageReader.getSurface() 被提前关闭或未设置监听器
• SurfaceView/TextureView 尚未初始化完毕就启动相机
• Activity 生命周期未同步释放 Camera 导致 Surface 被回收

典型异常：

E CameraCaptureSession: Session 0: Surface is invalid, configuration failed
E Surface: getSlotFromBufferLocked: unknown buffer

建议检查：

• SurfaceView.getHolder().getSurface().isValid() 为 true
• TextureView.isAvailable() 为 true 时再启动
• 绑定 Surface 后立刻调用 setOnImageAvailableListener 防止被系统收回

6.4 原因三：分辨率或格式过大导致内存分配失败

当配置如 4000x3000 JPEG + 1920x1080 YUV + 1280x720 Preview 的组合时，部分中低端设备会触发底层 gralloc 分配失败。

建议：

• 控制 YUV 分辨率为 640x480 或以下
• 避免 JPEG + Analysis 并存
• 使用 dumpsys SurfaceFlinger 观察显存使用情况

6.5 原因四：不支持的格式/类型 Surface 被绑定

如尝试将 MediaCodec 输出 Surface、非 ImageReader 类型绑定到 Camera 会直接失败。

确认格式是否为以下合法类型：

ImageFormat.YUV_420_888  
ImageFormat.JPEG  
ImageFormat.RAW_SENSOR  
PixelFormat.PRIVATE  

若出现以下日志：

E CameraDevice: Surface format -1 is not supported

说明 Surface 创建方式有误，建议回溯到 Surface 实例来源。

6.6 原因五：组合模式不被 HAL 支持

平台差异：

• Qualcomm 一般支持 3 路输出，但需满足格式搭配
• MTK 不支持同时启用 JPEG + YUV_420_888
• Samsung Exynos 拍照时默认占用所有通道

可使用 dumpsys media.camera 读取 HAL 报告的 availableConfigurations ：

adb shell dumpsys media.camera | grep StreamConfigurationMap

确认当前配置是否存在于支持的组合表内。

6.7 高质量调试建议流程（可脚本化）

1. 日志打印 ：

   Log.d("Camera", "Preview Size: " + previewSize);
   Log.d("Camera", "JPEG Size: " + captureSize);
   Log.d("Camera", "YUV Size: " + analysisSize);
   
   

2. 系统状态检查 ：

   adb shell dumpsys media.camera
   adb logcat | grep Camera
   
   

3. Surface 状态 ：

   adb shell dumpsys SurfaceFlinger --list
   
   

4. 强制缓冲回收测试 ：

   • 在 Activity onDestroy() 中断开所有 Surface
   • 调用 ImageReader.close() , cameraDevice.close()

6.8 建议封装错误监控日志模块

class SurfaceConfigLogger {
    void logCombination(List<Surface> surfaces);
    void dumpSizesAndFormats(StreamConfigurationMap map);
    void checkValidLifecycle(Surface s);
}

便于记录线上错误配置组合，用于大规模机型适配回溯分析。

小结

Surface 配置失败是影响 Camera 应用稳定性的核心技术障碍。通过对错误类型、平台兼容性与系统资源调度机制的深入理解，结合日志分析与自动化校验策略，可以显著提升系统适配成功率与用户体验。

七、实战案例：构建自适应输出配置模型

在面对多机型、多分辨率、多格式组合需求的 Camera 应用开发中， 构建一个可扩展的自适应输出配置模型 是保障稳定性的关键。本章结合实际项目经验，从设备能力读取、输出组合筛选、动态选择策略与降级机制等角度出发，讲解如何在复杂场景下优雅地处理 Surface 输出配置问题，适配高通、MTK、三星等多平台，确保在不同硬件能力上获得最优配置方案。

7.1 设计目标与适配需求

典型业务场景需满足以下输出需求：

• 预览：YUV 流，支持高帧率、低延迟
• 拍照：JPEG 流，需高分辨率、无卡顿
• 图像分析：YUV 或 RGBA 流，供 ML 模型处理

挑战点：

• 各平台对输出组合的支持策略不同（如 MTK 不支持 YUV+JPEG 并存）
• 部分分辨率组合在低端设备上引发内存溢出或缓冲错误
• UseCase 重建或热启动频繁失败

7.2 模块结构设计（伪代码框架）

class OutputConfigurationModel {
    Size previewSize;
    Size captureSize;
    Size analysisSize;
    int formatPreview = ImageFormat.YUV_420_888;
    int formatCapture = ImageFormat.JPEG;
    int formatAnalysis = ImageFormat.YUV_420_888;

    boolean isSupported(StreamConfigurationMap map) {
        return map.isOutputSupportedFor(formatPreview)
            && map.isOutputSupportedFor(formatCapture)
            && map.isOutputSupportedFor(formatAnalysis);
    }
}

定义结构体，封装每组输出组合与判断逻辑。

7.3 读取支持能力并生成组合候选集

StreamConfigurationMap map = cameraCharacteristics.get(
    CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);

Size[] previewSizes = map.getOutputSizes(ImageFormat.YUV_420_888);
Size[] jpegSizes = map.getOutputSizes(ImageFormat.JPEG);

遍历组合列表：

List<OutputConfigurationModel> candidates = new ArrayList<>();
for (Size preview : previewSizes) {
    for (Size jpeg : jpegSizes) {
        OutputConfigurationModel model = new OutputConfigurationModel();
        model.previewSize = preview;
        model.captureSize = jpeg;
        // analysisSize 可限定为 preview 以下
        model.analysisSize = preview; 
        if (model.isSupported(map)) {
            candidates.add(model);
        }
    }
}

7.4 结合机型策略实现优先级排序

Collections.sort(candidates, (a, b) -> {
    int scoreA = score(a.previewSize, a.captureSize);
    int scoreB = score(b.previewSize, b.captureSize);
    return scoreB - scoreA;
});

优先选取：

• 分辨率最大但仍稳定的组合
• 相机厂商推荐尺寸（可由 metadata 提取）

7.5 动态降级策略实现

在运行时若 createCaptureSession() 抛异常，可通过预置的 fallback 列表快速切换：

int retryIndex = 1;
while (retryIndex < candidates.size()) {
    try {
        configureOutputs(candidates.get(retryIndex));
        break;
    } catch (Exception e) {
        retryIndex++;
    }
}

7.6 记录设备能力与结果：形成运行时适配缓存

首次运行后将选择的配置写入 SharedPreferences 或 SQLite 中：

SharedPreferences.Editor editor = prefs.edit();
editor.putString("CAMERA_CONFIG_KEY", serialize(model));
editor.apply();

下次启动优先使用上次成功组合。

7.7 实战中常见组合建议（适用于绝大多数中端机）

在需要分析稳定性时，可动态调低 Preview 分辨率；若图像分析优先，则牺牲拍照精度。

7.8 日志与调试建议：构建配置失败记录模块

class OutputErrorLogger {
    void logFailure(OutputConfigurationModel model, Exception e);
    void exportToFile(Context context);
}

每次创建失败记录入日志中，便于大规模线上排查与兼容性图谱建立。

小结

通过构建自适应输出配置模型，不仅可以提升 Camera 应用的系统适配能力，还能实现图像链路的资源优化与异常容错。该模型在主流 Android 相机应用、AI 视觉平台中均有成熟应用，是 Camera 工程开发的重要基础模块之一。

八、兼容性优化与跨平台配置建议

在构建面向多品牌、多 SoC 平台的 Camera 应用时，开发者会遇到显著的配置能力差异和图像链路支持不一致问题。特别是在 StreamConfigurationMap 的实际支持项中，存在一些平台定制行为与非公开限制。为了保证拍照/预览/分析等 UseCase 的稳定运行，需要结合厂商行为进行有针对性的兼容性优化与结构封装。

8.1 平台差异现状概览

• 高通平台（QTI）

  • 支持 YUV+JPEG+PRIVATE 的多路输出
  • 推荐使用 getOutputMinFrameDuration() 控制帧率
  • 部分机型对 JPEG 分辨率设置有默认值覆盖

• MTK 平台

  • YUV+JPEG 多输出组合支持受限，需调整 Stream 顺序
  • 使用 KEY_MTK_* 扩展参数控制 stream group
  • 热重启（reconfigure）容错能力弱

• 三星 Exynos 平台

  • 多 UseCase 并发策略自定义显著（非标准行为）
  • 可能未公开支持部分常规 OutputFormats （如 RAW）
  • 多摄组合输出有特定逻辑 ID 限制

8.2 输出格式选择的跨平台策略

建议统一用 YUV_420_888 作为中间格式桥接分析与预览流。

8.3 分辨率设置的通用降级策略

在动态适配中，需预设分辨率优先级，从高到低依次尝试，避免硬编码：

val preferredSizes = listOf(
    Size(1920, 1080),
    Size(1280, 720),
    Size(640, 480),
    Size(320, 240)
)

通过 StreamConfigurationMap.getOutputSizes() 动态筛选支持项，再进行自动排序选择。

8.4 创建 Session 的顺序影响

在部分 MTK 与三星平台中， UseCase 创建顺序影响 Session 可用性 。推荐顺序：

1. Preview
2. ImageAnalysis（可选）
3. ImageCapture（JPEG）

若构建失败，尝试修改 Surface 注册顺序可解决部分问题。

8.5 动态适配封装建议

统一管理配置能力与行为差异：

class StreamProfile {
    List<Size> previewSizes;
    List<Size> jpegSizes;
    boolean supportYuvAnalysis;
    boolean supportMultiStream;
    String platformType; // e.g., "QTI", "MTK", "EXYNOS"
}

结合厂商字段判断平台：

String manufacturer = Build.MANUFACTURER.toLowerCase();
if (manufacturer.contains("vivo") || manufacturer.contains("oppo")) {
    profile.platformType = "MTK";
} else if (manufacturer.contains("samsung")) {
    profile.platformType = "EXYNOS";
} else {
    profile.platformType = "QTI";
}

8.6 日志记录与兼容性数据库建设建议

构建自定义兼容性问题记录模块：

class CompatibilityLogger {
    void record(String model, String issueType, String surfaceCombo);
    List<String> getFailureHistory();
}

可在服务器端记录机型 → UseCase 成功率，自动分发兼容组合。

8.7 跨平台输出配置封装模型结构建议

class OutputConfigFactory {
    OutputConfiguration buildFor(UseCaseType type, String platform) {
        // 高通优先组合输出
        // MTK 限定 Preview+JPEG，Analysis 分离
        // 三星优先 PRIVATE+YUV
    }
}

结合 Build 信息和设备能力动态生成配置，屏蔽平台差异。

8.8 自动回退与重建机制

在配置失败时：

• 降低分辨率重试
• 改变输出顺序
• 拆分 UseCase：Analysis 独立启动
• 记录错误日志，规避下次失败

典型代码：

try {
    camera.createCaptureSession(surfaceList, callback, handler);
} catch (Exception e) {
    tryLowerConfig(); // 降级策略
}

小结

跨平台 Camera 配置不仅仅是技术细节的堆砌，更是一套系统的稳定性策略。通过结合设备能力查询、输出格式筛选、顺序调整、行为差异记录与自动回退机制，开发者可以构建一个真正可落地、适配广泛、维护成本低的 Camera UseCase 管理体系。

本文转自 https://jc-performance.cn//online/4108_148669718.html，如有侵权，请联系删除。