鸿蒙OS 相机设备开发指导

相机开发流程

相机模块主要工作是给相机应用开发者提供基本的相机API接口，用于使用相机系统的功能，进行相机硬件的访问、操作和新功能开发。相机的开发流程如图所示：

图1 相机开发流程

接口说明

相机模块为相机应用开发者提供了3个包的内容，包括方法、枚举、以及常量/变量，方便开发者更容易地实现相机功能。详情请查阅对应开发场景。

相机权限申请

在使用相机之前，需要申请相机的相关权限，保证应用拥有相机硬件及其他功能权限，应用权限的介绍请参考 权限章节，相机涉及权限如下表。

相机设备创建

CameraKit 类是相机的入口 API 类，用于获取相机设备特性、打开相机，其接口如下表。

基于 HarmonyOS 实现一个相机应用，无论将来想应用到哪个或者哪些设备上，都必须先创建一个独立的相机设备，然后才能继续相机的其他操作。相机设备创建的建议步骤如下：

1. 通过 CameraKit.getInstance(Context context) 方法获取唯一的 CameraKit 对象是创建新的相机应用的第一步操作。

   private void openCamera(){
       // 获取CameraKit对象
       CameraKit cameraKit = CameraKit.getInstance(context);
       if (cameraKit == null) {
           // 处理cameraKit获取失败的情况 
       }
   }

如果此步骤操作失败，相机可能被占用或无法使用。如果被占用，必须等到相机释放后才能重新获取CameraKit对象。

1. 通过getCameraIds()方法，获取当前使用的设备支持的逻辑相机列表。逻辑相机列表中存储了当前设备拥有的所有逻辑相机ID，如果列表不为空，则列表中的每个ID都支持独立创建相机对象；否则，说明正在使用的设备无可用的相机，不能继续后续的操作。

   try {
       // 获取当前设备的逻辑相机列表
       String[] cameraIds = cameraKit.getCameraIds();
       if (cameraIds.length <= 0) {
           HiLog.error("cameraIds size is 0");
       }
   } catch (IllegalStateException e) {
       // 处理异常
   }

还可以继续查询指定相机ID的静态信息：

调用getDeviceLinkType(String physicalId)方法获取物理相机连接方式；

调用getCameraInfo(String cameraId)方法查询相机硬件朝向等信息；

调用getCameraAbility(String cameraId)方法查询相机能力信息（比如支持的分辨率列表等）。

1. 通过createCamera(String cameraId, CameraStateCallback callback, EventHandler handler)方法，创建相机对象，此步骤执行成功意味着相机系统的硬件已经完成了上电。

   // 创建相机设备
   cameraKit.createCamera(cameraIds[0], cameraStateCallback, eventHandler);

第一个参数 cameraId 可以是上一步获取的逻辑相机列表中的任何一个相机ID。

第二和第三个参数负责相机创建和相机运行时的数据和状态检测，请务必保证在整个相机运行周期内有效。

   private final class CameraStateCallbackImpl extends CameraStateCallback {
       @Override
       public void onCreated(Camera camera) {
            // 创建相机设备
       }

    
       @Override
       public void onConfigured(Camera camera) {
           // 配置相机设备
       }

    
       @Override
       public void onPartialConfigured(Camera camera) {
           // 当使用了 addDeferredSurfaceSize 配置了相机，会接到此回调
       }

    
       @Override
       public void onReleased(Camera camera) { 
          // 释放相机设备
       }
   }

    
   // 相机创建和相机运行时的回调
   CameraStateCallbackImpl cameraStateCallback = new CameraStateCallbackImpl();
   if(cameraStateCallback ==null) {
       HiLog.error("cameraStateCallback is null");
   }

   import ohos.eventhandler.EventHandler;
   import ohos.eventhandler.EventRunner;

    
   // 执行回调的 EventHandler
   EventHandler eventHandler = new EventHandler(EventRunner.create("CameraCb"));
   if(eventHandler ==null) {
       HiLog.error("eventHandler is null");
   }

至此，相机设备的创建已经完成。相机设备创建成功会在 CameraStateCallback 中触发 onCreated(Camera camera)回调。在进入相机设备配置前，请确保相机设备已经创建成功。否则会触发相机设备创建失败的回调，并返回错误码，需要进行错误处理后，重新执行相机设备的创建。

