HarmonyOS 6 自定义人脸识别模型7：相机C++ API能力介绍

在前面文章《HarmonyOS 6 自定义人脸识别模型5：NDK相机预览实现》实现了基于XComponent实现的基础的相机预览功能，但是只有预览没有任何的时机作用。在 HarmonyOS 相机系统开发中，通过 NDK (C/C++) 层接入相机 API 赋予了开发者更高性能与更底层的硬件控制权，尤其是当我们需要集成依赖 C++ 实时处理的算法（如自定义人脸识别模型）或更精细的相机控制时，直接调用 C++ Camera API 将能够避免频繁的跨语言（ArkTS <-> C++）开销，大幅提升采集流水线的效率。

本文我们以拍照、录制视频、对焦等常用功能为例，对其中涉及到的 HarmonyOS 系统相机 C++ API (NDK) 能力及核心系统函数原型进行详细地梳理和介绍。

1. 核心会话与模式控制 API

在应用的 ArkTS 层，根据业务需求，需要动态切换正在使用的相机模式（图库、拍照或录像），前面文章已经介绍了基于的预览实现，主要原理是配置相机后设置相机的输出管道，将相机输出内容一份关联到XComponent中，一份给编码器。主要涉及到一下API：

• 底层 C++ 能力：它依赖于
  CaptureSession 层面对资源配置的管理能力：
  • 添加/移除 Output：使用 OH_CaptureSession_AddPhotoOutput 和 OH_CaptureSession_AddVideoOutput 来动态装载输出流模块，或者用 OH_CaptureSession_RemovePhotoOutput 卸载。
  • 动态提交：调用 OH_CaptureSession_BeginConfig(...)、OH_CaptureSession_CommitConfig(...) 和 OH_CaptureSession_Start(...) 生效这套全新的流组合配置。在这个过程中，不仅使得相机的会话能在不同模式间无缝切换，还支持同时携带多种输出流（如 Preview + Photo，或是 Preview + Video + Photo）。
• 涉及到系统 API 原型如下：

  Camera_ErrorCode OH_CaptureSession_BeginConfig(Camera_CaptureSession* session);
  Camera_ErrorCode OH_CaptureSession_CommitConfig(Camera_CaptureSession* session);
  Camera_ErrorCode OH_CaptureSession_Start(Camera_CaptureSession* session);
  Camera_ErrorCode OH_CaptureSession_AddPhotoOutput(Camera_CaptureSession* session, Camera_PhotoOutput* dest);
  Camera_ErrorCode OH_CaptureSession_AddVideoOutput(Camera_CaptureSession* session, Camera_VideoOutput* dest);
  Camera_ErrorCode OH_CaptureSession_RemovePhotoOutput(Camera_CaptureSession* session, Camera_PhotoOutput* dest);
  

2. 视频流控制 API

在录制视频时，需要API 用于处理录像模式下数据流生命周期的控制。

• 底层 C++ 能力：分别封装自宏观的 OH_VideoOutput_Start 与 OH_VideoOutput_Stop / OH_VideoOutput_Release。
  • 启动推流（videoOutputStart）：当用户真正点击界面的“录制”按钮时，该接口开始将相机数据推送给下方的视频编码器（Recorder）或者特定的 Surface。
  • 销毁并释放（videoOutputStopAndRelease）：中断写入，停止数据流并将创建的对应底层 VideoOutput 实例完全销毁，释放相机对编码、媒体写入资源的锁定。
• 涉及到系统 API 原型：

    Camera_ErrorCode OH_VideoOutput_Start(Camera_VideoOutput* videoOutput);
    Camera_ErrorCode OH_VideoOutput_Stop(Camera_VideoOutput* videoOutput);
    Camera_ErrorCode OH_VideoOutput_Release(Camera_VideoOutput* videoOutput);

在录制前，视频流需要明确尺寸比例与帧率等规范参数。

• 底层 C++ 能力：通过查询 Camera_OutputCapability（涵盖相机所有支持的流的能力信息）中解析 videoProfiles (即 Camera_VideoProfile 列表)。
• 从 Camera_VideoProfile 中不仅能获取视频分辨率的 size.width 及 size.height 以配合 UI 的宽高比 (ratioXC) 需求选取最佳尺寸，还可以获取 range.min（如帧率支持情况），使得应用和媒体写入容器能适配最精准的参数。

3. 图像捕获控制 API

在拍照场景，在预览就绪时点击按钮调用图像捕获截图进行拍照。

• 底层 C++ 能力：对应于 OH_PhotoOutput_Capture(photoOutput_)。它使用默认相机的默认图像质量、方向参数等，快速将当前光学画面捕获成相片并送入绑定的 SurfaceID，从而触发上层应用的回调事件实现图像的持久化。
• 涉及系统 API 原型：

Camera_ErrorCode OH_PhotoOutput_Capture(Camera_PhotoOutput* photoOutput);

在实际业务场景下，图片可能包含地理位置打卡、镜头翻转（如前置自拍防镜像）、不同图片质量的需求，系统API提供了带参捕获的方法：

• 底层 C++ 能力：其调用了极度灵活的 OH_PhotoOutput_Capture_WithCaptureSetting 方法。底层通过传入 Camera_PhotoCaptureSetting，实现：
  • 图片旋转 (Rotation) 和 镜像 (Mirror)：解决不同镜头模组或用户取向视角的问题。
  • EXIF地理信息 (Location)：传入自定义装配的 Camera_Location（经纬度与海拔）至图像元数据中。
  • 图片质量控制 (Quality)：直接调配底层 ISP 压缩的质量比重。
• 涉及系统 API 原型：

