📚 课程目录第3章多Camera HAL配置文件结构

3、多Camera HAL配置文件结构：XML/JSON配置文件的作用、Camera ID映射、物理Camera与逻辑Camera

在多Camera系统中，HAL配置文件是连接Android框架与底层硬件驱动的桥梁。本章深入剖析配置文件的结构设计、Camera ID的映射机制，以及物理Camera与逻辑Camera的协同关系，帮助开发者精准定位配置问题。

3.1 配置文件的作用与格式选择

Android Camera HAL通过配置文件定义设备支持的Camera数量、类型、能力及拓扑关系。主流格式为XML和JSON，两者在可读性、解析效率和扩展性上各有侧重。

特性	XML	JSON
可读性	标签结构清晰，适合复杂层级	轻量简洁，数组表达直观
解析性能	DOM/SAX解析，内存占用较高	原生JSON解析器，效率更高
类型支持	属性值均为字符串，需额外转换	原生支持数字、布尔、数组
扩展性	通过XSD可严格校验	Schema校验相对宽松
Android生态	传统HAL（如camera_provider）常用	新项目（如Camera HAL3）逐渐采纳

实践建议：在兼容性调试阶段，优先使用JSON格式。其数组结构能更自然地表达多Camera拓扑，且解析错误率低于XML。若需兼容旧版Android（如Android 9以下），则保留XML解析路径。

3.2 Camera ID映射机制

Camera ID是Android框架识别Camera设备的唯一标识。在多Camera系统中，ID映射涉及三个层面：物理ID、逻辑ID和框架可见ID。

  核心映射规则：
  物理Camera ID：由HAL层直接分配，对应硬件传感器（如IMX586、OV64B）。
逻辑Camera ID：由配置文件定义，组合多个物理Camera实现多摄功能（如广角+主摄）。
框架可见ID：通过camera_provider服务注册到Android框架，应用层通过CameraManager.getCameraIdList()获取。

以下是一个典型的JSON配置文件片段，展示ID映射关系：

{
  "cameras": [
    {
      "id": 0,
      "type": "LOGICAL",
      "physicalCameras": [1, 2],
      "facing": "BACK",
      "capabilities": ["BACKWARD_COMPATIBLE", "LOGICAL_MULTI_CAMERA"]
    },
    {
      "id": 1,
      "type": "PHYSICAL",
      "sensorName": "IMX586",
      "facing": "BACK",
      "role": "WIDE"
    },
    {
      "id": 2,
      "type": "PHYSICAL",
      "sensorName": "OV64B",
      "facing": "BACK",
      "role": "ULTRA_WIDE"
    }
  ]
}

常见陷阱：ID冲突是调试中最频繁的问题。若物理Camera ID与逻辑Camera ID重叠，框架会拒绝注册。务必保证所有ID在全局唯一，且逻辑Camera的ID不能与任何物理Camera ID重复。

3.3 物理Camera与逻辑Camera的拓扑结构

物理Camera代表真实的硬件传感器，逻辑Camera则是对多个物理Camera的抽象组合。理解两者的关系是配置多Camera系统的关键。

3.4 配置文件中的关键字段解析

无论是XML还是JSON，配置文件都包含一组核心字段，用于定义Camera的行为和约束。

字段名	类型	说明	示例值
`id`	int	Camera唯一标识符	0, 1, 2
`type`	string	Camera类型：PHYSICAL / LOGICAL	"LOGICAL"
`facing`	string	朝向：BACK / FRONT / EXTERNAL	"BACK"
`physicalCameras`	array	逻辑Camera包含的物理Camera ID列表	[1, 2]
`sensorName`	string	物理Camera的传感器型号	"IMX586"
`role`	string	物理Camera在逻辑组合中的角色	"WIDE"
`capabilities`	array	Camera支持的能力列表	["BACKWARD_COMPATIBLE", "LOGICAL_MULTI_CAMERA"]

3.5 多Camera配置的调试流程

当多Camera系统出现兼容性问题时，按以下步骤排查配置文件：

验证ID唯一性：使用adb shell dumpsys media.camera检查注册的Camera列表，确认无ID冲突。
检查物理Camera角色：确保每个物理Camera的role字段在逻辑Camera的physicalCameras列表中正确匹配。
确认能力声明：逻辑Camera必须包含LOGICAL_MULTI_CAMERA能力，否则框架不会启用多摄模式。
验证传感器兼容性：同一逻辑Camera下的物理Camera应具有相似的输出尺寸和帧率，避免同步失败。
测试应用层调用：使用Camera2Basic示例应用，验证CameraCharacteristics.getPhysicalCameraIds()返回正确。

  调试工具推荐：
  adb shell dumpsys media.camera：查看当前注册的Camera设备列表及配置。
adb logcat -s CameraService：过滤Camera服务日志，定位配置解析错误。
adb shell cat /vendor/etc/camera/camera_config.xml：直接查看设备上的配置文件。

3.6 常见配置错误与解决方案

错误现象	可能原因	解决方案
应用无法获取逻辑Camera	逻辑Camera ID与物理Camera ID冲突	重新分配ID，确保逻辑Camera ID不与任何物理Camera ID重复
多摄模式无法启动	逻辑Camera缺少`LOGICAL_MULTI_CAMERA`能力	在`capabilities`数组中添加该能力
物理Camera角色不匹配	`role`字段拼写错误或未定义	使用标准角色值：WIDE, ULTRA_WIDE, TELE, MACRO
传感器同步失败	物理Camera输出尺寸/帧率不一致	统一配置输出参数，或使用HAL层的同步机制

重要提示：修改配置文件后，必须重启cameraserver进程或重启设备才能生效。使用adb shell killall cameraserver可快速重启Camera服务，无需完整重启系统。