相机设备配置

创建相机设备成功后，在 CameraStateCallback 中会触发 onCreated(Camera camera)回调，并且带回 Camera 对象，用于执行相机设备的操作。

当一个新的相机设备成功创建后，首先需要对相机进行配置，调用 configure(CameraConfig) 方法实现配置。相机配置主要是设置预览、拍照、录像用到的 Surface(详见 ohos.agp.graphics.Surface)，没有配置过 Surface，相应的功能不能使用。

为了进行相机帧捕获结果的数据和状态检测，还需要在相机配置时调用 setFrameStateCallback(FrameStateCallback, EventHandler)方法设置帧回调。

private final class CameraStateCallbackImpl extends CameraStateCallback {
    @Override
    public void onCreated(Camera camera) {
        cameraConfigBuilder = camera.getCameraConfigBuilder();
        if (cameraConfigBuilder == null) {
            HiLog.error("onCreated cameraConfigBuilder is null");
            return;
        }
        // 配置预览的Surface
        cameraConfigBuilder.addSurface(previewSurface);
        // 配置拍照的Surface
        cameraConfigBuilder.addSurface(imageReceiver.getRecevingSurface());
        // 配置帧结果的回调
        cameraConfigBuilder.setFrameStateCallback(frameStateCallbackImpl, handler);
        try {
            // 相机设备配置
            camera.configure(cameraConfigBuilder.build());
        } catch (IllegalArgumentException e) {
            HiLog.error("Argument Exception");
        } catch (IllegalStateException e) {
            HiLog.error("State Exception");
        }
    }
}

相机配置成功后，在 CameraStateCallback 中会触发 onConfigured(Camera camera)回调，然后才可以执行相机帧捕获相关的操作。

相机帧捕获

Camera 操作类，包括相机预览、录像、拍照等功能接口。

启动预览（循环帧捕获）

用户一般都是先看见预览画面才执行拍照或者其他功能，所以对于一个普通的相机应用，预览是必不可少的。启动预览的建议步骤如下：

1. 通过getFrameConfigBuilder(FRAME_CONFIG_PREVIEW)方法获取预览配置模板，常用帧配置项见下表，更多的帧配置项以及详细使用方法请参考 API 接口说明的 FrameConfig.Builder 部分。

1. 通过 triggerLoopingCapture(FrameConfig)方法实现循环帧捕获(如预览/录像)。

   private final class CameraStateCallbackImpl extends CameraStateCallback {
       @Override
       public void onConfigured(Camera camera) {
           // 获取预览配置模板
           frameConfigBuilder = camera.getFrameConfigBuilder(FRAME_CONFIG_PREVIEW);
           // 配置预览 Surface
           frameConfigBuilder.addSurface(previewSurface);
           previewFrameConfig = frameConfigBuilder.build();
           try {
               // 启动循环帧捕获
               int triggerId = camera.triggerLoopingCapture(previewFrameConfig);
           } catch (IllegalArgumentException e) {
               HiLog.error("Argument Exception");
           } catch (IllegalStateException e) {
               HiLog.error("State Exception");
            }
       }
   }

经过以上的操作，相机应用已经可以正常进行实时预览了。在预览状态下，开发者还可以执行其他操作，比如：

当预览帧配置更改时，可以通过triggerLoopingCapture(FrameConfig)方法实现预览帧配置的更新；

   // 预览帧变焦值变更
   frameConfigBuilder.setZoom(1.2f);
   // 调用triggerLoopingCapture方法实现预览帧配置更新
   triggerLoopingCapture(frameConfigBuilder.build());

通过stopLoopingCapture()方法停止循环帧捕获(停止预览)。

   // 停止预览帧捕获
   camera.stopLoopingCapture(frameConfigBuilder.build())

实现拍照（单帧捕获）

拍照功能属于相机应用的最重要功能之一，而且照片质量对用户至关重要。相机模块基于相机复杂的逻辑，从应用接口层到器件驱动层都已经默认的做好了最适合用户的配置，这些默认配置尽可能地保证用户拍出的每张照片的质量。发起拍照的建议步骤如下：

