合作咨询
我们的专家服务团队将竭诚为您提供专业的合作咨询服务
Class Info |
|---|
模式操作类。 特定的拍摄场景对应特定的模式,模式对象仅能通过如下方法获取: 使用CameraKit.createMode(String, int, ModeStateCallback, Handler)创建模式对象,并通过 ModeStateCallback 进行模式状态的回调。 使用CameraKit.changeMode(Mode, int, ModeStateCallback)切换模式对象,并通过 ModeStateCallback 进行模式状态的回调模式的操作流程建议为:
模式使用的简单代码示例如下: // 创建全局的动作状态回调
final ActionStateCallback stateCallback = new ActionStateCallback() {
public void onPreview(Mode mode, @PreviewResult.State int state, @Nullable PreviewResult result) {
}
public void onTakePicture(Mode mode,@PreviewResult.State int state, @Nullable TakePictureResult result) {
}
};
// 创建全局的动作数据回调
final ActionDataCallback dataCallback = new ActionDataCallback() {
public void onImageAvailable(Mode mode, int id, Image image) {
}
};
// 创建全局的模式状态回调
ModeStateCallback callback = new ModeStateCallback() {
public void onCreated(Mode mode) {
// 模式创建成功并配置模式
ModeConfig.Builder builder = mode.getModeConfigBuilder();
builder.setStateCallback(stateCallback, handler)
builder.setDataCallback(dataCallback, handler)
builder.addPreviewSurface(surface);
mode.configure();
}
public void onConfigured(Mode mode) {
// 模式配置成功,可以操作模式
mode.startPreview();
}
};
// 开始创建模式
CameraKit.getInstance(context).createMode(id, Mode.Type.BOKEH_MODE, callback, handler);
Since: 2019-06-11 |
Modifier and Type | Class and Description |
|---|---|
static interface | 设置动作下发状态的返回码。 |
static interface | 模式的类型。 |
Modifier and Type | Method and Description |
|---|---|
void | 配置模式参数。 |
java.lang.String | 获取当前模式的逻辑摄像头ID。 特别需要注意的是,当模式被完全释放的时候(调用完release()且ModeStateCallback.onReleased(com.huawei.camera.camerakit.Mode)回调结束), 模式不再可用,此时获得的逻辑摄像头ID是不可信的。 |
| 获取模式对应的静态参数。 | |
| 获取模式构造器对象。 | |
int | getType() 获取当前模式的类型。 |
void | 暂停录像动作。 |
void | release() 释放模式对象及资源。 |
void | 恢复继续录像动作。 |
int | setBeauty(int type, int level) 设置美颜的类型和以及对应的级别。 |
int | setColorMode(int colorMode) 设置色彩模式类型。 |
int | setFaceDetection(int type, boolean isEnable) 设置人脸检测或笑脸检测功能,数据结果以回调方式返回。 |
int | setFlashMode(int flashMode) 设置闪光灯模式。 |
int | setFocus(int focusMode, android.graphics.Rect rect) 设置对焦。 |
int | setImageRotation(int degrees) 设置图片旋转角度,用于纠正HAL层图片旋转信息。 |
int | setLocation(android.location.Location location) 设置地理位置信息。 |
<T> int | setParameter(android.hardware.camera2.CaptureRequest.Key<T> key, T value) 设置模式参数。 |
<T> int | setParameters(java.util.Map<android.hardware.camera2.CaptureRequest.Key<T>,T> params) 批量设置模式参数。 |
int | setSceneDetection(boolean isEnable) 设置自动场景检测,数据结果以回调方式返回。 |
int | setZoom(float value) 设置变焦。 |
void | 启动预览。 |
void | 开始录像动作。 |
void | startRecording(java.io.File file) 启动录像动作,把录像文件保存在指定的文件中。 |
void | 停止拍摄动作,可用于停止连拍、超级夜景等动作。 |
void | 停止预览。 |
void | 停止录像动作。 |
void | 拍摄一张照片,结果数据以回调方式通知。 |
void | takePicture(java.io.File file) 拍摄一张照片,并保存成指定的文件。 |
void | 连续拍摄多张照片,结果数据以回调方式通知。 |
void | takePictureBurst(java.io.File file) 连续拍摄多张照片,并保存到指定的目录下。 |
Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method |
|---|
public ModeCharacteristics getModeCharacteristics() 获取模式对应的静态参数。 用法参见ModeCharacteristics。 |
Returns:
Type | Description |
|---|---|
相机静态能力,如果设备ID无效,模式类型错误,或者查询失败则返回null。 |
Method |
|---|
public ModeConfig.Builder getModeConfigBuilder() 获取模式构造器对象。 |
Returns:
Type | Description |
|---|---|
ModeConfig.Builder 模式构建模板类。 |
Method |
|---|
public void configure() 配置模式参数。 当一个新的模式成功创建后,首先需要对模式进行配置,在configure前需要调用getModeConfigBuilder()获取 ModeConfig.Builder实例进行配置,模式配置中主要是设置预览、拍照、录像用到的Surface。其中预览的surface必须配置, 其他可以选择性配置。没有配置过Surface,相应的功能也不能使用。建议操作流程为:
此外,可以重新加入相应的Surface,再次配置模式以获得功能的支持。 在模式配置时,会对模式配置参数做有效性的检测,非法的参数或是无效的参数可能引发异常,如previewSurface为空, 则会抛出IllegalArgumentException异常。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalArgumentException | 如果配置参数无效。 |
Method |
|---|
public void release() 释放模式对象及资源。 一旦模式被释放,他所提供的动作就不能再被调用,否则会获得不可预期的结果,或是会引发状态异常。 |
Method |
|---|
public void startPreview() 启动预览。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常,重复调用将被忽略成无效操作。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 如果模式没有成功配置。 |
Method |
|---|
public void stopPreview() 停止预览。 如果之前没有调用ModeStateCallback.onConfigured(com.huawei.camera.camerakit.Mode)成功配置过模式,调用此函数或重复调用, 将被忽略成无效操作。 |
Method |
|---|
public void takePicture(@NonNull java.io.File file) 拍摄一张照片,并保存成指定的文件。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。 正常的拍照以回调方式通知,分别是ActionStateCallback.TakePictureResult.State.CAPTURE_COMPLETED和 ActionStateCallback.TakePictureResult.State.CAPTURE_FILE_SAVED回调。 限制1:连续拍照的间隔必须是要等上一张照片拍完后才能下发下一张照片的动作,开发者应该监听 ActionStateCallback.TakePictureResult.State.CAPTURE_COMPLETED状态,违反此限制的行为将导致第二次的拍照动作不能成功。 限制2:在拍照的过程中会忽略掉其他动作的响应,这个行为视具体模式而定。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
file | 拍照得到图片的全路径(路径+文件名),空入参引发空指针异常。无效的或不可访问的文件路径会通过onError回调返回错误信息。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void takePicture() 拍摄一张照片,结果数据以回调方式通知。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。 正常的拍照以回调方式通知,分别是ActionStateCallback.TakePictureResult.State.CAPTURE_COMPLETED ActionDataCallback.onImageAvailable(com.huawei.camera.camerakit.Mode, int, android.media.Image)以及回调。 限制1:连续拍照的间隔必须是要等上一张照片拍完后才能下发下一张照片的动作,开发者应该监听 ActionStateCallback.TakePictureResult.State.CAPTURE_COMPLETED状态,违反此限制的行为将导致第二次 的拍照动作不能成功。 限制2:在拍照的过程中会忽略掉其他动作的响应,这个行为视具体模式而定。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void takePictureBurst(@NonNull java.io.File file) 连续拍摄多张照片,并保存到指定的目录下。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。 连拍过程中每次拍摄的结果以回调方式通知,ActionStateCallback.BurstResult.State.BURST_ONCE回调。 连拍结束的信息以回调方式通知,开发者应监听ActionStateCallback.BurstResult.State.BURST_COMPLETED回调, 在收到该连拍结束的回调后,才能进行下次拍照或连拍,否则将导致第二次的拍照动作不能成功。 限制1:连拍过程中,不响应普通的拍照动作,重复下发连拍动作会被忽略。 限制2:在拍照的过程中会忽略掉其他动作的响应,这个行为视具体模式而定。调用stopPicture()停止连拍。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
file | 拍照得到图片的存储路径,空入参引发空指针异常。无效的或不可访问的文件路径会通过onError回调返回错误信息。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void takePictureBurst() 连续拍摄多张照片,结果数据以回调方式通知。 此函数的合法调用必须确保以下三个条件:
非合法的调用会引起状态异常或是非法调用异常。 连拍过程中每次拍摄的结果以回调方式通知,分别是ActionDataCallback.onImageAvailable(com.huawei.camera.camerakit.Mode, int, android.media.Image)以及 ActionStateCallback.BurstResult.State.BURST_ONCE回调。 连拍结束的信息以回调方式通知,开发者应监听ActionStateCallback.BurstResult.State.BURST_COMPLETED回调, 在收到该连拍结束的回调后,才能进行下次拍照或连拍,否则将导致第二次的拍照动作不能成功。 限制1:连拍过程中,不响应普通的拍照动作,重复下发连拍动作会被忽略。 限制2:在拍照的过程中会忽略掉其他动作的响应,这个行为视具体模式而定。调用stopPicture()停止连拍。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void stopPicture() 停止拍摄动作,可用于停止连拍、超级夜景等动作。 如果在连拍状态下调用,在模式内部拍照停止的时候会以ActionStateCallback.BurstResult.State.BURST_COMPLETED 通知,此通知可以作为连拍停止的信号。此外夜景也可以通过这个函数停止。 如果之前没有调用ModeStateCallback.onConfigured(com.huawei.camera.camerakit.Mode)成功配置过模式,将被忽略成无效操作。 |
Method |
|---|
public void startRecording() 开始录像动作。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。在录像过程中是否支持拍照视具体模式而定。 开发者可以通过ModeCharacteristics.isCaptureSupported()查询是否支持 建议用户在调用该方法后,接着调编码器对应的方法,例如MediaRecorder.start() 限制:在录像过程中会忽略掉其他动作的响应,这个行为视具体模式而定。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void startRecording(@NonNull java.io.File file) 启动录像动作,把录像文件保存在指定的文件中。 此函数的合法调用必须确保以下四个条件:
非法的调用会引起状态异常或是非法调用异常。在录像过程中是否支持拍照视具体模式而定。 开发者可以通过ModeCharacteristics.isCaptureSupported()查询是否支持 用户在调用该方法后,不需要对编码器进行操作,Kit内部会自行编码,并且使用之前须进行相机、录制和写权限的检查,确保权限处于开启状态。 限制:在录像过程中会忽略掉其他动作的响应,这个行为视具体模式而定;同一个手机平台,可能支持多个帧率,帧率越大,一次录制处理时间越长。 使用限制: 该接口当前只支持超慢模式的视频录制,当超慢工作在手动模式下,则只需要调用该接口即可完成一次录制, 此时录制过程中不可以人为停止(程序退出或调用stopRecording()),否则录制视频失败;当超慢工作在自动模式下, 即运动检测触发录制,在下发检测区域RequestKey.HW_SUPER_SLOW_CHECK_AREA后,调用该接口后进入运动检测, 在返回ActionStateCallback.RecordingResult.State.RECORDING_STARTED之前,可调用stopRecording() 停止本次录制,若是录制开始后,中途也不应该人为停止,否则同样会录制失败。 录制开始后或者运动检测期间,用户下发的对焦、变焦、闪光灯等操作不起作用,用户也不应该这么做。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
file | 录像文件的存储路径。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
java.lang.UnsupportedOperationException | 当前模式不支持录像操作。 |
Since:
API版本 VersionInfo.API_LEVEL_1以上
Method |
|---|
public void pauseRecording() 暂停录像动作。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。多次调用该函数则无效处理,被忽略。 建议用户在调用该方法后,接着调编码器对应的方法,例如MediaRecorder.pause()。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void resumeRecording() 恢复继续录像动作。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。该操作只会在暂停状态才有效,其他状态无效。 建议用户在调用该方法后,接着调编码器对应的方法,例如MediaRecorder.resume()。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public void stopRecording() 停止录像动作。 此函数的合法调用必须确保以下三个条件:
非法的调用会引起状态异常或是非法调用异常。多次调用该函数则无效处理,被忽略。 建议用户在调用该方法后,接着调编码器对应的方法,例如MediaRecorder.stop()。 |
Throws:
Throw Name | Throw Description |
|---|---|
java.lang.IllegalStateException | 非预览状态下调用会抛出状态异常。 |
Method |
|---|
public int setFocus(int focusMode, android.graphics.Rect rect) 设置对焦。 此函数的合法调用必须同时满足以下条件:
若传入区域为空,自动对焦的区域为整个预览区域,此时由于没有明确焦点,会影响大光圈虚化效果。 此动作对应的状态是ActionStateCallback.FocusResult.State.FOCUS_SUCCEED。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
focusMode | 对焦模式,必须是在支持的对焦模式范围,可通过 ModeCharacteristics.getSupportedAutoFocus()查询。无效的对焦模式,将被忽略。 |
rect | 对焦矩形区域,可以为空。如果传入的是空对象,则使用自动对焦。 采用中心坐标系,坐标系范围从(-1000, -1000)到(1000, 1000)。 其范围及方向总是和相机预览保持一致,不受缩放,旋转方向等的影响。 如果矩形区域不在合法区间内,则触摸对焦不生效。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
See Also:
Method |
|---|
public int setZoom(float value) 设置变焦。 此函数的合法调用必须确保以下条件:
|
Parameters:
Parameter Name | Parameter Description |
|---|---|
value | 变焦值,必须是在支持的变焦范围内, 可通过ModeCharacteristics.getSupportedZoom()查询。无效的变焦,将被忽略。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
Method |
|---|
public int setFlashMode(int flashMode) 设置闪光灯模式。 此函数的合法调用必须确保以下条件:
|
Parameters:
Parameter Name | Parameter Description |
|---|---|
flashMode | 闪光灯模式,必须是在支持的闪光灯范围内,可通过 ModeCharacteristics.getSupportedFlashMode()查询。无效的闪光灯模式,将被忽略。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
Method |
|---|
public int setFaceDetection(int type, boolean isEnable) 设置人脸检测或笑脸检测功能,数据结果以回调方式返回。 此函数的合法调用必须确保以下两个条件:
非法调用会被忽略。 人脸检测的结果是以ActionStateCallback.onFaceDetection(Mode, int, ActionStateCallback.FaceDetectionResult) 通知的,开发者可以在ActionStateCallback.FaceDetectionResult 获取检测到的信息。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
type | 人脸检测的类型,取值参见Metadata.FaceDetectionType,使用前需要查询对应用能是否支持。 如果设置不支持的检测,会被忽略。 |
isEnable | 是否开启。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
See Also:
Method |
|---|
public int setBeauty(int type, int level) 设置美颜的类型和以及对应的级别。 此函数的合法调用必须确保以下两个条件:
非法调用会被忽略。 在设置美颜类型之前,开发者应该先查询美颜的类型及其能力范围。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
type | 美颜的类型,详细的定义在Metadata.BeautyType中。如果传入的类型不支持,会被忽略。 |
level | 对应美颜类型的级别,对应的Key查询支持的范围。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
See Also:
Method |
|---|
public int setColorMode(int colorMode) 设置色彩模式类型。 此函数的合法调用必须确保以下两个条件:
在设置色彩模式之前,开发者应该先查询色彩模式支持的范围。非合法调用会被忽略。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
colorMode | 色彩模式的范围,通过ModeCharacteristics.getSupportedColorMode()查询获得, 详细的定义在Metadata.ColorType中。如果传入的类型不支持,会被忽略。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
See Also:
Method |
|---|
public int setSceneDetection(boolean isEnable) 设置自动场景检测,数据结果以回调方式返回。 此函数的合法调用必须确保以下两个条件:
非法调用会被忽略。 自动场景检测的结果是以ActionStateCallback.onSceneDetection(Mode, int, ActionStateCallback.SceneDetectionResult)通知的, 开发者可以通过ActionStateCallback.SceneDetectionResult可以获取当前的场景信息。 返回的场景,其取值范围参见Metadata.SceneDetectionType,不同场景有不同的含义和用法,请参见对应的文档。 识别到场景后,通过setParameter(android.hardware.camera2.CaptureRequest.Key<T>, T)及RequestKey.HW_SCENE_EFFECT_ENABLE进入场景,打开对应的效果。 注意这个动作只对效果类场景生效,对于场景推荐类,需要按照文档指示进行操作。 进入场景后,通过setParameter(android.hardware.camera2.CaptureRequest.Key<T>, T)及RequestKey.HW_SCENE_EFFECT_ENABLE退出场景,取消对应的效果。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
isEnable | 开启或停止场景检测。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
Method |
|---|
public int setLocation(android.location.Location location) 设置地理位置信息。 此函数的合法调用必须确保已经调用ModeStateCallback.onConfigured(com.huawei.camera.camerakit.Mode)成功配置过模式,非法调用 会被忽略。为了保证地址位置的准确性,开发正应当在拍照的时候及时更新位置信息。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
location | 地址位置信息,可以为空。如果设置空,在保存的照片中没有地理位置信息。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
Method |
|---|
public int setImageRotation(int degrees) 设置图片旋转角度,用于纠正HAL层图片旋转信息。 此函数的合法调用必须确保已经调用ModeStateCallback.onConfigured(com.huawei.camera.camerakit.Mode)成功配置过模式。非法调用 会被忽略。 为了保证图片旋转角度的准确性,开发正应当在拍照的时候及时更新旋转角度。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
degrees | 旋转角度,应当为90的倍数,传入其他整数会被四舍五入至90的倍数。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
Method |
|---|
public int setImageRotation(int degrees) 设置图片旋转角度,用于纠正HAL层图片旋转信息。 此函数的合法调用必须确保已经调用ModeStateCallback.onConfigured(com.huawei.camera.camerakit.Mode)成功配置过模式。非法调用 会被忽略。 为了保证图片旋转角度的准确性,开发正应当在拍照的时候及时更新旋转角度。 |
Type Parameters:
Type Parameter Name | Type Parameter Description |
|---|---|
T | 模式参数的数值类型。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
key | 模式参数,在使用之前应当通过ModeCharacteristics.getSupportedParameters()查询是否支持。 |
value | 模式参数对应的值,该值应该是在支持范围内ModeCharacteristics.getParameterRange(android.hardware.camera2.CaptureRequest.Key<T>), 需要通过ModeCharacteristics.getParameterRange(CaptureRequest.Key)查询。 |
Returns:
Type | Description |
|---|---|
int | 设置动作下发结果,取值参见Mode.ResultCode。 |
See Also:
ModeCharacteristics.getSupportedParameters(), ModeCharacteristics.getParameterRange(CaptureRequest.Key)
Method |
|---|
public <T> int setParameters(java.util.Map<android.hardware.camera2.CaptureRequest.Key<T>,T> params) 批量设置模式参数。 此函数的合法调用必须确保以下三个条件:
非法调用会被忽略。 开发者需要了解,模式参数存在参数互斥的可能性,这个视具体的模式而定。因此,用户应当保证在传入的Map对象 中不应该存在互斥的功能,如果存在互斥功能的情况,系统可能会随机选择一个可用的参数或则放弃互斥功能组中的参数, 结果将不可预期。可以通过查询互斥功能组的方式了解,详见ModeCharacteristics.getConflictActions()。 |
Type Parameters:
Type Parameter Name | Type Parameter Description |
|---|---|
T | 模式参数的数值类型。 |
Parameters:
Parameter Name | Parameter Description |
|---|---|
params | 一组模式参数的列表。在使用之前应当通过ModeCharacteristics.getSupportedParameters()获得。 |
Returns:
Type | Description |
|---|---|
int | 模式的类型,取值参见Mode.ResultCode。 |
See Also:
ModeCharacteristics.getSupportedParameters(), ModeCharacteristics.getParameterRange(CaptureRequest.Key)
Method |
|---|
public int getType() 获取当前模式的类型。 特别需要注意的是:当模式被完全释放的时候(调用完release()且ModeStateCallback.onReleased(com.huawei.camera.camerakit.Mode)回调结束), 模式不再可用,此时获得的模式类型是不可信的。 |
Returns:
Type | Description |
|---|---|
int | 模式的类型,详见Mode.Type。 |
Method |
|---|
public java.lang.String getCameraId() 获取当前模式的逻辑摄像头ID。 特别需要注意的是,当模式被完全释放的时候(调用完release()且ModeStateCallback.onReleased(com.huawei.camera.camerakit.Mode)回调结束), 模式不再可用,此时获得的逻辑摄像头ID是不可信的。 |
Returns:
Type | Description |
|---|---|
java.lang.String | 返回逻辑摄像头ID |