1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file istream_operator.h 18 * 19 * @brief Declares APIs for stream operations. 20 * 21 * @since 1.0 22 * @version 1.0 23 */ 24 25 #ifndef HDI_STREAM_OPERATOR_CLIENT_INF_H 26 #define HDI_STREAM_OPERATOR_CLIENT_INF_H 27 28 #include <list> 29 #include <map> 30 #include <vector> 31 #include <iservmgr_hdi.h> 32 #include <hdf_log.h> 33 #include "istream_operator_callback.h" 34 #include "ioffline_stream_operator.h" 35 #include "types.h" 36 37 namespace OHOS::Camera { 38 enum { 39 CMD_STREAM_OPERATOR_IS_STREAMS_SUPPORTED = 0, 40 CMD_STREAM_OPERATOR_CREATE_STREAMS, 41 CMD_STREAM_OPERATOR_RELEASE_STREAMS, 42 CMD_STREAM_OPERATOR_COMMIT_STREAMS, 43 CMD_STREAM_OPERATOR_GET_STREAM_ATTRIBUTES, 44 CMD_STREAM_OPERATOR_ATTACH_BUFFER_QUEUE, 45 CMD_STREAM_OPERATOR_DETACH_BUFFER_QUEUE, 46 CMD_STREAM_OPERATOR_CAPTURE, 47 CMD_STREAM_OPERATOR_CANCEL_CAPTURE, 48 CMD_STREAM_OPERATOR_CHANGE_TO_OFFLINE_STREAM, 49 }; 50 51 class IBufferProducer; 52 class IStreamOperator : public IRemoteBroker { 53 public: 54 DECLARE_INTERFACE_DESCRIPTOR(u"HDI.Camera.V1_0.StreamOperator"); 55 ~IStreamOperator()56 virtual ~IStreamOperator() {} 57 58 /** 59 * @brief Checks whether a specific stream can be dynamically created. 60 * 61 * 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. 62 * The current module supports preview streams, video streams, photographing streams, and the like. For details, see {@link StreamIntent}. 63 * 64 * This function is used to check whether a stream can be dynamically created based on the operation mode, configuration information, and existing streams in the current module. 65 * If the stream can be created without stopping the existing streams or making the upper-layer service or application unaware of the stopping of the existing streams, 66 * <b>type</b> is set to <b>DYNAMIC_SUPPORTED</b> so that the upper-layer service or application can directly add the new stream. 67 * If the stream can be created only after the upper-layer service or application stops capturing all streams, <b>type</b> is set to <b>RE_CONFIGURED_REQUIRED</b>. 68 * If the stream is not supported, <b>type</b> is set to <b>NOT_SUPPORTED</b>. 69 * This function must be called prior to {@link CreateStreams}. 70 * 71 * @param mode Indicates the operation mode of the stream. For details, see {@link OperationMode}. 72 * @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). 73 * @param info Indicates the stream configuration information. For details, see {@link StreamInfo}. 74 * @param type Indicates the support type of the dynamically created stream. The supported types are defined in {@link StreamSupportType}. 75 * 76 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 77 * 78 * @since 1.0 79 * @version 1.0 80 */ 81 virtual CamRetCode IsStreamsSupported( 82 OperationMode mode, 83 const std::shared_ptr<CameraStandard::CameraMetadata> &modeSetting, 84 const std::shared_ptr<StreamInfo> &info, 85 StreamSupportType &type) = 0; 86 87 virtual CamRetCode IsStreamsSupported( 88 OperationMode mode, 89 const std::shared_ptr<CameraStandard::CameraMetadata> &modeSetting, 90 const std::vector<std::shared_ptr<StreamInfo>> &info, 91 StreamSupportType &type) = 0; 92 93 /** 94 * @brief Creates streams. 95 * 96 * Before calling this function, you must use {@link IsStreamsSupported} to check whether the hardware abstraction layer (HAL) supports the streams to create. 97 * 98 * @param streamInfos Indicates the list of stream information, which is defined by {@link StreamInfo}. The passed stream information may be changed. 99 * Therefore, you can run {@link GetStreamAttributes} to obtain the latest stream attributes after the stream is created. 100 * 101 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 102 * 103 * @since 1.0 104 * @version 1.0 105 */ 106 virtual CamRetCode CreateStreams(const std::vector<std::shared_ptr<StreamInfo>> &streamInfos) = 0; 107 108 /** 109 * @brief Releases streams. 110 * 111 * @param streamIds Indicates the IDs of the streams to release. 112 * 113 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 114 * 115 * @since 1.0 116 * @version 1.0 117 */ 118 virtual CamRetCode ReleaseStreams(const std::vector<int> &streamIds) = 0; 119 120 /** 121 * @brief Configures a stream. 122 * 123 * This function must be called after {@link CreateStreams}. 124 * 125 * @param mode Indicates the operation mode of the stream. For details, see {@link OperationMode}. 126 * @param modeSetting Indicates the stream configuration parameters, including the frame rate and zoom information. 127 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 128 * 129 * @since 1.0 130 * @version 1.0 131 */ 132 virtual CamRetCode CommitStreams(OperationMode mode, 133 const std::shared_ptr<CameraStandard::CameraMetadata> &modeSetting) = 0; 134 135 /** 136 * @brief Obtains stream attributes. 137 * 138 * @param attributes Indicates the obtained stream attributes. Stream information passed by the <b>streamInfos</b> parameter in {@link CreateStreams} 139 * may be overridden. Therefore, the stream attributes obtained by using this function may be 140 * different from the stream information passed in {@link CreateStreams}. 141 * 142 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 143 * 144 * @since 1.0 145 * @version 1.0 146 */ 147 virtual CamRetCode GetStreamAttributes( 148 std::vector<std::shared_ptr<StreamAttribute>> &attributes) = 0; 149 150 /** 151 * @brief Attaches a producer handle to a stream. 152 * 153 * 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, 154 * call {@link DetachBufferQueue} to detach the existing procedure handle and then call this function to attach the new one. 155 * 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. 156 * In this case, set <b>bufferQueue_</b> in the {@link StreamInfo} parameter of {@link CreateStreams} to <b>null</b>, 157 * and set <b>tunneledMode_</b> to <b>false</b>. 158 * 159 * @param streamId Indicates the ID of the stream to which the procedure handle is to be attached. 160 * @param producer Indicates the producer handle to be attached. 161 * 162 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 163 * 164 * @since 1.0 165 * @version 1.0 166 */ 167 virtual CamRetCode AttachBufferQueue(int streamId, const OHOS::sptr<OHOS::IBufferProducer> &producer) = 0; 168 169 /** 170 * @brief Detaches the producer handle from a stream. 171 * 172 * @param streamId Indicates the ID of the stream from which the procedure handle is to be detached. 173 * 174 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 175 * 176 * @since 1.0 177 * @version 1.0 178 */ 179 virtual CamRetCode DetachBufferQueue(int streamId) = 0; 180 181 /** 182 * @brief Captures an image. 183 * 184 * This function must be called after {@link CommitStreams}. 185 * There are two image capture modes: continuous capture and single capture. A continuous capture is performed inside the module after being triggered, 186 * and the consumer can continuously receive captured image data after calling this function only once. If this function is called again, 187 * 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. 188 * After a single capture is triggered, only one frame of image data is captured. This mode applies to the single shooting scenario. 189 * When the capture is started, {@link OnCaptureStarted} is called to notify of the start. 190 * To stop a continuous capture, call {@link CancelCapture}. 191 * When the capture ends, {@link OnCaptureEnded} is called to notify the caller of the information such as the number of captured frames. 192 * <b>enableShutterCallback_</b> in {@link CaptureInfo} is used to enable the callback for each capture. After the callback is enabled, {@link OnFrameShutter} is called upon each capture. 193 * 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. 194 * 195 * @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. 196 * @param info Indicates the capture request configuration information. For details, see {@link CaptureInfo}. 197 * @param isStreaming Specifies whether to continuously capture images. The value <b>true</b> means to continuously capture images, and <b>false</b> means the opposite. 198 * 199 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 200 * 201 * @since 1.0 202 * @version 1.0 203 */ 204 virtual CamRetCode Capture(int captureId, 205 const std::shared_ptr<CaptureInfo> &info, bool isStreaming) = 0; 206 207 /** 208 * @brief Cancels a capture. 209 * 210 * {@link OnCaptureEnded} is called when a continuous capture is canceled. 211 * 212 * @param captureId Indicates the ID of the capture request to cancel. 213 * 214 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 215 * 216 * @since 1.0 217 * @version 1.0 218 */ 219 virtual CamRetCode CancelCapture(int captureId) = 0; 220 221 /** 222 * @brief Converts a specific stream to an offline stream. 223 * 224 * Only photographing streams can be converted into offline streams. 225 * 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. 226 * Converting to an offline stream enables the bottom-layer device to close and the offline stream to take over for subsequent processing. 227 * 228 * @param streamIds Indicates the IDs of the streams to be converted. 229 * @param callback Indicates the callback for conversion to offline streams. 230 * @param offlineOperator Indicates the offline stream after conversion. 231 * 232 * @return Returns <b>NO_ERROR</b> if the operation is successful; returns an error code defined in {@link CamRetCode} otherwise. 233 * 234 * @since 1.0 235 * @version 1.0 236 */ 237 virtual CamRetCode ChangeToOfflineStream(const std::vector<int> &streamIds, 238 OHOS::sptr<IStreamOperatorCallback> &callback, 239 OHOS::sptr<IOfflineStreamOperator> &offlineOperator) = 0; 240 }; 241 } 242 243 #endif // HDI_STREAM_OPERATOR_CLIENT_INF_H 244