1. 通过getFrameConfigBuilder(FRAME_CONFIG_PICTURE)方法获取拍照配置模板，并且设置拍照帧配置，如下表：

1. 拍照前准备图像帧数据的接收实现。

   // 图像帧数据接收处理对象       
   private ImageReceiver imageReceiver;
   // 执行回调的 EventHandler
   private EventHandler eventHandler = new EventHandler(EventRunner.create("CameraCb"));
   // 拍照支持分辨率
   private Size pictureSize;

    
   // 单帧捕获生成图像回调 Listener
   private final ImageReceiver.IImageArrivalListener imageArrivalListener = new ImageReceiver.IImageArrivalListener() {
       @Override
       public void onImageArrival(ImageReceiver imageReceiver) {
           StringBuffer fileName = new StringBuffer("picture_"); 
           fileName.append(UUID.randomUUID()).append(".jpg"); // 定义生成图片文件名
           File myFile = new File(dirFile, fileName.toString()); // 创建图片文件
           imageSaver = new ImageSaver(imageReceiver.readNextImage(), myFile); // 创建一个读写线程任务用于保存图片
           eventHandler.postTask(imageSaver); // 执行读写线程任务生成图片
       }
   };

    
   // 保存图片, 图片数据读写，及图像生成见 run 方法
   class ImageSaver implements Runnable {
       private final Image myImage;
       private final File myFile;

    
       ImageSaver(Image image, File file) {
           myImage = image;
           myFile = file;
       }

    
       @Override
       public void run() {
           Image.Component component = myImage.getComponent(ImageFormat.ComponentType.JPEG);
           byte[] bytes = new byte[component.remaining()];
           component.read(bytes);
           FileOutputStream output = null;
           try {
               output = new FileOutputStream(myFile);
               output.write(bytes); // 写图像数据
           } catch (IOException e) {
               HiLog.error("save picture occur exception!");
           } finally {
               myImage.release();
               if (output != null) {
                   try {
                       output.close(); // 关闭流
                   } catch (IOException e) {
                       HiLog.error("image release occur exception!");
                   }
               }
           }
       }
   }
   private void takePictureInit() {
       List<Size> pictureSizes = cameraAbility.getSupportedSizes(ImageFormat.JPEG); // 获取拍照支持分辨率列表
       pictureSize = getpictureSize(pictureSizes) // 根据拍照要求选择合适的分辨率
       imageReceiver = ImageReceiver.create(Math.max(pictureSize.width, pictureSize.height),
           Math.min(pictureSize.width, pictureSize.height), ImageFormat.JPEG, 5); // 创建 ImageReceiver 对象，注意 creat 函数中宽度要大于高度；5 为最大支持的图像数，请根据实际设置。
       imageReceiver.setImageArrivalListener(imageArrivalListener);
   }

1. 通过 triggerSingleCapture(FrameConfig)方法实现单帧捕获(如拍照)。

   private void capture() {
       // 获取拍照配置模板
       framePictureConfigBuilder = cameraDevice.getFrameConfigBuilder(FRAME_CONFIG_PICTURE);
       // 配置拍照 Surface
       framePictureConfigBuilder.addSurface(imageReceiver.getRecevingSurface());
       // 配置拍照其他参数
       framePictureConfigBuilder.setImageRotation(90);
       try {
           // 启动单帧捕获(拍照)
           camera.triggerSingleCapture(framePictureConfigBuilder.build());
       } catch (IllegalArgumentException e) {
           HiLog.error("Argument Exception");
       } catch (IllegalStateException e) {
           HiLog.error("State Exception");
       }
   }

为了捕获到质量更高和效果更好的图片，还可以在帧结果中实时监测自动对焦和自动曝光的状态，一般而言，在自动对焦完成，自动曝光收敛后的瞬间是发起单帧捕获的最佳时机。

实现连拍（多帧捕获）

连拍功能方便用户一次拍照获取多张照片，用于捕捉精彩瞬间。同普通拍照的实现流程一致，但连拍需要使用 triggerMultiCapture(List<FrameConfig> frameConfigs)方法。

启动录像（循环帧捕获）

启动录像和启动预览类似，但需要另外配置录像 Surface 才能使用。

