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 Query whether the stream corresponding to the parameter can be added.
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     * which can be ignored currently.
109     *
110     * @return Returns <b>NO_ERROR</b> if the operation is successful;
111     * returns an error code defined in {@link CamRetCode} otherwise.
112     *
113     * @since 3.2
114     * @version 1.0
115     */
116    CommitStreams([in] enum OperationMode mode, [in] unsigned char[] modeSetting);
117
118    /**
119     * @brief Obtains stream attributes.The stream properties obtained through this API
120     * may be different from the stream information entered by {@link CreateStreams}.
121     *
122     * @param attributes Indicates the obtained stream attributes.
123     * Stream information passed by the <b>streamInfos</b> parameter in {@link CreateStreams}
124     * may be overridden. Therefore, the stream attributes obtained by using this function may be
125     * different from the stream information passed in {@link CreateStreams}.
126     *
127     * @return Returns <b>NO_ERROR</b> if the operation is successful;
128     * returns an error code defined in {@link CamRetCode} otherwise.
129     *
130     * @since 3.2
131     * @version 1.0
132     */
133    GetStreamAttributes([out] struct StreamAttribute[] attributes);
134
135    /**
136     * @brief Attaches a producer handle to a stream.
137     *
138     * If a producer handle has been specified during stream creation (by {@link CreateStreams}),
139     * you do not need to call this function. If you want to attach a new producer handle,
140     * call {@link DetachBufferQueue} to detach the existing producer handle and then
141     * call this function to attach the new one.
142     * You do not need to attach a producer handle for IoT devices that do not support or require
143     * image data caching and transferring of preview streams.
144     * In this case, set <b>bufferQueue_</b> in the {@link StreamInfo} parameter of {@link CreateStreams}
145     * to <b>null</b>,
146     * and set <b>tunneledMode_</b> to <b>false</b>.
147     *
148     * @param streamId Indicates the ID of the stream to which the producer handle is to be attached.
149     * @param producer Indicates the producer handle to be attached.
150     *
151     * @return Returns <b>NO_ERROR</b> if the operation is successful;
152     * returns an error code defined in {@link CamRetCode} otherwise.
153     *
154     * @since 3.2
155     * @version 1.0
156     */
157    AttachBufferQueue([in] int streamId, [in] BufferProducerSequenceable bufferProducer);
158
159    /**
160     * @brief Detaches the producer handle from a stream.
161     *
162     * @param streamId Indicates the ID of the stream from which the producer handle is to be detached.
163     *
164     * @return Returns <b>NO_ERROR</b> if the operation is successful;
165     * returns an error code defined in {@link CamRetCode} otherwise.
166     *
167     * @since 3.2
168     * @version 1.0
169     */
170    DetachBufferQueue([in] int streamId);
171
172    /**
173     * @brief Captures an image.
174     *
175     * This function must be called after {@link CommitStreams}.
176     * There are two image capture modes: continuous capture and single capture.
177     * A continuous capture is performed inside the module after being triggered,
178     * and the consumer can continuously receive captured image data after calling this function only once.
179     * If this function is called again, the current capture is stopped, the capture request configuration is updated,
180     * and a new capture is performed.
181     * This mode is mainly used in preview, video recording, or continuous shooting scenarios.
182     * After a single capture is triggered, only one frame of image data is captured.
183     * This mode applies to the single shooting scenario.
184     * When the capture is started, {@link OnCaptureStarted} is called to notify of the start.
185     * To stop a continuous capture, call {@link CancelCapture}.
186     * When the capture ends, {@link OnCaptureEnded} is called to notify the caller of the information
187     * such as the number of captured frames.
188     * <b>enableShutterCallback_</b> in {@link CaptureInfo} is used to enable the callback for each capture.
189     * After the callback is enabled, {@link OnFrameShutter} is called upon each capture.
190     * In the scenario where multiple streams are captured at the same time, this module ensures that
191     * the captured data of multiple streams is reported simultaneously.
192     *
193     * @param captureId Indicates the ID of the capture request. You must ensure that the ID of the
194     * capture request is unique when the camera is started.
195     * @param info Indicates the capture request configuration information. For details, see {@link CaptureInfo}.
196     * @param isStreaming Specifies whether to continuously capture images.
197     * 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;
200     * returns an error code defined in {@link CamRetCode} otherwise.
201     *
202     * @since 3.2
203     * @version 1.0
204     */
205    Capture([in] int captureId, [in] struct CaptureInfo info, [in] boolean isStreaming);
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 be canceled.
213     *
214     * @return Returns <b>NO_ERROR</b> if the operation is successful;
215     * returns an error code defined in {@link CamRetCode} otherwise.
216     *
217     * @since 3.2
218     * @version 1.0
219     */
220    CancelCapture([in] int captureId);
221
222    /**
223     * @brief Converts a specific stream to an offline stream.
224     *
225     * Only photographing streams can be converted into offline streams,other streams are not supported.
226     * Due to the limited processing capability, some devices may spend a long period of time on
227     * algorithm processing during photographing, causing the capture requests to stack in the module.
228     * Converting to an offline stream enables the bottom-layer device to close and
229     * the offline stream to take over for subsequent processing.
230     *
231     * @param streamIds Indicates the IDs of the streams to be converted.
232     * @param callback Indicates the callback for conversion to offline streams.
233     * @param offlineOperator Indicates the offline stream after conversion.
234     *
235     * @return Returns <b>NO_ERROR</b> if the operation is successful;
236     * returns an error code defined in {@link CamRetCode} otherwise.
237     *
238     * @since 3.2
239     * @version 1.0
240     */
241    ChangeToOfflineStream([in] int[] streamIds, [in] IStreamOperatorCallback callbackObj,
242        [out] IOfflineStreamOperator offlineOperator);
243}
244