From 1ce33271c15d4d6f82c7371814aa25b23ad70ed6 Mon Sep 17 00:00:00 2001 From: wwx1074746 Date: Thu, 24 Feb 2022 11:15:29 +0800 Subject: [PATCH] add camera hdi interface definition Signed-off-by: wwx1074746 --- camera/v1_0/BUILD.gn | 41 +++ camera/v1_0/CameraTypes.idl | 399 ++++++++++++++++++++++++ camera/v1_0/ICameraDevice.idl | 129 ++++++++ camera/v1_0/ICameraDeviceCallback.idl | 55 ++++ camera/v1_0/ICameraHost.idl | 107 +++++++ camera/v1_0/ICameraHostCallback.idl | 51 +++ camera/v1_0/IOfflineStreamOperator.idl | 67 ++++ camera/v1_0/IStreamOperator.idl | 237 ++++++++++++++ camera/v1_0/IStreamOperatorCallback.idl | 78 +++++ 9 files changed, 1164 insertions(+) create mode 100644 camera/v1_0/BUILD.gn create mode 100644 camera/v1_0/CameraTypes.idl create mode 100644 camera/v1_0/ICameraDevice.idl create mode 100644 camera/v1_0/ICameraDeviceCallback.idl create mode 100644 camera/v1_0/ICameraHost.idl create mode 100644 camera/v1_0/ICameraHostCallback.idl create mode 100644 camera/v1_0/IOfflineStreamOperator.idl create mode 100644 camera/v1_0/IStreamOperator.idl create mode 100644 camera/v1_0/IStreamOperatorCallback.idl diff --git a/camera/v1_0/BUILD.gn b/camera/v1_0/BUILD.gn new file mode 100644 index 00000000..71d214a4 --- /dev/null +++ b/camera/v1_0/BUILD.gn @@ -0,0 +1,41 @@ +# Copyright (c) 2022 Huawei Device Co., Ltd. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import("//drivers/adapter/uhdf2/hdi.gni") +if (defined(ohos_lite)) { + group("libcamera_proxy_1.0") { + deps = [] + public_configs = [] + } +} else { + hdi("camera") { + package = "OHOS.HDI.camera.v1_0" + + module_name = "camera_service" + + sources = [ + "CameraTypes.idl", + "ICameraDevice.idl", + "ICameraDeviceCallback.idl", + "ICameraHost.idl", + "ICameraHostCallback.idl", + "IOfflineStreamOperator.idl", + "IStreamOperator.idl", + "IStreamOperatorCallback.idl", + ] + + language = "cpp" + subsystem_name = "hdf" + part_name = "camera_device_driver" + } +} diff --git a/camera/v1_0/CameraTypes.idl b/camera/v1_0/CameraTypes.idl new file mode 100644 index 00000000..6a65bb2f --- /dev/null +++ b/camera/v1_0/CameraTypes.idl @@ -0,0 +1,399 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file types.h + * + * @brief Declares data types + * used by the Hardware Driver Interfaces (HDIs) of this module. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +/** + * @brief Enumerates return values of the HDIs. + */ +enum CamRetCode { + /** + * Successful call. + */ + NO_ERROR = 0, + + /** + * The camera device is busy. + */ + // CAMERA_BUSY = - 1 // unexpected '-', + + /** + * Insufficient resources. + */ + // INSUFFICIENT_RESOURCES = - 2 // unexpected '-', + + /** + * Invalid parameters. + */ + // INVALID_ARGUMENT = - 3 // unexpected '-', + + /** + * Unsupported function. + */ + // METHOD_NOT_SUPPORTED = - 4 // unexpected '-', + + /** + * The camera device is closed. + */ + // CAMERA_CLOSED = - 5 // unexpected '-', + + /** + * A critical error occurs at the driver layer. + */ + // DEVICE_ERROR = - 6 // unexpected '-', +}; + +/** + * @brief Enumerates metadata reporting modes. + */ +enum ResultCallbackMode { + /** + * Frame-by-frame reporting + */ + PER_FRAME = 0, + + /** + * Reporting upon device status change + */ + ON_CHANGED = 1, +}; + +/** + * @brief Enumerates stream operation modes. + */ +enum OperationMode { + /** + * Normal + */ + NORMAL = 0, +}; + +/** + * @brief Enumerates stream types. + */ +enum StreamIntent { + /** + * Preview streams, indicating that stream data is used for preview + */ + PREVIEW = 0, + + /** + * Video streams, indicating that stream data is used to encode and generate videos + */ + VIDEO = 1, + + /** + * Photographing streams, indicating that stream data is used to encode and generate images + */ + STILL_CAPTURE = 2, + + /** + * Stream data that is used to store thumbnails + */ + POST_VIEW = 3, + + /** + * Stream data that is used for image analysis + */ + ANALYZE = 4, + + /** + * Custom type + */ + CUSTOM = 5, +}; + +/** + * @brief Enumerates encoding types of stream data. + */ +enum EncodeType { + /** + * Unspecified + */ + ENCODE_TYPE_NULL = 0, + + /** + * H.264 + */ + ENCODE_TYPE_H264 = 1, + + /** + * H.265 + */ + ENCODE_TYPE_H265 = 2, + + /** + * JPEG + */ + ENCODE_TYPE_JPEG = 3, +}; + +/** + * @brief Enumerates the support types of the stream. For details about the application scenario, + * see {@link IsStreamsSupported}. + */ +enum StreamSupportType { + /** + * The stream can be dynamically created, and the corresponding stream parameters take effect directly. + */ + DYNAMIC_SUPPORTED = 0, + + /** + * The stream cannot be dynamically created, + * and the corresponding parameters take effect only after the existing stream is stopped and reconfigured. + */ + RE_CONFIGURED_REQUIRED = 1, + + /** + * The stream cannot be dynamically created. + */ + NOT_SUPPORTED = 2, +}; + +/** + * @brief Enumerates camera device statuses. + */ +enum CameraStatus { + /** + * The camera device is not in position or is unavailable. + */ + UN_AVAILABLE = 0, + + /** + * The camera device is available. + */ + AVAILABLE = 1, +}; + +/** + * @brief Enumerates flash statuses. + */ +enum FlashlightStatus { + /** + * The flash is off. + */ + FLASHLIGHT_OFF = 0, + + /** + * The flash is on. + */ + FLASHLIGHT_ON = 1, + + /** + * The flash is unavailable. + */ + FLASHLIGHT_UNAVAILABLE = 2, +}; + +/** + * @brief Enumerates camera device error types, which are used by {@link OnError}. + */ +enum ErrorType { + /** + * A critical error occurs. The camera device needs to be closed. + */ + FATAL_ERROR = 0, + + /** + * A request timeout occurs. The camera device needs to be closed. + */ + REQUEST_TIMEOUT = 1, +}; + +/** + * @brief Enumerates stream error types, which are used by {@link CaptureErrorInfo}. + */ +enum StreamError { + /** + * Unknown error + */ + UNKNOWN_ERROR = 0, + + /** + * Packet loss + */ + BUFFER_LOST = 1, +}; + +/** + * @brief Defines the stream information, which is used to pass configuration parameters during stream creation. + */ +struct StreamInfo { + /** + * Stream ID, which uniquely identifies a stream on a camera device. + */ + int streamId_; + + /** + * Image width. + */ + int width_; + + /** + * Image height. + */ + int height_; + + /** + * Image format. + */ + int format_; + + /** + * Image color space. + */ + int datasapce_; + + /** + * Stream type. + */ + enum StreamIntent intent_; + + /** + * Tunnel mode. The value true means that the tunnel mode is enabled, and false means the opposite. + * + * After the tunnel mode is enabled, + * the hardware abstraction layer (HAL) does not directly interact with the upper layer. + * Instead, it uses the producer handle provided by the graphics layer to transfer frame data. + * You need to disable the tunnel mode for IoT devices that do not support + * or require image data caching and forwarding of preview streams. + */ + boolean tunneledMode_; + + /** + * Producer handle provided by the graphics layer. + */ + unsigned char[] bufferQueue_; + + /** + * Minimum frame interval. + */ + int minFrameDuration_; + + /** + * Encoding type. + */ + enum EncodeType encodeType_; +}; + +/** + * @brief Defines the stream attributes. + */ +struct StreamAttribute { + /** + * Stream ID, which uniquely identifies a stream on a camera device. + */ + int streamId_; + + /** + * Image width. + */ + int width_; + + /** + * Image height. + */ + int height_; + + /** + * New image format. + */ + int overrideFormat_; + + /** + * New image color space. + */ + int overrideDatasapce_; + + /** + * New procedure usage. + */ + int producerUsage_; + + /** + * New number of produce buffers. + */ + int producerBufferCount_; + + /** + * Maximum number of frames that can be captured in a continuous capture. + */ + int maxBatchCaptureCount_; + + /** + * Maximum number of concurrent capture requests. The default value is 1. + */ + int maxCaptureCount_; +}; + +/** + * @brief Defines the information about a capture request. + */ +struct CaptureInfo { + /** + * IDs of captured streams. + */ + int[] streamIds_; + + /** + * Captured configuration information. + */ + unsigned char[] captureSetting_; + + /** + * Whether to enable callback for each capture. If enabled, {@link OnFrameShutter} is called upon each capture. + */ + boolean enableShutterCallback_; +}; + +/** + * @brief Defines the information about the end of packet capture, which is used by {@link OnCaptureEnded}. + */ +struct CaptureEndedInfo { + /** + * ID of a captured stream. + */ + int streamId_; + + /** + * Number of frames that have been captured when the capture ends. + */ + int frameCount_; +}; + +/** + * @brief Defines the stream error information, which is used by {@link OnCaptureError}. + */ +struct CaptureErrorInfo { + /** + * Stream ID + */ + int streamId_; + + /** + * Error type + */ + enum StreamError error_; +}; diff --git a/camera/v1_0/ICameraDevice.idl b/camera/v1_0/ICameraDevice.idl new file mode 100644 index 00000000..6f4669c1 --- /dev/null +++ b/camera/v1_0/ICameraDevice.idl @@ -0,0 +1,129 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file icamera_device.h + * + * @brief Declares APIs for camera device operations. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.IStreamOperatorCallback; +import OHOS.HDI.camera.v1_0.IStreamOperator; + +interface ICameraDevice { + /** + * @brief Obtains the stream operation handle. + * + * @param callback Indicates a stream callback. For details, see {@link IStreamOperatorCallback}. + * {@link OnCaptureStarted} and {@link OnCaptureEnded} are used to report the start and end of capture, + * and {@link OnCaptureError} is used to report a capture error. + * + * @param streamOperator Indicates the stream operation handle. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + GetStreamOperator([in] IStreamOperatorCallback callbackObj,[out] IStreamOperator streamOperator); + + /** + * @brief Updates camera device control parameters. + * + * @param settings Indicates the camera parameters, including the sensor frame rate and 3A parameters. + * 3A stands for automatic focus (AF), automatic exposure (AE), and automatic white-balance (?AWB). + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + UpdateSettings([in] unsigned char[] settings); + + /** + * @brief Sets the metadata reporting mode. + * + * @param mode Indicates the metadata reporting mode to set, which can be frame-by-frame reporting or reporting + * upon device status change. For details, see {@link ResultCallbackMode}. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + SetResultMode([in] enum ResultCallbackMode mode); + + /** + * @brief Obtains enabled metadata. + * + * Metadata to be reported is enabled by calling {@link EnableResult}. + * + * @param results Indicates all enabled metadata. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + GetEnabledResults([out] int[] results); + + /** + * @brief Enables metadata reporting. + * + * Only metadata that is enabled can be reported by using {@link OnResult}. + * + * @param results Indicates the metadata for which reporting is to be enabled. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + EnableResult([in] int[] results); + + /** + * @brief Disables metadata reporting. + * + * After metadata reporting is disabled, the metadata is not reported by calling {@link OnResult}. + * To enable metadata reporting, you must call {@link EnableResult}. + * + * @param results Indicates the metadata for which reporting is to be disabled. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + DisableResult([in] int[] results); + + /** + * @brief Closes the camera device. + * + * @since 1.0 + * @version 1.0 + */ + Close(); +} diff --git a/camera/v1_0/ICameraDeviceCallback.idl b/camera/v1_0/ICameraDeviceCallback.idl new file mode 100644 index 00000000..69d1a844 --- /dev/null +++ b/camera/v1_0/ICameraDeviceCallback.idl @@ -0,0 +1,55 @@ + +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file icamera_device_callback.h + * + * @brief Declares callbacks for reporting camera device errors and metadata. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.CameraTypes; + +[callback] interface ICameraDeviceCallback { + /** + * @brief Called when an error occurs on the camera device. The caller needs to implement this function. + * + * @param type Indicates the error type. For details, see {@link ErrorType}. + * @param errorCode Indicates the error code. This parameter is not used currently. + * + * @since 1.0 + * @version 1.0 + */ + OnError([in] enum ErrorType type,[in] int errorCode); + + /** + * @brief Called to report metadata related to the camera device. + * For details about the reporting mode, see {@link SetResultMode}. + * + * @param timestamp Indicates the timestamp when the metadata is reported. + * @param result Indicates the metadata reported. The reported metadata is specified by {@link EnableResult}. + * You can call {@link GetEnabledResults} to obtain enabled metadata and + * call {@link DisableResult} to disable metadata reporting. + * + * @since 1.0 + * @version 1.0 + */ + OnResult([in] unsigned long timestamp,[in] unsigned char[] result); +} diff --git a/camera/v1_0/ICameraHost.idl b/camera/v1_0/ICameraHost.idl new file mode 100644 index 00000000..398ff048 --- /dev/null +++ b/camera/v1_0/ICameraHost.idl @@ -0,0 +1,107 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file icamera_host.h + * + * @brief Management class of the camera service that provides Hardware Driver Interfaces (HDIs) for the upper layer. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.ICameraHostCallback; +import OHOS.HDI.camera.v1_0.ICameraDeviceCallback; +import OHOS.HDI.camera.v1_0.ICameraDevice; + +interface ICameraHost { + /** + * @brief Sets callbacks. For details about the callbacks, see {@link ICameraHostCallback}. + * + * @param callback Indicates the callbacks to set. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + SetCallback([in] ICameraHostCallback callbackObj); + + /** + * @brief Obtains the IDs of available camera devices. + * + * @param cameraIds Indicates the IDs of available camera devices. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + GetCameraIds([out] String[] cameraIds); + + /** + * @brief Obtains the abilities of a camera device. + * + * @param cameraId Indicates the ID of the camera device, which can be obtained by calling {@link GetCameraIds}. + * + * @param ability Returns the abilities of the camera device. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + GetCameraAbility([in] String cameraId,[out] unsigned char[] cameraAbility); + + /** + * @brief Opens a camera device. + * + * By calling this function, you can obtain the ICameraDevice instance and operate the + * specific camera device mapping to the instance. + * + * @param cameraId Indicates the ID of the camera device, which can be obtained by calling {@link GetCameraIds}. + * @param callback Indicates the callback related to the camera. For details, see {@link ICameraDeviceCallback}. + * @param device Indicates the ICameraDevice instance corresponding to the ID of the camera device. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + OpenCamera([in] String cameraId,[in] ICameraDeviceCallback callbackObj,[out] ICameraDevice device); + + /** + * @brief Turns on or off the flash. + * + * This function can be used only by the caller who has opened the camera device specified by cameraId. + * + * @param cameraId Indicates the ID of the camera whose flash is to be turned on or off. + * @param isEnable Specifies whether to turn on or off the flash. The value true means to turn on the flash, + * and false means the opposite. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + SetFlashlight([in] String cameraId,[in] boolean isEnable); +} diff --git a/camera/v1_0/ICameraHostCallback.idl b/camera/v1_0/ICameraHostCallback.idl new file mode 100644 index 00000000..5274b7e3 --- /dev/null +++ b/camera/v1_0/ICameraHostCallback.idl @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file icamera_host_callback.h + * + * @brief Declares callbacks for status changes of cameras and flashes. The caller needs to implement the callbacks. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.CameraTypes; + +[callback] interface ICameraHostCallback { + /** + * @brief Called when the camera status changes to report the latest status. + * + * @param cameraId Indicates the ID of the camera whose status changes. + * @param status Indicates the latest status of the camera. + * + * @since 1.0 + * @version 1.0 + */ + OnCameraStatus([in] String cameraId,[in] enum CameraStatus status); + + /** + * @brief Called when the flash status changes to report the latest status. + * + * @param cameraId Indicates the ID of the camera to which the flash whose status changes is bound. + * @param status Indicates the latest status of the flash. + * + * @since 1.0 + * @version 1.0 + */ + OnFlashlightStatus([in] String cameraId,[in] enum FlashlightStatus status); +} diff --git a/camera/v1_0/IOfflineStreamOperator.idl b/camera/v1_0/IOfflineStreamOperator.idl new file mode 100644 index 00000000..6b12140a --- /dev/null +++ b/camera/v1_0/IOfflineStreamOperator.idl @@ -0,0 +1,67 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file ioffline_stream_operator.h + * + * @brief Declares APIs for offline stream operations. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.CameraTypes; + +interface IOfflineStreamOperator { + /** + * @brief Cancels a capture request. + * + * @param captureId Indicates the ID of the capture request to cancel. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + CancelCapture([in] int captureId); + + /** + * @brief Releases offline streams. + * + * @param streamIds Indicates the IDs of the offline streams to release. + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + ReleaseStreams([in] int[] streamIds); + + /** + * @brief Releases all offline streams. + * + * + * @return Returns NO_ERROR if the operation is successful; returns an error code defined + * in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + Release(); +} diff --git a/camera/v1_0/IStreamOperator.idl b/camera/v1_0/IStreamOperator.idl new file mode 100644 index 00000000..8a23ea43 --- /dev/null +++ b/camera/v1_0/IStreamOperator.idl @@ -0,0 +1,237 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file istream_operator.h + * + * @brief Declares APIs for stream operations. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.CameraTypes; +import OHOS.HDI.camera.v1_0.IStreamOperatorCallback; +import OHOS.HDI.camera.v1_0.IOfflineStreamOperator; + +interface IStreamOperator { + /** + * @brief Checks whether a specific stream can be dynamically created. + * + * A stream is a sequence of data elements output from a bottom-layer device, processed by the current module, + * and then transmitted to an upper-layer service or application. + * The current module supports preview streams, video streams, photographing streams, and the like. + * For details, see {@link StreamIntent}. + * + * This function is used to check whether a stream or streams can be dynamically created based on the + * operation mode, configuration information, and existing streams in the current module. + * If the streams can be created without stopping the existing streams or making the upper-layer service or + * application unaware of the stopping of the existing streams, + * type is set to DYNAMIC_SUPPORTED so that the upper-layer service or application + * can directly add the new stream. + * If the streams can be created only after the upper-layer service or application stops capturing all streams, + * type is set to RE_CONFIGURED_REQUIRED. + * If the streams are not supported, type is set to NOT_SUPPORTED. + * This function must be called prior to {@link CreateStreams}. + * + * @param mode Indicates the operation mode of the streams. For details, see {@link OperationMode}. + * @param modeSetting Indicates the stream configuration parameters, including the frame rate and 3A. + * 3A stands for automatic focus (AF), automatic exposure (AE), and automatic white-balance (AWB). + * @param info Indicates the stream configuration information. For details, see {@link StreamInfo}. + * @param type Indicates the support type of the dynamically created stream. + * The supported types are defined in {@link StreamSupportType}. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + IsStreamsSupported([in] enum OperationMode mode,[in] unsigned char[] modeSetting, + [in] struct StreamInfo[] info,[in] enum StreamSupportType type); + + /** + * @brief Creates streams. + * + * Before calling this function, you must use {@link IsStreamsSupported} to check whether the hardware + * abstraction layer (HAL) supports the streams to create. + * + * @param streamInfos Indicates the list of stream information, which is defined by {@link StreamInfo}. + * The passed stream information may be changed. Therefore, you can run {@link GetStreamAttributes} to + * obtain the latest stream attributes after the stream is created. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + CreateStreams([in] struct StreamInfo[] streamInfos); + + /** + * @brief Releases streams. + * + * @param streamIds Indicates the IDs of the streams to release. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + ReleaseStreams([in] int[] streamIds); + + /** + * @brief Configures a stream. + * + * This function must be called after {@link CreateStreams}. + * + * @param mode Indicates the operation mode of the stream. For details, see {@link OperationMode}. + * @param modeSetting Indicates the stream configuration parameters, including the frame rate and zoom information. + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + CommitStreams([in] enum OperationMode mode,[in] unsigned char[] modeSetting); + + /** + * @brief Obtains stream attributes. + * + * @param attributes Indicates the obtained stream attributes. + * Stream information passed by the streamInfos parameter in {@link CreateStreams} + * may be overridden. Therefore, the stream attributes obtained by using this function may be + * different from the stream information passed in {@link CreateStreams}. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + GetStreamAttributes([out] struct StreamAttribute[] attributes); + + /** + * @brief Attaches a producer handle to a stream. + * + * If a producer handle has been specified during stream creation (by {@link CreateStreams}), + * you do not need to call this function. If you want to attach a new procedure handle, + * call {@link DetachBufferQueue} to detach the existing procedure handle and then + * call this function to attach the new one. + * You do not need to attach a procedure handle for IoT devices that do not support or require + * image data caching and transferring of preview streams. + * In this case, set bufferQueue_ in the {@link StreamInfo} parameter of {@link CreateStreams} + * to null, + * and set tunneledMode_ to false. + * + * @param streamId Indicates the ID of the stream to which the procedure handle is to be attached. + * @param producer Indicates the producer handle to be attached. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + AttachBufferQueue([in] int streamId,[in] unsigned char[] bufferProducer); + + /** + * @brief Detaches the producer handle from a stream. + * + * @param streamId Indicates the ID of the stream from which the procedure handle is to be detached. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + DetachBufferQueue([in] int streamId); + + /** + * @brief Captures an image. + * + * This function must be called after {@link CommitStreams}. + * There are two image capture modes: continuous capture and single capture. + * A continuous capture is performed inside the module after being triggered, + * and the consumer can continuously receive captured image data after calling this function only once. + * If this function is called again, the current capture is stopped, the capture request configuration is updated, + * and a new capture is performed. + * This mode is mainly used in preview, video recording, or continuous shooting scenarios. + * After a single capture is triggered, only one frame of image data is captured. + * This mode applies to the single shooting scenario. + * When the capture is started, {@link OnCaptureStarted} is called to notify of the start. + * To stop a continuous capture, call {@link CancelCapture}. + * When the capture ends, {@link OnCaptureEnded} is called to notify the caller of the information + * such as the number of captured frames. + * enableShutterCallback_ in {@link CaptureInfo} is used to enable the callback for each capture. + * After the callback is enabled, {@link OnFrameShutter} is called upon each capture. + * In the scenario where multiple streams are captured at the same time, this module ensures that + * the captured data of multiple streams is reported simultaneously. + * + * @param captureId Indicates the ID of the capture request. You must ensure that the ID of the + * capture request is unique when the camera is started. + * @param info Indicates the capture request configuration information. For details, see {@link CaptureInfo}. + * @param isStreaming Specifies whether to continuously capture images. + * The value true means to continuously capture images, and false means the opposite. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + Capture([in] int captureId,[in] struct CaptureInfo info,[in] boolean isStreaming); + + /** + * @brief Cancels a capture. + * + * {@link OnCaptureEnded} is called when a continuous capture is canceled. + * + * @param captureId Indicates the ID of the capture request to cancel. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + CancelCapture([in] int captureId); + + /** + * @brief Converts a specific stream to an offline stream. + * + * Only photographing streams can be converted into offline streams. + * Due to the limited processing capability, some devices may spend a long period of time on + * algorithm processing during photographing, causing the capture requests to stack in the module. + * Converting to an offline stream enables the bottom-layer device to close and + * the offline stream to take over for subsequent processing. + * + * @param streamIds Indicates the IDs of the streams to be converted. + * @param callback Indicates the callback for conversion to offline streams. + * @param offlineOperator Indicates the offline stream after conversion. + * + * @return Returns NO_ERROR if the operation is successful; + * returns an error code defined in {@link CamRetCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + ChangeToOfflineStream([in] int[] streamIds,[in] IStreamOperatorCallback callbackObj, + [out] IOfflineStreamOperator offlineOperator); +} diff --git a/camera/v1_0/IStreamOperatorCallback.idl b/camera/v1_0/IStreamOperatorCallback.idl new file mode 100644 index 00000000..75060da4 --- /dev/null +++ b/camera/v1_0/IStreamOperatorCallback.idl @@ -0,0 +1,78 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file istream_operator_callback.h + * + * @brief Declares callbacks related to {@link IStreamOperator}. The caller needs to implement these callbacks. + * + * @since 1.0 + * @version 1.0 + */ + +package OHOS.HDI.camera.v1_0; + +import OHOS.HDI.camera.v1_0.CameraTypes; + +[callback] interface IStreamOperatorCallback { + /** + * @brief Called when the capture starts. + * + * @param captureId Indicates the ID of the capture request corresponding to the callback. + * @param streamIds Indicates the IDs of the streams corresponding to the callback. + * + * @since 1.0 + * @version 1.0 + */ + OnCaptureStarted([in] int captureId,[in] int[] streamIds); + + /** + * @brief Called when the capture ends. + * + * @param captureId Indicates the ID of the capture request corresponding to the callback. + * @param infos Indicates information related to the capture when it ends. + * + * @since 1.0 + * @version 1.0 + */ + OnCaptureEnded([in] int captureId,[in] struct CaptureEndedInfo[] infos); + + /** + * @brief Called when an error occurs during the capture. + * + * @param captureId Indicates the ID of the capture request corresponding to the callback. + * @param infos Indicates a list of capture error messages. + * + * @since 1.0 + * @version 1.0 + */ + OnCaptureError([in] int captureId,[in] struct CaptureErrorInfo[] infos); + + /** + * @brief Called when a frame is captured. + * + * This callback is enabled by using enableShutterCallback_ in the {@link CaptureInfo} parameter of {@link Capture}. + * When enableShutterCallback_ is set to true, + * this callback is triggered each time a frame is captured. + * + * @param captureId Indicates the ID of the capture request corresponding to the callback. + * @param streamIds Indicates the IDs of the streams corresponding to the callback. + * @param timestamp Indicates the timestamp when the callback is invoked. + * + * @since 1.0 + * @version 1.0 + */ + OnFrameShutter([in] int captureId,[in] int[] streamIds,[in] unsigned long timestamp); +} -- Gitee