Camera_ErrorCode OH_PhotoOutput_Capture_WithCaptureSetting(Camera_PhotoOutput* photoOutput, Camera_PhotoCaptureSetting setting);

4. 曝光与对焦参数调节 API

大部分的相机应用都提供了点击屏幕对相机进行对焦，HarmonyOS 系统API提供了对应的能力，这部分接口代表了高级硬件管控能力（高级 3A 操作：AE、AF、AWB 控制），将用户丰富的界面手势交互（如点击、滑动）转变为底层 ISP 控制命令。

设置对焦对标和测光参考点接口：

• 底层 C++ 能力：实现基于坐标的点击对焦与点击测光。
  • 使用 OH_CaptureSession_SetFocusPoint(session, focusPoint) 发送对焦坐标到传感器模块；
  • 使用 OH_CaptureSession_SetMeteringPoint(session, exposurePoint) 调整画面特定测光参考点，保证目标主体的曝光精确。
• 涉及系统 API 原型：

    Camera_ErrorCode OH_CaptureSession_SetFocusPoint(Camera_CaptureSession* session, Camera_Point focusPoint);
   Camera_ErrorCode OH_CaptureSession_SetMeteringPoint(Camera_CaptureSession* session, Camera_Point exposurePoint);

此外系统API还提供了曝光补偿控制，通过响应用户在画面上下滑动的手势设置曝光补偿：

• 底层 C++ 能力：调用 OH_CaptureSession_GetExposureBiasRange 获取该设备镜头支持的最大（Max）、最小（Min）曝光补偿阈值及步长（Step），然后使用 OH_CaptureSession_SetExposureBias 去设定实际数值。从而提高或降低画面的整体亮度进光量，适用于强逆光或背光补救。
• 涉及系统 API 原型：

    Camera_ErrorCode OH_CaptureSession_GetExposureBiasRange(Camera_CaptureSession* session, float* minExposureBias, float* maxExposureBias, float* step);
    Camera_ErrorCode OH_CaptureSession_SetExposureBias(Camera_CaptureSession* session, float exposureBias);

在光照快速变换场景，系统提供了设置曝光模式的方法：

• 底层 C++ 能力：依赖 OH_CaptureSession_IsExposureModeSupported 和 OH_CaptureSession_SetExposureMode。能够赋予相机固定曝光模式（Locked）或持续自动曝光（Continuous Auto Exposure），非常适合处理光照快速变幻的任务场景。
• 涉及系统 API 原型：

    Camera_ErrorCode OH_CaptureSession_IsExposureModeSupported(Camera_CaptureSession* session, Camera_ExposureMode exposureMode, bool* isSupported);
    Camera_ErrorCode OH_CaptureSession_SetExposureMode(Camera_CaptureSession* session, Camera_ExposureMode exposureMode);

5. 辅助与稳定系统 API

系统还提供了辅助性API，比如焦距控制：

• 底层 C++ 能力：通过先使用 OH_CaptureSession_GetZoomRatioRange 得到硬件的最大最小光学/算法变焦范围，再调用 OH_CaptureSession_SetZoomRatio 生效变焦值。支持应用层面实时的画面缩放操控。
• 涉及系统 API 原型：

  Camera_ErrorCode OH_CaptureSession_GetZoomRatioRange(Camera_CaptureSession* session, float* minZoom, float* maxZoom);
  Camera_ErrorCode OH_CaptureSession_SetZoomRatio(Camera_CaptureSession* session, float zoom);
  

闪光灯探测与控制：

• 底层 C++ 能力：封装了对闪光灯硬件特性的三步验证逻辑：
  1. OH_CaptureSession_HasFlash：探测当前设备是否存在物理闪光灯或者前置屏幕补光。
  2. OH_CaptureSession_IsFlashModeSupported：查验是否支持特定的闪光策略（如自动闪光、常亮、去红眼等）。
  3. OH_CaptureSession_SetFlashMode 与 OH_CaptureSession_GetFlashMode 实装和校验策略。
• 系统 API 原型：

    Camera_ErrorCode OH_CaptureSession_HasFlash(Camera_CaptureSession* session, bool* hasFlash);
    Camera_ErrorCode OH_CaptureSession_IsFlashModeSupported(Camera_CaptureSession* session, Camera_FlashMode flashMode, bool* isSupported);
    Camera_ErrorCode OH_CaptureSession_SetFlashMode(Camera_CaptureSession* session, Camera_FlashMode flashMode);

目前旗舰设备均搭载了OIS（光学防抖）或EIS（电子防抖）。

• 底层 C++ 能力：调用 OH_CaptureSession_IsVideoStabilizationModeSupported 测试特定的防抖类型，并通过 OH_CaptureSession_SetVideoStabilizationMode 进行设置，确保采集视频时面对强抖动环境，输出帧依然具备优秀的过渡平滑度。
• 系统 API 原型：

    Camera_ErrorCode OH_CaptureSession_IsVideoStabilizationModeSupported(Camera_CaptureSession* session, Camera_VideoStabilizationMode videoMode, bool* isSupported);
    Camera_ErrorCode OH_CaptureSession_SetVideoStabilizationMode(Camera_CaptureSession* session, Camera_VideoStabilizationMode videoMode);

总结

通过以上对相机 C++ (NDK) 核心操作的封装，不仅让基于 ArkTS 构建的鸿蒙应用具备了极强的定制相机基础操作能力（对焦、曝光、闪光灯或防抖等），还能与包含 NDK 图像或视频缓冲区的 C++ 面部识别网络进行同内存层的无缝结合。这使得复杂的计算机视觉类应用，可以在 HarmonyOS 上具备既顺畅又低延迟的极佳体验。