1. 录像前需要进行音视频模块的配置。

   private Source source; // 音视频源
   private AudioProperty.Builder audioPropertyBuilder; // 音频属性
   private VideoProperty.Builder videoPropertyBuilder; // 视频属性
   private StorageProperty.Builder storagePropertyBuilder; // 音视频存储属性
   private Recorder mediaRecorder; // 录像操作对象
   private String recordName; // 音视频文件名

    
   private void initMediaRecorder() {
       HiLog.info("initMediaRecorder begin");
       videoPropertyBuilder.setRecorderBitRate(10000000); // 设置录制比特率
       int rotation = DisplayManager.getInstance().getDefaultDisplay(this).get().getRotation();
       videoPropertyBuilder.setRecorderDegrees(getOrientation(rotation)); // 设置录像方向
       videoPropertyBuilder.setRecorderFps(30); // 设置录制采样率
       videoPropertyBuilder.setRecorderHeight(Math.min(recordSize.height, recordSize.width)); // 设置录像支持的分辨率，需保证 width > height
       videoPropertyBuilder.setRecorderWidth(Math.max(recordSize.height, recordSize.width));
       videoPropertyBuilder.setRecorderVideoEncoder(Recorder.VideoEncoder.H264); // 设置视频编码方式
       videoPropertyBuilder.setRecorderRate(30); // 设置录制帧率
       source.setRecorderAudioSource(Recorder.AudioSource.MIC); // 设置录制音频源
       source.setRecorderVideoSource(Recorder.VideoSource.SURFACE); // 设置视频窗口
       mediaRecorder.setSource(source); // 设置音视频源
       mediaRecorder.setOutputFormat(Recorder.OutputFormat.MPEG_4); // 设置音视频输出格式
       StringBuffer fileName = new StringBuffer("record_"); // 生成随机文件名
       fileName.append(UUID.randomUUID()).append(".mp4");
       recordName = fileName.toString();
       File file = new File(dirFile, fileName.toString()); // 创建录像文件对象
       storagePropertyBuilder.setRecorderFile(file); // 设置存储音视频文件名
       mediaRecorder.setStorageProperty(storagePropertyBuilder.build());
       audioPropertyBuilder.setRecorderAudioEncoder(Recorder.AudioEncoder.AAC); // 设置音频编码格式
       mediaRecorder.setAudioProperty(audioPropertyBuilder.build()); // 设置音频属性
       mediaRecorder.setVideoProperty(videoPropertyBuilder.build()); // 设置视频属性
       mediaRecorder.prepare(); // 准备录制
       HiLog.info("initMediaRecorder end");
   }

1. 配置录像帧，启动录像。

   private final class CameraStateCallbackImpl extends CameraStateCallback {
       @Override
       public void onConfigured(Camera camera) {
           // 获取预览配置模板
           frameConfigBuilder = camera.getFrameConfigBuilder(FRAME_CONFIG_PREVIEW);
           // 配置预览Surface
           frameConfigBuilder.addSurface(previewSurface);
           // 配置录像的Surface
           mRecorderSurface = mediaRecorder.getVideoSurface();
           cameraConfigBuilder.addSurface(mRecorderSurface);
           previewFrameConfig = frameConfigBuilder.build();
           try {
               // 启动循环帧捕获
               int triggerId = camera.triggerLoopingCapture(previewFrameConfig);
           } catch (IllegalArgumentException e) {
               HiLog.error("Argument Exception");
           } catch (IllegalStateException e) {
               HiLog.error("State Exception");
           }
       }
   }

1. 通过 camera.stopLoopingCapture()方法停止循环帧捕获（录像）。

相机设备释放

使用完相机后，必须通过 release() 来关闭相机和释放资源，否则可能导致其他相机应用无法启动。一旦相机被释放，它所提供的操作就不能再被调用，否则会导致不可预期的结果，或是会引发状态异常。

相机设备释放的示例代码如下：

private void releaseCamera() {
    if (camera != null) {
        // 关闭相机和释放资源
        camera.release();
        camera = null;
    }
    // 拍照配置模板置空
    framePictureConfigBuilder = null;
    // 预览配置模板置空
    previewFrameConfig = null;
}