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 "istream_operator_callback.h" 32 #include "ioffline_stream_operator.h" 33 #include "types.h" 34 #include "icamera_interface.h" 35 36 namespace OHOS::Camera { 37 class IBufferProducer; 38 class IStreamOperator : public ICameraInterface { 39 public: 40 DECLARE_INTERFACE_DESCRIPTOR(u"HDI.Camera.V1_0.StreamOperator"); 41 ~IStreamOperator()42 virtual ~IStreamOperator() {} 43 44 /** 45 * @brief Checks whether a specific stream can be dynamically created. 46 * 47 * A stream is a sequence of data elements output from a bottom-layer device, processed by the current module, 48 * and then transmitted to an upper-layer service or application. 49 * The current module supports preview streams, video streams, photographing streams, and the like. 50 * For details, see {@link StreamIntent}. 51 * 52 * This function is used to check whether a stream or streams can be dynamically created based on the 53 * operation mode, configuration information, and existing streams in the current module. 54 * If the streams can be created without stopping the existing streams or making the upper-layer service or 55 * application unaware of the stopping of the existing streams, 56 * <b>type</b> is set to <b>DYNAMIC_SUPPORTED</b> so that the upper-layer service or application 57 * can directly add the new stream. 58 * If the streams can be created only after the upper-layer service or application stops capturing all streams, 59 * <b>type</b> is set to <b>RE_CONFIGURED_REQUIRED</b>. 60 * If the streams are not supported, <b>type</b> is set to <b>NOT_SUPPORTED</b>. 61 * This function must be called prior to {@link CreateStreams}. 62 * 63 * @param mode Indicates the operation mode of the streams. For details, see {@link OperationMode}. 64 * @param modeSetting Indicates the stream configuration parameters, including the frame rate and 3A. 65 * 3A stands for automatic focus (AF), automatic exposure (AE), and automatic white-balance (AWB). 66 * @param info Indicates the stream configuration information. For details, see {@link StreamInfo}. 67 * @param type Indicates the support type of the dynamically created stream. 68 * The supported types are defined in {@link StreamSupportType}. 69 * 70 * @return Returns <b>NO_ERROR</b> if the operation is successful; 71 * returns an error code defined in {@link CamRetCode} otherwise. 72 * 73 * @since 1.0 74 * @version 1.0 75 */ 76 virtual CamRetCode IsStreamsSupported( 77 OperationMode mode, 78 const std::shared_ptr<CameraMetadata> &modeSetting, 79 const std::vector<std::shared_ptr<StreamInfo>> &info, 80 StreamSupportType &type) = 0; 81 82 /** 83 * @brief Creates streams. 84 * 85 * Before calling this function, you must use {@link IsStreamsSupported} to check whether the hardware 86 * abstraction layer (HAL) supports the streams to create. 87 * 88 * @param streamInfos Indicates the list of stream information, which is defined by {@link StreamInfo}. 89 * The passed stream information may be changed. Therefore, you can run {@link GetStreamAttributes} to 90 * obtain the latest stream attributes after the stream is created. 91 * 92 * @return Returns <b>NO_ERROR</b> if the operation is successful; 93 * returns an error code defined in {@link CamRetCode} otherwise. 94 * 95 * @since 1.0 96 * @version 1.0 97 */ 98 virtual CamRetCode CreateStreams(const std::vector<std::shared_ptr<StreamInfo>> &streamInfos) = 0; 99 100 /** 101 * @brief Releases streams. 102 * 103 * @param streamIds Indicates the IDs of the streams to release. 104 * 105 * @return Returns <b>NO_ERROR</b> if the operation is successful; 106 * returns an error code defined in {@link CamRetCode} otherwise. 107 * 108 * @since 1.0 109 * @version 1.0 110 */ 111 virtual CamRetCode ReleaseStreams(const std::vector<int> &streamIds) = 0; 112 113 /** 114 * @brief Configures a stream. 115 * 116 * This function must be called after {@link CreateStreams}. 117 * 118 * @param mode Indicates the operation mode of the stream. For details, see {@link OperationMode}. 119 * @param modeSetting Indicates the stream configuration parameters, including the frame rate and zoom information. 120 * @return Returns <b>NO_ERROR</b> if the operation is successful; 121 * returns an error code defined in {@link CamRetCode} otherwise. 122 * 123 * @since 1.0 124 * @version 1.0 125 */ 126 virtual CamRetCode CommitStreams(OperationMode mode, 127 const std::shared_ptr<CameraMetadata> &modeSetting) = 0; 128 129 /** 130 * @brief Obtains stream attributes. 131 * 132 * @param attributes Indicates the obtained stream attributes. 133 * Stream information passed by the <b>streamInfos</b> parameter in {@link CreateStreams} 134 * may be overridden. Therefore, the stream attributes obtained by using this function may be 135 * different from the stream information passed in {@link CreateStreams}. 136 * 137 * @return Returns <b>NO_ERROR</b> if the operation is successful; 138 * returns an error code defined in {@link CamRetCode} otherwise. 139 * 140 * @since 1.0 141 * @version 1.0 142 */ 143 virtual CamRetCode GetStreamAttributes( 144 std::vector<std::shared_ptr<StreamAttribute>> &attributes) = 0; 145 146 /** 147 * @brief Attaches a producer handle to a stream. 148 * 149 * If a producer handle has been specified during stream creation (by {@link CreateStreams}), 150 * you do not need to call this function. If you want to attach a new procedure handle, 151 * call {@link DetachBufferQueue} to detach the existing procedure handle and then 152 * call this function to attach the new one. 153 * You do not need to attach a procedure handle for IoT devices that do not support or require 154 * image data caching and transferring of preview streams. 155 * In this case, set <b>bufferQueue_</b> in the {@link StreamInfo} parameter of {@link CreateStreams} 156 * 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; 163 * returns an error code defined in {@link CamRetCode} otherwise. 164 * 165 * @since 1.0 166 * @version 1.0 167 */ 168 virtual CamRetCode AttachBufferQueue(int streamId, const OHOS::sptr<OHOS::IBufferProducer> &producer) = 0; 169 170 /** 171 * @brief Detaches the producer handle from a stream. 172 * 173 * @param streamId Indicates the ID of the stream from which the procedure handle is to be detached. 174 * 175 * @return Returns <b>NO_ERROR</b> if the operation is successful; 176 * returns an error code defined in {@link CamRetCode} otherwise. 177 * 178 * @since 1.0 179 * @version 1.0 180 */ 181 virtual CamRetCode DetachBufferQueue(int streamId) = 0; 182 183 /** 184 * @brief Captures an image. 185 * 186 * This function must be called after {@link CommitStreams}. 187 * There are two image capture modes: continuous capture and single capture. 188 * A continuous capture is performed inside the module after being triggered, 189 * and the consumer can continuously receive captured image data after calling this function only once. 190 * If this function is called again, the current capture is stopped, the capture request configuration is updated, 191 * and a new capture is performed. 192 * This mode is mainly used in preview, video recording, or continuous shooting scenarios. 193 * After a single capture is triggered, only one frame of image data is captured. 194 * This mode applies to the single shooting scenario. 195 * When the capture is started, {@link OnCaptureStarted} is called to notify of the start. 196 * To stop a continuous capture, call {@link CancelCapture}. 197 * When the capture ends, {@link OnCaptureEnded} is called to notify the caller of the information 198 * such as the number of captured frames. 199 * <b>enableShutterCallback_</b> in {@link CaptureInfo} is used to enable the callback for each capture. 200 * After the callback is enabled, {@link OnFrameShutter} is called upon each capture. 201 * In the scenario where multiple streams are captured at the same time, this module ensures that 202 * the captured data of multiple streams is reported simultaneously. 203 * 204 * @param captureId Indicates the ID of the capture request. You must ensure that the ID of the 205 * capture request is unique when the camera is started. 206 * @param info Indicates the capture request configuration information. For details, see {@link CaptureInfo}. 207 * @param isStreaming Specifies whether to continuously capture images. 208 * The value <b>true</b> means to continuously capture images, and <b>false</b> means the opposite. 209 * 210 * @return Returns <b>NO_ERROR</b> if the operation is successful; 211 * returns an error code defined in {@link CamRetCode} otherwise. 212 * 213 * @since 1.0 214 * @version 1.0 215 */ 216 virtual CamRetCode Capture(int captureId, 217 const std::shared_ptr<CaptureInfo> &info, bool isStreaming) = 0; 218 219 /** 220 * @brief Cancels a capture. 221 * 222 * {@link OnCaptureEnded} is called when a continuous capture is canceled. 223 * 224 * @param captureId Indicates the ID of the capture request to cancel. 225 * 226 * @return Returns <b>NO_ERROR</b> if the operation is successful; 227 * returns an error code defined in {@link CamRetCode} otherwise. 228 * 229 * @since 1.0 230 * @version 1.0 231 */ 232 virtual CamRetCode CancelCapture(int captureId) = 0; 233 234 /** 235 * @brief Converts a specific stream to an offline stream. 236 * 237 * Only photographing streams can be converted into offline streams. 238 * Due to the limited processing capability, some devices may spend a long period of time on 239 * algorithm processing during photographing, causing the capture requests to stack in the module. 240 * Converting to an offline stream enables the bottom-layer device to close and 241 * the offline stream to take over for subsequent processing. 242 * 243 * @param streamIds Indicates the IDs of the streams to be converted. 244 * @param callback Indicates the callback for conversion to offline streams. 245 * @param offlineOperator Indicates the offline stream after conversion. 246 * 247 * @return Returns <b>NO_ERROR</b> if the operation is successful; 248 * returns an error code defined in {@link CamRetCode} otherwise. 249 * 250 * @since 1.0 251 * @version 1.0 252 */ 253 virtual CamRetCode ChangeToOfflineStream(const std::vector<int> &streamIds, 254 OHOS::sptr<IStreamOperatorCallback> &callback, 255 OHOS::sptr<IOfflineStreamOperator> &offlineOperator) = 0; 256 }; 257 } 258 #endif // HDI_STREAM_OPERATOR_CLIENT_INF_H