HarmonyOS相机模块支持相机业务的开发,开发者可以通过已开放的接口实现相机硬件的访问、操作和新功能开发,最常见的操作如:预览、拍照、连拍和录像等。
相机模块主要工作是给相机应用开发者提供基本的相机API接口,用于使用相机系统的功能,进行相机硬件的访问、操作和新功能开发。相机的开发流程如图所示:
相机模块为相机应用开发者提供了3个包的内容,包括方法、枚举、以及常量/变量,方便开发者更容易地实现相机功能。详情请查阅对应开发场景。
包名 | 功能 |
---|---|
ohos.media.camera.CameraKit | 相机功能入口类。获取当前支持的相机列表及其静态能力信息,创建相机对象。 |
ohos.media.camera.device | 相机设备操作类。提供相机能力查询、相机配置、相机帧捕获、相机状态回调等功能。 |
ohos.media.camera.params | 相机参数类。提供相机属性、参数和操作结果的定义。 |
在使用相机之前,需要申请相机的相关权限,保证应用拥有相机硬件及其他功能权限,相机涉及权限如下表。
权限名称 | 权限属性值 | 是否必选 |
---|---|---|
相机权限 | ohos.permission.CAMERA | 必选 |
录音权限 | ohos.permission.MICROPHONE | 可选(需要录像时申请) |
存储权限 | ohos.permission.WRITE_MEDIA | 可选(需要保存图像及视频到设备的外部存储时申请) |
位置权限 | ohos.permission.MEDIA_LOCATION | 可选(需要保存图像及视频位置信息时申请) |
CameraKit类是相机的入口API类,用于获取相机设备特性、打开相机,其接口如下表。
接口名 | 描述 |
---|---|
createCamera(String cameraId, CameraStateCallback callback, EventHandler handler) | 创建相机对象。 |
getCameraAbility(String cameraId) | 获取指定逻辑相机或物理相机的静态能力。 |
getCameraIds() | 获取当前逻辑相机列表。 |
getCameraInfo(String cameraId) | 获取指定逻辑相机的信息。 |
getInstance(Context context) | 获取CameraKit实例。 |
registerCameraDeviceCallback(CameraDeviceCallback callback, EventHandler handler) | 注册相机使用状态回调。 |
unregisterCameraDeviceCallback(CameraDeviceCallback callback) | 注销相机使用状态回调。 |
在实现一个相机应用之前必须先创建一个独立的相机设备,然后才能继续相机的其他操作。相机设备创建的建议步骤如下:
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的主要接口
接口名 | 描述 |
---|---|
getDeviceLinkType(String physicalId) | 获取物理相机连接方式。 |
getFacingType() | 获取相机朝向信息。 |
getLogicalId() | 获取逻辑相机ID。 |
getPhysicalIdList() | 获取对应的物理相机ID列表。 |
CameraAbility的主要接口
接口名 | 描述 |
---|---|
getSupportedSizes(int format) | 根据格式查询输出图像的分辨率列表。 |
getSupportedSizes(Class<T> clazz) | 根据Class类型查询分辨率列表。 |
getParameterRange(ParameterKey.Key<T> parameter) | 获取指定参数能够设置的值范围。 |
getPropertyValue(PropertyKey.Key<T> property) | 获取指定属性对应的值。 |
getSupportedAeMode() | 获取当前相机支持的自动曝光模式。 |
getSupportedAfMode() | 获取当前相机支持的自动对焦模式。 |
getSupportedFaceDetection() | 获取相机支持的人脸检测类型范围。 |
getSupportedFlashMode() | 当前相机支持的闪光灯取值范围。 |
getSupportedParameters() | 当前相机支持的参数设置。 |
getSupportedProperties() | 获取当前相机的属性列表。 |
getSupportedResults() | 获取当前相机支持的参数设置可返回的结果列表。 |
getSupportedZoom() | 获取相机支持的变焦范围。 |
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的主要接口
接口名 | 描述 |
---|---|
addSurface(Surface surface) | 相机配置中增加Surface。 |
build() | 相机配置的构建类。 |
removeSurface(Surface surface) | 移除先前添加的Surface。 |
setFrameStateCallback(FrameStateCallback callback, EventHandler handler) | 设置用于相机帧结果返回的FrameStateCallback和Handler。 |
addDeferredSurfaceSize(Size surfaceSize, Class<T> clazz) | 添加延迟Surface的尺寸、类型。 |
addDeferredSurface(Surface surface) | 设置延迟的Surface,此Surface的尺寸和类型必须和使用addDeferredSurfaceSize配置的一致。 |