1# IStreamOperator
2
3
4## 概述
5
6定义Camera设备流操作。
7
8对Camera设备执行流的创建、配置与添加参数、属性获取、句柄绑定与解除、图像捕获与取消、流的转换以及流释放操作。
9
10流是指从底层设备输出，经本模块内部各环节处理，最终传递到上层服务或者应用的一组数据序列。 本模块支持的流的类型有预览流，录像流，拍照流等，更多类型可查看[StreamIntent](_camera_v10.md#streamintent)。
11
12**起始版本：** 3.2
13
14**相关模块：**[Camera](_camera_v10.md)
15
16
17## 汇总
18
19
20### Public 成员函数
21
22| 名称 | 描述 |
23| -------- | -------- |
24| [IsStreamsSupported](#isstreamssupported) ([in] enum [OperationMode](_camera_v10.md#operationmode) mode, [in] unsigned char[] modeSetting, [in] struct [StreamInfo](_stream_info_v10.md)[] infos, [out] enum [StreamSupportType](_camera_v10.md#streamsupporttype) type) | 查询是否支持添加参数对应的流。 |
25| [CreateStreams](#createstreams) ([in] struct [StreamInfo](_stream_info_v10.md)[] streamInfos) | 创建流。 |
26| [ReleaseStreams](#releasestreams) ([in] int[] streamIds) | 释放流。 |
27| [CommitStreams](#commitstreams) ([in] enum [OperationMode](_camera_v10.md#operationmode) mode, [in] unsigned char[] modeSetting) | 配置流。 |
28| [GetStreamAttributes](#getstreamattributes) ([out] struct [StreamAttribute](_stream_attribute_v10.md)[] attributes) | 获取流的属性。 |
29| [AttachBufferQueue](#attachbufferqueue) ([in] int streamId, [in] BufferProducerSequenceable bufferProducer) | 绑定生产者句柄和指定流。 |
30| [DetachBufferQueue](#detachbufferqueue) ([in] int streamId) | 解除生产者句柄和指定流的绑定关系。 |
31| [Capture](#capture) ([in] int captureId, [in] struct [CaptureInfo](_capture_info_v10.md) info, [in] boolean isStreaming) | 捕获图像。 |
32| [CancelCapture](#cancelcapture) ([in] int captureId) | 取消连续捕获。 |
33| [ChangeToOfflineStream](#changetoofflinestream) ([in] int[] streamIds, [in] [IStreamOperatorCallback](interface_i_stream_operator_callback_v10.md) callbackObj, [out] [IOfflineStreamOperator](interface_i_offline_stream_operator_v10.md) offlineOperator) | 将指定流转换成离线流。 |
34
35
36## 成员函数说明
37
38
39### AttachBufferQueue()
40
41```
42IStreamOperator::AttachBufferQueue ([in] int streamId, [in] BufferProducerSequenceable bufferProducer )
43```
44
45**描述**
46
47绑定生产者句柄和指定流。
48
49如果在[CreateStreams](#createstreams)创建流时已经指定了生产者句柄，则不需要调用该接口。如果需要重新绑定， 需先调用[DetachBufferQueue](#detachbufferqueue)进行解绑，然后再绑定。
50
51对于一些IOT设备，可能不需要或者不支持预览流的图像数据缓存流转，那么不需要绑定生产者句柄， 此时在创建流时[CreateStreams](#createstreams)的[StreamInfo](_stream_info_v10.md)参数的生产者句柄bufferQueue_为空，而 tunneledMode_需设置为false。
52
53**起始版本：** 3.2
54
55**参数:**
56
57| 名称 | 描述 |
58| -------- | -------- |
59| streamId | 用于标识要绑定的流。 |
60| bufferProducer | 生产者句柄。 |
61
62**返回：**
63
64NO_ERROR 表示执行成功。
65
66其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
67
68**参见：**
69
70[DetachBufferQueue](#detachbufferqueue)
71
72
73### CancelCapture()
74
75```
76IStreamOperator::CancelCapture ([in] int captureId)
77```
78
79**描述**
80
81取消连续捕获。
82
83捕获结束时，会调用[OnCaptureEnded](interface_i_stream_operator_callback_v10.md#oncaptureended)来通知调用者捕获的帧计数等信息。
84
85**起始版本：** 3.2
86
87**参数:**
88
89| 名称 | 描述 |
90| -------- | -------- |
91| captureId | 用于标识要取消的捕获请求。 |
92
93**返回：**
94
95NO_ERROR 表示执行成功。
96
97其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
98
99**参见：**
100
101[Capture](#capture)
102
103
104### Capture()
105
106```
107IStreamOperator::Capture ([in] int captureId, [in] struct CaptureInfo info, [in] boolean isStreaming )
108```
109
110**描述**
111
112捕获图像。
113
114本接口必须在调用[CommitStreams](#commitstreams)配置流之后调用。 图像捕获有两种模式，分别是连续捕获和单次捕获。
115
116- 连续捕获即触发之后模块内部进行连续的捕获，消费者只需调用此函数一次即可连续接收捕获的图像数据。若再次调用了本接口， 则停止当前捕获，更新捕获信息，再进行一次新的捕获，多用于预览、录像或者连拍场景。
117
118- 单次捕获即触发之后只捕获一帧图像数据，用于单次拍照场景。捕获启动时，会调用[OnCaptureStarted](interface_i_stream_operator_callback_v10.md#oncapturestarted)来通知调用者捕获已经启动。
119
120- 连续捕获需调用[CancelCapture](#cancelcapture)来停止捕获。捕获结束时，会调用[OnCaptureEnded](interface_i_stream_operator_callback_v10.md#oncaptureended)来通知调用者捕获的帧计数等信息。
121
122[CaptureInfo](_capture_info_v10.md)的enableShutterCallback_使能[OnFrameShutter](interface_i_stream_operator_callback_v10.md#onframeshutter)，使能后每次捕获触发[OnFrameShutter](interface_i_stream_operator_callback_v10.md#onframeshutter)。
123
124对于多个流同时捕获的场景，本模块内部保证同时上报多路流捕获数据。
125
126**起始版本：** 3.2
127
128**参数:**
129
130| 名称 | 描述 |
131| -------- | -------- |
132| captureId | 捕获请求的唯一标识，由调用者指定，调用者需保证在Camera设备打开期间，捕获请求ID是唯一的。 |
133| info | 捕获请求的参数信息，具体信息查看[CaptureInfo](_capture_info_v10.md)。 |
134| isStreaming | 是否连续捕获，true表示连续捕获，否则为单次捕获。 |
135
136**返回：**
137
138NO_ERROR 表示执行成功。
139
140其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
141
142**参见：**
143
144OnFrameShutter
145
146
147### ChangeToOfflineStream()
148
149```
150IStreamOperator::ChangeToOfflineStream ([in] int[] streamIds, [in] IStreamOperatorCallback callbackObj, [out] IOfflineStreamOperator offlineOperator )
151```
152
153**描述**
154
155将指定流转换成离线流。
156
157离线流只能由拍照流转换而来，其他流不支持。 一些设备处理能力有限，可能导致拍照时算法处理时间较长，从而引起捕获请求堆积在模块内部，而转换为离线 流之后，可关闭底层设备，由离线流接替，进行后续的处理。
158
159**起始版本：** 3.2
160
161**参数:**
162
163| 名称 | 描述 |
164| -------- | -------- |
165| streamIds | 用于指定要转换成离线流的流集合。 |
166| callbackObj | 用于设置离线流的回调。 |
167| offlineOperator | 转换后的离线流。 |
168
169**返回：**
170
171NO_ERROR 表示执行成功。
172
173其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
174
175
176### CommitStreams()
177
178```
179IStreamOperator::CommitStreams ([in] enum OperationMode mode, [in] unsigned char[] modeSetting )
180```
181
182**描述**
183
184配置流。
185
186本接口需在调用[CreateStreams](#createstreams)创建流之后调用。
187
188**起始版本：** 3.2
189
190**参数:**
191
192| 名称 | 描述 |
193| -------- | -------- |
194| mode | 流运行的模式，支持的模式定义在[OperationMode](_camera_v10.md#operationmode)。 |
195| modeSetting | 流的配置参数，包括帧率，ZOOM等信息。ZOOM：变焦，目前可以忽略 |
196
197**返回：**
198
199NO_ERROR 表示执行成功。
200
201其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
202
203
204### CreateStreams()
205
206```
207IStreamOperator::CreateStreams ([in] struct StreamInfo[] streamInfos)
208```
209
210**描述**
211
212创建流。
213
214此函数接口依据输入的流信息创建流，调用该接口之前需先通过[IsStreamsSupported](#isstreamssupported)查询HAL是否支持要创建的流。
215
216**起始版本：** 3.2
217
218**参数:**
219
220| 名称 | 描述 |
221| -------- | -------- |
222| streamInfos | 流信息列表，流信息定义在[StreamInfo](_stream_info_v10.md)。输入的流信息可能会被修改，需通过 [GetStreamAttributes](#getstreamattributes)获取最新的流属性。 |
223
224**返回：**
225
226NO_ERROR 表示执行成功。
227
228其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
229
230
231### DetachBufferQueue()
232
233```
234IStreamOperator::DetachBufferQueue ([in] int streamId)
235```
236
237**描述**
238
239解除生产者句柄和指定流的绑定关系。
240
241**起始版本：** 3.2
242
243**参数:**
244
245| 名称 | 描述 |
246| -------- | -------- |
247| streamId | 用于标识要解除绑定的流。 |
248
249**返回：**
250
251NO_ERROR 表示执行成功。
252
253其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
254
255**参见：**
256
257[AttachBufferQueue](#attachbufferqueue)
258
259
260### GetStreamAttributes()
261
262```
263IStreamOperator::GetStreamAttributes ([out] struct StreamAttribute[] attributes)
264```
265
266**描述**
267
268获取流的属性。
269
270通过该接口获取的流属性可能会和[CreateStreams](#createstreams)输入的流信息存在差异。
271
272**起始版本：** 3.2
273
274**参数:**
275
276| 名称 | 描述 |
277| -------- | -------- |
278| attributes | 用于获取流的属性。在调用[CreateStreams](#createstreams)时，通过参数streamInfos携带的流信息可能会被重写。 |
279
280**返回：**
281
282NO_ERROR 表示执行成功。
283
284其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
285
286
287### IsStreamsSupported()
288
289```
290IStreamOperator::IsStreamsSupported ([in] enum OperationMode mode, [in] unsigned char[] modeSetting, [in] struct StreamInfo[] infos, [out] enum StreamSupportType type )
291```
292
293**描述**
294
295查询是否支持添加参数对应的流。
296
297此函数接口根据输入的运行模式和配置信息以及当前模块中正在运行的流，查询是否支持动态添加流。
298
299- 如果本模块支持在不停止其他流的情况下添加新流，或者即使停止其他流但上层服务或应用不感知， 则通过type参数返回DYNAMIC_SUPPORTED，上层服务或应用可以直接添加新流；
300
301- 如果本模块支持添加新流但需要上层服务或应用先停止所有流的捕获，则通过type参数返回RE_CONFIGURED_REQUIRED;
302
303- 如果不支持添加输入的新流，则返回NOT_SUPPORTED。 此函数需要在调用[CreateStreams](#createstreams)创建流之前调用。
304
305**起始版本：** 3.2
306
307**参数:**
308
309| 名称 | 描述 |
310| -------- | -------- |
311| mode | 流的使用模式，支持的模式参考[OperationMode](_camera_v10.md#operationmode)。 |
312| modeSetting | 流的配置，包括帧率，3A等配置信息。3A：自动曝光 (AE)、自动聚焦 (AF)、自动白平衡 (AWB) |
313| infos | 流的配置信息，具体参考[StreamInfo](_stream_info_v10.md)。 |
314| type | 对动态配置流的支持类型，支持类型定义在[StreamSupportType](_camera_v10.md#streamsupporttype)。 |
315
316**返回：**
317
318NO_ERROR 表示执行成功。
319
320其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
321
322
323### ReleaseStreams()
324
325```
326IStreamOperator::ReleaseStreams ([in] int[] streamIds)
327```
328
329**描述**
330
331释放流。
332
333**起始版本：** 3.2
334
335**参数:**
336
337| 名称 | 描述 |
338| -------- | -------- |
339| streamIds | 要释放的流ID列表。 |
340
341**返回：**
342
343NO_ERROR 表示执行成功。
344
345其他值表示执行失败，具体错误码查看[CamRetCode](_camera_v10.md#camretcode)。
346