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