数据流配置

Android 包含一些功能，允许摄像头客户端针对具体使用情形选择最佳的摄像头数据流，并确保摄像头设备支持某些数据流组合。数据流配置是指在摄像头设备中配置的单个摄像头数据流，而数据流组合是指在摄像头设备中配置的一组或多组数据流。如需详细了解这些功能，请参阅推荐的数据流配置和用于查询功能组合的 API。

参考实现

我们提供了推荐的数据流配置和用于查询数据流组合功能的 API 的供应商端参考实现。您可以在 QCamera3HWI.cpp 找到此实现。

摄像头供应商可以向相机客户端发布针对特定使用情形推荐的数据流配置。这些推荐的数据流配置是 StreamConfigurationMap 的子集，可以帮助相机客户端选择最佳配置。

尽管 StreamConfigurationMap 为相机客户端提供了详尽的数据流配置信息，但它并未提供任何有关选择某个数据流（而非另一个数据流）对效率、耗电量或性能有何影响的信息。摄像头客户端可以从所有可能的数据流配置中任意选择一个，但在许多情况下，这会导致客户端使用次优的摄像头配置，还会导致应用执行耗时而彻底的搜索。

例如，虽然某些已处理的 YUV 格式是必需的并且必须受支持，但摄像头设备可能无法对此类格式提供原生支持。这会导致需要对格式转换进行额外的处理，并且会降低效率。尺寸和相应的宽高比也可能具有类似的影响，因此就耗电量和性能而言，使用特定尺寸更好。

与 StreamConfigurationMap 相比，推荐的数据流配置映射不必详尽无遗。 推荐的配置映射必须遵循实现部分中的要求，可以包括 StreamConfigurationMap 中存在的任何可用格式、尺寸或其他值。StreamConfigurationMap 中不存在的隐藏格式、尺寸或其他值不能包含在推荐的数据流配置映射中。

根据推荐的数据流配置，所有测试都保持不变，并且不会放宽要求。

相机实现提供的推荐数据流配置是可选的，相机客户端可以将其忽略。

实现

请按照以下步骤实现此功能。

元数据条目

要启用此功能，Camera HAL 必须填充以下静态元数据条目：

  • android.scaler.availableRecommendedStreamConfigurations：针对特定用例推荐的数据流配置的子集。该声明使用位图，以 [1 << PREVIEW | 1 << RECORD..] 的形式表示推荐的用例。用例为常规（格式、宽度、高度、输入）元组额外增加了一个条目。 禁止使用不存在的公开用例或其他任何在 [PUBLIC_END, VENDOR_START] 范围内设置的位。

    这些信息存储在 availableRecommendedStreamConfigurations 元数据标记中。

    以下示例展示了仅支持 4K 和 1080p 的摄像头设备的推荐数据流配置数组，其中两种分辨率对于视频录制来说均属首选，但建议仅使用 1080p 进行预览。

    [3840, 2160, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT,
(1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT),
1920, 1080, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT,
(1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_PREVIEW |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT)]

  • android.depth.availableRecommendedDepthStreamConfigurations（仅在设备支持时可用）：针对此摄像头设备建议的推荐深度数据空间数据流配置。与上述元数据条目类似，附加的用例位图表示建议的用例。

    这些信息存储在 availableRecommendedInputOutputFormatsMap 元数据标记中。

  • android.scaler.availableRecommendedInputOutputFormatsMap（仅在设备支持时可用）：针对此摄像头设备建议的输入数据流推荐图片格式到其相应输出格式的映射。

    这些信息存储在 availableRecommendedDepthStreamConfigurations 元数据标记中。

通过 RecommendedStreamConfigurationMap API，相机客户端可以使用这些信息。

必需的使用情形

必须为以下使用情形提供推荐的数据流配置，并满足相应的要求：

用例 要求
PREVIEW 预览必须仅包含具有输出格式（如 YUV_420_888 和 IMPLEMENTATION_DEFINED）的非停滞处理式数据流配置。
RECORD 视频录制必须包含用于将发布的受支持媒体配置文件与 IMPLEMENTATION_DEFINED 格式相匹配的数据流配置。
VIDEO_SNAPSHOT 视频快照必须包含至少与最大 RECORD 分辨率一样大的数据流配置，并且仅包含 BLOB + DATASPACE_JFIF 格式/数据空间组合 (JPEG)。配置不应引起预览故障，并且应该能够以 30fps 的速度运行。
SNAPSHOT 快照数据流配置必须包含至少一个大小接近 android.sensor.info.activeArraySize 的数据流配置，并且包含 BLOB + DATASPACE_JFIF 格式/数据空间组合 (JPEG)。考虑到宽高比和对齐方式方面的限制以及其他特定于供应商的限制，最大建议尺寸的面积不应小于传感器数组尺寸面积的 97%。
ZSL（如果支持） 如果摄像头设备支持，则推荐的输入数据流配置必须仅与其他已处理或停滞的输出格式一起发布。
RAW（如果支持） 如果摄像头设备支持，推荐的原始数据流配置必须仅包括基于 RAW 的输出格式。

其他用例

您可以针对特定于您的实现的使用情形提供其他推荐的数据流配置。

验证

如要测试推荐的数据流配置的实现，请运行以下 CTS 和 VTS 测试：

用于查询功能组合的 API

从 Android 15 开始，Android 平台提供了用于查询功能组合的 API。借助此 API，摄像头客户端可以查询设备是否可支持指定的功能组合。此 API 是必需的，因为 camera2 API 会将 4K、60fps、HDR 视频、UltraHDR、超广角变焦和防抖等不同功能建模为正交控件。

要求

为了支持用于查询功能组合的 API，摄像头 HAL 必须实现 ICameraDevice 接口的版本 3。如需了解详情，请参阅实现部分。

支持该 API 时，预览防抖功能必须与其他功能互不干扰。这意味着，对于支持预览防抖的摄像头设备，特定组合在预览防抖开启或关闭时，isStreamCombinationWithSettingsSupported 的返回值必须相同。这会缩小功能组合查询的搜索空间。

此外，对于媒体性能等级 15，主后置摄像头必须支持 1080p 和 720p 预览以及最大尺寸 JPEG 的 10 位 HLG10 预览的预览防抖功能。如需详细了解这些要求，请参阅 CDD 的 2.2.7.2. 摄像头部分。

实现

为了支持 API 查询功能组合，请在 ICameraDevice 的版本 3 中实现以下功能组合查询 API：

对于低于 ICameraDevice 接口版本 3 的版本，HAL 应实现 isStreamCombinationSupported 方法。

如需详细了解该 API 所查询的功能组合，请参阅 system/media/camera/docs/metadata_definitions.xml 中的 sessionConfigurationQueryVersion 文档。

如需查看此功能的参考实现，请参阅 hardware/google/camera/devices/EmulatedCamera/hwl/。

公共 API

应用可以使用以下公共 API 查询设备支持的功能组合：

验证

如需验证此功能的实现，请使用以下 VTS、CTS 和摄像头 ITS (CTS 验证程序) 测试：

VTS

CTS

相机 ITS