HarmonyOS相机模块支持相机业务的开发,开发者可以通过已开放的接口实现相机硬件的访问、操作和新功能开发,最常见的操作如:预览、拍照、连拍和录像等。
基本概念
相机静态能力
用于描述相机的固有能力的一系列参数,比如朝向、支持的分辨率等信息。
物理相机
物理相机就是独立的实体摄像头设备。物理相机ID是用于标志每个物理摄像头的唯一字串。
逻辑相机
逻辑相机是多个物理相机组合出来的抽象设备,逻辑相机通过同时控制多个物理相机设备来完成相机某些功能,如大光圈、变焦等功能。逻辑摄像机ID是一个唯一的字符串,标识多个物理摄像机的抽象能力。
帧捕获
相机启动后对帧的捕获动作统称为帧捕获。主要包含单帧捕获、多帧捕获、循环帧捕获。
单帧捕获
指的是相机启动后,在帧数据流中捕获一帧数据,常用于普通拍照。
多帧捕获
指的是相机启动后,在帧数据流中连续捕获多帧数据,常用于连拍。
循环帧捕获
指的是相机启动后,在帧数据流中一直捕获帧数据,常用于预览和录像。
约束与限制
在同一时刻只能有一个相机应用在运行中。
相机模块内部有状态控制,开发者必须按照指导文档中的流程进行接口的顺序调用,否则可能会出现调用失败等问题。
为了开发的相机应用拥有更好的兼容性,在创建相机对象或者参数相关设置前请务必进行能力查询。
相机开发流程
相机模块主要工作是给相机应用开发者提供基本的相机API接口,用于使用相机系统的功能,进行相机硬件的访问、操作和新功能开发。相机的开发流程如图所示:
接口说明
相机模块为相机应用开发者提供了3个包的内容,包括方法、枚举、以及常量/变量,方便开发者更容易地实现相机功能。详情请查阅对应开发场景。
相机权限申请
在使用相机之前,需要申请相机的相关权限,保证应用拥有相机硬件及其他功能权限,相机涉及权限如下表。
相机设备创建
CameraKit类是相机的入口API类,用于获取相机设备特性、打开相机,其接口如下表。
在实现一个相机应用之前必须先创建一个独立的相机设备,然后才能继续相机的其他操作。相机设备创建的建议步骤如下:
1. 通过CameraKit.getInstance(Context context)方法获取唯一的CameraKit对象
private void openCamera(){ // 获取CameraKit对象 CameraKit cameraKit = CameraKit.getInstance(getApplicationContext()); if (cameraKit == null) { // 处理cameraKit获取失败的情况 } }
如果此步骤操作失败,相机可能被占用或无法使用。如果被占用,必须等到相机释放后才能重新获取CameraKit对象。
2. 通过getCameraIds()方法,获取当前使用的设备支持的逻辑相机列表。逻辑相机列表中存储了当前设备拥有的所有逻辑相机ID,如果列表不为空,则列表中的每个ID都支持独立创建相机对象;否则,说明正在使用的设备无可用的相机,不能继续后续的操作。
try { // 获取当前设备的逻辑相机列表 String[] cameraIds = cameraKit.getCameraIds(); if (cameraIds.length <= 0) { HiLog.error(LABEL, "cameraIds size is 0"); } } catch (IllegalStateException e) { // 处理异常 }
还可以继续查询指定相机ID的静态信息:
调用getDeviceLinkType(String physicalId)方法获取物理相机连接方式;
调用getCameraInfo(String cameraId)方法查询相机硬件朝向等信息;
调用getCameraAbility(String cameraId)方法查询相机能力信息(比如支持的分辨率列表等)。
CameraInfo的主要接口
CameraAbility的主要接口
3. 通过createCamera(String cameraId, CameraStateCallback callback, EventHandler handler)方法,创建相机对象,此步骤执行成功意味着相机系统的硬件已经完成了上电。
// 前置相机类型 int frontCamera = CameraInfo.FacingType.CAMERA_FACING_FRONT; // 后置相机类型 int backCamera = CameraInfo.FacingType.CAMERA_FACING_BACK; // 其他相机类型 int otherCamera = CameraInfo.FacingType.CAMERA_FACING_OTHERS; // 选择想要创建的相机类型,如果不存在该类型相机,则返回false boolean isCameraCreated = openCameraByFacingType(frontCamera);
// 根据类型创建相机的方法 private boolean openCameraByFacingType(int facingType) { CameraKit cameraKit = CameraKit.getInstance(getApplicationContext()); for(String cameraId : cameraKit.getCameraIds()) { CameraInfo cameraInfo = cameraKit.getCameraInfo(cameraId); if(facingType == cameraInfo.getFacingType()) { cameraKit.createCamera(cameraId, cameraStateCallback, eventHandler); return true; } } return false; }
参数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();
import ohos.eventhandler.EventHandler; import ohos.eventhandler.EventRunner; // 执行回调的EventHandler EventHandler eventHandler = new EventHandler(EventRunner.create("CameraCb"));
至此,相机设备的创建已经完成。相机设备创建成功会在CameraStateCallback中触发onCreated(Camera camera)回调。在进入相机设备配置前,请确保相机设备已经创建成功。否则会触发相机设备创建失败的回调,并返回错误码,需要进行错误处理后,重新执行相机设备的创建。
相机设备配置
创建相机设备成功后,在CameraStateCallback中会触发onCreated(Camera camera)回调,并且带回Camera对象,用于执行相机设备的操作。
当一个新的相机设备成功创建后,首先需要对相机进行配置,调用configure(CameraConfig)方法实现配置。相机配置主要是设置预览、拍照、录像用到的Surface(详见ohos.agp.graphics.Surface),没有配置过Surface,相应的功能不能使用。
为了进行相机帧捕获结果的数据和状态检测,还需要在相机配置时调用setFrameStateCallback(FrameStateCallback, EventHandler)方法设置帧回调。
// Surface提供对象 private SurfaceProvider surfaceProvider; private void initSurface() { surfaceProvider = new SurfaceProvider(this); DirectionalLayout.LayoutConfig params = new DirectionalLayout.LayoutConfig( ComponentContainer.LayoutConfig.MATCH_PARENT, ComponentContainer.LayoutConfig.MATCH_PARENT); surfaceProvider.setLayoutConfig(params); surfaceProvider.pinToZTop(false); surfaceProvider.getSurfaceOps().get().addCallback(new SurfaceCallBack()); ((ComponentContainer) findComponentById(ResourceTable.Id_surface_container)).addComponent(surfaceProvider); } private FrameStateCallback frameStateCallbackImpl = new FrameStateCallback(){ @Override public void onFrameStarted(Camera camera, FrameConfig frameConfig, long frameNumber, long timestamp) { ... } @Override public void onFrameProgressed(Camera camera, FrameConfig frameConfig, FrameResult frameResult) { ... } @Override public void onFrameFinished(Camera camera, FrameConfig frameConfig, FrameResult frameResult) { ... } @Override public void onFrameError(Camera camera, FrameConfig frameConfig, int errorCode, FrameResult frameResult) { ... } @Override public void onCaptureTriggerStarted(Camera camera, int captureTriggerId, long firstFrameNumber) { ... } @Override public void onCaptureTriggerFinished(Camera camera, int captureTriggerId, long lastFrameNumber) { ... } @Override public void onCaptureTriggerInterrupted(Camera camera, int captureTriggerId) { ... } }; // 相机设备 private Camera cameraDevice; // 相机预览模板 private Surface previewSurface; // 相机配置模板 private CameraConfig.Builder cameraConfigBuilder; // 图像帧数据接收处理对象 private ImageReceiver imageReceiver; private final class CameraStateCallbackImpl extends CameraStateCallback { @Override public void onCreated(Camera camera) { cameraDevice = camera; previewSurface = surfaceProvider.getSurfaceOps().get().getSurface(); cameraConfigBuilder = camera.getCameraConfigBuilder(); if (cameraConfigBuilder == null) { HiLog.error(LABEL, "onCreated cameraConfigBuilder is null"); return; } // 配置预览的Surface cameraConfigBuilder.addSurface(previewSurface); // 配置拍照的Surface cameraConfigBuilder.addSurface(imageReceiver.getRecevingSurface()); // 配置帧结果的回调 cameraConfigBuilder.setFrameStateCallback(frameStateCallbackImpl, eventHandler); try { // 相机设备配置 camera.configure(cameraConfigBuilder.build()); } catch (IllegalArgumentException e) { HiLog.error(LABEL, "Argument Exception"); } catch (IllegalStateException e) { HiLog.error(LABEL, "State Exception"); } } }
相机配置成功后,在CameraStateCallback中会触发onConfigured(Camera camera)回调,然后才可以执行相机帧捕获相关的操作。
CameraConfig.Builder的主要接口